@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Thumbnail/Thumbnail.spec.md

@@ -1,244 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Thumbnail
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-26
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Thumbnail/Thumbnail.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/Thumbnail.stories.tsx,
-    .github/visual-baseline/manifest.json,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:internationalization,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-009, spec:AST-085, spec:AST-086]
----
-
-# Thumbnail component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                             |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | A 64px square image preview with `src`, `alt`, `label`, `isLoading`, `isDisabled`, an optional `onClick` open action, and an optional `onRemove` action revealed per `showRemoveOn`. |
-| Behavior                | The preview shows a skeleton, the image, an upload overlay, or a placeholder; it is a named group whose open and remove actions are separate buttons.                                |
-| End-user impact         | Screen-reader users hear the file and image in one group name and reach "Open …" and "Remove …" buttons; keyboard and touch users can always reach a hover-revealed remove button.   |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                         |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Six implementation gaps are listed under Current-state impact.                                            |
-| Review checks           | Reject a hover-only remove button that leaves the tab order, a name on a roleless element, an image exposed without `alt`, or a busy spinner that announces itself.                  |
-| Governing rules         | `spec:AST-085/FR1`; `spec:AST-086/FR8`; WCAG 2.2 2.5.8; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:internationalization/INV1a`.                               |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Thumbnail previews one image attachment in a compact square, with optional
-open and remove actions. It owns the preview's loading, error, and upload
-states, its accessible group name, and the placement and reveal of its remove
-action.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes
-- Controlled/uncontrolled behavior: not applicable; image-failure tracking is
-  internal state
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Caller `role` replaces the group role (FR7, AR1).** A caller `role`, such
-  as `none` or `img`, overwrites `role="group"`, leaving the composed name on
-  an element that may not take it, where `architecture:public-component-api`
-  INV5 keeps component-owned semantics from being overwritten.
-- **Joined name outside the catalog (FR3).** With both `label` and `alt`, the
-  group name "{label} — {alt}" is assembled at the call site rather than from
-  one catalog message, so a locale cannot reorder or re-punctuate it
-  (`architecture:internationalization` INV1a).
-- **Remove target below 24px (AR4).** On a fine pointer the remove button's hit
-  area is 20 by 20 CSS pixels and it overlaps the open action, where WCAG 2.2
-  2.5.8 requires 24 by 24 or spacing. On a coarse pointer it is 24 by 24.
-- **Label tooltip not reachable by keyboard (FR3).** The label tooltip
-  attaches to the root group, which is not focusable, so keyboard focus on the
-  open or remove button does not reveal it (WCAG 2.2 2.1.1). The label still
-  reaches assistive technology through the group and button names.
-- **Two focus indicators on Open and Remove (FR4).** The image container
-  outlines whenever it contains keyboard focus, and both the open and the
-  remove button keep their own focus ring, so focusing either draws two
-  indicators, where `architecture:interaction-modality` INV3 allows one per
-  focus move.
-- **Disabled state not reflected on the target (FR6).** The `thumbnail`
-  target reflects no state, so a theme cannot style the disabled state there (`architecture:component-theming-surface` INV6).
-
-## Ownership boundary
-
-**Owns**
-
-- The root group, the square image container, and the Image, Placeholder,
-  Skeleton, Upload overlay, and Remove button parts.
-- The visual-state choice and image-failure retry.
-- The group name, the open-button name, and the remove-button name.
-- The remove button's placement, scrim, hit area, and hover reveal.
-- The upload busy announcement.
-
-**Does not own / non-goals**
-
-- Lightbox or detail view opened by `onClick` — owned by the product callsite.
-- Collections of attachments and upload transport — owned by composing
-  components and the product callsite.
-- Button, Skeleton, Spinner, Icon, and Tooltip internals — owned by those
-  components; Thumbnail composes them.
-- The hover-and-focus reveal mechanism — owned by the shared container-reveal
-  utility.
-
-## Public concepts
-
-| Concept       | Closed values or states                                                   | Meaning                                                                                       | Availability by variant/orientation/state         | Default     | Owner                 | Stability | Invalid-value behavior           |
-| ------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------- | --------------------- | --------- | -------------------------------- |
-| Visual state  | skeleton; image or placeholder under the upload scrim; image; placeholder | What the image container shows (FR2).                                                         | Resolved from `src`, `isLoading`, and load errors | placeholder | `component:Thumbnail` | Stable    | —                                |
-| Open action   | present; absent                                                           | `onClick` adds an "Open …" button over the image; inert while loading or disabled (FR4).      | With `onClick`                                    | absent      | `component:Thumbnail` | Stable    | —                                |
-| Remove action | present; absent                                                           | `onRemove` adds a "Remove …" button in the top inline-end corner; inert while disabled (FR5). | With `onRemove`                                   | absent      | `component:Thumbnail` | Stable    | —                                |
-| Remove reveal | `hover`, `always`                                                         | Whether the remove button is shown at rest.                                                   | Only with `onRemove`                              | `hover`     | `component:Thumbnail` | Stable    | TypeScript rejects other values. |
-| Disabled      | enabled; disabled                                                         | Dims the thumbnail; its actions stay focusable and announced as disabled (FR6).               | All states                                        | enabled     | `component:Thumbnail` | Stable    | —                                |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                    |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | The root is a 64px-wide, non-shrinking, isolated inline-flex column carrying the `thumbnail` target. It holds a square image container with `--radius-element` corners, clipped overflow, and a `--color-neutral` background.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
-| FR2 | `isLoading` without `src` shows a Skeleton; `isLoading` with `src` shows the image, or the placeholder glyph if that `src` failed, under an overlay-colored upload scrim holding a small on-media Spinner; `src` without loading shows the image, cover-fitted, with a 1px inset border; no `src`, or a `src` that failed to load, shows a secondary-colored image placeholder glyph. A failure is tracked per `src`, so a changed `src` is tried again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
-| FR3 | The root is `role="group"` named "{label} — {alt}" when both exist, else `label`, else `alt`, else the translated "Thumbnail"; a caller `aria-label` or `aria-labelledby` reaches the root after it and names the group instead. A joined name is one catalog message (`architecture:internationalization` INV1a); implementation gap: "{label} — {alt}" is joined at the call site (Current-state impact). A defined `label` also wraps the thumbnail in a Tooltip showing it, which also sets the label as the group's accessible description; `label` is never rendered inline. A tooltip can be revealed from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip attaches to the non-focusable root and opens on hover and touch only; focusing the open or remove button does not show it (Current-state impact). In development, a `src` with no `alt`, `label`, `aria-label`, or `aria-labelledby` logs a warning. | Current source and tests |
-| FR4 | With `onClick`, a full-size `button type="button"` named "Open {name}" wraps the image content and calls `onClick`; hover and pressed overlays show for mouse and touch. While loading or disabled, Open stays mounted and inert, so a focused Open keeps focus (`spec:AST-085` FR1, FR4, FR6). Each focus move shows one indicator (`architecture:interaction-modality` INV3): the image container draws the shared focus-visible outline for the open button. Implementation gap: both the open and the remove button keep their own focus ring inside the container outline, so focusing either draws two indicators (Current-state impact).                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR5 | With `onRemove`, a small icon-only secondary Button named "Remove {name}" sits `--spacing-1` from the top and inline-end edges above the image, painted with the overlay scrim and on-dark icon; a click stops propagation before `onRemove`, so it never opens the thumbnail. With `showRemoveOn="hover"` the button is visually hidden at rest by opacity, stays in the tab order and accessibility tree, and is revealed on container hover, on focus within, and always on touch devices. While disabled, Remove stays mounted and inert, so a focused Remove keeps focus (`spec:AST-085` FR1, FR4).                                                                                                                                                                                                                                                                                                                              | Current source and tests |
-| FR6 | `isDisabled` dims the root to half opacity with pointer events off. Its actions stay mounted, focusable, and announced as disabled (`spec:AST-085` FR1, FR4, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `thumbnail` target reflects no state (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
-| FR7 | `ref` reaches the root. Supported DOM, ARIA, data, and event props reach the root; `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. A caller `aria-label` or `aria-labelledby` names the group (FR3). The group role is component-owned semantics (`architecture:public-component-api` INV5). Implementation gap: caller props spread after the role, so a caller `role` replaces it (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Theme paint.** A theme may restyle `thumbnail` without changing its
-  states, names, or action placement.
-- **AV2 — Image content.** Image dimensions vary; the image always covers the
-  square.
-
-### Representative states
-
-| State                | Required invariant                                                                                                                                    | Allowed variation |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
-| Image, named         | Group named from `label` and `alt`; image exposed with its `alt`.                                                                                     | —                 |
-| Image without alt    | Image `alt=""`, `role="presentation"`, `aria-hidden`.                                                                                                 | —                 |
-| Placeholder or error | Placeholder glyph; a new `src` retries.                                                                                                               | —                 |
-| Loading, no src      | Skeleton; an Open action stays mounted and inert.                                                                                                     | —                 |
-| Uploading            | The image, or the placeholder if it failed, under the scrim with a hidden Spinner; busy start announced once; an Open action stays mounted and inert. | —                 |
-| Openable             | "Open {name}" button; focus outline on the container (the button's own ring is the FR4 gap).                                                          | —                 |
-| Removable, hover     | "Remove {name}" in the tab order, revealed on hover, focus, and touch.                                                                                | —                 |
-| Disabled             | Half opacity; Open and Remove stay mounted, focusable, and inert.                                                                                     | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Visual state.** Loading without `src` → loading with `src` (the
-  image, or the placeholder if it failed, under the upload scrim) → image →
-  placeholder (no `src` or load error).
-- **ORD2 — Name.** "{label} — {alt}" → `label` → `alt` → "Thumbnail"; a caller
-  `aria-label` replaces it on the group.
-- **ORD3 — Remove click.** Stop propagation → `onRemove`.
-
-### Performance and resources
-
-- **PR1 — CSS reveal and shared press.** The hover reveal is CSS-only. Every
-  Thumbnail installs the shared document-level press controller on mount, and
-  only an interactive one carries its press marker; the uploading state
-  announces through the shared busy-announcement channel. Thumbnail adds no
-  listener, observer, or timer of its own.
-
-## Accessibility contract
-
-- **AR1 — Group name.** The root is a named group, never a roleless element
-  with a name, so the open and remove buttons inside it stay reachable.
-  Implementation gap: a caller `role` replaces the group role (FR7).
-- **AR2 — Image alternative.** An image with `alt` is exposed with it; without
-  `alt` it is explicitly decorative.
-- **AR3 — Busy state.** The upload Spinner is hidden from assistive technology;
-  Thumbnail announces "Loading" once per busy start through the shared channel,
-  as `spec:AST-086` FR8 requires of a busy owner.
-- **AR4 — Remove target.** The remove target is at least 24 by 24 CSS pixels
-  for every pointer (WCAG 2.2 2.5.8). The button is 20 by 20, with a hit area
-  extended 2px on every side on coarse pointers. Implementation gap: on a fine
-  pointer the target stays 20 by 20.
-- **AR5 — Disabled and loading.** A disabled thumbnail's actions stay mounted,
-  focusable, and announced as disabled, and a loading thumbnail's Open stays
-  mounted and inert, so focus never moves when either state starts
-  (`spec:AST-085` FR1, FR4, FR5, FR6).
-- **AR6 — Reachable remove.** A hover-revealed remove button is never removed
-  from the tab order and appears on keyboard focus and on touch devices.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                 | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
-| Image            | The preview image as a cover-fitted square.                        | Current source and docs  | Prominent      | FR1, FR2, AR2      |
-| Placeholder      | An image silhouette when there is no image.                        | Current source and docs  | Supporting     | FR2                |
-| Remove button    | An overlaid close control on a fixed scrim legible over any image. | Current source and docs  | Supporting     | FR5, AR4, AR6      |
-| Upload overlay   | A scrim with a spinner while an image uploads.                     | Current source and docs  | Supporting     | FR2, AR3           |
-| Skeleton         | A shimmer while loading without an image.                          | Current source and docs  | Supporting     | FR2                |
-
-Theming: the root is the single `thumbnail` target; the parts add no targets.
-The consumer anatomy names no root part, so no anatomy-theming block is
-declared.
-
-## Family and system relationships
-
-- `spec:AST-085` owns focusable disabled controls; AR5 records how Thumbnail applies it.
-- `spec:AST-086` owns busy announcements; AR3 records Thumbnail's conformance.
-- `architecture:internationalization` owns the catalog behind the fallback
-  name and the open and remove names.
-- `architecture:public-component-api` owns ref, passthrough, and styling-input
-  rules; FR7 applies them to the root.
-
-## Verification map
-
-| Contract            | Verification                                                                  | Representative states                                              | Mutation or failure expectation                                                                                                                                                                                                                                                                                                 | Audit section              |
-| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1                 | `Thumbnail.stories.tsx` in a browser                                          | Every state                                                        | Gap: no test asserts the root width, layout, or the image container's shape, clipping, or paint; they are visible only in the rendered fixture.                                                                                                                                                                                 | `audit:Thumbnail/layout`   |
-| FR2, ORD1           | `Thumbnail.test.tsx` state, error, and retry tests                            | Image, placeholder, skeleton, uploading, failed, changed `src`     | A wrong element for any state, a failed image left showing, or a changed `src` not retried fails. Gap: a failed `src` while uploading, the scrim and placeholder paint and the Spinner's size and shade have no automated check; the cover fit and inset border appear only in the static-image visual baseline.                | `audit:Thumbnail/behavior` |
-| FR3, ORD2, AR1, AR2 | `Thumbnail.test.tsx` naming, role, image, warning, and tooltip tests          | Label, label with alt, alt, neither                                | A missing label or joined name, a missing `group` role, an exposed decorative image, a lost `alt`, a missing or repeated warning, or the label rendered inline fails. Gap: no test asserts the alt-only or default "Thumbnail" name, a caller `aria-label` or `aria-labelledby`, the label description, or the tooltip opening. | `audit:Thumbnail/a11y`     |
-| FR4                 | `Thumbnail.test.tsx` naming, click, loading, disabled, and touch-press tests  | Openable, loading, disabled                                        | A wrong "Open …" name, a lost callback, or a missing touch-press overlay fails. The loading and disabled tests fail if Open unmounts, calls `onClick`, or loses focus or its disabled state. Gap: the full-size button, the hover overlay, and the focus indicators have no automated check.                                    | `audit:Thumbnail/behavior` |
-| FR5, ORD3, AR6      | `Thumbnail.test.tsx` remove and `showRemoveOn` suites                         | Hover, always, default reveal                                      | A lost `onRemove`, a hover-revealed button missing from the DOM, or the same reveal treatment for both values fails. A wrong "Remove …" name also fails. Gap: that a remove click never calls `onClick`, the button's position and paint, and the reveal triggers have no automated check.                                      | `audit:Thumbnail/a11y`     |
-| FR6, AR5            | `Thumbnail.test.tsx` disabled tests                                           | Disabled with actions                                              | The tests fail if a disabled Open or Remove unmounts, loses focus, drops `aria-disabled`, or calls its callback. Gap: the half opacity and pointer-events rule have no automated check.                                                                                                                                         | `audit:Thumbnail/a11y`     |
-| FR7                 | `Thumbnail.test.tsx` ref and test-id tests                                    | Root                                                               | A lost ref or `data-testid` fails. Gap: no test covers DOM passthrough, attribute order, or the styling-input merge.                                                                                                                                                                                                            | `audit:Thumbnail/api`      |
-| AR3                 | `Thumbnail.test.tsx` uploading test; source review against `spec:AST-086` FR8 | Uploading                                                          | An exposed upload Spinner fails. Gap: no automated check fails if the busy state is announced twice.                                                                                                                                                                                                                            | `audit:Thumbnail/a11y`     |
-| AR4                 | `Thumbnail.stories.tsx` in a browser at fine and coarse pointers              | Removable                                                          | Gap: no automated target-size check; the fine-pointer size is the recorded gap.                                                                                                                                                                                                                                                 | `audit:Thumbnail/a11y`     |
-| PR1                 | Source review                                                                 | Removable, openable, uploading                                     | Gap: no automated check fails if Thumbnail adds its own listener, observer, or timer.                                                                                                                                                                                                                                           | `audit:Thumbnail/behavior` |
-| AR1, AR2            | Accessibility-tree evidence (`spec:AST-009` FR3)                              | Named group, open and remove buttons, image with and without `alt` | Gap: no accessibility-tree check proves the group name, button names, or image exposure; the unit tests query the DOM.                                                                                                                                                                                                          | `audit:Thumbnail/a11y`     |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## 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.

package/src/TimeInput/TimeInput.spec.md

@@ -1,270 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:TimeInput
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/TimeInput/TimeInput.test.tsx,
-    packages/core/src/TimeInput/NativeTimeInput.test.tsx,
-    packages/core/src/TimeInput/Presentation.test.tsx,
-    packages/core/src/TimeInput/TimeInput.fr10.test.tsx,
-    packages/core/src/InputGroup/InputGroup.test.tsx,
-  ]
-modules: []
-families: [family:input-fields]
-design_specs: [design:reduced-motion]
-architecture:
-  [
-    architecture:component-size-cascade,
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:internationalization,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-043, spec:AST-085, spec:AST-086, spec:AST-102]
----
-
-# TimeInput component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | The Hour format default is the provider locale's hour cycle, not a fixed `12h`; no prop, type, or export changes. TimeInput takes an ISO time `value`, `onChange`, `changeAction`, `isLoading`, `min`, `max`, `hasSeconds`, `hourFormat`, `increment`, `hasClear`, `presentation` (and deprecated `nativePicker`), Field props, size, status, and the input-family part props.                                                                                                                                                                                                                                                                                                                                                                                                |
-| Behavior                | `presentation` picks the surface: a typed field, the browser time picker, or bottom-sheet wheels, each committing ISO times inside the range through `onChange` and an optional `changeAction`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| End-user impact         | Desktop users type times in many forms and step with arrows; touch users get the OS picker by default. Keyboard and screen-reader users can reach a disabled field and hear invalid entries and stepped times.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| Builder impact          | A caller that relied on the `12h` default under a 24-hour locale passes `hourFormat="12h"` to keep twelve-hour text. A per-user 12/24-hour preference goes on the provider locale as a `-u-hc-` extension (`en-US-u-hc-h23`) rather than on each field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| Compatibility/readiness | The `hourFormat` default is the provider locale's hour cycle, which is `12h` for `en`/`en-US` and with no provider; every other released default, API, and DOM shape holds. Caller handlers other than focus, blur, and click still run while disabled, the clear and Save buttons scale under reduced motion, the grouped sheet field is unnamed by its own label, stepping a draft shows stale text, a focused clear button drops focus when disabled, the sheet surface is pointer-only, the sheet and native surfaces drop focus on clear, the format hint outlasts a disable, the grouped tooltip status describes nothing, the sheet's hour, minute, and second wheels use ASCII digits, and typed parsing commits prefixes; all are listed under Current-state impact. |
-| Review checks           | Reject a surface other than the one `presentation` names, a commit outside `min`/`max`, an Action skipped by clear, a disabled field that leaves the tab order or changes value, or `nativePicker` winning over `presentation`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Governing rules         | `spec:AST-043` FR1–FR4; `family:input-fields` FR3–FR6, FR8–FR11; `spec:AST-085` FR1, FR2, FR4, FR6; `spec:AST-086` FR3, FR4, FR8; `architecture:internationalization` INV1a, INV8; `design:reduced-motion` DR1; `architecture:interaction-modality` INV4.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-TimeInput collects one time of day as an ISO string. It owns time parsing,
-range checks, arrow-key stepping, the choice among typed, native, and sheet
-surfaces under `spec:AST-043`, and its adaptation to Field and InputGroup
-under `family:input-fields`. Consumer usage lives in `TimeInput.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `no` for `hourFormat`, which follows the
-  provider locale's hour cycle (`12h` for `en` and `en-US`, the released
-  default with no provider); `yes` for `presentation="adaptive-native"`,
-  `increment={1}`, no seconds, no clear, `size="md"`, `statusVariant="attached"`
-- Compatibility class: default change for non-English-US locales; no public
-  prop, type, export, or DOM change
-- Controlled/uncontrolled behavior: controlled; `value` is an ISO time or
-  `undefined`, and the field shows an optimistic value only while a
-  `changeAction` is pending
-- Migration decision: `nativePicker` stays as the deprecated mapping in
-  `spec:AST-043` FR3
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- Surface selection and its fallbacks.
-- The typed field: parsing, draft, commit, invalid-entry announcement, and
-  arrow-key stepping with its announcement.
-- The native time control's integration and the bottom-sheet time wheels.
-- The change and Action pipeline, busy state, and clear.
-- Disabled and disabled-reason behavior; the `time-input` target; its grouped
-  adaptation.
-
-**Does not own / non-goals**
-
-- Label, description, status message placement, label tooltip, and `width` —
-  owned by Field under `family:input-fields` (shared owner section).
-- The browser time picker's own interface — owned by the platform.
-- BottomSheet and wheel mechanics — owned by `component:BottomSheet` and the
-  shared wheel used by the date and time inputs.
-- Combined date and time — owned by DateTimeInput.
-- Read-only — not provided.
-
-## Public concepts
-
-| Concept       | Closed values or states                                                                       | Meaning                              | Availability by variant/orientation/state                                                                                              | Default                                                                     | Owner                 | Stability  | Invalid-value behavior                                                                                                                       |
-| ------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| Presentation  | `text-input`, `popover`, `bottom-sheet`, `native`, `adaptive-bottom-sheet`, `adaptive-native` | Which surface selects the time.      | Always.                                                                                                                                | `adaptive-native`                                                           | `spec:AST-043`        | Stable     | TypeScript rejects other values.                                                                                                             |
-| Native picker | `touch`, `always`, `never` (deprecated)                                                       | Released surface selector.           | Ignored when `presentation` is set.                                                                                                    | unset                                                                       | `spec:AST-043`        | Deprecated | A development warning names the replacement.                                                                                                 |
-| Hour format   | `12h`, `24h`                                                                                  | Display and wheel hour format.       | Typed, native (resting text), and sheet surfaces.                                                                                      | The provider locale's hour cycle, including a `-u-hc-` extension on its tag | `component:TimeInput` | Stable     | TypeScript rejects other values.                                                                                                             |
-| Seconds       | off, on                                                                                       | Whether values carry seconds.        | Typed and sheet surfaces; keeps adaptive and legacy native off. A forced native surface ignores it and commits hours and minutes only. | off                                                                         | `component:TimeInput` | Stable     | Not applicable.                                                                                                                              |
-| Increment     | whole minutes                                                                                 | Arrow-key step.                      | Typed surface; not 1 keeps adaptive and legacy native off.                                                                             | `1`                                                                         | `component:TimeInput` | Stable     | A fractional increment steps by nothing: an arrow key re-commits and announces `value`, or commits the current time when the field is empty. |
-| Range         | `min`, `max` ISO times                                                                        | Inclusive allowed times.             | Every surface.                                                                                                                         | unbounded                                                                   | `component:TimeInput` | Stable     | Out-of-range entries do not commit.                                                                                                          |
-| Busy          | idle, busy                                                                                    | The value is loading or being saved. | `isLoading`, or while a `changeAction` is pending.                                                                                     | idle                                                                        | `family:input-fields` | Stable     | Not applicable.                                                                                                                              |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Basis                                                                                    |
-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| FR1  | Surface by `presentation` and pointer: `text-input` and `popover` → typed field; `bottom-sheet` → sheet; `native` → native picker on every pointer with no fallback; `adaptive-bottom-sheet` → typed on a fine pointer, sheet on a coarse one; `adaptive-native` → typed on a fine pointer, native on a coarse one, falling back to the typed field when `hasSeconds` or `increment` is not 1. Deprecated `nativePicker` maps `touch` → `adaptive-native`, `always` → native with the same fallbacks, `never` → `text-input`; `presentation` wins when both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `spec:AST-043` FR1–FR4; current tests                                                    |
-| FR2  | Every surface reports changes as `onChange(isoTime \| undefined)` and then, when supplied, `changeAction` in a transition; while the Action is pending the field shows the proposed value; while `isLoading` or while the shown value differs from `value`, it sets `aria-busy`, shows a decorative Spinner, and announces the busy start once; once the Action settles the field shows `value`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `family:input-fields` FR5, FR6; `spec:AST-086` FR8; current source                       |
-| FR3  | Typed field: a native text input with a leading clock icon. Typing keeps a draft and commits as soon as the draft parses to an in-range time different from `value`. On blur an empty draft commits `undefined` (when a value exists), a valid draft commits if changed, and an invalid draft reverts. An invalid draft sets `aria-invalid` and fills a persistent assertive region with the localized invalid-time message. Typed times MUST parse in the active locale, and a commit MUST reflect the whole typed time (`architecture:internationalization` INV8). The parser reads the locale's digits, hour-minute and minute-second separators, and day-period words on either side of the time, plus English day periods, `:`, and ASCII digits in every locale, so every time FR5 displays reads back as itself. Implementation gap: it commits as soon as a prefix parses: typing "2.30pm" under `en` commits 02:00 from "2" and keeps it on blur.                                                                                                                                                                                                                                      | `spec:AST-086` FR3; current tests; `architecture:internationalization` INV8              |
-| FR4  | Typed field: ArrowUp and ArrowDown step by `increment` minutes from `value`, or from the current time when empty, commit only when the result is in range, and announce the new time politely (in FR5's display text for the field's hour format). Arrow keys that belong to an IME composition do nothing. The shown text MUST match the committed and announced time. Implementation gap: stepping while a typed draft is pending commits and announces the stepped time but keeps showing the draft, and blur then commits the draft when it parses.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current tests                                                                            |
-| FR5  | Typed field: the value shows as 12-hour or 24-hour text, with seconds when `hasSeconds`. The hour format is `hourFormat` when set, else the provider locale's hour cycle (`h11`/`h12` → 12-hour, `h23`/`h24` → 24-hour), so a `-u-hc-` extension on the provider tag carries an app's per-user preference. Every surface receives the same resolved hour format. While focused, enabled, and empty, the placeholder becomes the catalog format hint for that hour format; otherwise it is `placeholder` or the localized default. Implementation gap: a field that becomes disabled while focused keeps showing the hint until blur. On every surface, time text MUST use the locale's digits, separator, and (for twelve-hour text) day-period words (`architecture:internationalization` INV1a, INV8): the typed, native resting, and sheet field text and the stepped announcement come from the shared time formatter. A locale whose twelve-hour reading writes 02:00 and 14:00 alike (no day period) gets English twelve-hour text. Implementation gap: the sheet's hour, minute, and second wheel options use ASCII digits; the sheet's AM/PM wheel uses the catalog's day-period words. | `architecture:internationalization`; current tests                                       |
-| FR6  | Native surface: an `<input type="time">` the platform picks with, plus a clock button labelled with the localized open-picker phrase. Native edits outside `min`/`max` do not commit; they set `aria-invalid` and fill the assertive invalid-time region. A pending Action keeps the picker enabled. Clearing does not refocus or reopen the picker.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `spec:AST-043` FR2; current tests                                                        |
-| FR7  | Sheet surface: a read-only combobox (`aria-haspopup="dialog"`, `aria-expanded`) that opens a BottomSheet of hour, minute, optional second, and (12-hour) meridiem wheels when tapped. Wheel options outside the range are disabled; each wheel change clamps to the range and commits. `isLoading` makes the sheet field inert as well as busy. The wheels MUST be reachable by keyboard (`architecture:interaction-modality` INV4). Implementation gap: Enter, Space, ArrowDown, and Alt+ArrowDown do not open the sheet, and the clock button is out of the tab order, so keyboard users cannot set a time on this surface.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `spec:AST-043` DEC-3; current source and tests; `architecture:interaction-modality` INV4 |
-| FR8  | With `hasClear`, a clear button shows while a value is shown and the field is editable. It commits `undefined` through FR2's pipeline, including `changeAction`. On the typed surface it then focuses the input (keyboard: at once; pointer: on the next frame without scrolling). Implementation gap: on the sheet surface, and on the native surface (which does not refocus so the picker does not reopen), it moves focus nowhere, so a keyboard clear leaves focus on the document body. The clear button, and the sheet's Save button, are `component:Button`s, so their press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: both still scale under reduced motion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `family:input-fields` FR6, FR11; current tests                                           |
-| FR9  | TimeInput 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, on every surface: `aria-disabled="true"` on the focusable control, a kept tab stop, no value change by typing, arrows, the picker, or the wheels, a dropped draft, no caller `onClick`, 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 control. Implementation gap: caller DOM handlers other than focus and blur (`onKeyDown` and the like) still run; only `onClick` is blocked. Implementation gap: when a focused clear button disappears because the field becomes disabled, focus falls to the document body; no destination is named (`spec:AST-085` FR4).                                                                                                                                                                                                                                                                                      | `spec:AST-085` FR1, FR2, FR6; `family:input-fields` FR4; current tests                   |
-| FR10 | Inside InputGroup there is no Field. On the typed and native surfaces, a visually hidden label, description, and status message inside the control name and describe it, the local status icon is suppressed, and a status message is announced through the shared channel (assertive for errors, polite otherwise) when it appears. The sheet surface MUST be named and described the same way. Implementation gap: the grouped sheet field renders no hidden label, description, or status node, so it is named only by the group label, its description and status ids resolve to nothing, and its own status message is not announced (the group's status still describes it). Implementation gap: with `statusVariant="tooltip"`, the grouped typed and native fields render the hidden status message but leave it out of `aria-describedby`, so it is announced once and never describes the control.                                                                                                                                                                                                                                                                                    | `family:input-fields` FR3; `spec:AST-086`; current tests                                 |
-| FR11 | Base props reach the semantic control; a caller DOM handler runs after the component's own handler for the same event and cannot cancel built-in behavior. A caller `aria-labelledby` is appended to the field label. `container*` and `control*` reach the Field box and control box; root styling is not accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `family:input-fields` FR10; current tests                                                |
-| FR12 | Size and text size (typed and native surfaces; the sheet field sets no font of its own), status presentation, and click-to-focus (typed surface) match `component:TextInput` FR9, FR11, and FR12, including its implementation gaps (the fixed height against `spec:AST-102` FR4, an error status without text, and the color-only `detached` status without a message). The control box carries `astryx-time-input` with `data-size`, `data-status`, and `data-disabled`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `family:input-fields` FR8, FR9; current tests                                            |
-
-### Allowed variation
-
-- **AV1 — Native picker interface.** The platform decides how its picker looks
-  and steps.
-- **AV2 — Accepted typed forms.** The shared time parser decides which typed
-  spellings parse. A parse MUST commit the time the person typed, never a
-  different one (FR3 gap: prefix commits).
-
-### Representative states
-
-| State                        | Required invariant                                               | Allowed variation |
-| ---------------------------- | ---------------------------------------------------------------- | ----------------- |
-| Fine pointer, default        | Typed field with clock icon.                                     | Hour format.      |
-| Coarse pointer, default      | Native time picker, unless seconds or a non-1 increment.         | Platform UI.      |
-| Forced `native` with seconds | Native picker anyway.                                            | —                 |
-| `bottom-sheet`               | Combobox opening wheels; out-of-range options disabled.          | —                 |
-| Invalid typed draft          | `aria-invalid`; assertive invalid-time message; reverts on blur. | —                 |
-| Disabled with reason         | Focusable; no change on any surface; reason tooltip.             | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Surface.** `presentation`, else `nativePicker`'s mapping, else
-  `adaptive-native`; then pointer; then the adaptive and legacy native
-  fallbacks.
-- **ORD2 — Change.** `onChange`, then the optimistic value and `changeAction`.
-- **ORD3 — Sheet wheel.** Compose the time from the wheels → clamp to range →
-  commit if changed.
-
-### Performance and resources
-
-- **PR1 — Pointer query.** One coarse-pointer media query per instance decides
-  the surface (the native surface's segment adds its own); the typed field adds
-  no measurement.
-
-## Accessibility contract
-
-- **AR1 — Name and description.** Standalone, the control is named by the
-  Field label (plus any caller `aria-labelledby`) and described by description,
-  status message or status tooltip, disabled reason, and caller description.
-  Inside InputGroup it is named and described per FR10, including its gaps for
-  the sheet surface and the tooltip status variant.
-- **AR2 — Announcements.** Invalid typed drafts and out-of-range native edits
-  announce assertively (FR3, FR6);
-  stepped times announce politely (FR4); grouped status messages on the typed
-  and native surfaces announce through the channel (FR10; the sheet surface is
-  a gap).
-- **AR3 — Disabled.** FR9 satisfies `spec:AST-085` FR1 and FR6 on every
-  surface; the FR2 gap is noted there.
-- **AR4 — Sheet semantics.** The sheet field is a read-only combobox that
-  reports its open state and opens a dialog. Implementation gap: it opens only
-  by pointer (FR7).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                     | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
-| Clock icon       | Leading icon; the native surface's open-picker button. | Current source           | Supporting     | FR3, FR6           |
-| Time control     | Typed text, native time input, or sheet combobox.      | Current source and tests | Prominent      | FR1                |
-| Wheels           | Hour, minute, second, meridiem wheels in the sheet.    | Current source           | Prominent      | FR7                |
-
-`design:reduced-motion` governs the clear and Save buttons' press scale (FR8);
-no other design record governs TimeInput. The control box carries `time-input`; the
-consumer anatomy names no control-box part, so this record carries no
-anatomy-theming map.
-
-## Family and system relationships
-
-- `spec:AST-043` owns the presentation values, fallbacks, deprecated mapping,
-  and precedence; TimeInput implements them, including the sheet DEC-3
-  approves.
-- `family:input-fields` owns grouped admission, disabled reasons, busy,
-  Transition Actions, status placement, prop targets, and the clear tooltip.
-- `spec:AST-085` owns disabled focusability; FR9 records the handler gap.
-- `spec:AST-086` owns the persistent invalid-entry region and busy
-  announcement.
-- DateTimeInput shares the native time control and the wheel behavior.
-
-## Verification map
-
-| Contract       | Verification                                                                                                                                                  | Representative states                                      | Mutation or failure expectation                                                                                                                                                                                                                           | Audit section                   |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, ORD1      | `Presentation.test.tsx`; `NativeTimeInput.test.tsx` mode cases                                                                                                | Each value × pointer; deprecated mapping; both props       | A substituted surface, a lost fallback, or `nativePicker` winning fails. Evidence gap: no real-browser check of the surface per pointer, as `spec:AST-043` asks. No test covers `presentation="popover"`.                                                 | `audit:TimeInput/behavior`      |
-| FR3–FR5, AR2   | `TimeInput.test.tsx` typing, blur, invalid, stepping, IME, and format cases, including "shows the catalog format hint for the resolved hour format" (24-hour) | 12h, 24h, seconds; invalid and out of range                | A commit of an invalid time, a missing alert, or a step during IME fails. Evidence gap: no test asserts the 12-hour format hint, stepping from the current time when empty, or a step that would leave the range. No test steps while a draft is pending. | `audit:TimeInput/behavior`      |
-| FR6            | `NativeTimeInput.test.tsx`                                                                                                                                    | Coarse default; range; pending Action; clear; clock button | An out-of-range native commit, or a reopened picker after clear, fails.                                                                                                                                                                                   | `audit:TimeInput/behavior`      |
-| FR7, ORD3, AR4 | `Presentation.test.tsx` sheet cases                                                                                                                           | Forced and adaptive sheet; disabled                        | A sheet field that is not inert while disabled fails. Evidence gap: no test opens the sheet by keyboard or asserts the clock button's tab order. No test disables an out-of-range wheel option or clamps a wheel change.                                  | `audit:TimeInput/behavior`      |
-| FR8            | `TimeInput.test.tsx` clear cases; `NativeTimeInput.test.tsx` clear case                                                                                       | With value; empty                                          | A clear on an empty field, or no `undefined`, fails. Evidence gap: no test asserts the focus move after clear on either surface, `changeAction` on clear, or a clear or Save press under reduced motion.                                                  | `audit:TimeInput/behavior`      |
-| FR9, AR3       | `TimeInput.test.tsx` disabled suites; `NativeTimeInput.test.tsx` and `Presentation.test.tsx` disabled cases; `InputGroup.test.tsx` disabled-propagation cases | Each surface; with reason; draft in progress               | A lost tab stop, a value change, or a caller `onClick` fails. Evidence gap: no test asserts that caller `onKeyDown` and similar handlers still run while disabled (the FR9 gap).                                                                          | `audit:TimeInput/accessibility` |
-| FR10           | `TimeInput.test.tsx` InputGroup suite                                                                                                                         | Grouped with description and status                        | A duplicate label, a visible status icon, or a missed announcement fails. Evidence gap: no test groups the sheet surface.                                                                                                                                 | `audit:TimeInput/accessibility` |
-| FR11           | `TimeInput.fr10.test.tsx`                                                                                                                                     | Each surface; handler composition                          | A base prop off the control, or a caller handler that cancels built-ins, fails.                                                                                                                                                                           | `audit:TimeInput/api`           |
-| FR12           | `TimeInput.test.tsx` status and theme-state cases                                                                                                             | Status; disabled                                           | A missing state attribute fails. Evidence gap: no test asserts `data-size` or `data-status`.                                                                                                                                                              | `audit:TimeInput/theming`       |
-| FR2, ORD2      | Evidence gap: no TimeInput test of the pending Action's optimistic value                                                                                      | —                                                          | —                                                                                                                                                                                                                                                         | `audit:TimeInput/behavior`      |
-| AR1, PR1       | Covered by the FR10 and FR11 rows for naming. Evidence gap: no test asserts the single coarse-pointer query that decides the surface                          | —                                                          | —                                                                                                                                                                                                                                                         | `audit:TimeInput/behavior`      |
-
-## Current-state impact
-
-- **Sheet keyboard access (FR7, AR4).** The sheet surface opens only by tap or
-  click, and its clock button is out of the tab order, so keyboard users cannot
-  set a time there, against `architecture:interaction-modality` INV4.
-- **Sheet and native clear focus (FR8).** Clearing on the sheet or native
-  surface leaves keyboard focus on the document body.
-- **Grouped sheet field (FR10).** Inside InputGroup the sheet field is named only
-  by the group label, references missing description and status ids, and does
-  not announce its own status message.
-- **Stepping a draft (FR4).** Stepping while a typed draft is pending announces
-  a time the field does not show, and blur then commits the draft when it
-  parses.
-- **Clear button focus (FR9).** A focused clear button that disappears when the
-  field becomes disabled drops focus to the page, against `spec:AST-085` FR4.
-- **Button press under reduced motion (FR8).** The clear button and the sheet's
-  Save button scale to 0.98 on a press when the person prefers reduced motion,
-  as `component:Button` FR15 records, against `design:reduced-motion` DR1.
-- **Caller handlers while disabled (FR9).** A disabled TimeInput still runs a
-  caller's DOM handlers other than focus and blur, such as `onKeyDown`, and
-  blocks only `onClick`, against `spec:AST-085` FR2.
-- **Format hint (FR5).** The focused-empty format hint stays shown until blur
-  when a focused field becomes disabled.
-- **Typed parsing (FR3, AV2).** The typed field commits a parsed prefix, so a
-  typed time can commit a different time, against
-  `architecture:internationalization` INV8.
-- **Wheel digits (FR5).** The sheet's hour, minute, and second wheels use ASCII
-  digits in every locale, against `architecture:internationalization` INV1a
-  and INV8.
-- **Grouped tooltip status (FR10).** Inside InputGroup with
-  `statusVariant="tooltip"`, the typed and native fields never reference the
-  hidden status message from `aria-describedby`.
-- **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), and the color-only `detached` status without a message (WCAG 2.2
-  1.4.1) that `component:TextInput` records apply here.
-- **Source comment.** The `size` JSDoc in `TimeInput.tsx` gives 18 px and 26 px
-  heights; the shipped heights come from the shared element sizes.
-
-## Decision log
-
-No component-local decision. TimeInput applies `spec:AST-043`,
-`family:input-fields`, and `spec:AST-085`.
-
-## 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.