@astryxdesign/core 0.7.1 → 0.7.2-canary.374b53a

package/src/Button/__tests__/Button.a11y.known-failures.ts

@@ -22,65 +22,4 @@
 
 import type {KnownFailure} from '@astryxdesign/a11y-spec';
 
-export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
-  // ---- Button and IconButton go natively disabled while busy --------------
-  // One defect, one record per component.
-  // They are written out rather than generated, because a record has to name
-  // exactly one thing that is broken — a loop would make it easy to widen this
-  // later without anyone noticing.
-  {
-    expectation: 'button.focus.reachable-and-escapable',
-    binding: 'Button',
-    state: 'button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      '10 presses of Tab from the start of the document never reached the button, so a keyboard user cannot get to this action',
-    standardsReference:
-      'WCAG 2.2 2.1.1 Keyboard and 2.1.2 No Keyboard Trap (Level A)',
-    userImpact:
-      'A keyboard user who activates Save and waits is dropped to the top of the document the moment the action starts, and the button leaves the tab sequence entirely — so they cannot get back to it, to see that it is busy or to interrupt it. The next Tab restarts from the beginning of the page.',
-    reason:
-      'Button sets the native disabled attribute while a clickAction is pending. A natively disabled element is neither focusable nor a tab stop. Separate implementation work will turn this record into an unexpected pass.',
-  },
-  {
-    expectation: 'button.focus.reachable-and-escapable',
-    binding: 'IconButton',
-    state: 'icon-button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      '10 presses of Tab from the start of the document never reached the button, so a keyboard user cannot get to this action',
-    standardsReference:
-      'WCAG 2.2 2.1.1 Keyboard and 2.1.2 No Keyboard Trap (Level A)',
-    userImpact:
-      'The same drop from an icon button, where it is worse: an icon button is usually one of several in a row, so the user loses their place among them.',
-    reason:
-      'IconButton is a thin wrapper over Button and inherits the behaviour exactly.',
-  },
-
-  {
-    expectation: 'button.unavailable.inert',
-    binding: 'Button',
-    state: 'button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'this state is declared focusable so its reason stays reachable, but it cannot take focus — so a keyboard user can neither read why it is unavailable nor reach it to confirm it refuses to act',
-    standardsReference:
-      'Current Astryx family:buttons FR3 and WAI-ARIA APG Button unavailable-state requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact:
-      'The third face of the same defect: because the busy button cannot take focus, there is no way to confirm from the keyboard that it declines a second press — the user can neither reach it nor see why it is unavailable.',
-    reason:
-      'Same native disabled attribute. Recorded separately because a record names exactly one outcome, and a fix that restored focus without keeping the button inert would satisfy one of these and not the other.',
-  },
-  {
-    expectation: 'button.unavailable.inert',
-    binding: 'IconButton',
-    state: 'icon-button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'this state is declared focusable so its reason stays reachable, but it cannot take focus — so a keyboard user can neither read why it is unavailable nor reach it to confirm it refuses to act',
-    standardsReference:
-      'Current Astryx family:buttons FR3 and WAI-ARIA APG Button unavailable-state requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact: 'The same, from an icon button.',
-    reason: 'Inherited from Button, as above.',
-  },
-];
+export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

package/src/Button/__tests__/Button.a11y.states.ts

@@ -177,16 +177,9 @@ export const BUTTON_BINDING_STATES = [
     binding: 'Button',
     summary:
       'a button waiting on the action it started: the action is unavailable, and it is meant to stay focusable so the user can see that and interrupt it',
-    // `focusable: true` is the declaration, and the component does not deliver
-    // it — see the known-failure records. Declaring what the component does
-    // instead would make the expectations that catch it not-applicable, which
-    // is how a contract quietly stops noticing a defect.
     facts: facts({operable: false, unavailable: true}),
     visibleLabel: null,
     storyId: 'a11y-button-pattern--button-loading',
-    declaredNotDelivered: [
-      {fact: 'focusable', owned: 'button.focus.reachable-and-escapable'},
-    ],
   },
 
   // ---- IconButton ---------------------------------------------------------
@@ -214,9 +207,6 @@ export const BUTTON_BINDING_STATES = [
     facts: facts({operable: false, unavailable: true}),
     visibleLabel: null,
     storyId: 'a11y-button-pattern--icon-button-loading',
-    declaredNotDelivered: [
-      {fact: 'focusable', owned: 'button.focus.reachable-and-escapable'},
-    ],
   },
 
   // ---- ClickableCard ------------------------------------------------------

package/src/HoverCard/HoverCard.test.tsx

@@ -109,6 +109,64 @@ describe('useHoverCard identity', () => {
   });
 });
 
+// A card closed while the pointer rests on it unmounts without a mouseleave,
+// so the hook must not keep believing the pointer is over the card: if it
+// does, the next open of the same trigger never closes on leave.
+describe('useHoverCard closing while the pointer is on the card', () => {
+  function Harness() {
+    const card = useHoverCard({delay: 0, hideDelay: 0});
+    return (
+      <div>
+        <span ref={card.ref}>Trigger</span>
+        <output data-testid="state">{card.isOpen ? 'open' : 'closed'}</output>
+        {card.renderHoverCard(
+          <button type="button" onClick={card.hide}>
+            Pick
+          </button>,
+        )}
+      </div>
+    );
+  }
+
+  async function openThenRestOnCard() {
+    const state = screen.getByTestId('state');
+    fireEvent.mouseEnter(screen.getByText('Trigger'));
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    const pick = screen.getByRole('button', {name: 'Pick', hidden: true});
+    fireEvent.mouseLeave(screen.getByText('Trigger'));
+    fireEvent.mouseEnter(pick.parentElement!);
+    return {state, pick};
+  }
+
+  async function expectNextOpenClosesOnLeave(state: HTMLElement) {
+    const trigger = screen.getByText('Trigger');
+    fireEvent.mouseEnter(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    fireEvent.mouseLeave(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+  }
+
+  it('closes the next open on leave after hide() from inside the card', async () => {
+    render(<Harness />);
+    const {state, pick} = await openThenRestOnCard();
+
+    fireEvent.click(pick);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+
+  it('closes the next open on leave after Escape dismisses the card', async () => {
+    render(<Harness />);
+    const {state} = await openThenRestOnCard();
+
+    fireEvent.keyDown(document.body, {key: 'Escape'});
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+});
+
 describe('HoverCard', () => {
   it('renders trigger element', () => {
     render(

package/src/HoverCard/useHoverCard.tsx

@@ -345,6 +345,14 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     hideLayer();
   }, [clearTimeouts, hideLayer]);
 
+  // The imperative hide. A card closed while the pointer rests on it unmounts
+  // without a mouseleave, so the content-hover latch is cleared here; left set,
+  // it would keep the trigger's next hover-open from closing on leave.
+  const hide = useCallback(() => {
+    isHoveringContentRef.current = false;
+    hideLayer();
+  }, [hideLayer]);
+
   const {
     isTouchPointerRef,
     isTouchInteraction,
@@ -508,7 +516,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           ? null
           : document.getElementById(layerId);
       const hadFocus = card?.contains(document.activeElement) ?? false;
-      hideLayer();
+      hide();
       if (hadFocus) {
         isEscapeDismissingRef.current = true;
         triggerRef.current?.focus();
@@ -720,6 +728,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     isOpen: isLayerOpen,
     renderHoverCard,
     show: showLayer,
-    hide: hideLayer,
+    hide,
   };
 }

package/src/IconButton/IconButton.doc.mjs

@@ -46,7 +46,7 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and disables interaction.',
+      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
       default: 'false',
     },
     {
@@ -141,7 +141,7 @@ export const docsDense = {
     variant: 'visual style variant',
     size: 'size variant',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
-    isLoading: 'shows loading spinner + disables interaction',
+    isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
     isDisabled: 'disables button',
     tooltip: 'tooltip text shown on hover',
     onClick: 'standard click handler',

package/src/IconButton/IconButton.test.tsx

@@ -124,7 +124,9 @@ describe('IconButton', () => {
   it('shows loading state', () => {
     render(<IconButton label="Save" icon={<span>💾</span>} isLoading />);
     const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('forwards ref correctly', () => {

package/src/List/ListItem.doc.mjs

@@ -12,8 +12,9 @@ export const docs = {
   props: [
     {
       name: 'label',
-      type: 'string',
-      description: 'Primary text.',
+      type: 'ReactNode',
+      description:
+        'Primary content. A plain string gets single-line truncation automatically; a ReactNode renders as given, so child components control their own text behavior.',
       required: true,
     },
     {
@@ -123,8 +124,9 @@ export const docsZh = {
   props: [
     {
       name: 'label',
-      type: 'string',
-      description: '主要文本。',
+      type: 'ReactNode',
+      description:
+        '主要内容。纯字符串会自动应用单行截断；ReactNode 按原样渲染，由子组件自行控制文本行为。',
       required: true,
     },
     {
@@ -205,7 +207,8 @@ export const docsDense = {
   description:
     'List item w/ label, description, start/end content slots, interactive patterns.',
   propDescriptions: {
-    label: 'Primary text.',
+    label:
+      'Primary content. String auto-truncates; ReactNode renders as given.',
     description: 'Secondary text below label.',
     startContent: 'Content before label area (e.g. icon, avatar).',
     endContent: 'Content after label area (e.g. badge, chevron).',

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

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.