@jupyter-ai/persona-manager 0.1.0 → 0.1.1

package/lib/persona-controls.d.ts

@@ -51,6 +51,26 @@ export declare function showLoadingPlaceholder(hasAwareness: boolean, managerRes
  * control's kind. A null value resets that control to the persona's default.
  */
 export declare function applyControlChange(settings: PersonaSettings, control: Control, value: string | null): PersonaSettings;
+/**
+ * A dropdown for a control, titled with the control's label. The first choice
+ * row is "Default" (selection = null); the rest are the persona's advertised
+ * options (selection = that option's id). Exported for tests.
+ */
+export declare function ControlItem(props: {
+    control: Control;
+    onSelect: (value: string | null) => void;
+}): JSX.Element;
+/**
+ * The overflow popover: controls that did not fit inline, shown as a single flat
+ * menu (no nested dropdowns). Each control renders as a group label followed by
+ * its Default row and choices. Exported for tests.
+ */
+export declare function OverflowMenu(props: {
+    controls: Control[];
+    anchor: HTMLElement | null;
+    onClose: () => void;
+    onChange: (control: Control, value: string | null) => void;
+}): JSX.Element;
 /**
  * Format a token count compactly: 950 stays as-is, 41500 becomes "41.5k",
  * 1240000 becomes "1.24M". `Intl.NumberFormat` picks the tier after rounding,

package/lib/persona-controls.js

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
 import { Button, ListItemText, ListSubheader, Menu, MenuItem, Popover, Skeleton } from '@mui/material';
 import ArrowDropDownIcon from '@mui/icons-material/ArrowDropDown';
 import CheckIcon from '@mui/icons-material/Check';
@@ -189,12 +189,15 @@ function currentControlLabel(control) {
  * description, which is just noise). The full description is available on hover.
  */
 function ChoiceMenuItem(props) {
-    const { primary, selected, onSelect } = props;
-    const description = props.description &&
-        props.description.trim().toLowerCase() !== primary.trim().toLowerCase()
-        ? props.description
+    // MenuList clones the row it picks for initial focus with extra props
+    // (tabIndex, autoFocus); forward them to the MenuItem, or no row is ever
+    // focused and the menu's arrow-key and type-ahead handling never engages.
+    const { primary, description: rawDescription, selected, onSelect, ...menuItemProps } = props;
+    const description = rawDescription &&
+        rawDescription.trim().toLowerCase() !== primary.trim().toLowerCase()
+        ? rawDescription
         : null;
-    return (React.createElement(MenuItem, { selected: selected, onClick: onSelect, title: description !== null && description !== void 0 ? description : undefined },
+    return (React.createElement(MenuItem, { ...menuItemProps, selected: selected, onClick: onSelect, title: description !== null && description !== void 0 ? description : undefined },
         React.createElement(ListItemText, { primary: primary, secondary: description, classes: {
                 primary: `${MENU_CLASS}-name`,
                 secondary: `${MENU_CLASS}-desc`
@@ -213,16 +216,34 @@ function defaultChoiceLabel(control) {
     return name ? `Default (${name})` : 'Default';
 }
 /**
- * A dropdown for a control. The first row is "Default" (selection = null); the
- * rest are the persona's advertised options (selection = that option's id).
+ * The uppercase group label used in control menus: it titles a control's own
+ * dropdown and labels each control's section in the overflow menu. Rendered
+ * with MUI's `ListSubheader`, which has no tabindex, so arrow-key focus skips
+ * it and the menu stays keyboard-navigable.
  */
-function ControlItem(props) {
+function ControlSubheader(props) {
+    return (React.createElement(ListSubheader, { id: props.id, disableSticky: true, className: `${MENU_CLASS}-subheader` }, props.label));
+}
+// MUI's MenuList skips initial focus for children whose type carries this
+// static; ListSubheader's own copy is hidden behind the wrapper.
+ControlSubheader.muiSkipListHighlight = true;
+/**
+ * A dropdown for a control, titled with the control's label. The first choice
+ * row is "Default" (selection = null); the rest are the persona's advertised
+ * options (selection = that option's id). Exported for tests.
+ */
+export function ControlItem(props) {
     const { control, onSelect } = props;
     const [anchor, setAnchor] = useState(null);
+    // The heading names the menu for assistive tech: the subheader itself is a
+    // roleless, never-focused list row, so without this wiring the popup has no
+    // accessible name at all.
+    const headingId = useId();
     return (React.createElement(React.Fragment, null,
         React.createElement(Button, { className: `${SELECTOR_CLASS} ${SELECTOR_CLASS}-control-btn`, size: "small", variant: "text", disableRipple: true, endIcon: React.createElement(ArrowDropDownIcon, { className: `${SELECTOR_CLASS}-arrow` }), onClick: event => setAnchor(event.currentTarget), title: control.label },
             React.createElement("span", { className: `${SELECTOR_CLASS}-control-value` }, currentControlLabel(control))),
-        React.createElement(Menu, { anchorEl: anchor, open: !!anchor, onClose: () => setAnchor(null), ...menuAnchorProps },
+        React.createElement(Menu, { anchorEl: anchor, open: !!anchor, onClose: () => setAnchor(null), MenuListProps: { 'aria-labelledby': headingId }, ...menuAnchorProps },
+            React.createElement(ControlSubheader, { id: headingId, label: control.label }),
             React.createElement(ChoiceMenuItem, { primary: defaultChoiceLabel(control), description: null, selected: control.selection === null, onSelect: () => {
                     setAnchor(null);
                     onSelect(null);
@@ -234,15 +255,13 @@ function ControlItem(props) {
 }
 /**
  * The overflow popover: controls that did not fit inline, shown as a single flat
- * menu (no nested dropdowns). Each control renders as a `ListSubheader` group
- * label followed by its Default row and choices. Using MUI primitives keeps the
- * menu keyboard-navigable: `ListSubheader` has no tabindex so arrow-key focus
- * skips it.
+ * menu (no nested dropdowns). Each control renders as a group label followed by
+ * its Default row and choices. Exported for tests.
  */
-function OverflowMenu(props) {
+export function OverflowMenu(props) {
     const { controls, anchor, onClose, onChange } = props;
-    return (React.createElement(Menu, { anchorEl: anchor, open: !!anchor, onClose: onClose, ...menuAnchorProps }, controls.flatMap(control => [
-        React.createElement(ListSubheader, { key: `${control.id}-label`, disableSticky: true, className: `${SELECTOR_CLASS}-overflow-subheader` }, control.label),
+    return (React.createElement(Menu, { anchorEl: anchor, open: !!anchor, onClose: onClose, MenuListProps: { 'aria-label': 'More controls' }, ...menuAnchorProps }, controls.flatMap(control => [
+        React.createElement(ControlSubheader, { key: `${control.id}-label`, label: control.label }),
         React.createElement(ChoiceMenuItem, { key: `${control.id}-default`, primary: defaultChoiceLabel(control), description: null, selected: control.selection === null, onSelect: () => {
                 onClose();
                 onChange(control, null);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jupyter-ai/persona-manager",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "The core manager & registry for AI personas in Jupyter AI",
     "keywords": [
         "jupyter",
@@ -71,6 +71,7 @@
         "@types/json-schema": "^7.0.11",
         "@types/react": "^18.0.26",
         "@types/react-addons-linked-state-mixin": "^0.14.22",
+        "@types/react-dom": "^18.0.0",
         "@typescript-eslint/eslint-plugin": "^6.1.0",
         "@typescript-eslint/parser": "^6.1.0",
         "css-loader": "^6.7.1",

package/src/__tests__/persona-controls-menus.spec.tsx

@@ -0,0 +1,175 @@
+/**
+ * Renders the control menus and pins their user-observable contract: each
+ * dropdown opens titled by its control's heading, the heading names the menu
+ * for assistive tech without joining keyboard traversal, and arrow keys,
+ * type-ahead, and Enter drive the choice rows.
+ */
+import React from 'react';
+import { createRoot, Root } from 'react-dom/client';
+import { Control, ControlItem, OverflowMenu } from '../persona-controls';
+
+// React 18.3 ships `React.act`, which the installed @types/react (18.0) does
+// not declare yet.
+const { act } = React as unknown as { act: (callback: () => void) => void };
+
+(
+  globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const SUBHEADER_SELECTOR = 'li.jp-jai-controlMenu-subheader';
+
+function modelControl(selection: string | null): Control {
+  return {
+    id: '__model__',
+    kind: 'model',
+    label: 'Model',
+    current: 'alpha',
+    selection,
+    options: [
+      { id: 'alpha', name: 'Alpha', description: null },
+      { id: 'beta', name: 'Beta', description: null }
+    ]
+  };
+}
+
+describe('control menus', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  function menu(): HTMLElement {
+    return document.querySelector('ul[role="menu"]') as HTMLElement;
+  }
+
+  function focused(): HTMLElement {
+    return document.activeElement as HTMLElement;
+  }
+
+  function press(key: string): void {
+    act(() => {
+      focused().dispatchEvent(
+        new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true })
+      );
+    });
+  }
+
+  describe('control dropdown', () => {
+    function openMenu(
+      control: Control,
+      onSelect: (value: string | null) => void = () => undefined
+    ): void {
+      act(() => {
+        root.render(<ControlItem control={control} onSelect={onSelect} />);
+      });
+      act(() => {
+        (container.querySelector('button') as HTMLElement).dispatchEvent(
+          new MouseEvent('click', { bubbles: true })
+        );
+      });
+    }
+
+    it('opens titled by a heading that names the menu', () => {
+      openMenu(modelControl('beta'));
+      const heading = document.querySelector(SUBHEADER_SELECTOR) as HTMLElement;
+      expect(heading.textContent).toBe('Model');
+      expect(heading.hasAttribute('tabindex')).toBe(false);
+      expect(heading.id).toBeTruthy();
+      expect(menu().getAttribute('aria-labelledby')).toBe(heading.id);
+    });
+
+    it('focuses the selected row and moves focus with the keyboard', () => {
+      openMenu(modelControl('beta'));
+      // Rows: heading, "Default (Alpha)", "Alpha", "Beta"; "Beta" is selected.
+      expect(focused().textContent).toBe('Beta');
+      expect(focused().getAttribute('role')).toBe('menuitem');
+      // Wrapping from the last row skips the heading to the first choice row.
+      press('ArrowDown');
+      expect(focused().textContent).toBe('Default (Alpha)');
+      press('ArrowDown');
+      expect(focused().textContent).toBe('Alpha');
+      // Type-ahead: "b" jumps to Beta.
+      press('b');
+      expect(focused().textContent).toBe('Beta');
+    });
+
+    it('leaves focus in place when type-ahead matches only the heading', () => {
+      openMenu(modelControl('beta'));
+      // First key after open, so it cannot buffer onto a previous press: "m"
+      // matches the heading ("Model") and no choice row, and the heading
+      // never takes focus.
+      press('m');
+      expect(focused().textContent).toBe('Beta');
+    });
+
+    it('falls back to the first choice row when the selection is stale', () => {
+      // A selection id the persona no longer advertises leaves no row
+      // selected; initial focus then skips the heading to the first row.
+      openMenu(modelControl('stale'));
+      expect(focused().textContent).toBe('Default (Alpha)');
+      expect(focused().getAttribute('role')).toBe('menuitem');
+    });
+
+    it('activates the focused row with Enter', () => {
+      const onSelect = jest.fn();
+      openMenu(modelControl(null), onSelect);
+      press('ArrowDown');
+      press('ArrowDown');
+      press('Enter');
+      expect(onSelect).toHaveBeenCalledWith('beta');
+    });
+  });
+
+  describe('overflow menu', () => {
+    it('is labeled and arrows skip the section headings', () => {
+      const first: Control = {
+        id: 'a',
+        kind: 'setting',
+        label: 'Aaa',
+        current: null,
+        selection: 'a1',
+        options: [{ id: 'a1', name: 'A one', description: null }]
+      };
+      const second: Control = {
+        id: 'b',
+        kind: 'setting',
+        label: 'Bbb',
+        current: null,
+        selection: 'stale',
+        options: [{ id: 'b1', name: 'B one', description: null }]
+      };
+      const anchor = document.createElement('button');
+      document.body.appendChild(anchor);
+      act(() => {
+        root.render(
+          <OverflowMenu
+            controls={[first, second]}
+            anchor={anchor}
+            onClose={() => undefined}
+            onChange={() => undefined}
+          />
+        );
+      });
+      expect(menu().getAttribute('aria-label')).toBe('More controls');
+      const headings = Array.from(
+        document.querySelectorAll(SUBHEADER_SELECTOR)
+      ).map(h => h.textContent);
+      expect(headings).toEqual(['Aaa', 'Bbb']);
+      // "A one" is the only selected row; ArrowDown crosses the "Bbb" heading
+      // to the next section's first choice row.
+      expect(focused().textContent).toBe('A one');
+      press('ArrowDown');
+      expect(focused().textContent).toBe('Default');
+      anchor.remove();
+    });
+  });
+});

package/src/persona-controls.tsx

@@ -1,6 +1,7 @@
 import React, {
   useCallback,
   useEffect,
+  useId,
   useLayoutEffect,
   useRef,
   useState
@@ -280,14 +281,24 @@ function ChoiceMenuItem(props: {
   selected: boolean;
   onSelect: () => void;
 }): JSX.Element {
-  const { primary, selected, onSelect } = props;
+  // MenuList clones the row it picks for initial focus with extra props
+  // (tabIndex, autoFocus); forward them to the MenuItem, or no row is ever
+  // focused and the menu's arrow-key and type-ahead handling never engages.
+  const {
+    primary,
+    description: rawDescription,
+    selected,
+    onSelect,
+    ...menuItemProps
+  } = props;
   const description =
-    props.description &&
-    props.description.trim().toLowerCase() !== primary.trim().toLowerCase()
-      ? props.description
+    rawDescription &&
+    rawDescription.trim().toLowerCase() !== primary.trim().toLowerCase()
+      ? rawDescription
       : null;
   return (
     <MenuItem
+      {...menuItemProps}
       selected={selected}
       onClick={onSelect}
       title={description ?? undefined}
@@ -319,15 +330,42 @@ function defaultChoiceLabel(control: Control): string {
 }
 
 /**
- * A dropdown for a control. The first row is "Default" (selection = null); the
- * rest are the persona's advertised options (selection = that option's id).
+ * The uppercase group label used in control menus: it titles a control's own
+ * dropdown and labels each control's section in the overflow menu. Rendered
+ * with MUI's `ListSubheader`, which has no tabindex, so arrow-key focus skips
+ * it and the menu stays keyboard-navigable.
  */
-function ControlItem(props: {
+function ControlSubheader(props: { label: string; id?: string }): JSX.Element {
+  return (
+    <ListSubheader
+      id={props.id}
+      disableSticky
+      className={`${MENU_CLASS}-subheader`}
+    >
+      {props.label}
+    </ListSubheader>
+  );
+}
+
+// MUI's MenuList skips initial focus for children whose type carries this
+// static; ListSubheader's own copy is hidden behind the wrapper.
+ControlSubheader.muiSkipListHighlight = true;
+
+/**
+ * A dropdown for a control, titled with the control's label. The first choice
+ * row is "Default" (selection = null); the rest are the persona's advertised
+ * options (selection = that option's id). Exported for tests.
+ */
+export function ControlItem(props: {
   control: Control;
   onSelect: (value: string | null) => void;
 }): JSX.Element {
   const { control, onSelect } = props;
   const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+  // The heading names the menu for assistive tech: the subheader itself is a
+  // roleless, never-focused list row, so without this wiring the popup has no
+  // accessible name at all.
+  const headingId = useId();
   return (
     <>
       <Button
@@ -347,8 +385,10 @@ function ControlItem(props: {
         anchorEl={anchor}
         open={!!anchor}
         onClose={() => setAnchor(null)}
+        MenuListProps={{ 'aria-labelledby': headingId }}
         {...menuAnchorProps}
       >
+        <ControlSubheader id={headingId} label={control.label} />
         <ChoiceMenuItem
           primary={defaultChoiceLabel(control)}
           description={null}
@@ -377,12 +417,10 @@ function ControlItem(props: {
 
 /**
  * The overflow popover: controls that did not fit inline, shown as a single flat
- * menu (no nested dropdowns). Each control renders as a `ListSubheader` group
- * label followed by its Default row and choices. Using MUI primitives keeps the
- * menu keyboard-navigable: `ListSubheader` has no tabindex so arrow-key focus
- * skips it.
+ * menu (no nested dropdowns). Each control renders as a group label followed by
+ * its Default row and choices. Exported for tests.
  */
-function OverflowMenu(props: {
+export function OverflowMenu(props: {
   controls: Control[];
   anchor: HTMLElement | null;
   onClose: () => void;
@@ -394,16 +432,11 @@ function OverflowMenu(props: {
       anchorEl={anchor}
       open={!!anchor}
       onClose={onClose}
+      MenuListProps={{ 'aria-label': 'More controls' }}
       {...menuAnchorProps}
     >
       {controls.flatMap(control => [
-        <ListSubheader
-          key={`${control.id}-label`}
-          disableSticky
-          className={`${SELECTOR_CLASS}-overflow-subheader`}
-        >
-          {control.label}
-        </ListSubheader>,
+        <ControlSubheader key={`${control.id}-label`} label={control.label} />,
         <ChoiceMenuItem
           key={`${control.id}-default`}
           primary={defaultChoiceLabel(control)}

package/style/base.css

@@ -278,10 +278,11 @@
   flex-shrink: 0;
 }
 
-/* overflow popover: an uppercase group label above each overflowed control's
-   choices, with a hairline divider and top spacing separating the sections.
-   Scoped under the paper to win over MUI's ListSubheader defaults. */
-.jp-jai-controlMenu-paper .jp-jai-personaControls-overflow-subheader {
+/* Control menu group label: an uppercase heading above a control's choices.
+   It titles each control's own dropdown; in the overflow popover a hairline
+   divider and top spacing separate the controls' sections. Scoped under the
+   paper to win over MUI's ListSubheader defaults. */
+.jp-jai-controlMenu-paper .jp-jai-controlMenu-subheader {
   margin-top: 8px;
   padding: 8px 12px 2px;
   border-top: 1px solid var(--jp-border-color2);
@@ -295,9 +296,9 @@
   background-color: var(--jp-layout-color1);
 }
 
-/* first section sits flush at the top, no divider or extra gap above it. */
-.jp-jai-controlMenu-paper
-  .jp-jai-personaControls-overflow-subheader:first-child {
+/* The first (or only) label sits flush at the top, no divider or extra gap
+   above it. */
+.jp-jai-controlMenu-paper .jp-jai-controlMenu-subheader:first-child {
   margin-top: 0;
   border-top: none;
 }
@@ -361,8 +362,8 @@
   white-space: nowrap;
 }
 
-/* Usage popover card: labeled sections in the overflow-subheader style, then
-   one row per quantity, label muted and value right-aligned. */
+/* Usage popover card: labeled sections in the control menu's subheader style,
+   then one row per quantity, label muted and value right-aligned. */
 .jp-jai-usage-card {
   padding: 8px 12px;
   min-width: 220px;