1 | import { CellType } from '@jupyterlab/nbformat';
|
2 | import { IDataConnector } from '@jupyterlab/statedb';
|
3 | import { PartialJSONObject, PartialJSONValue, ReadonlyPartialJSONObject, ReadonlyPartialJSONValue, Token } from '@lumino/coreutils';
|
4 | import { IDisposable } from '@lumino/disposable';
|
5 | import { ISignal } from '@lumino/signaling';
|
6 | import { ISchemaValidator } from './settingregistry';
|
7 | import type { RJSFSchema, UiSchema } from '@rjsf/utils';
|
8 | /**
|
9 | * The setting registry token.
|
10 | */
|
11 | export declare const ISettingRegistry: Token<ISettingRegistry>;
|
12 | /**
|
13 | * The settings registry interface.
|
14 | */
|
15 | export interface ISettingRegistry {
|
16 | /**
|
17 | * The data connector used by the setting registry.
|
18 | */
|
19 | readonly connector: IDataConnector<ISettingRegistry.IPlugin, string, string>;
|
20 | /**
|
21 | * The schema of the setting registry.
|
22 | */
|
23 | readonly schema: ISettingRegistry.ISchema;
|
24 | /**
|
25 | * The schema validator used by the setting registry.
|
26 | */
|
27 | readonly validator: ISchemaValidator;
|
28 | /**
|
29 | * A signal that emits the name of a plugin when its settings change.
|
30 | */
|
31 | readonly pluginChanged: ISignal<this, string>;
|
32 | /**
|
33 | * The collection of setting registry plugins.
|
34 | */
|
35 | readonly plugins: {
|
36 | [name: string]: ISettingRegistry.IPlugin | undefined;
|
37 | };
|
38 | /**
|
39 | * Get an individual setting.
|
40 | *
|
41 | * @param plugin - The name of the plugin whose settings are being retrieved.
|
42 | *
|
43 | * @param key - The name of the setting being retrieved.
|
44 | *
|
45 | * @returns A promise that resolves when the setting is retrieved.
|
46 | */
|
47 | get(plugin: string, key: string): Promise<{
|
48 | composite: PartialJSONValue | undefined;
|
49 | user: PartialJSONValue | undefined;
|
50 | }>;
|
51 | /**
|
52 | * Load a plugin's settings into the setting registry.
|
53 | *
|
54 | * @param plugin - The name of the plugin whose settings are being loaded.
|
55 | *
|
56 | * @param forceTransform - An optional parameter to force replay the transforms methods.
|
57 | *
|
58 | * @returns A promise that resolves with a plugin settings object or rejects
|
59 | * if the plugin is not found.
|
60 | */
|
61 | load(plugin: string, forceTransform?: boolean): Promise<ISettingRegistry.ISettings>;
|
62 | /**
|
63 | * Reload a plugin's settings into the registry even if they already exist.
|
64 | *
|
65 | * @param plugin - The name of the plugin whose settings are being reloaded.
|
66 | *
|
67 | * @returns A promise that resolves with a plugin settings object or rejects
|
68 | * with a list of `ISchemaValidator.IError` objects if it fails.
|
69 | */
|
70 | reload(plugin: string): Promise<ISettingRegistry.ISettings>;
|
71 | /**
|
72 | * Remove a single setting in the registry.
|
73 | *
|
74 | * @param plugin - The name of the plugin whose setting is being removed.
|
75 | *
|
76 | * @param key - The name of the setting being removed.
|
77 | *
|
78 | * @returns A promise that resolves when the setting is removed.
|
79 | */
|
80 | remove(plugin: string, key: string): Promise<void>;
|
81 | /**
|
82 | * Set a single setting in the registry.
|
83 | *
|
84 | * @param plugin - The name of the plugin whose setting is being set.
|
85 | *
|
86 | * @param key - The name of the setting being set.
|
87 | *
|
88 | * @param value - The value of the setting being set.
|
89 | *
|
90 | * @returns A promise that resolves when the setting has been saved.
|
91 | *
|
92 | */
|
93 | set(plugin: string, key: string, value: PartialJSONValue): Promise<void>;
|
94 | /**
|
95 | * Register a plugin transform function to act on a specific plugin.
|
96 | *
|
97 | * @param plugin - The name of the plugin whose settings are transformed.
|
98 | *
|
99 | * @param transforms - The transform functions applied to the plugin.
|
100 | *
|
101 | * @returns A disposable that removes the transforms from the registry.
|
102 | *
|
103 | * #### Notes
|
104 | * - `compose` transformations: The registry automatically overwrites a
|
105 | * plugin's default values with user overrides, but a plugin may instead wish
|
106 | * to merge values. This behavior can be accomplished in a `compose`
|
107 | * transformation.
|
108 | * - `fetch` transformations: The registry uses the plugin data that is
|
109 | * fetched from its connector. If a plugin wants to override, e.g. to update
|
110 | * its schema with dynamic defaults, a `fetch` transformation can be applied.
|
111 | */
|
112 | transform(plugin: string, transforms: {
|
113 | [phase in ISettingRegistry.IPlugin.Phase]?: ISettingRegistry.IPlugin.Transform;
|
114 | }): IDisposable;
|
115 | /**
|
116 | * Upload a plugin's settings.
|
117 | *
|
118 | * @param plugin - The name of the plugin whose settings are being set.
|
119 | *
|
120 | * @param raw - The raw plugin settings being uploaded.
|
121 | *
|
122 | * @returns A promise that resolves when the settings have been saved.
|
123 | */
|
124 | upload(plugin: string, raw: string): Promise<void>;
|
125 | }
|
126 | /**
|
127 | * A namespace for setting registry interfaces.
|
128 | */
|
129 | export declare namespace ISettingRegistry {
|
130 | /**
|
131 | * The primitive types available in a JSON schema.
|
132 | */
|
133 | type Primitive = 'array' | 'boolean' | 'null' | 'number' | 'object' | 'string';
|
134 | /**
|
135 | * The menu ids defined by default.
|
136 | */
|
137 | type DefaultMenuId = 'jp-menu-file' | 'jp-menu-file-new' | 'jp-menu-edit' | 'jp-menu-help' | 'jp-menu-kernel' | 'jp-menu-run' | 'jp-menu-settings' | 'jp-menu-view' | 'jp-menu-tabs';
|
138 | /**
|
139 | * An interface defining a menu.
|
140 | */
|
141 | interface IMenu extends PartialJSONObject {
|
142 | /**
|
143 | * Unique menu identifier
|
144 | */
|
145 | id: DefaultMenuId | string;
|
146 | /**
|
147 | * Menu items
|
148 | */
|
149 | items?: IMenuItem[];
|
150 | /**
|
151 | * The rank order of the menu among its siblings.
|
152 | */
|
153 | rank?: number;
|
154 | /**
|
155 | * Menu title
|
156 | *
|
157 | * #### Notes
|
158 | * Default will be the capitalized id.
|
159 | */
|
160 | label?: string;
|
161 | /**
|
162 | * Menu icon id
|
163 | *
|
164 | * #### Note
|
165 | * The icon id will looked for in registered LabIcon.
|
166 | */
|
167 | icon?: string;
|
168 | /**
|
169 | * Get the mnemonic index for the title.
|
170 | *
|
171 | * #### Notes
|
172 | * The default value is `-1`.
|
173 | */
|
174 | mnemonic?: number;
|
175 | /**
|
176 | * Whether a menu is disabled. `False` by default.
|
177 | *
|
178 | * #### Notes
|
179 | * This allows an user to suppress a menu.
|
180 | */
|
181 | disabled?: boolean;
|
182 | }
|
183 | /**
|
184 | * An interface describing a menu item.
|
185 | */
|
186 | interface IMenuItem extends PartialJSONObject {
|
187 | /**
|
188 | * The type of the menu item.
|
189 | *
|
190 | * The default value is `'command'`.
|
191 | */
|
192 | type?: 'command' | 'submenu' | 'separator';
|
193 | /**
|
194 | * The command to execute when the item is triggered.
|
195 | *
|
196 | * The default value is an empty string.
|
197 | */
|
198 | command?: string;
|
199 | /**
|
200 | * The arguments for the command.
|
201 | *
|
202 | * The default value is an empty object.
|
203 | */
|
204 | args?: PartialJSONObject;
|
205 | /**
|
206 | * The rank order of the menu item among its siblings.
|
207 | */
|
208 | rank?: number;
|
209 | /**
|
210 | * The submenu for a `'submenu'` type item.
|
211 | *
|
212 | * The default value is `null`.
|
213 | */
|
214 | submenu?: IMenu | null;
|
215 | /**
|
216 | * Whether a menu item is disabled. `false` by default.
|
217 | *
|
218 | * #### Notes
|
219 | * This allows an user to suppress menu items.
|
220 | */
|
221 | disabled?: boolean;
|
222 | }
|
223 | /**
|
224 | * An interface describing a context menu item
|
225 | */
|
226 | interface IContextMenuItem extends IMenuItem {
|
227 | /**
|
228 | * The CSS selector for the context menu item.
|
229 | *
|
230 | * The context menu item will only be displayed in the context menu
|
231 | * when the selector matches a node on the propagation path of the
|
232 | * contextmenu event. This allows the menu item to be restricted to
|
233 | * user-defined contexts.
|
234 | *
|
235 | * The selector must not contain commas.
|
236 | */
|
237 | selector: string;
|
238 | }
|
239 | /**
|
240 | * The settings for a specific plugin.
|
241 | */
|
242 | interface IPlugin extends PartialJSONObject {
|
243 | /**
|
244 | * The name of the plugin.
|
245 | */
|
246 | id: string;
|
247 | /**
|
248 | * The collection of values for a specified plugin.
|
249 | */
|
250 | data: ISettingBundle;
|
251 | /**
|
252 | * The raw user settings data as a string containing JSON with comments.
|
253 | */
|
254 | raw: string;
|
255 | /**
|
256 | * The JSON schema for the plugin.
|
257 | */
|
258 | schema: ISchema;
|
259 | /**
|
260 | * The published version of the NPM package containing the plugin.
|
261 | */
|
262 | version: string;
|
263 | }
|
264 | /**
|
265 | * A namespace for plugin functionality.
|
266 | */
|
267 | namespace IPlugin {
|
268 | /**
|
269 | * A function that transforms a plugin object before it is consumed by the
|
270 | * setting registry.
|
271 | */
|
272 | type Transform = (plugin: IPlugin) => IPlugin;
|
273 | /**
|
274 | * The phases during which a transformation may be applied to a plugin.
|
275 | */
|
276 | type Phase = 'compose' | 'fetch';
|
277 | }
|
278 | /**
|
279 | * A minimal subset of the formal JSON Schema that describes a property.
|
280 | */
|
281 | interface IProperty extends PartialJSONObject {
|
282 | /**
|
283 | * The default value, if any.
|
284 | */
|
285 | default?: PartialJSONValue;
|
286 | /**
|
287 | * The schema description.
|
288 | */
|
289 | description?: string;
|
290 | /**
|
291 | * The schema's child properties.
|
292 | */
|
293 | properties?: {
|
294 | [property: string]: IProperty;
|
295 | };
|
296 | /**
|
297 | * The title of a property.
|
298 | */
|
299 | title?: string;
|
300 | /**
|
301 | * The type or types of the data.
|
302 | */
|
303 | type?: Primitive | Primitive[];
|
304 | }
|
305 | /**
|
306 | * A schema type that is a minimal subset of the formal JSON Schema along with
|
307 | * optional JupyterLab rendering hints.
|
308 | */
|
309 | interface ISchema extends IProperty {
|
310 | /**
|
311 | * The JupyterLab menus that are created by a plugin's schema.
|
312 | */
|
313 | 'jupyter.lab.menus'?: {
|
314 | main: IMenu[];
|
315 | context: IContextMenuItem[];
|
316 | };
|
317 | /**
|
318 | * Whether the schema is deprecated.
|
319 | *
|
320 | * #### Notes
|
321 | * This flag can be used by functionality that loads this plugin's settings
|
322 | * from the registry. For example, the setting editor does not display a
|
323 | * plugin's settings if it is set to `true`.
|
324 | */
|
325 | 'jupyter.lab.setting-deprecated'?: boolean;
|
326 | /**
|
327 | * The JupyterLab icon hint.
|
328 | */
|
329 | 'jupyter.lab.setting-icon'?: string;
|
330 | /**
|
331 | * The JupyterLab icon class hint.
|
332 | */
|
333 | 'jupyter.lab.setting-icon-class'?: string;
|
334 | /**
|
335 | * The JupyterLab icon label hint.
|
336 | */
|
337 | 'jupyter.lab.setting-icon-label'?: string;
|
338 | /**
|
339 | * The JupyterLab toolbars created by a plugin's schema.
|
340 | *
|
341 | * #### Notes
|
342 | * The toolbar items are grouped by document or widget factory name
|
343 | * that will contain a toolbar.
|
344 | */
|
345 | 'jupyter.lab.toolbars'?: {
|
346 | [factory: string]: IToolbarItem[];
|
347 | };
|
348 | /**
|
349 | * A flag that indicates plugin should be transformed before being used by
|
350 | * the setting registry.
|
351 | *
|
352 | * #### Notes
|
353 | * If this value is set to `true`, the setting registry will wait until a
|
354 | * transformation has been registered (by calling the `transform()` method
|
355 | * of the registry) for the plugin ID before resolving `load()` promises.
|
356 | * This means that if the attribute is set to `true` but no transformation
|
357 | * is registered in time, calls to `load()` a plugin will eventually time
|
358 | * out and reject.
|
359 | */
|
360 | 'jupyter.lab.transform'?: boolean;
|
361 | /**
|
362 | * The JupyterLab shortcuts that are created by a plugin's schema.
|
363 | */
|
364 | 'jupyter.lab.shortcuts'?: IShortcut[];
|
365 | /**
|
366 | * The JupyterLab metadata-form schema
|
367 | */
|
368 | 'jupyter.lab.metadataforms'?: IMetadataForm[];
|
369 | /**
|
370 | * The root schema is always an object.
|
371 | */
|
372 | type: 'object';
|
373 | }
|
374 | /**
|
375 | * The setting values for a plugin.
|
376 | */
|
377 | interface ISettingBundle extends PartialJSONObject {
|
378 | /**
|
379 | * A composite of the user setting values and the plugin schema defaults.
|
380 | *
|
381 | * #### Notes
|
382 | * The `composite` values will always be a superset of the `user` values.
|
383 | */
|
384 | composite: PartialJSONObject;
|
385 | /**
|
386 | * The user setting values.
|
387 | */
|
388 | user: PartialJSONObject;
|
389 | }
|
390 | /**
|
391 | * An interface for manipulating the settings of a specific plugin.
|
392 | */
|
393 | interface ISettings<O extends ReadonlyPartialJSONObject = ReadonlyPartialJSONObject> extends IDisposable {
|
394 | /**
|
395 | * A signal that emits when the plugin's settings have changed.
|
396 | */
|
397 | readonly changed: ISignal<this, void>;
|
398 | /**
|
399 | * The composite of user settings and extension defaults.
|
400 | */
|
401 | readonly composite: O;
|
402 | /**
|
403 | * The plugin's ID.
|
404 | */
|
405 | readonly id: string;
|
406 | readonly plugin: ISettingRegistry.IPlugin;
|
407 | /**
|
408 | * The plugin settings raw text value.
|
409 | */
|
410 | readonly raw: string;
|
411 | /**
|
412 | * The plugin's schema.
|
413 | */
|
414 | readonly schema: ISettingRegistry.ISchema;
|
415 | /**
|
416 | * The user settings.
|
417 | */
|
418 | readonly user: O;
|
419 | /**
|
420 | * The published version of the NPM package containing these settings.
|
421 | */
|
422 | readonly version: string;
|
423 | /**
|
424 | * Return the defaults in a commented JSON format.
|
425 | */
|
426 | annotatedDefaults(): string;
|
427 | /**
|
428 | * Calculate the default value of a setting by iterating through the schema.
|
429 | *
|
430 | * @param key - The name of the setting whose default value is calculated.
|
431 | *
|
432 | * @returns A calculated default JSON value for a specific setting.
|
433 | */
|
434 | default(key: string): PartialJSONValue | undefined;
|
435 | /**
|
436 | * Get an individual setting.
|
437 | *
|
438 | * @param key - The name of the setting being retrieved.
|
439 | *
|
440 | * @returns The setting value.
|
441 | */
|
442 | get(key: string): {
|
443 | composite: ReadonlyPartialJSONValue | undefined;
|
444 | user: ReadonlyPartialJSONValue | undefined;
|
445 | };
|
446 | /**
|
447 | * Remove a single setting.
|
448 | *
|
449 | * @param key - The name of the setting being removed.
|
450 | *
|
451 | * @returns A promise that resolves when the setting is removed.
|
452 | *
|
453 | * #### Notes
|
454 | * This function is asynchronous because it writes to the setting registry.
|
455 | */
|
456 | remove(key: string): Promise<void>;
|
457 | /**
|
458 | * Save all of the plugin's user settings at once.
|
459 | */
|
460 | save(raw: string): Promise<void>;
|
461 | /**
|
462 | * Set a single setting.
|
463 | *
|
464 | * @param key - The name of the setting being set.
|
465 | *
|
466 | * @param value - The value of the setting.
|
467 | *
|
468 | * @returns A promise that resolves when the setting has been saved.
|
469 | *
|
470 | * #### Notes
|
471 | * This function is asynchronous because it writes to the setting registry.
|
472 | */
|
473 | set(key: string, value: PartialJSONValue): Promise<void>;
|
474 | /**
|
475 | * Validates raw settings with comments.
|
476 | *
|
477 | * @param raw - The JSON with comments string being validated.
|
478 | *
|
479 | * @returns A list of errors or `null` if valid.
|
480 | */
|
481 | validate(raw: string): ISchemaValidator.IError[] | null;
|
482 | }
|
483 | /**
|
484 | * An interface describing a JupyterLab keyboard shortcut.
|
485 | */
|
486 | interface IShortcut extends PartialJSONObject {
|
487 | /**
|
488 | * The optional arguments passed into the shortcut's command.
|
489 | */
|
490 | args?: PartialJSONObject;
|
491 | /**
|
492 | * The command invoked by the shortcut.
|
493 | */
|
494 | command: string;
|
495 | /**
|
496 | * Whether a keyboard shortcut is disabled. `False` by default.
|
497 | */
|
498 | disabled?: boolean;
|
499 | /**
|
500 | * The key sequence of the shortcut.
|
501 | *
|
502 | * ### Notes
|
503 | *
|
504 | * If this is a list like `['Ctrl A', 'B']`, the user needs to press
|
505 | * `Ctrl A` followed by `B` to trigger the shortcuts.
|
506 | */
|
507 | keys: string[];
|
508 | /**
|
509 | * The CSS selector applicable to the shortcut.
|
510 | */
|
511 | selector: string;
|
512 | }
|
513 | /**
|
514 | * An interface describing the metadata form.
|
515 | */
|
516 | interface IMetadataForm extends PartialJSONObject {
|
517 | /**
|
518 | * The section unique ID.
|
519 | */
|
520 | id: string;
|
521 | /**
|
522 | * The metadata schema.
|
523 | */
|
524 | metadataSchema: IMetadataSchema;
|
525 | /**
|
526 | * The ui schema as used by react-JSON-schema-form.
|
527 | */
|
528 | uiSchema?: {
|
529 | [metadataKey: string]: UiSchema;
|
530 | };
|
531 | /**
|
532 | * The jupyter properties.
|
533 | */
|
534 | metadataOptions?: {
|
535 | [metadataKey: string]: IMetadataOptions;
|
536 | };
|
537 | /**
|
538 | * The section label.
|
539 | */
|
540 | label?: string;
|
541 | /**
|
542 | * The section rank in notebooktools panel.
|
543 | */
|
544 | rank?: number;
|
545 | /**
|
546 | * Whether to show the modified field from default value.
|
547 | */
|
548 | showModified?: boolean;
|
549 | /**
|
550 | * Keep the plugin at origin of the metadata form.
|
551 | */
|
552 | _origin?: string;
|
553 | }
|
554 | /**
|
555 | * The metadata schema as defined in JSON schema.
|
556 | */
|
557 | interface IMetadataSchema extends RJSFSchema {
|
558 | /**
|
559 | * The properties as defined in JSON schema, and interpretable by react-JSON-schema-form.
|
560 | */
|
561 | properties: {
|
562 | [option: string]: any;
|
563 | };
|
564 | /**
|
565 | * The required fields.
|
566 | */
|
567 | required?: string[];
|
568 | /**
|
569 | * Support for allOf feature of JSON schema (useful for if/then/else).
|
570 | */
|
571 | allOf?: Array<PartialJSONObject>;
|
572 | }
|
573 | /**
|
574 | * Options to customize the widget, the field and the relevant metadata.
|
575 | */
|
576 | interface IMetadataOptions extends PartialJSONObject {
|
577 | /**
|
578 | * Name of a custom react widget registered.
|
579 | */
|
580 | customWidget?: string;
|
581 | /**
|
582 | * Name of a custom react field registered.
|
583 | */
|
584 | customField?: string;
|
585 | /**
|
586 | * Metadata applied to notebook or cell.
|
587 | */
|
588 | metadataLevel?: 'cell' | 'notebook';
|
589 | /**
|
590 | * Cells which should have this metadata.
|
591 | */
|
592 | cellTypes?: CellType[];
|
593 | /**
|
594 | * Whether to avoid writing default value in metadata.
|
595 | */
|
596 | writeDefault?: boolean;
|
597 | }
|
598 | /**
|
599 | * An interface describing a toolbar item.
|
600 | */
|
601 | interface IToolbarItem extends PartialJSONObject {
|
602 | /**
|
603 | * Unique toolbar item name
|
604 | */
|
605 | name: string;
|
606 | /**
|
607 | * The command to execute when the item is triggered.
|
608 | *
|
609 | * The default value is an empty string.
|
610 | */
|
611 | command?: string;
|
612 | /**
|
613 | * The arguments for the command.
|
614 | *
|
615 | * The default value is an empty object.
|
616 | */
|
617 | args?: PartialJSONObject;
|
618 | /**
|
619 | * Whether the toolbar item is ignored (i.e. not created). `false` by default.
|
620 | *
|
621 | * #### Notes
|
622 | * This allows an user to suppress toolbar items.
|
623 | */
|
624 | disabled?: boolean;
|
625 | /**
|
626 | * Item icon id
|
627 | *
|
628 | * #### Note
|
629 | * The id will be looked for in the LabIcon registry.
|
630 | * The command icon will be overridden by this label if defined.
|
631 | */
|
632 | icon?: string;
|
633 | /**
|
634 | * Item label
|
635 | *
|
636 | * #### Note
|
637 | * The command label will be overridden by this label if defined.
|
638 | */
|
639 | label?: string;
|
640 | /**
|
641 | * The rank order of the toolbar item among its siblings.
|
642 | */
|
643 | rank?: number;
|
644 | /**
|
645 | * The type of the toolbar item.
|
646 | */
|
647 | type?: 'command' | 'spacer';
|
648 | }
|
649 | }
|