/
index.ts
693 lines (624 loc) · 18.3 KB
/
index.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
/* -----------------------------------------------------------------------------
| Copyright (c) Jupyter Development Team.
| Distributed under the terms of the Modified BSD License.
|----------------------------------------------------------------------------*/
/**
* @packageDocumentation
* @module rendermime-interfaces
*/
import type { ReadonlyPartialJSONObject } from '@lumino/coreutils';
import type { Widget } from '@lumino/widgets';
/**
* A namespace for rendermime associated interfaces.
*/
export namespace IRenderMime {
/**
* A model for mime data.
*/
export interface IMimeModel {
/**
* Whether the data in the model is trusted.
*/
readonly trusted: boolean;
/**
* The data associated with the model.
*/
readonly data: ReadonlyPartialJSONObject;
/**
* The metadata associated with the model.
*
* Among others, it can include an attribute named `fragment`
* that stores a URI fragment identifier for the MIME resource.
*/
readonly metadata: ReadonlyPartialJSONObject;
/**
* Set the data associated with the model.
*
* #### Notes
* Calling this function may trigger an asynchronous operation
* that could cause the renderer to be rendered with a new model
* containing the new data.
*/
setData(options: IMimeModel.ISetDataOptions): void;
}
/**
* The namespace for IMimeModel associated interfaces.
*/
export namespace IMimeModel {
/**
* The options used to update a mime model.
*/
export interface ISetDataOptions {
/**
* The new data object.
*/
data?: ReadonlyPartialJSONObject;
/**
* The new metadata object.
*/
metadata?: ReadonlyPartialJSONObject;
}
}
/**
* A toolbar item.
*/
export interface IToolbarItem {
/**
* Unique item name
*/
name: string;
/**
* Toolbar widget
*/
widget: Widget;
}
/**
* The options used to initialize a document widget factory.
*
* This interface is intended to be used by mime renderer extensions
* to define a document opener that uses its renderer factory.
*/
export interface IDocumentWidgetFactoryOptions {
/**
* The name of the widget to display in dialogs.
*/
readonly name: string;
/**
* The label of the widget to display in dialogs.
* If not given, name is used instead.
*/
readonly label?: string;
/**
* The name of the document model type.
*/
readonly modelName?: string;
/**
* The primary file type of the widget.
*/
readonly primaryFileType: string;
/**
* The file types the widget can view.
*/
readonly fileTypes: ReadonlyArray<string>;
/**
* The file types for which the factory should be the default.
*/
readonly defaultFor?: ReadonlyArray<string>;
/**
* The file types for which the factory should be the default for rendering,
* if that is different than the default factory (which may be for editing)
* If undefined, then it will fall back on the default file type.
*/
readonly defaultRendered?: ReadonlyArray<string>;
/**
* The application language translator.
*/
readonly translator?: ITranslator;
/**
* A function returning a list of toolbar items to add to the toolbar.
*/
readonly toolbarFactory?: (widget?: Widget) => IToolbarItem[];
}
export namespace LabIcon {
/**
* The simplest possible interface for defining a generic icon.
*/
export interface IIcon {
/**
* The name of the icon. By convention, the icon name will be namespaced
* as so:
*
* "pkg-name:icon-name"
*/
readonly name: string;
/**
* A string containing the raw contents of an svg file.
*/
svgstr: string;
}
/**
* Interface for generic renderer.
*/
export interface IRenderer {
readonly render: (container: HTMLElement, options?: any) => void;
readonly unrender?: (container: HTMLElement, options?: any) => void;
}
/**
* A type that can be resolved to a LabIcon instance.
*/
export type IResolvable = string | (IIcon & Partial<IRenderer>);
}
/**
* A file type to associate with the renderer.
*/
export interface IFileType {
/**
* The name of the file type.
*/
readonly name: string;
/**
* The mime types associated the file type.
*/
readonly mimeTypes: ReadonlyArray<string>;
/**
* The extensions of the file type (e.g. `".txt"`). Can be a compound
* extension (e.g. `".table.json`).
*/
readonly extensions: ReadonlyArray<string>;
/**
* An optional display name for the file type.
*/
readonly displayName?: string;
/**
* An optional pattern for a file name (e.g. `^Dockerfile$`).
*/
readonly pattern?: string;
/**
* The icon for the file type. Can either be a string containing the name
* of an existing icon, or an object with \{name, svgstr\} fields, where
* svgstr is a string containing the raw contents of an svg file.
*/
readonly icon?: LabIcon.IResolvable;
/**
* The icon class name for the file type.
*/
readonly iconClass?: string;
/**
* The icon label for the file type.
*/
readonly iconLabel?: string;
/**
* The file format for the file type ('text', 'base64', or 'json').
*/
readonly fileFormat?: string | null;
}
/**
* An interface for using a RenderMime.IRenderer for output and read-only documents.
*/
export interface IExtension {
/**
* The ID of the extension.
*
* #### Notes
* The convention for extension IDs in JupyterLab is the full NPM package
* name followed by a colon and a unique string token, e.g.
* `'@jupyterlab/apputils-extension:settings'` or `'foo-extension:bar'`.
*/
readonly id: string;
/**
* Extension description.
*
* #### Notes
* This can be used to provide user documentation on the feature
* brought by the extension.
*/
readonly description?: string;
/**
* A renderer factory to be registered to render the MIME type.
*/
readonly rendererFactory: IRendererFactory;
/**
* The rank passed to `RenderMime.addFactory`. If not given,
* defaults to the `defaultRank` of the factory.
*/
readonly rank?: number;
/**
* The timeout after user activity to re-render the data.
*/
readonly renderTimeout?: number;
/**
* Preferred data type from the model. Defaults to `string`.
*/
readonly dataType?: 'string' | 'json';
/**
* The options used to open a document with the renderer factory.
*/
readonly documentWidgetFactoryOptions?:
| IDocumentWidgetFactoryOptions
| ReadonlyArray<IDocumentWidgetFactoryOptions>;
/**
* The optional file type associated with the extension.
*/
readonly fileTypes?: ReadonlyArray<IFileType>;
}
/**
* The interface for a module that exports an extension or extensions as
* the default value.
*/
export interface IExtensionModule {
/**
* The default export.
*/
readonly default: IExtension | ReadonlyArray<IExtension>;
}
/**
* A widget which displays the contents of a mime model.
*/
export interface IRenderer extends Widget {
/**
* Render a mime model.
*
* @param model - The mime model to render.
*
* @returns A promise which resolves when rendering is complete.
*
* #### Notes
* This method may be called multiple times during the lifetime
* of the widget to update it if and when new data is available.
*/
renderModel(model: IMimeModel): Promise<void>;
}
/**
* The interface for a renderer factory.
*/
export interface IRendererFactory {
/**
* Whether the factory is a "safe" factory.
*
* #### Notes
* A "safe" factory produces renderer widgets which can render
* untrusted model data in a usable way. *All* renderers must
* handle untrusted data safely, but some may simply failover
* with a "Run cell to view output" message. A "safe" renderer
* is an indication that its sanitized output will be useful.
*/
readonly safe: boolean;
/**
* The mime types handled by this factory.
*/
readonly mimeTypes: ReadonlyArray<string>;
/**
* The default rank of the factory. If not given, defaults to 100.
*/
readonly defaultRank?: number;
/**
* Create a renderer which displays the mime data.
*
* @param options - The options used to render the data.
*/
createRenderer(options: IRendererOptions): IRenderer;
}
/**
* The options used to create a renderer.
*/
export interface IRendererOptions {
/**
* The preferred mimeType to render.
*/
mimeType: string;
/**
* The html sanitizer.
*/
sanitizer: ISanitizer;
/**
* An optional url resolver.
*/
resolver: IResolver | null;
/**
* An optional link handler.
*/
linkHandler: ILinkHandler | null;
/**
* The LaTeX typesetter.
*/
latexTypesetter: ILatexTypesetter | null;
/**
* The Markdown parser.
*/
markdownParser?: IMarkdownParser | null;
/**
* The application language translator.
*/
translator?: ITranslator;
}
/**
* The options used to sanitize.
*/
export interface ISanitizerOptions {
/**
* The allowed tags.
*/
allowedTags?: string[];
/**
* The allowed attributes for a given tag.
*/
allowedAttributes?: { [key: string]: string[] };
/**
* The allowed style values for a given tag.
*/
allowedStyles?: { [key: string]: { [key: string]: RegExp[] } };
}
/**
* An object that handles html sanitization.
*/
export interface ISanitizer {
/**
* @returns Whether to replace URLs by HTML anchors.
*/
getAutolink?(): boolean;
/**
* Sanitize an HTML string.
*
* @param dirty - The dirty text.
* @param options - The optional sanitization options.
*
* @returns The sanitized string.
*/
sanitize(dirty: string, options?: ISanitizerOptions): string;
}
/**
* An object that handles links on a node.
*/
export interface ILinkHandler {
/**
* Add the link handler to the node.
*
* @param node the anchor node for which to handle the link.
*
* @param path the path to open when the link is clicked.
*
* @param id an optional element id to scroll to when the path is opened.
*/
handleLink(node: HTMLElement, path: string, id?: string): void;
/**
* Add the path handler to the node.
*
* @param node the anchor node for which to handle the link.
*
* @param path the path to open when the link is clicked.
*
* @param scope the scope to which the path is bound.
*
* @param id an optional element id to scroll to when the path is opened.
*/
handlePath?(
node: HTMLElement,
path: string,
scope: 'kernel' | 'server',
id?: string
): void;
}
export interface IResolvedLocation {
/**
* Location scope.
*/
scope: 'kernel' | 'server';
/**
* Resolved path.
*/
path: string;
}
/**
* An object that resolves relative URLs.
*/
export interface IResolver {
/**
* Resolve a relative url to an absolute url path.
*/
resolveUrl(url: string): Promise<string>;
/**
* Get the download url for a given absolute url path.
*
* #### Notes
* This URL may include a query parameter.
*/
getDownloadUrl(url: string): Promise<string>;
/**
* Whether the URL should be handled by the resolver
* or not.
*
* @param allowRoot - Whether the paths starting at Unix-style filesystem root (`/`) are permitted.
*
* #### Notes
* This is similar to the `isLocal` check in `URLExt`,
* but can also perform additional checks on whether the
* resolver should handle a given URL.
*/
isLocal?: (url: string, allowRoot?: boolean) => boolean;
/**
* Resolve a path from Jupyter kernel to a path:
* - relative to `root_dir` (preferrably) this is in jupyter-server scope,
* - path understood and known by kernel (if such a path exists).
* Returns `null` if there is no file matching provided path in neither
* kernel nor jupyter-server contents manager.
*/
resolvePath?: (path: string) => Promise<IResolvedLocation | null>;
}
/**
* The interface for a LaTeX typesetter.
*/
export interface ILatexTypesetter {
/**
* Typeset a DOM element.
*
* @param element - the DOM element to typeset. The typesetting may
* happen synchronously or asynchronously.
*/
typeset(element: HTMLElement): void;
}
/**
* The interface for a Markdown parser.
*/
export interface IMarkdownParser {
/**
* Render a markdown source into unsanitized HTML.
*
* @param source - The string to render.
* @returns - A promise of the string containing HTML which may require sanitization.
*/
render(source: string): Promise<string>;
}
// ********************** //
// Translation interfaces //
// ********************** //
/**
* Bundle of gettext-based translation functions for a specific domain.
*/
export type TranslationBundle = {
/**
* Alias for `gettext` (translate strings without number inflection)
* @param msgid message (text to translate)
* @param args
*
* @returns A translated string if found, or the original string.
*/
__(msgid: string, ...args: any[]): string;
/**
* Alias for `ngettext` (translate accounting for plural forms)
* @param msgid message for singular
* @param msgid_plural message for plural
* @param n determines which plural form to use
* @param args
*
* @returns A translated string if found, or the original string.
*/
_n(msgid: string, msgid_plural: string, n: number, ...args: any[]): string;
/**
* Alias for `pgettext` (translate in given context)
* @param msgctxt context
* @param msgid message (text to translate)
* @param args
*
* @returns A translated string if found, or the original string.
*/
_p(msgctxt: string, msgid: string, ...args: any[]): string;
/**
* Alias for `npgettext` (translate accounting for plural forms in given context)
* @param msgctxt context
* @param msgid message for singular
* @param msgid_plural message for plural
* @param n number used to determine which plural form to use
* @param args
*
* @returns A translated string if found, or the original string.
*/
_np(
msgctxt: string,
msgid: string,
msgid_plural: string,
n: number,
...args: any[]
): string;
/**
* Look up the message id in the catalog and return the corresponding message string.
* Otherwise, the message id is returned.
*
* @param msgid message (text to translate)
* @param args
*
* @returns A translated string if found, or the original string.
*/
gettext(msgid: string, ...args: any[]): string;
/**
* Do a plural-forms lookup of a message id. msgid is used as the message id for
* purposes of lookup in the catalog, while n is used to determine which plural form
* to use. Otherwise, when n is 1 msgid is returned, and msgid_plural is returned in
* all other cases.
*
* @param msgid message for singular
* @param msgid_plural message for plural
* @param n determines which plural form to use
* @param args
*
* @returns A translated string if found, or the original string.
*/
ngettext(
msgid: string,
msgid_plural: string,
n: number,
...args: any[]
): string;
/**
* Look up the context and message id in the catalog and return the corresponding
* message string. Otherwise, the message id is returned.
*
* @param msgctxt context
* @param msgid message (text to translate)
* @param args
*
* @returns A translated string if found, or the original string.
*/
pgettext(msgctxt: string, msgid: string, ...args: any[]): string;
/**
* Do a plural-forms lookup of a message id. msgid is used as the message id for
* purposes of lookup in the catalog, while n is used to determine which plural
* form to use. Otherwise, when n is 1 msgid is returned, and msgid_plural is
* returned in all other cases.
*
* @param msgctxt context
* @param msgid message for singular
* @param msgid_plural message for plural
* @param n number used to determine which plural form to use
* @param args
*
* @returns A translated string if found, or the original string.
*/
npgettext(
msgctxt: string,
msgid: string,
msgid_plural: string,
n: number,
...args: any[]
): string;
/**
* Do a plural-forms lookup of a message id. msgid is used as the message id for
* purposes of lookup in the catalog, while n is used to determine which plural
* form to use. Otherwise, when n is 1 msgid is returned, and msgid_plural is
* returned in all other cases.
*
* @param domain - The translations domain.
* @param msgctxt - The message context.
* @param msgid - The singular string to translate.
* @param msgid_plural - The plural string to translate.
* @param n - The number for pluralization.
* @param args - Any additional values to use with interpolation
*
* @returns A translated string if found, or the original string.
*/
dcnpgettext(
domain: string,
msgctxt: string,
msgid: string,
msgid_plural: string,
n: number,
...args: any[]
): string;
};
/**
* Translation provider interface
*/
export interface ITranslator {
/**
* The code of the language in use.
*/
readonly languageCode: string;
/**
* Load translation bundles for a given domain.
*
* @param domain The translation domain to use for translations.
*
* @returns The translation bundle if found, or the English bundle.
*/
load(domain: string): TranslationBundle;
}
}