@astryxdesign/core 0.7.1 → 0.7.2-canary.b69b2df

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.',
+      },
+    ],
+  },
+};

package/src/Pagination/Pagination.doc.mjs

@@ -137,7 +137,7 @@ export const docs = {
       name: 'variant',
       type: "'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none'",
       description:
-        "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label ('Page [ n ] / N') flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons.",
+        "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y' (add first/last buttons with hasFirstLast), 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label ('Page [ n ] / N') flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons.",
       default: "'pages'",
     },
     {
@@ -150,8 +150,8 @@ export const docs = {
       name: 'hasFirstLast',
       type: 'boolean',
       description:
-        "Whether to show first/last («/») double-chevron buttons flanking prev/next. Only applies to the 'input' variant; omitted when the page count is unknown (cursor/hasMore pagination).",
-      default: 'true',
+        "Whether to show first/last («/») double-chevron buttons flanking prev/next. Applies to the 'input' variant (shown unless false) and the 'compact' variant (shown only when true); other variants ignore it. Omitted when the page count is unknown (cursor/hasMore pagination).",
+      default: "true for 'input'; false for 'compact'",
     },
     {
       name: 'step',
@@ -288,7 +288,7 @@ export const docsZh = {
       name: 'variant',
       type: "'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none'",
       description:
-        "控制上一页/下一页按钮之间显示内容的视觉变体。'pages' 显示带省略号的页码按钮，'count' 显示 'X-Y of Z' 文本，'compact' 显示 'Page X of Y'，'dots' 显示点指示器，'input' 显示带前置标签的可编辑页码框——'Page [ n ] / N'——默认两侧带首页/末页按钮，'none' 仅显示上一页/下一页按钮。",
+        "控制上一页/下一页按钮之间显示内容的视觉变体。'pages' 显示带省略号的页码按钮，'count' 显示 'X-Y of Z' 文本，'compact' 显示 'Page X of Y'（可通过 hasFirstLast 添加首页/末页按钮），'dots' 显示点指示器，'input' 显示带前置标签的可编辑页码框——'Page [ n ] / N'——默认两侧带首页/末页按钮，'none' 仅显示上一页/下一页按钮。",
       default: "'pages'",
     },
     {
@@ -301,8 +301,8 @@ export const docsZh = {
       name: 'hasFirstLast',
       type: 'boolean',
       description:
-        "是否显示首页/末页（«/»）双箭头按钮，位于上一页/下一页两侧。仅适用于 'input' 变体；当页数未知（游标/hasMore 分页）时省略。",
-      default: 'true',
+        "是否显示首页/末页（«/»）双箭头按钮，位于上一页/下一页两侧。适用于 'input' 变体（除非设为 false 否则显示）和 'compact' 变体（仅在设为 true 时显示）；其他变体忽略此项。当页数未知（游标/hasMore 分页）时省略。",
+      default: "'input' 为 true；'compact' 为 false",
     },
     {
       name: 'step',
@@ -400,7 +400,7 @@ export const docsDense = {
     onPageSizeChange: 'Called on page size change. Auto resets to page 1.',
     variant: "Display between prev/next. 'input' = 'Page [n] / N' + first/last.",
     pageLabel: "Noun before the 'input' box (e.g. 'Page' or 'Row'). Navigation stays page-based. Default localized 'Page'.",
-    hasFirstLast: "Show first/last («/») buttons in the 'input' variant. Omitted when total unknown.",
+    hasFirstLast: "Show first/last («/») buttons. 'input' default true; 'compact' default false (opt in). Other variants ignore. Omitted when total unknown.",
     step: 'Pages the prev/next buttons advance per click. Clamped to range; < 1 or non-integer falls back to 1.',
     siblingCount: "Page buttons each side of current; only variant='pages'.",
     size: 'Control size.',

package/src/Pagination/Pagination.spec.md

@@ -92,15 +92,15 @@ and usage remain documented in `Pagination.doc.mjs`.
 
 ### Representative states
 
-| State                         | Required invariant                                                                | Allowed variation                                  |
-| ----------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
-| Numbered, known page count    | Page number buttons render; Ellipsis appears only where pages are omitted.        | Page count, sibling range, and active page.        |
-| Count with known item total   | Count readout renders between Previous/next buttons.                              | Range and total text.                              |
-| Compact with known page count | Compact readout renders between Previous/next buttons.                            | Current and total page text.                       |
-| Dots with known page count    | One Dot renders for each page and active state stays on the Dot target.           | Dot count and active Dot.                          |
-| Input with known page count   | Page input label, Page input, and Page input total render; First/last may render. | Label text and first/last opt-out.                 |
-| Input with unknown page count | Page input label and disabled Page input remain; total and First/last are absent. | Cursor-backed current page.                        |
-| None                          | Previous/next buttons remain without a presentation-specific part between them.   | Enabled state follows current paging availability. |
+| State                         | Required invariant                                                                           | Allowed variation                                  |
+| ----------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Numbered, known page count    | Page number buttons render; Ellipsis appears only where pages are omitted.                   | Page count, sibling range, and active page.        |
+| Count with known item total   | Count readout renders between Previous/next buttons.                                         | Range and total text.                              |
+| Compact with known page count | Compact readout renders between Previous/next buttons; First/last render only when opted in. | Current and total page text and first/last opt-in. |
+| Dots with known page count    | One Dot renders for each page and active state stays on the Dot target.                      | Dot count and active Dot.                          |
+| Input with known page count   | Page input label, Page input, and Page input total render; First/last may render.            | Label text and first/last opt-out.                 |
+| Input with unknown page count | Page input label and disabled Page input remain; total and First/last are absent.            | Cursor-backed current page.                        |
+| None                          | Previous/next buttons remain without a presentation-specific part between them.              | Enabled state follows current paging availability. |
 
 The optional Page-size selector may precede the paging controls in any current
 presentation when page-size options are provided.

package/src/Pagination/Pagination.test.tsx

@@ -20,6 +20,7 @@ import {
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Pagination, generatePageRange} from './Pagination';
+import {InternationalizationProvider} from '../i18n';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -119,6 +120,28 @@ describe('Pagination', () => {
       ).toBeInTheDocument();
     });
 
+    it('does not introduce Stack theme targets around navigation controls', () => {
+      const {rerender} = render(
+        <Pagination page={3} onChange={() => {}} totalPages={5} />,
+      );
+      expect(
+        screen.getByRole('navigation').querySelector('.astryx-stack'),
+      ).toBeNull();
+
+      rerender(
+        <Pagination
+          page={3}
+          onChange={() => {}}
+          totalPages={5}
+          variant="compact"
+          hasFirstLast
+        />,
+      );
+      expect(
+        screen.getByRole('navigation').querySelector('.astryx-stack'),
+      ).toBeNull();
+    });
+
     it('gives the prev/next carets a hover tooltip matching their accessible name', () => {
       // The carets are icon-only, so sighted users need a visible label on
       // hover, not just the accessible name. The tooltip reuses the same
@@ -291,6 +314,225 @@ describe('Pagination', () => {
       );
       expect(screen.getByText('Page 3 of 10')).toBeInTheDocument();
     });
+
+    describe('first/last buttons', () => {
+      function navButtonNames(): string[] {
+        return within(screen.getByRole('navigation'))
+          .getAllByRole('button')
+          .map(button => button.getAttribute('aria-label') ?? '');
+      }
+
+      it('omits first/last when hasFirstLast is unset', () => {
+        render(
+          <Pagination
+            page={5}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to previous page',
+          'Go to next page',
+        ]);
+      });
+
+      it('omits first/last when hasFirstLast is false', () => {
+        render(
+          <Pagination
+            page={5}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast={false}
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to previous page',
+          'Go to next page',
+        ]);
+      });
+
+      it('flanks prev/next with first/last when hasFirstLast is true', () => {
+        render(
+          <Pagination
+            page={5}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to first page',
+          'Go to previous page',
+          'Go to next page',
+          'Go to last page',
+        ]);
+        // The readout stays between prev and next.
+        const readout = within(screen.getByRole('navigation')).getByText(
+          'Page 5 of 10',
+        );
+        const prev = screen.getByRole('button', {name: 'Go to previous page'});
+        const next = screen.getByRole('button', {name: 'Go to next page'});
+        expect(
+          prev.compareDocumentPosition(readout) &
+            Node.DOCUMENT_POSITION_FOLLOWING,
+        ).toBeTruthy();
+        expect(
+          next.compareDocumentPosition(readout) &
+            Node.DOCUMENT_POSITION_PRECEDING,
+        ).toBeTruthy();
+        // Compact never gains an editable box.
+        expect(screen.queryByRole('spinbutton')).not.toBeInTheDocument();
+      });
+
+      it('jumps to the first and last page through onChange and changeAction', async () => {
+        const user = userEvent.setup();
+        const onChange = vi.fn();
+        const changeAction = vi.fn();
+        render(
+          <Pagination
+            page={5}
+            onChange={onChange}
+            changeAction={changeAction}
+            totalItems={95}
+            pageSize={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        await user.click(
+          screen.getByRole('button', {name: 'Go to first page'}),
+        );
+        expect(onChange).toHaveBeenLastCalledWith(1);
+        expect(changeAction).toHaveBeenLastCalledWith(1);
+        await waitFor(() => {
+          expect(politeRegion()).toHaveTextContent('Page 1 of 10');
+        });
+
+        await user.click(screen.getByRole('button', {name: 'Go to last page'}));
+        // 95 items at 10 per page is 10 pages.
+        expect(onChange).toHaveBeenLastCalledWith(10);
+        expect(changeAction).toHaveBeenLastCalledWith(10);
+        await waitFor(() => {
+          expect(politeRegion()).toHaveTextContent('Page 10 of 10');
+        });
+      });
+
+      it('disables first on the first page and last on the last page', () => {
+        const {rerender} = render(
+          <Pagination
+            page={1}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(
+          screen.getByRole('button', {name: 'Go to first page'}),
+        ).toBeDisabled();
+        expect(
+          screen.getByRole('button', {name: 'Go to last page'}),
+        ).not.toBeDisabled();
+
+        rerender(
+          <Pagination
+            page={10}
+            onChange={() => {}}
+            totalPages={10}
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(
+          screen.getByRole('button', {name: 'Go to first page'}),
+        ).not.toBeDisabled();
+        expect(
+          screen.getByRole('button', {name: 'Go to last page'}),
+        ).toBeDisabled();
+      });
+
+      it('omits first/last when the total page count is unknown', async () => {
+        const user = userEvent.setup();
+        const onChange = vi.fn();
+        render(
+          <Pagination
+            page={2}
+            onChange={onChange}
+            hasMore
+            variant="compact"
+            hasFirstLast
+          />,
+        );
+        expect(navButtonNames()).toEqual([
+          'Go to previous page',
+          'Go to next page',
+        ]);
+        await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+        expect(onChange).toHaveBeenLastCalledWith(3);
+      });
+
+      it('mirrors the first/last chevrons under RTL like prev/next', () => {
+        render(
+          <InternationalizationProvider locale="en" dir="rtl">
+            <div dir="rtl">
+              <Pagination
+                page={5}
+                onChange={() => {}}
+                totalPages={10}
+                variant="compact"
+                hasFirstLast
+              />
+            </div>
+          </InternationalizationProvider>,
+        );
+        // jsdom applies no CSS transforms, so assert the first/last icons carry
+        // every class the mirrored prev/next icons share (the mirror included).
+        const iconClasses = (name: string) =>
+          new Set(
+            screen
+              .getByRole('button', {name})
+              .querySelector('.astryx-icon')
+              ?.getAttribute('class')
+              ?.split(/\s+/) ?? [],
+          );
+        const prev = iconClasses('Go to previous page');
+        const shared = [...iconClasses('Go to next page')].filter(name =>
+          prev.has(name),
+        );
+        expect(shared.length).toBeGreaterThan(0);
+        for (const name of ['Go to first page', 'Go to last page']) {
+          const classes = iconClasses(name);
+          expect(shared.filter(c => !classes.has(c))).toEqual([]);
+        }
+      });
+    });
+  });
+
+  describe('hasFirstLast on other variants', () => {
+    it.each(['pages', 'count', 'dots', 'none'] as const)(
+      'does not add first/last to the %s variant',
+      variant => {
+        render(
+          <Pagination
+            page={3}
+            onChange={() => {}}
+            totalItems={50}
+            pageSize={10}
+            variant={variant}
+            hasFirstLast
+          />,
+        );
+        expect(
+          screen.queryByRole('button', {name: 'Go to first page'}),
+        ).not.toBeInTheDocument();
+        expect(
+          screen.queryByRole('button', {name: 'Go to last page'}),
+        ).not.toBeInTheDocument();
+      },
+    );
   });
 
   // ---------------------------------------------------------------------------