@jupyter/chat 0.7.0 → 0.8.0

package/src/components/input/use-chat-commands.tsx

@@ -0,0 +1,186 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import React from 'react';
+import { useEffect, useState } from 'react';
+import type {
+  AutocompleteChangeReason,
+  AutocompleteProps as GenericAutocompleteProps
+} from '@mui/material';
+import { Box } from '@mui/material';
+
+import { ChatCommand, IChatCommandRegistry } from '../../chat-commands';
+import { IInputModel } from '../../input-model';
+
+type AutocompleteProps = GenericAutocompleteProps<any, any, any, any>;
+
+type UseChatCommandsReturn = {
+  autocompleteProps: Omit<AutocompleteProps, 'renderInput'>;
+  menu: {
+    open: boolean;
+    highlighted: boolean;
+  };
+};
+
+/**
+ * A hook which automatically returns the list of command options given the
+ * current input and chat command registry.
+ *
+ * Intended usage: `const chatCommands = useChatCommands(...)`.
+ */
+export function useChatCommands(
+  inputModel: IInputModel,
+  chatCommandRegistry?: IChatCommandRegistry
+): UseChatCommandsReturn {
+  // whether an option is highlighted in the chat commands menu
+  const [highlighted, setHighlighted] = useState(false);
+
+  // whether the chat commands menu is open
+  const [open, setOpen] = useState(false);
+
+  // current list of chat commands matched by the current word.
+  // the current word is the space-separated word at the user's cursor.
+  const [commands, setCommands] = useState<ChatCommand[]>([]);
+
+  useEffect(() => {
+    async function getCommands(_: IInputModel, currentWord: string | null) {
+      const providers = chatCommandRegistry?.getProviders();
+      if (!providers) {
+        return;
+      }
+
+      if (!currentWord?.length) {
+        setCommands([]);
+        setOpen(false);
+        setHighlighted(false);
+        return;
+      }
+
+      let newCommands: ChatCommand[] = [];
+      for (const provider of providers) {
+        // TODO: optimize performance when this method is truly async
+        try {
+          newCommands = newCommands.concat(
+            await provider.getChatCommands(inputModel)
+          );
+        } catch (e) {
+          console.error(
+            `Error when getting chat commands from command provider '${provider.id}': `,
+            e
+          );
+        }
+      }
+      if (newCommands) {
+        setOpen(true);
+      }
+      setCommands(newCommands);
+    }
+
+    inputModel.currentWordChanged.connect(getCommands);
+
+    return () => {
+      inputModel.currentWordChanged.disconnect(getCommands);
+    };
+  }, [inputModel]);
+
+  /**
+   * onChange(): the callback invoked when a command is selected from the chat
+   * commands menu by the user.
+   */
+  const onChange: AutocompleteProps['onChange'] = (
+    e: unknown,
+    command: ChatCommand,
+    reason: AutocompleteChangeReason
+  ) => {
+    if (reason !== 'selectOption') {
+      // only call this callback when a command is selected by the user. this
+      // requires `reason === 'selectOption'`.
+      return;
+    }
+
+    if (!chatCommandRegistry) {
+      return;
+    }
+
+    const currentWord = inputModel.currentWord;
+    if (!currentWord) {
+      return;
+    }
+
+    // if replaceWith is set, handle the command immediately
+    if (command.replaceWith) {
+      inputModel.replaceCurrentWord(command.replaceWith);
+      return;
+    }
+
+    // otherwise, defer handling to the command provider
+    chatCommandRegistry.handleChatCommand(command, inputModel);
+  };
+
+  return {
+    autocompleteProps: {
+      open,
+      options: commands,
+      getOptionLabel: (command: ChatCommand) => command.name,
+      renderOption: (
+        defaultProps,
+        command: ChatCommand,
+        __: unknown,
+        ___: unknown
+      ) => {
+        const { key, ...listItemProps } = defaultProps;
+        const commandIcon: JSX.Element = (
+          <span>
+            {typeof command.icon === 'object' ? (
+              <command.icon.react />
+            ) : (
+              command.icon
+            )}
+          </span>
+        );
+        return (
+          <Box key={key} component="li" {...listItemProps}>
+            {commandIcon}
+            <p className="jp-chat-command-name">{command.name}</p>
+            <span> - </span>
+            <p className="jp-chat-command-description">{command.description}</p>
+          </Box>
+        );
+      },
+      // always show all options, since command providers should exclusively
+      // define what commands are added to the menu.
+      filterOptions: (commands: ChatCommand[]) => commands,
+      value: null,
+      autoHighlight: true,
+      freeSolo: true,
+      disableClearable: true,
+      onChange,
+      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);
+        }
+    },
+    menu: {
+      open,
+      highlighted
+    }
+  };
+}

package/src/context.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { createContext } from 'react';
+import { IAttachmentOpenerRegistry } from './registry';
+
+export const AttachmentOpenerContext = createContext<
+  IAttachmentOpenerRegistry | undefined
+>(undefined);

package/src/index.ts

@@ -6,6 +6,7 @@
 export * from './active-cell-manager';
 export * from './components';
 export * from './icons';
+export * from './input-model';
 export * from './model';
 export * from './registry';
 export * from './selection-watcher';
@@ -13,3 +14,4 @@ export * from './types';
 export * from './widgets/chat-error';
 export * from './widgets/chat-sidebar';
 export * from './widgets/chat-widget';
+export * from './chat-commands';

package/src/input-model.ts

@@ -0,0 +1,406 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { IDisposable } from '@lumino/disposable';
+import { ISignal, Signal } from '@lumino/signaling';
+import { IActiveCellManager } from './active-cell-manager';
+import { ISelectionWatcher } from './selection-watcher';
+import { IAttachment } from './types';
+
+const WHITESPACE = new Set([' ', '\n', '\t']);
+
+/**
+ * The chat input interface.
+ */
+export interface IInputModel extends IDisposable {
+  /**
+   * The entire input value.
+   */
+  value: string;
+
+  /**
+   * A signal emitting when the value has changed.
+   */
+  readonly valueChanged: ISignal<IInputModel, string>;
+
+  /**
+   * The current cursor index.
+   * This refers to the index of the character in front of the cursor.
+   */
+  cursorIndex: number | null;
+
+  /**
+   * A signal emitting when the cursor position has changed.
+   */
+  readonly cursorIndexChanged: ISignal<IInputModel, number | null>;
+
+  /**
+   * The current word behind the user's cursor, space-separated.
+   */
+  readonly currentWord: string | null;
+
+  /**
+   * A signal emitting when the current word has changed.
+   */
+  readonly currentWordChanged: ISignal<IInputModel, string | null>;
+
+  /**
+   * Get the active cell manager.
+   */
+  readonly activeCellManager: IActiveCellManager | null;
+
+  /**
+   * Get the selection watcher.
+   */
+  readonly selectionWatcher: ISelectionWatcher | null;
+
+  /**
+   * The input configuration.
+   */
+  config: InputModel.IConfig;
+
+  /**
+   * A signal emitting when the messages list is updated.
+   */
+  readonly configChanged: ISignal<IInputModel, InputModel.IConfig>;
+
+  /**
+   * Function to request the focus on the input of the chat.
+   */
+  focus(): void;
+
+  /**
+   * A signal emitting when the focus is requested on the input.
+   */
+  readonly focusInputSignal?: ISignal<IInputModel, void>;
+
+  /**
+   * The attachments list.
+   */
+  readonly attachments: IAttachment[];
+
+  /**
+   * Add attachment to the next message to send.
+   */
+  addAttachment?(attachment: IAttachment): void;
+
+  /**
+   * Remove attachment to the next message to send.
+   */
+  removeAttachment?(attachment: IAttachment): void;
+
+  /**
+   * Clear the attachment list.
+   */
+  clearAttachments(): void;
+
+  /**
+   * A signal emitting when the attachment list has changed.
+   */
+  readonly attachmentsChanged?: ISignal<IInputModel, IAttachment[]>;
+
+  /**
+   * Replace the current word in the input with a new one.
+   */
+  replaceCurrentWord(newWord: string): void;
+}
+
+/**
+ * The input model.
+ */
+export class InputModel implements IInputModel {
+  constructor(options: InputModel.IOptions) {
+    this._value = options.value || '';
+    this._attachments = options.attachments || [];
+    this.cursorIndex = options.cursorIndex || this.value.length;
+    this._activeCellManager = options.activeCellManager ?? null;
+    this._selectionWatcher = options.selectionWatcher ?? null;
+
+    this._config = {
+      ...options.config
+    };
+  }
+
+  /**
+   * The entire input value.
+   */
+  get value(): string {
+    return this._value;
+  }
+  set value(newInput: string) {
+    this._value = newInput;
+    this._valueChanged.emit(newInput);
+  }
+
+  /**
+   * A signal emitting when the value has changed.
+   */
+  get valueChanged(): ISignal<IInputModel, string> {
+    return this._valueChanged;
+  }
+
+  /**
+   * The cursor position in the input.
+   */
+  get cursorIndex(): number | null {
+    return this._cursorIndex;
+  }
+  set cursorIndex(newIndex: number | null) {
+    if (newIndex === null || newIndex > this._value.length) {
+      return;
+    }
+    this._cursorIndex = newIndex;
+    this._cursorIndexChanged.emit(newIndex);
+
+    if (this._cursorIndex === null) {
+      return;
+    }
+    const currentWord = Private.getCurrentWord(this._value, this._cursorIndex);
+    if (currentWord !== this._currentWord) {
+      this._currentWord = currentWord;
+      this._currentWordChanged.emit(this._currentWord);
+    }
+  }
+
+  /**
+   * A signal emitting when the cursor position has changed.
+   */
+  get cursorIndexChanged(): ISignal<IInputModel, number | null> {
+    return this._cursorIndexChanged;
+  }
+
+  /**
+   * The current word behind the user's cursor, space-separated.
+   */
+  get currentWord(): string | null {
+    return this._currentWord;
+  }
+
+  /**
+   * A signal emitting when the current word has changed.
+   */
+  get currentWordChanged(): ISignal<IInputModel, string | null> {
+    return this._currentWordChanged;
+  }
+
+  /**
+   * Get the active cell manager.
+   */
+  get activeCellManager(): IActiveCellManager | null {
+    return this._activeCellManager;
+  }
+
+  /**
+   * Get the selection watcher.
+   */
+  get selectionWatcher(): ISelectionWatcher | null {
+    return this._selectionWatcher;
+  }
+
+  /**
+   * The input configuration.
+   */
+  get config(): InputModel.IConfig {
+    return this._config;
+  }
+  set config(value: Partial<InputModel.IConfig>) {
+    this._config = { ...this._config, ...value };
+    this._configChanged.emit(this._config);
+  }
+
+  /**
+   * A signal emitting when the configuration is updated.
+   */
+  get configChanged(): ISignal<IInputModel, InputModel.IConfig> {
+    return this._configChanged;
+  }
+
+  /**
+   * Function to request the focus on the input of the chat.
+   */
+  focus(): void {
+    this._focusInputSignal.emit();
+  }
+
+  /**
+   * A signal emitting when the focus is requested on the input.
+   */
+  get focusInputSignal(): ISignal<IInputModel, void> {
+    return this._focusInputSignal;
+  }
+
+  /**
+   * The attachments list.
+   */
+  get attachments(): IAttachment[] {
+    return this._attachments;
+  }
+
+  /**
+   * Add attachment to send with next message.
+   */
+  addAttachment = (attachment: IAttachment): void => {
+    const duplicateAttachment = this._attachments.find(
+      att => att.type === attachment.type && att.value === attachment.value
+    );
+    if (duplicateAttachment) {
+      return;
+    }
+
+    this._attachments.push(attachment);
+    this._attachmentsChanged.emit([...this._attachments]);
+  };
+
+  /**
+   * Remove attachment to be sent.
+   */
+  removeAttachment = (attachment: IAttachment): void => {
+    const attachmentIndex = this._attachments.findIndex(
+      att => att.type === attachment.type && att.value === attachment.value
+    );
+    if (attachmentIndex === -1) {
+      return;
+    }
+
+    this._attachments.splice(attachmentIndex, 1);
+    this._attachmentsChanged.emit([...this._attachments]);
+  };
+
+  /**
+   * Update attachments.
+   */
+  clearAttachments = (): void => {
+    this._attachments = [];
+    this._attachmentsChanged.emit([]);
+  };
+
+  /**
+   * A signal emitting when the input attachments changed.
+   */
+  get attachmentsChanged(): ISignal<IInputModel, IAttachment[]> {
+    return this._attachmentsChanged;
+  }
+
+  /**
+   * Replace the current word in the input with a new one.
+   */
+  replaceCurrentWord(newWord: string): void {
+    if (this.cursorIndex === null) {
+      return;
+    }
+    const [start, end] = Private.getCurrentWordBoundaries(
+      this.value,
+      this.cursorIndex
+    );
+    this.value = this.value.slice(0, start) + newWord + this.value.slice(end);
+  }
+
+  /**
+   * Dispose the input model.
+   */
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this._isDisposed = true;
+  }
+
+  /**
+   * Whether the input model is disposed.
+   */
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  private _value: string;
+  private _cursorIndex: number | null = null;
+  private _currentWord: string | null = null;
+  private _attachments: IAttachment[];
+  private _activeCellManager: IActiveCellManager | null;
+  private _selectionWatcher: ISelectionWatcher | null;
+  private _config: InputModel.IConfig;
+  private _valueChanged = new Signal<IInputModel, string>(this);
+  private _cursorIndexChanged = new Signal<IInputModel, number | null>(this);
+  private _currentWordChanged = new Signal<IInputModel, string | null>(this);
+  private _configChanged = new Signal<IInputModel, InputModel.IConfig>(this);
+  private _focusInputSignal = new Signal<InputModel, void>(this);
+  private _attachmentsChanged = new Signal<InputModel, IAttachment[]>(this);
+  private _isDisposed = false;
+}
+
+export namespace InputModel {
+  export interface IOptions {
+    /**
+     * The initial value of the input.
+     */
+    value?: string;
+
+    /**
+     * The initial attachments.
+     */
+    attachments?: IAttachment[];
+
+    /**
+     * The current cursor index.
+     * This refers to the index of the character in front of the cursor.
+     */
+    cursorIndex?: number;
+
+    /**
+     * The configuration for the input component.
+     */
+    config?: IConfig;
+
+    /**
+     * Active cell manager.
+     */
+    activeCellManager?: IActiveCellManager | null;
+
+    /**
+     * Selection watcher.
+     */
+    selectionWatcher?: ISelectionWatcher | null;
+  }
+
+  export interface IConfig {
+    /**
+     * Whether to send a message via Shift-Enter instead of Enter.
+     */
+    sendWithShiftEnter?: boolean;
+  }
+}
+
+namespace Private {
+  export function getCurrentWordBoundaries(
+    input: string,
+    cursorIndex: number
+  ): [number, number] {
+    let start = cursorIndex;
+    let end = cursorIndex;
+    const n = input.length;
+
+    while (start > 0 && !WHITESPACE.has(input[start - 1])) {
+      start--;
+    }
+
+    while (end < n && !WHITESPACE.has(input[end])) {
+      end++;
+    }
+
+    return [start, end];
+  }
+
+  /**
+   * Gets the current (space-separated) word around the user's cursor. The current
+   * word is used to generate a list of matching chat commands.
+   */
+  export function getCurrentWord(
+    input: string,
+    cursorIndex: number
+  ): string | null {
+    const [start, end] = getCurrentWordBoundaries(input, cursorIndex);
+    return input.slice(start, end);
+  }
+}