@jupyter/chat 0.1.0 → 0.3.0

package/src/active-cell-manager.ts

@@ -0,0 +1,318 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { JupyterFrontEnd, LabShell } from '@jupyterlab/application';
+import { Cell, ICellModel } from '@jupyterlab/cells';
+import { IChangedArgs } from '@jupyterlab/coreutils';
+import { INotebookTracker, NotebookActions } from '@jupyterlab/notebook';
+import { IError as CellError } from '@jupyterlab/nbformat';
+import { ISignal, Signal } from '@lumino/signaling';
+
+type CellContent = {
+  type: string;
+  source: string;
+};
+
+type CellWithErrorContent = {
+  type: 'code';
+  source: string;
+  error: {
+    name: string;
+    value: string;
+    traceback: string[];
+  };
+};
+
+export interface IActiveCellManager {
+  /**
+   * Whether the notebook is available and an active cell exists.
+   */
+  readonly available: boolean;
+  /**
+   * The `CellError` output within the active cell, if any.
+   */
+  readonly activeCellError: CellError | null;
+  /**
+   * A signal emitting when the active cell changed.
+   */
+  readonly availabilityChanged: ISignal<this, boolean>;
+  /**
+   * A signal emitting when the error state of the active cell changed.
+   */
+  readonly activeCellErrorChanged: ISignal<this, CellError | null>;
+  /**
+   * Returns an `ActiveCellContent` object that describes the current active
+   * cell. If no active cell exists, this method returns `null`.
+   *
+   * When called with `withError = true`, this method returns `null` if the
+   * active cell does not have an error output. Otherwise it returns an
+   * `ActiveCellContentWithError` object that describes both the active cell and
+   * the error output.
+   */
+  getContent(withError: boolean): CellContent | CellWithErrorContent | null;
+  /**
+   * Inserts `content` in a new cell above the active cell.
+   */
+  insertAbove(content: string): void;
+  /**
+   * Inserts `content` in a new cell below the active cell.
+   */
+  insertBelow(content: string): void;
+  /**
+   * Replaces the contents of the active cell.
+   */
+  replace(content: string): Promise<void>;
+}
+
+/**
+ * The active cell manager namespace.
+ */
+export namespace ActiveCellManager {
+  /**
+   * The constructor options.
+   */
+  export interface IOptions {
+    /**
+     * The notebook tracker.
+     */
+    tracker: INotebookTracker;
+    /**
+     * The current shell of the application.
+     */
+    shell: JupyterFrontEnd.IShell;
+  }
+}
+
+/**
+ * A manager that maintains a reference to the current active notebook cell in
+ * the main panel (if any), and provides methods for inserting or appending
+ * content to the active cell.
+ *
+ * The current active cell should be obtained by listening to the
+ * `activeCellChanged` signal.
+ */
+export class ActiveCellManager implements IActiveCellManager {
+  constructor(options: ActiveCellManager.IOptions) {
+    this._notebookTracker = options.tracker;
+    this._notebookTracker.activeCellChanged.connect(this._onActiveCellChanged);
+    options.shell.currentChanged?.connect(this._onMainAreaChanged);
+    if (options.shell instanceof LabShell) {
+      options.shell.layoutModified?.connect(this._onMainAreaChanged);
+    }
+    this._onMainAreaChanged();
+  }
+
+  /**
+   * Whether the notebook is available and an active cell exists.
+   */
+  get available(): boolean {
+    return this._available;
+  }
+
+  /**
+   * The `CellError` output within the active cell, if any.
+   */
+  get activeCellError(): CellError | null {
+    return this._activeCellError;
+  }
+
+  /**
+   * A signal emitting when the active cell changed.
+   */
+  get availabilityChanged(): ISignal<this, boolean> {
+    return this._availabilityChanged;
+  }
+
+  /**
+   * A signal emitting when the error state of the active cell changed.
+   */
+  get activeCellErrorChanged(): ISignal<this, CellError | null> {
+    return this._activeCellErrorChanged;
+  }
+
+  /**
+   * Returns an `ActiveCellContent` object that describes the current active
+   * cell. If no active cell exists, this method returns `null`.
+   *
+   * When called with `withError = true`, this method returns `null` if the
+   * active cell does not have an error output. Otherwise it returns an
+   * `ActiveCellContentWithError` object that describes both the active cell and
+   * the error output.
+   */
+  getContent(withError: false): CellContent | null;
+  getContent(withError: true): CellWithErrorContent | null;
+  getContent(withError = false): CellContent | CellWithErrorContent | null {
+    const sharedModel = this._notebookTracker.activeCell?.model.sharedModel;
+    if (!sharedModel) {
+      return null;
+    }
+
+    // case where withError = false
+    if (!withError) {
+      return {
+        type: sharedModel.cell_type,
+        source: sharedModel.getSource()
+      };
+    }
+
+    // case where withError = true
+    const error = this._activeCellError;
+    if (error) {
+      return {
+        type: 'code',
+        source: sharedModel.getSource(),
+        error: {
+          name: error.ename,
+          value: error.evalue,
+          traceback: error.traceback
+        }
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Inserts `content` in a new cell above the active cell.
+   */
+  insertAbove(content: string): void {
+    const notebookPanel = this._notebookTracker.currentWidget;
+    if (!notebookPanel || !notebookPanel.isVisible) {
+      return;
+    }
+
+    // create a new cell above the active cell and mark new cell as active
+    NotebookActions.insertAbove(notebookPanel.content);
+    // replace content of this new active cell
+    this.replace(content);
+  }
+
+  /**
+   * Inserts `content` in a new cell below the active cell.
+   */
+  insertBelow(content: string): void {
+    const notebookPanel = this._notebookTracker.currentWidget;
+    if (!notebookPanel || !notebookPanel.isVisible) {
+      return;
+    }
+
+    // create a new cell below the active cell and mark new cell as active
+    NotebookActions.insertBelow(notebookPanel.content);
+    // replace content of this new active cell
+    this.replace(content);
+  }
+
+  /**
+   * Replaces the contents of the active cell.
+   */
+  async replace(content: string): Promise<void> {
+    const notebookPanel = this._notebookTracker.currentWidget;
+    if (!notebookPanel || !notebookPanel.isVisible) {
+      return;
+    }
+    // get reference to active cell directly from Notebook API. this avoids the
+    // possibility of acting on an out-of-date reference.
+    const activeCell = this._notebookTracker.activeCell;
+    if (!activeCell) {
+      return;
+    }
+
+    // wait for editor to be ready
+    await activeCell.ready;
+
+    // replace the content of the active cell
+    /**
+     * NOTE: calling this method sometimes emits an error to the browser console:
+     *
+     * ```
+     * Error: Calls to EditorView.update are not allowed while an update is in progress
+     * ```
+     *
+     * However, there seems to be no impact on the behavior/stability of the
+     * JupyterLab application after this error is logged. Furthermore, this is
+     * the official API for setting the content of a cell in JupyterLab 4,
+     * meaning that this is likely unavoidable.
+     */
+    activeCell.editor?.model.sharedModel.setSource(content);
+  }
+
+  private _onMainAreaChanged = () => {
+    const value = this._notebookTracker.currentWidget?.isVisible ?? false;
+    if (value !== this._notebookVisible) {
+      this._notebookVisible = value;
+      this._available = !!this._activeCell && this._notebookVisible;
+      this._availabilityChanged.emit(this._available);
+    }
+  };
+
+  /**
+   * Handle the change of active notebook cell.
+   */
+  private _onActiveCellChanged = (
+    _: INotebookTracker,
+    activeCell: Cell<ICellModel> | null
+  ): void => {
+    if (this._activeCell !== activeCell) {
+      this._activeCell?.model.stateChanged.disconnect(this._cellStateChange);
+      this._activeCell = activeCell;
+
+      activeCell?.ready.then(() => {
+        this._activeCell?.model.stateChanged.connect(this._cellStateChange);
+        this._available = !!this._activeCell && this._notebookVisible;
+        this._availabilityChanged.emit(this._available);
+        this._activeCell?.disposed.connect(() => {
+          this._activeCell = null;
+        });
+      });
+    }
+  };
+
+  /**
+   * Handle the change of the active cell state.
+   */
+  private _cellStateChange = (
+    _: ICellModel,
+    change: IChangedArgs<boolean, boolean, any>
+  ): void => {
+    if (change.name === 'executionCount') {
+      const currSharedModel = this._activeCell?.model.sharedModel;
+      const prevActiveCellError = this._activeCellError;
+      let currActiveCellError: CellError | null = null;
+      if (currSharedModel && 'outputs' in currSharedModel) {
+        currActiveCellError =
+          currSharedModel.outputs.find<CellError>(
+            (output): output is CellError => output.output_type === 'error'
+          ) || null;
+      }
+
+      // for some reason, the `CellError` object is not referentially stable,
+      // meaning that this condition always evaluates to `true` and the
+      // `activeCellErrorChanged` signal is emitted every 200ms, even when the
+      // error output is unchanged. this is why we have to rely on
+      // `execution_count` to track changes to the error output.
+      if (prevActiveCellError !== currActiveCellError) {
+        this._activeCellError = currActiveCellError;
+        this._activeCellErrorChanged.emit(this._activeCellError);
+      }
+    }
+  };
+
+  /**
+   * The notebook tracker.
+   */
+  private _notebookTracker: INotebookTracker;
+  /**
+   * Whether the current notebook panel is visible or not.
+   */
+  private _notebookVisible: boolean = false;
+  /**
+   * The active cell.
+   */
+  private _activeCell: Cell | null = null;
+  private _available: boolean = false;
+  private _activeCellError: CellError | null = null;
+  private _availabilityChanged = new Signal<this, boolean>(this);
+  private _activeCellErrorChanged = new Signal<this, CellError | null>(this);
+}

package/src/components/chat-input.tsx

@@ -3,31 +3,112 @@
  * Distributed under the terms of the Modified BSD License.
  */
 
-import React, { useState } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 
 import {
+  Autocomplete,
   Box,
+  IconButton,
+  InputAdornment,
   SxProps,
   TextField,
-  Theme,
-  IconButton,
-  InputAdornment
+  Theme
 } from '@mui/material';
 import { Send, Cancel } from '@mui/icons-material';
 import clsx from 'clsx';
+import { IChatModel } from '../model';
+import { IAutocompletionRegistry } from '../registry';
+import { AutocompleteCommand, IAutocompletionCommandsProps } from '../types';
 
 const INPUT_BOX_CLASS = 'jp-chat-input-container';
 const SEND_BUTTON_CLASS = 'jp-chat-send-button';
 const CANCEL_BUTTON_CLASS = 'jp-chat-cancel-button';
 
 export function ChatInput(props: ChatInput.IProps): JSX.Element {
-  const [input, setInput] = useState(props.value || '');
+  const { autocompletionName, autocompletionRegistry, model } = props;
+  const autocompletion = useRef<IAutocompletionCommandsProps>();
+  const [input, setInput] = useState<string>(props.value || '');
+  const [sendWithShiftEnter, setSendWithShiftEnter] = useState<boolean>(
+    model.config.sendWithShiftEnter ?? false
+  );
+
+  useEffect(() => {
+    model.configChanged.connect((_, config) => {
+      setSendWithShiftEnter(config.sendWithShiftEnter ?? false);
+    });
+  }, [model]);
+
+  // The autocomplete commands options.
+  const [commandOptions, setCommandOptions] = useState<AutocompleteCommand[]>(
+    []
+  );
+  // whether any option is highlighted in the slash command autocomplete
+  const [highlighted, setHighlighted] = useState<boolean>(false);
+  // controls whether the slash command autocomplete is open
+  const [open, setOpen] = useState<boolean>(false);
+
+  /**
+   * Effect: fetch the list of available autocomplete commands.
+   */
+  useEffect(() => {
+    if (autocompletionRegistry === undefined) {
+      return;
+    }
+    autocompletion.current = autocompletionName
+      ? autocompletionRegistry.get(autocompletionName)
+      : autocompletionRegistry.getDefaultCompletion();
+
+    if (autocompletion.current === undefined) {
+      return;
+    }
+
+    if (Array.isArray(autocompletion.current.commands)) {
+      setCommandOptions(autocompletion.current.commands);
+    } else if (typeof autocompletion.current.commands === 'function') {
+      autocompletion.current
+        .commands()
+        .then((commands: AutocompleteCommand[]) => {
+          setCommandOptions(commands);
+        });
+    }
+  }, []);
+
+  /**
+   * Effect: Open the autocomplete when the user types the 'opener' string into an
+   * empty chat input. Close the autocomplete and reset the last selected value when
+   * the user clears the chat input.
+   */
+  useEffect(() => {
+    if (!autocompletion.current?.opener) {
+      return;
+    }
+
+    if (input === autocompletion.current?.opener) {
+      setOpen(true);
+      return;
+    }
+
+    if (input === '') {
+      setOpen(false);
+      return;
+    }
+  }, [input]);
 
   function handleKeyDown(event: React.KeyboardEvent<HTMLInputElement>) {
+    if (event.key !== 'Enter') {
+      return;
+    }
+
+    // do not send the message if the user was selecting a suggested command from the
+    // Autocomplete component.
+    if (highlighted) {
+      return;
+    }
+
     if (
       event.key === 'Enter' &&
-      ((props.sendWithShiftEnter && event.shiftKey) ||
-        (!props.sendWithShiftEnter && !event.shiftKey))
+      ((sendWithShiftEnter && event.shiftKey) ||
+        (!sendWithShiftEnter && !event.shiftKey))
     ) {
       onSend();
       event.stopPropagation();
@@ -52,7 +133,7 @@ export function ChatInput(props: ChatInput.IProps): JSX.Element {
   }
 
   // Set the helper text based on whether Shift+Enter is used for sending.
-  const helperText = props.sendWithShiftEnter ? (
+  const helperText = sendWithShiftEnter ? (
     <span>
       Press <b>Shift</b>+<b>Enter</b> to send message
     </span>
@@ -64,49 +145,106 @@ export function ChatInput(props: ChatInput.IProps): JSX.Element {
 
   return (
     <Box sx={props.sx} className={clsx(INPUT_BOX_CLASS)}>
-      <Box sx={{ display: 'flex' }}>
-        <TextField
-          value={input}
-          onChange={e => setInput(e.target.value)}
-          fullWidth
-          variant="outlined"
-          multiline
-          onKeyDown={handleKeyDown}
-          placeholder="Start chatting"
-          InputProps={{
-            endAdornment: (
-              <InputAdornment position="end">
-                {props.onCancel && (
+      <Autocomplete
+        options={commandOptions}
+        value={props.value}
+        open={open}
+        autoHighlight
+        freeSolo
+        // ensure the autocomplete popup always renders on top
+        componentsProps={{
+          popper: {
+            placement: 'top'
+          },
+          paper: {
+            sx: {
+              border: '1px solid lightgray'
+            }
+          }
+        }}
+        ListboxProps={{
+          sx: {
+            '& .MuiAutocomplete-option': {
+              padding: 2
+            }
+          }
+        }}
+        renderInput={params => (
+          <TextField
+            {...params}
+            fullWidth
+            variant="outlined"
+            multiline
+            onKeyDown={handleKeyDown}
+            placeholder="Start chatting"
+            InputProps={{
+              ...params.InputProps,
+              endAdornment: (
+                <InputAdornment position="end">
+                  {props.onCancel && (
+                    <IconButton
+                      size="small"
+                      color="primary"
+                      onClick={onCancel}
+                      title={'Cancel edition'}
+                      className={clsx(CANCEL_BUTTON_CLASS)}
+                    >
+                      <Cancel />
+                    </IconButton>
+                  )}
                   <IconButton
                     size="small"
                     color="primary"
-                    onClick={onCancel}
-                    disabled={!input.trim().length}
-                    title={'Cancel edition'}
-                    className={clsx(CANCEL_BUTTON_CLASS)}
+                    onClick={onSend}
+                    disabled={
+                      props.onCancel
+                        ? input === props.value
+                        : !input.trim().length
+                    }
+                    title={`Send message ${sendWithShiftEnter ? '(SHIFT+ENTER)' : '(ENTER)'}`}
+                    className={clsx(SEND_BUTTON_CLASS)}
                   >
-                    <Cancel />
+                    <Send />
                   </IconButton>
-                )}
-                <IconButton
-                  size="small"
-                  color="primary"
-                  onClick={onSend}
-                  disabled={!input.trim().length}
-                  title={`Send message ${props.sendWithShiftEnter ? '(SHIFT+ENTER)' : '(ENTER)'}`}
-                  className={clsx(SEND_BUTTON_CLASS)}
-                >
-                  <Send />
-                </IconButton>
-              </InputAdornment>
-            )
-          }}
-          FormHelperTextProps={{
-            sx: { marginLeft: 'auto', marginRight: 0 }
-          }}
-          helperText={input.length > 2 ? helperText : ' '}
-        />
-      </Box>
+                </InputAdornment>
+              )
+            }}
+            FormHelperTextProps={{
+              sx: { marginLeft: 'auto', marginRight: 0 }
+            }}
+            helperText={input.length > 2 ? helperText : ' '}
+          />
+        )}
+        {...autocompletion.current?.props}
+        inputValue={input}
+        onInputChange={(_, newValue: string) => {
+          setInput(newValue);
+        }}
+        onHighlightChange={
+          /**
+           * On highlight change: set `highlighted` to whether an option is
+           * highlighted by the user.
+           *
+           * This isn't called when an option is selected for some reason, so we
+           * need to call `setHighlighted(false)` in `onClose()`.
+           */
+          (_, highlightedOption) => {
+            setHighlighted(!!highlightedOption);
+          }
+        }
+        onClose={
+          /**
+           * On close: set `highlighted` to `false` and close the popup by
+           * setting `open` to `false`.
+           */
+          () => {
+            setHighlighted(false);
+            setOpen(false);
+          }
+        }
+        // hide default extra right padding in the text field
+        disableClearable
+      />
     </Box>
   );
 }
@@ -119,6 +257,10 @@ export namespace ChatInput {
    * The properties of the react element.
    */
   export interface IProps {
+    /**
+     * The chat model.
+     */
+    model: IChatModel;
     /**
      * The initial value of the input (default to '')
      */
@@ -131,13 +273,17 @@ export namespace ChatInput {
      * The function to be called to cancel editing.
      */
     onCancel?: () => unknown;
-    /**
-     * Whether using shift+enter to send the message.
-     */
-    sendWithShiftEnter: boolean;
     /**
      * Custom mui/material styles.
      */
     sx?: SxProps<Theme>;
+    /**
+     * Autocompletion properties.
+     */
+    autocompletionRegistry?: IAutocompletionRegistry;
+    /**
+     * Autocompletion name.
+     */
+    autocompletionName?: string;
   }
 }