@jupyter/chat 0.25.0-alpha.0 → 0.25.0-alpha.2

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

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

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

@@ -0,0 +1,58 @@
+/*
+ * 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 writer = (user, typingIndicator) => ({ user, typingIndicator });
+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 a custom indicator, not just a generic one', () => {
+        const el = render([writer(alice, 'is running `ripgrep`')]);
+        expect(el.textContent).toContain('Alice is running `ripgrep`');
+    });
+    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/writing-indicator.js

@@ -57,7 +57,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.25.0-alpha.0",
+  "version": "0.25.0-alpha.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,76 @@
+/*
+ * 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 writer = (user: IUser, typingIndicator?: string): IChatModel.IWriter =>
+  ({ user, typingIndicator }) 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 a custom indicator, not just a generic one', () => {
+    const el = render([writer(alice, 'is running `ripgrep`')]);
+    expect(el.textContent).toContain('Alice is running `ripgrep`');
+  });
+
+  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/writing-indicator.tsx

@@ -92,6 +92,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'