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