@jupyterlab/rendermime
Version:
JupyterLab - RenderMime
207 lines (179 loc) • 5.91 kB
text/typescript
/* -----------------------------------------------------------------------------
| Copyright (c) Jupyter Development Team.
| Distributed under the terms of the Modified BSD License.
|----------------------------------------------------------------------------*/
import { IRenderMime } from '@jupyterlab/rendermime-interfaces';
import { ITranslator } from '@jupyterlab/translation';
import { ReadonlyPartialJSONObject, Token } from '@lumino/coreutils';
import { MimeModel } from './mimemodel';
/**
* The rendermime token.
*/
export const IRenderMimeRegistry = new Token<IRenderMimeRegistry>(
'@jupyterlab/rendermime:IRenderMimeRegistry',
'A service for the rendermime registry for the application. Use this to create renderers for various mime-types in your extension. Many times it will be easier to create a "mime renderer extension" rather than using this service directly.'
);
export interface IRenderMimeRegistry {
/**
* The sanitizer used by the rendermime instance.
*/
readonly sanitizer: IRenderMime.ISanitizer;
/**
* The object used to resolve relative urls for the rendermime instance.
*/
readonly resolver: IRenderMime.IResolver | null;
/**
* The object used to handle path opening links.
*/
readonly linkHandler: IRenderMime.ILinkHandler | null;
/**
* The LaTeX typesetter for the rendermime.
*/
readonly latexTypesetter: IRenderMime.ILatexTypesetter | null;
/**
* The Markdown parser for the rendermime.
*/
readonly markdownParser: IRenderMime.IMarkdownParser | null;
/**
* The ordered list of mimeTypes.
*/
readonly mimeTypes: ReadonlyArray<string>;
/**
* Find the preferred mime type for a mime bundle.
*
* @param bundle - The bundle of mime data.
*
* @param safe - How to consider safe/unsafe factories. If 'ensure',
* it will only consider safe factories. If 'any', any factory will be
* considered. If 'prefer', unsafe factories will be considered, but
* only after the safe options have been exhausted.
*
* @returns The preferred mime type from the available factories,
* or `undefined` if the mime type cannot be rendered.
*/
preferredMimeType(
bundle: ReadonlyPartialJSONObject,
safe?: 'ensure' | 'prefer' | 'any'
): string | undefined;
/**
* Create a renderer for a mime type.
*
* @param mimeType - The mime type of interest.
*
* @returns A new renderer for the given mime type.
*
* @throws An error if no factory exists for the mime type.
*/
createRenderer(mimeType: string): IRenderMime.IRenderer;
/**
* Create a new mime model. This is a convenience method.
*
* @options - The options used to create the model.
*
* @returns A new mime model.
*/
createModel(options?: MimeModel.IOptions): MimeModel;
/**
* Create a clone of this rendermime instance.
*
* @param options - The options for configuring the clone.
*
* @returns A new independent clone of the rendermime.
*/
clone(options?: IRenderMimeRegistry.ICloneOptions): IRenderMimeRegistry;
/**
* Get the renderer factory registered for a mime type.
*
* @param mimeType - The mime type of interest.
*
* @returns The factory for the mime type, or `undefined`.
*/
getFactory(mimeType: string): IRenderMime.IRendererFactory | undefined;
/**
* Add a renderer factory to the rendermime.
*
* @param factory - The renderer factory of interest.
*
* @param rank - The rank of the renderer. A lower rank indicates
* a higher priority for rendering. If not given, the rank will
* defer to the `defaultRank` of the factory. If no `defaultRank`
* is given, it will default to 100.
*
* #### Notes
* The renderer will replace an existing renderer for the given
* mimeType.
*/
addFactory(factory: IRenderMime.IRendererFactory, rank?: number): void;
/**
* Remove a mime type.
*
* @param mimeType - The mime type of interest.
*/
removeMimeType(mimeType: string): void;
/**
* Get the rank for a given mime type.
*
* @param mimeType - The mime type of interest.
*
* @returns The rank of the mime type or undefined.
*/
getRank(mimeType: string): number | undefined;
/**
* Set the rank of a given mime type.
*
* @param mimeType - The mime type of interest.
*
* @param rank - The new rank to assign.
*
* #### Notes
* This is a no-op if the mime type is not registered.
*/
setRank(mimeType: string, rank: number): void;
}
export namespace IRenderMimeRegistry {
/**
* The options used to clone a rendermime instance.
*/
export interface ICloneOptions {
/**
* The new sanitizer used to sanitize untrusted html inputs.
*/
sanitizer?: IRenderMime.ISanitizer;
/**
* The new resolver object.
*/
resolver?: IRenderMime.IResolver;
/**
* The new path handler.
*/
linkHandler?: IRenderMime.ILinkHandler;
/**
* The new LaTeX typesetter.
*/
latexTypesetter?: IRenderMime.ILatexTypesetter;
/**
* The new Markdown parser.
*/
markdownParser?: IRenderMime.IMarkdownParser;
/**
* The application language translator.
*/
translator?: ITranslator;
}
}
/**
* The latex typesetter token.
*/
export const ILatexTypesetter = new Token<IRenderMime.ILatexTypesetter>(
'@jupyterlab/rendermime:ILatexTypesetter',
'A service for the LaTeX typesetter for the application. Use this if you want to typeset math in your extension.'
);
export interface ILatexTypesetter extends IRenderMime.ILatexTypesetter {}
/**
* The markdown parser token.
*/
export const IMarkdownParser = new Token<IRenderMime.IMarkdownParser>(
'@jupyterlab/rendermime:IMarkdownParser',
'A service for rendering markdown syntax as HTML content.'
);
export interface IMarkdownParser extends IRenderMime.IMarkdownParser {}