@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/MultiSelector/MultiSelector.test.tsx

@@ -35,6 +35,7 @@ import {generateThemeCSS} from '../theme/generateThemeRules';
 import {selectorPresentationStyles} from '../Selector/selectorPresentation.stylex';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {InputGroup, InputGroupText} from '../InputGroup';
+import {focusVars} from '../theme/tokens.stylex';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -4083,6 +4084,164 @@ describe('MultiSelector option actions (grid)', () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
+  it('draws the standard focus ring on the active action cell, from the focus tokens', async () => {
+    // jsdom resolves no custom property, so the ring is read from StyleX
+    // classes: a class name hashes one property and its value, and the same
+    // declaration yields the same class wherever it is written.
+    const ring = stylex.create({
+      active: {
+        outlineWidth: focusVars['--focus-outline-width'],
+        outlineStyle: focusVars['--focus-outline-style'],
+        outlineColor: focusVars['--focus-outline-color'],
+        outlineOffset: focusVars['--focus-outline-offset'],
+      },
+    });
+    const ringClasses = stylex
+      .props(ring.active)
+      .className!.split(' ')
+      .filter(token => /^x[a-z0-9]+$/.test(token));
+    expect(ringClasses).toHaveLength(4);
+
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Labels"
+        options={OPTIONS}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Labels'});
+    await user.click(trigger);
+    const bug = screen.getByRole('row', {name: 'Bug', ...h});
+    const actionCell = bug.children[1] as HTMLElement;
+    for (const token of ringClasses) {
+      expect(actionCell).not.toHaveClass(token);
+    }
+    fireEvent.keyDown(trigger, {key: 'ArrowRight'});
+    expect(trigger).toHaveAttribute('aria-activedescendant', actionCell.id);
+    for (const token of ringClasses) {
+      expect(actionCell).toHaveClass(token);
+    }
+  });
+
+  it('draws no focus ring on an action cell highlighted after pointer input, until a key moves the highlight', async () => {
+    const ring = stylex.create({
+      active: {
+        outlineWidth: focusVars['--focus-outline-width'],
+        outlineStyle: focusVars['--focus-outline-style'],
+        outlineColor: focusVars['--focus-outline-color'],
+        outlineOffset: focusVars['--focus-outline-offset'],
+      },
+    });
+    const ringClasses = stylex
+      .props(ring.active)
+      .className!.split(' ')
+      .filter(token => /^x[a-z0-9]+$/.test(token));
+    expect(ringClasses).toHaveLength(4);
+
+    const user = userEvent.setup();
+    render(
+      <MultiSelector
+        label="Labels"
+        options={OPTIONS}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+    const trigger = screen.getByRole('combobox', {name: 'Labels'});
+    await user.click(trigger);
+    const bug = screen.getByRole('row', {name: 'Bug', ...h});
+    const actionCell = bug.children[1] as HTMLElement;
+    fireEvent.mouseEnter(actionCell);
+    // The hover moved the highlight onto the action cell, without the ring.
+    expect(trigger).toHaveAttribute('aria-activedescendant', actionCell.id);
+    for (const token of ringClasses) {
+      expect(actionCell).not.toHaveClass(token);
+    }
+    // Keyboard navigation back onto the cell draws it.
+    fireEvent.keyDown(trigger, {key: 'ArrowLeft'});
+    fireEvent.keyDown(trigger, {key: 'ArrowRight'});
+    expect(trigger).toHaveAttribute('aria-activedescendant', actionCell.id);
+    for (const token of ringClasses) {
+      expect(actionCell).toHaveClass(token);
+    }
+  });
+
+  describe('ring under mixed input', () => {
+    const ringClasses = () => {
+      const ring = stylex.create({
+        active: {
+          outlineWidth: focusVars['--focus-outline-width'],
+          outlineStyle: focusVars['--focus-outline-style'],
+          outlineColor: focusVars['--focus-outline-color'],
+          outlineOffset: focusVars['--focus-outline-offset'],
+        },
+      });
+      return stylex
+        .props(ring.active)
+        .className!.split(' ')
+        .filter(token => /^x[a-z0-9]+$/.test(token));
+    };
+    const hasRing = (cell: HTMLElement) =>
+      ringClasses().every(token => cell.classList.contains(token));
+
+    async function openWithKeyboardOnBugAction() {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Labels"
+          options={OPTIONS}
+          value={[]}
+          onChange={() => {}}
+        />,
+      );
+      const trigger = screen.getByRole('combobox', {name: 'Labels'});
+      await user.click(trigger);
+      const row = (name: string) => screen.getByRole('row', {name, ...h});
+      fireEvent.keyDown(trigger, {key: 'ArrowRight'});
+      const bugAction = row('Bug').children[1] as HTMLElement;
+      expect(trigger).toHaveAttribute('aria-activedescendant', bugAction.id);
+      expect(hasRing(bugAction)).toBe(true);
+      return {trigger, row, bugAction};
+    }
+
+    it('keeps the ring when the pointer crosses a disabled option the highlight ignores', async () => {
+      const {trigger, row, bugAction} = await openWithKeyboardOnBugAction();
+      fireEvent.mouseEnter(row('Docs').children[0]);
+      expect(trigger).toHaveAttribute('aria-activedescendant', bugAction.id);
+      expect(hasRing(bugAction)).toBe(true);
+    });
+
+    it('follows the keyboard modality when a hover moves the highlight to another action', async () => {
+      const {trigger, row} = await openWithKeyboardOnBugAction();
+      const docsAction = row('Docs').children[1] as HTMLElement;
+      fireEvent.mouseEnter(docsAction);
+      expect(trigger).toHaveAttribute('aria-activedescendant', docsAction.id);
+      expect(hasRing(docsAction)).toBe(true);
+    });
+
+    it('draws no ring for a modifier chord after pointer input', async () => {
+      const user = userEvent.setup();
+      render(
+        <MultiSelector
+          label="Labels"
+          options={OPTIONS}
+          value={[]}
+          onChange={() => {}}
+        />,
+      );
+      const trigger = screen.getByRole('combobox', {name: 'Labels'});
+      await user.click(trigger);
+      const bugAction = screen.getByRole('row', {name: 'Bug', ...h})
+        .children[1] as HTMLElement;
+      fireEvent.mouseEnter(bugAction);
+      expect(hasRing(bugAction)).toBe(false);
+      fireEvent.keyDown(trigger, {key: 'ArrowRight', ctrlKey: true});
+      expect(hasRing(bugAction)).toBe(false);
+    });
+  });
+
   it('the inline-end arrow reaches the action cell, Enter fires it, inline-start returns', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();

package/src/MultiSelector/MultiSelector.tsx

@@ -50,6 +50,7 @@ import type {IndicatorPosition} from '../Indicator';
 import {Badge} from '../Badge';
 import {
   colorVars,
+  focusVars,
   sizeVars,
   spacingVars,
   radiusVars,
@@ -74,7 +75,10 @@ import {
 import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {devWarn, warnOnce} from '../utils/devWarning';
-import {FOCUS_OUTLINE_PARTS} from '../utils/focusOutline.stylex';
+import {
+  getInteractionModality,
+  useInteractionModalityTracking,
+} from '../utils/interactionModality';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
 import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
@@ -436,11 +440,15 @@ const styles = stylex.create({
     flexShrink: 0,
     borderRadius: radiusVars['--radius-element'],
   },
+  // The standard ring, from the focus tokens themselves: inside
+  // `stylex.create` StyleX resolves an imported `defineVars` group, and a
+  // plain object such as `FOCUS_OUTLINE_PARTS` compiles to variables nothing
+  // defines.
   actionCellActive: {
-    outlineWidth: FOCUS_OUTLINE_PARTS.outlineWidth,
-    outlineStyle: FOCUS_OUTLINE_PARTS.outlineStyle,
-    outlineColor: FOCUS_OUTLINE_PARTS.outlineColor,
-    outlineOffset: FOCUS_OUTLINE_PARTS.outlineOffset,
+    outlineWidth: focusVars['--focus-outline-width'],
+    outlineStyle: focusVars['--focus-outline-style'],
+    outlineColor: focusVars['--focus-outline-color'],
+    outlineOffset: focusVars['--focus-outline-offset'],
   },
 
   // Empty state
@@ -1752,8 +1760,8 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     getActionCellId,
     activeDescendantId,
     onTriggerClick,
-    onKeyDown,
-    onItemMouseEnter,
+    onKeyDown: onComboboxKeyDown,
+    onItemMouseEnter: onComboboxItemMouseEnter,
   } = useMultiCombobox({
     selectableItems: sortedItems,
     isDisabled: isDisabled || isEffectivelyReadOnly,
@@ -1784,6 +1792,29 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     ),
   });
 
+  // A hover moves the highlight too, but the focus ring follows the shared
+  // interaction modality (architecture:interaction-modality INV1): it is read
+  // whenever a key or the pointer moves the highlight, so an action cell
+  // highlighted after pointer input keeps the hover treatment and no ring.
+  useInteractionModalityTracking();
+  const [isKeyboardHighlight, setIsKeyboardHighlight] = useState(
+    () => getInteractionModality() === 'keyboard',
+  );
+  const onKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLElement>) => {
+      onComboboxKeyDown(event);
+      setIsKeyboardHighlight(getInteractionModality() === 'keyboard');
+    },
+    [onComboboxKeyDown],
+  );
+  const onItemMouseEnter = useCallback(
+    (...args: Parameters<typeof onComboboxItemMouseEnter>) => {
+      onComboboxItemMouseEnter(...args);
+      setIsKeyboardHighlight(getInteractionModality() === 'keyboard');
+    },
+    [onComboboxItemMouseEnter],
+  );
+
   // The trigger button owns its click so a consumer `onClick`, which lands on
   // the button, composes after the built-in toggle. A press elsewhere in the
   // control box (padding, start icon, chevron) still opens the panel.
@@ -2117,6 +2148,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
                   styles.actionCell,
                   isHighlighted &&
                     highlightedCell === 'action' &&
+                    isKeyboardHighlight &&
                     styles.actionCellActive,
                 )}>
                 {isSelectAll || isCreate ? null : item.action}
@@ -2131,6 +2163,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     [
       isGrid,
       highlightedCell,
+      isKeyboardHighlight,
       getActionCellId,
       renderOption,
       indicatorPosition,

package/src/MultiSelector/OptionActions.a11y.chromium.spec.ts

@@ -6,8 +6,10 @@
  *   built Storybook.
  * @output Real-engine proof for option actions: the action is visible at rest
  *   beside its row (`spec:AST-058` FR8), the keyboard reaches it through the
- *   inline-end arrow in both directions and fires it with Enter, and the
- *   highlight follows a real mouse across rows and actions.
+ *   inline-end arrow in both directions and fires it with Enter, the active
+ *   action cell draws the standard focus ring when the shared input modality
+ *   is keyboard and not after pointer input, and the highlight follows a real
+ *   mouse across rows and actions.
  * @position Run with `pnpm test:a11y-contract`; paint, pointer paths and the
  *   active descendant as an engine exposes them are not jsdom claims.
  */
@@ -143,6 +145,114 @@ test('the keyboard reaches an action through the inline-end arrow and fires it w
   await expect.poll(async () => activeDescendant(page)).toBe('row:Bug');
 });
 
+test('the active action cell draws the standard focus ring', async ({page}) => {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-multiselector--row-actions&viewMode=story`,
+  );
+  const search = page.getByRole('combobox');
+  await expect(search).toBeFocused();
+  await search.press('ArrowDown'); // select-all
+  await search.press('ArrowDown'); // Feature (no action)
+  await search.press('ArrowDown'); // Bug
+  await search.press('ArrowRight');
+  await expect
+    .poll(async () => activeDescendant(page))
+    .toBe('gridcell:Edit Bug');
+  const ring = await page.evaluate(() => {
+    const id = document.activeElement?.getAttribute('aria-activedescendant');
+    const cell = id ? document.getElementById(id) : null;
+    if (!cell) {
+      return null;
+    }
+    const cs = getComputedStyle(cell);
+    // The ring the focus tokens describe, resolved by the browser on a probe.
+    const probe = document.createElement('div');
+    probe.style.cssText =
+      'outline-width:var(--focus-outline-width);outline-style:var(--focus-outline-style);outline-color:var(--focus-outline-color);outline-offset:var(--focus-outline-offset)';
+    document.body.appendChild(probe);
+    const want = getComputedStyle(probe);
+    const result = {
+      style: cs.outlineStyle,
+      width: cs.outlineWidth,
+      color: cs.outlineColor,
+      offset: cs.outlineOffset,
+      wantStyle: want.outlineStyle,
+      wantWidth: want.outlineWidth,
+      wantColor: want.outlineColor,
+      wantOffset: want.outlineOffset,
+    };
+    probe.remove();
+    return result;
+  });
+  expect(ring).not.toBeNull();
+  expect(ring!.style).not.toBe('none');
+  expect(ring!.width).not.toBe('0px');
+  expect(ring!.style).toBe(ring!.wantStyle);
+  expect(ring!.width).toBe(ring!.wantWidth);
+  expect(ring!.color).toBe(ring!.wantColor);
+  expect(ring!.offset).toBe(ring!.wantOffset);
+  // Back on the option cell, the action cell drops the ring.
+  await search.press('ArrowLeft');
+  await expect.poll(async () => activeDescendant(page)).toBe('row:Bug');
+  const after = await page
+    .getByRole('row', {name: 'Bug'})
+    .locator('[data-multi-selector-action-cell]')
+    .evaluate(cell => getComputedStyle(cell).outlineStyle);
+  expect(after).toBe('none');
+});
+
+test('the action-cell ring follows the shared input modality', async ({
+  page,
+}) => {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-multiselector--row-actions&viewMode=story`,
+  );
+  const search = page.getByRole('combobox');
+  await expect(search).toBeFocused();
+  const actionCell = (name: string) =>
+    page.getByRole('row', {name}).locator('[data-multi-selector-action-cell]');
+  const outlineStyle = async (name: string) =>
+    actionCell(name).evaluate(cell => getComputedStyle(cell).outlineStyle);
+  const hover = async (name: string) => {
+    const cell = await box(actionCell(name));
+    await page.mouse.move(cell.x + cell.width / 2, cell.y + cell.height / 2, {
+      steps: 6,
+    });
+  };
+
+  // Pointer input: a click into the search field, then a hover onto an
+  // action, moves the highlight without the ring, and leaves none behind.
+  await search.click();
+  await hover('Bug');
+  await expect
+    .poll(async () => activeDescendant(page))
+    .toBe('gridcell:Edit Bug');
+  expect(await outlineStyle('Bug')).toBe('none');
+  // A modifier chord is not keyboard navigation for the shared tracker.
+  await search.press('Control+ArrowRight');
+  expect(await outlineStyle('Bug')).toBe('none');
+  await page.mouse.move(1, 1, {steps: 6});
+  expect(await outlineStyle('Bug')).toBe('none');
+
+  // Keyboard input: back onto the same cell, the ring is drawn.
+  await search.press('ArrowLeft');
+  await expect.poll(async () => activeDescendant(page)).toBe('row:Bug');
+  await search.press('ArrowRight');
+  await expect
+    .poll(async () => activeDescendant(page))
+    .toBe('gridcell:Edit Bug');
+  expect(await outlineStyle('Bug')).not.toBe('none');
+
+  // Still keyboard-driven, a hover that moves the highlight to another
+  // row's action carries the ring with it.
+  await hover('P0');
+  await expect
+    .poll(async () => activeDescendant(page))
+    .toBe('gridcell:Edit P0');
+  expect(await outlineStyle('P0')).not.toBe('none');
+  expect(await outlineStyle('Bug')).toBe('none');
+});
+
 test('under RTL the inline-end arrow is ArrowLeft', async ({page}) => {
   await page.goto(
     `${storybook.origin}/iframe.html?id=core-multiselector--row-actions-rtl&viewMode=story`,

package/src/MultiSelector/hooks.ts

@@ -6,10 +6,12 @@
  * @file hooks.ts
  * @input Uses React hooks, MultiSelectorOptionData type
  * @output Exports useMultiCombobox hook
- * @position Internal hook; used by MultiSelector.tsx
+ * @position Public hook, exported from the MultiSelector entry point; used by
+ *   MultiSelector.tsx
  *
  * SYNC: When modified, update:
  * - /packages/core/src/MultiSelector/index.ts
+ * - /packages/core/src/MultiSelector/useMultiCombobox.doc.mjs
  */
 
 import {useCallback, useRef, useState} from 'react';

package/src/MultiSelector/useMultiCombobox.doc.mjs

@@ -0,0 +1,267 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useMultiCombobox',
+  displayName: 'useMultiCombobox',
+  group: 'MultiSelector',
+  keywords: [
+    'combobox',
+    'multi-select',
+    'multiselect',
+    'listbox',
+    'grid',
+    'toggle',
+    'highlight',
+    'active option',
+    'aria-activedescendant',
+    'keyboard',
+    'headless',
+    'apg',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseMultiComboboxOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.selectableItems',
+      type: 'MultiSelectorOptionData[]',
+      description:
+        'The options in the same order as they render. Options with `disabled` cannot be toggled and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list still lands on the first or last option.',
+      required: true,
+    },
+    {
+      name: 'options.isOpen',
+      type: 'boolean',
+      description: 'Whether the list is shown. The caller owns this state.',
+      required: true,
+    },
+    {
+      name: 'options.onOpen',
+      type: '() => unknown',
+      description:
+        'Called to show the list. Return `false` to refuse; the hook then leaves the highlight alone.',
+      required: true,
+    },
+    {
+      name: 'options.onClose',
+      type: '() => void',
+      description: 'Called to hide the list. The highlight resets first.',
+      required: true,
+    },
+    {
+      name: 'options.onToggle',
+      type: '(itemValue: string) => void',
+      description:
+        'Called with the value of the option to add or remove. Toggling keeps the list open.',
+      required: true,
+    },
+    {
+      name: 'options.listboxId',
+      type: 'string',
+      description:
+        "The listbox (or grid) element's id. Option and action-cell ids are derived from it.",
+      required: true,
+    },
+    {
+      name: 'options.hasSearch',
+      type: 'boolean',
+      description:
+        'Whether the list has its own search field. Space then types instead of toggling, opening by a press or Enter does not pre-highlight (ArrowDown and ArrowUp still open on the first and last option), Delete and Backspace edit the query, and type-to-select is off. Home and End still jump to the first and last option, so a search input that keeps them for the caret should stop them before this handler and rely on PageUp and PageDown.',
+      default: 'false',
+    },
+    {
+      name: 'options.onClear',
+      type: '() => void',
+      description:
+        'Clears every selected value. When provided, Delete or Backspace on the closed control clears them, so clearing is not pointer-only. Ignored while the list is open or with `hasSearch`.',
+    },
+    {
+      name: 'options.hasValue',
+      type: 'boolean',
+      description:
+        'Whether anything is selected. The Delete and Backspace clear is skipped when false.',
+      default: 'false',
+    },
+    {
+      name: 'options.isGrid',
+      type: 'boolean',
+      description:
+        "Whether each row pairs an option cell with an action cell. The inline-end arrow then moves the highlight to the row's action and the inline-start arrow back, following visual direction in right-to-left layouts, and Enter on the action runs `onActivateAction` instead of toggling.",
+      default: 'false',
+    },
+    {
+      name: 'options.rowHasAction',
+      type: '(index: number) => boolean',
+      description:
+        'In a grid, whether the row at `index` has an action cell to move to.',
+    },
+    {
+      name: 'options.onActivateAction',
+      type: '(index: number) => void',
+      description:
+        "In a grid, runs the control in the highlighted row's action cell. The selection does not change.",
+    },
+    {
+      name: 'options.isDisabled',
+      type: 'boolean',
+      description: 'Whether the control ignores clicks and keys.',
+      default: 'false',
+    },
+  ],
+  returns: [
+    {
+      name: 'highlightedIndex',
+      type: 'number',
+      description: 'Index of the active row, or -1 when none is active.',
+    },
+    {
+      name: 'setHighlightedIndex',
+      type: '(index: number) => void',
+      description:
+        "Sets the active row, for example after filtering. The highlight lands on the row's option cell.",
+    },
+    {
+      name: 'highlightedCell',
+      type: "'option' | 'action'",
+      description:
+        "Which cell of the active row is highlighted; `'action'` only in a grid.",
+    },
+    {
+      name: 'activeDescendantId',
+      type: 'string | undefined',
+      description:
+        "The id to pass as the control's `aria-activedescendant`: the active option, or its action cell in a grid. Undefined while the list is closed or nothing is active.",
+    },
+    {
+      name: 'getItemId',
+      type: '(index: number) => string',
+      description: 'The id to render on the option at `index`.',
+    },
+    {
+      name: 'getActionCellId',
+      type: '(index: number) => string',
+      description:
+        'In a grid, the id to render on the action cell of row `index`.',
+    },
+    {
+      name: 'onTriggerClick',
+      type: '() => void',
+      description: 'Toggles the list from a press on the control.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description:
+        'Key handler for the control that keeps focus. ArrowDown and ArrowUp open the list or move the active row; Enter (and Space without search) toggles the active option and keeps the list open; Escape and Tab close it; Home, End, PageUp and PageDown jump to the first or last option; without search, typed characters move to the first option whose label starts with them.',
+    },
+    {
+      name: 'onItemMouseEnter',
+      type: "(item: MultiSelectorOptionData, index: number, cell?: 'option' | 'action') => void",
+      description:
+        'Makes the hovered option, or its action cell, active without scrolling the list or moving focus.',
+    },
+  ],
+  usage: {
+    description:
+      'Tracks the active option of a multi-select combobox and handles its keys, while DOM focus stays on the control. It powers MultiSelector; unlike useCombobox, toggling an option keeps the list open, and rows can carry an action cell. It renders nothing and sets no attributes: the caller renders the control and the list, and wires the ARIA attributes from what it returns.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Render each option with `id={getItemId(index)}` and pass `activeDescendantId` as the control's `aria-activedescendant`.",
+      },
+      {
+        guidance: true,
+        description:
+          'Use `isGrid` only when rows carry a control next to the option; give each action cell `id={getActionCellId(index)}`.',
+      },
+      {
+        guidance: true,
+        description:
+          'Announce the number of results through useAnnounce when the options change for a new query.',
+      },
+      {
+        guidance: false,
+        description:
+          'Close the list after each toggle; a multi-select stays open so several options can be picked in a row.',
+      },
+    ],
+  },
+  relatedComponents: ['MultiSelector'],
+  relatedHooks: ['useCombobox', 'useAnnounce'],
+  importPath: '@astryxdesign/core/MultiSelector',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Multi-select combobox state + keys; focus stays on control. Powers MultiSelector. Toggle keeps list open; rows may carry an action cell (grid). Renders nothing, sets no attrs: caller renders + wires ARIA.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.selectableItems':
+      'options in render order; disabled ones not toggleable, skipped while moving in open list (ArrowDown/Up opening still lands first / last).',
+    'options.isOpen': 'list shown; caller owns state.',
+    'options.onOpen':
+      'show list; return false to refuse (highlight untouched).',
+    'options.onClose': 'hide list; highlight resets first.',
+    'options.onToggle': 'add / remove value; list stays open.',
+    'options.listboxId':
+      'listbox / grid id; option + action-cell ids derive from it.',
+    'options.hasSearch':
+      'own search field: Space types, press / Enter opening does not pre-highlight (ArrowDown/Up still first / last), Delete / Backspace edit query, no type-to-select. Home / End still jump; stop them first to keep them for the caret, use PageUp / PageDown.',
+    'options.onClear':
+      'clear all; Delete / Backspace on closed control. ignored when open or hasSearch.',
+    'options.hasValue': 'anything selected; clear skipped when false.',
+    'options.isGrid':
+      'rows = option + action cell; inline-end / inline-start arrows move between them (RTL-aware); Enter on action -> onActivateAction.',
+    'options.rowHasAction': 'grid: row at index has an action cell.',
+    'options.onActivateAction':
+      "grid: run highlighted row's action; selection unchanged.",
+    'options.isDisabled': 'ignore clicks + keys.',
+  },
+  returnDescriptions: {
+    highlightedIndex: 'active row index, -1 = none.',
+    setHighlightedIndex: 'set active row (lands on option cell).',
+    highlightedCell: "'option' | 'action' (action only in grid).",
+    activeDescendantId:
+      'control aria-activedescendant: active option or its action cell; undefined when closed / none.',
+    getItemId: 'id for option at index.',
+    getActionCellId: 'grid: id for action cell of row index.',
+    onTriggerClick: 'toggle list from a press on control.',
+    onKeyDown:
+      'control keydown: ArrowDown/Up open or move; Enter (Space w/o search) toggles, stays open; Escape / Tab close; Home / End / PageUp / PageDown jump; typed chars jump by label prefix (w/o search).',
+    onItemMouseEnter:
+      'hover makes option / action cell active; no scroll, no focus move.',
+  },
+  usage: {
+    description:
+      'Headless multi-select combobox: active option + keys, focus stays on control; toggle keeps list open. Caller renders + wires ARIA.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Option id = getItemId(index); control aria-activedescendant = activeDescendantId.',
+      },
+      {
+        guidance: true,
+        description:
+          'isGrid only when rows carry a control; action cell id = getActionCellId(index).',
+      },
+      {
+        guidance: true,
+        description: 'Announce result count via useAnnounce on new query.',
+      },
+      {
+        guidance: false,
+        description: 'Close after each toggle; multi-select stays open.',
+      },
+    ],
+  },
+};