@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/dist/utils/plainDate.js

@@ -35,7 +35,11 @@ export function plainDateToISO(pd) {
   return `${y}-${m}-${d}`;
 }
 export function plainDateToDate(pd) {
-  return new Date(pd.year, pd.month - 1, pd.day);
+  // Unlike the Date constructor, setFullYear keeps years 0-99 as given
+  // instead of reading them as 1900-1999.
+  const d = new Date(0, 0, 1);
+  d.setFullYear(pd.year, pd.month - 1, pd.day);
+  return d;
 }
 export function plainDateFromDate(d) {
   return {
@@ -77,6 +81,17 @@ export function plainDateAddDays(pd, n) {
   return plainDateFromDate(d);
 }
 
+/**
+ * `Date.UTC` with years 0-99 kept as given; `Date.UTC` itself reads them as
+ * 1900-1999.
+ */
+function utcTime(year, monthIndex, day, hour = 0, minute = 0, second = 0) {
+  const d = new Date(0);
+  d.setUTCFullYear(year, monthIndex, day);
+  d.setUTCHours(hour, minute, second);
+  return d.getTime();
+}
+
 /**
  * Whole calendar days from `a` to `b`, ignoring time of day. Positive when
  * `b` is after `a`, negative when before. Uses UTC midnight so DST shifts
@@ -84,8 +99,8 @@ export function plainDateAddDays(pd, n) {
  */
 export function plainDateDiffDays(a, b) {
   const msPerDay = 24 * 60 * 60 * 1000;
-  const aUTC = Date.UTC(a.year, a.month - 1, a.day);
-  const bUTC = Date.UTC(b.year, b.month - 1, b.day);
+  const aUTC = utcTime(a.year, a.month - 1, a.day);
+  const bUTC = utcTime(b.year, b.month - 1, b.day);
   return Math.round((bUTC - aUTC) / msPerDay);
 }
 
@@ -122,14 +137,23 @@ export function getTimeZoneParts(instant, timezoneID) {
 }
 function getTimezoneOffsetMS(timezoneID, instant) {
   const parts = getTimeZoneParts(instant, timezoneID);
-  return Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second) - instant;
+  return utcTime(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second) - instant;
 }
+const DAY_MS = 24 * 60 * 60 * 1000;
 export function plainDateToInstant(date, timezoneID, hour = 0, minute = 0) {
-  const utcGuess = Date.UTC(date.year, date.month - 1, date.day, hour, minute);
-  const firstOffset = getTimezoneOffsetMS(timezoneID, utcGuess);
-  const firstInstant = utcGuess - firstOffset;
-  const secondOffset = getTimezoneOffsetMS(timezoneID, firstInstant);
-  return utcGuess - secondOffset;
+  // The wall time read as if it were UTC; subtracting an offset gives a
+  // candidate instant.
+  const wallTime = utcTime(date.year, date.month - 1, date.day, hour, minute);
+  // The offsets in effect a day either side cover any transition that can make
+  // this wall time skipped or repeated.
+  const offsetBefore = getTimezoneOffsetMS(timezoneID, wallTime - DAY_MS);
+  const offsetAfter = getTimezoneOffsetMS(timezoneID, wallTime + DAY_MS);
+  // AST-067 (Temporal's "compatible" disambiguation): a wall time that happens
+  // twice resolves to its earlier occurrence, and one that never happens is
+  // read in the offset before the transition, which moves it forward by the
+  // length of the gap.
+  const candidates = [offsetBefore, offsetAfter].map(offset => wallTime - offset).filter((instant, index) => getTimezoneOffsetMS(timezoneID, instant) === (index === 0 ? offsetBefore : offsetAfter));
+  return candidates.length > 0 ? Math.min(...candidates) : wallTime - offsetBefore;
 }
 export function plainDateFromInstant(instant, timezoneID) {
   const parts = getTimeZoneParts(instant, timezoneID);
@@ -181,7 +205,11 @@ export function plainDateGetWeekNumber(pd) {
   const d = plainDateToDate(pd);
   const dayNum = d.getDay() || 7;
   d.setDate(d.getDate() + 4 - dayNum);
-  const yearStart = new Date(d.getFullYear(), 0, 1);
+  const yearStart = plainDateToDate({
+    year: d.getFullYear(),
+    month: 1,
+    day: 1
+  });
   return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
 }
 
@@ -262,6 +290,31 @@ export function plainDateFormat(pd, options, locale = 'en') {
   }).format(plainDateToDate(pd));
 }
 
+/**
+ * The locale's name for the "week of year" date field ("week", "Woche", "週"),
+ * from CLDR through `Intl.DisplayNames`. Calendar names its week-number
+ * column header with it, so no catalog string is needed for a word the
+ * platform already carries in every locale.
+ *
+ * `Intl.DisplayNames` with `type: 'dateTimeField'` is inside the Baseline − 2
+ * support tier (Chrome 106, Safari 15.4, Firefox 110). Should a host lack it
+ * or return nothing, the field's English CLDR name stands in rather than an
+ * empty header.
+ */
+export function plainDateWeekFieldName(locale = 'en') {
+  try {
+    const name = new Intl.DisplayNames(locale, {
+      type: 'dateTimeField'
+    }).of('weekOfYear');
+    if (name != null && name !== '') {
+      return name;
+    }
+  } catch {
+    // Fall through to the English CLDR value.
+  }
+  return 'week';
+}
+
 // =============================================================================
 // Shared date-only format vocabulary
 // =============================================================================

package/locales/en.json

@@ -409,7 +409,7 @@
   },
   "@astryx.commandPalette.noResultsFor": {
     "defaultMessage": "No results for {query}",
-    "description": "Screen-reader-only announcement when a CommandPalette query matches nothing. `{query}` is the user's verbatim search text; keep it last if your language allows so truncation-by-AT still conveys the outcome."
+    "description": "Not read by any component: CommandPalette announces its rendered empty-search message (`emptySearchText`) instead. Formerly the screen-reader-only announcement when a query matched nothing; `{query}` was the user's verbatim search text."
   },
   "@astryx.commandPalette.loading": {
     "defaultMessage": "Loading",
@@ -863,6 +863,10 @@
     "defaultMessage": "Search…",
     "description": "Grey placeholder inside the CommandPalette's search input. Imperative verb; trailing `…` is one character."
   },
+  "@astryx.commandPalette.input.label": {
+    "defaultMessage": "Search commands",
+    "description": "Screen-reader-only accessible name for the CommandPalette query input. Distinguish it from the visible placeholder; verb followed by the app actions being searched."
+  },
   "@astryx.commandPalette.list.label": {
     "defaultMessage": "Commands",
     "description": "\"Command\" = an app action a user can invoke (metaphor from CLI), not a Unix command. Screen-reader-only name for the matching-commands list."
@@ -1287,6 +1291,10 @@
     "defaultMessage": "Increment {label}",
     "description": "Accessible label for the NumberInput button that increases the value by one configured step. Example: `Increment Quantity`."
   },
+  "@astryx.numberInput.invalidNumber": {
+    "defaultMessage": "Invalid number",
+    "description": "Screen-reader-only live-region alert in NumberInput when the typed text is not a valid number for the field. The field silently reverts on blur, so this is the only rejection feedback a screen-reader user gets."
+  },
   "@astryx.selector.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the selected value from a Selector. `{label}` is the selector's visible label — example: `Clear Country`."
@@ -1407,6 +1415,10 @@
     "defaultMessage": "{count, number} {count, plural, one {character} other {characters}} over the limit",
     "description": "Screen-reader-only assertive announcement when the user has typed past a TextArea's maxLength. `{count}` is how many characters over — example: `3 characters over the limit`."
   },
+  "@astryx.inputClearButton.tooltip": {
+    "defaultMessage": "Clear",
+    "description": "Tooltip shown on hover or keyboard focus over the X button inside an input that clears its value. Verb, imperative. Shown alone beside the field, so it names only the action; the screen-reader label names the field separately."
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a TextInput. Example: `Clear Email`, `Clear Name`."

package/locales/pseudo.json

@@ -647,6 +647,9 @@
   "@astryx.commandPalette.input.placeholder": {
     "defaultMessage": "⟦Šéàřçĥ…⟧"
   },
+  "@astryx.commandPalette.input.label": {
+    "defaultMessage": "⟦Šéàřçĥ çóɱɱàñðš⟧"
+  },
   "@astryx.commandPalette.list.label": {
     "defaultMessage": "⟦Çóɱɱàñðš⟧"
   },
@@ -965,6 +968,9 @@
   "@astryx.numberInput.incrementLabel": {
     "defaultMessage": "⟦Íñçřéɱéñţ {label}⟧"
   },
+  "@astryx.numberInput.invalidNumber": {
+    "defaultMessage": "⟦Íñṽàłíð ñúɱƀéř⟧"
+  },
   "@astryx.selector.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
@@ -1055,6 +1061,9 @@
   "@astryx.textArea.charactersOverLimit": {
     "defaultMessage": "⟦{count, number} {count, plural, one {character} other {characters}} óṽéř ţĥé łíɱíţ⟧"
   },
+  "@astryx.inputClearButton.tooltip": {
+    "defaultMessage": "⟦Çłéàř⟧"
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.1-canary.ff40b78",
+  "version": "0.7.1",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -787,8 +787,6 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.1-canary.ff40b78",
-    "@astryxdesign/cli": "0.7.1-canary.ff40b78",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -799,7 +797,9 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2"
+    "tailwindcss": "^4.3.2",
+    "@astryxdesign/a11y-spec": "0.0.0",
+    "@astryxdesign/cli": "0.7.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/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

package/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.

package/src/AlertDialog/AlertDialog.test.tsx

@@ -93,11 +93,9 @@ describe('AlertDialog', () => {
     onAction: vi.fn(),
   };
 
-  it('renders with alertdialog role', () => {
-    render(<AlertDialog {...defaultProps} />);
-    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
-  });
-
+  // The alertdialog role and the aria-describedby link are asserted by the
+  // Alert Dialog accessibility contract binding (AlertDialog.a11y.test.tsx /
+  // .chromium.spec.ts), not here.
   it('renders title and description', () => {
     render(<AlertDialog {...defaultProps} />);
     expect(screen.getByText('Delete item?')).toBeInTheDocument();
@@ -115,15 +113,6 @@ describe('AlertDialog', () => {
     expect(titleEl).toHaveTextContent('Delete item?');
   });
 
-  it('links description via aria-describedby', () => {
-    render(<AlertDialog {...defaultProps} />);
-    const dialog = screen.getByRole('alertdialog');
-    const describedBy = dialog.getAttribute('aria-describedby');
-    expect(describedBy).toBeTruthy();
-    const descEl = document.getElementById(describedBy!);
-    expect(descEl).toHaveTextContent('This action cannot be undone.');
-  });
-
   it('renders cancel and action buttons', () => {
     render(<AlertDialog {...defaultProps} />);
     expect(screen.getByText('Cancel')).toBeInTheDocument();

package/src/AlertDialog/__tests__/AlertDialog.a11y.chromium.spec.ts

@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AlertDialog.a11y.chromium.spec.ts
+ * @input Built AlertDialog stories and ALERT_DIALOG_PATTERN in real Chromium
+ * @output Browser evidence for every alert-dialog expectation across the binding's states, the surface opened through its opener the way a person reaches it
+ * @position Chromium lane of the AlertDialog binding (component:AlertDialog AR1)
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  ALERT_DIALOG_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {
+  ALERT_DIALOG_BINDING_STATES,
+  ALERT_DIALOG_CANCEL_LABEL,
+  ALERT_DIALOG_MESSAGE,
+  ALERT_DIALOG_OPEN_LABEL,
+  type AlertDialogBindingState,
+} from './AlertDialog.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+async function mountState(
+  page: Page,
+  state: AlertDialogBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const root = page.locator('#storybook-root');
+  const subject = root.locator('dialog');
+  await root.getByRole('button', {name: ALERT_DIALOG_OPEN_LABEL}).click();
+  await subject.waitFor({state: 'visible'});
+  const message = subject.getByText(ALERT_DIALOG_MESSAGE);
+  const cancel = subject.getByRole('button', {
+    name: ALERT_DIALOG_CANCEL_LABEL,
+  });
+  return {subject, related: {message, cancel}};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: AlertDialogBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: ALERT_DIALOG_PATTERN,
+    binding: 'AlertDialog',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every alert-dialog expectation is exercised by an AlertDialog state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of ALERT_DIALOG_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of ALERT_DIALOG_BINDING_STATES) {
+  test(`AlertDialog [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(ALERT_DIALOG_PATTERN, [result]);
+    // Required rows block (AST-020 FR9); advisory rows and exact known
+    // failures report.
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/AlertDialog/__tests__/AlertDialog.a11y.renders.tsx

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file AlertDialog.a11y.renders.tsx
+ * @input One AlertDialog binding state
+ * @output The React tree every lane renders for that state: an opener button and the AlertDialog it opens (the jsdom test directly, the story through Storybook)
+ * @position Shared fixture for the AlertDialog binding
+ */
+
+import {useState, type ReactElement} from 'react';
+import {AlertDialog} from '../AlertDialog';
+import {
+  ALERT_DIALOG_ACTION_LABEL,
+  ALERT_DIALOG_CANCEL_LABEL,
+  ALERT_DIALOG_MESSAGE,
+  ALERT_DIALOG_OPEN_LABEL,
+  ALERT_DIALOG_TITLE,
+  type AlertDialogBindingState,
+} from './AlertDialog.a11y.states';
+
+function BoundAlertDialog({state}: {state: AlertDialogBindingState}) {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <>
+      <button type="button" onClick={() => setIsOpen(true)}>
+        {ALERT_DIALOG_OPEN_LABEL}
+      </button>
+      <AlertDialog
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        title={ALERT_DIALOG_TITLE}
+        description={ALERT_DIALOG_MESSAGE}
+        cancelLabel={ALERT_DIALOG_CANCEL_LABEL}
+        actionLabel={ALERT_DIALOG_ACTION_LABEL}
+        isActionLoading={state.isActionLoading}
+        onAction={() => setIsOpen(false)}
+      />
+    </>
+  );
+}
+
+export function renderAlertDialogState(
+  state: AlertDialogBindingState,
+): ReactElement {
+  return (
+    <div style={{padding: 24}}>
+      <BoundAlertDialog state={state} />
+    </div>
+  );
+}