@jupyter/chat 0.13.0 → 0.15.0

package/src/components/messages/navigation.tsx

@@ -0,0 +1,167 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { Button } from '@jupyter/react-components';
+import {
+  LabIcon,
+  caretDownEmptyIcon,
+  classes
+} from '@jupyterlab/ui-components';
+import React, { useEffect, useState } from 'react';
+
+import { BaseMessageProps } from './messages';
+import { IChatModel } from '../../model';
+
+const NAVIGATION_BUTTON_CLASS = 'jp-chat-navigation';
+const NAVIGATION_UNREAD_CLASS = 'jp-chat-navigation-unread';
+const NAVIGATION_TOP_CLASS = 'jp-chat-navigation-top';
+const NAVIGATION_BOTTOM_CLASS = 'jp-chat-navigation-bottom';
+
+/**
+ * The navigation component props.
+ */
+type NavigationProps = BaseMessageProps & {
+  /**
+   * The reference to the messages container.
+   */
+  refMsgBox: React.RefObject<HTMLDivElement>;
+  /**
+   * Whether all the messages has been rendered once on first display.
+   */
+  allRendered: boolean;
+};
+
+/**
+ * The navigation component, to navigate to unread messages.
+ */
+export function Navigation(props: NavigationProps): JSX.Element {
+  const { model } = props;
+  const [lastInViewport, setLastInViewport] = useState<boolean>(true);
+  const [unreadBefore, setUnreadBefore] = useState<number | null>(null);
+  const [unreadAfter, setUnreadAfter] = useState<number | null>(null);
+
+  const gotoMessage = (msgIdx: number, alignToTop: boolean = true) => {
+    props.refMsgBox.current?.children.item(msgIdx)?.scrollIntoView(alignToTop);
+  };
+
+  // Listen for change in unread messages, and find the first unread message before or
+  // after the current viewport, to display navigation buttons.
+  useEffect(() => {
+    // Do not attempt to display navigation until messages are rendered, it can lead to
+    // wrong assumption, because more messages are in the viewport before they are
+    // rendered.
+    if (!props.allRendered) {
+      return;
+    }
+
+    const unreadChanged = (model: IChatModel, unreadIndexes: number[]) => {
+      const viewport = model.messagesInViewport;
+      if (!viewport) {
+        return;
+      }
+
+      // Initialize the next values with the current values if there still relevant.
+      let before =
+        unreadBefore !== null &&
+        unreadIndexes.includes(unreadBefore) &&
+        unreadBefore < Math.min(...viewport)
+          ? unreadBefore
+          : null;
+
+      let after =
+        unreadAfter !== null &&
+        unreadIndexes.includes(unreadAfter) &&
+        unreadAfter > Math.max(...viewport)
+          ? unreadAfter
+          : null;
+
+      unreadIndexes.forEach(unread => {
+        if (viewport?.includes(unread)) {
+          return;
+        }
+        if (unread < (before ?? Math.min(...viewport))) {
+          before = unread;
+        } else if (
+          unread > Math.max(...viewport) &&
+          unread < (after ?? model.messages.length)
+        ) {
+          after = unread;
+        }
+      });
+
+      setUnreadBefore(before);
+      setUnreadAfter(after);
+    };
+
+    model.unreadChanged?.connect(unreadChanged);
+
+    unreadChanged(model, model.unreadMessages);
+
+    // Move to the last the message after all the messages have been first rendered.
+    gotoMessage(model.messages.length - 1, false);
+
+    return () => {
+      model.unreadChanged?.disconnect(unreadChanged);
+    };
+  }, [model, props.allRendered]);
+
+  // Listen for change in the viewport, to add a navigation button if the last is not
+  // in viewport.
+  useEffect(() => {
+    const viewportChanged = (model: IChatModel, viewport: number[]) => {
+      setLastInViewport(
+        model.messages.length === 0 ||
+          viewport.includes(model.messages.length - 1)
+      );
+    };
+
+    model.viewportChanged?.connect(viewportChanged);
+
+    viewportChanged(model, model.messagesInViewport ?? []);
+
+    return () => {
+      model.viewportChanged?.disconnect(viewportChanged);
+    };
+  }, [model]);
+
+  return (
+    <>
+      {unreadBefore !== null && (
+        <Button
+          className={`${NAVIGATION_BUTTON_CLASS} ${NAVIGATION_UNREAD_CLASS} ${NAVIGATION_TOP_CLASS}`}
+          onClick={() => gotoMessage!(unreadBefore)}
+          title={'Go to unread messages'}
+        >
+          <LabIcon.resolveReact
+            display={'flex'}
+            icon={caretDownEmptyIcon}
+            iconClass={classes('jp-Icon')}
+          />
+        </Button>
+      )}
+      {(unreadAfter !== null || !lastInViewport) && (
+        <Button
+          className={`${NAVIGATION_BUTTON_CLASS} ${unreadAfter !== null ? NAVIGATION_UNREAD_CLASS : ''} ${NAVIGATION_BOTTOM_CLASS}`}
+          onClick={
+            unreadAfter === null
+              ? () => gotoMessage(model.messages.length - 1, false)
+              : () => gotoMessage(unreadAfter)
+          }
+          title={
+            unreadAfter !== null
+              ? 'Go to unread messages'
+              : 'Go to last message'
+          }
+        >
+          <LabIcon.resolveReact
+            display={'flex'}
+            icon={caretDownEmptyIcon}
+            iconClass={classes('jp-Icon')}
+          />
+        </Button>
+      )}
+    </>
+  );
+}

package/src/components/messages/welcome.tsx

@@ -5,6 +5,7 @@
 
 import { classes } from '@jupyterlab/ui-components';
 import React, { useEffect, useRef } from 'react';
+
 import { MarkdownRenderer, MD_RENDERED_CLASS } from '../../markdown-renderer';
 
 const WELCOME_MESSAGE_CLASS = 'jp-chat-welcome-message';

package/src/components/messages/writers.tsx

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { Box, Typography } from '@mui/material';
+import React, { useMemo } from 'react';
+
+import { Avatar } from '../avatar';
+import { IUser } from '../../types';
+
+const WRITERS_CLASS = 'jp-chat-writers';
+
+/**
+ * The writers component props.
+ */
+type writersProps = {
+  /**
+   * The list of users currently writing.
+   */
+  writers: IUser[];
+};
+
+/**
+ * Animated typing indicator component
+ */
+const TypingIndicator = (): JSX.Element => (
+  <Box className="jp-chat-typing-indicator">
+    <span className="jp-chat-typing-dot"></span>
+    <span className="jp-chat-typing-dot"></span>
+    <span className="jp-chat-typing-dot"></span>
+  </Box>
+);
+
+/**
+ * The writers component, displaying the current writers.
+ */
+export function WritingUsersList(props: writersProps): JSX.Element | null {
+  const { writers } = props;
+
+  // Don't render if no writers
+  if (writers.length === 0) {
+    return null;
+  }
+
+  const writersText = writers.length > 1 ? ' are writing' : ' is writing';
+
+  const writingUsers: JSX.Element[] = useMemo(
+    () =>
+      writers.map((writer, index) => (
+        <Box key={writer.username || index} className="jp-chat-writer-item">
+          <Avatar user={writer} small />
+          <Typography variant="body2" className="jp-chat-writer-name">
+            {writer.display_name ??
+              writer.name ??
+              (writer.username || 'User undefined')}
+          </Typography>
+          {index < writers.length - 1 && (
+            <Typography variant="body2" className="jp-chat-writer-separator">
+              {index < writers.length - 2 ? ', ' : ' and '}
+            </Typography>
+          )}
+        </Box>
+      )),
+    [writers]
+  );
+
+  return (
+    <Box className={`${WRITERS_CLASS}`}>
+      <Box className="jp-chat-writers-content">
+        {writingUsers}
+        <Box className="jp-chat-writing-status">
+          <Typography variant="body2" className="jp-chat-writing-text">
+            {writersText}
+          </Typography>
+          <TypingIndicator />
+        </Box>
+      </Box>
+    </Box>
+  );
+}

package/src/context.ts

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { createContext } from 'react';
-import { IAttachmentOpenerRegistry } from './registry';
+import { IAttachmentOpenerRegistry } from './registers';
 
 export const AttachmentOpenerContext = createContext<
   IAttachmentOpenerRegistry | undefined

package/src/index.ts

@@ -4,16 +4,12 @@
  */
 
 export * from './active-cell-manager';
-export * from './chat-commands';
 export * from './components';
-export * from './footers';
 export * from './icons';
 export * from './input-model';
 export * from './markdown-renderer';
 export * from './model';
-export * from './registry';
+export * from './registers';
 export * from './selection-watcher';
 export * from './types';
-export * from './widgets/chat-error';
-export * from './widgets/chat-sidebar';
-export * from './widgets/chat-widget';
+export * from './widgets';

package/src/input-model.ts

@@ -11,8 +11,6 @@ import { ISelectionWatcher } from './selection-watcher';
 import { IChatContext } from './model';
 import { IAttachment, IUser } from './types';
 
-const WHITESPACE = new Set([' ', '\n', '\t']);
-
 /**
  * The chat input interface.
  */
@@ -525,6 +523,18 @@ export namespace InputModel {
 }
 
 namespace Private {
+  const WHITESPACE = new Set([' ', '\n', '\t']);
+
+  /**
+   * Returns the start index (inclusive) & end index (exclusive) that contain
+   * the current word. The start & end index can be passed to `String.slice()`
+   * to extract the current word. The returned range never includes any
+   * whitespace character unless it is escaped by a backslash `\`.
+   *
+   * NOTE: the escape sequence handling here is naive and non-recursive. This
+   * function considers the space in "`\\ `" as escaped, even though "`\\ `"
+   * defines a backslash followed by an _unescaped_ space in most languages.
+   */
   export function getCurrentWordBoundaries(
     input: string,
     cursorIndex: number
@@ -533,11 +543,30 @@ namespace Private {
     let end = cursorIndex;
     const n = input.length;
 
-    while (start > 0 && !WHITESPACE.has(input[start - 1])) {
+    while (
+      // terminate when `input[start - 1]` is whitespace
+      // i.e. `input[start]` is never whitespace after exiting
+      (start - 1 >= 0 && !WHITESPACE.has(input[start - 1])) ||
+      // unless it is preceded by a backslash
+      (start - 2 >= 0 &&
+        input[start - 2] === '\\' &&
+        WHITESPACE.has(input[start - 1]))
+    ) {
       start--;
     }
 
-    while (end < n && !WHITESPACE.has(input[end])) {
+    // `end` is an exclusive index unlike `start`, hence the different `while`
+    // condition here
+    while (
+      // terminate when `input[end]` is whitespace
+      // i.e. `input[end]` may be whitespace after exiting
+      (end < n && !WHITESPACE.has(input[end])) ||
+      // unless it is preceded by a backslash
+      (end < n &&
+        end - 1 >= 0 &&
+        input[end - 1] === '\\' &&
+        WHITESPACE.has(input[end]))
+    ) {
       end++;
     }
 

package/src/{registry.ts → registers/attachment-openers.ts}

@@ -2,8 +2,9 @@
  * Copyright (c) Jupyter Development Team.
  * Distributed under the terms of the Modified BSD License.
  */
+
 import { Token } from '@lumino/coreutils';
-import { IAttachment } from './types';
+import { IAttachment } from '../types';
 
 /**
  * The token for the attachments opener registry, which can be provided by an extension

package/src/registers/chat-commands.ts

@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { LabIcon } from '@jupyterlab/ui-components';
+import { Token } from '@lumino/coreutils';
+import { IInputModel } from '../input-model';
+
+/**
+ * The token for the chat command registry, which can be provided by an extension
+ * using @jupyter/chat package.
+ */
+export const IChatCommandRegistry = new Token<IChatCommandRegistry>(
+  '@jupyter/chat:IChatCommandRegistry'
+);
+
+/**
+ * Interface of a chat command registry, which tracks a list of chat command
+ * providers. Providers provide a list of commands given a user's partial input,
+ * and define how commands are handled when accepted in the chat commands menu.
+ */
+export interface IChatCommandRegistry {
+  /**
+   * Adds a chat command provider to the registry.
+   */
+  addProvider(provider: IChatCommandProvider): void;
+
+  /**
+   * Lists all chat command providers previously added via `addProvider()`.
+   */
+  getProviders(): IChatCommandProvider[];
+
+  /**
+   * Calls `onSubmit()` on each command provider in serial. Each command
+   * provider's `onSubmit()` method is responsible for checking the entire input
+   * for command calls and handling them accordingly.
+   *
+   * This method is called by the application after the user presses the "Send"
+   * button but before the message is sent to server.
+   */
+  onSubmit(inputModel: IInputModel): Promise<void>;
+}
+
+export type ChatCommand = {
+  /**
+   * The name of the command. This defines what the user should type in the
+   * input to have the command appear in the chat commands menu.
+   */
+  name: string;
+
+  /**
+   * ID of the provider the command originated from.
+   */
+  providerId: string;
+
+  /**
+   * If set, this will be rendered as the icon for the command in the chat
+   * commands menu. Jupyter Chat will choose a default if this is unset.
+   */
+  icon?: LabIcon | JSX.Element | string | null;
+
+  /**
+   * If set, this will be rendered as the description for the command in the
+   * chat commands menu. Jupyter Chat will choose a default if this is unset.
+   */
+  description?: string;
+
+  /**
+   * If set, Jupyter Chat will replace the current word with this string immediately when
+   * the command is accepted from the chat commands menu or the current word
+   * matches the command's `name` exactly.
+   *
+   * This is generally used by "shortcut command" providers, e.g. the emoji
+   * command provider.
+   */
+  replaceWith?: string;
+
+  /**
+   * Specifies whether the application should add a space ' ' after the command
+   * is accepted from the menu. This should be set to `true` if the command that
+   * replaces the current word needs to be handled on submit, and the command is
+   * valid on its own.
+   *
+   * Defaults to `false`.
+   */
+  spaceOnAccept?: boolean;
+};
+
+/**
+ * Interface of a command provider.
+ */
+export interface IChatCommandProvider {
+  /**
+   * ID of this command provider.
+   */
+  id: string;
+
+  /**
+   * A method that should return the list of valid chat commands whose names
+   * complete the current word.
+   *
+   * The current word should be accessed from `inputModel.currentWord`.
+   */
+  listCommandCompletions(inputModel: IInputModel): Promise<ChatCommand[]>;
+
+  /**
+   * A method that should identify and handle *all* command calls within a
+   * message that the user intends to submit. This method is called after a user
+   * presses the "Send" button but before the message is sent to the server.
+   *
+   * The entire message should be read from `inputModel.value`. This method may
+   * modify the new message before submission by setting `inputModel.value` or
+   * by calling other methods available on `inputModel`.
+   */
+  onSubmit(inputModel: IInputModel): Promise<void>;
+}
+
+/**
+ * Default chat command registry implementation.
+ */
+export class ChatCommandRegistry implements IChatCommandRegistry {
+  constructor() {
+    this._providers = new Map<string, IChatCommandProvider>();
+  }
+
+  addProvider(provider: IChatCommandProvider): void {
+    this._providers.set(provider.id, provider);
+  }
+
+  getProviders(): IChatCommandProvider[] {
+    return Array.from(this._providers.values());
+  }
+
+  async onSubmit(inputModel: IInputModel) {
+    for (const provider of this._providers.values()) {
+      await provider.onSubmit(inputModel);
+    }
+  }
+
+  private _providers: Map<string, IChatCommandProvider>;
+}

package/src/{footers/registry.ts → registers/footers.ts}

@@ -4,7 +4,15 @@
  */
 
 import { Token } from '@lumino/coreutils';
-import { MessageFooter, MessageFooterSection } from './types';
+import { IChatModel } from '../model';
+import { IChatMessage } from '../types';
+
+/**
+ * The token providing the chat footer registry.
+ */
+export const IMessageFooterRegistry = new Token<IMessageFooterRegistry>(
+  '@jupyter/chat:ChatFooterRegistry'
+);
 
 /**
  * The interface of a registry to provide chat footer.
@@ -22,6 +30,32 @@ export interface IMessageFooterRegistry {
   addSection(section: MessageFooterSection): void;
 }
 
+/**
+ * The props sent passed to each `MessageFooterSection` React component.
+ */
+export type MessageFooterSectionProps = {
+  model: IChatModel;
+  message: IChatMessage;
+};
+
+/**
+ * A message footer section which can be added to the footer registry.
+ */
+export type MessageFooterSection = {
+  component: React.FC<MessageFooterSectionProps>;
+  position: 'left' | 'center' | 'right';
+};
+
+/**
+ * The message footer returned by the registry, composed of 'left', 'center',
+ * and 'right' sections.
+ */
+export type MessageFooter = {
+  left?: MessageFooterSection;
+  center?: MessageFooterSection;
+  right?: MessageFooterSection;
+};
+
 /**
  * The default implementation of the message footer registry.
  */
@@ -43,10 +77,3 @@ export class MessageFooterRegistry implements IMessageFooterRegistry {
 
   private _footers: MessageFooter = {};
 }
-
-/**
- * The token providing the chat footer registry.
- */
-export const IMessageFooterRegistry = new Token<IMessageFooterRegistry>(
-  '@jupyter/chat:ChatFooterRegistry'
-);

package/src/{footers → registers}/index.ts

@@ -3,5 +3,6 @@
  * Distributed under the terms of the Modified BSD License.
  */
 
-export * from './registry';
-export * from './types';
+export * from './attachment-openers';
+export * from './chat-commands';
+export * from './footers';

package/src/selection-watcher.ts

@@ -6,6 +6,10 @@
 import { JupyterFrontEnd } from '@jupyterlab/application';
 import { DocumentWidget } from '@jupyterlab/docregistry';
 import { CodeEditor } from '@jupyterlab/codeeditor';
+import {
+  EditorLanguageRegistry,
+  IEditorLanguageRegistry
+} from '@jupyterlab/codemirror';
 import { Notebook } from '@jupyterlab/notebook';
 
 import { find } from '@lumino/algorithm';
@@ -26,6 +30,10 @@ export namespace SelectionWatcher {
      * The current shell of the application.
      */
     shell: JupyterFrontEnd.IShell;
+    /**
+     * Editor language registry.
+     */
+    languages?: IEditorLanguageRegistry;
   }
 
   /**
@@ -44,6 +52,10 @@ export namespace SelectionWatcher {
      * The ID of the document widget in which the selection was made.
      */
     widgetId: string;
+    /**
+     * The language of the selection.
+     */
+    language?: string;
     /**
      * The ID of the cell in which the selection was made, if the original widget
      * was a notebook.
@@ -70,6 +82,7 @@ export interface ISelectionWatcher {
 export class SelectionWatcher {
   constructor(options: SelectionWatcher.IOptions) {
     this._shell = options.shell;
+    this._languages = options.languages || new EditorLanguageRegistry();
     this._shell.currentChanged?.connect((sender, args) => {
       // Do not change the main area widget if the new one has no editor, for example
       // a chat panel. However, the selected text is only available if the main area
@@ -149,12 +162,15 @@ export class SelectionWatcher {
     editor.setSelection({ start: newPosition, end: newPosition });
   }
 
-  protected _poll(): void {
+  protected async _poll(): Promise<void> {
     let currSelection: SelectionWatcher.Selection | null = null;
     const prevSelection = this._selection;
     // Do not return selected text if the main area widget is hidden.
     if (this._mainAreaDocumentWidget?.isVisible) {
-      currSelection = getTextSelection(this._mainAreaDocumentWidget);
+      currSelection = await getTextSelection(
+        this._mainAreaDocumentWidget,
+        this._languages
+      );
     }
     if (prevSelection?.text !== currSelection?.text) {
       this._selection = currSelection;
@@ -169,14 +185,16 @@ export class SelectionWatcher {
     this,
     SelectionWatcher.Selection | null
   >(this);
+  private _languages: IEditorLanguageRegistry;
 }
 
 /**
  * Gets a Selection object from a document widget. Returns `null` if unable.
  */
-function getTextSelection(
-  widget: Widget | null
-): SelectionWatcher.Selection | null {
+async function getTextSelection(
+  widget: Widget | null,
+  languages: IEditorLanguageRegistry
+): Promise<SelectionWatcher.Selection | null> {
   const editor = getEditor(widget);
   // widget type check is redundant but hints the type to TypeScript
   if (!editor || !(widget instanceof DocumentWidget)) {
@@ -207,6 +225,7 @@ function getTextSelection(
     [start, end] = [end, start];
   }
 
+  const language = (await languages.getLanguage(editor?.model.mimeType))?.name;
   return {
     ...selectionObj,
     start,
@@ -214,6 +233,10 @@ function getTextSelection(
     text,
     numLines: text.split('\n').length,
     widgetId: widget.id,
+
+    ...(language && {
+      language
+    }),
     ...(cellId && {
       cellId
     })

package/src/types.ts

@@ -14,9 +14,14 @@ export interface IUser {
   color?: string;
   avatar_url?: string;
   /**
-   * The string to use to mention a user in the chat.
+   * The string to use to mention a user in the chat. This is computed via the
+   * following procedure:
+   *
+   * 1. Let `mention_name = user.display_name || user.name || user.username`.
+   *
+   * 2. Replace each ' ' character with '-' in `mention_name`.
    */
-  mention_name?: string;
+  mention_name: string;
   /**
    * Boolean identifying if user is a bot.
    */