1 | /**
|
2 | * @packageDocumentation
|
3 | * @module rendermime-interfaces
|
4 | */
|
5 | import { ITranslator } from '@jupyterlab/translation';
|
6 | import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
|
7 | import { Widget } from '@lumino/widgets';
|
8 | /**
|
9 | * A namespace for rendermime associated interfaces.
|
10 | */
|
11 | export declare namespace IRenderMime {
|
12 | /**
|
13 | * A model for mime data.
|
14 | */
|
15 | interface IMimeModel {
|
16 | /**
|
17 | * Whether the data in the model is trusted.
|
18 | */
|
19 | readonly trusted: boolean;
|
20 | /**
|
21 | * The data associated with the model.
|
22 | */
|
23 | readonly data: ReadonlyPartialJSONObject;
|
24 | /**
|
25 | * The metadata associated with the model.
|
26 | *
|
27 | * Among others, it can include an attribute named `fragment`
|
28 | * that stores a URI fragment identifier for the MIME resource.
|
29 | */
|
30 | readonly metadata: ReadonlyPartialJSONObject;
|
31 | /**
|
32 | * Set the data associated with the model.
|
33 | *
|
34 | * #### Notes
|
35 | * Calling this function may trigger an asynchronous operation
|
36 | * that could cause the renderer to be rendered with a new model
|
37 | * containing the new data.
|
38 | */
|
39 | setData(options: IMimeModel.ISetDataOptions): void;
|
40 | }
|
41 | /**
|
42 | * The namespace for IMimeModel associated interfaces.
|
43 | */
|
44 | namespace IMimeModel {
|
45 | /**
|
46 | * The options used to update a mime model.
|
47 | */
|
48 | interface ISetDataOptions {
|
49 | /**
|
50 | * The new data object.
|
51 | */
|
52 | data?: ReadonlyPartialJSONObject;
|
53 | /**
|
54 | * The new metadata object.
|
55 | */
|
56 | metadata?: ReadonlyPartialJSONObject;
|
57 | }
|
58 | }
|
59 | /**
|
60 | * A toolbar item.
|
61 | */
|
62 | interface IToolbarItem {
|
63 | /**
|
64 | * Item name
|
65 | */
|
66 | name: string;
|
67 | /**
|
68 | * Toolbar widget
|
69 | */
|
70 | widget: Widget;
|
71 | }
|
72 | /**
|
73 | * The options used to initialize a document widget factory.
|
74 | *
|
75 | * This interface is intended to be used by mime renderer extensions
|
76 | * to define a document opener that uses its renderer factory.
|
77 | */
|
78 | interface IDocumentWidgetFactoryOptions {
|
79 | /**
|
80 | * The name of the widget to display in dialogs.
|
81 | */
|
82 | readonly name: string;
|
83 | /**
|
84 | * The name of the document model type.
|
85 | */
|
86 | readonly modelName?: string;
|
87 | /**
|
88 | * The primary file type of the widget.
|
89 | */
|
90 | readonly primaryFileType: string;
|
91 | /**
|
92 | * The file types the widget can view.
|
93 | */
|
94 | readonly fileTypes: ReadonlyArray<string>;
|
95 | /**
|
96 | * The file types for which the factory should be the default.
|
97 | */
|
98 | readonly defaultFor?: ReadonlyArray<string>;
|
99 | /**
|
100 | * The file types for which the factory should be the default for rendering,
|
101 | * if that is different than the default factory (which may be for editing)
|
102 | * If undefined, then it will fall back on the default file type.
|
103 | */
|
104 | readonly defaultRendered?: ReadonlyArray<string>;
|
105 | /**
|
106 | * A function returning a list of toolbar items to add to the toolbar.
|
107 | */
|
108 | readonly toolbarFactory?: (widget?: IRenderer) => IToolbarItem[];
|
109 | }
|
110 | namespace LabIcon {
|
111 | /**
|
112 | * The simplest possible interface for defining a generic icon.
|
113 | */
|
114 | interface IIcon {
|
115 | /**
|
116 | * The name of the icon. By convention, the icon name will be namespaced
|
117 | * as so:
|
118 | *
|
119 | * "pkg-name:icon-name"
|
120 | */
|
121 | readonly name: string;
|
122 | /**
|
123 | * A string containing the raw contents of an svg file.
|
124 | */
|
125 | svgstr: string;
|
126 | }
|
127 | /**
|
128 | * Interface for generic renderer.
|
129 | */
|
130 | interface IRenderer {
|
131 | readonly render: (container: HTMLElement, options?: any) => void;
|
132 | readonly unrender: (container: HTMLElement) => void;
|
133 | }
|
134 | /**
|
135 | * A type that can be resolved to a LabIcon instance.
|
136 | */
|
137 | type IResolvable = string | (IIcon & Partial<IRenderer>);
|
138 | }
|
139 | /**
|
140 | * A file type to associate with the renderer.
|
141 | */
|
142 | interface IFileType {
|
143 | /**
|
144 | * The name of the file type.
|
145 | */
|
146 | readonly name: string;
|
147 | /**
|
148 | * The mime types associated the file type.
|
149 | */
|
150 | readonly mimeTypes: ReadonlyArray<string>;
|
151 | /**
|
152 | * The extensions of the file type (e.g. `".txt"`). Can be a compound
|
153 | * extension (e.g. `".table.json`).
|
154 | */
|
155 | readonly extensions: ReadonlyArray<string>;
|
156 | /**
|
157 | * An optional display name for the file type.
|
158 | */
|
159 | readonly displayName?: string;
|
160 | /**
|
161 | * An optional pattern for a file name (e.g. `^Dockerfile$`).
|
162 | */
|
163 | readonly pattern?: string;
|
164 | /**
|
165 | * The icon for the file type. Can either be a string containing the name
|
166 | * of an existing icon, or an object with {name, svgstr} fields, where
|
167 | * svgstr is a string containing the raw contents of an svg file.
|
168 | */
|
169 | readonly icon?: LabIcon.IResolvable;
|
170 | /**
|
171 | * The icon class name for the file type.
|
172 | */
|
173 | readonly iconClass?: string;
|
174 | /**
|
175 | * The icon label for the file type.
|
176 | */
|
177 | readonly iconLabel?: string;
|
178 | /**
|
179 | * The file format for the file type ('text', 'base64', or 'json').
|
180 | */
|
181 | readonly fileFormat?: string;
|
182 | }
|
183 | /**
|
184 | * An interface for using a RenderMime.IRenderer for output and read-only documents.
|
185 | */
|
186 | interface IExtension {
|
187 | /**
|
188 | * The ID of the extension.
|
189 | *
|
190 | * #### Notes
|
191 | * The convention for extension IDs in JupyterLab is the full NPM package
|
192 | * name followed by a colon and a unique string token, e.g.
|
193 | * `'@jupyterlab/apputils-extension:settings'` or `'foo-extension:bar'`.
|
194 | */
|
195 | readonly id: string;
|
196 | /**
|
197 | * A renderer factory to be registered to render the MIME type.
|
198 | */
|
199 | readonly rendererFactory: IRendererFactory;
|
200 | /**
|
201 | * The rank passed to `RenderMime.addFactory`. If not given,
|
202 | * defaults to the `defaultRank` of the factory.
|
203 | */
|
204 | readonly rank?: number;
|
205 | /**
|
206 | * The timeout after user activity to re-render the data.
|
207 | */
|
208 | readonly renderTimeout?: number;
|
209 | /**
|
210 | * Preferred data type from the model. Defaults to `string`.
|
211 | */
|
212 | readonly dataType?: 'string' | 'json';
|
213 | /**
|
214 | * The options used to open a document with the renderer factory.
|
215 | */
|
216 | readonly documentWidgetFactoryOptions?: IDocumentWidgetFactoryOptions | ReadonlyArray<IDocumentWidgetFactoryOptions>;
|
217 | /**
|
218 | * The optional file type associated with the extension.
|
219 | */
|
220 | readonly fileTypes?: ReadonlyArray<IFileType>;
|
221 | }
|
222 | /**
|
223 | * The interface for a module that exports an extension or extensions as
|
224 | * the default value.
|
225 | */
|
226 | interface IExtensionModule {
|
227 | /**
|
228 | * The default export.
|
229 | */
|
230 | readonly default: IExtension | ReadonlyArray<IExtension>;
|
231 | }
|
232 | /**
|
233 | * A widget which displays the contents of a mime model.
|
234 | */
|
235 | interface IRenderer extends Widget {
|
236 | /**
|
237 | * The application language translator.
|
238 | */
|
239 | translator?: ITranslator;
|
240 | /**
|
241 | * Render a mime model.
|
242 | *
|
243 | * @param model - The mime model to render.
|
244 | *
|
245 | * @returns A promise which resolves when rendering is complete.
|
246 | *
|
247 | * #### Notes
|
248 | * This method may be called multiple times during the lifetime
|
249 | * of the widget to update it if and when new data is available.
|
250 | */
|
251 | renderModel(model: IMimeModel): Promise<void>;
|
252 | }
|
253 | /**
|
254 | * The interface for a renderer factory.
|
255 | */
|
256 | interface IRendererFactory {
|
257 | /**
|
258 | * Whether the factory is a "safe" factory.
|
259 | *
|
260 | * #### Notes
|
261 | * A "safe" factory produces renderer widgets which can render
|
262 | * untrusted model data in a usable way. *All* renderers must
|
263 | * handle untrusted data safely, but some may simply failover
|
264 | * with a "Run cell to view output" message. A "safe" renderer
|
265 | * is an indication that its sanitized output will be useful.
|
266 | */
|
267 | readonly safe: boolean;
|
268 | /**
|
269 | * The mime types handled by this factory.
|
270 | */
|
271 | readonly mimeTypes: ReadonlyArray<string>;
|
272 | /**
|
273 | * The default rank of the factory. If not given, defaults to 100.
|
274 | */
|
275 | readonly defaultRank?: number;
|
276 | /**
|
277 | * Create a renderer which displays the mime data.
|
278 | *
|
279 | * @param options - The options used to render the data.
|
280 | */
|
281 | createRenderer(options: IRendererOptions): IRenderer;
|
282 | }
|
283 | /**
|
284 | * The options used to create a renderer.
|
285 | */
|
286 | interface IRendererOptions {
|
287 | /**
|
288 | * The preferred mimeType to render.
|
289 | */
|
290 | mimeType: string;
|
291 | /**
|
292 | * The html sanitizer.
|
293 | */
|
294 | sanitizer: ISanitizer;
|
295 | /**
|
296 | * An optional url resolver.
|
297 | */
|
298 | resolver: IResolver | null;
|
299 | /**
|
300 | * An optional link handler.
|
301 | */
|
302 | linkHandler: ILinkHandler | null;
|
303 | /**
|
304 | * The LaTeX typesetter.
|
305 | */
|
306 | latexTypesetter: ILatexTypesetter | null;
|
307 | /**
|
308 | * The application language translator.
|
309 | */
|
310 | translator?: ITranslator;
|
311 | }
|
312 | /**
|
313 | * An object that handles html sanitization.
|
314 | */
|
315 | interface ISanitizer {
|
316 | /**
|
317 | * Sanitize an HTML string.
|
318 | */
|
319 | sanitize(dirty: string): string;
|
320 | }
|
321 | /**
|
322 | * An object that handles links on a node.
|
323 | */
|
324 | interface ILinkHandler {
|
325 | /**
|
326 | * Add the link handler to the node.
|
327 | *
|
328 | * @param node: the anchor node for which to handle the link.
|
329 | *
|
330 | * @param path: the path to open when the link is clicked.
|
331 | *
|
332 | * @param id: an optional element id to scroll to when the path is opened.
|
333 | */
|
334 | handleLink(node: HTMLElement, path: string, id?: string): void;
|
335 | }
|
336 | /**
|
337 | * An object that resolves relative URLs.
|
338 | */
|
339 | interface IResolver {
|
340 | /**
|
341 | * Resolve a relative url to an absolute url path.
|
342 | */
|
343 | resolveUrl(url: string): Promise<string>;
|
344 | /**
|
345 | * Get the download url for a given absolute url path.
|
346 | *
|
347 | * #### Notes
|
348 | * This URL may include a query parameter.
|
349 | */
|
350 | getDownloadUrl(url: string): Promise<string>;
|
351 | /**
|
352 | * Whether the URL should be handled by the resolver
|
353 | * or not.
|
354 | *
|
355 | * #### Notes
|
356 | * This is similar to the `isLocal` check in `URLExt`,
|
357 | * but can also perform additional checks on whether the
|
358 | * resolver should handle a given URL.
|
359 | */
|
360 | isLocal?: (url: string) => boolean;
|
361 | }
|
362 | /**
|
363 | * The interface for a LaTeX typesetter.
|
364 | */
|
365 | interface ILatexTypesetter {
|
366 | /**
|
367 | * Typeset a DOM element.
|
368 | *
|
369 | * @param element - the DOM element to typeset. The typesetting may
|
370 | * happen synchronously or asynchronously.
|
371 | *
|
372 | * #### Notes
|
373 | * The application-wide rendermime object has a settable
|
374 | * `latexTypesetter` property which is used wherever LaTeX
|
375 | * typesetting is required. Extensions wishing to provide their
|
376 | * own typesetter may replace that on the global `lab.rendermime`.
|
377 | */
|
378 | typeset(element: HTMLElement): void;
|
379 | }
|
380 | }
|