@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/NavMenu/NavHeadingMenu.spec.md

@@ -1,264 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:NavHeadingMenu
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-26
-owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/NavMenu/NavHeadingMenu.test.tsx,
-    apps/storybook/stories/NavMenu.stories.tsx,
-    packages/core/src/Icon/Icon.test.tsx,
-    packages/core/src/Text/Text.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:navigation-destinations, family:action-groups]
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:icon-resolution-and-component-slots,
-    architecture:interaction-modality,
-    architecture:layer-runtime,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-005/DEC-1, spec:AST-020, spec:AST-085]
----
-
-# NavHeadingMenu component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                              |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `NavHeadingMenu` with `children`, `size` (`sm`, `md`, `lg`; default `md`), and `minWidth`; `NavHeadingMenuItem` with `label`, `description`, `icon`, `href`, `onClick`, and `isDisabled`; targets `nav-heading-menu` and `nav-heading-menu-item` with a `size` state. |
-| Behavior                | A `role="menu"` list of `menuitem` rows inside a heading popover, with arrow, Home, End, typeahead, Enter, Space, and Escape support. Selecting an enabled item runs it and, where the host heading supplies a close action, closes the heading menu.                 |
-| End-user impact         | Users switch products or accounts from the heading menu by pointer or keyboard; disabled rows are skipped by keyboard and typeahead.                                                                                                                                  |
-| Builder impact          | None.                                                                                                                                                                                                                                                                 |
-| Compatibility/readiness | Records shipped behavior; no public change. Five implementation gaps (see Current-state impact).                                                                                                                                                                       |
-| Review checks           | Reject losing `menu`/`menuitem` roles to caller props, keyboard focus landing on a disabled item, or a caller `onKeyDown` that silently disables the keyboard model.                                                                                                  |
-| Governing rules         | `family:navigation-destinations` FR7; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:layer-runtime`.                                                                                                                    |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-NavHeadingMenu presents selectable actions inside a SideNavHeading or
-TopNavHeading popover. It owns the menu list, its keyboard model, and each
-item's row. `NavMenu.doc.mjs` documents NavHeadingMenu and NavHeadingMenuItem
-together, and NavHeadingMenuItem has no consumer doc of its own, so this record
-covers both.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; runtime, DOM, styling,
-  targets, and public API remain unchanged
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **A disabled link item still navigates.** A disabled NavHeadingMenuItem with
-  `href` keeps its link destination and does not cancel the click, so a pointer
-  click navigates even though the item reports `aria-disabled` and skips its
-  `onClick`. `family:navigation-destinations` FR7 has members keep their own
-  disabled semantics, and `spec:AST-085` FR2 has a disabled control block
-  navigation.
-- **The documented composition nests two menus.** Passed as the `menu` of
-  SideNavHeading or TopNavHeading, as its consumer doc directs, NavHeadingMenu's
-  `role="menu"` sits directly inside the heading's own `role="menu"` wrapper.
-  WAI-ARIA 1.2 allows a `menu` to own only `menuitem`-family items and groups,
-  so assistive technology meets a menu nested in a menu.
-- **The menu has no name of its own.** NavHeadingMenu's `menu` carries no
-  accessible name unless the caller passes `aria-label`; inside a heading only
-  the heading's wrapper `menu` is named. The APG menu pattern, which
-  `spec:AST-020` FR15 adopts, names each menu.
-- **A disabled item changes focusability.** A disabled item drops the
-  `tabIndex=-1` enabled items carry: a disabled link item becomes a page tab
-  stop, and a disabled action item cannot take focus at all. `spec:AST-085` FR1
-  keeps a disabled control's focus order as it is when enabled.
-- **Focus is shown only by fill.** An item removes the outline and marks focus
-  with the hover fill; it does not use the shared focus outline that
-  `architecture:interaction-modality` provides.
-
-## Ownership boundary
-
-**Owns**
-
-- The Menu container, menu semantics, keyboard movement, typeahead, and current
-  `nav-heading-menu` target.
-- Each Item's action/link row, selection handling, size treatment, and current
-  `nav-heading-menu-item` target.
-- The content layout that contains either the text-rendered or caller-rendered
-  label path and the optional description.
-
-**Does not own / non-goals**
-
-- Icon artwork and the `icon` target — delegated to `component:Icon` for values
-  rendered through Icon.
-- String label and description typography and their `text` target — delegated to
-  `component:Text`.
-- Non-string label content — owned by the caller.
-- The SideNavHeading or TopNavHeading trigger, popup surface, positioning,
-  dismissal lifecycle, or close-state ownership — owned by
-  `component:SideNavHeading` and `component:TopNavHeading`.
-- Destination acceptance and blocking — owned by
-  `family:navigation-destinations`.
-
-## Public concepts
-
-| Concept | Closed values or states | Meaning                                                 | Availability by variant/orientation/state | Default | Owner                      | Stability | Invalid-value behavior           |
-| ------- | ----------------------- | ------------------------------------------------------- | ----------------------------------------- | ------- | -------------------------- | --------- | -------------------------------- |
-| Size    | `sm`, `md`, `lg`        | Menu minimum width (160, 200, 240 px) and item padding. | Menu and every item through context.      | `md`    | `component:NavHeadingMenu` | Stable    | TypeScript rejects other values. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                           |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1 | NavHeadingMenu renders one Menu `div` carrying `role="menu"`, the current `nav-heading-menu` target with `size`, the forwarded `ref`, `data-testid`, and other DOM props; caller props cannot replace the role. `minWidth` overrides the size's minimum width.                                                                                                                                                                                                                                                                                                                                                                                                              | Current source, docs, and tests |
-| FR2 | NavHeadingMenuItem renders one Item carrying `role="menuitem"` and the current `nav-heading-menu-item` target with the menu's size, as the `LinkProvider` link (else `<a>`) when `href` is supplied and a `div` otherwise. Caller props cannot replace its role, tab index, or disabled state.                                                                                                                                                                                                                                                                                                                                                                              | Current source, docs, and tests |
-| FR3 | An optional Icon-rendered icon delegates to Icon's `icon` target. String labels and all descriptions render through Text's `text` target on one line; non-string labels render directly as caller-owned content.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and target docs  |
-| FR4 | The host heading owns the popup runtime. Where it supplies a close callback (TopNavHeading and the collapsed SideNavHeading), NavHeadingMenu calls it on Escape and on successful Item selection; an expanded SideNavHeading supplies none, so the menu stays open after a choice (`component:SideNavHeading` FR7).                                                                                                                                                                                                                                                                                                                                                         | Current source and tests        |
-| FR5 | Enabled items are focusable but not tab stops. In a standalone menu, ArrowDown and ArrowUp move one enabled item and wrap; Home and End go to the first and last; typing a character moves to the matching enabled item; Enter or Space activates the focused item.                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests        |
-| FR6 | Activating an enabled item runs its `onClick` and then the close callback; a disabled item carries `aria-disabled="true"`, MUST stay focusable outside the tab order as an enabled item is (`spec:AST-085` FR1), is skipped by keyboard movement and typeahead, and does not run `onClick` or close the menu. Implementation gap: a disabled item drops `tabIndex=-1` (Current-state impact).                                                                                                                                                                                                                                                                               | Current source and tests        |
-| FR7 | A caller `onKeyDown` on the menu runs first; the keyboard model still runs unless that caller calls `preventDefault()` on an event no item handler has already cancelled; an item handler that cancels does not stop arrow navigation.                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source and tests        |
-| FR8 | In the open menu, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. | Current source and tests        |
-
-### Allowed variation
-
-- Items may render as links or callback actions and may be enabled or disabled
-  without changing anatomy ownership.
-- Icon may be absent. A label may take the string path rendered through Text or
-  the non-string path rendered directly as caller-owned content. Item
-  description may be absent and, when present, renders through Text.
-- Menu size and minimum width may vary without creating separate anatomy parts
-  or targets.
-
-### Representative states
-
-| State             | Required invariant                                                | Allowed variation                                         |
-| ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
-| Link Item         | Item is an anchor with menuitem semantics and its current target. | Destination, text, description, and icon may vary.        |
-| Action Item       | Item is a div with menuitem semantics and its current target.     | Selection callback may vary.                              |
-| Disabled Item     | Item remains present and reflects disabled semantics.             | It is skipped by keyboard navigation and typeahead.       |
-| String-label Item | Text-rendered item label delegates to Text's current target.      | Label value, destination, description, and icon may vary. |
-| Custom-label Item | Caller-rendered item label remains caller-owned.                  | Caller controls the non-string label content.             |
-| Described Item    | Item description delegates to Text's current target.              | Description content may vary or be absent.                |
-
-### Transformation and precedence order
-
-- **ORD1 — Menu width.** `minWidth`, then the size's minimum width.
-- **ORD2 — Keyboard.** Caller `onKeyDown`, then the menu keyboard model (FR7).
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Menu semantics.** One `menu` holds `menuitem` rows (FR1, FR2). It is
-  named only by a caller `aria-label`; inside a heading, the heading names its
-  own wrapper `menu`, not this one (Current-state impact).
-- **AR2 — Keyboard.** FR5 and FR6.
-- **AR3 — Disabled.** Disabled items are exposed as disabled and unreachable by
-  keyboard movement.
-
-## Design relationships
-
-| Anatomy or state           | Design requirement                                                        | Representation authority       | Hierarchy role    | Component contract |
-| -------------------------- | ------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
-| Menu                       | Groups nav-heading actions with menu semantics and keyboard navigation.   | Current source and public docs | Prominent         | FR1, FR4           |
-| Item                       | Presents one selectable action or navigation destination.                 | Current source and public docs | Prominent         | FR2                |
-| Icon                       | Presents optional Icon-owned artwork before the label.                    | `component:Icon`               | Supporting        | FR3                |
-| Text-rendered item label   | Presents a string label through Text's body treatment.                    | `component:Text`               | Prominent         | FR2, FR3           |
-| Caller-rendered item label | Presents a non-string label directly through caller-owned content.        | Caller-supplied content        | Context-dependent | FR2, FR3           |
-| Item description           | Presents optional supporting content through Text's supporting treatment. | `component:Text`               | Supporting        | FR2, FR3           |
-
-The menu is popup content, not the popup host. SideNavHeading or TopNavHeading
-owns the layer lifecycle and supplies the close callback through context.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Menu": {"target": "nav-heading-menu"},
-  "Item": {"target": "nav-heading-menu-item"},
-  "Icon": {
-    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
-  },
-  "Text-rendered item label": {
-    "delegatesTo": {"owner": "component:Text", "target": "text"}
-  },
-  "Caller-rendered item label": {
-    "none": {
-      "reason": "intentional: Non-string label content is rendered directly and remains caller-owned"
-    }
-  },
-  "Item description": {
-    "delegatesTo": {"owner": "component:Text", "target": "text"}
-  }
-}
-```
-
-## Family and system relationships
-
-- `architecture:component-theming-surface` owns anatomy qualification, local
-  target mapping, component delegation, and factual `none` dispositions.
-- `architecture:icon-resolution-and-component-slots` owns Icon slot resolution;
-  this record states the current Icon delegation.
-- `architecture:layer-runtime` owns the shared popup host lifecycle used by the
-  parent nav heading. NavHeadingMenu owns only its menu behavior and consumes the
-  heading-provided close callback.
-- `architecture:public-component-api` owns the stable props and subcomponent
-  surface.
-- `family:navigation-destinations` owns the shared accept/block result for a
-  NavHeadingMenuItem `href`; `spec:AST-005/DEC-1` requires native and
-  custom-router item paths to preserve that result.
-
-## Verification map
-
-| Contract            | Verification                                                                   | Representative states                                                        | Mutation or failure expectation                                                                                                                                                                        | Audit section                   |
-| ------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
-| FR1, FR2            | `NavHeadingMenu.test.tsx` role, render, link, and disabled suites              | Menu with link, action, and disabled Items                                   | Removing menu/item semantics, content, or current rendering branches fails existing role, tag, attribute, and text checks.                                                                             | `audit:NavHeadingMenu/anatomy`  |
-| FR3                 | NavHeadingMenuItem source inspection plus Icon and Text target metadata        | Icon, string label, caller-rendered label, and description paths             | Source proves Icon-slot delegation, conditional label rendering, and Text-wrapped description; focused tests assert string and description content but not target placement or custom-label ownership. | `audit:NavHeadingMenu/theming`  |
-| FR4–FR7             | `NavHeadingMenu.test.tsx` context, keyboard, disabled, and pass-through suites | Selection, Escape, arrows, Home/End, typeahead, disabled, caller handlers    | Breaking close callback consumption, keyboard behavior, or role precedence fails focused interaction assertions.                                                                                       | `audit:NavHeadingMenu/behavior` |
-| Target inventory    | Source inspection and `themingTargets.test.ts`                                 | Menu, Item, and delegated Icon targets                                       | Runtime and documented target metadata drift fails target validation.                                                                                                                                  | `audit:NavHeadingMenu/theming`  |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                  | Canonical anatomy and both current local targets                             | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                                                                | `audit:NavHeadingMenu/theming`  |
-| FR8                 | `NavHeadingMenu.test.tsx` action-group suite (touch and mouse slides)          | Touch and mouse slides across items; a disabled item; undraggable link items | Removing the adoption fails the slide tests.                                                                                                                                                           | —                               |
-
-Read from source, with no focused test yet:
-
-- FR1: the forwarded `ref`, and the menu role winning over caller props.
-- FR2: the `nav-heading-menu-item` target and the `LinkProvider` link.
-- FR3.
-- FR5: that enabled items are focusable but not tab stops.
-- FR6: that a disabled item does not close the menu.
-- FR4, FR5, and AR1 inside SideNavHeading or TopNavHeading.
-- The Menu and Item target placements in the theming map.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, keyboard or layer
-algorithms, implementation steps, or system rules. It links to their owners.

package/src/NumberInput/NumberInput.spec.md

@@ -1,270 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:NumberInput
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: imdreamrunner
-approved_at: 2026-10-29
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/NumberInput/NumberInput.test.tsx,
-    packages/core/src/NumberInput/NumberInput.fr10.test.tsx,
-    packages/core/src/NumberInput/numberInputCommit.test.ts,
-    packages/core/src/NumberInput/numberParser.test.ts,
-    packages/core/src/NumberInput/numberParser.docblock.test.ts,
-    packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx,
-    packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts,
-    packages/core/src/NumberInput/__tests__/NumberInput.coarse-pointer.a11y.chromium.spec.ts,
-    packages/core/src/InputGroup/InputGroup.test.tsx,
-  ]
-modules: []
-families: [family:input-fields]
-design_specs: [design:reduced-motion]
-architecture:
-  [
-    architecture:icon-resolution-and-component-slots,
-    architecture:component-size-cascade,
-    architecture:component-theming-surface,
-    architecture:internationalization,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-085, spec:AST-086, spec:AST-102]
----
-
-# NumberInput component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                         |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | NumberInput is a controlled numeric field with Field props, size, status, `min`, `max`, `step`, `isIntegerOnly`, `formatValue`, `units`, steppers, wheel stepping, clear, disabled and read-only states, and input-family part props.                            |
-| Behavior                | A text-backed `spinbutton`; a typed draft commits on blur or Enter, parsed for the locale and clamped to the range. Arrow keys, the wheel, and available non-coarse-pointer steppers step on a grid and commit at once.                                          |
-| End-user impact         | Coarse-pointer users enter numbers directly instead of using compact steppers. Keyboard stepping remains available. Invalid entries are announced; disabled fields remain reachable; read-only is not announced.                                                 |
-| Builder impact          | Public prop types and numeric callbacks remain unchanged; existing NumberInput calls need no source or configuration migration.                                                                                                                                  |
-| Compatibility/readiness | Coarse-pointer adaptation is non-breaking: numeric values, validation, direct entry, and keyboard stepping remain supported. The read-only exposure and reduced-motion clear-button gaps remain listed under Current-state impact.                               |
-| Review checks           | Reject coarse-pointer steppers, loss of non-coarse-pointer steppers when requested, per-keystroke `onChange`, an unparsable commit, an off-grid or out-of-range step, a disabled field that leaves the tab order or submits, or stepping during IME composition. |
-| Governing rules         | FR5 and AR4 own pointer-conditioned stepper availability; `family:input-fields` FR3, FR4, FR8–FR11; `spec:AST-085` FR1–FR3, FR6; `spec:AST-086` FR3, FR4; `spec:AST-017` FR1, FR3, FR7; `architecture:internationalization`; `design:reduced-motion` DR1.        |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-NumberInput collects one number. It owns locale-aware parsing, the draft and
-commit policy, range clamping, stepping, formatted display, and the numeric
-field's adaptation to Field and InputGroup under `family:input-fields`.
-Consumer usage lives in `NumberInput.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`; `step={1}`, wheel stepping on, no
-  steppers, no clear, `size="md"`, `statusVariant="attached"`
-- Compatibility class: non-breaking presentation adaptation; public prop
-  names, types, exports, numeric values and callbacks, validation, direct entry,
-  and keyboard stepping remain unchanged under `spec:AST-017` FR3's numeric-stepper
-  presentation rule
-- Controlled/uncontrolled behavior: controlled only; `value` (`number`, `null`,
-  or `undefined`) is the committed value, and NumberInput keeps only an
-  uncommitted text draft of its own
-- Migration decision: no caller source or configuration migration; numeric
-  input functionality remains available through direct entry and keyboard
-  stepping while compact visual stepper aids adapt to pointer precision
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The text-backed spinbutton and its numeric ARIA values.
-- Locale-aware parsing, draft validity, and the commit, clear, or revert
-  decision.
-- Stepping by keyboard, wheel, and steppers, and the stepping grid.
-- Formatted display at rest and the form value it submits.
-- Units text, the invalid-entry announcement, and the steppers.
-- The stepper icon's `numberInput:stepperDown` extension key, which
-  `architecture:icon-resolution-and-component-slots` hands to NumberInput.
-- Disabled, disabled-reason, and read-only behavior; the `number-input`
-  target; its grouped adaptation.
-
-**Does not own / non-goals**
-
-- Label, description, label icon, label tooltip, status message placement, and
-  `width` — owned by Field under `family:input-fields` (shared owner section).
-- The clear button's own rendering and tooltip — owned by the shared clear
-  control (`family:input-fields` FR11).
-- InputGroup row geometry — owned by InputGroup under `family:input-fields`
-  (shared owner section).
-- `isLoading` and `changeAction` — not provided (`family:input-fields` AV5).
-- The parser and commit helpers — internal; other components reuse them but
-  they are not public.
-
-## Public concepts
-
-| Concept      | Closed values or states     | Meaning                              | Availability by variant/orientation/state   | Default                   | Owner                   | Stability | Invalid-value behavior                                                                                                    |
-| ------------ | --------------------------- | ------------------------------------ | ------------------------------------------- | ------------------------- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Range        | `min`, `max`, each optional | Inclusive bounds a commit clamps to. | Always.                                     | unbounded                 | `component:NumberInput` | Stable    | `min` above `max` (after integer rounding) reverts every typed commit on blur; Enter commits nothing and keeps the draft. |
-| Step         | positive finite number      | Stepping increment.                  | Arrow keys, wheel, steppers.                | `1`                       | `component:NumberInput` | Stable    | A missing, non-positive, non-finite, or (integer-only) fractional step becomes `1`.                                       |
-| Integer only | off, on                     | Only whole numbers parse and commit. | Always.                                     | off                       | `component:NumberInput` | Stable    | A fractional draft is invalid.                                                                                            |
-| Draft        | none, valid, invalid        | Uncommitted typed text.              | While editing.                              | none                      | `component:NumberInput` | Stable    | Not applicable.                                                                                                           |
-| Clearable    | off, on                     | Whether the value may become `null`. | Widens `onChange` to accept `null` when on. | off                       | `component:NumberInput` | Stable    | Not applicable.                                                                                                           |
-| Size         | `sm`, `md`, `lg`            | Control height.                      | Always.                                     | Inherited size, else `md` | `family:input-fields`   | Stable    | TypeScript rejects other values.                                                                                          |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                                                  |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| FR1  | The input is a native text input with `role="spinbutton"`, `inputMode` `numeric` when integer-only and `decimal` otherwise, `aria-valuemin` and `aria-valuemax` from the range, `aria-valuenow` from the committed `value`, and `aria-valuetext` set to the formatted value when `formatValue` is supplied.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current tests                                                          |
-| FR2  | Typing changes only a draft; `onChange` is not called while typing. A draft is valid when it parses for the active locale (grouping, decimal separator, digit script, and sign) and, for validity display, lies within the range and meets integer-only. An invalid draft colors the text secondary, sets `aria-invalid`, and fills a persistent assertive region with the localized invalid-number message.                                                                                                                                                                                                                                                                                                                                                                                      | `spec:AST-086` FR3; `architecture:internationalization`; current tests |
-| FR3  | On blur the draft resolves once and ends: an empty draft clears (`onChange(null)` when clearable and a value exists) or reverts; an unparsable or wrong-kind draft reverts; otherwise the number clamps to the range and commits with `onChange(number)` when it differs from `value`. Enter resolves a valid draft the same way and clears an empty draft when clearable. Enter commits nothing for an empty draft without `hasClear`, which stays in the field and is not marked invalid, or for an unparsable or wrong-kind draft, which stays in the field and stays invalid. Enter ends the draft only when its commit clamped. In a field that is not disabled, every Enter outside composition then calls `onEnter`, whatever it committed.                                                | Current tests                                                          |
-| FR4  | ArrowUp and ArrowDown without modifiers, the wheel over the focused input (when `isWheelEnabled`), and the steppers step by one grid position and commit at once. The grid starts at `min` (when it suits integer-only) or 0. From an empty field or an emptied draft, up goes to `min` or 0 and down to `max` or 0. Results round to the finer of the step's and the grid start's precision (at most 12 decimal places), clamp to the range, and never leave integer-only; a stepper that cannot move does nothing, while an arrow or wheel step that cannot move still ends the draft, committing a valid draft's number and dropping an unparsable one. A caller `onKeyDown` that prevents an arrow cancels that step. A wheel step stops the page from scrolling; otherwise the page scrolls. | Current tests                                                          |
-| FR5  | With `hasNumberSteppers`, increment and decrement buttons render at the end of the control unless the primary pointer is coarse. On coarse primary pointers the buttons are hidden from layout and the accessibility tree at every viewport width, with no opt-out; the control restores its normal themed end padding. Direct numeric entry and keyboard stepping remain available. When shown, the buttons are outside the tab order, are named with the localized increment and decrement phrases and the label, keep focus on the input when pressed, and expose `aria-disabled` when stepping that way cannot move or the field is disabled or read-only.                                                                                                                                    | `spec:AST-085` FR1, FR2; current tests                                 |
-| FR6  | With `formatValue`, the input shows the formatted committed value at rest and the plain locale-formatted number while focused. The form value is then submitted from a hidden input carrying the raw number, and the visible input has no `name`; without `formatValue` the visible input carries `name`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current tests                                                          |
-| FR7  | `units` renders as secondary text after the input and is part of the input's description.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current tests                                                          |
-| FR8  | With `hasClear`, a clear button shows while `value` is not `null` and the field is editable. Activating it calls `onChange(null)`, drops the draft, and focuses the input as TextInput's clear does. The clear button is a ghost small `component:Button`, so its press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: it still scales under reduced motion.                                                                                                                                                                                                                                                                                                                                                                                        | `family:input-fields` FR11; current tests                              |
-| FR9  | NumberInput is disabled when its own `isDisabled` or an enclosing InputGroup's `isDisabled` is true; an enabled group never re-enables a field that disables itself (`spec:AST-085` FR7). Disabled: `aria-disabled="true"` and `readOnly` on the input, a kept tab stop, no submitted value, no draft commit (a draft in progress is dropped), no stepping by any route, no caller handlers other than focus and blur, Enter cancelled, the clear button hidden, the control dimmed, and a keyboard focus ring. With `disabledMessage`, a reason tooltip opens on hover and keyboard focus and describes the input.                                                                                                                                                                               | `spec:AST-085` FR1–FR3, FR6; `family:input-fields` FR4; current tests  |
-| FR10 | Read-only: `readOnly`, full opacity, still submitted, no edits, and no stepping by keyboard, wheel, or steppers; the wheel then scrolls the page. Disabled wins when both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current tests                                                          |
-| FR11 | Arrow and Enter keys that belong to an IME composition neither step nor commit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current tests                                                          |
-| FR12 | Field composition, InputGroup adaptation, status presentation, start icon, click-to-focus, size and iOS text floor, and the prop targets match `component:TextInput` FR1, FR9, FR11–FR13, including its implementation gaps (the fixed height against `spec:AST-102` FR4, an error status without text, the color-only `detached` status, and the grouped description), plus a `labelIcon` passed to Field.                                                                                                                                                                                                                                                                                                                                                                                       | `family:input-fields` FR3, FR8–FR10; current tests                     |
-| FR13 | The control box carries `astryx-number-input` with `data-size`, `data-status`, `data-disabled`, and `data-readonly`. A theme `padding` in any spelling on `number-input` pads the control box and the stepper column together.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `architecture:component-theming-surface`; current tests                |
-
-### Allowed variation
-
-- **AV1 — Number formatting.** `formatValue` may return any text; the
-  committed value stays numeric.
-- **AV2 — Theme padding.** Themes may change `number-input` padding; the
-  steppers follow it.
-
-### Representative states
-
-| State                | Required invariant                                                               | Allowed variation |
-| -------------------- | -------------------------------------------------------------------------------- | ----------------- |
-| At rest, formatted   | Formatted text; `aria-valuetext`; hidden raw form value.                         | Format.           |
-| Focused              | Plain locale number, ready to edit.                                              | Locale.           |
-| Invalid draft        | Secondary text; `aria-invalid`; assertive invalid-number message; no `onChange`. | —                 |
-| Out-of-range commit  | Clamped value committed on blur or Enter.                                        | —                 |
-| Stepper at the bound | That stepper `aria-disabled`; stepping does nothing.                             | —                 |
-| Disabled with reason | Focusable; read-only; not submitted; no stepping; reason tooltip.                | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Typed commit.** Trim → empty check → locale parse → integer check →
-  range check (`min` rounded up and `max` rounded down when integer-only) →
-  clamp → commit if changed.
-- **ORD2 — Step.** Current number (the draft if valid; an emptied draft steps
-  from empty, FR4; otherwise `value`) → next grid position → round to the finer
-  of the step's and the grid start's precision → clamp → integer check.
-- **ORD3 — Availability.** Disabled, then read-only, then editable.
-
-### Performance and resources
-
-- **PR1 — One wheel listener.** Each mounted input with wheel stepping on
-  holds one non-passive wheel listener on itself; it acts only while that
-  input has focus.
-
-## Accessibility contract
-
-- **AR1 — Spinbutton.** FR1; the committed value, not the draft, is exposed.
-- **AR2 — Invalid entry.** FR2's assertive region announces an invalid draft,
-  since an invalid draft reverts silently on blur (WCAG 3.3.1).
-- **AR3 — Disabled.** FR9 satisfies `spec:AST-085` FR1, FR5, and FR6.
-- **AR4 — Steppers.** Compact pointer-only aids are hidden on coarse primary
-  pointers at every viewport width. Direct numeric entry remains available, and
-  arrow keys provide keyboard stepping on every pointer type (FR4, FR5).
-- **AR5 — Read-only exposure.** A read-only NumberInput MUST expose its
-  read-only state to assistive technology (WCAG 2.2 4.1.2). Implementation gap:
-  the spinbutton exposes no read-only state.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                                                            | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Input            | Numeric text; secondary color while the draft is invalid.                                                     | Current source and tests | Prominent      | FR2                |
-| Units            | Secondary text after the number.                                                                              | Current source and tests | Supporting     | FR7                |
-| Steppers         | Stacked at the end on non-coarse pointers; hidden on coarse primary pointers, with normal themed end padding. | FR5; DEC-1               | Supporting     | FR5, FR13          |
-
-`design:reduced-motion` governs the clear button's press scale (FR8); no other
-design record governs NumberInput. The control box carries `number-input`;
-the consumer anatomy names no control-box part, so this record carries no
-anatomy-theming map.
-
-## Family and system relationships
-
-- `family:input-fields` owns grouped admission, disabled reasons, status
-  placement, the focus-zoom floor, prop targets, and the clear tooltip;
-  NumberInput adopts them and exposes no `isLoading` or `changeAction`.
-- `spec:AST-085` owns disabled focusability; NumberInput meets it, including
-  the steppers.
-- `spec:AST-086` FR3 and FR4 own the persistent invalid-entry region.
-- `architecture:internationalization` owns locale resolution the parser uses.
-- `component:TextInput` is the reference for the shared text-field behavior
-  FR12 names.
-
-## Verification map
-
-| Contract                 | Verification                                                                                                                              | Representative states                                                                  | Mutation or failure expectation                                                                                             | Audit section                     |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| FR1, AR1                 | `NumberInput.test.tsx` spinbutton-attribute suite; `NumberInput.a11y.chromium.spec.ts`                                                    | Bounded, unbounded, formatted                                                          | A missing role or ARIA value fails.                                                                                         | `audit:NumberInput/accessibility` |
-| FR2, AR2                 | `numberParser.test.ts`; `numberParser.docblock.test.ts`; `NumberInput.test.tsx` invalid-feedback suite                                    | Locales, grouping, invalid text                                                        | A misparse, a commit of a guess, or a missing announcement fails.                                                           | `audit:NumberInput/behavior`      |
-| FR3, ORD1                | `numberInputCommit.test.ts`; `NumberInput.test.tsx` validation, commit-policy, clamping, keyboard-clearing suites                         | Blur, Enter, empty, clamp, inverted range                                              | A per-keystroke `onChange`, an unclamped commit, or a wrong clear fails.                                                    | `audit:NumberInput/behavior`      |
-| FR4, FR5, ORD2, AR4, PR1 | `NumberInput.test.tsx` stepping and steppers suites; wheel-listener cases                                                                 | Keys, wheel, steppers; bounds; empty; precision                                        | A step off the grid, past a bound, or with modifiers fails. Evidence gap: no test steps from an emptied draft over a value. | `audit:NumberInput/behavior`      |
-| FR6, FR7                 | `NumberInput.test.tsx` formatted-display, form, and units suites                                                                          | Rest and focus; form submission                                                        | A formatted value submitted, or units not described, fails.                                                                 | `audit:NumberInput/behavior`      |
-| FR8                      | `NumberInput.test.tsx` hasClear suite                                                                                                     | Clear; disabled; read-only                                                             | A clear on a disabled field, or no `null`, fails. Evidence gap: no test presses the clear button under reduced motion.      | `audit:NumberInput/behavior`      |
-| FR9, FR10, ORD3, AR3     | `NumberInput.test.tsx` disabled, disabledMessage, read-only, and form suites; `InputGroup.test.tsx` disabled-propagation cases            | Disabled, reason, read-only                                                            | A lost tab stop, a submitted disabled value, or stepping while read-only fails.                                             | `audit:NumberInput/accessibility` |
-| FR12                     | `NumberInput.fr10.test.tsx`; `NumberInput.test.tsx` status and click-to-focus suites                                                      | Standalone and grouped                                                                 | A base prop off the input, or styling on the wrong part, fails.                                                             | `audit:NumberInput/api`           |
-| FR13                     | `NumberInput.test.tsx` theme-state and stepper-padding suites                                                                             | Each padding spelling                                                                  | Steppers that ignore the theme padding fail.                                                                                | `audit:NumberInput/theming`       |
-| AR5                      | `NumberInput.a11y.chromium.spec.ts` with its recorded known failure                                                                       | Read-only                                                                              | The known failure stops matching when the gap closes.                                                                       | `audit:NumberInput/accessibility` |
-| FR11                     | `NumberInput.test.tsx` "does not step or commit on a composing keydown (IME)" and "waits for IME composition to finish before committing" | Composing arrows and Enter                                                             | A step or commit during composition fails.                                                                                  | `audit:NumberInput/behavior`      |
-| FR5, FR13, AR4           | `NumberInput.coarse-pointer.a11y.chromium.spec.ts`                                                                                        | Coarse/non-coarse pointers at 390 and 1280 px, LTR/RTL, non-default themed end padding | Visible coarse-pointer steppers, hidden fine-pointer steppers, wrong end padding, or lost direct/keyboard entry fail.       | `audit:NumberInput/behavior`      |
-
-## Current-state impact
-
-- **Read-only not exposed (AR5).** A read-only NumberInput's spinbutton does
-  not expose a read-only state, so assistive-technology users may expect to
-  edit it. The accessibility suite records this as a known failure.
-- **Clear press under reduced motion (FR8).** The clear button scales to 0.98
-  on a press when the person prefers reduced motion, as `component:Button` FR15
-  records, against `design:reduced-motion` DR1.
-- **Inherited TextInput gaps (FR12).** The fixed height (`spec:AST-102` FR4),
-  an error status without a message shown only by color and an icon (WCAG 2.2
-  3.3.1), the color-only `detached` status without a message (WCAG 2.2 1.4.1),
-  and the grouped description reference that `component:TextInput` records
-  apply here.
-- **Stepper icon key.** The steppers resolve their icon through the
-  `numberInput:stepperDown` extension key rather than the component-slot model,
-  the known deviation `architecture:icon-resolution-and-component-slots` names;
-  it exits under that record's exit condition.
-
-## Decision log
-
-NumberInput applies `family:input-fields` and `spec:AST-085`.
-
-### DEC-1 — Compact steppers follow primary-pointer precision
-
-**Reference:** `component:NumberInput/DEC-1`
-**Decider:** `imdreamrunner`, `2026-10-29`
-
-Coarse-primary-pointer presentation uses direct numeric entry rather than
-compact steppers, independently of viewport width and without an opt-out.
-Non-coarse-pointer steppers and keyboard stepping retain their contracts.
-The compact buttons are presentation aids: the numeric value, validation,
-callback, direct-entry, and keyboard-stepping contracts do not depend on their
-visibility. Adapting those aids requires no caller source or configuration
-migration.
-
-Rejected: width-based activation, because pointer precision governs this
-control affordance rather than the available layout width.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.