@astryxdesign/core 0.7.4 → 0.7.5-canary.07605c2

package/src/Icon/Icon.spec.md

@@ -27,7 +27,7 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-087]
 ---
 
 # Icon component contract
@@ -53,6 +53,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Owns**
 
 - Accepting a semantic icon key or a supplied icon component as the glyph source.
+- Passing the resolved size and a variant the entry can receive to a registry entry.
 - Resolving explicit, component-owned contextual, and standalone size defaults.
 - Applying Icon's size, color, theming target, and accessibility semantics to
   the rendered glyph.
@@ -71,12 +72,13 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept       | Closed values or states                                   | Meaning                                                   | Availability by variant/orientation/state | Default                                         | Owner            | Stability | Invalid-value behavior                                 |
-| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------- | --------- | ------------------------------------------------------ |
-| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                | Every render                              | Required                                        | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values. |
-| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                | Every rendered glyph                      | nearest component-owned default; otherwise `md` | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.      | Every rendered glyph                      | `inherit`                                       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
-| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph. | Every rendered glyph                      | Decorative                                      | `component:Icon` | Stable    | Empty labels use the decorative behavior.              |
+| Concept       | Closed values or states                                   | Meaning                                                    | Availability by variant/orientation/state        | Default                                         | Owner            | Stability | Invalid-value behavior                                                            |
+| ------------- | --------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------- | --------- | --------------------------------------------------------------------------------- |
+| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                 | Every render                                     | Required                                        | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values.                            |
+| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                 | Every rendered glyph                             | nearest component-owned default; otherwise `md` | `component:Icon` | Stable    | TypeScript rejects unsupported values.                                            |
+| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.       | Every rendered glyph                             | `inherit`                                       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                                            |
+| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph.  | Every rendered glyph                             | Decorative                                      | `component:Icon` | Stable    | Empty labels use the decorative behavior.                                         |
+| Variant       | names in `IconVariantMap`; the active theme lists its own | Requests a theme's alternate artwork for a registry glyph. | Registry glyphs only; never a supplied component | None                                            | `component:Icon` | Stable    | TypeScript rejects unknown names; an unlisted variant renders the normal artwork. |
 
 A namespaced key that does not resolve currently renders nothing. This is
 existing behavior, not an intentional fallback promise.
@@ -86,13 +88,15 @@ existing behavior, not an intentional fallback promise.
 Requirements identify their basis so observed code is not mistaken for an
 intentional decision.
 
-| ID  | Candidate invariant                                                                                                                                                                               | Basis                                                 | Draft review state                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
-| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                            | Documented promise and current tests.                 | Settled intent.                                         |
-| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data.                                                                     | Current source, docs, and theming tests.              | Settled intent.                                         |
-| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests.            | Settled intent.                                         |
-| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                               | Current source and regression tests.                  | Current compatibility behavior; verify before changing. |
-| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`. | Component-size precedence and Button sizing decision. | Settled intent.                                         |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                           | Basis                                                 | Draft review state                                      |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
+| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                                                                                                                                                                                                                                                                        | Documented promise and current tests.                 | Settled intent.                                         |
+| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data.                                                                                                                                                                                                                                                                                                                 | Current source, docs, and theming tests.              | Settled intent.                                         |
+| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type.                                                                                                                                                                                                                                             | Human decision, current source, and tests.            | Settled intent.                                         |
+| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                                                                                                                                                                                                                                                                           | Current source and regression tests.                  | Current compatibility behavior; verify before changing. |
+| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`.                                                                                                                                                                                                                                             | Component-size precedence and Button sizing decision. | Settled intent.                                         |
+| FR6 | In registry mode, Icon MUST pass `{size, variant}` to the selected entry, where `size` is the size resolved by ORD1 and `variant` is the requested variant when the active theme lists it and, for a theme-supplied entry, the theme that defined the entry lists it too, otherwise `undefined`. A supplied icon component MUST NOT receive `variant`, Icon MUST NOT forward `variant` to the DOM, and the `icon` target MUST NOT reflect it. | `spec:AST-087` FR1–FR5 and FR9.                       | Settled intent.                                         |
+| FR7 | The `icon` target MUST guarantee `width` and `height` on its `size:*` selectors as reviewed target-specific additions, so a theme sets each size's dimension. Without theme styles, sizes are 12, 16, 20, and 24px at a 16px root and scale with the root font size.                                                                                                                                                                          | `spec:AST-087` FR10.                                  | Settled intent.                                         |
 
 ### Allowed variation
 
@@ -109,15 +113,18 @@ intentional decision.
 
 ### Representative states
 
-| State                            | Required invariant                                       | Allowed variation                              |
-| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
-| Semantic key                     | One resolved glyph carries the `icon` target.            | Theme, registry, or built-in artwork.          |
-| Namespaced extension key         | A resolved extension glyph carries the `icon` target.    | Consumer- or library-owned artwork.            |
-| Supplied icon component          | The supplied glyph carries the `icon` target.            | Component implementation and SVG internals.    |
-| Standalone Icon without `size`   | The resolved size is `md`.                               | Glyph source and color.                        |
-| Owned icon slot without `size`   | The nearest documented component default is used.        | The owning component's declared size mapping.  |
-| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default. | Any supported Icon size.                       |
-| Unresolved namespaced key        | No glyph is currently rendered.                          | No fallback behavior is established by intent. |
+| State                            | Required invariant                                                                 | Allowed variation                              |
+| -------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------- |
+| Semantic key                     | One resolved glyph carries the `icon` target.                                      | Theme, registry, or built-in artwork.          |
+| Namespaced extension key         | A resolved extension glyph carries the `icon` target.                              | Consumer- or library-owned artwork.            |
+| Supplied icon component          | The supplied glyph carries the `icon` target.                                      | Component implementation and SVG internals.    |
+| Standalone Icon without `size`   | The resolved size is `md`.                                                         | Glyph source and color.                        |
+| Owned icon slot without `size`   | The nearest documented component default is used.                                  | The owning component's declared size mapping.  |
+| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default.                           | Any supported Icon size.                       |
+| Unresolved namespaced key        | No glyph is currently rendered.                                                    | No fallback behavior is established by intent. |
+| Listed variant                   | The entry receives the size and the variant when its defining theme also lists it. | The theme's artwork for that request.          |
+| Unlisted or omitted variant      | The entry receives `variant: undefined`.                                           | The theme's normal artwork.                    |
+| Variant on a supplied component  | The component renders as given without `variant`.                                  | Component implementation.                      |
 
 ### Transformation and precedence order
 
@@ -172,6 +179,8 @@ not promise a `span`, `svg`, or other element type.
   rules for the `icon` target.
 - `architecture:icon-resolution-and-component-slots` owns semantic-key and
   component-slot resolution before Icon renders the selected source.
+- `spec:AST-087` decides the `variant` request, theme-listed variant names, and
+  theme-set size dimensions.
 - `architecture:public-component-api` owns admission and compatibility rules for
   Icon's public props and observable defaults.
 - The owning component or family specifies each contextual Icon-size mapping.
@@ -181,12 +190,14 @@ not promise a `span`, `svg`, or other element type.
 
 ## Verification map
 
-| Contract            | Verification                                                                   | Representative states                                           | Mutation or failure expectation                                                                                                             | Audit section              |
-| ------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR3, FR5       | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions.             | `audit:Icon/behavior`      |
-| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection                   | Both source modes; size and color variants                      | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions. | `audit:Icon/theming`       |
-| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                                         | Decorative, labelled, explicit ARIA override                    | Changing default or labelled semantics fails accessibility assertions.                                                                      | `audit:Icon/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                  | Canonical consumer anatomy and current target                   | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                     | `audit:Icon/theming`       |
+| Contract            | Verification                                                                   | Representative states                                                                                            | Mutation or failure expectation                                                                                                               | Audit section              |
+| ------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3, FR5       | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes                                                  | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions.               | `audit:Icon/behavior`      |
+| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection                   | Both source modes; size and color variants                                                                       | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions.   | `audit:Icon/theming`       |
+| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                                         | Decorative, labelled, explicit ARIA override                                                                     | Changing default or labelled semantics fails accessibility assertions.                                                                        | `audit:Icon/accessibility` |
+| FR6                 | `Icon.test.tsx` variant suites (pending)                                       | listed, unlisted, and omitted variant; no active list; inherited entry under a replaced list; supplied component | An unlisted variant, or one the entry's defining theme does not list, reaches an entry, or `variant` reaches a supplied component or the DOM. | `audit:Icon/behavior`      |
+| FR7                 | Theme styling tests for each size (pending)                                    | each size with and without theme styles                                                                          | A themed size does not change the glyph dimension, or an unstyled size changes.                                                               | `audit:Icon/theming`       |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                  | Canonical consumer anatomy and current target                                                                    | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                       | `audit:Icon/theming`       |
 
 Focused coverage for `data-color` on both glyph source modes is a checkable test
 gap; source inspection is the current evidence for that part of FR2.

package/src/Layer/modalOutlet.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file modalOutlet.ts
- * @input The open Dialog `<dialog>` elements
+ * @input The open Dialog and scrim BottomSheet `<dialog>` elements
  * @output Exports useModalOutlet (a modal supplies its outlet),
  *   getActiveModalOutlet, and subscribeModalOutlets (a global host follows
  *   the latest one)

package/src/NumberInput/NumberInput.doc.mjs

@@ -81,7 +81,7 @@ export const docs = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. Stepping is off in every form while read-only: arrow keys, the wheel, and the number steppers. isDisabled takes precedence when both are set.',
+        'Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and keeps its form value. Stepping is off in every form while read-only: arrow keys, the wheel, and the number steppers. isDisabled takes precedence when both are set.',
       default: 'false',
     },
     {
@@ -308,7 +308,7 @@ export const docs = {
       {
         guidance: false,
         description:
-          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
     anatomy: [
@@ -401,7 +401,7 @@ export const docsZh = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        '将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留在 Tab 顺序中。只读时所有步进方式均被禁用：方向键、滚轮和步进按钮。同时设置时 isDisabled 优先。',
+        '将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留其表单值。只读时所有步进方式均被禁用：方向键、滚轮和步进按钮。同时设置时 isDisabled 优先。',
       default: 'false',
     },
     {
@@ -613,7 +613,7 @@ export const docsZh = {
       {
         guidance: false,
         description:
-          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
     anatomy: [
@@ -687,7 +687,7 @@ export const docsDense = {
       {
         guidance: false,
         description:
-          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Wrap a disabled NumberInput in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
     anatomy: [
@@ -737,7 +737,7 @@ export const docsDense = {
     isRequired: 'Field required (mutually exclusive w/ isOptional).',
     isDisabled: 'Input disabled.',
     isReadOnly:
-      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
+      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed.',
     disabledMessage:
       'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps input focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled NumberInput in Tooltip.',
     placeholder: 'Placeholder text.',

package/src/NumberInput/NumberInput.test.tsx

@@ -13,6 +13,8 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {act, useState} from 'react';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {InternationalizationProvider} from '../i18n';
 import {registerIcons, resetIcons} from '../Icon';
@@ -22,6 +24,21 @@ import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
+// jsdom cannot match `:focus-visible`: compare the ring's StyleX class hash.
+const RING = stylex
+  .props(
+    stylex.create({
+      ring: {
+        boxShadow: {
+          default: null,
+          ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+        },
+      },
+    }).ring,
+  )
+  .className!.split(' ')
+  .pop()!;
+
 // FieldStatus announces status messages through the persistent useAnnounce
 // singletons; remove them between tests so role/aria-live queries in this
 // file never match a leftover region.
@@ -149,7 +166,7 @@ describe('NumberInput', () => {
     expect(screen.getByRole('spinbutton')).not.toHaveAttribute('aria-required');
   });
 
-  it('sets disabled attribute when isDisabled is true', () => {
+  it('exposes aria-disabled, not native disabled, when isDisabled is true (spec:AST-085)', () => {
     render(
       <NumberInput
         label="Quantity"
@@ -158,7 +175,76 @@ describe('NumberInput', () => {
         onChange={() => {}}
       />,
     );
-    expect(screen.getByRole('spinbutton')).toBeDisabled();
+    expect(screen.getByRole('spinbutton')).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+  });
+
+  it('keeps a disabled input in the tab order and rings it (spec:AST-085 FR1, FR6)', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <NumberInput label="First" value={1} onChange={() => {}} />
+        <NumberInput label="Second" value={2} onChange={() => {}} isDisabled />
+      </>,
+    );
+    await user.tab();
+    await user.tab();
+    const input = screen.getByRole('spinbutton', {name: 'Second'});
+    expect(input).toHaveFocus();
+    expect(input.parentElement).toHaveClass(RING);
+  });
+
+  it('runs no caller handler, steps nothing and submits no form while disabled (spec:AST-085 FR2)', async () => {
+    const user = userEvent.setup();
+    const handlers = {
+      onChange: vi.fn(),
+      onEnter: vi.fn(),
+      onKeyDown: vi.fn(),
+      onPaste: vi.fn(),
+    };
+    const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
+    render(
+      <form onSubmit={onSubmit}>
+        <NumberInput
+          label="Quantity"
+          value={5}
+          isDisabled
+          hasNumberSteppers
+          {...handlers}
+        />
+      </form>,
+    );
+    await user.click(screen.getByRole('spinbutton'));
+    await user.keyboard('{ArrowUp}{ArrowDown}{Enter}');
+    await user.paste('9');
+    await user.click(screen.getByRole('button', {name: 'Increment Quantity'}));
+    for (const handler of [...Object.values(handlers), onSubmit]) {
+      expect(handler).not.toHaveBeenCalled();
+    }
+  });
+
+  it('commits nothing when a field disabled mid-entry loses focus (spec:AST-085 FR2)', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const field = (isDisabled: boolean) => (
+      <NumberInput
+        label="Quantity"
+        value={5}
+        onChange={onChange}
+        isDisabled={isDisabled}
+      />
+    );
+    const {rerender} = render(field(false));
+    const input = screen.getByRole('spinbutton');
+    await user.clear(input);
+    await user.type(input, '8');
+    onChange.mockClear();
+    rerender(field(true));
+    await user.tab();
+    expect(onChange).not.toHaveBeenCalled();
+    expect(input).toHaveValue('5');
   });
 
   it('does not fire onChange when disabled', async () => {
@@ -1424,10 +1510,10 @@ describe('NumberInput', () => {
       const increment = screen.getByRole('button', {
         name: 'Increment Quantity',
       });
-      expect(increment).toBeDisabled();
+      expect(increment).toHaveAttribute('aria-disabled', 'true');
       expect(
         screen.getByRole('button', {name: 'Decrement Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
 
       fireEvent.click(increment);
       expect(handleChange).not.toHaveBeenCalled();
@@ -1446,7 +1532,10 @@ describe('NumberInput', () => {
           />
         </form>,
       );
-      expect(screen.getByRole('spinbutton')).toBeDisabled();
+      expect(screen.getByRole('spinbutton')).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
       expect([
         ...new FormData(container.querySelector('form')!).keys(),
       ]).toEqual([]);
@@ -1693,7 +1782,7 @@ describe('NumberInput', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
+    it('stays focusable when disabled without a reason', () => {
       render(
         <NumberInput
           label="Quantity"
@@ -1703,8 +1792,8 @@ describe('NumberInput', () => {
         />,
       );
       const input = screen.getByRole('spinbutton');
-      expect(input).toBeDisabled();
-      expect(input).not.toHaveAttribute('aria-disabled');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
     });
   });
 });
@@ -2006,14 +2095,14 @@ describe('NumberInput stepping', () => {
 
     const input = screen.getByRole('spinbutton');
     const increment = screen.getByRole('button', {name: 'Increment Amount'});
-    expect(increment).toBeEnabled();
+    expect(increment).not.toHaveAttribute('aria-disabled');
 
     fireEvent.click(increment);
 
     expect(input).toHaveValue('99.99');
     expect(input).toHaveAttribute('aria-valuenow', '99.99');
     expect(input).not.toHaveAttribute('aria-invalid');
-    expect(increment).toBeDisabled();
+    expect(increment).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('allows wheel stepping by default and consumes the focused gesture', () => {
@@ -2259,10 +2348,33 @@ describe('NumberInput stepping', () => {
       );
       expect(
         screen.getByRole('button', {name: 'Increment Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
       expect(
         screen.getByRole('button', {name: 'Decrement Quantity'}),
-      ).not.toBeDisabled();
+      ).not.toHaveAttribute('aria-disabled');
+    });
+
+    it('commits nothing from a click on the stepper at the reached boundary (spec:AST-085 FR2)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={onChange}
+          min={0}
+          max={10}
+          hasNumberSteppers
+        />,
+      );
+      const input = screen.getByRole('spinbutton');
+      await user.clear(input);
+      await user.type(input, '10');
+      onChange.mockClear();
+      await user.click(
+        screen.getByRole('button', {name: 'Increment Quantity'}),
+      );
+      expect(onChange).not.toHaveBeenCalled();
     });
 
     it('disables both steppers with the input', () => {
@@ -2277,10 +2389,10 @@ describe('NumberInput stepping', () => {
       );
       expect(
         screen.getByRole('button', {name: 'Increment Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
       expect(
         screen.getByRole('button', {name: 'Decrement Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
     });
   });
 });

package/src/NumberInput/NumberInput.tsx

@@ -53,6 +53,7 @@ import {useTooltip} from '../Tooltip';
 import {getInputARIA} from '../utils';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
+import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
@@ -261,7 +262,7 @@ interface NumberInputPropsBase extends Omit<
    * Whether the input is read-only.
    * The value is shown at full opacity and still submits with the form, but
    * cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
-   * stays in the tab order — use it for a value the user should see and send
+   * keeps its form value — use it for a value the user should see and send
    * but not change. Stepping is off in every form while read-only: arrow keys,
    * the wheel, and the number steppers. `isDisabled` takes precedence when both
    * are set.
@@ -275,8 +276,8 @@ interface NumberInputPropsBase extends Omit<
    * keyboard and assistive technology. The field cannot be edited (it becomes
    * read-only) while disabled.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the reason
+   * is attached to the field itself.
    *
    * @example
    * ```
@@ -600,12 +601,20 @@ export function NumberInput({
   const [pendingInput, setPendingInput] = useState<string | null>(null);
   const [isFocused, setIsFocused] = useState(false);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input container (which already exists) and
+  // Disabled-reason tooltip. The tooltip listeners attach to the input container (which already exists) and
   // the input stays perceivable via aria-disabled instead of the native
   // disabled attribute. The field is made read-only so it can't be typed into,
   // and value mutation is blocked by the isDisabled guard in the handlers.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
+  // A disabled field keeps its tab stop but, like a natively disabled one,
+  // runs no caller event handler other than focus and blur (`spec:AST-085` FR2).
+  const fieldProps = isDisabled
+    ? Object.fromEntries(
+        Object.entries(rest).filter(
+          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
+        ),
+      )
+    : rest;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
     // The container div is not naturally focusable; focusin bubbles up from
@@ -699,6 +708,12 @@ export function NumberInput({
       if (pendingInput === null) {
         return;
       }
+      if (isDisabled) {
+        // A field disabled mid-entry commits nothing; its draft is dropped, as
+        // a natively disabled field's was (spec:AST-085 FR2).
+        setPendingInput(null);
+        return;
+      }
 
       const decision = resolveNumberInputCommit(pendingInput, {
         min,
@@ -722,7 +737,17 @@ export function NumberInput({
         onChange(decision.value);
       }
     },
-    [hasClear, isIntegerOnly, locale, max, min, onChange, pendingInput, value],
+    [
+      hasClear,
+      isDisabled,
+      isIntegerOnly,
+      locale,
+      max,
+      min,
+      onChange,
+      pendingInput,
+      value,
+    ],
   );
 
   // Blur ends the edit and displays the resulting committed value.
@@ -780,6 +805,13 @@ export function NumberInput({
   // Handle keyboard events
   const handleKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
+      if (isDisabled) {
+        // A read-only field still submits its form on Enter.
+        if (e.key === 'Enter') {
+          e.preventDefault();
+        }
+        return;
+      }
       // The field is type="text" for formatted display, so an IME can compose
       // into it: Enter commits the candidate and the arrows walk the candidate
       // window. The composing keydown fires before compositionend, so without
@@ -804,7 +836,7 @@ export function NumberInput({
       }
       onKeyDown?.(e);
     },
-    [commitPendingInput, onEnter, onKeyDown, stepValue],
+    [commitPendingInput, isDisabled, onEnter, onKeyDown, stepValue],
   );
 
   // React's delegated wheel listener can be passive, so use a native,
@@ -902,6 +934,7 @@ export function NumberInput({
           hasNumberSteppers && styles.wrapperWithNumberSteppers,
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
+          isDisabled && inputDisabledFocusStyles.ring,
           status && inputStatusBorderStyles[status.type],
           status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
@@ -914,7 +947,7 @@ export function NumberInput({
       {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
       {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
-        {...rest}
+        {...fieldProps}
         ref={mergedInputRef}
         id={id}
         name={isDisabled || formatValue ? undefined : htmlName}
@@ -928,12 +961,11 @@ export function NumberInput({
         onBlur={handleBlur}
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
-        // With a disabledMessage the input keeps focusability via aria-disabled
-        // so the reason is focus-discoverable; readOnly + the handler guards
-        // keep the value from changing.
-        disabled={isDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        readOnly={isReadOnly || showsDisabledMessage || undefined}
+        // A disabled input keeps its place in the tab order (spec:AST-085):
+        // aria-disabled instead of the native attribute, with readOnly + the
+        // handler guards keeping the value from changing.
+        aria-disabled={isDisabled ? 'true' : undefined}
+        readOnly={isReadOnly || isDisabled || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-valuemin={min ?? undefined}
@@ -992,10 +1024,17 @@ export function NumberInput({
             type="button"
             tabIndex={-1}
             {...pressable}
-            disabled={isDisabled || isReadOnly || !canIncrement}
+            aria-disabled={
+              isDisabled || isReadOnly || !canIncrement || undefined
+            }
             aria-label={t('@astryx.numberInput.incrementLabel', {label})}
             onPointerDown={event => event.preventDefault()}
             onClick={() => {
+              // An aria-disabled stepper does nothing, as a natively disabled
+              // one did (spec:AST-085 FR2).
+              if (isDisabled || isReadOnly || !canIncrement) {
+                return;
+              }
               inputRef.current?.focus();
               stepValue(1);
             }}
@@ -1016,10 +1055,17 @@ export function NumberInput({
             type="button"
             tabIndex={-1}
             {...pressable}
-            disabled={isDisabled || isReadOnly || !canDecrement}
+            aria-disabled={
+              isDisabled || isReadOnly || !canDecrement || undefined
+            }
             aria-label={t('@astryx.numberInput.decrementLabel', {label})}
             onPointerDown={event => event.preventDefault()}
             onClick={() => {
+              // An aria-disabled stepper does nothing, as a natively disabled
+              // one did (spec:AST-085 FR2).
+              if (isDisabled || isReadOnly || !canDecrement) {
+                return;
+              }
               inputRef.current?.focus();
               stepValue(-1);
             }}

package/src/Pagination/Pagination.test.tsx

@@ -965,7 +965,7 @@ describe('Pagination', () => {
         />,
       );
       const box = screen.getByRole('spinbutton', {name: 'Go to page'});
-      expect(box).toBeDisabled();
+      expect(box).toHaveAttribute('aria-disabled', 'true');
       // Disabled input never fires a change.
       await user.type(box, '5{Enter}');
       expect(onChange).not.toHaveBeenCalled();
@@ -999,7 +999,7 @@ describe('Pagination', () => {
       // editable box is inert rather than accepting entries it can't resolve.
       expect(
         screen.getByRole('spinbutton', {name: 'Go to page'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
     });
 
     it('renders the localized "Page" label by default and a custom pageLabel', () => {