@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Tokenizer/__tests__/TokenizerEndLane.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file TokenizerEndLane.a11y.chromium.spec.ts
@@ -52,26 +53,65 @@ async function open(
 }
 
 /**
- * Sets the story's sizing container to `width` and, for every field with a
- * visible clear-all lane, returns each visible box that intersects the lane:
- * tokens, the "+N more" count, and the input's content box (where its text
- * and caret paint).
+ * Sizes the story to `width` (a pixel width, or `max-content` for a
+ * content-sized field) and waits for the layout to settle.
+ *
+ * The sizing box is the story decorator's: the outermost element in the story
+ * whose own inline style sizes it, by a width or by a grid column, and that
+ * holds the fields. An inline size inside a field never counts: the end
+ * lane's reserved Spinner sets its own width inline, and resizing it instead
+ * of the story would widen the lane across the token rows. A grid decorator
+ * sizes its fields through its column, so the column follows the width. The
+ * layer mode's popover takes its width from the in-flow field inside the box.
  */
-async function overlapsAt(page: Page, width: number): Promise<string[]> {
-  return page.evaluate(async width => {
-    // The story decorator's fixed-width box; the layer mode's popover takes
-    // its width from the in-flow field inside it.
-    const host = document.querySelector<HTMLElement>(
-      '#storybook-root [style*="width"]',
-    );
-    if (!host) {
-      throw new Error('No sizing container in the story');
+async function sizeStory(page: Page, width: string): Promise<void> {
+  const box = await page
+    .locator(
+      '#storybook-root [style*="width"], #storybook-root [style*="grid-template-columns"]',
+    )
+    .filter({has: page.locator('.astryx-tokenizer')})
+    .first()
+    .elementHandle({timeout: 5_000});
+  if (box == null) {
+    throw new Error('No sizing container in the story');
+  }
+  await box.evaluate(async (host, width) => {
+    host.style.width = width;
+    if (host.style.gridTemplateColumns !== '') {
+      host.style.gridTemplateColumns =
+        width === 'max-content' ? 'max-content' : `minmax(0, ${width})`;
     }
-    host.style.width = `${width}px`;
     for (let frame = 0; frame < 4; frame++) {
       await new Promise(resolve => requestAnimationFrame(resolve));
     }
+    // The fields sit inside the box, so a pixel width bounds every one of
+    // them; no field inside, or one wider than the box, means the box sized
+    // something else.
+    const fields = host.querySelectorAll('.astryx-tokenizer');
+    if (fields.length === 0) {
+      throw new Error('The sizing box holds no field');
+    }
+    if (width !== 'max-content') {
+      for (const field of fields) {
+        const fieldWidth = field.getBoundingClientRect().width;
+        if (fieldWidth > parseFloat(width) + 0.5) {
+          throw new Error(
+            `Sized the story to ${width}, but a field is ${fieldWidth}px wide`,
+          );
+        }
+      }
+    }
+  }, width);
+}
 
+/**
+ * Sizes the story to `width` and, for every field with a visible clear-all
+ * lane, returns each visible box that intersects the lane: tokens, the "+N
+ * more" count, and the input's content box (where its text and caret paint).
+ */
+async function overlapsAt(page: Page, width: number): Promise<string[]> {
+  await sizeStory(page, `${width}px`);
+  return page.evaluate(width => {
     const isShown = (el: Element) =>
       el.checkVisibility({visibilityProperty: true}) &&
       !el.closest('[aria-hidden="true"]');
@@ -173,32 +213,26 @@ async function sweepWhileBusy(
 }
 
 /**
- * Sizes the story container (a pixel width, or `max-content` for a
- * content-sized field) and returns the field's border box.
+ * Sizes the story (a pixel width, or `max-content` for a content-sized field)
+ * and returns the field's border box.
  */
 async function fieldBoxAt(
   page: Page,
   width: string,
 ): Promise<{width: number; height: number}> {
-  return page.evaluate(async width => {
-    const host = document.querySelector<HTMLElement>(
-      '#storybook-root [style*="width"]',
-    );
+  await sizeStory(page, width);
+  return page.evaluate(() => {
     const field = document.querySelector('button[aria-label="Clear all"]')
       ?.parentElement?.parentElement;
-    if (!host || !field) {
-      throw new Error('Field or sizing container did not render');
-    }
-    host.style.width = width;
-    for (let frame = 0; frame < 4; frame++) {
-      await new Promise(resolve => requestAnimationFrame(resolve));
+    if (!field) {
+      throw new Error('Field did not render');
     }
     const {width: w, height: h} = field.getBoundingClientRect();
     return {
       width: Math.round(w * 100) / 100,
       height: Math.round(h * 100) / 100,
     };
-  }, width);
+  });
 }
 
 /** Adds tokens through the menu, as a person would. */

package/src/Toolbar/Toolbar.spec.md

@@ -1,54 +1,90 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Toolbar
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-27
 owners: [cixzhang]
 review_triggers: [layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/Toolbar/Toolbar.test.tsx,
+    packages/core/src/Toolbar/__tests__/Toolbar.a11y.test.tsx,
+    packages/core/src/Toolbar/__tests__/Toolbar.a11y.chromium.spec.ts,
     packages/core/src/Section/Section.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
   ]
 modules: []
 families: [family:layout-regions]
-design_specs: []
+design_specs: [design:reduced-motion]
 architecture:
   [
     architecture:component-theming-surface,
     architecture:container-padding,
+    architecture:component-size-cascade,
+    architecture:interaction-modality,
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-020]
 ---
 
 # Toolbar component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `Toolbar` with `label`, `startContent`, `centerContent`, `endContent`, `size` (`md`), `gap` (`1`), `orientation` (`horizontal`), `variant` (`transparent`), and `dividers`; target `toolbar` with `size`.                           |
+| Behavior                | A Section-wrapped `role="toolbar"` row with start, optional center, and end lanes. The row is one tab stop; arrow keys, Home, and End move focus among its controls along its orientation.                                          |
+| End-user impact         | Keyboard users Tab into the toolbar once and move between its controls with arrows, without losing text-caret keys inside an input or arrow keys inside an open menu; screen-reader users hear a named toolbar and its orientation. |
+| Builder impact          | None.                                                                                                                                                                                                                               |
+| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact).                                                                                                                                    |
+| Review checks           | Reject more than one tab stop, arrows that steal caret keys from a text input mid-line, caller props that replace `role`, `aria-label`, or `aria-orientation`, or moving outer chrome into Toolbar.                                 |
+| Governing rules         | `family:layout-regions`; `spec:AST-020` (toolbar pattern binding); `architecture:container-padding`.                                                                                                                                |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
 Toolbar presents a named contextual action region with one semantic toolbar row
-inside Section-owned outer chrome. This draft records the current consumer
-anatomy and theming ownership without changing layout, keyboard behavior,
-targets, or public API.
+inside Section-owned outer chrome. It owns the row's semantics, lane layout,
+keyboard model, and size cascade. Consumer usage lives in `Toolbar.doc.mjs`.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
+- Compatibility class: records shipped behavior; runtime, DOM, styling,
   targets, and public API remain unchanged
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **The keyboard hint fades under reduced motion.** The arrow-key hint (FR6)
+  fades out over 150 ms (it appears at once) even when reduced motion is
+  requested;
+  `design:reduced-motion` DR3 allows no animated property for a fine pointer.
+- **A vertical toolbar with center content stays side by side.** With
+  `orientation="vertical"` and `centerContent`, the three lanes stay in one row
+  while `aria-orientation` is vertical and ArrowDown and ArrowUp move between
+  them, so the visual order and the announced axis disagree.
+- **The tab stop does not follow a pointer click.** After a click on a control
+  that does not hold the stop, the stop stays on the earlier control, so
+  Shift+Tab from the clicked control lands on that earlier control inside the
+  toolbar before leaving it.
+- **Links and some fields keep their own tab stops.** A link (such as a Button
+  with `href`), `textarea`, or `select` in the row is outside the roving stop:
+  it keeps its own tab stop and the arrow keys skip it. The APG toolbar pattern
+  makes the toolbar a single tab stop.
+
 ## Ownership boundary
 
 **Owns**
@@ -59,25 +95,30 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Does not own / non-goals**
 
 - The painted outer chrome, variant, block padding, and selected divider edges —
-  delegated to `component:Section`.
+  owned by Section and uncontracted here.
 - Content supplied through the three layout slots — owned by the caller or its
-  rendered components.
+  rendered components, except the press tracking `family:action-groups` FR5
+  gives Toolbar across its buttons.
 - A general arbitrary-child layout primitive contract.
-- New runtime behavior, targets, props, or target placement.
+- Arrow-key handling inside composed menus or popovers — owned by those
+  components.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props, slots, and usage remain
-documented in `Toolbar.doc.mjs`; `family:layout-regions` owns the shared
-structural-region boundary.
+No component-local concept beyond the consumer props; `family:layout-regions`
+owns the shared structural-region boundary.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                              | Basis                                      | Draft review state                                 |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------- |
-| FR1 | The current render contains Section-owned Outer chrome around one named Toolbar carrying `role="toolbar"` and the current `toolbar` target.                      | Current source, docs, tests, and family    | Verified current behavior; no new behavior decided |
-| FR2 | The Toolbar uses its current two-lane layout without center content and its current three-lane layout when center content is supplied.                           | Current source and focused structure tests | Verified current behavior; no layout change        |
-| FR3 | Variant, selected divider edges, and outer padding remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout. | Current source, docs, and family contract  | Verified current ownership; no target change       |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                         |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| FR1 | The render contains Section-owned Outer chrome around one Toolbar carrying `role="toolbar"`, `aria-label` from `label`, `aria-orientation`, and the `toolbar` target with `size`. Caller `role`, `aria-label`, and `aria-orientation` are dropped; other DOM props reach the toolbar row; `ref`, `className`, `style`, and `xstyle` reach the Section.                                                                                                                                                                                                                                                                                                                                                                                                    | Current source, docs, tests, and family       |
+| FR2 | Without center content the Toolbar is a flex line of the present start and end lanes, a row when horizontal and a column of lanes when vertical; with center content it is a three-lane grid whose lanes sit side by side in either orientation. Each lane lays its controls out in a row. No lane clips its content, and the center lane can shrink below its content width. `gap` spaces controls within and between lanes.                                                                                                                                                                                                                                                                                                                             | Current source and focused structure tests    |
+| FR3 | Variant (default `transparent`), selected divider edges, and block padding by size remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source, docs, and family contract     |
+| FR4 | The row MUST be a single tab stop. ArrowRight and ArrowLeft (horizontal) or ArrowDown and ArrowUp (vertical) move focus between its controls, wrapping at the ends and skipping disabled controls; Home and End move to the first and last. Implementation gap: only buttons, inputs, and elements with `tabindex` share the stop, so links, `textarea`, and `select` keep their own tab stops, and a pointer click does not move the stop (Current-state impact). Arrows do not move focus out of a text input whose caret is mid-line, and inside an open composed menu arrow keys belong to the menu. The toolbar keeps its tab stop after a composed menu is dismissed from outside, and keeps its own arrow movement when rendered inside a popover. | APG toolbar pattern; current source and tests |
+| FR5 | Caller `onKeyDown`, `onFocus`, and `onBlur` run first; when the caller cancels the event, the built-in handling is skipped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                      |
+| FR6 | Keyboard focus entering the row can show a brief, self-dismissing hint for its arrow-key axis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source                                |
+| FR7 | `size` (default `md`) is provided to descendant controls as their default size; Toolbar starts its own size scope and does not inherit an outer size provider (`architecture:component-size-cascade` INV7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                      |
 
 ### Allowed variation
 
@@ -88,33 +129,33 @@ structural-region boundary.
 
 ### Representative states
 
-| State             | Required invariant                                      | Allowed variation                                   |
-| ----------------- | ------------------------------------------------------- | --------------------------------------------------- |
-| Empty toolbar     | Outer chrome and named Toolbar remain rendered.         | No caller slot content.                             |
-| Two-lane layout   | Start and/or end content use the current flex layout.   | Either lane may be absent.                          |
-| Three-lane layout | Center content selects the current three-column layout. | Start or end content may be absent.                 |
-| Vertical toolbar  | Toolbar semantics and target remain unchanged.          | Layout and keyboard movement use the vertical axis. |
+| State             | Required invariant                                      | Allowed variation                                                                  |
+| ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Empty toolbar     | Outer chrome and named Toolbar remain rendered.         | No caller slot content.                                                            |
+| Two-lane layout   | Start and/or end content use the current flex layout.   | Either lane may be absent.                                                         |
+| Three-lane layout | Center content selects the current three-column layout. | Start or end content may be absent.                                                |
+| Vertical toolbar  | Toolbar semantics and target remain unchanged.          | Keyboard movement uses the vertical axis; lanes stack only without center content. |
 
 ### Transformation and precedence order
 
-- No new slot, layout, edge-compensation, padding, or event precedence rule is
-  introduced.
+- **ORD1 — Events.** Caller handler, then the built-in handler unless cancelled
+  (FR5).
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- No resource rule.
 
 ## Accessibility contract
 
-This draft does not change or extend Toolbar's current accessible name,
-orientation, roving-tabindex, keyboard-hint, caret-guard, or event-composition
-behavior.
+- **AR1 — Named toolbar.** FR1's role, name, and orientation.
+- **AR2 — Keyboard.** FR4 follows the APG toolbar pattern, apart from FR4's
+  implementation gap.
 
 ## Design relationships
 
 | Anatomy or state | Design requirement                                                               | Representation authority                  | Hierarchy role | Component contract |
 | ---------------- | -------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
-| Outer chrome     | Supplies the painted surface, padding, and selected boundaries around the row.   | `component:Section`                       | Supporting     | FR1, FR3           |
+| Outer chrome     | Supplies the painted surface, padding, and selected boundaries around the row.   | Section                                   | Supporting     | FR1, FR3           |
 | Toolbar          | Presents the named toolbar semantics and current two- or three-lane arrangement. | Current source, docs, and family contract | Prominent      | FR1, FR2, FR3      |
 
 The slot contents are caller-owned content inside Toolbar's layout. They do not
@@ -141,27 +182,40 @@ become additional Toolbar-owned anatomy or targets.
   geometry used by the composed Section and Toolbar.
 - `architecture:component-theming-surface` owns anatomy qualification, local
   target mapping, and component delegation.
-- `architecture:public-component-api` owns the stable prop and slot surface; this
-  documentation adds no API.
+- `architecture:public-component-api` owns the stable prop and slot surface.
+- `spec:AST-020` binds the toolbar accessibility pattern exercised by the
+  Toolbar a11y tests.
 
 ## Verification map
 
-| Contract            | Verification                                                    | Representative states                          | Mutation or failure expectation                                                                                      | Audit section           |
-| ------------------- | --------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1                 | `Toolbar.test.tsx` role, name, pass-through, and Section suites | Empty and populated Toolbar                    | Removing the role/name, Toolbar target, Section composition, or delegated Section target fails current evidence.     | `audit:Toolbar/anatomy` |
-| FR2                 | `Toolbar.test.tsx` slot and child-count suites                  | Start-only, end-only, two-lane, and three-lane | Changing current slot presence or two-/three-lane structure fails focused assertions.                                | `audit:Toolbar/layout`  |
-| FR3                 | Toolbar and Section source plus their focused tests             | Variant, divider, size, and orientation states | Moving outer chrome ownership into Toolbar or moving toolbar semantics onto Section contradicts source and coverage. | `audit:Toolbar/theming` |
-| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`                | Toolbar and delegated Section targets          | Runtime and documented target metadata drift fails target validation.                                                | `audit:Toolbar/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                   | Canonical anatomy and current local target     | Missing, extra, prefixed, or stale mappings fail repository validation.                                              | `audit:Toolbar/theming` |
-
-Existing tests assert the semantic row, slot structure, and Section composition.
-They do not prove computed inset or edge-compensation geometry for every parent
-padding state; this documentation does not claim that coverage.
+| Contract            | Verification                                                                                                 | Representative states                               | Mutation or failure expectation                                                                                  | Audit section                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| FR1                 | `Toolbar.test.tsx` role, name, pass-through, and Section suites                                              | Empty and populated Toolbar                         | Removing the role/name, Toolbar target, Section composition, or delegated Section target fails current evidence. | `audit:Toolbar/anatomy`       |
+| FR2                 | `Toolbar.test.tsx` slot and child-count suites                                                               | Start-only, end-only, two-lane, and three-lane      | Changing current slot presence or two-/three-lane structure fails focused assertions.                            | `audit:Toolbar/layout`        |
+| FR3                 | `Toolbar.test.tsx` variant and block-inset tests                                                             | Default and passed variant                          | A variant that no longer reaches Section fails.                                                                  | `audit:Toolbar/theming`       |
+| FR4, FR5, AR1–AR2   | `Toolbar.test.tsx` keyboard and composition suites; `Toolbar.a11y.test.tsx`; `Toolbar.a11y.chromium.spec.ts` | Horizontal, vertical, text input, MoreMenu, popover | Extra tab stops, stolen caret keys, or ignored caller cancellation fails.                                        | `audit:Toolbar/accessibility` |
+| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`                                                             | Toolbar and delegated Section targets               | Runtime and documented target metadata drift fails target validation.                                            | `audit:Toolbar/theming`       |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                | Canonical anatomy and current local target          | Missing, extra, prefixed, or stale mappings fail repository validation.                                          | `audit:Toolbar/theming`       |
+
+Read from source, with no focused test yet:
+
+- FR1: caller `role`, `aria-label`, and `aria-orientation` being dropped, and
+  `className`, `style`, and `xstyle` reaching Section.
+- FR2: the flex and grid layouts themselves, and `gap` spacing.
+- FR3: divider edges.
+- FR5: caller `onFocus` and `onBlur` running first and their cancellation.
+- FR4: links, `textarea`, and `select` keeping their own tab stops, and the stop
+  staying put after a pointer click.
+- FR6.
+- FR7: descendant controls taking `size` as their default, and the fresh size
+  scope.
+
+Computed inset and edge-compensation geometry for each parent padding state is
+not claimed.
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-layout, accessibility, or API decision.
+No component-local decision is recorded.
 
 ## Open questions
 

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

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/toolbar\.|packages/core/src/Toolbar/|apps/storybook/stories/ToolbarA11y)
 
 /**
  * @file Toolbar.a11y.chromium.spec.ts