@jupyterlab/settingregistry 4.0.0-alpha.8 → 4.0.0-beta.0

package/lib/plugin-schema.json

@@ -56,6 +56,13 @@
             },
             "additionalProperties": false
         },
+        "jupyter.lab.metadataforms": {
+            "items": {
+                "$ref": "#/definitions/metadataForm"
+            },
+            "type": "array",
+            "default": []
+        },
         "jupyter.lab.setting-deprecated": {
             "type": "boolean",
             "default": false
@@ -295,6 +302,87 @@
             "required": ["name"],
             "additionalProperties": false,
             "type": "object"
+        },
+        "metadataForm": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "The section ID"
+                },
+                "metadataSchema": {
+                    "type": "object",
+                    "items": {
+                        "$ref": "#/definitions/metadataSchema"
+                    }
+                },
+                "uiSchema": {
+                    "type": "object"
+                },
+                "metadataOptions": {
+                    "type": "object",
+                    "items": {
+                        "$ref": "#/definitions/metadataOptions"
+                    }
+                },
+                "label": {
+                    "type": "string",
+                    "description": "The section label"
+                },
+                "rank": {
+                    "type": "integer",
+                    "description": "The rank of the section in the right panel"
+                },
+                "showModified": {
+                    "type": "boolean",
+                    "description": "Whether to show modified values from defaults"
+                }
+            },
+            "required": ["id", "metadataSchema"]
+        },
+        "metadataSchema": {
+            "properties": {
+                "properties": {
+                    "type": "object",
+                    "description": "The property set up by extension",
+                    "properties": {
+                        "title": {
+                            "type": "string"
+                        },
+                        "description": {
+                            "type": "string"
+                        },
+                        "type": {
+                            "type": "string"
+                        }
+                    }
+                }
+            },
+            "type": "object",
+            "required": ["properties"]
+        },
+        "metadataOptions": {
+            "properties": {
+                "customRenderer": {
+                    "type": "string"
+                },
+                "metadataLevel": {
+                    "type": "string",
+                    "enum": ["cell", "notebook"],
+                    "default": "cell"
+                },
+                "cellTypes": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "enum": ["code", "markdown", "raw"]
+                    }
+                },
+                "writeDefault": {
+                    "type": "boolean"
+                }
+            },
+            "type": "object"
         }
     }
 }

package/lib/settingregistry.d.ts

@@ -29,18 +29,14 @@ export declare namespace ISchemaValidator {
      * A schema validation error definition.
      */
     interface IError {
-        /**
-         * The path in the data where the error occurred.
-         */
-        dataPath: string;
         /**
          * The keyword whose validation failed.
          */
-        keyword: string;
+        keyword: string | string[];
         /**
          * The error message.
          */
-        message: string;
+        message?: string;
         /**
          * Optional parameter metadata that might be included in an error.
          */
@@ -49,6 +45,26 @@ export declare namespace ISchemaValidator {
          * The path in the schema where the error occurred.
          */
         schemaPath: string;
+        /**
+         * @todo handle new fields from ajv8
+         **/
+        schema?: unknown;
+        /**
+         * @todo handle new fields from ajv8
+         **/
+        instancePath: string;
+        /**
+         * @todo handle new fields from ajv8
+         **/
+        propertyName?: string;
+        /**
+         * @todo handle new fields from ajv8
+         **/
+        data?: unknown;
+        /**
+         * @todo handle new fields from ajv8
+         **/
+        parentSchema?: unknown;
     }
 }
 /**
@@ -229,10 +245,35 @@ export declare class SettingRegistry implements ISettingRegistry {
     private _timeout;
     private _transformers;
 }
+/**
+ * Base settings specified by a JSON schema.
+ */
+export declare class BaseSettings<T extends ISettingRegistry.IProperty = ISettingRegistry.IProperty> {
+    constructor(options: {
+        schema: T;
+    });
+    /**
+     * The plugin's schema.
+     */
+    get schema(): T;
+    /**
+     * Checks if any fields are different from the default value.
+     */
+    isDefault(user: ReadonlyPartialJSONObject): boolean;
+    /**
+     * Calculate the default value of a setting by iterating through the schema.
+     *
+     * @param key - The name of the setting whose default value is calculated.
+     *
+     * @returns A calculated default JSON value for a specific setting.
+     */
+    default(key?: string): PartialJSONValue | undefined;
+    private _schema;
+}
 /**
  * A manager for a specific plugin's settings.
  */
-export declare class Settings implements ISettingRegistry.ISettings {
+export declare class Settings extends BaseSettings<ISettingRegistry.ISchema> implements ISettingRegistry.ISettings {
     /**
      * Instantiate a new plugin settings manager.
      */
@@ -258,18 +299,13 @@ export declare class Settings implements ISettingRegistry.ISettings {
      */
     get isDisposed(): boolean;
     get plugin(): ISettingRegistry.IPlugin;
-    /**
-     * The plugin's schema.
-     */
-    get schema(): ISettingRegistry.ISchema;
     /**
      * The plugin settings raw text value.
      */
     get raw(): string;
     /**
-     * Checks if any fields are different from the default value.
+     * Whether the settings have been modified by the user or not.
      */
-    isDefault(user: ReadonlyPartialJSONObject): boolean;
     get isModified(): boolean;
     /**
      * The user settings.
@@ -283,14 +319,6 @@ export declare class Settings implements ISettingRegistry.ISettings {
      * Return the defaults in a commented JSON format.
      */
     annotatedDefaults(): string;
-    /**
-     * Calculate the default value of a setting by iterating through the schema.
-     *
-     * @param key - The name of the setting whose default value is calculated.
-     *
-     * @returns A calculated default JSON value for a specific setting.
-     */
-    default(key?: string): PartialJSONValue | undefined;
     /**
      * Dispose of the plugin settings resources.
      */

package/lib/settingregistry.js

@@ -11,6 +11,17 @@ import SCHEMA from './plugin-schema.json';
  * An alias for the JSON deep copy function.
  */
 const copy = JSONExt.deepCopy;
+/** Default arguments for Ajv instances.
+ *
+ * https://ajv.js.org/options.html
+ */
+const AJV_DEFAULT_OPTIONS = {
+    /**
+     * @todo the implications of enabling strict mode are beyond the scope of
+     *       the initial PR
+     */
+    strict: false
+};
 /**
  * The default number of milliseconds before a `load()` call to the registry
  * will wait before timing out if it requires a transformation that has not been
@@ -29,8 +40,11 @@ export class DefaultSchemaValidator {
      * Instantiate a schema validator.
      */
     constructor() {
-        this._composer = new Ajv({ useDefaults: true });
-        this._validator = new Ajv();
+        this._composer = new Ajv({
+            useDefaults: true,
+            ...AJV_DEFAULT_OPTIONS
+        });
+        this._validator = new Ajv({ ...AJV_DEFAULT_OPTIONS });
         this._composer.addSchema(SCHEMA, 'jupyterlab-plugin-schema');
         this._validator.addSchema(SCHEMA, 'jupyterlab-plugin-schema');
     }
@@ -55,7 +69,7 @@ export class DefaultSchemaValidator {
                 const keyword = 'schema';
                 const message = `Setting registry schemas' root-level type must be ` +
                     `'object', rejecting type: ${plugin.schema.type}`;
-                return [{ dataPath: 'type', keyword, schemaPath: '', message }];
+                return [{ instancePath: 'type', keyword, schemaPath: '', message }];
             }
             const errors = this._addSchema(plugin.id, plugin.schema);
             return errors || this.validateData(plugin);
@@ -69,7 +83,7 @@ export class DefaultSchemaValidator {
             if (error instanceof SyntaxError) {
                 return [
                     {
-                        dataPath: '',
+                        instancePath: '',
                         keyword: 'syntax',
                         schemaPath: '',
                         message: error.message
@@ -80,7 +94,7 @@ export class DefaultSchemaValidator {
             const line = error.lineNumber;
             return [
                 {
-                    dataPath: '',
+                    instancePath: '',
                     keyword: 'parse',
                     schemaPath: '',
                     message: `${description} (line ${line} column ${column})`
@@ -226,7 +240,7 @@ export class SettingRegistry {
         if (fetched === undefined) {
             throw [
                 {
-                    dataPath: '',
+                    instancePath: '',
                     keyword: 'id',
                     message: `Could not fetch settings for ${plugin}.`,
                     schemaPath: ''
@@ -281,7 +295,10 @@ export class SettingRegistry {
         }
         // Parse the raw JSON string removing all comments and return an object.
         const raw = json5.parse(plugins[plugin].raw);
-        plugins[plugin].raw = Private.annotatedPlugin(plugins[plugin], Object.assign(Object.assign({}, raw), { [key]: value }));
+        plugins[plugin].raw = Private.annotatedPlugin(plugins[plugin], {
+            ...raw,
+            [key]: value
+        });
         return this._save(plugin);
     }
     /**
@@ -305,7 +322,9 @@ export class SettingRegistry {
     transform(plugin, transforms) {
         const transformers = this._transformers;
         if (plugin in transformers) {
-            throw new Error(`${plugin} already has a transformer.`);
+            const error = new Error(`${plugin} already has a transformer.`);
+            error.name = 'TransformError';
+            throw error;
         }
         transformers[plugin] = {
             fetch: transforms.fetch || (plugin => plugin),
@@ -347,9 +366,9 @@ export class SettingRegistry {
         catch (errors) {
             const output = [`Validating ${plugin} failed:`];
             errors.forEach((error, index) => {
-                const { dataPath, schemaPath, keyword, message } = error;
-                if (dataPath || schemaPath) {
-                    output.push(`${index} - schema @ ${schemaPath}, data @ ${dataPath}`);
+                const { instancePath, schemaPath, keyword, message } = error;
+                if (instancePath || schemaPath) {
+                    output.push(`${index} - schema @ ${schemaPath}, data @ ${instancePath}`);
                 }
                 output.push(`{${keyword}} ${message}`);
             });
@@ -396,7 +415,7 @@ export class SettingRegistry {
         if (fetched === undefined) {
             throw [
                 {
-                    dataPath: '',
+                    instancePath: '',
                     keyword: 'id',
                     message: `Could not fetch settings for ${plugin}.`,
                     schemaPath: ''
@@ -422,7 +441,7 @@ export class SettingRegistry {
             if (transformed.id !== id) {
                 throw [
                     {
-                        dataPath: '',
+                        instancePath: '',
                         keyword: 'id',
                         message: 'Plugin transformations cannot change plugin IDs.',
                         schemaPath: ''
@@ -442,7 +461,7 @@ export class SettingRegistry {
         }
         throw [
             {
-                dataPath: '',
+                instancePath: '',
                 keyword: 'timeout',
                 message: `Transforming ${plugin.id} timed out.`,
                 schemaPath: ''
@@ -462,14 +481,58 @@ export class SettingRegistry {
         this.plugins[plugin.id] = await this._transform('compose', plugin);
     }
 }
+/**
+ * Base settings specified by a JSON schema.
+ */
+export class BaseSettings {
+    constructor(options) {
+        this._schema = options.schema;
+    }
+    /**
+     * The plugin's schema.
+     */
+    get schema() {
+        return this._schema;
+    }
+    /**
+     * Checks if any fields are different from the default value.
+     */
+    isDefault(user) {
+        for (const key in this.schema.properties) {
+            const value = user[key];
+            const defaultValue = this.default(key);
+            if (value === undefined ||
+                defaultValue === undefined ||
+                JSONExt.deepEqual(value, JSONExt.emptyObject) ||
+                JSONExt.deepEqual(value, JSONExt.emptyArray)) {
+                continue;
+            }
+            if (!JSONExt.deepEqual(value, defaultValue)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Calculate the default value of a setting by iterating through the schema.
+     *
+     * @param key - The name of the setting whose default value is calculated.
+     *
+     * @returns A calculated default JSON value for a specific setting.
+     */
+    default(key) {
+        return Private.reifyDefault(this.schema, key);
+    }
+}
 /**
  * A manager for a specific plugin's settings.
  */
-export class Settings {
+export class Settings extends BaseSettings {
     /**
      * Instantiate a new plugin settings manager.
      */
     constructor(options) {
+        super({ schema: options.plugin.schema });
         this._changed = new Signal(this);
         this._isDisposed = false;
         this.id = options.plugin.id;
@@ -497,12 +560,6 @@ export class Settings {
     get plugin() {
         return this.registry.plugins[this.id];
     }
-    /**
-     * The plugin's schema.
-     */
-    get schema() {
-        return this.plugin.schema;
-    }
     /**
      * The plugin settings raw text value.
      */
@@ -510,24 +567,8 @@ export class Settings {
         return this.plugin.raw;
     }
     /**
-     * Checks if any fields are different from the default value.
+     * Whether the settings have been modified by the user or not.
      */
-    isDefault(user) {
-        for (const key in this.schema.properties) {
-            const value = user[key];
-            const defaultValue = this.default(key);
-            if (value === undefined ||
-                defaultValue === undefined ||
-                JSONExt.deepEqual(value, JSONExt.emptyObject) ||
-                JSONExt.deepEqual(value, JSONExt.emptyArray)) {
-                continue;
-            }
-            if (!JSONExt.deepEqual(value, defaultValue)) {
-                return false;
-            }
-        }
-        return true;
-    }
     get isModified() {
         return !this.isDefault(this.user);
     }
@@ -549,16 +590,6 @@ export class Settings {
     annotatedDefaults() {
         return Private.annotatedDefaults(this.schema, this.id);
     }
-    /**
-     * Calculate the default value of a setting by iterating through the schema.
-     *
-     * @param key - The name of the setting whose default value is calculated.
-     *
-     * @returns A calculated default JSON value for a specific setting.
-     */
-    default(key) {
-        return Private.reifyDefault(this.schema, key);
-    }
     /**
      * Dispose of the plugin settings resources.
      */
@@ -667,7 +698,11 @@ export class Settings {
         addition.forEach(menu => {
             const refIndex = merged.findIndex(ref => ref.id === menu.id);
             if (refIndex >= 0) {
-                merged[refIndex] = Object.assign(Object.assign(Object.assign({}, merged[refIndex]), menu), { items: reconcileItems(merged[refIndex].items, menu.items, warn, addNewItems) });
+                merged[refIndex] = {
+                    ...merged[refIndex],
+                    ...menu,
+                    items: reconcileItems(merged[refIndex].items, menu.items, warn, addNewItems)
+                };
             }
             else {
                 if (addNewItems) {
@@ -700,7 +735,7 @@ export class Settings {
             switch ((_a = item.type) !== null && _a !== void 0 ? _a : 'command') {
                 case 'separator':
                     if (addNewItems) {
-                        items.push(Object.assign({}, item));
+                        items.push({ ...item });
                     }
                     break;
                 case 'submenu':
@@ -712,9 +747,13 @@ export class Settings {
                             }
                         }
                         else {
-                            items[refIndex] = Object.assign(Object.assign(Object.assign({}, items[refIndex]), item), { submenu: reconcileMenus(items[refIndex].submenu
+                            items[refIndex] = {
+                                ...items[refIndex],
+                                ...item,
+                                submenu: reconcileMenus(items[refIndex].submenu
                                     ? [items[refIndex].submenu]
-                                    : null, [item.submenu], warn, addNewItems)[0] });
+                                    : null, [item.submenu], warn, addNewItems)[0]
+                            };
                         }
                     }
                     break;
@@ -728,14 +767,14 @@ export class Settings {
                         });
                         if (refIndex < 0) {
                             if (addNewItems) {
-                                items.push(Object.assign({}, item));
+                                items.push({ ...item });
                             }
                         }
                         else {
                             if (warn) {
                                 console.warn(`Menu entry for command '${item.command}' is duplicated.`);
                             }
-                            items[refIndex] = Object.assign(Object.assign({}, items[refIndex]), item);
+                            items[refIndex] = { ...items[refIndex], ...item };
                         }
                     }
             }
@@ -752,12 +791,15 @@ export class Settings {
     function filterDisabledItems(items) {
         return items.reduce((final, value) => {
             var _a;
-            const copy = Object.assign({}, value);
+            const copy = { ...value };
             if (!copy.disabled) {
                 if (copy.type === 'submenu') {
                     const { submenu } = copy;
                     if (submenu && !submenu.disabled) {
-                        copy.submenu = Object.assign(Object.assign({}, submenu), { items: filterDisabledItems((_a = submenu.items) !== null && _a !== void 0 ? _a : []) });
+                        copy.submenu = {
+                            ...submenu,
+                            items: filterDisabledItems((_a = submenu.items) !== null && _a !== void 0 ? _a : [])
+                        };
                     }
                 }
                 final.push(copy);
@@ -829,7 +871,7 @@ export class Settings {
             .filter(shortcut => !shortcut.disabled)
             // Fix shortcuts comparison in rjsf Form to avoid polluting the user settings
             .map(shortcut => {
-            return Object.assign({ args: {} }, shortcut);
+            return { args: {}, ...shortcut };
         }));
     }
     SettingRegistry.reconcileShortcuts = reconcileShortcuts;
@@ -851,39 +893,17 @@ export class Settings {
         const items = JSONExt.deepCopy(reference);
         // Merge array element depending on the type
         addition.forEach(item => {
-            switch (item.type) {
-                case 'command':
-                    if (item.command) {
-                        const refIndex = items.findIndex(ref => {
-                            var _a, _b;
-                            return ref.name === item.name &&
-                                ref.command === item.command &&
-                                JSONExt.deepEqual((_a = ref.args) !== null && _a !== void 0 ? _a : {}, (_b = item.args) !== null && _b !== void 0 ? _b : {});
-                        });
-                        if (refIndex < 0) {
-                            items.push(Object.assign({}, item));
-                        }
-                        else {
-                            if (warn) {
-                                console.warn(`Toolbar item for command '${item.command}' is duplicated.`);
-                            }
-                            items[refIndex] = Object.assign(Object.assign({}, items[refIndex]), item);
-                        }
-                    }
-                    break;
-                case 'spacer':
-                default: {
-                    const refIndex = items.findIndex(ref => ref.name === item.name);
-                    if (refIndex < 0) {
-                        items.push(Object.assign({}, item));
-                    }
-                    else {
-                        if (warn) {
-                            console.warn(`Toolbar item '${item.name}' is duplicated.`);
-                        }
-                        items[refIndex] = Object.assign(Object.assign({}, items[refIndex]), item);
-                    }
+            // Name must be unique so it's sufficient to only compare it
+            const refIndex = items.findIndex(ref => ref.name === item.name);
+            if (refIndex < 0) {
+                items.push({ ...item });
+            }
+            else {
+                if (warn &&
+                    JSONExt.deepEqual(Object.keys(item), Object.keys(items[refIndex]))) {
+                    console.warn(`Toolbar item '${item.name}' is duplicated.`);
                 }
+                items[refIndex] = { ...items[refIndex], ...item };
             }
         });
         return items;
@@ -999,9 +1019,9 @@ var Private;
     /**
      * Create a fully extrapolated default value for a root key in a schema.
      */
-    function reifyDefault(schema, root) {
-        var _a, _b, _c;
-        const definitions = schema.definitions;
+    function reifyDefault(schema, root, definitions) {
+        var _a, _b, _c, _d;
+        definitions = definitions !== null && definitions !== void 0 ? definitions : schema.definitions;
         // If the property is at the root level, traverse its schema.
         schema = (root ? (_a = schema.properties) === null || _a === void 0 ? void 0 : _a[root] : schema) || {};
         if (schema.type === 'object') {
@@ -1010,7 +1030,7 @@ var Private;
             // Iterate through and populate each child property.
             const props = schema.properties || {};
             for (const property in props) {
-                result[property] = reifyDefault(props[property]);
+                result[property] = reifyDefault(props[property], undefined, definitions);
             }
             return result;
         }
@@ -1027,9 +1047,9 @@ var Private;
             // Iterate through the items in the array and fill in defaults
             for (const item in result) {
                 // Use the values that are hard-coded in the default array over the defaults for each field.
-                const reified = reifyDefault(props) || {};
+                const reified = (_c = reifyDefault(props, undefined, definitions)) !== null && _c !== void 0 ? _c : {};
                 for (const prop in reified) {
-                    if ((_c = result[item]) === null || _c === void 0 ? void 0 : _c[prop]) {
+                    if ((_d = result[item]) === null || _d === void 0 ? void 0 : _d[prop]) {
                         reified[prop] = result[item][prop];
                     }
                 }