jupyterlab-emrys/lib/rendermime/index.d.ts

A computational environment for Jupyter. Powered by Emrys

import { Widget } from 'phosphor-widget';
import { ISanitizer } from '../sanitizer';
/**
 * A composite renderer.
 *
 * #### Notes
 * When rendering a mimebundle, a mimetype is selected from the mimetypes by
 * searching through the `this.order` list. The first mimetype found in the bundle
 * determines the renderer that will be used.
 *
 * You can add a renderer by adding it to the `renderers` object and registering
 * the mimetype in the `order` array.
 */
export declare class RenderMime {
    /**
     * Construct a renderer.
     */
    constructor(options: RenderMime.IOptions);
    /**
     * The object used to resolve relative urls for the rendermime instance.
     */
    resolver: RenderMime.IResolver;
    /**
     * Render a mimebundle.
     *
     * @param bundle - the mimebundle to render.
     *
     * @param trusted - whether the bundle is trusted.
     */
    render(bundle: RenderMime.MimeMap<string>, trusted?: boolean): Widget;
    /**
     * Find the preferred mimetype in a mimebundle.
     *
     * @param bundle - the mimebundle giving available mimetype content.
     *
     * @param trusted - whether the bundle is trusted.
     *
     * #### Notes
     * If the bundle is not trusted, the highest preference
     * mimetype that is sanitizable or safe will be chosen.
     */
    preferredMimetype(bundle: RenderMime.MimeMap<string>, trusted?: boolean): string;
    /**
     * Clone the rendermime instance with shallow copies of data.
     */
    clone(): RenderMime;
    /**
     * Add a renderer by mimetype.
     *
     * @param mimetype - The mimetype of the renderer.
     * @param renderer - The renderer instance.
     * @param index - The optional order index.
     *
     * ####Notes
     * Negative indices count from the end, so -1 refers to the penultimate index.
     * Use the index of `.order.length` to add to the end of the render precedence list,
     * which would make the new renderer the last choice.
     */
    addRenderer(mimetype: string, renderer: RenderMime.IRenderer, index?: number): void;
    /**
     * Remove a renderer by mimetype.
     */
    removeRenderer(mimetype: string): void;
    /**
     * Get the ordered list of mimetypes.
     *
     * #### Notes
     * These mimetypes are searched from beginning to end, and the first matching
     * mimetype is used.
     */
    /**
     * Set the ordered list of mimetypes.
     */
    order: string[];
    private _renderers;
    private _order;
    private _sanitizer;
    private _resolver;
}
/**
 * The namespace for RenderMime statics.
 */
export declare namespace RenderMime {
    /**
     * The options used to initialize a rendermime instance.
     */
    interface IOptions {
        /**
         * A map of mimetypes to renderers.
         */
        renderers: MimeMap<IRenderer>;
        /**
         * A list of mimetypes in order of precedence (earliest has precedence).
         */
        order: string[];
        /**
         * The sanitizer used to sanitize html inputs.
         */
        sanitizer: ISanitizer;
        /**
         * The initial resolver object.
         *
         * The default is `null`.
         */
        resolver?: IResolver;
    }
    /**
     * Valid rendered object type.
     */
    type RenderedObject = HTMLElement | Widget;
    /**
     * A map of mimetypes to types.
     */
    type MimeMap<T> = {
        [mimetype: string]: T;
    };
    /**
     * The interface for a renderer.
     */
    interface IRenderer {
        /**
         * The mimetypes this renderer accepts.
         */
        mimetypes: string[];
        /**
         * Whether the input is safe without sanitization.
         */
        isSafe(mimetype: string): boolean;
        /**
         * Whether the input can safely sanitized for a given mimetype.
         */
        sanitizable(mimetype: string): boolean;
        /**
         * Render the transformed mime bundle.
         *
         * @param options - The options used for rendering.
         */
        render(options: IRenderOptions): Widget;
    }
    /**
     * The options used to transform or render mime data.
     */
    interface IRenderOptions {
        /**
         * The mimetype.
         */
        mimetype: string;
        /**
         * The source data.
         */
        source: string;
        /**
         * An optional url resolver.
         */
        resolver?: IResolver;
        /**
         * An optional html santizer.
         *
         * If given, should be used to sanitize raw html.
         */
        sanitizer?: ISanitizer;
    }
    /**
     * An object that resolves relative URLs.
     */
    interface IResolver {
        /**
         * Resolve a url to a correct server path.
         */
        resolveUrl(url: string): string;
    }
}