@jupyterlab/notebook-extension 4.7.0-alpha.0 → 4.7.0-alpha.2

package/src/tool-widgets/activeCellToolWidget.tsx

@@ -5,13 +5,23 @@
 
 import React from 'react';
 import type { FieldProps } from '@rjsf/utils';
+import { SystemClipboard } from '@jupyterlab/apputils';
 import type { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
+import { PageConfig } from '@jupyterlab/coreutils';
 import type { INotebookTracker } from '@jupyterlab/notebook';
 import { NotebookTools } from '@jupyterlab/notebook';
 import type { ISharedText } from '@jupyter/ydoc';
 import { PanelLayout, Widget } from '@lumino/widgets';
-import type { CodeCellModel, ICellModel } from '@jupyterlab/cells';
-import { InputPrompt } from '@jupyterlab/cells';
+import type { ICellModel } from '@jupyterlab/cells';
+import { InputPrompt, isCodeCellModel } from '@jupyterlab/cells';
+import type { ITranslator } from '@jupyterlab/translation';
+import { nullTranslator } from '@jupyterlab/translation';
+import {
+  checkIcon,
+  copyIcon,
+  linkIcon,
+  ToolbarButtonComponent
+} from '@jupyterlab/ui-components';
 import { Debouncer } from '@lumino/polling';
 
 /**
@@ -27,6 +37,25 @@ const ACTIVE_CELL_TOOL_CONTENT_CLASS = 'jp-ActiveCellTool-Content';
  */
 const ACTIVE_CELL_TOOL_CELL_CONTENT_CLASS = 'jp-ActiveCellTool-CellContent';
 
+/**
+ * The class name added to the cell ID field.
+ */
+const CELL_ID_FIELD_CLASS = 'jp-CellIdField';
+
+type CopiedAction = 'id' | 'link';
+
+interface ICellIdFieldProps extends FieldProps {
+  /**
+   * The tracker to the notebook panel.
+   */
+  tracker: INotebookTracker;
+
+  /**
+   * Language translator.
+   */
+  translator?: ITranslator;
+}
+
 namespace Private {
   /**
    * Custom active cell field options.
@@ -44,17 +73,138 @@ namespace Private {
   }
 }
 
+/**
+ * The cell ID field, displaying the ID of the active cell.
+ *
+ * ## Note
+ * This field does not work as other metadata form fields, as it does not update metadata.
+ */
+export function CellIdField(props: ICellIdFieldProps): JSX.Element {
+  const translator = props.translator ?? nullTranslator;
+  const trans = translator.load('jupyterlab');
+  const title = props.schema.title ?? trans.__('Cell ID');
+  const activeCellId = props.tracker.activeCell?.model.id ?? '';
+  const [copiedAction, setCopiedAction] = React.useState<CopiedAction | null>(
+    null
+  );
+  const copiedTimeout = React.useRef<number | null>(null);
+
+  React.useEffect(() => {
+    setCopiedAction(null);
+  }, [activeCellId]);
+
+  React.useEffect(() => {
+    return () => {
+      if (copiedTimeout.current !== null) {
+        window.clearTimeout(copiedTimeout.current);
+      }
+    };
+  }, []);
+
+  const showCopied = (action: CopiedAction) => {
+    setCopiedAction(action);
+    if (copiedTimeout.current !== null) {
+      window.clearTimeout(copiedTimeout.current);
+    }
+    copiedTimeout.current = window.setTimeout(() => {
+      setCopiedAction(null);
+      copiedTimeout.current = null;
+    }, 1400);
+  };
+
+  const onCopyId = () => {
+    if (!activeCellId) {
+      return;
+    }
+    void SystemClipboard.getInstance()
+      .setData('text/plain', activeCellId)
+      .then(() => showCopied('id'));
+  };
+
+  const onCopyLink = () => {
+    const notebookPanel = props.tracker.currentWidget;
+    const activeCell = props.tracker.activeCell;
+    if (!notebookPanel || !activeCell) {
+      return;
+    }
+
+    const url = PageConfig.getUrl({
+      workspace: PageConfig.defaultWorkspace,
+      treePath: notebookPanel.context.path,
+      toShare: true
+    });
+    void SystemClipboard.getInstance()
+      .setData(
+        'text/plain',
+        `${url}#cell-id=${encodeURIComponent(activeCell.model.id)}`
+      )
+      .then(() => showCopied('link'));
+  };
+
+  return (
+    <div className={CELL_ID_FIELD_CLASS}>
+      <label htmlFor={props.idSchema.$id}>{title}</label>
+      <div className="jp-CellIdField-row">
+        <input
+          className="jp-mod-styled jp-CellIdField-input"
+          id={props.idSchema.$id}
+          readOnly
+          type="text"
+          value={activeCellId}
+        />
+        <ToolbarButtonComponent
+          className={`jp-CellIdField-button ${
+            copiedAction === 'id' ? 'jp-mod-copied' : ''
+          }`}
+          enabled={!!activeCellId}
+          icon={copiedAction === 'id' ? checkIcon : copyIcon}
+          iconLabel={trans.__('Copy cell ID')}
+          onClick={onCopyId}
+          tooltip={
+            copiedAction === 'id'
+              ? trans.__('Copied')
+              : trans.__('Copy cell ID')
+          }
+        />
+        <ToolbarButtonComponent
+          className={`jp-CellIdField-button ${
+            copiedAction === 'link' ? 'jp-mod-copied' : ''
+          }`}
+          enabled={!!activeCellId}
+          icon={copiedAction === 'link' ? checkIcon : linkIcon}
+          iconLabel={trans.__('Copy link to cell')}
+          onClick={onCopyLink}
+          tooltip={
+            copiedAction === 'link'
+              ? trans.__('Copied')
+              : trans.__('Copy link to cell')
+          }
+        />
+      </div>
+    </div>
+  );
+}
+
 /**
  * The active cell field, displaying the first line and execution count of the active cell.
  *
  * ## Note
  * This field does not work as other metadata form fields, as it does not update metadata.
+ *
+ * A single instance is meant to be shared by every render of the field. The
+ * displayed cell follows the notebook tracker rather than the render calls, so
+ * that the field keeps working when the metadata form is not being rebuilt, and
+ * so that it does not hold on to a cell model of a closed notebook.
+ *
+ * One instance owns one node, so the field can only be mounted in one place at
+ * a time: `render` moves the node to the most recent mount point and leaves any
+ * earlier one empty. Nothing renders this field twice today.
  */
 export class ActiveCellTool extends NotebookTools.Tool {
   constructor(options: Private.IOptions) {
     super();
-    const { languages } = options;
     this._tracker = options.tracker;
+    this._languages = options.languages;
 
     this.addClass(ACTIVE_CELL_TOOL_CLASS);
     this.layout = new PanelLayout();
@@ -71,51 +221,191 @@ export class ActiveCellTool extends NotebookTools.Tool {
     this._editorEl = editor;
     (this.layout as PanelLayout).addWidget(new Widget({ node }));
 
-    const update = async () => {
-      this._editorEl.innerHTML = '';
-      if (this._cellModel?.type === 'code') {
-        this._inputPrompt.executionCount = `${
-          (this._cellModel as CodeCellModel).executionCount ?? ''
-        }`;
-        this._inputPrompt.show();
-      } else {
-        this._inputPrompt.executionCount = null;
-        this._inputPrompt.hide();
-      }
+    // Only edits to the current cell are rate-limited; switching cells updates
+    // the display immediately, see `_onActiveCellChanged`.
+    this._previewDebouncer = new Debouncer<void, void, null[]>(
+      () => this._update(),
+      150
+    );
 
-      if (this._cellModel) {
-        await languages.highlight(
-          this._cellModel.sharedModel.getSource().split('\n')[0],
-          languages.findByMIME(this._cellModel.mimeType),
-          this._editorEl
-        );
-      }
-    };
+    this._tracker.activeCellChanged.connect(this._onActiveCellChanged, this);
+    // `activeCellChanged` is not emitted when the last notebook is closed:
+    // NotebookTracker.onCurrentChanged returns early on a null widget. Without
+    // this second connection the field would keep the cell model of a closed
+    // notebook, and its shared model, alive for the rest of the session.
+    this._tracker.currentChanged.connect(this._onActiveCellChanged, this);
+    this._onActiveCellChanged();
+  }
 
-    this._refreshDebouncer = new Debouncer(update, 150);
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this._tracker.activeCellChanged.disconnect(this._onActiveCellChanged, this);
+    this._tracker.currentChanged.disconnect(this._onActiveCellChanged, this);
+    this._disconnectCellModel();
+    this._previewDebouncer.dispose();
+    super.dispose();
   }
 
   render(props: FieldProps): JSX.Element {
-    const activeCell = this._tracker.activeCell;
-    if (activeCell) this._cellModel = activeCell?.model || null;
-    (this._cellModel?.sharedModel as ISharedText).changed.connect(
-      this.refresh,
+    // The content is driven by the tracker; React only supplies the mount
+    // point, which is a different element on every rebuild of the form.
+    return (
+      <div
+        ref={ref => {
+          if (!ref || this.node.parentElement === ref) {
+            return;
+          }
+          ref.appendChild(this.node);
+          if (this._pendingUpdate) {
+            this._update().catch(console.warn);
+          }
+        }}
+      ></div>
+    );
+  }
+
+  /**
+   * Follow the active cell of the tracker, which is null once the last
+   * notebook is closed.
+   */
+  private _onActiveCellChanged(): void {
+    const cellModel = this._tracker.activeCell?.model ?? null;
+    if (cellModel === this._cellModel) {
+      return;
+    }
+    this._disconnectCellModel();
+    this._cellModel = cellModel;
+    if (cellModel) {
+      (cellModel.sharedModel as ISharedText).changed.connect(
+        this._onCellContentChanged,
+        this
+      );
+      cellModel.mimeTypeChanged.connect(this._onCellContentChanged, this);
+    }
+    // The prompt now belongs to a cell whose source line is not on screen yet,
+    // so leave it to `_update` to write both together.
+    this._promptOutdated = true;
+    this._update().catch(console.warn);
+  }
+
+  /**
+   * Handle a change to the current cell source, mime type or execution count.
+   */
+  private _onCellContentChanged(): void {
+    if (!this.node.isConnected) {
+      this._pendingUpdate = true;
+      this._promptOutdated = true;
+      return;
+    }
+    if (!this._promptOutdated) {
+      // The cell is unchanged and no switch is in flight, so writing the prompt
+      // now cannot pair it with the source line of a different cell.
+      this._updatePrompt();
+    }
+    this._previewDebouncer.invoke().catch(console.warn);
+  }
+
+  /**
+   * Stop listening to the cell model the tool is currently displaying.
+   */
+  private _disconnectCellModel(): void {
+    const cellModel = this._cellModel;
+    if (!cellModel) {
+      return;
+    }
+    (cellModel.sharedModel as ISharedText).changed.disconnect(
+      this._onCellContentChanged,
       this
     );
-    this._cellModel?.mimeTypeChanged.connect(this.refresh, this);
-    this.refresh()
-      .then(() => undefined)
-      .catch(console.warn);
-    return <div ref={ref => ref?.appendChild(this.node)}></div>;
+    cellModel.mimeTypeChanged.disconnect(this._onCellContentChanged, this);
+    this._cellModel = null;
   }
 
-  private async refresh(): Promise<void> {
-    await this._refreshDebouncer.invoke();
+  /**
+   * Reflect the execution count of the current cell.
+   */
+  private _updatePrompt(): void {
+    const cellModel = this._cellModel;
+    if (cellModel && isCodeCellModel(cellModel)) {
+      this._inputPrompt.executionCount = `${cellModel.executionCount ?? ''}`;
+      this._inputPrompt.show();
+    } else {
+      this._inputPrompt.executionCount = null;
+      this._inputPrompt.hide();
+    }
+  }
+
+  /**
+   * Refresh the preview, writing an outdated prompt along with it.
+   *
+   * The prompt is written in the same task as the preview it belongs with, so
+   * that the field never shows the prompt of one cell above the source line of
+   * another while a language mode is being loaded.
+   */
+  private async _update(): Promise<void> {
+    if (!this.node.isConnected) {
+      // Nothing is on screen; catch up when the field is mounted again.
+      this._pendingUpdate = true;
+      return;
+    }
+    this._pendingUpdate = false;
+
+    const cellModel = this._cellModel;
+    const pending = ++this._updateId;
+
+    if (!cellModel) {
+      this._promptOutdated = false;
+      this._updatePrompt();
+      this._editorEl.replaceChildren();
+      return;
+    }
+
+    const source = cellModel.sharedModel.getSource();
+    const lineEnd = source.indexOf('\n');
+    const firstLine = lineEnd === -1 ? source : source.slice(0, lineEnd);
+
+    // Highlight into a detached node, so that the preview is never cleared
+    // while waiting for a language mode to load.
+    const staging = document.createElement('pre');
+    try {
+      await this._languages.highlight(
+        firstLine,
+        this._languages.findByMIME(cellModel.mimeType),
+        staging
+      );
+    } catch (error) {
+      // Fall back to unhighlighted source rather than keeping the previous
+      // cell's line on screen.
+      console.warn(error);
+      staging.replaceChildren(document.createTextNode(firstLine));
+    }
+
+    if (pending !== this._updateId) {
+      // A newer update started while this one was highlighting; it still owes
+      // the prompt write, so `_promptOutdated` is deliberately left set.
+      return;
+    }
+
+    if (this._promptOutdated) {
+      this._updatePrompt();
+      this._promptOutdated = false;
+    }
+    const fragment = document.createDocumentFragment();
+    while (staging.firstChild) {
+      fragment.appendChild(staging.firstChild);
+    }
+    this._editorEl.replaceChildren(fragment);
   }
 
   private _tracker: INotebookTracker;
-  private _cellModel: ICellModel | null;
-  private _refreshDebouncer: Debouncer<void, void, null[]>;
+  private _languages: IEditorLanguageRegistry;
+  private _cellModel: ICellModel | null = null;
+  private _previewDebouncer: Debouncer<void, void, null[]>;
+  private _updateId = 0;
+  private _pendingUpdate = false;
+  private _promptOutdated = false;
   private _editorEl: HTMLPreElement;
   private _inputPrompt: InputPrompt;
 }

package/src/tool-widgets/metadataEditorFields.tsx

@@ -77,9 +77,12 @@ export class CellMetadataField extends NotebookTools.MetadataEditorTool {
 
   render(props: FieldProps): JSX.Element {
     const cell = this._tracker.activeCell;
+    // Replace and dispose the source created for the previous render.
+    const previousSource = this.editor.source;
     this.editor.source = cell
       ? new ObservableJSON({ values: cell.model.metadata as JSONObject })
       : null;
+    previousSource?.dispose();
     this.editor.source?.changed.connect(this._onSourceChanged, this);
 
     return (
@@ -120,9 +123,12 @@ export class NotebookMetadataField extends NotebookTools.MetadataEditorTool {
 
   render(props: FieldProps): JSX.Element {
     const notebook = this._tracker.currentWidget;
+    // Replace and dispose the source created for the previous render.
+    const previousSource = this.editor.source;
     this.editor.source = notebook
       ? new ObservableJSON({ values: notebook.model?.metadata as JSONObject })
       : null;
+    previousSource?.dispose();
     this.editor.source?.changed.connect(this._onSourceChanged, this);
 
     return (