@jupyter/chat 0.9.0 → 0.10.0

package/lib/utils.js

@@ -6,6 +6,7 @@ import { CodeMirrorEditor } from '@jupyterlab/codemirror';
 import { DocumentWidget } from '@jupyterlab/docregistry';
 import { FileEditor } from '@jupyterlab/fileeditor';
 import { Notebook } from '@jupyterlab/notebook';
+const MENTION_CLASS = 'jp-chat-mention';
 /**
  * Gets the editor instance used by a document widget. Returns `null` if unable.
  */
@@ -35,3 +36,31 @@ export function getCellIndex(notebook, cellId) {
     const idx = (_a = notebook.model) === null || _a === void 0 ? void 0 : _a.sharedModel.cells.findIndex(cell => cell.getId() === cellId);
     return idx === undefined ? -1 : idx;
 }
+/**
+ * Replace a mention to user (@someone) to a span, for markdown renderer.
+ *
+ * @param content - the content to update.
+ * @param user - the user mentioned.
+ */
+export function replaceMentionToSpan(content, user) {
+    if (!user.mention_name) {
+        return content;
+    }
+    const regex = new RegExp(user.mention_name, 'g');
+    const mention = `<span class="${MENTION_CLASS}">${user.mention_name}</span>`;
+    return content.replace(regex, mention);
+}
+/**
+ * Replace a span to a mentioned to user string (@someone).
+ *
+ * @param content - the content to update.
+ * @param user - the user mentioned.
+ */
+export function replaceSpanToMention(content, user) {
+    if (!user.mention_name) {
+        return content;
+    }
+    const span = `<span class="${MENTION_CLASS}">${user.mention_name}</span>`;
+    const regex = new RegExp(span, 'g');
+    return content.replace(regex, user.mention_name);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyter/chat",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A package that provides UI components that can be used to create a chat in a Jupyterlab extension.",
   "keywords": [
     "jupyter",

package/src/__tests__/mocks.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import {
+  AbstractChatContext,
+  AbstractChatModel,
+  IChatModel,
+  IChatContext
+} from '../model';
+import { INewMessage } from '../types';
+
+export class MockChatContext
+  extends AbstractChatContext
+  implements IChatContext
+{
+  get users() {
+    return [];
+  }
+}
+
+export class MockChatModel extends AbstractChatModel implements IChatModel {
+  sendMessage(message: INewMessage): Promise<boolean | void> | boolean | void {
+    // No-op
+  }
+
+  createChatContext(): IChatContext {
+    return new MockChatContext({ model: this });
+  }
+}

package/src/__tests__/model.spec.ts

@@ -7,29 +7,39 @@
  * Example of [Jest](https://jestjs.io/docs/getting-started) unit tests
  */
 
-import { ChatModel, IChatModel } from '../model';
-import { IChatMessage } from '../types';
+import { AbstractChatModel, IChatContext, IChatModel } from '../model';
+import { IChatMessage, INewMessage } from '../types';
+import { MockChatModel, MockChatContext } from './mocks';
 
 describe('test chat model', () => {
   describe('model instantiation', () => {
-    it('should create a ChatModel', () => {
-      const model = new ChatModel();
-      expect(model).toBeInstanceOf(ChatModel);
+    it('should create an AbstractChatModel', () => {
+      const model = new MockChatModel();
+      expect(model).toBeInstanceOf(AbstractChatModel);
     });
 
-    it('should dispose a ChatModel', () => {
-      const model = new ChatModel();
+    it('should dispose an AbstractChatModel', () => {
+      const model = new MockChatModel();
       model.dispose();
       expect(model.isDisposed).toBeTruthy();
     });
   });
 
   describe('incoming message', () => {
-    class TestChat extends ChatModel {
+    class TestChat extends AbstractChatModel implements IChatModel {
       protected formatChatMessage(message: IChatMessage): IChatMessage {
         message.body = 'formatted msg';
         return message;
       }
+      sendMessage(
+        message: INewMessage
+      ): Promise<boolean | void> | boolean | void {
+        // No-op
+      }
+
+      createChatContext(): IChatContext {
+        return new MockChatContext({ model: this });
+      }
     }
 
     let model: IChatModel;
@@ -47,7 +57,7 @@ describe('test chat model', () => {
     });
 
     it('should signal incoming message', () => {
-      model = new ChatModel();
+      model = new MockChatModel();
       model.messagesUpdated.connect((sender: IChatModel) => {
         expect(sender).toBe(model);
         messages = model.messages;
@@ -72,12 +82,12 @@ describe('test chat model', () => {
 
   describe('model config', () => {
     it('should have empty config', () => {
-      const model = new ChatModel();
+      const model = new MockChatModel();
       expect(model.config.sendWithShiftEnter).toBeUndefined();
     });
 
     it('should allow config', () => {
-      const model = new ChatModel({ config: { sendWithShiftEnter: true } });
+      const model = new MockChatModel({ config: { sendWithShiftEnter: true } });
       expect(model.config.sendWithShiftEnter).toBeTruthy();
     });
   });

package/src/__tests__/widgets.spec.ts

@@ -11,25 +11,26 @@ import {
   IRenderMimeRegistry,
   RenderMimeRegistry
 } from '@jupyterlab/rendermime';
-import { ChatModel, IChatModel } from '../model';
+import { IChatModel } from '../model';
 import { ChatWidget } from '../widgets/chat-widget';
+import { MockChatModel } from './mocks';
 
 describe('test chat widget', () => {
   let model: IChatModel;
   let rmRegistry: IRenderMimeRegistry;
 
   beforeEach(() => {
-    model = new ChatModel();
+    model = new MockChatModel();
     rmRegistry = new RenderMimeRegistry();
   });
 
   describe('model instantiation', () => {
-    it('should create a ChatModel', () => {
+    it('should create an AbstractChatModel', () => {
       const widget = new ChatWidget({ model, rmRegistry });
       expect(widget).toBeInstanceOf(ChatWidget);
     });
 
-    it('should dispose a ChatModel', () => {
+    it('should dispose an AbstractChatModel', () => {
       const widget = new ChatWidget({ model, rmRegistry });
       widget.dispose();
       expect(widget.isDisposed).toBeTruthy();

package/src/chat-commands/types.ts

@@ -22,7 +22,7 @@ export type ChatCommand = {
    * 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 | string;
+  icon?: LabIcon | JSX.Element | string | null;
 
   /**
    * If set, this will be rendered as the description for the command in the

package/src/components/chat-input.tsx

@@ -22,8 +22,8 @@ import {
   useChatCommands
 } from './input';
 import { IInputModel, InputModel } from '../input-model';
-import { IAttachment } from '../types';
 import { IChatCommandRegistry } from '../chat-commands';
+import { IAttachment } from '../types';
 
 const INPUT_BOX_CLASS = 'jp-chat-input-container';
 const INPUT_TOOLBAR_CLASS = 'jp-chat-input-toolbar';
@@ -256,7 +256,7 @@ export namespace ChatInput {
    */
   export interface IProps {
     /**
-     * The chat model.
+     * The input model.
      */
     model: IInputModel;
     /**

package/src/components/chat-messages.tsx

@@ -25,6 +25,7 @@ import { IChatCommandRegistry } from '../chat-commands';
 import { IInputModel, InputModel } from '../input-model';
 import { IChatModel } from '../model';
 import { IChatMessage, IUser } from '../types';
+import { replaceSpanToMention } from '../utils';
 
 const MESSAGES_BOX_CLASS = 'jp-chat-messages-container';
 const MESSAGE_CLASS = 'jp-chat-message';
@@ -375,19 +376,27 @@ export const ChatMessage = forwardRef<HTMLDivElement, ChatMessageProps>(
     // Create an input model only if the message is edited.
     useEffect(() => {
       if (edit && canEdit) {
-        setInputModel(
-          new InputModel({
+        setInputModel(() => {
+          let body = message.body;
+          message.mentions?.forEach(user => {
+            body = replaceSpanToMention(body, user);
+          });
+          return new InputModel({
+            chatContext: model.createChatContext(),
             onSend: (input: string, model?: IInputModel) =>
               updateMessage(message.id, input, model),
             onCancel: () => cancelEdition(),
-            value: message.body,
+            value: body,
+            activeCellManager: model.activeCellManager,
+            selectionWatcher: model.selectionWatcher,
+            documentManager: model.documentManager,
             config: {
               sendWithShiftEnter: model.config.sendWithShiftEnter
             },
             attachments: message.attachments,
-            documentManager: model.documentManager
-          })
-        );
+            mentions: message.mentions
+          });
+        });
       } else {
         setInputModel(null);
       }
@@ -411,6 +420,7 @@ export const ChatMessage = forwardRef<HTMLDivElement, ChatMessageProps>(
       const updatedMessage = { ...message };
       updatedMessage.body = input;
       updatedMessage.attachments = inputModel.attachments;
+      updatedMessage.mentions = inputModel.mentions;
       model.updateMessage!(id, updatedMessage);
       setEdit(false);
     };

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

@@ -3,13 +3,13 @@
  * Distributed under the terms of the Modified BSD License.
  */
 
-import React from 'react';
-import { useEffect, useState } from 'react';
+import { LabIcon } from '@jupyterlab/ui-components';
 import type {
   AutocompleteChangeReason,
   AutocompleteProps as GenericAutocompleteProps
 } from '@mui/material';
 import { Box } from '@mui/material';
+import React, { useEffect, useState } from 'react';
 
 import { ChatCommand, IChatCommandRegistry } from '../../chat-commands';
 import { IInputModel } from '../../input-model';
@@ -131,9 +131,11 @@ export function useChatCommands(
         ___: unknown
       ) => {
         const { key, ...listItemProps } = defaultProps;
-        const commandIcon: JSX.Element = (
+        const commandIcon: JSX.Element = React.isValidElement(command.icon) ? (
+          command.icon
+        ) : (
           <span>
-            {typeof command.icon === 'object' ? (
+            {command.icon instanceof LabIcon ? (
               <command.icon.react />
             ) : (
               command.icon

package/src/index.ts

@@ -4,6 +4,7 @@
  */
 
 export * from './active-cell-manager';
+export * from './chat-commands';
 export * from './components';
 export * from './icons';
 export * from './input-model';
@@ -14,4 +15,3 @@ 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

@@ -3,12 +3,13 @@
  * Distributed under the terms of the Modified BSD License.
  */
 
+import { IDocumentManager } from '@jupyterlab/docmanager';
 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';
-import { IDocumentManager } from '@jupyterlab/docmanager';
+import { IChatContext } from './model';
+import { IAttachment, IUser } from './types';
 
 const WHITESPACE = new Set([' ', '\n', '\t']);
 
@@ -16,6 +17,11 @@ const WHITESPACE = new Set([' ', '\n', '\t']);
  * The chat input interface.
  */
 export interface IInputModel extends IDisposable {
+  /**
+   * The chat context (a readonly subset of the chat model).
+   */
+  readonly chatContext: IChatContext;
+
   /**
    * Function to send a message.
    */
@@ -121,6 +127,26 @@ export interface IInputModel extends IDisposable {
    * Replace the current word in the input with a new one.
    */
   replaceCurrentWord(newWord: string): void;
+
+  /**
+   * The mentioned user list.
+   */
+  readonly mentions: IUser[];
+
+  /**
+   * Add user mention.
+   */
+  addMention?(user: IUser): void;
+
+  /**
+   * Remove a user mention.
+   */
+  removeMention(user: IUser): void;
+
+  /**
+   * Clear mentions list.
+   */
+  clearMentions(): void;
 }
 
 /**
@@ -129,8 +155,10 @@ export interface IInputModel extends IDisposable {
 export class InputModel implements IInputModel {
   constructor(options: InputModel.IOptions) {
     this._onSend = options.onSend;
+    this._chatContext = options.chatContext;
     this._value = options.value || '';
     this._attachments = options.attachments || [];
+    this._mentions = options.mentions || [];
     this.cursorIndex = options.cursorIndex || this.value.length;
     this._activeCellManager = options.activeCellManager ?? null;
     this._selectionWatcher = options.selectionWatcher ?? null;
@@ -141,6 +169,13 @@ export class InputModel implements IInputModel {
     this.cancel = options.onCancel;
   }
 
+  /**
+   * The chat context (a readonly subset of the chat model);
+   */
+  get chatContext(): IChatContext {
+    return this._chatContext;
+  }
+
   /**
    * Function to send a message.
    */
@@ -335,6 +370,40 @@ export class InputModel implements IInputModel {
     this.value = this.value.slice(0, start) + newWord + this.value.slice(end);
   }
 
+  /**
+   * The mentioned user list.
+   */
+  get mentions(): IUser[] {
+    return this._mentions;
+  }
+
+  /**
+   * Add a user mention.
+   */
+  addMention(user: IUser): void {
+    const usernames = this._mentions.map(user => user.username);
+    if (!usernames.includes(user.username)) {
+      this._mentions.push(user);
+    }
+  }
+
+  /**
+   * Remove a user mention.
+   */
+  removeMention(user: IUser): void {
+    const index = this._mentions.indexOf(user);
+    if (index > -1) {
+      this._mentions.splice(index, 1);
+    }
+  }
+
+  /**
+   * Clear mentions list.
+   */
+  clearMentions = (): void => {
+    this._mentions = [];
+  };
+
   /**
    * Dispose the input model.
    */
@@ -353,10 +422,12 @@ export class InputModel implements IInputModel {
   }
 
   private _onSend: (input: string, model?: InputModel) => void;
+  private _chatContext: IChatContext;
   private _value: string;
   private _cursorIndex: number | null = null;
   private _currentWord: string | null = null;
   private _attachments: IAttachment[];
+  private _mentions: IUser[];
   private _activeCellManager: IActiveCellManager | null;
   private _selectionWatcher: ISelectionWatcher | null;
   private _documentManager: IDocumentManager | null;
@@ -372,6 +443,11 @@ export class InputModel implements IInputModel {
 
 export namespace InputModel {
   export interface IOptions {
+    /**
+     * The chat context (a readonly subset of the chat model).
+     */
+    chatContext: IChatContext;
+
     /**
      * The function that should send the message.
      * @param content - the content of the message.
@@ -394,6 +470,11 @@ export namespace InputModel {
      */
     attachments?: IAttachment[];
 
+    /**
+     * The initial mentions.
+     */
+    mentions?: IUser[];
+
     /**
      * The current cursor index.
      * This refers to the index of the character in front of the cursor.

package/src/model.ts

@@ -8,6 +8,9 @@ import { CommandRegistry } from '@lumino/commands';
 import { IDisposable } from '@lumino/disposable';
 import { ISignal, Signal } from '@lumino/signaling';
 
+import { IActiveCellManager } from './active-cell-manager';
+import { IInputModel, InputModel } from './input-model';
+import { ISelectionWatcher } from './selection-watcher';
 import {
   IChatHistory,
   INewMessage,
@@ -15,9 +18,7 @@ import {
   IConfig,
   IUser
 } from './types';
-import { IActiveCellManager } from './active-cell-manager';
-import { ISelectionWatcher } from './selection-watcher';
-import { IInputModel, InputModel } from './input-model';
+import { replaceMentionToSpan } from './utils';
 
 /**
  * The chat model interface.
@@ -172,18 +173,24 @@ export interface IChatModel extends IDisposable {
    * Update the current writers list.
    */
   updateWriters(writers: IUser[]): void;
+
+  /**
+   * Create the chat context that will be passed to the input model.
+   */
+  createChatContext(): IChatContext;
 }
 
 /**
- * The default chat model implementation.
- * It is not able to send or update a message by itself, since it depends on the
- * chosen technology.
+ * An abstract implementation of IChatModel.
+ *
+ * The class inheriting from it must implement at least:
+ * - sendMessage(message: INewMessage)
  */
-export class ChatModel implements IChatModel {
+export abstract class AbstractChatModel implements IChatModel {
   /**
    * Create a new chat model.
    */
-  constructor(options: ChatModel.IOptions = {}) {
+  constructor(options: IChatModel.IOptions = {}) {
     if (options.id) {
       this.id = options.id;
     }
@@ -198,6 +205,7 @@ export class ChatModel implements IChatModel {
     };
 
     this._inputModel = new InputModel({
+      chatContext: this.createChatContext(),
       activeCellManager: options.activeCellManager,
       selectionWatcher: options.selectionWatcher,
       documentManager: options.documentManager,
@@ -421,7 +429,9 @@ export class ChatModel implements IChatModel {
    * @param message - the message to send.
    * @returns whether the message has been sent or not.
    */
-  sendMessage(message: INewMessage): Promise<boolean | void> | boolean | void {}
+  abstract sendMessage(
+    message: INewMessage
+  ): Promise<boolean | void> | boolean | void;
 
   /**
    * Clear the message list.
@@ -453,6 +463,9 @@ export class ChatModel implements IChatModel {
    * Can be useful if some actions are required on the message.
    */
   protected formatChatMessage(message: IChatMessage): IChatMessage {
+    message.mentions?.forEach(user => {
+      message.body = replaceMentionToSpan(message.body, user);
+    });
     return message;
   }
 
@@ -537,6 +550,11 @@ export class ChatModel implements IChatModel {
     this._writersChanged.emit(writers);
   }
 
+  /**
+   * Create the chat context that will be passed to the input model.
+   */
+  abstract createChatContext(): IChatContext;
+
   /**
    * Add unread messages to the list.
    * @param indexes - list of new indexes.
@@ -609,7 +627,7 @@ export class ChatModel implements IChatModel {
 /**
  * The chat model namespace.
  */
-export namespace ChatModel {
+export namespace IChatModel {
   /**
    * The instantiation options for a ChatModel.
    */
@@ -645,3 +663,49 @@ export namespace ChatModel {
     documentManager?: IDocumentManager | null;
   }
 }
+
+/**
+ * Interface of the chat context, a 'subset' of the model with readonly attribute,
+ * which can be passed to the input model.
+ * This allows third party extensions to get some attribute of the model without
+ * exposing the method that can modify it.
+ */
+export interface IChatContext {
+  /**
+   * The name of the chat.
+   */
+  readonly name: string;
+  /**
+   * A copy of the messages.
+   */
+  readonly messages: IChatMessage[];
+  /**
+   * A list of all users who have connected to this chat.
+   */
+  readonly users: IUser[];
+}
+
+/**
+ * An abstract base class implementing `IChatContext`. This can be extended into
+ * a complete implementation, as done in `jupyterlab-chat`.
+ */
+export abstract class AbstractChatContext implements IChatContext {
+  constructor(options: { model: IChatModel }) {
+    this._model = options.model;
+  }
+
+  get name(): string {
+    return this._model.name;
+  }
+
+  get messages(): IChatMessage[] {
+    return [...this._model.messages];
+  }
+
+  /**
+   * ABSTRACT: Should return a list of users who have connected to this chat.
+   */
+  abstract get users(): IUser[];
+
+  protected _model: IChatModel;
+}

package/src/types.ts

@@ -13,6 +13,10 @@ export interface IUser {
   initials?: string;
   color?: string;
   avatar_url?: string;
+  /**
+   * The string to use to mention a user in the chat.
+   */
+  mention_name?: string;
 }
 
 /**
@@ -51,6 +55,7 @@ export interface IChatMessage<T = IUser, U = IAttachment> {
   time: number;
   sender: T;
   attachments?: U[];
+  mentions?: T[];
   raw_time?: boolean;
   deleted?: boolean;
   edited?: boolean;

package/src/utils.ts

@@ -10,6 +10,10 @@ import { FileEditor } from '@jupyterlab/fileeditor';
 import { Notebook } from '@jupyterlab/notebook';
 import { Widget } from '@lumino/widgets';
 
+import { IUser } from './types';
+
+const MENTION_CLASS = 'jp-chat-mention';
+
 /**
  * Gets the editor instance used by a document widget. Returns `null` if unable.
  */
@@ -45,3 +49,33 @@ export function getCellIndex(notebook: Notebook, cellId: string): number {
   );
   return idx === undefined ? -1 : idx;
 }
+
+/**
+ * Replace a mention to user (@someone) to a span, for markdown renderer.
+ *
+ * @param content - the content to update.
+ * @param user - the user mentioned.
+ */
+export function replaceMentionToSpan(content: string, user: IUser): string {
+  if (!user.mention_name) {
+    return content;
+  }
+  const regex = new RegExp(user.mention_name, 'g');
+  const mention = `<span class="${MENTION_CLASS}">${user.mention_name}</span>`;
+  return content.replace(regex, mention);
+}
+
+/**
+ * Replace a span to a mentioned to user string (@someone).
+ *
+ * @param content - the content to update.
+ * @param user - the user mentioned.
+ */
+export function replaceSpanToMention(content: string, user: IUser): string {
+  if (!user.mention_name) {
+    return content;
+  }
+  const span = `<span class="${MENTION_CLASS}">${user.mention_name}</span>`;
+  const regex = new RegExp(span, 'g');
+  return content.replace(regex, user.mention_name);
+}

package/style/chat.css

@@ -140,3 +140,9 @@
   color: gray;
   margin: 5px;
 }
+
+.jp-chat-mention {
+  border-radius: 10px;
+  padding: 0 0.2em;
+  background-color: var(--jp-brand-color4);
+}