@astryxdesign/core 0.7.1 → 0.7.2-canary.c68f5e8

package/src/Button/Button.test.tsx

@@ -11,7 +11,13 @@
 
 import {readFileSync} from 'node:fs';
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  createEvent,
+  act,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
 import * as stylex from '@stylexjs/stylex';
@@ -127,8 +133,9 @@ describe('Button', () => {
   it('shows isLoading state with spinner', () => {
     render(<Button label="Submit" isLoading />);
     const button = screen.getByRole('button');
-    // Button should be disabled when loading
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     expect(button.className).toContain('styles.inactive');
     expect(button.className).not.toContain('styles.disabled');
   });
@@ -143,7 +150,7 @@ describe('Button', () => {
 
   it('sets aria-busy synchronously while clickAction is pending', async () => {
     // The spinner reveal is visually delayed (CSS animation-delay), but the
-    // loading DOM state — aria-busy and disabled — must not be delayed.
+    // loading DOM state — aria-busy and aria-disabled — must not be delayed.
     const user = userEvent.setup();
     let resolveAction: (() => void) | undefined;
     const clickAction = vi.fn(
@@ -157,7 +164,9 @@ describe('Button', () => {
 
     await user.click(button);
     expect(button).toHaveAttribute('aria-busy', 'true');
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
 
     await act(async () => {
       resolveAction?.();
@@ -165,6 +174,7 @@ describe('Button', () => {
     });
     expect(button).not.toHaveAttribute('aria-busy', 'true');
     expect(button).not.toBeDisabled();
+    expect(button).not.toHaveAttribute('aria-disabled');
   });
 
   it('renders the loading spinner with the inherit shade for every variant (#2717)', () => {
@@ -310,9 +320,10 @@ describe('Button', () => {
     );
     // endContent should still be in the DOM
     expect(screen.getByTestId('end')).toBeInTheDocument();
-    // Button should be disabled and have aria-busy
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
     const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
     expect(button).toHaveAttribute('aria-busy', 'true');
   });
 
@@ -516,6 +527,111 @@ describe('Button', () => {
     expect(handleKeyDown).toHaveBeenCalledTimes(1);
   });
 
+  it('uses aria-disabled instead of disabled while isLoading, so the button stays focusable (#4871)', () => {
+    render(<Button label="Save" isLoading />);
+    const button = screen.getByRole('button');
+    // Native disabled would move focus to <body> the moment the action
+    // starts, losing the keyboard user's place — busy must stay
+    // aria-disabled + focusable per the "Disabled vs Busy" convention.
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    button.focus();
+    expect(button).toHaveFocus();
+  });
+
+  it('does not fire onClick while aria-disabled via isLoading', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(<Button label="Save" isLoading onClick={handleClick} />);
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('does not let a click on a busy button reach a wrapping ancestor handler', async () => {
+    // A native `disabled` element never dispatches a click, so it never
+    // reaches an ancestor either. aria-disabled (busy-only) is a real,
+    // interactive element that still dispatches one — preventDefault alone
+    // only cancels the button's own default action, not propagation, so
+    // an unrelated wrapper (a clickable row/card/backdrop) would otherwise
+    // still fire.
+    const user = userEvent.setup();
+    const ancestorClick = vi.fn();
+    render(
+      <div onClick={ancestorClick}>
+        <Button label="Save" isLoading />
+      </div>,
+    );
+    await user.click(screen.getByRole('button'));
+    expect(ancestorClick).not.toHaveBeenCalled();
+  });
+
+  it('does not let a click on a busy-only anchor Button reach a wrapping ancestor handler', async () => {
+    const user = userEvent.setup();
+    const ancestorClick = vi.fn();
+    render(
+      <div onClick={ancestorClick}>
+        <Button label="Docs" href="https://example.com" isLoading />
+      </div>,
+    );
+    await user.click(screen.getByRole('link'));
+    expect(ancestorClick).not.toHaveBeenCalled();
+  });
+
+  it('suppresses activation keys but passes other keys while aria-disabled via isLoading', async () => {
+    const user = userEvent.setup();
+    const handleKeyDown = vi.fn();
+    render(<Button label="Save" isLoading onKeyDown={handleKeyDown} />);
+    const button = screen.getByRole('button');
+    button.focus();
+    await user.keyboard('{Enter}');
+    expect(handleKeyDown).not.toHaveBeenCalled();
+
+    await user.keyboard('{Escape}');
+    expect(handleKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('suppresses activation keys but passes other keys on a busy-only anchor Button', async () => {
+    // The button-rendered path suppresses Enter/Space while aria-disabled;
+    // the anchor-rendered path (href set, busy-only) shares the same
+    // handleKeyDown but only wires onClick, so a consumer onKeyDown still
+    // received Enter/Space on a busy link.
+    const user = userEvent.setup();
+    const handleKeyDown = vi.fn();
+    render(
+      <Button
+        label="Docs"
+        href="https://example.com"
+        isLoading
+        onKeyDown={handleKeyDown}
+      />,
+    );
+    const link = screen.getByRole('link');
+    link.focus();
+    await user.keyboard('{Enter}');
+    expect(handleKeyDown).not.toHaveBeenCalled();
+
+    await user.keyboard('{Escape}');
+    expect(handleKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps native disabled (not aria-disabled) when isDisabled and not busy, even without a tooltip', () => {
+    render(<Button label="Save" isDisabled />);
+    const button = screen.getByRole('button');
+    expect(button).toHaveAttribute('disabled');
+    expect(button).not.toHaveAttribute('aria-disabled');
+  });
+
+  it('keeps native disabled when isDisabled and isLoading are both true (isDisabled wins)', () => {
+    render(<Button label="Save" isDisabled isLoading />);
+    const button = screen.getByRole('button');
+    // "isDisabled behavior unchanged: that stays native disabled" — busy-only
+    // aria-disabled is only for the case where busy is the SOLE reason the
+    // button can't be clicked, not when it's also genuinely isDisabled.
+    expect(button).toHaveAttribute('disabled');
+    expect(button).not.toHaveAttribute('aria-disabled');
+  });
+
   it('has a live region that announces loading state', () => {
     const {rerender} = render(<Button label="Submit" />);
     const button = screen.getByRole('button');
@@ -663,8 +779,6 @@ describe('Button', () => {
   });
 
   it('exposes aria-busy on the link-rendered button while loading', () => {
-    // Non-interruptible loading disables the button, which falls back to
-    // <button> rendering — so an anchor only shows loading when interruptible.
     render(
       <Button
         label="Docs"
@@ -682,6 +796,38 @@ describe('Button', () => {
     const link = screen.getByRole('link');
     expect(link).not.toHaveAttribute('aria-busy');
   });
+
+  it('stays an anchor while busy-only, not a disabled <button> fallback (#4871)', () => {
+    // Non-interruptible busy is exactly the isBusyOnlyDisabled case: not
+    // isDisabled, blocked only because a fire-once action is in flight.
+    // Swapping the element to <button disabled> here would drop focus the
+    // same way the native disabled attribute did (credit @AKnassa, #4879).
+    render(<Button label="Docs" href="https://example.com" isLoading />);
+    const link = screen.getByRole('link', {name: 'Docs'});
+    expect(link.tagName).toBe('A');
+    expect(link).toHaveAttribute('href', 'https://example.com');
+    expect(link).toHaveAttribute('aria-busy', 'true');
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).not.toHaveAttribute('disabled');
+  });
+
+  it('keeps a busy-only anchor focusable and guards its navigation', () => {
+    render(<Button label="Docs" href="https://example.com" isLoading />);
+    const link = screen.getByRole('link', {name: 'Docs'});
+    link.focus();
+    expect(link).toHaveFocus();
+
+    const event = createEvent.click(link);
+    fireEvent(link, event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('falls back to <button disabled> for a truly disabled href Button', () => {
+    render(<Button label="Docs" href="https://example.com" isDisabled />);
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    const button = screen.getByRole('button', {name: 'Docs'});
+    expect(button).toBeDisabled();
+  });
 });
 
 describe('Button pressed state (touch)', () => {

package/src/Button/Button.tsx

@@ -594,26 +594,37 @@ export function Button({
   // the consumer is deliberately showing it.
   const delaySpinner = isPending || isInterruptible;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
-  // When interruptible, the loading state drives the spinner and aria-busy but
-  // not disabled, so clicks keep landing and can interrupt the in-flight action.
-  const buttonDisabled =
-    isDisabled || groupDisabled || (isLoadingState && !isInterruptible);
-  // A loading button remains non-interactive, but its spinner communicates an
-  // active state and must retain contrast. Only explicitly disabled controls
-  // receive the visually dimmed treatment.
-  const visuallyDisabled = isDisabled || groupDisabled;
+  const isTrueDisabled = isDisabled || groupDisabled;
+  // Busy-only: the button can't fire again purely because an action is in
+  // flight, not because it's genuinely isDisabled/group-disabled. Per the API
+  // Conventions "Disabled vs Busy" rule, busy is visual-only (aria-busy +
+  // spinner) and must never take focusability away — the click-handler ref
+  // guard (actionInFlightRef) is what actually makes a fire-once action fire
+  // once, so the native disabled attribute adds nothing but a focus loss
+  // here. When interruptible, the loading state drives the spinner and
+  // aria-busy but not disabled at all, so clicks keep landing and can
+  // interrupt the in-flight action.
+  const isBusyOnlyDisabled =
+    !isTrueDisabled && isLoadingState && !isInterruptible;
+  const buttonDisabled = isTrueDisabled || isBusyOnlyDisabled;
   // isIconOnly prop is the source of truth for icon-only rendering.
   // When false (default), label is always rendered as visible text.
 
   const LinkComponent = useLinkComponent(as);
 
-  // Render as link when href is provided and button is not disabled.
-  // Disabled links are an accessibility anti-pattern — fall back to <button>.
-  const renderAsLink = href != null && !buttonDisabled;
+  // Render as link when href is provided and the button is not TRULY
+  // disabled. Disabled links are an accessibility anti-pattern, so a
+  // genuinely isDisabled/group-disabled button falls back to <button>.
+  // Busy-only does NOT fall back: swapping <a> for a disabled <button>
+  // mid-action would drop focus the same way the native attribute does
+  // (credit @AKnassa, #4879), which is exactly the bug this PR fixes.
+  const renderAsLink = href != null && !isTrueDisabled;
 
-  // Use aria-disabled when tooltip is present so the button remains focusable
-  // for keyboard users to reach the tooltip. Otherwise use native disabled.
-  const useAriaDisabled = tooltip != null && buttonDisabled;
+  // Use aria-disabled (button stays focusable) when busy-only, or when a
+  // tooltip is present so keyboard users can still reach it. A genuinely
+  // isDisabled/group-disabled button (not busy) keeps native disabled.
+  const useAriaDisabled =
+    buttonDisabled && (isBusyOnlyDisabled || tooltip != null);
 
   // Attach tooltip behavior via the hook rather than wrapping the button in a
   // <Tooltip> element. The hook adds hover/focus triggers to the button itself,
@@ -630,6 +641,16 @@ export function Button({
     // a re-click while pending starts a fresh action that interrupts the prior.
     if (buttonDisabled || (actionInFlightRef.current && !isInterruptible)) {
       e.preventDefault();
+      // A native `disabled` element never dispatches a click at all, so it
+      // never reaches a wrapping element's own handler either. An
+      // aria-disabled button (busy-only, or with a tooltip) is still a real,
+      // interactive element the DOM keeps dispatching clicks on —
+      // preventDefault alone only cancels the button's OWN default action
+      // (form submit, link navigation), not propagation. Without this, an
+      // unavailable Button inside a clickable row/card/backdrop still
+      // triggers that ancestor's action, which the previously native-disabled
+      // control never did.
+      e.stopPropagation();
       return;
     }
     props.onClick?.(e);
@@ -669,7 +690,7 @@ export function Button({
     isIconOnly && styles.iconOnly,
     interactionOverlayStyles.backgroundImage,
     buttonDisabled && styles.inactive,
-    visuallyDisabled && styles.disabled,
+    isTrueDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
     renderAsLink && styles.link,
     !buttonGroup && styles.pressable,
@@ -797,7 +818,9 @@ export function Button({
         {...describedByProp}
         {...edgeCompAttr}
         aria-busy={isLoadingState || undefined}
-        onClick={handleClick}>
+        aria-disabled={useAriaDisabled || undefined}
+        onClick={handleClick}
+        {...(handleKeyDown ? {onKeyDown: handleKeyDown} : null)}>
         {buttonContent}
       </LinkComponent>
     );

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/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/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.