An open source design system that's fully customizable and agent ready
TypeScript
spec(i18n, Resizable, AST-103): factories take announcement and label options with a catalog default (#9395)
Cindy Zhangc5fbecb8dbf7
diff --git a/docs/architecture/internationalization.md b/docs/architecture/internationalization.mdindex e3593e8838..6f404a0c1c 100644--- a/docs/architecture/internationalization.md+++ b/docs/architecture/internationalization.md@@ -58,11 +58,12 @@ deciding_specs: []{"scope": "global","triggers": {- "accessibility": ["INV1", "INV1a", "INV7"],+ "accessibility": ["INV1", "INV1a", "INV3a", "INV7"],"behavior": ["INV1","INV1a","INV3",+ "INV3a","INV4","INV5","INV7",@@ -73,7 +74,7 @@ deciding_specs: []],"compatibility": ["INV2", "INV9", "INV10"],"layout": ["INV11", "INV12"],- "public-api": ["INV1", "INV1a", "INV2", "INV7", "INV9", "INV10"],+ "public-api": ["INV1", "INV1a", "INV2", "INV3a", "INV7", "INV9", "INV10"],"react-runtime": ["INV3", "INV4", "INV11", "INV12", "INV13"]}}@@ -191,6 +192,21 @@ for all 30 shipped locales plus `pseudo`.- **INV3 — No provider is deterministic English.** Components used outside aprovider resolve Astryx strings from the shipped English catalog, expose locale`en`, direction `ltr`, and do not read the browser or host locale implicitly.+- **INV3a — Factories take an option for each string they announce or show.**+ A public non-React factory (`architecture:public-component-api` INV22) that+ announces or shows Astryx text (a live-region announcement, an `aria-*` or+ `title` value, or a visible label) takes an option for each such string. A+ factory with one string takes a flat optional string option for it, such as+ `createResizable`'s `collapsedLabel` (a caller-supplied accessible name that+ already exists as its own option, such as `label`, stays flat and does not+ count toward the factory's strings); a factory with more than one groups+ them under one optional `labels` object, each key optional. An absent option+ or key falls back to the catalog message, translated when the factory's+ React wrapper runs under a provider and English without one; a given string+ replaces that message, including over a provider's translation. No factory+ takes a translator: translation comes only from a provider. The rule covers+ INV22 factories. Per-message options are the factory mechanism; the+ external-runtime adapter (INV14) stays a separate, broader decision.- **INV4 — Runtime locale changes are live.** Re-rendering the provider with a newlocale, messages, overrides, or direction updates consumers in that subtree.Astryx does not persist or select the application's locale.@@ -402,6 +418,7 @@ callers remain conformance work and do not relax INV1a, INV8, INV9, or INV10.| INV1, INV1a, INV7 | hardcoded-string lint, catalog tests, component translation tests with a non-English provider | Astryx-owned text bypasses the catalog, an announcement or count is assembled from fragments or a hand-rolled plural, or non-string output reaches visible/AT attributes || INV2, INV13, INV14 | export drift checks, public i18n tests, compatibility review | A parallel/replacement runtime lands without migration, or client hooks claim server behavior || INV3–INV5 | resolver and provider rerender tests | no-provider output depends on the host, locale swaps stay stale, fallback order changes, or malformed-locale behavior is described as graceful |+| INV3a | factory unit tests: a flat option or `labels` key replaces its message, including under a provider, and outside a provider its absence announces or shows shipped English; wrapper tests: under a non-English provider its absence gives the translation. Evidence gap: no factory test covers a flat option or `labels` key yet | a factory announces or shows Astryx text that no option or `labels` key can replace, groups more than one string outside one `labels` object, takes a translator, ignores a given string, or gives something other than the catalog message when it is absent || INV6 | `check:i18n-catalog`, key-format lint, and focused mutation tests | stale/malformed keys, malformed ICU, or source/translation runtime-contract drift passes CI || INV15 | generator tests, `check:i18n-runtime`, package-export drift check, provider/resolver runtime-catalog tests | a generated module carries descriptions or is committed, a malformed entry projects instead of failing, a rich export path changes, or a `RuntimeCatalog` input is rejected or leaks a non-rich context shape || INV16 | build-plugin unit and real-build tests | a rich or generated locale import fails to resolve through the standard plugin |diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex b57ecee3b0..cdf8b74f93 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -229,7 +229,8 @@ guidance owns the process used to propose and test APIs.`useAnimatedLayout`, `useEntryAnimation`, `useContainerReveal`,`useTouchTrigger`, `useTableRowExpansion`, and `useTableColumnResize`. A hookwhose current signature cannot delegate gains a ref-taking signature beside- it; the old signature is deprecated under INV9.+ it; the old signature is deprecated under INV9. A factory's announced and shown+ strings follow `architecture:internationalization` INV3a's options.- **INV23 — Each private data attribute has one owner module.** A`data-astryx-*` attribute is private unless this invariant names it public.Each private attribute has one internal owner module in the package thatdiff --git a/docs/specs/AST-103-reorderable/spec.md b/docs/specs/AST-103-reorderable/spec.mdindex 2981d3f4b4..52ccadc076 100644--- a/docs/specs/AST-103-reorderable/spec.md+++ b/docs/specs/AST-103-reorderable/spec.md@@ -143,6 +143,32 @@ const {detach} = reorderable.attach(listElement, {collections, or attached to two containers, reorders each on its own andmoves nothing between them; its `start` targets the one mounted or attachedlast, with a development warning.+ `options` also takes `labels?: ReorderableLabels`, which+ holds every string the object announces or shows+ (`architecture:internationalization` INV3a):+ - announcements: `pickedUp` and `dropped` (a drag's pick-up and drop, with+ position and count), `cancelled` (a cancelled drag, back to its+ position), `place`, `placeAtTop`, `placeAtEnd`, `placeInGrid`, and `placeInTree` (FR4's+ move announcements, `placeInTree` adding the parent), `refused` (a move past a rejected row), `notMoved`+ (FR4b's move the app did not apply), `modeDone` (leaving reorder mode),+ and `unnamedItem` (what announcements call an item with no text, such as+ "Item 2");+ - shown labels: `handle` (the handle's name, "Reorder" and the item's+ label), `handleVerb` ("Reorder" alone, read before the row's own label+ when that label names the handle), `unnamedHandle` (the handle of an item+ with no text, such as "Reorder item 3"), `handleHint` (the handle's+ description of dragging and reorder mode), `moveUp`, `moveDown`,+ `moveLeft`, and `moveRight` (the hint's move buttons), and `done` (the+ hint's Done).++ Every key is optional. An absent key falls back to the catalog message,+ translated when a collection renders under a provider and English without+ one; a given string replaces that message, including over a provider's+ translation. A templated message's key takes the catalog's ICU template+ with the same arguments, such as `place`'s label, position, count, and+ neighbors, or `dropped`'s position and count. Implementation gap: not+ built; `labels` does not exist yet, so every string is the catalog's.+- **FR2 — Present means enabled.** A collection that accepts reordering takesthe object through one `reorderable` prop; there is no separate boolean.With the prop absent the collection renders no handle, registers no reorder@@ -234,9 +260,11 @@ const {detach} = reorderable.attach(listElement, {by the end of the task that ran `onReorder` is refused and announced, such as"Can't move King of hearts". Once a move commits, `attach` focuses the moveditem's handle as `items()` returns it and scrolls it into view, so focus- stays on the handle however the app moved or re-rendered the item. `attach` resolves its strings and number formats as a component outside a- provider does, from the shipped English catalog- (`architecture:internationalization` INV3). `detach` ends any drag or reorder+ stays on the handle however the app moved or re-rendered the item. `attach` takes each string from the object's+ `labels` (FR1), an absent key falling back to the shipped English catalog,+ and formats numbers as a component outside a provider does+ (`architecture:internationalization` INV3, INV3a). Implementation gap: not+ built; `attach` uses the shipped English catalog for every string. `detach` ends any drag or reordermode in progress, calling nothing, andremoves every listener, observer, timer, element (that container included),and attribute `attach` added, restoring each handle's own role, name, and tab order; and creating or importing the object does no DOM@@ -271,17 +299,17 @@ const {detach} = reorderable.attach(listElement, {## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1, FR6–FR8 | Public-API review, type tests, and descriptor checks | the factory's options; a collection's `reorderable` type; the factory's and List's descriptors | an extra gesture, timing, or animation option, an experimental name or subpath, a missing descriptor, or a second public reorder API, fails |-| FR2 | Bundle and runtime check of a collection with and without the prop | without the prop; with the prop | reorder code in the bundle, a handle, or a reorder listener without the prop fails; the measured cost is recorded in the pull request |-| FR3 | Browser tests with real touch input and a mouse (`spec:AST-013` FR10) | a hold and drag; a flick; a drop; a cancelled drag; Reduce Motion; a fanned hand with custom `positions`; a list without them; a `positions` array of the wrong length; a tree with `positions`; custom `positions` beside a rejected end row; a pen drag on a fine and on a coarse primary pointer | a drag that starts off the handle, a commit before the drop, two callbacks for one drag, a callback on cancel, travel under Reduce Motion, a drop that ignores `positions` of the right length, a wrong-length array or a tree whose drops do not come from the measured layout, a drop outside the drop range, a mouse drag, or a pen drag on a fine primary pointer that waits for a hold, or a pen drag on a coarse primary pointer that starts without one, or a call without `positions` whose behavior changes fails |-| FR4 | Keyboard, mouse, and announcement-routing tests of reorder mode (`spec:AST-009` FR17) | entering by click, Enter, and Space; arrows in vertical, horizontal, and grid collections; Up, Down, Left, and Right in a tree; each move's announcement at the top, middle, and end; a move past a rejected row; Escape and a second activation; focus and scroll after each move | a move that does not commit at once, an announcement missing, repeated, or before render, a move past a rejected row at either end, or a mid-list rejected row that blocks a move, focus leaving the handle, or moves undone on exit fails |-| FR4 hint | Browser tests with a mouse, a finger, and a keyboard | the hint's axis in vertical, horizontal, and grid collections; each move button and Done; a tap-only reorder; the hint's theme roles | a hint off the keyboard hint's layer, anchoring, or theme roles, buttons that ignore taps or are hidden from assistive technology, a button whose move or announcement differs from its key, focus leaving the handle, or a hint that outlives the mode fails |-| FR4 two-dimensional | Keyboard and announcement-routing tests on a wrapping card grid, left-to-right and right-to-left | Left and Right across a row end; Up and Down between full rows and into a short last row; announcements with row and column; the hint's four buttons; a resize that changes the column count | a move off reading order, a mirrored direction wrong in right-to-left, a short-row move that is not clamped to its last position, a missing row or column, or a column count read from anything but layout fails |-| FR4a | Keyboard, mouse, and announcement-routing tests of `start(key)` | `start` from a context-menu item and a toolbar button; a key that is not reorderable, not mounted, or unknown; an object re-created each render; one object on two collections | `start` that does not focus and scroll to the handle, a hint or announcement that differs from the handle's mode, a missing-key call that throws or acts, or a two-collection call without a development warning fails |-| FR4b | Browser tests of `attach` on plain elements with a mouse, a finger, a pen, and the keyboard, and listener counts after `detach` | a drag, a cancelled drag, reorder mode, a fanned layout with `positions`, a move the app applies and one it does not, `detach` mid-drag, a server import, a page in another language, an item element with no accessible name, an item `isReorderable` rejects, a keyless item, `start(key)` on an attached item, a handle with its own `tabindex="-1"`, a container inside a modal dialog the page opens, one object attached to two containers, a pen drag on a fine and on a coarse primary pointer, a move the app applies by moving the item's element and one by re-rendering it | a missing drag, mode, or announcement on plain elements; a handle without FR4's role, pressed state, or name, one named "Reorder" alone when the item has text, or one outside the Tab order; a rejected or keyless item whose handle is a Reorder toggle or can be dragged; a `start(key)` that does not reach an attached item; a move announced before `items()` reports it, or one the app did not apply left unrefused; a drag or mode still running, or a listener, observer, hint element, handle attribute, or changed tab order left, after `detach`, strings other than the shipped English catalog's, an announcement inside a page-opened modal that reaches only the page-body channel, a move between two containers or a `start` there without the development warning, a pen drag on a fine primary pointer that waits for a hold, or one on a coarse primary pointer that starts without one,, focus not on the moved item's handle after a move, or DOM work at import fails |-| FR5 | Element and listener counts of a list with and without the prop | a row at rest; a row picked up; a row dropped | more than one added element per row, a grip drawn with elements, a per-row listener, a second preview, a source that leaves its place, a preview left after the drop, or a preview that assistive technology reaches, fails |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR6–FR8 | Public-API review, type tests, and descriptor checks | the factory's options, `ReorderableLabels`' keys included; a collection's `reorderable` type; the factory's and List's descriptors | an extra gesture, timing, or animation option, an experimental name or subpath, a missing descriptor, a second public reorder API, a string the object announces or shows that no `labels` key replaces, or a translator option, fails |+| FR2 | Bundle and runtime check of a collection with and without the prop | without the prop; with the prop | reorder code in the bundle, a handle, or a reorder listener without the prop fails; the measured cost is recorded in the pull request |+| FR3 | Browser tests with real touch input and a mouse (`spec:AST-013` FR10) | a hold and drag; a flick; a drop; a cancelled drag; Reduce Motion; a fanned hand with custom `positions`; a list without them; a `positions` array of the wrong length; a tree with `positions`; custom `positions` beside a rejected end row; a pen drag on a fine and on a coarse primary pointer | a drag that starts off the handle, a commit before the drop, two callbacks for one drag, a callback on cancel, travel under Reduce Motion, a drop that ignores `positions` of the right length, a wrong-length array or a tree whose drops do not come from the measured layout, a drop outside the drop range, a mouse drag, or a pen drag on a fine primary pointer that waits for a hold, or a pen drag on a coarse primary pointer that starts without one, or a call without `positions` whose behavior changes fails |+| FR4 | Keyboard, mouse, and announcement-routing tests of reorder mode (`spec:AST-009` FR17) | entering by click, Enter, and Space; arrows in vertical, horizontal, and grid collections; Up, Down, Left, and Right in a tree; each move's announcement at the top, middle, and end; a move past a rejected row; Escape and a second activation; focus and scroll after each move | a move that does not commit at once, an announcement missing, repeated, or before render, a move past a rejected row at either end, or a mid-list rejected row that blocks a move, focus leaving the handle, or moves undone on exit fails |+| FR4 hint | Browser tests with a mouse, a finger, and a keyboard | the hint's axis in vertical, horizontal, and grid collections; each move button and Done; a tap-only reorder; the hint's theme roles | a hint off the keyboard hint's layer, anchoring, or theme roles, buttons that ignore taps or are hidden from assistive technology, a button whose move or announcement differs from its key, focus leaving the handle, or a hint that outlives the mode fails |+| FR4 two-dimensional | Keyboard and announcement-routing tests on a wrapping card grid, left-to-right and right-to-left | Left and Right across a row end; Up and Down between full rows and into a short last row; announcements with row and column; the hint's four buttons; a resize that changes the column count | a move off reading order, a mirrored direction wrong in right-to-left, a short-row move that is not clamped to its last position, a missing row or column, or a column count read from anything but layout fails |+| FR4a | Keyboard, mouse, and announcement-routing tests of `start(key)` | `start` from a context-menu item and a toolbar button; a key that is not reorderable, not mounted, or unknown; an object re-created each render; one object on two collections | `start` that does not focus and scroll to the handle, a hint or announcement that differs from the handle's mode, a missing-key call that throws or acts, or a two-collection call without a development warning fails |+| FR4b | Browser tests of `attach` on plain elements with a mouse, a finger, a pen, and the keyboard, and listener counts after `detach` | a drag, a cancelled drag, reorder mode, a fanned layout with `positions`, a move the app applies and one it does not, `detach` mid-drag, a server import, a page in another language with every `labels` key given and with none, a given key under a provider, an item element with no accessible name, an item `isReorderable` rejects, a keyless item, `start(key)` on an attached item, a handle with its own `tabindex="-1"`, a container inside a modal dialog the page opens, one object attached to two containers, a pen drag on a fine and on a coarse primary pointer, a move the app applies by moving the item's element and one by re-rendering it | a missing drag, mode, or announcement on plain elements; a handle without FR4's role, pressed state, or name, one named "Reorder" alone when the item has text, or one outside the Tab order; a rejected or keyless item whose handle is a Reorder toggle or can be dragged; a `start(key)` that does not reach an attached item; a move announced before `items()` reports it, or one the app did not apply left unrefused; a drag or mode still running, or a listener, observer, hint element, handle attribute, or changed tab order left, after `detach`, a string other than its given `labels` key or, without one, the shipped English catalog's, an announcement inside a page-opened modal that reaches only the page-body channel, a move between two containers or a `start` there without the development warning, a pen drag on a fine primary pointer that waits for a hold, or one on a coarse primary pointer that starts without one, focus not on the moved item's handle after a move, or DOM work at import fails. Evidence gap: `labels` is not built, so no test covers a given key yet. |+| FR5 | Element and listener counts of a list with and without the prop | a row at rest; a row picked up; a row dropped | more than one added element per row, a grip drawn with elements, a per-row listener, a second preview, a source that leaves its place, a preview left after the drop, or a preview that assistive technology reaches, fails |## Decision log@@ -355,6 +383,19 @@ second hint pattern.Rejected: a menu of Move before and Move after.+### DEC-6 — One `labels` object holds every string++**Reference:** `spec:AST-103/DEC-6`+**Decider:** `cixzhang`, `2026-11-01`++A page without a provider, such as one attaching plain elements, still needs+its own language, and the object announces and shows many strings. One+optional `labels` object holds them, each key falling back to the catalog+message, as `architecture:internationalization` INV3a gives a factory with+more than one string; translation itself stays with the provider.++Rejected: a translator-function option, and one flat option per string.+## Open questionsNone.diff --git a/docs/specs/components/Resizable/Resizable.spec.md b/docs/specs/components/Resizable/Resizable.spec.mdindex 346a4e38ee..4e1153f2d3 100644--- a/docs/specs/components/Resizable/Resizable.spec.md+++ b/docs/specs/components/Resizable/Resizable.spec.md@@ -103,6 +103,10 @@ Consumer migration instructions belong in consumer docs and release notes.`architecture:public-component-api` INV7 has handlers compose.- **Collapse and open do not slide yet (FR8).** A LayoutPanel's pane jumpsclosed and open, where `spec:AST-105` FR9 slides it.+- **No `collapsedLabel` yet (AR1).** `createResizable` and the options form+ of `useResizable` are not built, so a caller without a provider cannot+ replace the English "Collapsed" announcement, where+ `architecture:internationalization` INV3a gives it a per-message option.- **`shrinkOrder` is inert.** useResizable accepts and documents`shrinkOrder`, but no code reads it, so it has no effect.@@ -198,6 +202,12 @@ Consumer migration instructions belong in consumer docs and release notes.`role="separator"` with an accessible name, `aria-orientation` (the axis thedivider lies along), `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` inpixels, `aria-valuetext` while collapsed, and `aria-disabled` when disabled.+ `CreateResizableOptions`, which `useResizable(handleRef, options)` also+ takes, has `collapsedLabel?: string`, announced as the Handle's+ `aria-valuetext` while collapsed; absent, the catalog's "Collapsed"+ (`architecture:internationalization` INV3a). Implementation gap:+ `CreateResizableOptions` and the options form of `useResizable` are not+ built, so `collapsedLabel` does not exist yet.ArrowRight and ArrowDown move the divider toward the end of its axis andArrowLeft and ArrowUp toward the start, the inline arrows following thereading direction under RTL, with Shift for a larger step, so the pane grows