@jupyter/chat 0.1.0 → 0.3.0

package/lib/active-cell-manager.d.ts

@@ -0,0 +1,151 @@
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { INotebookTracker } from '@jupyterlab/notebook';
+import { IError as CellError } from '@jupyterlab/nbformat';
+import { ISignal } 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 declare namespace ActiveCellManager {
+    /**
+     * The constructor options.
+     */
+    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 declare class ActiveCellManager implements IActiveCellManager {
+    constructor(options: ActiveCellManager.IOptions);
+    /**
+     * Whether the notebook is available and an active cell exists.
+     */
+    get available(): boolean;
+    /**
+     * The `CellError` output within the active cell, if any.
+     */
+    get activeCellError(): CellError | null;
+    /**
+     * A signal emitting when the active cell changed.
+     */
+    get availabilityChanged(): ISignal<this, boolean>;
+    /**
+     * A signal emitting when the error state of the active cell changed.
+     */
+    get 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: false): CellContent | null;
+    getContent(withError: true): 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>;
+    private _onMainAreaChanged;
+    /**
+     * Handle the change of active notebook cell.
+     */
+    private _onActiveCellChanged;
+    /**
+     * Handle the change of the active cell state.
+     */
+    private _cellStateChange;
+    /**
+     * The notebook tracker.
+     */
+    private _notebookTracker;
+    /**
+     * Whether the current notebook panel is visible or not.
+     */
+    private _notebookVisible;
+    /**
+     * The active cell.
+     */
+    private _activeCell;
+    private _available;
+    private _activeCellError;
+    private _availabilityChanged;
+    private _activeCellErrorChanged;
+}
+export {};

package/lib/active-cell-manager.js

@@ -0,0 +1,201 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { LabShell } from '@jupyterlab/application';
+import { NotebookActions } from '@jupyterlab/notebook';
+import { Signal } from '@lumino/signaling';
+/**
+ * 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 {
+    constructor(options) {
+        var _a, _b;
+        this._onMainAreaChanged = () => {
+            var _a, _b;
+            const value = (_b = (_a = this._notebookTracker.currentWidget) === null || _a === void 0 ? void 0 : _a.isVisible) !== null && _b !== void 0 ? _b : 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.
+         */
+        this._onActiveCellChanged = (_, activeCell) => {
+            var _a;
+            if (this._activeCell !== activeCell) {
+                (_a = this._activeCell) === null || _a === void 0 ? void 0 : _a.model.stateChanged.disconnect(this._cellStateChange);
+                this._activeCell = activeCell;
+                activeCell === null || activeCell === void 0 ? void 0 : activeCell.ready.then(() => {
+                    var _a, _b;
+                    (_a = this._activeCell) === null || _a === void 0 ? void 0 : _a.model.stateChanged.connect(this._cellStateChange);
+                    this._available = !!this._activeCell && this._notebookVisible;
+                    this._availabilityChanged.emit(this._available);
+                    (_b = this._activeCell) === null || _b === void 0 ? void 0 : _b.disposed.connect(() => {
+                        this._activeCell = null;
+                    });
+                });
+            }
+        };
+        /**
+         * Handle the change of the active cell state.
+         */
+        this._cellStateChange = (_, change) => {
+            var _a;
+            if (change.name === 'executionCount') {
+                const currSharedModel = (_a = this._activeCell) === null || _a === void 0 ? void 0 : _a.model.sharedModel;
+                const prevActiveCellError = this._activeCellError;
+                let currActiveCellError = null;
+                if (currSharedModel && 'outputs' in currSharedModel) {
+                    currActiveCellError =
+                        currSharedModel.outputs.find((output) => 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);
+                }
+            }
+        };
+        /**
+         * Whether the current notebook panel is visible or not.
+         */
+        this._notebookVisible = false;
+        /**
+         * The active cell.
+         */
+        this._activeCell = null;
+        this._available = false;
+        this._activeCellError = null;
+        this._availabilityChanged = new Signal(this);
+        this._activeCellErrorChanged = new Signal(this);
+        this._notebookTracker = options.tracker;
+        this._notebookTracker.activeCellChanged.connect(this._onActiveCellChanged);
+        (_a = options.shell.currentChanged) === null || _a === void 0 ? void 0 : _a.connect(this._onMainAreaChanged);
+        if (options.shell instanceof LabShell) {
+            (_b = options.shell.layoutModified) === null || _b === void 0 ? void 0 : _b.connect(this._onMainAreaChanged);
+        }
+        this._onMainAreaChanged();
+    }
+    /**
+     * Whether the notebook is available and an active cell exists.
+     */
+    get available() {
+        return this._available;
+    }
+    /**
+     * The `CellError` output within the active cell, if any.
+     */
+    get activeCellError() {
+        return this._activeCellError;
+    }
+    /**
+     * A signal emitting when the active cell changed.
+     */
+    get availabilityChanged() {
+        return this._availabilityChanged;
+    }
+    /**
+     * A signal emitting when the error state of the active cell changed.
+     */
+    get activeCellErrorChanged() {
+        return this._activeCellErrorChanged;
+    }
+    getContent(withError = false) {
+        var _a;
+        const sharedModel = (_a = this._notebookTracker.activeCell) === null || _a === void 0 ? void 0 : _a.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) {
+        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) {
+        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) {
+        var _a;
+        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.
+         */
+        (_a = activeCell.editor) === null || _a === void 0 ? void 0 : _a.model.sharedModel.setSource(content);
+    }
+}

package/lib/components/chat-input.d.ts

@@ -1,5 +1,7 @@
 /// <reference types="react" />
 import { SxProps, Theme } from '@mui/material';
+import { IChatModel } from '../model';
+import { IAutocompletionRegistry } from '../registry';
 export declare function ChatInput(props: ChatInput.IProps): JSX.Element;
 /**
  * The chat input namespace.
@@ -9,6 +11,10 @@ export declare namespace ChatInput {
      * The properties of the react element.
      */
     interface IProps {
+        /**
+         * The chat model.
+         */
+        model: IChatModel;
         /**
          * The initial value of the input (default to '')
          */
@@ -21,13 +27,17 @@ export declare 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;
     }
 }

package/lib/components/chat-input.js

@@ -2,19 +2,86 @@
  * Copyright (c) Jupyter Development Team.
  * Distributed under the terms of the Modified BSD License.
  */
-import React, { useState } from 'react';
-import { Box, TextField, IconButton, InputAdornment } from '@mui/material';
+import React, { useEffect, useRef, useState } from 'react';
+import { Autocomplete, Box, IconButton, InputAdornment, TextField } from '@mui/material';
 import { Send, Cancel } from '@mui/icons-material';
 import clsx from 'clsx';
 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) {
+    var _a, _b;
+    const { autocompletionName, autocompletionRegistry, model } = props;
+    const autocompletion = useRef();
     const [input, setInput] = useState(props.value || '');
+    const [sendWithShiftEnter, setSendWithShiftEnter] = useState((_a = model.config.sendWithShiftEnter) !== null && _a !== void 0 ? _a : false);
+    useEffect(() => {
+        model.configChanged.connect((_, config) => {
+            var _a;
+            setSendWithShiftEnter((_a = config.sendWithShiftEnter) !== null && _a !== void 0 ? _a : false);
+        });
+    }, [model]);
+    // The autocomplete commands options.
+    const [commandOptions, setCommandOptions] = useState([]);
+    // whether any option is highlighted in the slash command autocomplete
+    const [highlighted, setHighlighted] = useState(false);
+    // controls whether the slash command autocomplete is open
+    const [open, setOpen] = useState(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) => {
+                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(() => {
+        var _a, _b;
+        if (!((_a = autocompletion.current) === null || _a === void 0 ? void 0 : _a.opener)) {
+            return;
+        }
+        if (input === ((_b = autocompletion.current) === null || _b === void 0 ? void 0 : _b.opener)) {
+            setOpen(true);
+            return;
+        }
+        if (input === '') {
+            setOpen(false);
+            return;
+        }
+    }, [input]);
     function handleKeyDown(event) {
+        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();
             event.preventDefault();
@@ -35,7 +102,7 @@ export function ChatInput(props) {
         props.onCancel();
     }
     // Set the helper text based on whether Shift+Enter is used for sending.
-    const helperText = props.sendWithShiftEnter ? (React.createElement("span", null,
+    const helperText = sendWithShiftEnter ? (React.createElement("span", null,
         "Press ",
         React.createElement("b", null, "Shift"),
         "+",
@@ -47,14 +114,55 @@ export function ChatInput(props) {
         React.createElement("b", null, "Enter"),
         " to add a new line"));
     return (React.createElement(Box, { sx: props.sx, className: clsx(INPUT_BOX_CLASS) },
-        React.createElement(Box, { sx: { display: 'flex' } },
-            React.createElement(TextField, { value: input, onChange: e => setInput(e.target.value), fullWidth: true, variant: "outlined", multiline: true, onKeyDown: handleKeyDown, placeholder: "Start chatting", InputProps: {
+        React.createElement(Autocomplete, { options: commandOptions, value: props.value, open: open, autoHighlight: true, freeSolo: true, 
+            // 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 => (React.createElement(TextField, { ...params, fullWidth: true, variant: "outlined", multiline: true, onKeyDown: handleKeyDown, placeholder: "Start chatting", InputProps: {
+                    ...params.InputProps,
                     endAdornment: (React.createElement(InputAdornment, { position: "end" },
-                        props.onCancel && (React.createElement(IconButton, { size: "small", color: "primary", onClick: onCancel, disabled: !input.trim().length, title: 'Cancel edition', className: clsx(CANCEL_BUTTON_CLASS) },
+                        props.onCancel && (React.createElement(IconButton, { size: "small", color: "primary", onClick: onCancel, title: 'Cancel edition', className: clsx(CANCEL_BUTTON_CLASS) },
                             React.createElement(Cancel, null))),
-                        React.createElement(IconButton, { size: "small", color: "primary", onClick: onSend, disabled: !input.trim().length, title: `Send message ${props.sendWithShiftEnter ? '(SHIFT+ENTER)' : '(ENTER)'}`, className: clsx(SEND_BUTTON_CLASS) },
+                        React.createElement(IconButton, { size: "small", color: "primary", onClick: onSend, disabled: props.onCancel
+                                ? input === props.value
+                                : !input.trim().length, title: `Send message ${sendWithShiftEnter ? '(SHIFT+ENTER)' : '(ENTER)'}`, className: clsx(SEND_BUTTON_CLASS) },
                             React.createElement(Send, null))))
                 }, FormHelperTextProps: {
                     sx: { marginLeft: 'auto', marginRight: 0 }
-                }, helperText: input.length > 2 ? helperText : ' ' }))));
+                }, helperText: input.length > 2 ? helperText : ' ' })), ...(_b = autocompletion.current) === null || _b === void 0 ? void 0 : _b.props, inputValue: input, onInputChange: (_, newValue) => {
+                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: true })));
 }

package/lib/components/chat-messages.d.ts

@@ -1,32 +1,62 @@
-/// <reference types="react" />
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import type { SxProps, Theme } from '@mui/material';
+import React from 'react';
 import { IChatModel } from '../model';
-import { IChatMessage, IUser } from '../types';
+import { IChatMessage } from '../types';
+/**
+ * The base components props.
+ */
 type BaseMessageProps = {
     rmRegistry: IRenderMimeRegistry;
     model: IChatModel;
 };
-type ChatMessageProps = BaseMessageProps & {
+/**
+ * The messages list component.
+ */
+export declare function ChatMessages(props: BaseMessageProps): JSX.Element;
+/**
+ * The message header props.
+ */
+type ChatMessageHeaderProps = {
     message: IChatMessage;
-};
-type ChatMessagesProps = BaseMessageProps & {
-    messages: IChatMessage[];
-};
-export type ChatMessageHeaderProps = IUser & {
-    timestamp: number;
-    rawTime?: boolean;
-    deleted?: boolean;
-    edited?: boolean;
     sx?: SxProps<Theme>;
 };
+/**
+ * The message header component.
+ */
 export declare function ChatMessageHeader(props: ChatMessageHeaderProps): JSX.Element;
 /**
- * The messages list UI.
+ * The message component props.
  */
-export declare function ChatMessages(props: ChatMessagesProps): JSX.Element;
+type ChatMessageProps = BaseMessageProps & {
+    /**
+     * The message to display.
+     */
+    message: IChatMessage;
+    /**
+     * The index of the message in the list.
+     */
+    index: number;
+    /**
+     * The intersection observer for all the messages.
+     */
+    observer: IntersectionObserver | null;
+};
 /**
- * the message UI.
+ * The message component body.
  */
 export declare function ChatMessage(props: ChatMessageProps): JSX.Element;
+/**
+ * The navigation component props.
+ */
+type NavigationProps = BaseMessageProps & {
+    /**
+     * The reference to the messages container.
+     */
+    refMsgBox: React.RefObject<HTMLDivElement>;
+};
+/**
+ * The navigation component, to navigate to unread messages.
+ */
+export declare function Navigation(props: NavigationProps): JSX.Element;
 export {};