@astryxdesign/core 0.7.5 → 0.7.6-canary.bb18c81

package/dist/utils/presentation.d.ts

@@ -0,0 +1,50 @@
+import type { AdaptivePresentation } from '../hooks/useAdaptivePresentation.js';
+import type { CompactDefinition } from '../theme/themeAdaptations.js';
+import { type TouchPresentation } from './touchPresentation.js';
+/** What a component does when the caller omits `presentation`. */
+export type PresentationDefault = 'popover' | 'touch';
+export interface ResolvedPresentation {
+    /** The surface to render. */
+    readonly surface: 'popover' | 'bottom-sheet';
+    /**
+     * The component's touch input modes apply: a finger, and `presentation`
+     * not pinned to `'popover'`.
+     */
+    readonly touchModes: boolean;
+}
+export interface PresentationOptions {
+    /** What an omitted `presentation` means. @default 'popover' */
+    readonly whenOmitted?: PresentationDefault;
+}
+/**
+ * usePresentation's options. There is no server hint: the server and
+ * hydrating render never present touch modes (`spec:AST-094` FR13).
+ */
+export type UsePresentationOptions = PresentationOptions;
+export interface ReadPresentationOptions extends PresentationOptions {
+    /** The window to read; the global one by default. */
+    readonly view?: Window | null;
+    /**
+     * The active theme's compact definition (`useCompactDefinition()`, read
+     * while rendering), so a theme that moves `md` moves the sheet too
+     * (`spec:AST-012` FR9).
+     */
+    readonly compact: CompactDefinition;
+}
+/** The decision, from a presentation request and a touch presentation. */
+export declare function resolvePresentation(presentation: AdaptivePresentation | undefined, touch: TouchPresentation, whenOmitted?: PresentationDefault): ResolvedPresentation;
+/**
+ * The presentation now, following the pointer and the size as they change
+ * (a tablet docking a trackpad). SSR-safe: renders the server default (not
+ * touch, not compact) until hydrated (`spec:AST-094` FR13). It subscribes
+ * only to what the request reads: a pinned `'popover'` to neither query,
+ * `'bottom-sheet'` and the omitted `'touch'` default to the pointer, and
+ * `'adaptive'` to the pointer and the compact size.
+ */
+export declare function usePresentation(presentation: AdaptivePresentation | undefined, { whenOmitted }?: UsePresentationOptions): ResolvedPresentation;
+/**
+ * The presentation at this moment, for a decision taken once (a menu
+ * deciding how it follows the finger that opened it).
+ */
+export declare function readPresentation(presentation: AdaptivePresentation | undefined, { whenOmitted, view, compact }: ReadPresentationOptions): ResolvedPresentation;
+//# sourceMappingURL=presentation.d.ts.map

package/dist/utils/presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../src/utils/presentation.ts"],"names":[],"mappings":"AAoDA,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAE7B,kEAAkE;AAClE,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,cAAc,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAEzD,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,qDAAqD;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,oBAAoB,GAAG,SAAS,EAC9C,KAAK,EAAE,iBAAiB,EACxB,WAAW,GAAE,mBAA+B,GAC3C,oBAAoB,CAStB;AA8BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,oBAAoB,GAAG,SAAS,EAC9C,EAAC,WAAuB,EAAC,GAAE,sBAA2B,GACrD,oBAAoB,CAWtB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,oBAAoB,GAAG,SAAS,EAC9C,EAAC,WAAuB,EAAE,IAAI,EAAE,OAAO,EAAC,EAAE,uBAAuB,GAChE,oBAAoB,CAQtB"}

package/dist/utils/presentation.js

@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file presentation.ts
+ * @input A component's `presentation` prop (a caller's value, or omitted),
+ *   what the component does when it is omitted, and the touch presentation
+ *   (utils/touchPresentation.ts)
+ * @output usePresentation and readPresentation (and the pure
+ *   resolvePresentation): the surface to render and whether the component's
+ *   touch input modes apply
+ * @position Internal resolver for stable components that, under a finger,
+ *   present a different surface or switch how an open surface follows input
+ *   (architecture:public-component-api INV16)
+ *
+ * A caller's explicit `presentation` always wins over the touch default:
+ *
+ * - `'popover'`: the fine-pointer surface AND input modes, on every device;
+ * - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a
+ *   finger;
+ * - `'adaptive'`: the sheet on a compact touch screen and the popover
+ *   elsewhere, with touch input modes under a finger;
+ * - omitted: the component's default. `whenOmitted: 'popover'` answers as
+ *   `'popover'` (today's components). `whenOmitted: 'touch'` keeps the
+ *   popover surface and turns the component's touch input modes on under a
+ *   finger, as UIMenu tracks a finger in an anchored menu. Making `'touch'`
+ *   a released component's default is a functional default change
+ *   (`spec:AST-017` FR3) whose Changeset names `presentation="popover"`.
+ *
+ * One touch model on every touch device: the modes depend on the pointer,
+ * never on the platform. Touch styling (press paint, the text-size floor)
+ * and touch-only behavior that a component's own record defines (a row
+ * swipe, a slider's thumb) do not read this: they keep the touch
+ * presentation.
+ *
+ * CSS: a style that implements a touch surface or input mode is applied with
+ * `touchModes` (`stylex.props(touchModes && styles.touchMode)`), never as a
+ * bare media key on a base style, so a pinned `'popover'` keeps none of it.
+ * A rule inside it that needs the touch query uses the touch presentation's
+ * touch key; the iOS `@supports` gate is only for the one style iOS WebKit
+ * itself requires (the 16px text-size floor), never for a touch mode. On the
+ * server and while hydrating, `touchModes` is false and `'adaptive'` is the
+ * popover: a touch surface or mode opens only after hydration
+ * (`spec:AST-094` FR13), and no hint changes that. usePresentation listens
+ * only to the queries a request reads (`architecture:react-component-runtime`
+ * INV5): none for a pinned `'popover'`.
+ *
+ * SYNC: When modified, update presentation.test.ts.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { readTouchPresentation, TOUCH_QUERY, useCompactDefinition } from "./touchPresentation.js";
+
+/** What a component does when the caller omits `presentation`. */
+
+/**
+ * usePresentation's options. There is no server hint: the server and
+ * hydrating render never present touch modes (`spec:AST-094` FR13).
+ */
+
+/** The decision, from a presentation request and a touch presentation. */
+export function resolvePresentation(presentation, touch, whenOmitted = 'popover') {
+  const request = presentation ?? whenOmitted;
+  const surface = request === 'bottom-sheet' || request === 'adaptive' && touch.isTouch && touch.isCompact ? 'bottom-sheet' : 'popover';
+  const touchModes = request !== 'popover' && touch.isTouch;
+  return {
+    surface,
+    touchModes
+  };
+}
+const noSubscription = () => () => {};
+/** The server and hydrating render match no query (`spec:AST-094` FR13). */
+const matchesNothing = () => false;
+
+/**
+ * A media query's match, subscribed only while `query` is given
+ * (`architecture:react-component-runtime` INV5); false on the server and
+ * while hydrating (`spec:AST-094` FR13).
+ */
+function useMatchWhileRead(query) {
+  const subscribe = useCallback(onStoreChange => {
+    if (query == null) {
+      return noSubscription();
+    }
+    const mql = window.matchMedia(query);
+    mql.addEventListener('change', onStoreChange);
+    return () => mql.removeEventListener('change', onStoreChange);
+  }, [query]);
+  const getSnapshot = useCallback(() => query != null && window.matchMedia(query).matches, [query]);
+  return useSyncExternalStore(subscribe, getSnapshot, matchesNothing);
+}
+
+/**
+ * The presentation now, following the pointer and the size as they change
+ * (a tablet docking a trackpad). SSR-safe: renders the server default (not
+ * touch, not compact) until hydrated (`spec:AST-094` FR13). It subscribes
+ * only to what the request reads: a pinned `'popover'` to neither query,
+ * `'bottom-sheet'` and the omitted `'touch'` default to the pointer, and
+ * `'adaptive'` to the pointer and the compact size.
+ */
+export function usePresentation(presentation, {
+  whenOmitted = 'popover'
+} = {}) {
+  const request = presentation ?? whenOmitted;
+  const compact = useCompactDefinition();
+  const isTouch = useMatchWhileRead(request === 'popover' ? null : TOUCH_QUERY);
+  const isCompact = useMatchWhileRead(request === 'adaptive' ? compact.query : null);
+  return useMemo(() => resolvePresentation(presentation, {
+    isTouch,
+    isCompact
+  }, whenOmitted), [presentation, isTouch, isCompact, whenOmitted]);
+}
+
+/**
+ * The presentation at this moment, for a decision taken once (a menu
+ * deciding how it follows the finger that opened it).
+ */
+export function readPresentation(presentation, {
+  whenOmitted = 'popover',
+  view,
+  compact
+}) {
+  const target = view === undefined ? typeof window === 'undefined' ? null : window : view;
+  return resolvePresentation(presentation, readTouchPresentation(target, compact), whenOmitted);
+}

package/dist/utils/touchPresentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"touchPresentation.d.ts","sourceRoot":"","sources":["../../src/utils/touchPresentation.ts"],"names":[],"mappings":"AA6DA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AAGnC,uDAAuD;AACvD,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAmC,CAAC;AAE9D,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,QACe,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,kCAAkC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,kFAGvB,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAOxD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,GAAE,OAAO,CAAC,iBAAiB,CAAM,GAC7C,iBAAiB,CAQnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,EAAE,iBAAiB,GACzB,iBAAiB,CAOnB"}
+{"version":3,"file":"touchPresentation.d.ts","sourceRoot":"","sources":["../../src/utils/touchPresentation.ts"],"names":[],"mappings":"AA+DA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AAGnC,uDAAuD;AACvD,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAmC,CAAC;AAE9D,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,QACe,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,kCAAkC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,kFAGvB,CAAC;AAEX,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAOxD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,GAAE,OAAO,CAAC,iBAAiB,CAAM,GAC7C,iBAAiB,CAQnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,EAAE,iBAAiB,GACzB,iBAAiB,CAOnB"}

package/dist/utils/touchPresentation.js

@@ -46,9 +46,11 @@
  * test keeps core's compact-touch keys identical to COMPACT_TOUCH_QUERY and
  * every touch-callout key spelled and nested as above. The iOS style gate
  * is only for a style iOS WebKit itself requires (core's 16px input floor);
- * it never selects a behaviour. The keys are literal because the Astryx
- * StyleX build does not resolve a key shared across files through
- * `defineConsts`. The hook is for behaviour. It answers the server default
+ * it never selects a behaviour. Core spells the keys literally: an imported
+ * `defineConsts` key compiles to a different StyleX priority than the same
+ * literal, which would reorder the cascade. `touchKeys`
+ * (touchPresentation.stylex.ts, internal to core) holds the same keys, and a
+ * test keeps every literal equal to them. The hook is for behaviour. It answers the server default
  * (not touch, not compact) until hydrated unless the caller passes a server
  * hint, and follows the pointer and size when they change (a tablet docking
  * a mouse).

package/dist/utils/touchPresentation.stylex.d.ts

@@ -0,0 +1,15 @@
+export declare const touchKeys: {
+    /** The primary pointer is coarse (TOUCH_QUERY). */
+    touch: string;
+    /** The viewport is compact (COMPACT_QUERY, `spec:AST-012` FR9). */
+    compact: string;
+    /** Both: a presentation such as a sheet in place of a popover. */
+    compactTouch: string;
+    /**
+     * The iOS WebKit gate, inside `touch` (IOS_SUPPORTS_QUERY): only for a
+     * style iOS WebKit itself requires (the 16px input floor), never a
+     * behaviour; touch behaviour is one model on every touch device.
+     */
+    iosSupports: string;
+};
+//# sourceMappingURL=touchPresentation.stylex.d.ts.map

package/dist/utils/touchPresentation.stylex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"touchPresentation.stylex.d.ts","sourceRoot":"","sources":["../../src/utils/touchPresentation.stylex.ts"],"names":[],"mappings":"AA4BA,eAAO,MAAM,SAAS;IACpB,mDAAmD;;IAEnD,mEAAmE;;IAEnE,kEAAkE;;IAGlE;;;;OAIG;;CAEH,CAAC"}

package/dist/utils/touchPresentation.stylex.js

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchPresentation.stylex.ts
+ * @input Uses StyleX defineConsts
+ * @output Exports touchKeys: the touch presentation resolver's queries as
+ *   StyleX at-rule keys
+ * @position The reference spellings of the touch, compact and iOS-gate
+ *   conditions. Core styles write these as literal keys wherever they need
+ *   them (`spec:AST-094` FR13, `spec:AST-012` FR9), and a test pins each
+ *   literal to these values; utils/touchPresentation.ts holds the same
+ *   queries for script (matchMedia)
+ *
+ * These are the spellings to match. A style that changes with these
+ * conditions writes the same literal key (`'@media (pointer: coarse)'`, the
+ * iOS gate as that media key outside `'@supports (-webkit-touch-callout:
+ * none)'`), and a test pins every literal in core to these values. Do not use
+ * an imported key as a computed StyleX key: it compiles to a different
+ * priority than the literal (6000 against 3200) and reorders the cascade.
+ * The iOS supports gate is only for a style iOS WebKit itself requires (the
+ * 16px input floor), never a behaviour.
+ *
+ * SYNC: When modified, update touchPresentation.ts and
+ * touchPresentation.test.ts.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+export const touchKeys = {
+  touch: "@media (pointer: coarse)",
+  compact: "@media (width < 768px), (height < 500px)",
+  compactTouch: "@media (width < 768px) and (pointer: coarse), (height < 500px) and (pointer: coarse)",
+  iosSupports: "@supports (-webkit-touch-callout: none)"
+};

package/locales/en.json

@@ -803,6 +803,10 @@
     "defaultMessage": "No data",
     "description": "Fallback empty-state text in the table body when there are zero rows. Neutral tone (not error-y); consumers commonly override with something specific like \"No results\"."
   },
+  "@astryx.table.columnResize.resizeColumn": {
+    "defaultMessage": "Resize column {label}",
+    "description": "Accessible name for a Table column-resize handle (a vertical separator between header cells). `label` is the column header's visible text, or the column key when the header has no text."
+  },
   "@astryx.table.filter.allPlaceholder": {
     "defaultMessage": "All",
     "description": "Placeholder on a per-column filter dropdown when nothing is selected, meaning \"no filter — all rows match\". Determiner form (as in \"all values\"), not the pronoun."
@@ -1567,6 +1571,10 @@
     "defaultMessage": "Expand all rows",
     "description": "Aria label for the Table tree-data header toggle when rows are collapsed and clicking it expands them."
   },
+  "@astryx.textArea.counter": {
+    "defaultMessage": "{count, number}/{limit, number}",
+    "description": "Visible character counter at the bottom of a TextArea that has a character limit, for example `62/2,000`. `{count}` is the characters typed so far and `{limit}` the limit; keep both numbers and reorder or change the separator if your language needs to."
+  },
   "@astryx.textArea.charactersRemaining": {
     "defaultMessage": "{count, number} {count, plural, one {character} other {characters}} remaining",
     "description": "Screen-reader-only announcement of how many characters the user can still type before hitting a TextArea's maxLength. Announced politely as the count nears the limit. `{count}` is the number remaining — example: `12 characters remaining`."
@@ -1643,6 +1651,10 @@
     "defaultMessage": "{count, number} of {total, number} selected",
     "description": "Polite screen-reader announcement of how many MultiSelector options are selected out of the total, spoken after each toggle. Live-region text, never shown on screen; example: `3 of 12 selected`."
   },
+  "@astryx.multiSelector.selectedCount": {
+    "defaultMessage": "{count, plural, one {# selected} other {# selected}}",
+    "description": "Visible text on a closed MultiSelector's trigger when it shows a count of the chosen options (`triggerDisplay=\"count\"`), for example `2 selected`. `{count}` is the number of chosen options; use a plural form if your language needs one."
+  },
   "@astryx.multiSelector.createOption": {
     "defaultMessage": "Create \"{query}\"",
     "description": "Label of the first row in a MultiSelector's search panel when `hasCreate` is set and the typed text matches no option. Picking it reports a creation to the caller. `{query}` is the trimmed text the person typed, shown in quotes."
@@ -1693,7 +1705,7 @@
   },
   "@astryx.tokenizer.create": {
     "defaultMessage": "Create \"{value}\"",
-    "description": "Label of the create row inside a Tokenizer's bottom sheet when `hasCreate` is set and the typed text matches no existing item. `{value}` is the typed text, e.g. `Create \"Marketing\"`."
+    "description": "Label of a Tokenizer's create row, in the inline menu and the bottom sheet, when `hasCreate` is set and the typed text matches no existing item. `{value}` is the typed text, e.g. `Create \"Marketing\"`."
   },
   "@astryx.tokenizer.add": {
     "defaultMessage": "Add",

package/locales/pseudo.json

@@ -602,6 +602,9 @@
   "@astryx.table.noData": {
     "defaultMessage": "⟦Ñó ðàţà⟧"
   },
+  "@astryx.table.columnResize.resizeColumn": {
+    "defaultMessage": "⟦Řéšížé çółúɱñ {label}⟧"
+  },
   "@astryx.table.filter.allPlaceholder": {
     "defaultMessage": "⟦Àłł⟧"
   },
@@ -1175,6 +1178,9 @@
   "@astryx.tableTree.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.textArea.counter": {
+    "defaultMessage": "⟦{count, number}/{limit, number}⟧"
+  },
   "@astryx.textArea.charactersRemaining": {
     "defaultMessage": "⟦{count, number} {count, plural, one {character} other {characters}} řéɱàíñíñĝ⟧"
   },
@@ -1232,6 +1238,9 @@
   "@astryx.multiSelector.selectionCount": {
     "defaultMessage": "⟦{count, number} óƒ {total, number} šéłéçţéð⟧"
   },
+  "@astryx.multiSelector.selectedCount": {
+    "defaultMessage": "⟦{count, plural, one {# selected} other {# selected}}⟧"
+  },
   "@astryx.multiSelector.createOption": {
     "defaultMessage": "⟦Çřéàţé \"{query}\"⟧"
   },

package/package.json

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

package/src/AlertDialog/AlertDialog.tsx

@@ -18,18 +18,19 @@
 
 import React, {useId, useCallback} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Dialog} from '../Dialog';
+import {Dialog} from '../Dialog/Dialog';
 import {Layout} from '../Layout/Layout';
 import {LayoutContent} from '../Layout/LayoutContent';
 import {LayoutFooter} from '../Layout/LayoutFooter';
-import {Stack} from '../Stack';
+import {Stack} from '../Stack/Stack';
 import {Heading} from '../Heading/Heading';
 import {Text} from '../Text/Text';
-import {Button, type ButtonVariant} from '../Button';
+import {Button} from '../Button/Button';
+import type {ButtonVariant} from '../Button';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 
 const SMALL_SCREEN_QUERY = '(max-width: 640px)';

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

@@ -91,15 +91,27 @@ async function runState(
   });
 }
 
-test('every alert-dialog expectation is exercised by an AlertDialog state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every alert-dialog expectation is exercised by an AlertDialog state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of ALERT_DIALOG_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      ALERT_DIALOG_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of ALERT_DIALOG_BINDING_STATES) {

package/src/Avatar/Avatar.spec.md

@@ -122,17 +122,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                    |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | The root is a relative, non-shrinking inline-flex box of the resolved size with the shape's radius; it carries the `avatar` target, which reflects `size` and `shape`. A clipped content area fills it with the same radius and suppresses text selection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR2 | The content area shows `src` while it has not failed, then `fallbackSrc` while it has not failed, then initials when the name yields any, then a default person icon at 60% of the box. Each image renders with empty `alt` and `object-fit: cover`. A failure is tracked per source, so a changed `src` or `fallbackSrc` is tried again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
-| FR3 | Initials are the first letter, digit, or emoji of the first and last words of the trimmed `name`, uppercased; leading punctuation in a word is skipped, words with none are dropped, one qualifying word yields one initial, and grapheme clusters are never split. A whitespace-only name counts as absent. Initials and the default icon paint on the `avatar-fallback` target (reflecting `size`) with `--color-neutral`, secondary text, body family, medium weight, and initials at 40% of the box.                                                                                                                                                                                                                                                                                                         | Current source and tests |
-| FR4 | A truthy `status` renders in an absolutely positioned slot outside the clipped content area. On a circle it centers on the circle's edge at the bottom inline-end 45° point; on other shapes it sits at the bottom inline-end corner, offset outward by a quarter of its size. Placement mirrors in right-to-left documents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
-| FR5 | The resolved name is `alt`, else `name` (blank strings count as absent), composed with the status label as the translated "{name}, {status}" when both exist; a status label alone also names the avatar. The status label comes from a string `label` on the passed element, read on every render, and from a label an AvatarStatusDot reports at any wrapper depth, which wins and updates the root before paint without a second render.                                                                                                                                                                                                                                                                                                                                                                      | Current source and tests |
-| FR6 | `href` renders the shared link component (or `as`) with `target` and `rel`; otherwise `onClick` renders a `button type="button"`; otherwise the root is a `div`. Link and button roots carry the `data-avatar-item` marker and the shared focus-visible outline; `onClick` attaches to the link or button. In development, an interactive avatar whose only name is a status label, or that has no name and no caller `aria-label`/`aria-labelledby`, logs a warning.                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
-| FR7 | The tooltip shows the trimmed custom string, else the meaningful `name`, placed above, on hover and keyboard focus; `tooltip={false}` or a blank result shows none. A static avatar with a tooltip and outside a group gets `tabIndex={0}` so keyboard users can reveal it. A custom string is added to `aria-describedby` after any caller value; the default name tooltip is not, because it repeats the name. Implementation gap: a grouped link or button avatar that is not the group's tab stop stops opening its tooltip on focus after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount (Current-state impact). | Current source and tests |
-| FR8 | Inside an AvatarGroup in the same layer (`spec:AST-038` FR7, FR8), the group's size and shape win over the avatar's own props; the root gains a 2px surface-colored ring outside its box and the group's negative inline-start overlap; a static avatar adds no tooltip tab stop, and link and button roots keep the `data-avatar-item` marker so they join the group's roving set. An avatar in a hover card, popover, or other layer opened from a group keeps its own size and shape, gets no ring or overlap, and keeps its tooltip tab stop; a link or button avatar there still carries the marker, so the group's roving focus, which selects marked elements in its DOM subtree, still includes it.                                                                                                      | Current source and tests |
-| FR9 | `ref` reaches the root of every variant. Supported DOM, ARIA, data, and event props reach the root after the derived ARIA, so a caller `aria-label`, `role`, or `aria-hidden` wins (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. Implementation gap: on the static root the component sets `tabIndex` after caller props, so a caller `tabIndex` is replaced (Current-state impact).                                                                                                                                                                                                                                                                                                                | Current source and tests |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root is a relative, non-shrinking inline-flex box of the resolved size with the shape's radius; it carries the `avatar` target, which reflects `size` and `shape`. A clipped content area fills it with the same radius and suppresses text selection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
+| FR2 | The content area shows `src` while it has not failed, then `fallbackSrc` while it has not failed, then initials when the name yields any, then a default person icon at 60% of the box. Each image renders with empty `alt` and `object-fit: cover`. A failure is tracked per source, so a changed `src` or `fallbackSrc` is tried again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
+| FR3 | Initials are the first letter, digit, or emoji of the first and last words of the trimmed `name`, uppercased; leading punctuation in a word is skipped, words with none are dropped, one qualifying word yields one initial, and grapheme clusters are never split. A whitespace-only name counts as absent. Initials and the default icon paint on the `avatar-fallback` target (reflecting `size`) with `--color-neutral`, secondary text, body family, medium weight, and initials at 40% of the box. In forced colors, a lone Avatar's initials and default icon take the surrounding color (`currentColor`): the forced foreground by default, and the system color of a control that paints one around it (GrayText, HighlightText); inside an AvatarGroup they keep the forced foreground on the group's ring. | Current source and tests |
+| FR4 | A truthy `status` renders in an absolutely positioned slot outside the clipped content area. On a circle it centers on the circle's edge at the bottom inline-end 45° point; on other shapes it sits at the bottom inline-end corner, offset outward by a quarter of its size. Placement mirrors in right-to-left documents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and tests |
+| FR5 | The resolved name is `alt`, else `name` (blank strings count as absent), composed with the status label as the translated "{name}, {status}" when both exist; a status label alone also names the avatar. The status label comes from a string `label` on the passed element, read on every render, and from a label an AvatarStatusDot reports at any wrapper depth, which wins and updates the root before paint without a second render.                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
+| FR6 | `href` renders the shared link component (or `as`) with `target` and `rel`; otherwise `onClick` renders a `button type="button"`; otherwise the root is a `div`. Link and button roots carry the `data-avatar-item` marker and the shared focus-visible outline; `onClick` attaches to the link or button. In development, an interactive avatar whose only name is a status label, or that has no name and no caller `aria-label`/`aria-labelledby`, logs a warning.                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
+| FR7 | The tooltip shows the trimmed custom string, else the meaningful `name`, placed above, on hover and keyboard focus; `tooltip={false}` or a blank result shows none. A static avatar with a tooltip and outside a group gets `tabIndex={0}` so keyboard users can reveal it. A custom string is added to `aria-describedby` after any caller value; the default name tooltip is not, because it repeats the name. Implementation gap: a grouped link or button avatar that is not the group's tab stop stops opening its tooltip on focus after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount (Current-state impact).      | Current source and tests |
+| FR8 | Inside an AvatarGroup in the same layer (`spec:AST-038` FR7, FR8), the group's size and shape win over the avatar's own props; the root gains a 2px surface-colored ring outside its box and the group's negative inline-start overlap; a static avatar adds no tooltip tab stop, and link and button roots keep the `data-avatar-item` marker so they join the group's roving set. An avatar in a hover card, popover, or other layer opened from a group keeps its own size and shape, gets no ring or overlap, and keeps its tooltip tab stop; a link or button avatar there still carries the marker, so the group's roving focus, which selects marked elements in its DOM subtree, still includes it.                                                                                                           | Current source and tests |
+| FR9 | `ref` reaches the root of every variant. Supported DOM, ARIA, data, and event props reach the root after the derived ARIA, so a caller `aria-label`, `role`, or `aria-hidden` wins (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. Implementation gap: on the static root the component sets `tabIndex` after caller props, so a caller `tabIndex` is replaced (Current-state impact).                                                                                                                                                                                                                                                                                                                     | Current source and tests |
 
 ### Allowed variation
 
@@ -227,17 +227,17 @@ no root part, so no anatomy-theming block is declared.
 
 ## Verification map
 
-| Contract           | Verification                                                                                                                                                | Representative states                                              | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                    | Audit section           |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
-| FR1–FR3            | `Avatar.test.tsx` fallback, initials, retry, and target tests                                                                                               | Photo, failure, initials, punctuation, emoji, blank name; `lg` box | A wrong initials-or-icon fallback, split grapheme, lost retry, missing target, or wrong `lg` box size fails. Gap: no test sets `src` and `fallbackSrc` together, so the `src`-first order is unchecked, and sizes other than `lg` and numeric sizes are visible only in `Avatar.stories.tsx`.                                                                      | `audit:Avatar/behavior` |
-| FR4                | `Avatar.test.tsx` shape and status tests; `Avatar.stories.tsx` status fixtures                                                                              | Every shape with a status; RTL                                     | A missing status slot fails. Gap: the tests assert presence only, so the slot's position, mirroring, and offset are visible only in the rendered fixtures.                                                                                                                                                                                                         | `audit:Avatar/layout`   |
-| FR5, AR1, AR2, PR1 | `Avatar.test.tsx` status-name and wrapper suites                                                                                                            | Direct, wrapped, changing, removed labels                          | A lost composed name, extra render, or stale label fails.                                                                                                                                                                                                                                                                                                          | `audit:Avatar/a11y`     |
-| FR6, AR3           | `Avatar.test.tsx` interactivity suite                                                                                                                       | Link, button, static, dev warnings                                 | A wrong root, a missing marker, or a missing warning fails. Gap: no test checks the focus-visible outline.                                                                                                                                                                                                                                                         | `audit:Avatar/behavior` |
-| FR7, AR4, AR5      | `Avatar.test.tsx` name-tooltip suite                                                                                                                        | Default, custom, disabled, blank                                   | A missing tab stop, a duplicated description, or a lost ref fails. Gap: no test covers a grouped avatar's tooltip after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount. | `audit:Avatar/a11y`     |
-| FR8                | `Avatar.test.tsx` group shape tests; `AvatarGroup.test.tsx` size-cascade, overlap, and roving suites; `layerScopedContext.test.tsx` AvatarGroup layer tests | Inside a group; in a layer opened from a group; outside a group    | An avatar size or shape prop winning inside a group, a lost overlap, an interactive avatar missing from the roving set, or a static avatar in a layer losing its tooltip tab stop fails. Gap: no test asserts the ring, or size and shape inside a layer.                                                                                                          | `audit:Avatar/behavior` |
-| FR9, AR6           | `Avatar.test.tsx` consumer-ARIA override suite                                                                                                              | Static and interactive roots                                       | A derived value replacing a caller `aria-label`, `role`, or `aria-hidden` fails. Gap: no test covers a caller `tabIndex`.                                                                                                                                                                                                                                          | `audit:Avatar/a11y`     |
-| AR1–AR3, AR5       | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                                                            | Named, decorative, status-composed, interactive                    | Gap: no accessibility-tree check proves the computed roles, names, or description; the unit tests query the DOM.                                                                                                                                                                                                                                                   | `audit:Avatar/a11y`     |
-| AR7                | `Avatar.stories.tsx` interactive and size fixtures in a browser                                                                                             | Interactive avatars at every size                                  | Gap: no automated target-size check; the undersized targets are the recorded gap.                                                                                                                                                                                                                                                                                  | `audit:Avatar/a11y`     |
+| Contract           | Verification                                                                                                                                                | Representative states                                                                                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                              | Audit section           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
+| FR1–FR3            | `Avatar.test.tsx` fallback, initials, retry, and target tests; `AvatarForcedColors.a11y.chromium.spec.ts` in real Chromium with forced colors emulated      | Photo, failure, initials, punctuation, emoji, blank name; `lg` box; forced colors alone, inside GrayText and HighlightText, and grouped | A wrong initials-or-icon fallback, split grapheme, lost retry, missing target, wrong `lg` box size, or forced-colors initials that miss the surrounding system color (lone) or leave the forced foreground (grouped) fails. Gap: no test sets `src` and `fallbackSrc` together, so the `src`-first order is unchecked, and sizes other than `lg` and numeric sizes are visible only in `Avatar.stories.tsx`. | `audit:Avatar/behavior` |
+| FR4                | `Avatar.test.tsx` shape and status tests; `Avatar.stories.tsx` status fixtures                                                                              | Every shape with a status; RTL                                                                                                          | A missing status slot fails. Gap: the tests assert presence only, so the slot's position, mirroring, and offset are visible only in the rendered fixtures.                                                                                                                                                                                                                                                   | `audit:Avatar/layout`   |
+| FR5, AR1, AR2, PR1 | `Avatar.test.tsx` status-name and wrapper suites                                                                                                            | Direct, wrapped, changing, removed labels                                                                                               | A lost composed name, extra render, or stale label fails.                                                                                                                                                                                                                                                                                                                                                    | `audit:Avatar/a11y`     |
+| FR6, AR3           | `Avatar.test.tsx` interactivity suite                                                                                                                       | Link, button, static, dev warnings                                                                                                      | A wrong root, a missing marker, or a missing warning fails. Gap: no test checks the focus-visible outline.                                                                                                                                                                                                                                                                                                   | `audit:Avatar/behavior` |
+| FR7, AR4, AR5      | `Avatar.test.tsx` name-tooltip suite                                                                                                                        | Default, custom, disabled, blank                                                                                                        | A missing tab stop, a duplicated description, or a lost ref fails. Gap: no test covers a grouped avatar's tooltip after a re-render that re-attaches its root element: a new `status` element (an inline `status` prop creates one on every parent render), a changed `name`, `alt`, locale, caller ARIA, or caller `ref`, or a tooltip that turns on after mount.                                           | `audit:Avatar/a11y`     |
+| FR8                | `Avatar.test.tsx` group shape tests; `AvatarGroup.test.tsx` size-cascade, overlap, and roving suites; `layerScopedContext.test.tsx` AvatarGroup layer tests | Inside a group; in a layer opened from a group; outside a group                                                                         | An avatar size or shape prop winning inside a group, a lost overlap, an interactive avatar missing from the roving set, or a static avatar in a layer losing its tooltip tab stop fails. Gap: no test asserts the ring, or size and shape inside a layer.                                                                                                                                                    | `audit:Avatar/behavior` |
+| FR9, AR6           | `Avatar.test.tsx` consumer-ARIA override suite                                                                                                              | Static and interactive roots                                                                                                            | A derived value replacing a caller `aria-label`, `role`, or `aria-hidden` fails. Gap: no test covers a caller `tabIndex`.                                                                                                                                                                                                                                                                                    | `audit:Avatar/a11y`     |
+| AR1–AR3, AR5       | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                                                            | Named, decorative, status-composed, interactive                                                                                         | Gap: no accessibility-tree check proves the computed roles, names, or description; the unit tests query the DOM.                                                                                                                                                                                                                                                                                             | `audit:Avatar/a11y`     |
+| AR7                | `Avatar.stories.tsx` interactive and size fixtures in a browser                                                                                             | Interactive avatars at every size                                                                                                       | Gap: no automated target-size check; the undersized targets are the recorded gap.                                                                                                                                                                                                                                                                                                                            | `audit:Avatar/a11y`     |
 
 ## Decision log
 

package/src/Avatar/Avatar.tsx

@@ -193,6 +193,19 @@ const styles = stylex.create({
     fontWeight: fontWeightVars['--font-weight-medium'],
     textTransform: 'uppercase',
   },
+  // After `fallback` on a lone Avatar: in forced colors its initials and
+  // default icon take the color around them, which the browser forces to
+  // CanvasText, so a control that paints itself disabled (GrayText) or
+  // selected (HighlightText) carries them with it; an
+  // authored color would be forced to CanvasText whatever the control shows.
+  // A grouped face keeps it: its ring's opaque fill is forced to Canvas, so
+  // only CanvasText is sure to read on it.
+  loneFallback: {
+    color: {
+      default: colorVars['--color-text-secondary'],
+      '@media (forced-colors: active)': 'currentColor',
+    },
+  },
   status: {
     position: 'absolute',
   },
@@ -784,6 +797,7 @@ export function Avatar({
               themeProps('avatar-fallback', {size: resolvedSize}),
               stylex.props(
                 styles.fallback,
+                avatarGroup == null && styles.loneFallback,
                 dynamicStyles.fontSize(numericSize),
               ),
             )}>
@@ -794,7 +808,10 @@ export function Avatar({
           <div
             {...mergeProps(
               themeProps('avatar-fallback', {size: resolvedSize}),
-              stylex.props(styles.fallback),
+              stylex.props(
+                styles.fallback,
+                avatarGroup == null && styles.loneFallback,
+              ),
             )}>
             <DefaultIcon size={numericSize} />
           </div>