@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/ButtonGroup/ButtonGroup.spec.md

@@ -1,220 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:ButtonGroup
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-25
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/ButtonGroup/ButtonGroup.test.tsx,
-    packages/core/src/Layer/layerScopedContext.test.tsx,
-    packages/core/src/hooks/useListFocus.test.tsx,
-  ]
-modules: []
-families: [family:buttons]
-design_specs: []
-architecture:
-  [
-    architecture:component-size-cascade,
-    architecture:component-theming-surface,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-038, spec:AST-085]
----
-
-# ButtonGroup component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                      |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. ButtonGroup takes `label`, `orientation`, `size`, `elevation`, `isDisabled`, and Button or IconButton children.                                                                                                                 |
-| Behavior                | A labelled `role="group"` that joins its Button members into one connected surface, gives them a default size and its disabled state, owns one shared elevation, and is one Tab stop with arrow-key roving.                                   |
-| End-user impact         | Keyboard users reach the whole group with one Tab and move through it with arrows, which skip disabled members. A disabled group without tooltips has no Tab stop, so keyboard users cannot find it or hear that it is disabled.              |
-| Builder impact          | None.                                                                                                                                                                                                                                         |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Disabled members use native `disabled`, the Tab stop leaves disabled and busy-only members, and wrapped members lose connected geometry; all are listed under Current-state impact. |
-| Review checks           | Reject a group without a name, gaps between members, rounded inner corners, a shadow on a member, more than one Tab stop, arrows that land on a disabled member, or arrows that steal keys from a member's open menu.                         |
-| Governing rules         | `family:buttons` FR3, FR8, FR10–FR12, AV5; `architecture:component-size-cascade` INV3–INV8; `spec:AST-085` FR1, FR7; `spec:AST-038` FR7, FR8.                                                                                                 |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-ButtonGroup presents a few related actions as one connected control. It owns
-the group's accessible name, connected geometry, shared elevation, inherited
-size and disabled state, and the group's single-Tab-stop keyboard model, as
-`family:buttons` assigns. Consumer usage lives in `ButtonGroup.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`; `orientation="horizontal"`, `size="md"`,
-  `elevation="none"`, `isDisabled={false}`
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The group root: role, accessible name, orientation and disabled exposure, and
-  the `button-group` target.
-- Connected geometry its Button members paint: outer-only corners, leading-edge
-  dividers, and no press scale.
-- One shared resting elevation, and flat members.
-- The default size and disabled state it gives its members.
-- Roving focus: one Tab stop, arrow keys, Home and End.
-
-**Does not own / non-goals**
-
-- Each member's own surface, naming, activation, pending, and disabled rendering
-  — owned by `component:Button` and `component:IconButton`. A press that slides across
-  members acts on the lifted member, as `family:action-groups` owns.
-- A member's menu or other layer, and keys pressed inside it — owned by that
-  member (for example `component:DropdownMenu`).
-- Selection state across toggles — owned by `component:ToggleButtonGroup`.
-- Horizontal overflow — uncontracted; the group does not wrap or collapse.
-- Nested ButtonGroups — unsupported; behavior is uncontracted.
-
-## Public concepts
-
-| Concept     | Closed values or states      | Meaning                                   | Availability by variant/orientation/state | Default                   | Owner                   | Stability | Invalid-value behavior           |
-| ----------- | ---------------------------- | ----------------------------------------- | ----------------------------------------- | ------------------------- | ----------------------- | --------- | -------------------------------- |
-| Orientation | `horizontal`, `vertical`     | Direction of the row and of arrow keys.   | Always.                                   | `horizontal`              | `component:ButtonGroup` | Stable    | TypeScript rejects other values. |
-| Size        | `sm`, `md`, `lg`             | Default size for members.                 | Always; a member's own `size` wins.       | Inherited size, else `md` | `family:buttons`        | Stable    | TypeScript rejects other values. |
-| Elevation   | `none`, `low`, `med`, `high` | Shadow under the whole connected surface. | Always; members paint none.               | `none`                    | `family:buttons`        | Stable    | TypeScript rejects other values. |
-| Disabled    | off, on                      | Every Button member is disabled.          | Always.                                   | off                       | `component:ButtonGroup` | Stable    | Not applicable.                  |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                                               |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| FR1  | The root is one element with `role="group"` and `aria-label` set to `label`. It reflects orientation as `data-orientation`, never `aria-orientation`, and sets `aria-disabled="true"` only while disabled. `ref`, `data-testid`, `className`, `style`, `xstyle`, and other DOM props reach it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `family:buttons` FR11; current source and tests                                     |
-| FR2  | Members sit edge to edge with no gap, stretched across the cross axis: a row when horizontal, a column when vertical.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `family:buttons` FR12; current source                                               |
-| FR3  | Group geometry is painted by Astryx Button members; other children keep their own paint. Only the group's outer corners are rounded: the first member's leading corners and the last member's trailing corners. A trailing layer element a member renders after itself (popover, template, or dialog) does not count as a member, so the real last member keeps its rounded corners. Any other following element, including a display-contents wrapper or a raw button, counts as a member. A Button member wrapped in a Tooltip or HoverCard MUST join the connected surface like a direct member (`family:buttons` FR12). Implementation gap: inside that display-contents wrapper the Button is both the first and the last child, so in a group of two or more it keeps all four corners rounded wherever it sits, and draws no divider when it is not first.                                                                                        | `family:buttons` FR12; current tests                                                |
-| FR4  | Every Button member after the first draws a divider on its leading edge (inline-start when horizontal, block-start when vertical) in the border color, or in the on-accent color on a primary or destructive member; a wrapped member does not (FR3 gap). Members do not take Button's press scale.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `family:buttons` FR12; current source                                               |
-| FR5  | The group paints the shadow for its `elevation`, following the element radius. Every Button member paints no shadow and reflects `data-elevation="none"`, whatever its own `elevation` says.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `family:buttons` FR8, FR10; current tests                                           |
-| FR6  | The group provides its resolved size to descendants up to the next layer boundary (`spec:AST-038` FR7, FR8): an explicit `size`, then the nearest outer provider, then `md`. A member's own `size` wins.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `architecture:component-size-cascade` INV3–INV8; current source; `spec:AST-038` FR7 |
-| FR7  | While disabled, every Button member MUST be disabled under `component:Button` FR10: focusable with `aria-disabled`, inert, and never running its action, so the group keeps its Tab stop (`spec:AST-085` FR1, FR7). Implementation gap: members without a tooltip render native `disabled`, so a disabled group contributes no Tab stop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `family:buttons` FR3; `spec:AST-085` FR7; current tests                             |
-| FR8  | The group is one Tab stop. The stop starts on the first enabled member and moves with arrow navigation. A link member counts as a member. The stop MUST always sit on exactly one member, and a member that becomes busy or disabled MUST keep it (`component:Button` FR9, FR10; `spec:AST-085` FR1, FR7). Implementation gap: the group repairs the stop only after its own renders and when focus enters a member, and each repair keeps an enabled holder or gives the stop to the first enabled member. Between repairs the stop can sit on a member that has become busy-only, disabled, or unmounted, so the group can have a second stop or none; focus that arrives by pointer or by code does not take the stop, so the next Tab or Shift+Tab can stop inside the group; and a fully disabled group repairs nothing, so a group disabled from its first render gives each tooltip-bearing member its own stop and native-disabled members none. | `family:buttons` AV5; WAI-ARIA APG roving tabindex; current tests                   |
-| FR9  | Horizontal groups move with Left and Right in visual order, reversed under RTL; vertical groups move with Up and Down. Home and End jump to the first and last enabled member. Movement wraps at the ends and skips natively disabled and `aria-disabled` members, busy-only members (`component:Button` FR9) included; a member busy with an interruptible action stays in the order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `family:buttons` AV5; current tests                                                 |
-| FR10 | Keys pressed inside a member's open layer (such as a DropdownMenu) belong to that layer, and the group keeps its Tab stop on its own members. A group inside a popover or other layer still handles its own arrow keys. The group's context does not reach Buttons rendered inside a member's layer (`spec:AST-038` FR7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source and tests; `spec:AST-038` FR7                                        |
-| FR11 | The root carries `astryx-button-group` and reflects `data-size`, `data-orientation`, and `data-elevation`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `family:buttons` FR10; `architecture:component-theming-surface`; tests              |
-
-### Allowed variation
-
-- **AV1 — Members.** Button, IconButton, and a Button-triggered DropdownMenu are
-  supported members; variants may differ between members.
-- **AV2 — Theme paint.** Themes may restyle the group and member surfaces
-  through `button-group` and `button` without changing connected geometry.
-
-### Representative states
-
-| State                 | Required invariant                                                                                                                                                                                                                | Allowed variation       |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| Horizontal, at rest   | Named group; one Tab stop on the first member; outer corners only.                                                                                                                                                                | Member variants.        |
-| Vertical              | Column; Up and Down move focus; block-start dividers.                                                                                                                                                                             | —                       |
-| Elevated              | Shadow on the group; members flat.                                                                                                                                                                                                | Tier.                   |
-| Trailing DropdownMenu | The menu trigger keeps rounded trailing corners; arrows inside the open menu stay with it.                                                                                                                                        | Menu content.           |
-| One member disabled   | Arrows skip it. Implementation gap: the Tab stop leaves it when the group repairs (FR8).                                                                                                                                          | Tooltip present or not. |
-| Group disabled        | `aria-disabled` on the group; every member focusable and inert; one Tab stop. Implementation gap: native-disabled members give no Tab stop; disabled from the first render, tooltip-bearing members are one stop each (FR7, FR8). | —                       |
-
-### Transformation and precedence order
-
-- **ORD1 — Member size.** Member `size`, then the group's resolved size.
-- **ORD2 — Member elevation.** Inside a group, always `none`; the group's
-  `elevation` paints.
-- **ORD3 — Member availability.** A member is disabled when the group or the
-  member is disabled; neither can re-enable the other. Otherwise Button's own
-  availability rules apply.
-
-### Performance and resources
-
-- **PR1 — Tab-stop repair.** The group repairs the Tab stop after each of its
-  own renders and when focus enters a member; it adds no global listener
-  beyond the press tracking `family:action-groups` FR5 gives it.
-
-## Accessibility contract
-
-- **AR1 — Group name.** The group exposes `role="group"` and its `label` as
-  its accessible name; members keep their own names (`family:buttons` FR11).
-- **AR2 — Keyboard.** FR8–FR10 are the keyboard contract.
-- **AR3 — Disabled exposure.** A disabled group exposes `aria-disabled` on the
-  group; members expose disabled per `component:Button` AR5 (FR7 gap).
-- **AR4 — Focus indicator.** Each member paints Button's focus indicator.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                    | Representation authority | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Button           | Members joined into one surface with outer-only corners.              | Current source and tests | Prominent      | FR2, FR3           |
-| Divider          | Thin leading-edge border between members; on-accent on solid members. | Current source           | Supporting     | FR4                |
-| Group shadow     | One shadow under the connected surface.                               | Current source and tests | Supporting     | FR5                |
-
-No design record governs ButtonGroup. The root carries the `button-group`
-target; the Button and Divider anatomy parts are painted by each member's
-`button` target. The consumer anatomy names no root part, so this record
-carries no anatomy-theming map.
-
-## Family and system relationships
-
-- `family:buttons` assigns ButtonGroup connected geometry, roving focus,
-  inherited size and disabled state, and one shared elevation (FR8, FR11,
-  FR12); ButtonGroup adopts them.
-- `component:Button` paints the connected geometry from the group's context
-  and owns each member's behavior.
-- `architecture:component-size-cascade` owns size inheritance (FR6).
-- `spec:AST-085` FR7 applies to group disablement; the gap is FR7 here.
-
-## Verification map
-
-| Contract             | Verification                                                                                                                                                                                                                                                                                       | Representative states                                               | Mutation or failure expectation                                                                                                                                                                                                                                               | Audit section                     |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| FR1, AR1             | `ButtonGroup.test.tsx` role, label, ref, `data-testid`, orientation                                                                                                                                                                                                                                | Horizontal and vertical                                             | A missing name, `aria-orientation`, a dropped ref, or a dropped `data-testid` fails. Evidence gap: no test passes `className`, `style`, or `xstyle`.                                                                                                                          | `audit:ButtonGroup/accessibility` |
-| FR3                  | `ButtonGroup.test.tsx` trailing-radius suite                                                                                                                                                                                                                                                       | Tooltip, link, DropdownMenu, HoverCard, and raw-button members      | A square trailing member, or a rounded inner member, fails. Evidence gap: the suite renders wrapped members only last and asserts the member before them; no test checks a wrapped member's own corners or divider in any position.                                           | `audit:ButtonGroup/layout`        |
-| FR5, FR11            | `ButtonGroup.test.tsx` elevation suite                                                                                                                                                                                                                                                             | Every tier; member with its own elevation                           | Identical classes for two tiers, a mismatched `data-elevation`, or a member not reporting `none` fails.                                                                                                                                                                       | `audit:ButtonGroup/theming`       |
-| FR11 (target, size)  | Evidence gap: no test asserts `astryx-button-group` or `data-size` on the root                                                                                                                                                                                                                     | Each size                                                           | —                                                                                                                                                                                                                                                                             | `audit:ButtonGroup/theming`       |
-| FR7, AR3             | `ButtonGroup.test.tsx` disabled cases                                                                                                                                                                                                                                                              | Group disabled                                                      | An operable member fails. Native-disabled and no-Tab-stop assertions match the FR7 gap.                                                                                                                                                                                       | `audit:ButtonGroup/accessibility` |
-| FR8, AR2             | `ButtonGroup.test.tsx` roving-tabindex suite                                                                                                                                                                                                                                                       | Enter and leave; disabled member; unmount; becomes disabled; link   | Two Tab stops or a lost stop fails. The suite asserts that a disabled member never holds the stop and that the stop is repaired away from it, matching the FR8 gap. Evidence gap: no test of a busy or self-unmounted holder, pointer focus, or a group disabled after mount. | `audit:ButtonGroup/accessibility` |
-| FR9, FR10, AR2       | `ButtonGroup.test.tsx` keyboard-navigation suite; `useListFocus.test.tsx` "useListFocus disabled-item skipping" for `aria-disabled` items and Home and End; `layerScopedContext.test.tsx` "ends group-owned disabled state while preserving explicit and inner-group state" for the layer boundary | Arrows, Home, End, vertical, RTL, open menu, group inside a popover | Wrong direction, no wrap, landing on a disabled member, stealing a menu's keys, or group state leaking into a member's layer fails. Evidence gap: no test skips a busy or tooltip-disabled Button member.                                                                     | `audit:ButtonGroup/accessibility` |
-| FR2, FR3, FR4, FR6   | Evidence gap: no assertion of gap-free layout, divider paint, the absent press scale, non-Button children keeping their own paint, or member size inheritance beyond rendering                                                                                                                     | —                                                                   | —                                                                                                                                                                                                                                                                             | `audit:ButtonGroup/layout`        |
-| ORD2                 | `ButtonGroup.test.tsx` elevation suite                                                                                                                                                                                                                                                             | Member with its own elevation                                       | A member not reporting `none` fails.                                                                                                                                                                                                                                          | `audit:ButtonGroup/theming`       |
-| ORD1, ORD3, PR1, AR4 | Evidence gap: no test asserts member size precedence, a member `isDisabled` inside an enabled group, when the Tab stop is repaired, or the member focus indicator                                                                                                                                  | —                                                                   | —                                                                                                                                                                                                                                                                             | `audit:ButtonGroup/behavior`      |
-
-## Current-state impact
-
-- **Disabled focusability (FR7, AR3).** A disabled group renders its members
-  with native `disabled`, so the group has no Tab stop, against `spec:AST-085`
-  FR1 and FR7 and `family:buttons` FR3. The group's tests assert that state.
-- **Tab stop (FR8).** The Tab stop leaves a disabled or busy-only member when the
-  group repairs it; between repairs the group can have a second stop or none,
-  including after a pointer click on a member or when the holder unmounts or
-  disables itself; and a group disabled from its first render gives each
-  tooltip-bearing member its own stop, against `spec:AST-085` FR1 and FR7.
-- **Wrapped members (FR3, FR4).** A Button wrapped in a Tooltip or HoverCard
-  keeps four rounded corners in any position, and no divider when it is not
-  first, against
-  `family:buttons` FR12.
-
-## Decision log
-
-No component-local decision. ButtonGroup applies `family:buttons`.
-
-## 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/Calendar/Calendar.spec.md

@@ -1,248 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Calendar
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility, theming]
-verified_by:
-  [
-    packages/core/src/Calendar/Calendar.test.tsx,
-    packages/core/src/hooks/useGridFocus.test.tsx,
-    packages/core/src/Calendar/__tests__/Calendar.a11y.test.tsx,
-    packages/core/src/Calendar/__tests__/Calendar.a11y.chromium.spec.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: [design:bidirectionality, design:reduced-motion]
-architecture:
-  [
-    architecture:internationalization,
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:react-component-runtime,
-  ]
-contributing: []
-system_specs: [spec:AST-020/FR15, spec:AST-085, spec:AST-102]
----
-
-# Calendar component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                             |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. `Calendar` and `CalendarProps` are exported from `@astryxdesign/core/Calendar`; `mode` selects a single date or a range, with `value`/`defaultValue`/`onChange`, bounds, constraints, span limits, focus date, and display options.                                                    |
-| Behavior                | One or two months render as day grids; a day is picked by pointer or keyboard; each month grid holds at most one roving Tab stop, which arrow, Home/End, and Page keys move, following the reading direction.                                                                                        |
-| End-user impact         | A keyboard or screen-reader user meets a named month grid, moves through it by day, week, and month, and hears each day's name, selection, today marker, and disabled state.                                                                                                                         |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                                |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The month buttons use native `disabled` at a bound and scale under reduced motion, day buttons hold a fixed size, day and week numbers use ASCII digits, and a key-moved Tab stop can go stale; all are listed under Current-state impact. |
-| Review checks           | Reject a day grid without `role="grid"` or a name, two days in one month holding a Tab stop, an arrow key that stops following the reading direction, or a selection or today state carried only by colour.                                                                                          |
-| Governing rules         | `architecture:public-component-api/INV1,INV5–INV8`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR15`; `spec:AST-085/FR1, FR4`; `spec:AST-102` FR4; `design:bidirectionality` DR6; `design:reduced-motion` DR1; `architecture:internationalization` INV8.                      |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Calendar lets a person pick a date or a date range by looking at whole months. It
-owns the month grid, its navigation, selection and range semantics, and the
-keyboard model that moves through days; date fields compose it.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
-- Controlled/uncontrolled behavior: `value` with `onChange` is controlled;
-  `defaultValue` starts internal state
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The month grid: its weekday column headers, week rows, day cells, outside days,
-  week numbers, and variable row count.
-- Month navigation, the focused day, and the keyboard model that moves it.
-- Single and range selection semantics, bounds, constraints, and span limits.
-
-**Does not own / non-goals**
-
-- The text field, popover, and bottom sheet that present a Calendar — owned by
-  DateInput and its siblings.
-- Time of day — owned by DateTimeInput.
-- `handleRef`, `onFocusDateChange`, the opening month inside the `min`/`max`
-  window, `weekStartsOn`, and `numberOfMonths` clamping — shipped and covered
-  by the consumer docs and tests, uncontracted here beyond FR1–FR7.
-
-## Public concepts
-
-| Concept     | Closed values or states                      | Meaning                                         | Availability by variant/orientation/state | Default                                                                                                         | Owner                | Stability | Invalid-value behavior       |
-| ----------- | -------------------------------------------- | ----------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------- | --------- | ---------------------------- |
-| `mode`      | `single`, `range`                            | Whether one date or a start–end pair is picked. | Always                                    | `single`                                                                                                        | `component:Calendar` | stable    | Type-rejected                |
-| Focused day | one visible day                              | The day whose button holds the grid's Tab stop. | Always                                    | selected day (`single`) or today when it is in that month and enabled, else the month's first enabled day (AR1) | `component:Calendar` | stable    | Clamped to the visible range |
-| Day state   | selected, in range, today, disabled, outside | What a day cell exposes and paints.             | Per cell                                  | none                                                                                                            | `component:Calendar` | stable    | Not applicable               |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                                                              |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| FR1 | Each rendered month is one `role="grid"` named for its month and year, with a `columnheader` per weekday (and, with week numbers, a named `columnheader` above the `rowheader` column) and one `row` per week. Month and year labels and day names come from the provider locale. Day and week numbers MUST use the locale's digits (`architecture:internationalization` INV8). Implementation gap: they render as ASCII digits in every locale.                                                                                                                                                                                                                         | shipped source and focused tests; `architecture:internationalization` INV8                         |
-| FR2 | At most one day button in each month's grid holds `tabIndex={0}`; every other day button in that grid is `-1`. Each day button is the shared `sm` element size (inside an `md`-sized cell) as a minimum that grows with a set text size (`spec:AST-102` FR4). Implementation gap: the day buttons hold a fixed size.                                                                                                                                                                                                                                                                                                                                                     | shipped `useGridFocus` behavior; `Calendar.test.tsx` single-Tab-stop assertion; `spec:AST-102` FR4 |
-| FR3 | A disabled day (outside bounds or rejected by a constraint) stays in the grid, stays focusable with `aria-disabled` and no native `disabled`, never holds the grid's Tab stop, and cannot be picked. Implementation gap: once a key move (arrow, Home, End, or Page key) has placed the Tab stop, it stays on that day when every day of the month becomes disabled (for example a range span cap in a two-month view).                                                                                                                                                                                                                                                  | `spec:AST-085` FR1, FR2; shipped source and focused tests                                          |
-| FR4 | In `range` mode the first pick starts the range and the second ends it, a second pick before the start swapping the two so the end never precedes the start; `minRangeSpan`/`maxRangeSpan` bound it. Escape, or picking the start day again when `minRangeSpan` is above 1, clears an in-progress range.                                                                                                                                                                                                                                                                                                                                                                 | shipped source and focused tests                                                                   |
-| FR5 | Moving the focused day across a month boundary navigates the visible month so the focused day stays visible, in one month or two; a borrowed adjacent-month day is exposed `aria-disabled` and cannot be picked; arrow keys, Home and End skip it, and a page never lands on it.                                                                                                                                                                                                                                                                                                                                                                                         | shipped source and focused tests                                                                   |
-| FR6 | The month header shows the month and year between Previous and Next month buttons (ghost, icon-only Buttons whose chevrons mirror under RTL), which carry `calendar-nav` with `data-nav` and `data-disabled`. A button whose direction would leave `min` or `max` MUST stay focusable with `aria-disabled`, change nothing, and keep focus (`spec:AST-085` FR1, FR4). Implementation gap: it is natively disabled, so a focused button that reaches the bound drops focus. The month buttons are `component:Button`s, so their press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: it still applies under reduced motion. | `spec:AST-085`; shipped source and focused tests; `design:reduced-motion` DR1                      |
-| FR7 | When the visible month changes, by the month buttons, a Page key, an arrow across a month edge, or the handle, the new month (both months in a two-month view) is announced politely; the first render and a pick that leaves the month in place announce nothing. In `range` mode the first pick announces the start and prompts for an end, the second announces the completed range in chronological order, and picking the start again when `minRangeSpan` is above 1 announces the cleared start; Escape clears an in-progress range without an announcement. Every announcement uses the provider locale.                                                          | shipped source and focused tests                                                                   |
-
-### Allowed variation
-
-- **AV1 — Month layout.** Row count, outside days, and week numbers may vary by
-  props without changing FR1–FR5.
-- **AV2 — Internal state.** The focused-day and selection state may be stored in
-  any private shape.
-
-### Representative states
-
-| State                  | Required invariant                                                                                                                                                                                                 | Allowed variation     |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
-| single, nothing picked | Today holds its month's Tab stop when it is enabled, otherwise the month's first enabled day does; no day is selected.                                                                                             | Month shown.          |
-| single, picked         | The selected day is exposed as selected and holds the Tab stop. Implementation gap: after a key move places the stop, a later pointer pick can leave it there, always when the picked day comes later in the grid. | Month shown.          |
-| range, in progress     | The start is selected; hovered days preview the range.                                                                                                                                                             | Pointer position.     |
-| two months             | Both grids are named; at most one Tab stop in each.                                                                                                                                                                | Which month is first. |
-| bounded                | Days outside `min`/`max` are disabled.                                                                                                                                                                             | Which days.           |
-
-### Transformation and precedence order
-
-- **ORD1 — Pick.** Disabled check → mode-specific selection update → `onChange`.
-- **ORD2 — Focus movement.** Key → reading-direction mapping → target day → month
-  navigation if needed → focus.
-
-### Performance and resources
-
-- **PR1 — Render-owned grid.** Day cells render from props and state; focus
-  movement reads the grid's cells on demand; day buttons share the press
-  controller's window and document listeners; Calendar owns no observer.
-
-## Accessibility contract
-
-- **AR1 — The day grid adopts the APG Grid pattern** (`spec:AST-020/FR15`), as
-  one composite control: each month is `role="grid"` with an accessible name,
-  weekday `columnheader` cells, week `row`s, and day `gridcell`s that carry
-  `aria-selected` when selected or in range and hold one `button` named by the
-  full date plus its selection or range role (selected, range start, range end,
-  or in range), which exposes `aria-current="date"` for today and `aria-disabled`
-  when disabled; one day button holds the Tab stop — the selected day in
-  `single` mode when it is in that month and enabled, else today when it is in
-  that month and enabled, else the month's first enabled day; a month with no
-  enabled day has no Tab stop. Implementation gap: once a key move (arrow, Home,
-  End, or Page key) has placed the stop, a later pointer pick can leave it
-  there (always when the picked day comes later in the grid), and when every
-  day of that month becomes disabled it stays on a disabled day.
-  ArrowLeft and ArrowRight move by a day following the reading direction
-  (`design:bidirectionality` DR6),
-  ArrowUp and ArrowDown by a week, Home and End to the first and last enabled day of the
-  week, PageUp and PageDown by a month, and Enter or Space picks the focused day;
-  an arrow skips a day disabled by a constraint and continues in the
-  same direction, crossing the month edge when it must; an arrow or Page key whose target
-  lies past `min` or `max` changes nothing and keeps focus where it is, and
-  so does an arrow whose direction has no enabled day within a year; a page
-  onto a day disabled by a constraint focuses that month's first enabled day
-  instead, and changes nothing when that month has no enabled day.
-
-## Design relationships
-
-`design:bidirectionality` DR6 governs the arrow-key direction (AR1), and
-`design:reduced-motion` governs the month buttons' press scale (FR6).
-
-| Anatomy or state | Design requirement                                                     | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ---------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Calendar root    | Holds the header and the grid; carries the component's theming target. | Current source and public docs | Supporting     | FR1                |
-| Month header     | Names the month and offers previous/next navigation.                   | Current source and public docs | Supporting     | FR1, FR5, FR6      |
-| Day button       | The control a date is picked with; carries the day target.             | Current source and public docs | Prominent      | FR2, FR3, AR1      |
-| Day grid         | Presents the weeks and days as a named grid.                           | Current source and public docs | Prominent      | FR1, FR2, AR1      |
-| Selected day     | Marks the chosen day or range without relying on colour alone.         | Current source and public docs | Prominent      | FR4, AR1           |
-| Today marker     | Marks today distinctly from selection.                                 | Current source and public docs | Supporting     | AR1                |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Calendar root": {"target": "calendar"},
-  "Month header": {"target": "calendar-nav"},
-  "Day grid": {
-    "none": {
-      "reason": "reachability-gap: No current public target reaches the grid element itself; `calendar` paints the root and `calendar-day` the day buttons."
-    }
-  },
-  "Day button": {"target": "calendar-day"},
-  "Selected day": {"inherits": "calendar-day"},
-  "Today marker": {"inherits": "calendar-day"}
-}
-```
-
-`calendar` is carried by the root element, `calendar-nav` by the previous and
-next month buttons inside the Month header, and `calendar-day` by each day
-button.
-
-## Family and system relationships
-
-- `spec:AST-020/FR15` decides which APG parts a component adopts; the day grid
-  adopts the Grid pattern because it already acts as one composite control.
-- `spec:AST-085` owns disabled focusability; days meet it and the month
-  buttons do not (FR6).
-- `component:Button` renders the month buttons.
-
-## Verification map
-
-| Contract        | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Representative states                                                                   | Mutation or failure expectation                                                                                                                                                                                                                               | Audit section                  |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1–FR5         | `Calendar.test.tsx` structure ("renders a valid APG grid: one grid, header row of columnheaders inside it, week rows of gridcells", "with week numbers, the header row's corner cell is a named columnheader, so every row child is a grid cell"), selection ("handles reverse range selection (end before start)", "caps the range highlight next to a disabled mid-range day (#2715)", "Escape cancels range selection in progress", "clears the in-progress start when the anchor is clicked again"), bounds ("prev button is disabled when focusDate month contains min", "next button is disabled when focusDate month contains max"), and navigation ("navigates to next month", "calls onFocusDateChange when navigating") suites                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | single, range, two months, bounded                                                      | A missing header row, a reverse pick that does not swap, a range highlight that reaches a disabled day, or a Previous/Next button enabled past `min`/`max` fails. Evidence gap: no test asserts locale digits for day or week numbers.                        | `audit:Calendar/behavior`      |
-| AR1             | `Calendar.test.tsx` ("has accessible grid structure", "sets aria-multiselectable on both grids in a two-month range view", "does not set aria-multiselectable in single mode", "announces the new month politely when clicking next", "displays day names") and `useGridFocus.test.tsx` ("ArrowDown moves the tab stop one row down", "flips ArrowLeft/ArrowRight under RTL"); `Calendar.test.tsx` "ArrowUp skips a disabled cell in the same column to the next enabled row (complex-2)" for the disabled-day skip; `Calendar.test.tsx` Page-key cases ("moves the focused day by a month with PageDown and PageUp, into the month now shown", "pages from a borrowed adjacent-month day onto the real day in the month already shown", "an arrow past max changes nothing and leaves no pending target behind", "a page into a month with no enabled day changes nothing and keeps focus", "a page onto a day disabled by a constraint moves the month and focuses its first enabled day", "a page whose target lies past max changes nothing and keeps focus", "in a two-month view a boundary blocks only out-of-range targets, not month movement", "in a two-month view PageDown from the second month moves both months and a later Next click selects no stale day"); borrowed-day cases ("skips borrowed adjacent-month days and crosses into their month instead", "in a two-month view an arrow from the first month lands on the real day, never a borrowed one", "an arrow toward a direction where every remaining day is disabled changes nothing", "an arrow resolves the next enabled day in its direction first: weekdays-only ArrowRight from Friday January 30 reaches Monday February 2", "an arrow whose next day in range does not exist changes nothing: max January 25, ArrowDown from January 21"); the single-Tab-stop assertion in the AST-085 range-cap case (FR2). `Calendar.test.tsx` selection-state accessible-name cases ("appends 'selected' to the selected day's button name in single mode", "marks range start, end, and in-range days in their accessible names"). Evidence gap: no Calendar-level test of Home, End, Enter, or Space; no test covers the Tab stop after a key move followed by a pointer pick or a fully disabled month | LTR and RTL; month boundary; selected, today, disabled days                             | A day loses its role, name or state, two days in one month hold a Tab stop, or an arrow, Home/End, Page or activation key stops moving or picking.                                                                                                            | `audit:Calendar/accessibility` |
-| FR6             | `Calendar.test.tsx` navigation, bound, theming-target ("renders the astryx-calendar-nav target on both month-nav buttons", "reflects the disabled nav state as a data attribute at the range edges", "keeps the default nav rendering unchanged (still a ghost icon button)"), and RTL month-navigation cases                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Previous and Next; at `min` and `max`; `dir="rtl"`                                      | A button enabled past a bound, a missing `calendar-nav` target or state attribute, or a lost shared chevron wrapper fails. Evidence gap: no test asserts focus kept at a bound (the FR6 gap), the mirrored chevron pixels, or the press under reduced motion. | `audit:Calendar/behavior`      |
-| FR7             | `Calendar.test.tsx` month-change announcement cases ("does not announce on initial render", "announces the new month politely when clicking next", "announces the next month when paging the grid with PageDown", "announces both months in a two-month view", "does not announce when selecting a date leaves the visible month unchanged") and range announcement cases ("announces the start pick and prompts for an end date", "announces the completed range in chronological order for a reverse pick")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Month buttons, Page keys, handle; single and two months; range start, complete, cleared | A missing, extra, or out-of-order announcement fails. Evidence gap: no test reaches the cleared-start announcement (the cleared-range case sets no `minRangeSpan`).                                                                                           | `audit:Calendar/accessibility` |
-| FR2 (size)      | Evidence gap: no test asserts day-button size or text growth                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | —                                                                                       | —                                                                                                                                                                                                                                                             | `audit:Calendar/layout`        |
-| AR1 (browser)   | `Calendar.a11y.test.tsx` and `Calendar.a11y.chromium.spec.ts` over the shared grid states                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Every representative state                                                              | A lost grid name, role, or start neighbourhood fails; browser-owned outcomes are reported.                                                                                                                                                                    | `audit:Calendar/accessibility` |
-| ORD1, ORD2, PR1 | ORD1 and ORD2 are covered by the FR3–FR5 and AR1 rows. Evidence gap: no test asserts the absence of per-cell listeners                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | —                                                                                       | —                                                                                                                                                                                                                                                             | `audit:Calendar/behavior`      |
-
-## Current-state impact
-
-- **Day and week digits (FR1).** Day and week numbers render as ASCII digits
-  in every locale, while month labels follow the locale, against
-  `architecture:internationalization` INV8.
-- **Stale Tab stop (FR3, AR1).** After a key move places the Tab stop, a later
-  pointer pick can leave it there (always when the picked day comes later in
-  the grid), and when every day of that month becomes disabled it stays on a
-  disabled day, so Tab can land on an unselected or disabled day.
-- **Month buttons under reduced motion (FR6).** The Previous and Next buttons
-  scale on a press when the person prefers reduced motion, as `component:Button`
-  FR15 records, against `design:reduced-motion` DR1.
-- **Fixed day size (FR2).** Day buttons hold a fixed size instead of growing
-  with a set text size, against `spec:AST-102` FR4.
-- **Month buttons at a bound (FR6).** Previous and Next become natively
-  disabled at `min` and `max`, so a keyboard user on the button that reaches the
-  bound loses focus, against `spec:AST-085` FR1 and FR4.
-
-## Decision log
-
-No component-local decision. The Grid adoption follows `spec:AST-020/FR15`.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables or examples (`Calendar.doc.mjs`),
-the date-field composition records, or shared theming rules. It links to their
-owners.