Improve form renderer registry (jupyterlab#13823)

* Use `pluginId.propertyName` as key for form renderers
Rename to use _renderer_ instead of _component_ as it is a more common wording in Lumino/Lab code base.

* Update migration guide

* Fix computing default for metadataform

* Fix rst syntax

* Remove `settings` from `FormContext`

Co-authored-by: Nicolas Brichet <[email protected]>

* Rename `customComponent` in `customRenderer`

* Drop `MetadataForm.ISettings`

Co-authored-by: Nicolas Brichet <[email protected]>

Author: fcollonval

docs/source/extension/extension_migration.rst

@@ -176,14 +176,17 @@ bumped their major version (following semver convention). We want to point out p
      need to switch to the Blueprint components as the interfaces of those components in JupyterLab
      do not match those of Blueprint JS.
    * Remove ``Collapse`` React component.
-   * Change the ``IFormComponentRegistry`` token, from ``@jupyterlab/ui-components:ISettingEditorRegistry`` to
-     ``@jupyterlab/ui-components:IFormComponentRegistry``.
-   * The ``FormComponentRegistry`` registers ``FormComponent`` instead of field renderers.
-     The methods have been renamed from ``...renderer``  to ``...component``. For example, ``addRenderer`` is now ``addComponent``.
-     A ``FormComponent`` defines a ``fieldRenderer`` or a ``widgetRenderer``.
+   * Form component registry changes:
+      - Rename the plugin ``'@jupyterlab/ui-components-extension:form-component-registry'`` to ``'@jupyterlab/ui-components-extension:form-renderer-registry'``
+      - Rename the ``IFormComponentRegistry`` token to ``IFormRendererRegistry``, from ``@jupyterlab/ui-components:ISettingEditorRegistry``
+        to ``@jupyterlab/ui-components:IFormRendererRegistry``.
+      - The ``FormRendererRegistry`` registers ``IFormRenderer`` instead of ``Field`` renderers.
+        A ``IFormRenderer`` defines a ``fieldRenderer`` (this is the renderer to set for backward compatibility)
+        or a ``widgetRenderer``.
+        The renderer id must follow the convention ``<ISettingRegistry.IPlugin.id>.<propertyName>``. This is to
+        ensure a custom renderer is not used for property with the same name but different schema.
 - ``@jupyterlab/translation`` from 3.x to 4.x
    Renamed the method ``locale`` into the property ``languageCode`` in the ``NullTranslator``
-
 - ``jupyter.extensions.hub-extension`` from 3.x to 4.x
    * Renamed ``jupyter.extensions.hub-extension`` to ``@jupyterlab/hub-extension:plugin``.
    * Renamed ``jupyter.extensions.hub-extension:plugin`` to ``@jupyterlab/hub-extension:menu``.

packages/completer-extension/src/index.ts

@@ -17,8 +17,8 @@ import {
 } from '@jupyterlab/completer';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import {
-  IFormComponent,
-  IFormComponentRegistry
+  IFormRenderer,
+  IFormRendererRegistry
 } from '@jupyterlab/ui-components';
 import type { FieldProps } from '@rjsf/core';
 
@@ -42,13 +42,13 @@ const defaultProvider: JupyterFrontEndPlugin<void> = {
 const manager: JupyterFrontEndPlugin<ICompletionProviderManager> = {
   id: COMPLETION_MANAGER_PLUGIN,
   requires: [ISettingRegistry],
-  optional: [IFormComponentRegistry],
+  optional: [IFormRendererRegistry],
   provides: ICompletionProviderManager,
   autoStart: true,
   activate: (
     app: JupyterFrontEnd,
     settings: ISettingRegistry,
-    editorRegistry: IFormComponentRegistry | null
+    editorRegistry: IFormRendererRegistry | null
   ): ICompletionProviderManager => {
     const AVAILABLE_PROVIDERS = 'availableProviders';
     const PROVIDER_TIMEOUT = 'providerTimeout';
@@ -101,12 +101,15 @@ const manager: JupyterFrontEndPlugin<ICompletionProviderManager> = {
       .catch(console.error);
 
     if (editorRegistry) {
-      const component: IFormComponent = {
+      const renderer: IFormRenderer = {
         fieldRenderer: (props: FieldProps) => {
           return renderAvailableProviders(props);
         }
       };
-      editorRegistry.addComponent('availableProviders', component);
+      editorRegistry.addRenderer(
+        `${COMPLETION_MANAGER_PLUGIN}.availableProviders`,
+        renderer
+      );
     }
 
     return manager;

packages/lsp-extension/src/index.ts

@@ -27,8 +27,8 @@ import { IRunningSessionManagers, IRunningSessions } from '@jupyterlab/running';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { ITranslator } from '@jupyterlab/translation';
 import {
-  IFormComponent,
-  IFormComponentRegistry,
+  IFormRenderer,
+  IFormRendererRegistry,
   LabIcon,
   pythonIcon
 } from '@jupyterlab/ui-components';
@@ -42,7 +42,7 @@ const plugin: JupyterFrontEndPlugin<ILSPDocumentConnectionManager> = {
   activate,
   id: '@jupyterlab/lsp-extension:plugin',
   requires: [ISettingRegistry, ITranslator],
-  optional: [IRunningSessionManagers, IFormComponentRegistry],
+  optional: [IRunningSessionManagers, IFormRendererRegistry],
   provides: ILSPDocumentConnectionManager,
   autoStart: true
 };
@@ -88,7 +88,7 @@ function activate(
   settingRegistry: ISettingRegistry,
   translator: ITranslator,
   runningSessionManagers: IRunningSessionManagers | null,
-  settingRendererRegistry: IFormComponentRegistry | null
+  settingRendererRegistry: IFormRendererRegistry | null
 ): ILSPDocumentConnectionManager {
   const LANGUAGE_SERVERS = 'languageServers';
   const languageServerManager = new LanguageServerManager({});
@@ -184,12 +184,15 @@ function activate(
   }
 
   if (settingRendererRegistry) {
-    const component: IFormComponent = {
+    const renderer: IFormRenderer = {
       fieldRenderer: (props: FieldProps) => {
         return renderServerSetting(props, translator);
       }
     };
-    settingRendererRegistry.addComponent(LANGUAGE_SERVERS, component);
+    settingRendererRegistry.addRenderer(
+      `${plugin.id}.${LANGUAGE_SERVERS}`,
+      renderer
+    );
   }
 
   return connectionManager;

packages/metadataform-extension/schema/metadataforms.json

@@ -75,7 +75,7 @@
     },
     "metadataOptions": {
       "properties": {
-        "customComponent": {
+        "customRenderer": {
           "type": "string"
         },
         "metadataLevel": {

packages/metadataform-extension/src/index.ts

@@ -12,7 +12,7 @@ import {
 import { INotebookTools } from '@jupyterlab/notebook';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { ITranslator } from '@jupyterlab/translation';
-import { IFormComponentRegistry } from '@jupyterlab/ui-components';
+import { IFormRendererRegistry } from '@jupyterlab/ui-components';
 import { JSONExt, PartialJSONArray } from '@lumino/coreutils';
 
 import {
@@ -30,7 +30,7 @@ namespace Private {
     registry: ISettingRegistry,
     notebookTools: INotebookTools,
     translator: ITranslator,
-    formComponentRegistry: IFormComponentRegistry
+    formComponentRegistry: IFormRendererRegistry
   ): Promise<IMetadataFormProvider> {
     let canonical: ISettingRegistry.ISchema | null;
     let loaded: { [name: string]: ISettingRegistry.IMetadataForm[] } = {};
@@ -221,9 +221,9 @@ namespace Private {
           }
 
           // Optionally links key to a custom widget.
-          if (options.customComponent) {
-            const component = formComponentRegistry.getComponent(
-              options.customComponent as string
+          if (options.customRenderer) {
+            const component = formComponentRegistry.getRenderer(
+              options.customRenderer as string
             );
 
             // If renderer is defined (custom widget has been registered), set it as used widget.
@@ -274,15 +274,15 @@ const metadataForm: JupyterFrontEndPlugin<IMetadataFormProvider> = {
   requires: [
     INotebookTools,
     ITranslator,
-    IFormComponentRegistry,
+    IFormRendererRegistry,
     ISettingRegistry
   ],
   provides: IMetadataFormProvider,
   activate: async (
     app: JupyterFrontEnd,
     notebookTools: INotebookTools,
     translator: ITranslator,
-    componentsRegistry: IFormComponentRegistry,
+    componentsRegistry: IFormRendererRegistry,
     settings: ISettingRegistry
   ): Promise<IMetadataFormProvider> => {
     return await Private.loadSettingsMetadataForm(

packages/metadataform/src/form.tsx

@@ -5,12 +5,12 @@
  * @module metadataform
  */
 
-import React from 'react';
-import Form, { IChangeEvent } from '@rjsf/core';
-import { JSONSchema7 } from 'json-schema';
-import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 import { ReactWidget } from '@jupyterlab/apputils';
-import { RJSFTemplatesFactory } from '@jupyterlab/ui-components';
+import { FormComponent } from '@jupyterlab/ui-components';
+import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
+import { IChangeEvent } from '@rjsf/core';
+import { JSONSchema7 } from 'json-schema';
+import React from 'react';
 
 import { MetadataForm } from './token';
 
@@ -25,11 +25,6 @@ export class FormWidget extends ReactWidget {
     super();
     this.addClass('jp-FormWidget');
     this._props = props;
-    this._templateFactory = new RJSFTemplatesFactory({
-      translator: this._props.translator,
-      compact: true,
-      showModifiedFromDefault: props.showModified
-    });
   }
 
   /**
@@ -38,27 +33,26 @@ export class FormWidget extends ReactWidget {
    */
   render(): JSX.Element {
     const formContext = {
-      settings: this._props.settings,
+      defaultFormData: this._props.settings.default(),
       updateMetadata: this._props.metadataFormWidget.updateMetadata
     };
     return (
-      <Form
+      <FormComponent
         schema={this._props.properties as JSONSchema7}
-        formData={this._props.formData}
+        formData={this._props.formData as Record<string, any>}
         formContext={formContext}
-        FieldTemplate={this._templateFactory.fieldTemplate}
-        ArrayFieldTemplate={this._templateFactory.arrayTemplate}
-        ObjectFieldTemplate={this._templateFactory.objectTemplate}
         uiSchema={this._props.uiSchema}
         liveValidate
         idPrefix={`jp-MetadataForm-${this._props.pluginId}`}
         onChange={(e: IChangeEvent<ReadonlyPartialJSONObject>) => {
           this._props.metadataFormWidget.updateMetadata(e.formData);
         }}
+        compact={true}
+        showModifiedFromDefault={this._props.showModified}
+        translator={this._props.translator}
       />
     );
   }
 
   private _props: MetadataForm.IProps;
-  private _templateFactory: RJSFTemplatesFactory;
 }

packages/metadataform/src/metadataform.ts

@@ -6,13 +6,16 @@
  */
 
 import { NotebookTools } from '@jupyterlab/notebook';
+import { BaseSettings } from '@jupyterlab/settingregistry';
 import {
   ITranslator,
   nullTranslator,
   TranslationBundle
 } from '@jupyterlab/translation';
 import {
   JSONExt,
+  JSONObject,
+  JSONValue,
   PartialJSONObject,
   PartialJSONValue,
   ReadonlyPartialJSONObject,
@@ -142,7 +145,10 @@ export class MetadataFormWidget
    * in metadata before performing update.
    * It uses an arrow function to allow using 'this' properly when called from a custom field.
    */
-  updateMetadata = (formData: ReadonlyPartialJSONObject, reload?: boolean) => {
+  updateMetadata = (
+    formData: ReadonlyPartialJSONObject,
+    reload?: boolean
+  ): void => {
     if (this.notebookTools == undefined) return;
 
     const notebook = this.notebookTools.activeNotebookPanel;
@@ -365,7 +371,7 @@ export class MetadataFormWidget
       this._metadataSchema
     );
 
-    const formData = {} as PartialJSONObject;
+    const formData = {} as JSONObject;
 
     for (let metadataKey of Object.keys(this._metadataSchema.properties)) {
       // Do not display the field if it's Notebook metadata and the notebook model is null.
@@ -416,12 +422,14 @@ export class MetadataFormWidget
       }
 
       // Fill the formData with the current metadata value.
-      if (hasValue) formData[metadataKey] = workingObject as PartialJSONValue;
+      if (hasValue) formData[metadataKey] = workingObject as JSONValue;
     }
 
     this.buildWidget({
       properties: formProperties,
-      settings: new Private.Settings(this._metaInformation),
+      settings: new BaseSettings({
+        schema: this._metadataSchema as PartialJSONObject
+      }),
       uiSchema: this._uiSchema,
       translator: this.translator || null,
       formData: formData,
@@ -432,7 +440,7 @@ export class MetadataFormWidget
   }
 
   protected translator: ITranslator;
-  private _form: FormWidget | undefined = undefined;
+  private _form: FormWidget | undefined;
   private _metadataSchema: MetadataForm.IMetadataSchema;
   private _metaInformation: MetadataForm.IMetaInformation;
   private _uiSchema: MetadataForm.IUiSchema;
@@ -452,24 +460,6 @@ namespace Private {
     [metadata: string]: PartialJSONObject | PartialJSONValue | undefined;
   }
 
-  /**
-   * The settings to send to RJSF templates in formContext.
-   */
-  export class Settings implements MetadataForm.ISettings {
-    constructor(metaInformation: MetadataForm.IMetaInformation) {
-      this.metaInformation = metaInformation;
-    }
-
-    /**
-     * Returns the default value for a specific key.
-     * @param metadataKey - the key for which we expect default value.
-     */
-    default(metadataKey: string) {
-      return this.metaInformation[metadataKey]?.default;
-    }
-
-    metaInformation: MetadataForm.IMetaInformation;
-  }
   /**
    * Recursive function to clean the empty nested metadata before updating real metadata.
    * this function is called when a nested metadata is undefined (or default), so maybe some

packages/metadataform/src/token.ts

@@ -7,12 +7,11 @@
 
 import { CellType } from '@jupyterlab/nbformat';
 import { NotebookTools } from '@jupyterlab/notebook';
-import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { BaseSettings, ISettingRegistry } from '@jupyterlab/settingregistry';
 import { ITranslator } from '@jupyterlab/translation';
 import {
   PartialJSONObject,
-  PartialJSONValue,
-  ReadonlyPartialJSONObject,
+  ReadonlyJSONObject,
   Token
 } from '@lumino/coreutils';
 import { MetadataFormWidget } from './metadataform';
@@ -23,22 +22,6 @@ export namespace MetadataForm {
    */
   export type IMetadataSchema = ISettingRegistry.IMetadataSchema;
 
-  /**
-   * The settings to send to RJSF templates in formContext.
-   */
-  export interface ISettings {
-    /**
-     * Returns the default value for a specific key.
-     * @param metadataKey - the key for which we expect default value.
-     */
-    default(metadataKey: string): PartialJSONValue | undefined;
-
-    /**
-     * The meta information associated to all properties.
-     */
-    metaInformation: IMetaInformation;
-  }
-
   /**
    * The meta information associated to all properties.
    */
@@ -132,12 +115,12 @@ export namespace MetadataForm {
     /**
      * Meta information associated to properties.
      */
-    settings: ISettings;
+    settings: BaseSettings;
 
     /**
      * Current data of the form.
      */
-    formData: ReadonlyPartialJSONObject | null;
+    formData: ReadonlyJSONObject;
 
     /**
      * Translator object.
@@ -178,7 +161,7 @@ export namespace MetadataForm {
      * The list contains also the conditional fields, which are not necessary
      * displayed and filled.
      */
-    get metadataKeys(): string[];
+    readonly metadataKeys: string[];
 
     /**
      * Get the properties of a MetadataKey.
@@ -205,7 +188,7 @@ export namespace MetadataForm {
      * This function build an object with all the root object to update
      * in metadata before performing update.
      */
-    updateMetadata(formData: ReadonlyPartialJSONObject, reload?: boolean): void;
+    updateMetadata(formData: ReadonlyJSONObject, reload?: boolean): void;
   }
 }