@jupyterlab/settingeditor 4.0.0-alpha.2 → 4.0.0-alpha.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyterlab/settingeditor",
-  "version": "4.0.0-alpha.2",
+  "version": "4.0.0-alpha.21",
   "description": "The JupyterLab default setting editor interface",
   "homepage": "https://github.com/jupyterlab/jupyterlab",
   "bugs": {
@@ -27,7 +27,8 @@
     "lib/*.js.map",
     "lib/*.js",
     "style/*.css",
-    "style/index.js"
+    "style/index.js",
+    "src/**/*.{ts,tsx}"
   ],
   "scripts": {
     "build": "tsc -b",
@@ -36,28 +37,34 @@
     "watch": "tsc -b --watch"
   },
   "dependencies": {
-    "@jupyterlab/apputils": "^4.0.0-alpha.2",
-    "@jupyterlab/codeeditor": "^4.0.0-alpha.2",
-    "@jupyterlab/inspector": "^4.0.0-alpha.2",
-    "@jupyterlab/rendermime": "^4.0.0-alpha.2",
-    "@jupyterlab/settingregistry": "^4.0.0-alpha.2",
-    "@jupyterlab/statedb": "^4.0.0-alpha.2",
-    "@jupyterlab/translation": "^4.0.0-alpha.2",
-    "@jupyterlab/ui-components": "^4.0.0-alpha.17",
-    "@lumino/commands": "^1.19.0",
-    "@lumino/coreutils": "^1.11.1",
-    "@lumino/messaging": "^1.10.1",
-    "@lumino/signaling": "^1.10.1",
-    "@lumino/widgets": "^1.30.0",
-    "react": "^17.0.1",
-    "react-dom": "^17.0.1"
+    "@jupyterlab/application": "^4.0.0-alpha.21",
+    "@jupyterlab/apputils": "^4.0.0-alpha.21",
+    "@jupyterlab/codeeditor": "^4.0.0-alpha.21",
+    "@jupyterlab/inspector": "^4.0.0-alpha.21",
+    "@jupyterlab/rendermime": "^4.0.0-alpha.21",
+    "@jupyterlab/settingregistry": "^4.0.0-alpha.21",
+    "@jupyterlab/statedb": "^4.0.0-alpha.21",
+    "@jupyterlab/translation": "^4.0.0-alpha.21",
+    "@jupyterlab/ui-components": "^4.0.0-alpha.36",
+    "@lumino/algorithm": "^2.0.0-rc.1",
+    "@lumino/commands": "^2.0.0-rc.1",
+    "@lumino/coreutils": "^2.0.0-rc.1",
+    "@lumino/disposable": "^2.0.0-rc.1",
+    "@lumino/messaging": "^2.0.0-rc.1",
+    "@lumino/polling": "^2.0.0-rc.1",
+    "@lumino/signaling": "^2.0.0-rc.1",
+    "@lumino/widgets": "^2.0.0-rc.1",
+    "@rjsf/core": "^5.1.0",
+    "@rjsf/utils": "^5.1.0",
+    "@rjsf/validator-ajv8": "^5.1.0",
+    "json-schema": "^0.4.0",
+    "react": "^18.2.0"
   },
   "devDependencies": {
-    "@types/react": "^17.0.0",
-    "@types/react-dom": "^17.0.0",
+    "@types/react": "^18.0.26",
     "rimraf": "~3.0.0",
-    "typedoc": "~0.21.2",
-    "typescript": "~4.5.2"
+    "typedoc": "~0.23.25",
+    "typescript": "~5.0.1-rc"
   },
   "publishConfig": {
     "access": "public"

package/src/SettingsFormEditor.tsx

@@ -0,0 +1,306 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+
+import { showErrorMessage } from '@jupyterlab/apputils';
+import { ISettingRegistry, Settings } from '@jupyterlab/settingregistry';
+import { ITranslator } from '@jupyterlab/translation';
+import {
+  caretDownIcon,
+  caretRightIcon,
+  FormComponent
+} from '@jupyterlab/ui-components';
+import { JSONExt, ReadonlyPartialJSONObject } from '@lumino/coreutils';
+import { Debouncer } from '@lumino/polling';
+import { IChangeEvent } from '@rjsf/core';
+import validatorAjv8 from '@rjsf/validator-ajv8';
+import { Field, UiSchema } from '@rjsf/utils';
+import { JSONSchema7 } from 'json-schema';
+import React from 'react';
+
+/**
+ * Indentation to use when saving the settings as JSON document.
+ */
+const JSON_INDENTATION = 4;
+
+/**
+ * Namespace for a React component that prepares the settings for a
+ * given plugin to be rendered in the FormEditor.
+ */
+export namespace SettingsFormEditor {
+  /**
+   * Props passed to the SettingsFormEditor component
+   */
+  export interface IProps {
+    /**
+     * Settings object with schema and user defined values.
+     */
+    settings: Settings;
+
+    /**
+     * Dictionary used for custom field renderers in the form.
+     */
+    renderers: { [id: string]: { [property: string]: Field } };
+
+    /**
+     * Whether the form is collapsed or not.
+     */
+    isCollapsed: boolean;
+
+    /**
+     * Callback with the collapse state value.
+     */
+    onCollapseChange: (v: boolean) => void;
+
+    /**
+     * Translator object
+     */
+    translator: ITranslator;
+
+    /**
+     * Callback to update the plugin list when a validation error occurs.
+     */
+    hasError: (error: boolean) => void;
+
+    /**
+     * Handler for when selection change is triggered by scrolling
+     * in the SettingsPanel.
+     */
+    onSelect: (id: string) => void;
+
+    /**
+     * Sends whether this editor has unsaved changes to the parent class.
+     */
+    updateDirtyState: (dirty: boolean) => void;
+
+    /**
+     * List of strings that match search value.
+     */
+    filteredValues: string[] | null;
+  }
+
+  export interface IState {
+    /**
+     * Indicates whether the settings have been modified. Used for hiding
+     * the "Restore to Default" button when there are no changes.
+     */
+    isModified: boolean;
+
+    // The following are state derived from props for memoization to avoid
+    // `Form` update that results in focus lost
+    // A better fix (that will break the API) would be to move this as props
+    // of the component
+    /**
+     * Form UI schema
+     */
+    uiSchema: UiSchema;
+    /**
+     * Filtered schema
+     */
+    filteredSchema?: ISettingRegistry.ISchema;
+    /**
+     * Form context
+     */
+    formContext?: any;
+  }
+}
+
+/**
+ * A React component that prepares the settings for a
+ * given plugin to be rendered in the FormEditor.
+ */
+export class SettingsFormEditor extends React.Component<
+  SettingsFormEditor.IProps,
+  SettingsFormEditor.IState
+> {
+  constructor(props: SettingsFormEditor.IProps) {
+    super(props);
+    const { settings } = props;
+    this._formData = settings.composite;
+    this.state = {
+      isModified: settings.isModified,
+      uiSchema: {},
+      filteredSchema: this.props.settings.schema,
+      formContext: {
+        defaultFormData: this.props.settings.default(),
+        settings: this.props.settings
+      }
+    };
+    this.handleChange = this.handleChange.bind(this);
+    this._debouncer = new Debouncer(this.handleChange);
+  }
+
+  componentDidMount(): void {
+    this._setUiSchema();
+    this._setFilteredSchema();
+  }
+
+  componentDidUpdate(prevProps: SettingsFormEditor.IProps): void {
+    this._setUiSchema(prevProps.renderers[prevProps.settings.id]);
+    this._setFilteredSchema(prevProps.filteredValues);
+
+    if (prevProps.settings !== this.props.settings) {
+      this.setState({
+        formContext: {
+          settings: this.props.settings,
+          defaultFormData: this.props.settings.default()
+        }
+      });
+    }
+  }
+
+  componentWillUnmount(): void {
+    this._debouncer.dispose();
+  }
+
+  /**
+   * Handler for edits made in the form editor.
+   */
+  handleChange(): void {
+    // Prevent unnecessary save when opening settings that haven't been modified.
+    if (
+      !this.props.settings.isModified &&
+      this.props.settings.isDefault(this._formData)
+    ) {
+      this.props.updateDirtyState(false);
+      return;
+    }
+    this.props.settings
+      .save(JSON.stringify(this._formData, undefined, JSON_INDENTATION))
+      .then(() => {
+        this.props.updateDirtyState(false);
+        this.setState({ isModified: this.props.settings.isModified });
+      })
+      .catch((reason: string) => {
+        this.props.updateDirtyState(false);
+        const trans = this.props.translator.load('jupyterlab');
+        void showErrorMessage(trans.__('Error saving settings.'), reason);
+      });
+  }
+
+  /**
+   * Handler for the "Restore to defaults" button - clears all
+   * modified settings then calls `setFormData` to restore the
+   * values.
+   */
+  reset = async (event: React.MouseEvent): Promise<void> => {
+    event.stopPropagation();
+    for (const field in this.props.settings.user) {
+      await this.props.settings.remove(field);
+    }
+    this._formData = this.props.settings.composite;
+    this.setState({ isModified: false });
+  };
+
+  render(): JSX.Element {
+    const trans = this.props.translator.load('jupyterlab');
+    const icon = this.props.isCollapsed ? caretRightIcon : caretDownIcon;
+
+    return (
+      <div>
+        <div
+          className="jp-SettingsHeader"
+          onClick={() => {
+            this.props.onCollapseChange(!this.props.isCollapsed);
+            this.props.onSelect(this.props.settings.id);
+          }}
+        >
+          <header className="jp-SettingsTitle">
+            <icon.react
+              tag="span"
+              elementPosition="center"
+              className="jp-SettingsTitle-caret"
+            />
+            <h2>{this.props.settings.schema.title}</h2>
+            <div className="jp-SettingsHeader-description">
+              {this.props.settings.schema.description}
+            </div>
+          </header>
+          {this.state.isModified && (
+            <button className="jp-RestoreButton" onClick={this.reset}>
+              {trans.__('Restore to Defaults')}
+            </button>
+          )}
+        </div>
+        {!this.props.isCollapsed && (
+          <FormComponent
+            validator={validatorAjv8}
+            schema={this.state.filteredSchema as JSONSchema7}
+            formData={this._formData}
+            uiSchema={this.state.uiSchema}
+            fields={this.props.renderers[this.props.settings.id]}
+            formContext={this.state.formContext}
+            liveValidate
+            idPrefix={`jp-SettingsEditor-${this.props.settings.id}`}
+            onChange={this._onChange}
+            translator={this.props.translator}
+          />
+        )}
+      </div>
+    );
+  }
+
+  private _onChange = (e: IChangeEvent<ReadonlyPartialJSONObject>): void => {
+    this.props.hasError(e.errors.length !== 0);
+    this._formData = e.formData;
+    if (e.errors.length === 0) {
+      this.props.updateDirtyState(true);
+      void this._debouncer.invoke();
+    }
+    this.props.onSelect(this.props.settings.id);
+  };
+
+  private _setUiSchema(prevRenderers?: { [id: string]: Field }) {
+    const renderers = this.props.renderers[this.props.settings.id];
+    if (
+      !JSONExt.deepEqual(
+        Object.keys(prevRenderers ?? {}).sort(),
+        Object.keys(renderers ?? {}).sort()
+      )
+    ) {
+      /**
+       * Construct uiSchema to pass any custom renderers to the form editor.
+       */
+      const uiSchema: UiSchema = {};
+      for (const id in this.props.renderers[this.props.settings.id]) {
+        if (
+          Object.keys(this.props.settings.schema.properties ?? {}).includes(id)
+        ) {
+          uiSchema[id] = {
+            'ui:field': id
+          };
+        }
+      }
+      this.setState({ uiSchema });
+    }
+  }
+
+  private _setFilteredSchema(prevFilteredValues?: string[] | null) {
+    if (
+      prevFilteredValues === undefined ||
+      !JSONExt.deepEqual(prevFilteredValues, this.props.filteredValues)
+    ) {
+      /**
+       * Only show fields that match search value.
+       */
+      const filteredSchema = JSONExt.deepCopy(this.props.settings.schema);
+      if (this.props.filteredValues?.length ?? 0 > 0) {
+        for (const field in filteredSchema.properties) {
+          if (
+            !this.props.filteredValues?.includes(
+              filteredSchema.properties[field].title ?? field
+            )
+          ) {
+            delete filteredSchema.properties[field];
+          }
+        }
+      }
+
+      this.setState({ filteredSchema });
+    }
+  }
+
+  private _debouncer: Debouncer<void, any>;
+  private _formData: any;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * @packageDocumentation
+ * @module settingeditor
+ */
+
+export * from './settingseditor';
+export * from './jsonsettingeditor';
+export * from './tokens';

package/src/inspector.ts

@@ -0,0 +1,144 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+
+import { InspectionHandler, InspectorPanel } from '@jupyterlab/inspector';
+import {
+  IRenderMimeRegistry,
+  RenderMimeRegistry,
+  standardRendererFactories
+} from '@jupyterlab/rendermime';
+import { ISchemaValidator } from '@jupyterlab/settingregistry';
+import { DataConnector } from '@jupyterlab/statedb';
+import {
+  ITranslator,
+  nullTranslator,
+  TranslationBundle
+} from '@jupyterlab/translation';
+import { ReadonlyJSONObject } from '@lumino/coreutils';
+import { RawEditor } from './raweditor';
+
+/**
+ * Create a raw editor inspector.
+ */
+export function createInspector(
+  editor: RawEditor,
+  rendermime?: IRenderMimeRegistry,
+  translator?: ITranslator
+): InspectorPanel {
+  translator = translator || nullTranslator;
+  const trans = translator.load('jupyterlab');
+  const connector = new InspectorConnector(editor, translator);
+  const inspector = new InspectorPanel({
+    initialContent: trans.__('Any errors will be listed here'),
+    translator: translator
+  });
+  const handler = new InspectionHandler({
+    connector,
+    rendermime:
+      rendermime ||
+      new RenderMimeRegistry({
+        initialFactories: standardRendererFactories,
+        translator: translator
+      })
+  });
+
+  inspector.addClass('jp-SettingsDebug');
+  inspector.source = handler;
+  handler.editor = editor.source;
+
+  return inspector;
+}
+
+/**
+ * The data connector used to populate a code inspector.
+ *
+ * #### Notes
+ * This data connector debounces fetch requests to throttle them at no more than
+ * one request per 100ms. This means that using the connector to populate
+ * multiple client objects can lead to missed fetch responses.
+ */
+class InspectorConnector extends DataConnector<
+  InspectionHandler.IReply,
+  void,
+  InspectionHandler.IRequest
+> {
+  constructor(editor: RawEditor, translator?: ITranslator) {
+    super();
+    this._editor = editor;
+    this._trans = (translator ?? nullTranslator).load('jupyterlab');
+  }
+
+  /**
+   * Fetch inspection requests.
+   */
+  fetch(
+    request: InspectionHandler.IRequest
+  ): Promise<InspectionHandler.IReply | undefined> {
+    return new Promise<InspectionHandler.IReply | undefined>(resolve => {
+      // Debounce requests at a rate of 100ms.
+      const current = (this._current = window.setTimeout(() => {
+        if (current !== this._current) {
+          return resolve(undefined);
+        }
+
+        const errors = this._validate(request.text);
+
+        if (!errors) {
+          return resolve({
+            data: { 'text/markdown': this._trans.__('No errors found') },
+            metadata: {}
+          });
+        }
+
+        resolve({ data: this.render(errors), metadata: {} });
+      }, 100));
+    });
+  }
+  /**
+   * Render validation errors as an HTML string.
+   */
+  protected render(errors: ISchemaValidator.IError[]): ReadonlyJSONObject {
+    return {
+      'text/markdown': errors.map(this.renderError.bind(this)).join('')
+    };
+  }
+
+  /**
+   * Render an individual validation error as a markdown string.
+   */
+  protected renderError(error: ISchemaValidator.IError): string {
+    switch (error.keyword) {
+      case 'additionalProperties':
+        return `**\`[${this._trans.__('additional property error')}]\`**
+          ${this._trans.__(
+            '`%1` is not a valid property',
+            error.params?.additionalProperty
+          )}`;
+      case 'syntax':
+        return `**\`[${this._trans.__('syntax error')}]\`** *${error.message}*`;
+      case 'type':
+        return `**\`[${this._trans.__('type error')}]\`**
+          \`${error.instancePath}\` ${error.message}`;
+      default:
+        return `**\`[${this._trans.__('error')}]\`** *${error.message}*`;
+    }
+  }
+
+  private _validate(raw: string): ISchemaValidator.IError[] | null {
+    const editor = this._editor;
+    if (!editor.settings) {
+      return null;
+    }
+    const { id, schema, version } = editor.settings;
+    const data = { composite: {}, user: {} };
+    const validator = editor.registry.validator;
+
+    return validator.validateData({ data, id, raw, schema, version }, false);
+  }
+
+  private _trans: TranslationBundle;
+  private _current = 0;
+  private _editor: RawEditor;
+}