@jupyter-ai/persona-manager 0.1.0 → 0.1.2

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 ControlMenu(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 OverflowControlsMenu(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,37 @@ 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. Sticky: when the menu scrolls, the
+ * label pins to the top, so the group the visible rows belong to stays
+ * readable; in the overflow menu the next section's label paints over it on
+ * arrival.
  */
-function ControlItem(props) {
+function ControlMenuSubheader(props) {
+    return (React.createElement(ListSubheader, { id: props.id, 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.
+ControlMenuSubheader.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 ControlMenu(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(ControlMenuSubheader, { id: headingId, label: control.label }),
             React.createElement(ChoiceMenuItem, { primary: defaultChoiceLabel(control), description: null, selected: control.selection === null, onSelect: () => {
                     setAnchor(null);
                     onSelect(null);
@@ -234,15 +258,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 OverflowControlsMenu(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(ControlMenuSubheader, { 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);
@@ -321,12 +343,12 @@ function ControlsRow(props) {
     const visible = controls.slice(0, visibleCount);
     const overflow = controls.slice(visibleCount);
     return (React.createElement("div", { className: `${SELECTOR_CLASS}-controls`, ref: rowRef },
-        React.createElement("div", { className: `${SELECTOR_CLASS}-controls-measure`, ref: measureRef, "aria-hidden": "true" }, controls.map(control => (React.createElement(ControlItem, { key: control.id, control: control, onSelect: v => onChange(control, v) })))),
-        visible.map(control => (React.createElement(ControlItem, { key: control.id, control: control, onSelect: v => onChange(control, v) }))),
+        React.createElement("div", { className: `${SELECTOR_CLASS}-controls-measure`, ref: measureRef, "aria-hidden": "true" }, controls.map(control => (React.createElement(ControlMenu, { key: control.id, control: control, onSelect: v => onChange(control, v) })))),
+        visible.map(control => (React.createElement(ControlMenu, { key: control.id, control: control, onSelect: v => onChange(control, v) }))),
         overflow.length ? (React.createElement(React.Fragment, null,
             React.createElement("button", { type: "button", ref: overflowBtnRef, className: `${SELECTOR_CLASS} ${SELECTOR_CLASS}-overflow-btn`, onClick: event => setOverflowAnchor(event.currentTarget), title: "More controls", "aria-label": "More controls" },
                 React.createElement(MoreHorizIcon, { fontSize: "small" })),
-            React.createElement(OverflowMenu, { controls: overflow, anchor: overflowAnchor, onClose: () => setOverflowAnchor(null), onChange: onChange }))) : null));
+            React.createElement(OverflowControlsMenu, { controls: overflow, anchor: overflowAnchor, onClose: () => setOverflowAnchor(null), onChange: onChange }))) : null));
 }
 // All formatters pin the `en` locale so numbers agree with each other and
 // with the surrounding English labels.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jupyter-ai/persona-manager",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "The core manager & registry for AI personas in Jupyter AI",
     "keywords": [
         "jupyter",
@@ -67,10 +67,14 @@
     "devDependencies": {
         "@jupyterlab/builder": "^4.0.0",
         "@jupyterlab/testutils": "^4.0.0",
+        "@testing-library/dom": "^10.4.0",
+        "@testing-library/react": "^16.3.0",
+        "@testing-library/user-event": "^14.6.0",
         "@types/jest": "^29.2.0",
         "@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,158 @@
+/**
+ * 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 { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {
+  Control,
+  ControlMenu,
+  OverflowControlsMenu
+} from '../persona-controls';
+
+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 }
+    ]
+  };
+}
+
+function heading(): HTMLElement {
+  return document.querySelector(SUBHEADER_SELECTOR) as HTMLElement;
+}
+
+function focused(): HTMLElement {
+  return document.activeElement as HTMLElement;
+}
+
+describe('control menus', () => {
+  describe('control dropdown', () => {
+    async function openMenu(
+      control: Control,
+      onSelect: (value: string | null) => void = () => undefined
+    ): Promise<ReturnType<typeof userEvent.setup>> {
+      const user = userEvent.setup();
+      render(<ControlMenu control={control} onSelect={onSelect} />);
+      await user.click(screen.getByRole('button'));
+      return user;
+    }
+
+    it('opens titled by a heading that names the menu', async () => {
+      await openMenu(modelControl('beta'));
+      expect(heading().textContent).toBe('Model');
+      expect(heading().hasAttribute('tabindex')).toBe(false);
+      expect(heading().id).toBeTruthy();
+      expect(screen.getByRole('menu').getAttribute('aria-labelledby')).toBe(
+        heading().id
+      );
+      // Sticky, so the title stays visible while a long option list scrolls.
+      expect(heading().classList.contains('MuiListSubheader-sticky')).toBe(
+        true
+      );
+    });
+
+    it('focuses the selected row and moves focus with the keyboard', async () => {
+      const user = await openMenu(modelControl('beta'));
+      // Rows: heading, "Default (Alpha)", "Alpha", "Beta"; "Beta" is selected.
+      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Beta' }));
+      // Wrapping from the last row skips the heading to the first choice row.
+      await user.keyboard('{ArrowDown}');
+      expect(focused()).toBe(
+        screen.getByRole('menuitem', { name: 'Default (Alpha)' })
+      );
+      await user.keyboard('{ArrowDown}');
+      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Alpha' }));
+      // Type-ahead: "b" jumps to Beta.
+      await user.keyboard('b');
+      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Beta' }));
+    });
+
+    it('leaves focus in place when type-ahead matches only the heading', async () => {
+      const user = await 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.
+      await user.keyboard('m');
+      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Beta' }));
+    });
+
+    it('falls back to the first choice row when the selection is stale', async () => {
+      // A selection id the persona no longer advertises leaves no row
+      // selected; initial focus then skips the heading to the first row.
+      await openMenu(modelControl('stale'));
+      expect(focused()).toBe(
+        screen.getByRole('menuitem', { name: 'Default (Alpha)' })
+      );
+    });
+
+    it('activates the focused row with Enter', async () => {
+      const onSelect = jest.fn();
+      const user = await openMenu(modelControl(null), onSelect);
+      await user.keyboard('{ArrowDown}{ArrowDown}{Enter}');
+      expect(onSelect).toHaveBeenCalledWith('beta');
+    });
+  });
+
+  describe('overflow menu', () => {
+    it('is labeled and arrows skip the section headings', async () => {
+      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: 'b1',
+        selection: 'stale',
+        options: [{ id: 'b1', name: 'B one', description: null }]
+      };
+      const user = userEvent.setup();
+      const anchor = document.createElement('button');
+      document.body.appendChild(anchor);
+      render(
+        <OverflowControlsMenu
+          controls={[first, second]}
+          anchor={anchor}
+          onClose={() => undefined}
+          onChange={() => undefined}
+        />
+      );
+      expect(screen.getByRole('menu').getAttribute('aria-label')).toBe(
+        'More controls'
+      );
+      const headings = Array.from(
+        document.querySelectorAll(SUBHEADER_SELECTOR)
+      );
+      expect(headings.map(h => h.textContent)).toEqual(['Aaa', 'Bbb']);
+      // Sticky, so the section a scrolled row belongs to stays visible.
+      for (const h of headings) {
+        expect(h.classList.contains('MuiListSubheader-sticky')).toBe(true);
+      }
+      // "A one" is the only selected row; ArrowDown crosses the "Bbb" heading
+      // to the next section's first choice row.
+      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'A one' }));
+      await user.keyboard('{ArrowDown}');
+      expect(focused()).toBe(
+        screen.getByRole('menuitem', { name: 'Default (B one)' })
+      );
+      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,44 @@ 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. Sticky: when the menu scrolls, the
+ * label pins to the top, so the group the visible rows belong to stays
+ * readable; in the overflow menu the next section's label paints over it on
+ * arrival.
  */
-function ControlItem(props: {
+function ControlMenuSubheader(props: {
+  label: string;
+  id?: string;
+}): JSX.Element {
+  return (
+    <ListSubheader id={props.id} 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.
+ControlMenuSubheader.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 ControlMenu(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 +387,10 @@ function ControlItem(props: {
         anchorEl={anchor}
         open={!!anchor}
         onClose={() => setAnchor(null)}
+        MenuListProps={{ 'aria-labelledby': headingId }}
         {...menuAnchorProps}
       >
+        <ControlMenuSubheader id={headingId} label={control.label} />
         <ChoiceMenuItem
           primary={defaultChoiceLabel(control)}
           description={null}
@@ -377,12 +419,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 OverflowControlsMenu(props: {
   controls: Control[];
   anchor: HTMLElement | null;
   onClose: () => void;
@@ -394,16 +434,14 @@ function OverflowMenu(props: {
       anchorEl={anchor}
       open={!!anchor}
       onClose={onClose}
+      MenuListProps={{ 'aria-label': 'More controls' }}
       {...menuAnchorProps}
     >
       {controls.flatMap(control => [
-        <ListSubheader
+        <ControlMenuSubheader
           key={`${control.id}-label`}
-          disableSticky
-          className={`${SELECTOR_CLASS}-overflow-subheader`}
-        >
-          {control.label}
-        </ListSubheader>,
+          label={control.label}
+        />,
         <ChoiceMenuItem
           key={`${control.id}-default`}
           primary={defaultChoiceLabel(control)}
@@ -517,7 +555,7 @@ function ControlsRow(props: {
         aria-hidden="true"
       >
         {controls.map(control => (
-          <ControlItem
+          <ControlMenu
             key={control.id}
             control={control}
             onSelect={v => onChange(control, v)}
@@ -526,7 +564,7 @@ function ControlsRow(props: {
       </div>
 
       {visible.map(control => (
-        <ControlItem
+        <ControlMenu
           key={control.id}
           control={control}
           onSelect={v => onChange(control, v)}
@@ -545,7 +583,7 @@ function ControlsRow(props: {
           >
             <MoreHorizIcon fontSize="small" />
           </button>
-          <OverflowMenu
+          <OverflowControlsMenu
             controls={overflow}
             anchor={overflowAnchor}
             onClose={() => setOverflowAnchor(null)}

package/style/base.css

@@ -229,6 +229,15 @@
   box-shadow: var(--jp-elevation-z6);
 }
 
+/* Keep focus-scrolled rows clear of the stuck group label: when arrow keys
+   scroll a row into view at the top, offset it by the label's height so the
+   label does not cover it. Only menus containing a group label need the
+   offset; the persona picker and usage popover share this paper class and
+   keep edge-aligned scrolling. */
+.jp-jai-controlMenu-paper:has(.jp-jai-controlMenu-subheader) {
+  scroll-padding-top: 32px;
+}
+
 /* stylelint-disable selector-class-pattern -- theming MUI's menu item classes */
 .jp-jai-controlMenu-paper .MuiMenuItem-root {
   padding: 6px 12px;
@@ -278,10 +287,15 @@
   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. The labels are sticky:
+   sticky is MUI's ListSubheader default, and its sticky class supplies the
+   positioning. The opaque background is load-bearing, scrolled rows pass
+   beneath it. One line only, so stacked sticky labels in the overflow menu
+   cover each other exactly. */
+.jp-jai-controlMenu-paper .jp-jai-controlMenu-subheader {
   margin-top: 8px;
   padding: 8px 12px 2px;
   border-top: 1px solid var(--jp-border-color2);
@@ -293,11 +307,14 @@
   text-transform: uppercase;
   color: var(--jp-ui-font-color1);
   background-color: var(--jp-layout-color1);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
-/* 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 +378,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;