Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(a11y): Window Splitter, Grid and Alert Dialog adoptions — Resizable, DateInput, new Calendar and AlertDialog draft records (#7464)

Cindy Zhang655fc299f1a5
diff --git a/.changeset/alert-dialog-doc-surface-part.md b/.changeset/alert-dialog-doc-surface-part.md
new file mode 100644
index 0000000000..9c10385746
--- /dev/null
+++ b/.changeset/alert-dialog-doc-surface-part.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] `AlertDialog`'s anatomy lists the dialog surface — the modal panel that holds the title, description, and buttons — and `Calendar`'s anatomy lists the calendar root and the day button, so every part that carries a theming target (`alert-dialog`, `calendar`, `calendar-day`) is named in the component docs.
+
+@cixzhang
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index ed67da8add..135cd637e5 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -90,6 +90,12 @@ export const docs = {
description:
'Overlay behind the dialog that blocks page interaction. Clicking it does not dismiss.',
},
+ {
+ name: 'Dialog surface',
+ required: true,
+ description:
+ 'The modal panel that holds the title, description, and buttons.',
+ },
],
},
// Intentionally a contained isInline preview, not playground.overlay: the
diff --git a/packages/core/src/AlertDialog/AlertDialog.spec.md b/packages/core/src/AlertDialog/AlertDialog.spec.md
new file mode 100644
index 0000000000..8e8575fcc5
--- /dev/null
+++ b/packages/core/src/AlertDialog/AlertDialog.spec.md
@@ -0,0 +1,205 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:AlertDialog
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming]
+verified_by:
+ [
+ packages/core/src/AlertDialog/AlertDialog.test.tsx,
+ packages/core/src/AlertDialog/useImperativeAlertDialog.test.tsx,
+ packages/core/src/Dialog/Dialog.test.tsx,
+ scripts/check-knowledge.mjs,
+ ]
+modules: []
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ architecture:layer-runtime,
+ ]
+contributing: []
+system_specs: [spec:AST-020/FR15]
+---
+
+# AlertDialog component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | None changes. `AlertDialog`, `AlertDialogProps`, and `useImperativeAlertDialog` are exported from `@astryxdesign/core/AlertDialog`; `title`, `description`, `actionLabel`, `onAction`, and `onOpenChange` are required with `isOpen`, plus cancel label, action variant, loading, width, and an inline preview mode. |
+| Behavior | A modal confirmation that interrupts: it opens through the native dialog, cannot be dismissed by a click outside, closes on Escape or Cancel through `onOpenChange(false)`, and runs `onAction` on the action button. |
+| End-user impact | A keyboard or screen-reader user is told a decision is needed (the title and description are announced), lands on Cancel, and cannot lose the dialog by clicking past it. |
+| Builder impact | None. |
+| Compatibility/readiness | Released behavior as observed; this draft records it and adopts the APG Alert Dialog pattern (AR1) under `spec:AST-020/FR15`. |
+| Review checks | Reject a modal AlertDialog without `role="alertdialog"`, a title or description not linked by id, initial focus on the destructive action, or a backdrop click that dismisses it. |
+| Governing rules | `architecture:public-component-api/INV1,INV5–INV8`; `architecture:component-theming-surface/INV3–INV7`; `architecture:layer-runtime`; `component:Dialog/AR1–AR3`; `spec:AST-020/FR15`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+AlertDialog asks a person to confirm or cancel one consequential action. It
+composes Dialog's modal, focus, and dismissal runtime with a fixed anatomy —
+title, description, Cancel, and one action — so a product gets an interrupting
+confirmation without assembling it.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation; runtime, DOM, styling, targets, and
+ public API are unchanged
+- Controlled/uncontrolled behavior: unchanged — `isOpen` with `onOpenChange` is
+ controlled; `useImperativeAlertDialog` owns that pair for a caller that wants
+ `show`/`hide`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The confirmation anatomy and its order: title, description, then Cancel and
+ action in the order FR3 states.
+- The alert-dialog role, its name and description links, and the least-destructive
+ initial focus.
+- The imperative wrapper hook.
+
+**Does not own / non-goals**
+
+- Modal presentation, focus return, backdrop, and dismissal mechanics — owned by
+ `component:Dialog` and `architecture:layer-runtime`.
+- Button variants and loading — owned by `component:Button`.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| --------------- | ----------------------- | ------------------------------------------------------------------- | ----------------------------------------- | --------------- | ----------------------- | --------- | ---------------------- |
+| `isInline` | `true`, `false` | Renders the content inline as a non-modal preview (`role="group"`). | Always | `false` | `component:AlertDialog` | stable | Type-rejected |
+| `actionVariant` | Button variants | The action button's emphasis. | Always | `'destructive'` | `component:Button` | stable | Button's behavior |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision. A `current` contract contains no unresolved rows.
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------ |
+| FR1 | A modal AlertDialog opens through Dialog's native modal path and a click on the backdrop does not dismiss it. | shipped source (`purpose="form"`); Alert Dialog accessibility contract (pending) | verify |
+| FR2 | Escape and the Cancel button both call `onOpenChange(false)`; the action button calls `onAction` and leaves closing to the caller. | shipped source and focused tests | verify |
+| FR3 | The anatomy is title, description, then the buttons: Cancel then action on wider screens, the action stacked above Cancel on small screens, Cancel keeping initial focus either way; the action may show a loading state while `isActionLoading`. | shipped source and focused tests | verify |
+| FR4 | `isInline` renders the same anatomy without modality and without the alert-dialog role. | shipped source and public docs | verify |
+| FR5 | `useImperativeAlertDialog` returns `show`, `hide`, and the element to render, and owns `isOpen`/`onOpenChange` for its caller. | shipped source and focused tests | verify |
+
+### Allowed variation
+
+- **AV1 — Layout.** Spacing and button width follow Dialog and Layout; the
+ small-screen stacking and order are FR3's.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| -------------- | ----------------------------------------------------------- | ---------------------- |
+| open, modal | `role="alertdialog"`, named and described, focus on Cancel. | Width, action variant. |
+| action loading | The action shows loading; Cancel stays available. | Loading affordance. |
+| inline preview | `role="group"`, no modality, same content. | Surrounding page. |
+| imperative | `show()` opens and `hide()` closes the same dialog. | Caller's trigger. |
+
+### Transformation and precedence order
+
+- **ORD1 — Dismissal.** Escape or Cancel → `onOpenChange(false)`; backdrop click →
+ nothing; action → `onAction` only.
+
+### Performance and resources
+
+- **PR1 — Dialog-owned resources.** AlertDialog's only listener is the
+ small-screen media query behind the button order; Dialog owns the modal
+ lifecycle.
+
+## Accessibility contract
+
+- **AR1 — AlertDialog adopts the APG Alert Dialog pattern** (`spec:AST-020/FR15`):
+ the modal surface is `role="alertdialog"`, named by its title through
+ `aria-labelledby` and described by its description through `aria-describedby`;
+ it is modal through Dialog (focus enters it and returns to the opener on close
+ per `component:Dialog/AR1–AR2`; Tab containment follows Dialog, whose record
+ leaves it open); initial
+ focus lands on Cancel, the least destructive action; Escape cancels; no click
+ outside dismisses it. The inline preview is not an alert dialog and carries
+ `role="group"`.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Title | Names the decision. | `component:Heading` | Prominent | FR3, AR1 |
+| Description | States the consequence. | `component:Text` | Supporting | FR3, AR1 |
+| Cancel button | The safe way out; receives initial focus. | `component:Button` | Supporting | FR2, AR1 |
+| Action button | The consequential choice, with its variant and loading; stacked above Cancel on small screens. | `component:Button` | Prominent | FR2, FR3 |
+| Backdrop | Separates the dialog from the page; does not dismiss it. | `component:Dialog` | Supporting | FR1 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Title": {"delegatesTo": {"owner": "component:Text", "target": "heading"}},
+ "Description": {"delegatesTo": {"owner": "component:Text", "target": "text"}},
+ "Cancel button": {
+ "delegatesTo": {"owner": "component:Button", "target": "button"}
+ },
+ "Action button": {
+ "delegatesTo": {"owner": "component:Button", "target": "button"}
+ },
+ "Backdrop": {
+ "delegatesTo": {"owner": "component:Dialog", "target": "dialog"}
+ },
+ "Dialog surface": {"target": "alert-dialog"}
+}
+```
+
+The dialog surface (the Dialog element AlertDialog renders) carries `alert-dialog`.
+
+## Family and system relationships
+
+- `component:Dialog` owns modality, focus return, and dismissal; AlertDialog
+ composes it with `purpose="form"` semantics and the alert-dialog role.
+- `family:overlay-dismissal` lists AlertDialog as a member: it dismisses through
+ Dialog's shared owner with no deviation of its own; Escape cancels it and a
+ backdrop click does not (FR1).
+- `spec:AST-020/FR15` decides which APG parts a component adopts; AlertDialog
+ adopts the Alert Dialog pattern's required parts because it already plays that
+ role.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1–FR5 | `AlertDialog.test.tsx` ("calls onOpenChange(false) on Escape", "does not call onOpenChange when action is clicked", "does not call onAction on Escape", "does not disable the cancel button while the action is loading", "exposes a named group instead, with no aria-modal") and `useImperativeAlertDialog.test.tsx` ("opens on show()", "closes on hide()") | open, loading, inline, imperative | Escape not cancelling, the action closing by itself, or the inline path claiming the role fails. | `audit:AlertDialog/behavior` |
+| AR1 | `AlertDialog.test.tsx` ("renders with alertdialog role", "links title via aria-labelledby", "links description via aria-describedby", "marks cancel as the initial focus target", "keeps the initial focus target on the least destructive action", "calls onOpenChange(false) on Escape", "stacks long destructive action labels above cancel on a narrow fine-pointer screen", "reaches both buttons by Tab, cancel first", "is a modal alertdialog", "does not claim the alertdialog role") and `useImperativeAlertDialog.test.tsx`; the no-backdrop-dismiss outcome and focus delegation under the Alert Dialog accessibility contract (`internal/a11y-spec`, pending) | open modal; after Escape; after Cancel | The role, name link, description link, or Cancel initial focus is lost, or a click outside dismisses the dialog. | `audit:AlertDialog/accessibility` |
+
+## Decision log
+
+None. This draft records shipped behavior; the Alert Dialog adoption follows the
+system rule rather than a component-local decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples
+(`AlertDialog.doc.mjs`), Dialog's modal contract, or shared theming rules. It
+links to their owners.
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index a5004da6b3..b7005104f4 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -6,23 +6,85 @@ export const docs = {
name: 'Calendar',
displayName: 'Calendar',
category: 'Form Controls',
- keywords: ["calendar","datepicker","date picker","rangepicker","date range","monthview","daypicker"],
+ keywords: [
+ 'calendar',
+ 'datepicker',
+ 'date picker',
+ 'rangepicker',
+ 'date range',
+ 'monthview',
+ 'daypicker',
+ ],
usage: {
description:
'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
bestPractices: [
- {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
- {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
- {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
- {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
- {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
- {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
+ {
+ guidance: true,
+ description:
+ 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Show two months side by side when the user frequently selects dates that span a month boundary.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Disable large blocks of dates without context. The user should understand why dates are unavailable.',
+ },
],
anatomy: [
- {name: 'Month header', required: true, description: 'The month name and year with navigation arrows to move between months. The arrows mirror automatically under dir="rtl".'},
- {name: 'Day grid', required: true, description: 'A 7-column grid of days with column headers for the day names.'},
- {name: 'Selected day', required: false, description: 'The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.'},
- {name: 'Today marker', required: false, description: 'A subtle indicator on the current date for orientation.'},
+ {
+ name: 'Calendar root',
+ required: true,
+ description:
+ 'The container that holds the month header and the day grid.',
+ },
+ {
+ name: 'Month header',
+ required: true,
+ description:
+ 'The month name and year with navigation arrows to move between months. The arrows mirror automatically under dir="rtl".',
+ },
+ {
+ name: 'Day grid',
+ required: true,
+ description:
+ 'A 7-column grid of days with column headers for the day names.',
+ },
+ {
+ name: 'Day button',
+ required: true,
+ description: 'One day in the grid; the control a date is picked with.',
+ },
+ {
+ name: 'Selected day',
+ required: false,
+ description:
+ 'The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.',
+ },
+ {
+ name: 'Today marker',
+ required: false,
+ description: 'A subtle indicator on the current date for orientation.',
+ },
],
},
props: [
@@ -35,7 +97,8 @@ export const docs = {
{
name: 'value',
type: 'ISODateString | DateRange | null',
- description: 'Controlled selected value. Use null for no selection; omit value or pass undefined for uncontrolled mode.',
+ description:
+ 'Controlled selected value. Use null for no selection; omit value or pass undefined for uncontrolled mode.',
},
{
name: 'defaultValue',
@@ -94,7 +157,8 @@ export const docs = {
{
name: 'handleRef',
type: 'React.Ref<CalendarHandle>',
- description: 'Imperative handle for calendar navigation, including navigateTo().',
+ description:
+ 'Imperative handle for calendar navigation, including navigateTo().',
},
{
name: 'hasOutsideDays',
@@ -117,15 +181,23 @@ export const docs = {
{
name: 'weekStartsOn',
type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
- description: 'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',
+ description:
+ 'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',
default: '0',
},
],
theming: {
targets: [
{className: 'astryx-calendar', visualProps: ['mode']},
- {className: 'astryx-calendar-nav', visualProps: ['nav'], states: ['disabled']},
- {className: 'astryx-calendar-day', states: ['selected', 'today', 'disabled', 'in-range', 'marker']},
+ {
+ className: 'astryx-calendar-nav',
+ visualProps: ['nav'],
+ states: ['disabled'],
+ },
+ {
+ className: 'astryx-calendar-day',
+ states: ['selected', 'today', 'disabled', 'in-range', 'marker'],
+ },
],
},
};
@@ -138,59 +210,138 @@ export const docsZh = {
description:
'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
bestPractices: [
- {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
- {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
- {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
- {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
- {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
- {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
+ {
+ guidance: true,
+ description:
+ 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Show two months side by side when the user frequently selects dates that span a month boundary.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Disable large blocks of dates without context. The user should understand why dates are unavailable.',
+ },
],
},
props: [
- {name: 'mode', type: "'single' | 'range'", description: '选择模式。', default: "'single'"},
- {name: 'value', type: 'ISODateString | DateRange | null', description: '受控选中值。null 表示没有选中值;省略或传入 undefined 为非受控模式。'},
- {name: 'defaultValue', type: 'ISODateString | DateRange', description: '非受控默认值。'},
+ {
+ name: 'mode',
+ type: "'single' | 'range'",
+ description: '选择模式。',
+ default: "'single'",
+ },
+ {
+ name: 'value',
+ type: 'ISODateString | DateRange | null',
+ description:
+ '受控选中值。null 表示没有选中值;省略或传入 undefined 为非受控模式。',
+ },
+ {
+ name: 'defaultValue',
+ type: 'ISODateString | DateRange',
+ description: '非受控默认值。',
+ },
{name: 'onChange', type: 'Function', description: '选择回调函数。'},
- {name: 'numberOfMonths', type: '1 | 2', description: '显示的月份数量。', default: '1'},
+ {
+ name: 'numberOfMonths',
+ type: '1 | 2',
+ description: '显示的月份数量。',
+ default: '1',
+ },
{name: 'min', type: 'ISODateString', description: '可选择的最早日期。'},
{name: 'max', type: 'ISODateString', description: '可选择的最晚日期。'},
- {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数。'},
- {name: 'maxRangeSpan', type: 'number', description: '范围模式:范围最多可跨越的天数,含首尾两端(7 = 7 天窗口)。选定起始日后限制窗口大小。'},
- {name: 'minRangeSpan', type: 'number', description: '范围模式:范围最少需跨越的天数,含首尾两端(2 表示禁止单日范围)。再次点击开始日期时,若最小范围允许则提交单日范围;否则取消进行中的选择。默认为 1。'},
- {name: 'focusDate', type: 'ISODateString', description: '受控可见月份。未设置时,日历打开时显示已选日期所在月份;若无选中值,则显示今天,并将其限制在 min/max 范围内。'},
- {name: 'onFocusDateChange', type: '(focusDate: ISODateString) => void', description: '导航回调函数。'},
- {name: 'handleRef', type: 'React.Ref<CalendarHandle>', description: '日历导航的命令式句柄,包括 navigateTo()。'},
- {name: 'hasOutsideDays', type: 'boolean', description: '显示相邻月份的日期。', default: 'true'},
- {name: 'hasWeekNumbers', type: 'boolean', description: '显示 ISO 周数。', default: 'false'},
- {name: 'hasVariableRowCount', type: 'boolean', description: '可变行数与固定 6 行网格。', default: 'false'},
- {name: 'weekStartsOn', type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'", description: '每周起始日。可为数字(0=周日)或三字母星期缩写(如 "mon")。', default: '0'},
+ {
+ name: 'dateConstraints',
+ type: 'Array<(date: Date) => boolean>',
+ description: '自定义约束函数。',
+ },
+ {
+ name: 'maxRangeSpan',
+ type: 'number',
+ description:
+ '范围模式:范围最多可跨越的天数,含首尾两端(7 = 7 天窗口)。选定起始日后限制窗口大小。',
+ },
+ {
+ name: 'minRangeSpan',
+ type: 'number',
+ description:
+ '范围模式:范围最少需跨越的天数,含首尾两端(2 表示禁止单日范围)。再次点击开始日期时,若最小范围允许则提交单日范围;否则取消进行中的选择。默认为 1。',
+ },
+ {
+ name: 'focusDate',
+ type: 'ISODateString',
+ description:
+ '受控可见月份。未设置时,日历打开时显示已选日期所在月份;若无选中值,则显示今天,并将其限制在 min/max 范围内。',
+ },
+ {
+ name: 'onFocusDateChange',
+ type: '(focusDate: ISODateString) => void',
+ description: '导航回调函数。',
+ },
+ {
+ name: 'handleRef',
+ type: 'React.Ref<CalendarHandle>',
+ description: '日历导航的命令式句柄,包括 navigateTo()。',
+ },
+ {
+ name: 'hasOutsideDays',
+ type: 'boolean',
+ description: '显示相邻月份的日期。',
+ default: 'true',
+ },
+ {
+ name: 'hasWeekNumbers',
+ type: 'boolean',
+ description: '显示 ISO 周数。',
+ default: 'false',
+ },
+ {
+ name: 'hasVariableRowCount',
+ type: 'boolean',
+ description: '可变行数与固定 6 行网格。',
+ default: 'false',
+ },
+ {
+ name: 'weekStartsOn',
+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+ description:
+ '每周起始日。可为数字(0=周日)或三字母星期缩写(如 "mon")。',
+ default: '0',
+ },
],
theming: {
targets: [
{
className: 'astryx-calendar',
- visualProps: [
- 'mode',
- ],
+ visualProps: ['mode'],
},
{
className: 'astryx-calendar-nav',
- visualProps: [
- 'nav',
- ],
- states: [
- 'disabled',
- ],
+ visualProps: ['nav'],
+ states: ['disabled'],
},
{
className: 'astryx-calendar-day',
- states: [
- 'selected',
- 'today',
- 'disabled',
- 'in-range',
- 'marker',
- ],
+ states: ['selected', 'today', 'disabled', 'in-range', 'marker'],
},
],
},
@@ -203,11 +354,31 @@ export const docsDense = {
description:
'Calendar lets the user pick a date or date range from a month grid. Use in booking, scheduling, date filters.',
bestPractices: [
- {guidance: true, description: 'Set min/max to limit selection to a valid window: only future dates for booking, current quarter for a report.'},
- {guidance: true, description: 'Use range mode when user picks start + end dates: trip, time-off request.'},
- {guidance: true, description: 'Use dateConstraints to disable specific dates (weekends/holidays); explain why unavailable.'},
- {guidance: true, description: 'Show two months side by side when user frequently selects dates spanning a month boundary.'},
- {guidance: false, description: 'Use for dates far in the past/future; text input is faster.'},
+ {
+ guidance: true,
+ description:
+ 'Set min/max to limit selection to a valid window: only future dates for booking, current quarter for a report.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use range mode when user picks start + end dates: trip, time-off request.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use dateConstraints to disable specific dates (weekends/holidays); explain why unavailable.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Show two months side by side when user frequently selects dates spanning a month boundary.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use for dates far in the past/future; text input is faster.',
+ },
{guidance: false, description: 'Disable dates without explaining why.'},
],
},
@@ -220,9 +391,12 @@ export const docsDense = {
min: 'minimum selectable date',
max: 'maximum selectable date',
dateConstraints: 'custom constraint fns',
- maxRangeSpan: 'range mode: max days a range may span, both ends counted (7 = 7-day window)',
- minRangeSpan: 'range mode: min days a range must span, both ends counted; repeated start click commits one day when allowed, otherwise cancels (default 1)',
- focusDate: 'controlled visible month (default: selected date, else today clamped into min/max)',
+ maxRangeSpan:
+ 'range mode: max days a range may span, both ends counted (7 = 7-day window)',
+ minRangeSpan:
+ 'range mode: min days a range must span, both ends counted; repeated start click commits one day when allowed, otherwise cancels (default 1)',
+ focusDate:
+ 'controlled visible month (default: selected date, else today clamped into min/max)',
onFocusDateChange: 'navigation callback',
handleRef: 'imperative navigation handle',
hasOutsideDays: 'show days from adjacent months',
diff --git a/packages/core/src/Calendar/Calendar.spec.md b/packages/core/src/Calendar/Calendar.spec.md
new file mode 100644
index 0000000000..e41b8cd7e4
--- /dev/null
+++ b/packages/core/src/Calendar/Calendar.spec.md
@@ -0,0 +1,217 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Calendar
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+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,
+ scripts/check-knowledge.mjs,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ architecture:react-component-runtime,
+ ]
+contributing: []
+system_specs: [spec:AST-020/FR15]
+---
+
+# 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 | Released behavior as observed; this draft records it and adopts the APG Grid pattern for the day grid (AR1) under `spec:AST-020/FR15`. |
+| 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`. |
+
+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: additive documentation; runtime, DOM, styling, targets, and
+ public API are unchanged
+- Controlled/uncontrolled behavior: unchanged — `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
+ `component:DateInput` and its siblings.
+- Time of day — owned by `component:DateTimeInput`.
+
+## 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
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision. A `current` contract contains no unresolved rows.
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------ |
+| FR1 | Each rendered month is one `role="grid"` named for its month and year, with a `columnheader` per weekday and one `row` per week. | shipped source and focused tests | verify |
+| FR2 | At most one day button in each month's grid holds `tabIndex={0}`; every other day button in that grid is `-1`. | shipped `useGridFocus` behavior; Grid accessibility contract (pending) | verify |
+| FR3 | A disabled day (outside bounds or rejected by a constraint) stays in the grid, is exposed as disabled, and cannot be picked. | shipped source and focused tests | verify |
+| 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 | verify |
+| FR5 | Moving the focused day across a month boundary navigates the visible month so the focused day stays visible, except in a two-month Calendar, where focus can land in the second month's grid on the target or on its first day button that is not natively disabled, which can be an `aria-disabled` borrowed day (AR1); an arrow can also land on a borrowed adjacent-month day, which is exposed `aria-disabled` and cannot be picked. | shipped source and focused tests | verify |
+
+### 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. | 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 and keeps no per-cell listeners.
+
+## 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, 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 gives it to the grid's first day button that is not natively
+ disabled, which can be a borrowed adjacent-month day, or to none.
+ ArrowLeft and ArrowRight move by a day following the reading direction,
+ ArrowUp and ArrowDown by a week, Home and End to the first and last 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 bounds or a constraint and continues in the
+ same direction.
+ Implementation gaps: PageUp and PageDown change the visible month but target
+ the day a week away and, when that day is not shown, focus the first day
+ button in the grid that is not natively disabled, which can be an
+ adjacent-month day; the arrow keys, Home and End can focus a borrowed
+ adjacent-month day that is `aria-disabled`, because cell focusability checks
+ only native `disabled`; and in a two-month Calendar, a key that changes the
+ visible months can leave focus in the second month's grid — on its own
+ button for the target day or, failing that, on its first day button that is
+ not natively disabled, which can be an `aria-disabled` borrowed day that
+ cannot be picked — instead of the target day, because each month grid falls
+ back on its own.
+
+## Design relationships
+
+| 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 |
+| 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.
+
+## 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"), 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. | `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; the at-most-one-Tab-stop-per-month (FR2), Home/End, Page and activation keys on Calendar itself under the Grid accessibility contract (`internal/a11y-spec`, pending) | 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` |
+
+## Decision log
+
+None. This draft records shipped behavior; the Grid adoption follows the system
+rule rather than a component-local decision.
+
+## 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.
diff --git a/packages/core/src/DateInput/DateInput.spec.md b/packages/core/src/DateInput/DateInput.spec.md
index d9479dcd1a..5b6f929377 100644
--- a/packages/core/src/DateInput/DateInput.spec.md
+++ b/packages/core/src/DateInput/DateInput.spec.md
@@ -211,6 +211,17 @@ approved policy.
- **AR7 — Directionality.** DateInput's own calendar and clear controls exchange logical
inline sides in RTL while preserving their labels and meanings; Calendar navigation
remains owned and verified by `component:Calendar`.
+- **AR8 — The month scroller is an APG grid** (`spec:AST-020/FR15`), as one
+ composite control: each mounted month pane of the touch calendar's scroller
+ is a `role="grid"` named for its month, with rows of `role="gridcell"` days,
+ at most one day per pane holding a Tab stop,
+ `aria-selected` on the chosen day; ArrowLeft and ArrowRight move by a day
+ following the reading direction, ArrowUp and ArrowDown by a week, Home and End
+ to the ends of the week, PageUp and PageDown by a month, and Enter or Space
+ picks the focused day. Implementation gaps: the horizontal arrows do not follow
+ the reading direction under RTL; PageUp/PageDown do not page by a month; and
+ a keyboard move can land on a neighbouring pane's dimmed, `aria-disabled` copy
+ of the target day instead of the real day in its own pane.
## Design relationships
@@ -271,16 +282,17 @@ the shared `input-clear-icon` target owns current clear-glyph theming.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, FR5–FR8, FR10–FR12; AR1–AR4 | `DateInput.test.tsx` | empty, valued, typing, invalid, constrained, open, disabled, busy, clear, status, grouped | Value, callbacks, ARIA, disabled guard, focus, or shared-field composition drifts | `audit:DateInput/pointer-field` |
-| FR2–FR4 | `Presentation.test.tsx`, `NativeDateField.test.tsx`, `DateInputTouch.test.tsx` | every presentation, omitted props, every deprecated mapping, dual props, fine/coarse, touchscreen laptop | A value resolves to the wrong surface, width affects modality, or legacy behavior wins incorrectly | `audit:DateInput/presentation` |
-| FR5–FR7; AR1, AR3–AR5 | `NativeDateField.test.tsx` | empty, valued, focused, constrained, disabled, clear, formatted, locale | Native commit, overlay, label, constraint, or focus reconciliation drifts | `audit:DateInput/native` |
-| FR1, FR4–FR7, FR9, FR11–FR12; AR1, AR4, AR6; PR1–PR2 | `DateInputTouch.test.tsx` | closed/open, month grid, selection correction, wheels, bounds, keyboard, swipe, mouse drag, clear, busy | Touch value parity, bounded rendering, focus, semantics, or gesture ownership drifts | `audit:DateInput/touch` |
-| FR2–FR3, FR6 | `DateInput.doc.mjs`, Storybook controls, `scripts/check-knowledge.mjs` | five presentation values, deprecated prop, named formats, English and Chinese docs | Source, docs, types, or default mappings disagree | `audit:DateInput/docs-api` |
-| Theming anatomy | `DateInput.test.tsx`, `themingTargets.test.ts`, generated probe theme | root size/status/disabled, toggle state, shared clear target | Target class or state is missing, undocumented, or placed on the wrong element | `audit:DateInput/theming` |
-| FR8; AR2 | `apps/storybook/stories/DateInput.stories.tsx`, component-scoped axe | open Calendar dialog plus closed field states | Important popup semantics stay unreachable to the browser audit | `audit:DateInput/a11y` |
-| AR7 | `apps/storybook/rtl-audit/targets.json`, component RTL audit | calendar and clear controls in LTR and RTL | DateInput-owned controls fail to exchange logical inline order | `audit:DateInput/rtl` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, FR5–FR8, FR10–FR12; AR1–AR4 | `DateInput.test.tsx` | empty, valued, typing, invalid, constrained, open, disabled, busy, clear, status, grouped | Value, callbacks, ARIA, disabled guard, focus, or shared-field composition drifts | `audit:DateInput/pointer-field` |
+| FR2–FR4 | `Presentation.test.tsx`, `NativeDateField.test.tsx`, `DateInputTouch.test.tsx` | every presentation, omitted props, every deprecated mapping, dual props, fine/coarse, touchscreen laptop | A value resolves to the wrong surface, width affects modality, or legacy behavior wins incorrectly | `audit:DateInput/presentation` |
+| FR5–FR7; AR1, AR3–AR5 | `NativeDateField.test.tsx` | empty, valued, focused, constrained, disabled, clear, formatted, locale | Native commit, overlay, label, constraint, or focus reconciliation drifts | `audit:DateInput/native` |
+| FR1, FR4–FR7, FR9, FR11–FR12; AR1, AR4, AR6; PR1–PR2 | `DateInputTouch.test.tsx` | closed/open, month grid, selection correction, wheels, bounds, keyboard, swipe, mouse drag, clear, busy | Touch value parity, bounded rendering, focus, semantics, or gesture ownership drifts | `audit:DateInput/touch` |
+| FR2–FR3, FR6 | `DateInput.doc.mjs`, Storybook controls, `scripts/check-knowledge.mjs` | five presentation values, deprecated prop, named formats, English and Chinese docs | Source, docs, types, or default mappings disagree | `audit:DateInput/docs-api` |
+| Theming anatomy | `DateInput.test.tsx`, `themingTargets.test.ts`, generated probe theme | root size/status/disabled, toggle state, shared clear target | Target class or state is missing, undocumented, or placed on the wrong element | `audit:DateInput/theming` |
+| FR8; AR2 | `apps/storybook/stories/DateInput.stories.tsx`, component-scoped axe | open Calendar dialog plus closed field states | Important popup semantics stay unreachable to the browser audit | `audit:DateInput/a11y` |
+| AR7 | `apps/storybook/rtl-audit/targets.json`, component RTL audit | calendar and clear controls in LTR and RTL | DateInput-owned controls fail to exchange logical inline order | `audit:DateInput/rtl` |
+| AR8 | `DateInputTouch.test.tsx` calendar-surface suite ("mounts a window of months around the visible one, not the whole century" for the named grids, "moves keyboard focus by date, across the month boundary", "moves a week at a time with the vertical arrows", "leaves exactly one day per month tab-reachable", "gives a spilled date no tab stop in the pane that borrows it", "disables days outside min/max and refuses to commit them"); ArrowLeft and ArrowUp (the suite presses only ArrowRight and ArrowDown on the month grid), RTL mirroring, Home/End, Page and activation keys under the Grid accessibility contract (`internal/a11y-spec`, pending) | LTR and RTL; month boundary; selected day; today | A day loses its gridcell role or selection, two days in one pane hold a Tab stop, or an arrow, Home/End, Page or activation key stops moving or picking | `audit:DateInput/accessibility` |
## Decision log
diff --git a/packages/core/src/Resizable/Resizable.spec.md b/packages/core/src/Resizable/Resizable.spec.md
index 5e11f9c502..a233109f29 100644
--- a/packages/core/src/Resizable/Resizable.spec.md
+++ b/packages/core/src/Resizable/Resizable.spec.md
@@ -152,6 +152,22 @@ orientation, collapsed value text, focus, pointer, or keyboard behavior. Its
`aria-valuemin`, `aria-valuemax`, and `aria-valuenow` remain the same resolved pixel
values used by hook state and painted geometry.
+- **AR1 — ResizeHandle adopts the APG Window Splitter pattern**
+ (`spec:AST-020/FR15`), as one composite control: the Handle is a focusable
+ `role="separator"` with an accessible name, `aria-orientation` (the axis the
+ divider lies along), `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` in pixels,
+ `aria-valuetext` while collapsed, and `aria-disabled` when disabled. ArrowRight
+ and ArrowDown move the divider toward the end of its axis and ArrowLeft and
+ ArrowUp toward the start, the inline arrows following the reading direction
+ under RTL, with Shift for a larger step, so the pane grows or shrinks by the
+ side of the Handle it sits on; Home moves to the minimum size and End to the
+ maximum; Enter collapses a collapsible pane and restores it. Implementation gaps under `spec:AST-020/FR15`: the Handle
+ does not name the pane it resizes with `aria-controls`; Enter reopens at the
+ minimum rather than restoring the previous size the pattern expects; an
+ unbounded Handle carries no `aria-valuemax` and End does not move it; and
+ Enter does not reopen a collapsed pane whose `minSize` is below
+ `collapsedSize`.
+
## Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
@@ -198,15 +214,16 @@ not emit the documented target state.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1 | `ResizeHandle.test.tsx` plus source inspection | Default, custom, collapsed, disabled, both axes | Handle and Grab zone regressions fail focused tests; custom Grip replacement currently relies on source review. | `audit:Resizable/anatomy` |
-| FR2 | Source inspection and `themingTargets.test.ts` | Handle, Grip pill, and Grab zone | Removing a target or documenting an unshipped Grab zone target fails evidence or inventory. | `audit:Resizable/theming` |
-| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts` | Pointer, keyboard, snap, collapse, persistence | Moving resize ownership or changing current transformations fails focused behavior coverage. | `audit:Resizable/behavior` |
-| FR4 | Source and public metadata comparison | Horizontal and vertical Handle | No current test detects that documented `direction` is absent from runtime target-state reflection. | `audit:Resizable/theming` |
-| FR5 | Hook/utils tests, typecheck, and Chromium | Canonical floor/ceiling/default; invalid XOR shape; SSR/hydration; basis changes; numeric `containerRef` parity | Wrong resolution, rescaling defaults, stale clamps, observer leaks, extra numeric renders/ref reads, or state/paint/storage/ARIA divergence fails. | `audit:Resizable/behavior` |
-| FR6 | Hook type/runtime and codemod tests | Removed alias type errors; single/multi-region inline migrations; numeric pixel bounds | A removed alias still type-checks, or migration changes its numeric meaning. | `audit:Resizable/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two current targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Resizable/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1 | `ResizeHandle.test.tsx` plus source inspection | Default, custom, collapsed, disabled, both axes | Handle and Grab zone regressions fail focused tests; custom Grip replacement currently relies on source review. | `audit:Resizable/anatomy` |
+| AR1 | `ResizeHandle.test.tsx` ("makes the separator focusable", "exposes the region size and bounds via ARIA", "grows the panel by a step on ArrowRight", "shrinks the panel by a step on ArrowLeft", "uses the large step when Shift is held", "jumps to the minimum on Home", "jumps to the maximum on End", "collapses on Enter when the region is collapsible", "inverts the pointer delta under RTL so dragging resizes intuitively") and `shippedDirections.test.ts`; RTL keyboard mirroring, `aria-controls`, and the disabled state under the Window Splitter accessibility contract (`internal/a11y-spec`, pending) | Inline and block axes; LTR and RTL; collapsed; disabled | The Handle loses its role, name, orientation or value properties; an arrow, Home, End or Enter stops moving the divider or moves it against the reading direction | `audit:Resizable/accessibility` |
+| FR2 | Source inspection and `themingTargets.test.ts` | Handle, Grip pill, and Grab zone | Removing a target or documenting an unshipped Grab zone target fails evidence or inventory. | `audit:Resizable/theming` |
+| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts` | Pointer, keyboard, snap, collapse, persistence | Moving resize ownership or changing current transformations fails focused behavior coverage. | `audit:Resizable/behavior` |
+| FR4 | Source and public metadata comparison | Horizontal and vertical Handle | No current test detects that documented `direction` is absent from runtime target-state reflection. | `audit:Resizable/theming` |
+| FR5 | Hook/utils tests, typecheck, and Chromium | Canonical floor/ceiling/default; invalid XOR shape; SSR/hydration; basis changes; numeric `containerRef` parity | Wrong resolution, rescaling defaults, stale clamps, observer leaks, extra numeric renders/ref reads, or state/paint/storage/ARIA divergence fails. | `audit:Resizable/behavior` |
+| FR6 | Hook type/runtime and codemod tests | Removed alias type errors; single/multi-region inline migrations; numeric pixel bounds | A removed alias still type-checks, or migration changes its numeric meaning. | `audit:Resizable/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two current targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Resizable/theming` |
Current tests exercise Handle and Grab zone structure and behavior but do not
render `children` to prove that custom content replaces Grip pill. That branch is
@@ -232,6 +249,12 @@ literal percentage.
partial second CSS implementation without a demonstrated need for arbitrary
composition.
+### The Handle is an APG window splitter
+
+**Decision:** ResizeHandle already acts as one composite control with the splitter's role, value properties, and keyboard, so it adopts the pattern's required parts and its keyboard (AR1), with `aria-controls`, the previous-size restore on Enter, `aria-valuemax` and End on an unbounded Handle, and the small-`minSize` reopen recorded as implementation gaps; the inline arrows follow the reading direction because a key that moves the divider against the way it travels on screen is a defect. Decided by `cixzhang`, `2026-10-13`.
+
+**Rejected:** a separate button to collapse the pane; a direction-free ArrowLeft under RTL.
+
## Open questions
- **OQ1 — Which follow-up should add and verify the missing Handle `direction`