@jupyter/chat 0.1.0

package/src/components/mui-extras/stacking-alert.tsx

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import React, { useState, useMemo, useCallback } from 'react';
+import { Alert, AlertColor, Collapse } from '@mui/material';
+
+export type StackingAlert = {
+  /**
+   * A function that triggers an alert. Successive alerts are indicated in the
+   * JSX element.
+   * @param alertType Type of alert.
+   * @param msg Message contained within the alert.
+   * @returns
+   */
+  show: (alertType: AlertColor, msg: string | Error) => void;
+  /**
+   * The Alert JSX element that should be rendered by the consumer.
+   * This will be `null` if no alerts were triggered.
+   */
+  jsx: JSX.Element | null;
+  /**
+   * An async function that closes the alert, and returns a Promise that
+   * resolves when the onClose animation is completed.
+   */
+  clear: () => void | Promise<void>;
+};
+
+/**
+ * Hook that returns a function to trigger an alert, and a corresponding alert
+ * JSX element for the consumer to render. The number of successive identical
+ * alerts `X` is indicated in the element via the suffix "(X)".
+ */
+export function useStackingAlert(): StackingAlert {
+  const [type, setType] = useState<AlertColor | null>(null);
+  const [msg, setMsg] = useState<string>('');
+  const [repeatCount, setRepeatCount] = useState(0);
+  const [expand, setExpand] = useState(false);
+  const [exitPromise, setExitPromise] = useState<Promise<void>>();
+  const [exitPromiseResolver, setExitPromiseResolver] = useState<() => void>();
+
+  const showAlert = useCallback(
+    (nextType: AlertColor, _nextMsg: string | Error) => {
+      // if the alert is identical to the previous alert, increment the
+      // `repeatCount` indicator.
+      const nextMsg = _nextMsg.toString();
+      if (nextType === type && nextMsg === msg) {
+        setRepeatCount(currCount => currCount + 1);
+        return;
+      }
+
+      if (type === null) {
+        // if this alert is being shown for the first time, initialize the
+        // exitPromise so we can await it on `clear()`.
+        setExitPromise(
+          new Promise(res => {
+            setExitPromiseResolver(() => res);
+          })
+        );
+      }
+
+      setType(nextType);
+      setMsg(nextMsg);
+      setRepeatCount(0);
+      setExpand(true);
+    },
+    [msg, type]
+  );
+
+  const alertJsx = useMemo(
+    () => (
+      <Collapse
+        in={expand}
+        onExited={() => {
+          exitPromiseResolver?.();
+          // only clear the alert after the Collapse exits, otherwise the alert
+          // disappears without any animation.
+          setType(null);
+          setMsg('');
+          setRepeatCount(0);
+        }}
+        timeout={200}
+      >
+        {type !== null && (
+          <Alert severity={type}>
+            {msg + (repeatCount ? ` (${repeatCount})` : '')}
+          </Alert>
+        )}
+      </Collapse>
+    ),
+    [msg, repeatCount, type, expand, exitPromiseResolver]
+  );
+
+  const clearAlert = useCallback(() => {
+    setExpand(false);
+    return exitPromise;
+  }, [expand, exitPromise]);
+
+  return {
+    show: showAlert,
+    jsx: alertJsx,
+    clear: clearAlert
+  };
+}

package/src/components/rendermime-markdown.tsx

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import React, { useState, useEffect, useRef } from 'react';
+import ReactDOM from 'react-dom';
+
+import { CopyButton } from './copy-button';
+import { MessageToolbar } from './toolbar';
+
+const MD_MIME_TYPE = 'text/markdown';
+const RENDERMIME_MD_CLASS = 'jp-chat-rendermime-markdown';
+
+type RendermimeMarkdownProps = {
+  markdownStr: string;
+  rmRegistry: IRenderMimeRegistry;
+  appendContent?: boolean;
+  edit?: () => void;
+  delete?: () => void;
+};
+
+/**
+ * Takes \( and returns \\(. Escapes LaTeX delimeters by adding extra backslashes where needed for proper rendering by @jupyterlab/rendermime.
+ */
+function escapeLatexDelimiters(text: string) {
+  return text
+    .replace('\\(', '\\\\(')
+    .replace('\\)', '\\\\)')
+    .replace('\\[', '\\\\[')
+    .replace('\\]', '\\\\]');
+}
+
+function RendermimeMarkdownBase(props: RendermimeMarkdownProps): JSX.Element {
+  const appendContent = props.appendContent || false;
+  const [renderedContent, setRenderedContent] = useState<HTMLElement | null>(
+    null
+  );
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const renderContent = async () => {
+      const mdStr = escapeLatexDelimiters(props.markdownStr);
+      const model = props.rmRegistry.createModel({
+        data: { [MD_MIME_TYPE]: mdStr }
+      });
+
+      const renderer = props.rmRegistry.createRenderer(MD_MIME_TYPE);
+      await renderer.renderModel(model);
+      props.rmRegistry.latexTypesetter?.typeset(renderer.node);
+
+      // Attach CopyButton to each <pre> block
+      if (containerRef.current && renderer.node) {
+        const preBlocks = renderer.node.querySelectorAll('pre');
+        preBlocks.forEach(preBlock => {
+          const copyButtonContainer = document.createElement('div');
+          preBlock.parentNode?.insertBefore(
+            copyButtonContainer,
+            preBlock.nextSibling
+          );
+          ReactDOM.render(
+            <CopyButton value={preBlock.textContent || ''} />,
+            copyButtonContainer
+          );
+        });
+      }
+
+      setRenderedContent(renderer.node);
+    };
+
+    renderContent();
+  }, [props.markdownStr, props.rmRegistry]);
+
+  return (
+    <div ref={containerRef} className={RENDERMIME_MD_CLASS}>
+      {renderedContent &&
+        (appendContent ? (
+          <div ref={node => node && node.appendChild(renderedContent)} />
+        ) : (
+          <div ref={node => node && node.replaceChildren(renderedContent)} />
+        ))}
+      <MessageToolbar edit={props.edit} delete={props.delete} />
+    </div>
+  );
+}
+
+export const RendermimeMarkdown = React.memo(RendermimeMarkdownBase);

package/src/components/scroll-container.tsx

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import React, { useEffect, useMemo } from 'react';
+import { Box, SxProps, Theme } from '@mui/material';
+
+type ScrollContainerProps = {
+  children: React.ReactNode;
+  sx?: SxProps<Theme>;
+};
+
+/**
+ * Component that handles intelligent scrolling.
+ *
+ * - If viewport is at the bottom of the overflow container, appending new
+ * children keeps the viewport on the bottom of the overflow container.
+ *
+ * - If viewport is in the middle of the overflow container, appending new
+ * children leaves the viewport unaffected.
+ *
+ * Currently only works for Chrome and Firefox due to reliance on
+ * `overflow-anchor`.
+ *
+ * **References**
+ * - https://css-tricks.com/books/greatest-css-tricks/pin-scrolling-to-bottom/
+ */
+export function ScrollContainer(props: ScrollContainerProps): JSX.Element {
+  const id = useMemo(
+    () => 'jupyter-chat-scroll-container-' + Date.now().toString(),
+    []
+  );
+
+  /**
+   * Effect: Scroll the container to the bottom as soon as it is visible.
+   */
+  useEffect(() => {
+    const el = document.querySelector<HTMLElement>(`#${id}`);
+    if (!el) {
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      entries => {
+        entries.forEach(entry => {
+          if (entry.isIntersecting) {
+            el.scroll({ top: 999999999 });
+          }
+        });
+      },
+      { threshold: 1.0 }
+    );
+
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <Box
+      id={id}
+      sx={{
+        overflowY: 'scroll',
+        '& *': {
+          overflowAnchor: 'none'
+        },
+        ...props.sx
+      }}
+    >
+      <Box sx={{ minHeight: '100.01%' }}>{props.children}</Box>
+      <Box sx={{ overflowAnchor: 'auto', height: '1px' }} />
+    </Box>
+  );
+}

package/src/components/toolbar.tsx

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import {
+  ToolbarButtonComponent,
+  deleteIcon,
+  editIcon
+} from '@jupyterlab/ui-components';
+import React from 'react';
+
+const TOOLBAR_CLASS = 'jp-chat-toolbar';
+
+/**
+ * The toolbar attached to a message.
+ */
+export function MessageToolbar(props: MessageToolbar.IProps): JSX.Element {
+  const buttons: JSX.Element[] = [];
+
+  if (props.edit !== undefined) {
+    const editButton = ToolbarButtonComponent({
+      icon: editIcon,
+      onClick: props.edit,
+      tooltip: 'Edit'
+    });
+    buttons.push(editButton);
+  }
+  if (props.delete !== undefined) {
+    const deleteButton = ToolbarButtonComponent({
+      icon: deleteIcon,
+      onClick: props.delete,
+      tooltip: 'Delete'
+    });
+    buttons.push(deleteButton);
+  }
+
+  return (
+    <div className={TOOLBAR_CLASS}>
+      {buttons.map(toolbarButton => toolbarButton)}
+    </div>
+  );
+}
+
+export namespace MessageToolbar {
+  export interface IProps {
+    edit?: () => void;
+    delete?: () => void;
+  }
+}

package/src/icons.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+// This file is based on iconimports.ts in @jupyterlab/ui-components, but is manually generated.
+
+import { LabIcon } from '@jupyterlab/ui-components';
+
+import chatSvgStr from '../style/icons/chat.svg';
+
+export const chatIcon = new LabIcon({
+  name: 'jupyter-chat::chat',
+  svgstr: chatSvgStr
+});

package/src/index.ts

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+export * from './icons';
+export * from './model';
+export * from './types';
+export * from './widgets/chat-error';
+export * from './widgets/chat-sidebar';
+export * from './widgets/chat-widget';

package/src/model.ts

@@ -0,0 +1,272 @@
+/*
+ * 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 {
+  IChatHistory,
+  INewMessage,
+  IChatMessage,
+  IConfig,
+  IUser
+} from './types';
+
+/**
+ * The chat model interface.
+ */
+export interface IChatModel extends IDisposable {
+  /**
+   * The chat model ID.
+   */
+  id: string;
+
+  /**
+   * The configuration for the chat panel.
+   */
+  config: IConfig;
+
+  /**
+   * The user connected to the chat panel.
+   */
+  readonly user?: IUser;
+
+  /**
+   * The chat messages list.
+   */
+  readonly messages: IChatMessage[];
+
+  /**
+   * The signal emitted when the messages list is updated.
+   */
+  readonly messagesUpdated: ISignal<IChatModel, void>;
+
+  /**
+   * Send a message, to be defined depending on the chosen technology.
+   * Default to no-op.
+   *
+   * @param message - the message to send.
+   * @returns whether the message has been sent or not, or nothing if not needed.
+   */
+  addMessage(message: INewMessage): Promise<boolean | void> | boolean | void;
+
+  /**
+   * Optional, to update a message from the chat panel.
+   *
+   * @param id - the unique ID of the message.
+   * @param message - the updated message.
+   */
+  updateMessage?(
+    id: string,
+    message: IChatMessage
+  ): Promise<boolean | void> | boolean | void;
+
+  /**
+   * Optional, to delete a message from the chat.
+   *
+   * @param id - the unique ID of the message.
+   */
+  deleteMessage?(id: string): Promise<boolean | void> | boolean | void;
+
+  /**
+   * Optional, to get messages history.
+   */
+  getHistory?(): Promise<IChatHistory>;
+
+  /**
+   * Dispose the chat model.
+   */
+  dispose(): void;
+
+  /**
+   * Whether the chat handler is disposed.
+   */
+  isDisposed: boolean;
+
+  /**
+   * Function to call when a message is received.
+   *
+   * @param message - the message with user information and body.
+   */
+  messageAdded(message: IChatMessage): void;
+
+  /**
+   * Function called when messages are inserted.
+   *
+   * @param index - the index of the first message of the list.
+   * @param messages - the messages list.
+   */
+  messagesInserted(index: number, messages: IChatMessage[]): void;
+
+  /**
+   * Function called when messages are deleted.
+   *
+   * @param index - the index of the first message to delete.
+   * @param count - the number of messages to delete.
+   */
+  messagesDeleted(index: number, count: number): void;
+}
+
+/**
+ * The default chat model implementation.
+ * It is not able to send or update a message by itself, since it depends on the
+ * chosen technology.
+ */
+export class ChatModel implements IChatModel {
+  /**
+   * Create a new chat model.
+   */
+  constructor(options: ChatModel.IOptions = {}) {
+    this._config = options.config ?? {};
+  }
+
+  /**
+   * The chat messages list.
+   */
+  get messages(): IChatMessage[] {
+    return this._messages;
+  }
+
+  /**
+   * The chat model ID.
+   */
+  get id(): string {
+    return this._id;
+  }
+  set id(value: string) {
+    this._id = value;
+  }
+
+  /**
+   * The chat settings.
+   */
+  get config(): IConfig {
+    return this._config;
+  }
+  set config(value: Partial<IConfig>) {
+    this._config = { ...this._config, ...value };
+  }
+
+  /**
+   * The signal emitted when the messages list is updated.
+   */
+  get messagesUpdated(): ISignal<IChatModel, void> {
+    return this._messagesUpdated;
+  }
+
+  /**
+   * Send a message, to be defined depending on the chosen technology.
+   * Default to no-op.
+   *
+   * @param message - the message to send.
+   * @returns whether the message has been sent or not.
+   */
+  addMessage(message: INewMessage): Promise<boolean | void> | boolean | void {}
+
+  /**
+   * Optional, to update a message from the chat panel.
+   *
+   * @param id - the unique ID of the message.
+   * @param message - the message to update.
+   */
+  updateMessage?(
+    id: string,
+    message: INewMessage
+  ): Promise<boolean | void> | boolean | void;
+
+  /**
+   * Dispose the chat model.
+   */
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this._isDisposed = true;
+  }
+
+  /**
+   * Whether the chat handler is disposed.
+   */
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  /**
+   * A function called before transferring the message to the panel(s).
+   * Can be useful if some actions are required on the message.
+   */
+  protected formatChatMessage(message: IChatMessage): IChatMessage {
+    return message;
+  }
+
+  /**
+   * Function to call when a message is received.
+   *
+   * @param message - the message with user information and body.
+   */
+  messageAdded(message: IChatMessage): void {
+    const messageIndex = this._messages.findIndex(msg => msg.id === message.id);
+    if (messageIndex > -1) {
+      // The message is an update of an existing one.
+      // Let's remove it to avoid position conflict if timestamp has changed.
+      this._messages.splice(messageIndex, 1);
+    }
+    // Find the first message that should be after this one.
+    let nextMsgIndex = this._messages.findIndex(msg => msg.time > message.time);
+    if (nextMsgIndex === -1) {
+      // There is no message after this one, so let's insert the message at the end.
+      nextMsgIndex = this._messages.length;
+    }
+    // Insert the message.
+    this.messagesInserted(nextMsgIndex, [message]);
+  }
+
+  /**
+   * Function called when messages are inserted.
+   *
+   * @param index - the index of the first message of the list.
+   * @param messages - the messages list.
+   */
+  messagesInserted(index: number, messages: IChatMessage[]): void {
+    const formattedMessages: IChatMessage[] = [];
+    messages.forEach(message => {
+      formattedMessages.push(this.formatChatMessage(message));
+    });
+    this._messages.splice(index, 0, ...formattedMessages);
+    this._messagesUpdated.emit();
+  }
+
+  /**
+   * Function called when messages are deleted.
+   *
+   * @param index - the index of the first message to delete.
+   * @param count - the number of messages to delete.
+   */
+  messagesDeleted(index: number, count: number): void {
+    this._messages.splice(index, count);
+    this._messagesUpdated.emit();
+  }
+
+  private _messages: IChatMessage[] = [];
+  private _id: string = '';
+  private _config: IConfig;
+  private _isDisposed = false;
+  private _messagesUpdated = new Signal<IChatModel, void>(this);
+}
+
+/**
+ * The chat model namespace.
+ */
+export namespace ChatModel {
+  /**
+   * The instantiation options for a ChatModel.
+   */
+  export interface IOptions {
+    /**
+     * Initial config for the chat widget.
+     */
+    config?: IConfig;
+  }
+}