@jupyter/chat 0.24.0 → 0.24.2

package/lib/__tests__/writing-indicator.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/writing-indicator.spec.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+// React 18 asks test environments to declare themselves, otherwise every
+// `act` call warns.
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+import { WritingIndicator } from '../components/writing-indicator';
+const alice = { username: 'a', name: 'Alice', display_name: 'Alice' };
+const bob = { username: 'b', name: 'Bob', display_name: 'Bob' };
+const writer = (user) => ({ user });
+describe('WritingIndicator accessibility', () => {
+    let container;
+    let root;
+    const render = (writers) => {
+        act(() => {
+            root.render(React.createElement(WritingIndicator, { writers: writers }));
+        });
+        return container.querySelector('.jp-chat-writers');
+    };
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+    });
+    afterEach(() => {
+        act(() => root.unmount());
+        container.remove();
+    });
+    it('is a polite live region, so a reply on its way is announced', () => {
+        // The indicator is the only signal that someone is replying. Without a
+        // live region it is visible text that assistive technology never speaks.
+        const el = render([]);
+        expect(el.getAttribute('role')).toBe('status');
+        expect(el.getAttribute('aria-live')).toBe('polite');
+    });
+    it('reads the whole phrase rather than a fragment of it', () => {
+        // Without aria-atomic, a change to part of the text can be announced on
+        // its own, so a reader hears a bare name with no context.
+        expect(render([]).getAttribute('aria-atomic')).toBe('true');
+    });
+    it('announces who is writing', () => {
+        expect(render([writer(alice)]).textContent).toContain('Alice is typing');
+    });
+    it('announces every writer, not just the first', () => {
+        const el = render([writer(alice), writer(bob)]);
+        expect(el.textContent).toContain('Alice');
+        expect(el.textContent).toContain('Bob');
+    });
+    it('says nothing when nobody is writing', () => {
+        var _a;
+        // The container is always rendered to reserve space, and holds a
+        // non-breaking space as a placeholder. That placeholder must not be
+        // announced as if it were a message.
+        const text = ((_a = render([]).textContent) !== null && _a !== void 0 ? _a : '').replace(/ /g, '').trim();
+        expect(text).toBe('');
+    });
+});

package/lib/components/messages/message-renderer.js

@@ -12,6 +12,11 @@ import { useChatContext } from '../../context';
 import { replaceMentionToSpan } from '../../utils';
 const RENDERED_CLASS = 'jp-chat-rendered-message';
 const DEFAULT_MIME_TYPE = 'text/markdown';
+/**
+ * The class name added to an output area widget. This is required to display cell
+ * output as a message in the chat.
+ */
+const OUTPUT_AREA_CLASS = 'jp-OutputArea';
 /**
  * The message renderer base component.
  */
@@ -22,6 +27,7 @@ function MessageRendererBase(props) {
     const [renderedContent, setRenderedContent] = useState(null);
     // Allow edition only on text messages.
     const [canEdit, setCanEdit] = useState(false);
+    const [isOutputArea, setIsOutputArea] = useState(false);
     // Each element is a two-tuple with the structure [codeToolbarRoot, codeToolbarProps].
     const [codeToolbarDefns, setCodeToolbarDefns] = useState([]);
     useEffect(() => {
@@ -86,6 +92,7 @@ function MessageRendererBase(props) {
             // never been attached, only the node.
             // This is necessary to render latex.
             MessageLoop.sendMessage(renderer, Widget.Msg.AfterAttach);
+            setIsOutputArea(!isMarkdownRenderer);
             // Add code toolbar if markdown has been rendered.
             if (isMarkdownRenderer) {
                 const newCodeToolbarDefns = [];
@@ -110,7 +117,7 @@ function MessageRendererBase(props) {
         renderContent();
     }, [message.body, message.mime_model, message.mentions, rmRegistry]);
     return (React.createElement(React.Fragment, null,
-        renderedContent && (React.createElement("div", { className: RENDERED_CLASS, ref: node => node && node.replaceChildren(renderedContent) })),
+        renderedContent && (React.createElement("div", { className: `${RENDERED_CLASS}${isOutputArea ? ` ${OUTPUT_AREA_CLASS}` : ''}`, ref: node => node && node.replaceChildren(renderedContent) })),
         React.createElement(MessageToolbar, { edit: canEdit ? props.edit : undefined, delete: props.delete }),
         // Render a `CodeToolbar` element underneath each code block.
         // We use ReactDOM.createPortal() so each `CodeToolbar` element is able

package/lib/components/writing-indicator.js

@@ -41,7 +41,17 @@ export function WritingIndicator(props) {
     const trans = useTranslator();
     // Always render the container to reserve space, even if no writers
     const writersText = writers.length > 0 ? formatWritersText(writers, trans) : '';
-    return (React.createElement(Box, { className: WRITERS_ELEMENT_CLASSNAME, sx: {
+    return (React.createElement(Box, { className: WRITERS_ELEMENT_CLASSNAME, 
+        // The indicator already says something useful, "Alice is typing..." or
+        // "Jupyternaut is running `ripgrep`", but only on screen. Announcing it
+        // politely means a screen reader user learns a reply is coming without
+        // being interrupted mid-sentence.
+        //
+        // The region is the container rather than the text, so it is present in
+        // the accessibility tree before a writer appears and the change is
+        // announced. `aria-atomic` keeps the phrase together: without it a name
+        // change alone can be read out on its own, stripped of its context.
+        role: "status", "aria-live": "polite", "aria-atomic": "true", sx: {
             ...props.sx,
             minHeight: '16px'
         } },

package/package.json

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

package/src/__tests__/writing-indicator.spec.tsx

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import React, { act } from 'react';
+import { createRoot, Root } from 'react-dom/client';
+
+// React 18 asks test environments to declare themselves, otherwise every
+// `act` call warns.
+(
+  globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+import { WritingIndicator } from '../components/writing-indicator';
+import { IChatModel } from '../model';
+import { IUser } from '../types';
+
+const alice: IUser = { username: 'a', name: 'Alice', display_name: 'Alice' };
+const bob: IUser = { username: 'b', name: 'Bob', display_name: 'Bob' };
+
+const writer = (user: IUser): IChatModel.IWriter =>
+  ({ user }) as IChatModel.IWriter;
+
+describe('WritingIndicator accessibility', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  const render = (writers: IChatModel.IWriter[]) => {
+    act(() => {
+      root.render(<WritingIndicator writers={writers} />);
+    });
+    return container.querySelector('.jp-chat-writers') as HTMLElement;
+  };
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it('is a polite live region, so a reply on its way is announced', () => {
+    // The indicator is the only signal that someone is replying. Without a
+    // live region it is visible text that assistive technology never speaks.
+    const el = render([]);
+    expect(el.getAttribute('role')).toBe('status');
+    expect(el.getAttribute('aria-live')).toBe('polite');
+  });
+
+  it('reads the whole phrase rather than a fragment of it', () => {
+    // Without aria-atomic, a change to part of the text can be announced on
+    // its own, so a reader hears a bare name with no context.
+    expect(render([]).getAttribute('aria-atomic')).toBe('true');
+  });
+
+  it('announces who is writing', () => {
+    expect(render([writer(alice)]).textContent).toContain('Alice is typing');
+  });
+
+  it('announces every writer, not just the first', () => {
+    const el = render([writer(alice), writer(bob)]);
+    expect(el.textContent).toContain('Alice');
+    expect(el.textContent).toContain('Bob');
+  });
+
+  it('says nothing when nobody is writing', () => {
+    // The container is always rendered to reserve space, and holds a
+    // non-breaking space as a placeholder. That placeholder must not be
+    // announced as if it were a message.
+    const text = (render([]).textContent ?? '').replace(/ /g, '').trim();
+    expect(text).toBe('');
+  });
+});

package/src/components/messages/message-renderer.tsx

@@ -19,6 +19,12 @@ import { replaceMentionToSpan } from '../../utils';
 const RENDERED_CLASS = 'jp-chat-rendered-message';
 const DEFAULT_MIME_TYPE = 'text/markdown';
 
+/**
+ * The class name added to an output area widget. This is required to display cell
+ * output as a message in the chat.
+ */
+const OUTPUT_AREA_CLASS = 'jp-OutputArea';
+
 /**
  * The type of the props for the MessageRenderer component.
  */
@@ -56,6 +62,8 @@ function MessageRendererBase(props: MessageRendererProps): JSX.Element {
   // Allow edition only on text messages.
   const [canEdit, setCanEdit] = useState<boolean>(false);
 
+  const [isOutputArea, setIsOutputArea] = useState<boolean>(false);
+
   // Each element is a two-tuple with the structure [codeToolbarRoot, codeToolbarProps].
   const [codeToolbarDefns, setCodeToolbarDefns] = useState<
     Array<[HTMLDivElement, CodeToolbarProps]>
@@ -129,6 +137,8 @@ function MessageRendererBase(props: MessageRendererProps): JSX.Element {
       // This is necessary to render latex.
       MessageLoop.sendMessage(renderer, Widget.Msg.AfterAttach);
 
+      setIsOutputArea(!isMarkdownRenderer);
+
       // Add code toolbar if markdown has been rendered.
       if (isMarkdownRenderer) {
         const newCodeToolbarDefns: [HTMLDivElement, CodeToolbarProps][] = [];
@@ -164,7 +174,7 @@ function MessageRendererBase(props: MessageRendererProps): JSX.Element {
     <>
       {renderedContent && (
         <div
-          className={RENDERED_CLASS}
+          className={`${RENDERED_CLASS}${isOutputArea ? ` ${OUTPUT_AREA_CLASS}` : ''}`}
           ref={node => node && node.replaceChildren(renderedContent)}
         />
       )}

package/src/components/writing-indicator.tsx

@@ -76,6 +76,18 @@ export function WritingIndicator(
   return (
     <Box
       className={WRITERS_ELEMENT_CLASSNAME}
+      // The indicator already says something useful, "Alice is typing..." or
+      // "Jupyternaut is running `ripgrep`", but only on screen. Announcing it
+      // politely means a screen reader user learns a reply is coming without
+      // being interrupted mid-sentence.
+      //
+      // The region is the container rather than the text, so it is present in
+      // the accessibility tree before a writer appears and the change is
+      // announced. `aria-atomic` keeps the phrase together: without it a name
+      // change alone can be read out on its own, stripped of its context.
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
       sx={{
         ...props.sx,
         minHeight: '16px'