An open source design system that's fully customizable and agent ready
TypeScript
feat(core)!: remove deprecated APIs for 0.6 (#6118)
Cindy Zhang3c50fccc8532
diff --git a/.changeset/migrate-deprecated-core-apis.md b/.changeset/migrate-deprecated-core-apis.mdnew file mode 100644index 0000000000..5debfd4e75--- /dev/null+++ b/.changeset/migrate-deprecated-core-apis.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] Add `astryx upgrade` transforms for the Core 0.6 deprecated-API removals: focus direction overrides, the hooks-path IME helper import, and Resizable pixel-bound aliases.++@cixzhangdiff --git a/.changeset/remove-deprecated-core-apis.md b/.changeset/remove-deprecated-core-apis.mdnew file mode 100644index 0000000000..6bfaac2119--- /dev/null+++ b/.changeset/remove-deprecated-core-apis.md@@ -0,0 +1,9 @@+---+'@astryxdesign/core': minor+---++[breaking] Remove deprecated focus-direction overrides, the hooks-path `isImeKeyEvent` re-export, and Resizable pixel-bound aliases.++**Codemod:** Run `npx astryx upgrade --apply` before updating to 0.6.0. It removes focus-hook `isRtl`, moves `isImeKeyEvent` imports to `@astryxdesign/core/utils`, and renames `minSizePx`/`maxSizePx` to `minSize`/`maxSize`.++@cixzhangdiff --git a/apps/docsite/src/app/playground/PlaygroundClient.tsx b/apps/docsite/src/app/playground/PlaygroundClient.tsxindex a179766570..d98861b09e 100644--- a/apps/docsite/src/app/playground/PlaygroundClient.tsx+++ b/apps/docsite/src/app/playground/PlaygroundClient.tsx@@ -325,8 +325,8 @@ export function PlaygroundClient() {const editorPanel = useResizable({defaultSize: 440,- minSizePx: 340,- maxSizePx: 760,+ minSize: 340,+ maxSize: 760,autoSaveId: 'astryx-playground-left-width',});diff --git a/apps/storybook/stories/Resizable.stories.tsx b/apps/storybook/stories/Resizable.stories.tsxindex 7b6ef8f83d..bd58b5a219 100644--- a/apps/storybook/stories/Resizable.stories.tsx+++ b/apps/storybook/stories/Resizable.stories.tsx@@ -49,8 +49,8 @@ export const HorizontalSplit: Story = {render: () => {const sidebar = useResizable({defaultSize: 250,- minSizePx: 150,- maxSizePx: 500,+ minSize: 150,+ maxSize: 500,});return (<div {...stylex.props(ps.shell)}>@@ -96,8 +96,8 @@ export const VerticalSplit: Story = {render: () => {const top = useResizable({defaultSize: 250,- minSizePx: 100,- maxSizePx: 350,+ minSize: 100,+ maxSize: 350,direction: 'vertical',});return (@@ -141,7 +141,7 @@ export const Collapsible: Story = {render: () => {const sidebar = useResizable({defaultSize: 260,- minSizePx: 180,+ minSize: 180,collapsible: true,collapsedSize: 60,});@@ -198,13 +198,13 @@ export const ThreePanelIDE: Story = {render: () => {const explorer = useResizable({defaultSize: 220,- minSizePx: 150,- maxSizePx: 400,+ minSize: 150,+ maxSize: 400,});const editor = useResizable({defaultSize: 280,- minSizePx: 100,- maxSizePx: 350,+ minSize: 100,+ maxSize: 350,direction: 'vertical',});return (@@ -268,8 +268,8 @@ export const SnapPoints: Story = {render: () => {const sidebar = useResizable({defaultSize: 260,- minSizePx: 56,- maxSizePx: 600,+ minSize: 56,+ maxSize: 600,snaps: [56, 160, 260, 400],});const isRail = sidebar.size <= 60;@@ -316,8 +316,8 @@ export const HiddenPill: Story = {render: () => {const sidebar = useResizable({defaultSize: 250,- minSizePx: 150,- maxSizePx: 500,+ minSize: 150,+ maxSize: 500,});return (<div {...stylex.props(ps.shell)}>@@ -357,7 +357,7 @@ export const HiddenPill: Story = {/** Disabled handle — divider visible but non-interactive. */export const Disabled: Story = {render: () => {- const sidebar = useResizable({defaultSize: 250, minSizePx: 150});+ const sidebar = useResizable({defaultSize: 250, minSize: 150});return (<div {...stylex.props(ps.shell)}><Layout@@ -392,8 +392,8 @@ export const WithLayout: Story = {render: () => {const sidebar = useResizable({defaultSize: 260,- minSizePx: 180,- maxSizePx: 450,+ minSize: 180,+ maxSize: 450,collapsible: true,collapsedSize: 50,});@@ -463,8 +463,8 @@ export const WithAppShell: Story = {render: () => {const nav = useResizable({defaultSize: 260,- minSizePx: 200,- maxSizePx: 400,+ minSize: 200,+ maxSize: 400,collapsible: true,collapsedSize: 50,snaps: [56, 260],@@ -524,8 +524,8 @@ export const WithEmbeddedFrame: Story = {render: () => {const sidebar = useResizable({defaultSize: 200,- minSizePx: 120,- maxSizePx: 520,+ minSize: 120,+ maxSize: 520,});return (<div {...stylex.props(ps.shell)}>diff --git a/apps/storybook/stories/useResizable.stories.tsx b/apps/storybook/stories/useResizable.stories.tsxindex f786bee757..a82a8e543a 100644--- a/apps/storybook/stories/useResizable.stories.tsx+++ b/apps/storybook/stories/useResizable.stories.tsx@@ -200,8 +200,8 @@ export const Horizontal: Story = {render: () => {const sidebar = useResizable({defaultSize: 200,- minSizePx: 100,- maxSizePx: 500,+ minSize: 100,+ maxSize: 500,});return (<div {...stylex.props(s.shell)}>@@ -231,8 +231,8 @@ export const Vertical: Story = {render: () => {const top = useResizable({defaultSize: 150,- minSizePx: 60,- maxSizePx: 250,+ minSize: 60,+ maxSize: 250,direction: 'vertical',});return (@@ -263,13 +263,13 @@ export const ThreePanel: Story = {render: () => {const left = useResizable({defaultSize: 180,- minSizePx: 120,- maxSizePx: 300,+ minSize: 120,+ maxSize: 300,});const right = useResizable({defaultSize: 220,- minSizePx: 150,- maxSizePx: 400,+ minSize: 150,+ maxSize: 400,});return (<div {...stylex.props(s.shell)}>@@ -312,13 +312,13 @@ export const Nested: Story = {render: () => {const sidebar = useResizable({defaultSize: 200,- minSizePx: 120,- maxSizePx: 350,+ minSize: 120,+ maxSize: 350,});const editor = useResizable({defaultSize: 200,- minSizePx: 80,- maxSizePx: 250,+ minSize: 80,+ maxSize: 250,direction: 'vertical',});return (@@ -383,8 +383,8 @@ export const AlwaysVisible: Story = {render: () => {const sidebar = useResizable({defaultSize: 250,- minSizePx: 100,- maxSizePx: 500,+ minSize: 100,+ maxSize: 500,});return (<div {...stylex.props(s.shell)}>@@ -414,13 +414,13 @@ export const MixedContainers: Story = {render: () => {const sidebar = useResizable({defaultSize: 200,- minSizePx: 120,- maxSizePx: 350,+ minSize: 120,+ maxSize: 350,});const editor = useResizable({defaultSize: 200,- minSizePx: 80,- maxSizePx: 250,+ minSize: 80,+ maxSize: 250,direction: 'vertical',});return (diff --git a/docs/specs/AST-010/spec.md b/docs/specs/AST-010/spec.mdindex df7d3fae07..4d90e9a2ad 100644--- a/docs/specs/AST-010/spec.md+++ b/docs/specs/AST-010/spec.md@@ -8,7 +8,7 @@ archive_reason: nullsuperseded_by: nullapproved_by: cixzhangapproved_at: 2026-08-31-phase: accepted+phase: shippedowners: [cixzhang]affects_architecture: [architecture:public-component-api]affects_families: [family:layout-regions]@@ -131,9 +131,8 @@ record is updated alongside that implementation.`min` or `max` value is a finite non-negative `PixelWidth`. A structured valuewith neither bound, both bounds, another discriminator, or any invalid number isinvalid. An invalid `defaultSize` MUST use 250px before normal bounds clamping;- an invalid `minSize` or `minSizePx` MUST use 50px; and an invalid `maxSize` or- `maxSizePx` MUST use unbounded `Infinity`. Explicit `maxSizePx: Infinity`- remains valid for compatibility because a shipped template uses it.+ an invalid `minSize` MUST use 50px; and an invalid `maxSize` MUST use unbounded+ `Infinity`. Explicit `maxSize: Infinity` remains valid.Development MUST warn for every fallback; production MUST use the same fallbackwithout warning. After initialization, an invalid raw value MUST NOT directlyreplace a persisted or otherwise legal selected pixel size; a fallback-normalized@@ -193,25 +192,12 @@ record is updated alongside that implementation.- `max(40%, 333px)` intent → `percent(40, {min: pixel(333)})`;- `min(10%, 400px)` intent → `percent(10, {max: pixel(400)})`.-- **API4 — Pixel aliases are exactly mutually exclusive with unified bounds.**- `minSizePx` and `maxSizePx` remain supported but become deprecated. Their public- type remains numeric. Untyped callers keep the released exact `Npx` / `N%`- runtime acceptance; this is compatibility only, not a new documented spelling.- TypeScript- MUST encode each old/new pair as an exact union, equivalent to:-- ```ts- type MinSizeConfig =- | {minSize?: ResizableSize; minSizePx?: never}- | {minSize?: never; minSizePx?: number};- type MaxSizeConfig =- | {maxSize?: ResizableSize; maxSizePx?: never}- | {maxSize?: never; maxSizePx?: number};- ```-- Old-only callers remain unchanged. If JavaScript, an `any` cast, or an object- spread supplies both, the unified `minSize` or `maxSize` MUST win and development- MUST emit a clear conflict/deprecation warning naming the ignored alias.+- **API4 — Unified bounds are the only public spellings in 0.6.**+ `minSize` and `maxSize` are the complete bound vocabulary. The deprecated+ `minSizePx` and `maxSizePx` aliases were supported through 0.5 and are removed in+ 0.6. Numeric `minSize` and `maxSize` retain identical pixel semantics, including+ explicit `maxSize: Infinity`. The 0.6 upgrade codemod rewrites static inline+ configurations; dynamically assembled configuration must rename the keys.- **API5 — Resolved output and state stay pixels.** `ResizableRegion.size`,`onSizeChange`, internal `ResizableProps` geometry, and persisted state remain@@ -228,15 +214,12 @@ record is updated alongside that implementation.### Invalid configuration behavior-| Input | Accepted values | Invalid fallback | Development behavior | Production behavior |-| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | ---------------------------------- |-| `defaultSize` | released `SizeValue` plus `PixelWidth` or `ResizablePercentSize`; structured default resolves once | 250px, then normal bounds clamp | warn and use fallback | use same fallback without warning |-| `minSize` | `ResizableSize`; full-match atomic strings; valid `pixel(value)` or `percent(value, {min XOR max: PixelWidth})` | 50px | warn and use fallback | use same fallback without warning |-| `minSizePx` | public type: non-negative finite number; untyped runtime also preserves exact `Npx` / `N%` strings | 50px | warn and use fallback | use same fallback without warning |-| `maxSize` | `ResizableSize`; full-match atomic strings; valid structured values; explicit `Infinity` remains unbounded | unbounded `Infinity` | warn and use fallback | use same fallback without warning |-| `maxSizePx` | public type: non-negative finite number or `Infinity`; untyped runtime also preserves exact `Npx` / `N%` strings | unbounded `Infinity` | warn for invalid values; do not warn for explicit `Infinity` | use same fallback without warning |-| old/new bound pair supplied together through untyped input | unified value is authoritative | ignore deprecated alias | warn and name the ignored alias | unified value wins without warning |-| resolved minimum above resolved maximum | both values are individually valid | maximum wins | warn and use released clamp order | use same ordering without warning |+| Input | Accepted values | Invalid fallback | Development behavior | Production behavior |+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------- | --------------------------------- |+| `defaultSize` | released `SizeValue` plus `PixelWidth` or `ResizablePercentSize`; structured default resolves once | 250px, then normal bounds clamp | warn and use fallback | use same fallback without warning |+| `minSize` | `ResizableSize`; full-match atomic strings; valid `pixel(value)` or `percent(value, {min XOR max: PixelWidth})` | 50px | warn and use fallback | use same fallback without warning |+| `maxSize` | `ResizableSize`; full-match atomic strings; valid structured values; explicit `Infinity` remains unbounded | unbounded `Infinity` | warn and use fallback | use same fallback without warning |+| resolved minimum above resolved maximum | both values are individually valid | maximum wins | warn and use released clamp order | use same ordering without warning |A fallback repairs configuration; it is not a new user selection. Afterinitialization, an invalid raw value never directly replaces persisted or otherwise@@ -268,44 +251,30 @@ through normal clamping.## Current-state impact-Current `main` accepts a percentage string only for `defaultSize`. It resolves-that value once against `window.innerWidth`, with a 1200px server fallback, and-stores the result as pixels. It does not follow later viewport changes. This-released behavior remains the compatibility path when `containerRef` is omitted.--`minSizePx` and `maxSizePx` cannot express percentage bounds. Builders can apply a-CSS percentage maximum, but CSS then clamps paint without clamping hook state.-ResizeHandle publishes the hook's `_size` as `aria-valuenow`, so the separator can-announce a value larger than the panel a person sees.--The proposed `containerRef` passes both gates in current-[AST-002](../AST-002/spec.md): the caller owns which element is the intended-percentage basis, and the hook cannot derive that choice safely. Keeping all-selected state in pixels makes the result predictable under AST-002 FR8 and avoids-an invalid split between selected state, paint, persistence, callbacks, and ARIA-under AST-002 FR10.--The open implementation spike in-[PR #5783](https://github.com/facebook/astryx/pull/5783) demonstrates-container-relative defaults and bounds and supplies browser measurements. It is-evidence for this proposal, not the governing contract. Before implementation is-accepted it must preserve one-time default resolution, pixel-only interaction and-persistence, vertical-axis behavior, multi-region behavior, collapse/expand, and-SSR requirements in this spec.--This change reviews the current owning records:--- `architecture:public-component-api` owns the additive API, stable pixel output,- deprecation, and migration boundary;-- `family:layout-regions` continues to delegate resize state and interaction to- useResizable and ResizeHandle while LayoutPanel consumes only resolved size;-- `spec:AST-002` requires the new caller-owned basis to remain understandable,- predictable, and correct in every supported state;-- shipped Resizable source, tests, and consumer docs remain the evidence for- current pointer, keyboard, collapse, snap, persistence, handle, and ARIA- behavior until implementation lands; and-- the draft `component:Resizable` record and Resizable consumer docs change when- the implementation ships, not in this specification pull request.+Current `main` ships the complete AST-010 model: `defaultSize`, `minSize`, and+`maxSize` accept pixel and percentage forms; `containerRef` supplies the optional+content-box basis; percentage defaults resolve once; and percentage bounds remain+live while selected state, paint, persistence, callbacks, and separator ARIA stay+in resolved pixels. The no-ref path retains the released `window.innerWidth` basis+and deterministic 1200px server fallback.++Before the unified bounds shipped, the pixel-only API could not express percentage+constraints. Applying CSS constraints separately could make paint disagree with+hook state and ResizeHandle ARIA. The unified bounds now own both forms. Astryx 0.6+removes the deprecated pixel-only key aliases while preserving numeric pixel+behavior under `minSize` and `maxSize`.++The shipped contract remains distributed across its current owners:++- `architecture:public-component-api` owns the stable exports, breaking-change+ classification, and migration boundary;+- `family:layout-regions` delegates resize state and interaction to useResizable+ and ResizeHandle while LayoutPanel consumes resolved size;+- `spec:AST-002` governs the caller-owned container basis and predictable state;+- shipped Resizable source, tests, browser evidence, and consumer docs verify+ pointer, keyboard, collapse, snap, persistence, handle, SSR, and ARIA behavior;+ and+- `component:Resizable` records the component-specific implementation contract.### Persistence representation@@ -333,13 +302,12 @@ never write a percentage descriptor or relative intent.2. Parse complete atomic strings and validate the complete `percent()` descriptor,including its XOR bound shape. Apply FR12's 250px/50px/`Infinity` fallbacksbefore clamping and warn only in development. Preserve explicit- `maxSizePx: Infinity` as valid legacy input.+ `maxSize: Infinity` as valid unbounded input.3. Export `percent`, `ResizablePercentSize`, and `ResizableSize` from Resizable;expose `percent`, the same Table `pixel` binding, `PixelWidth`, and theResizable types from the server-safe `Resizable/utils` subpath.-4. Encode each unified/deprecated bound pair as the exact API4 union. At runtime,- prefer a unified bound over a simultaneously supplied alias and warn in- development with the ignored alias's name.+4. Expose only `minSize` and `maxSize` for bounds. Do not retain runtime parsing,+ conflict warnings, or source types for the removed pixel aliases.5. When `containerRef` is supplied, measure its content box on the configured axisand observe it through Astryx's shared ResizeObserver.6. Resolve a percentage default once into selected pixel state. Remove default-only@@ -363,24 +331,24 @@ never write a percentage descriptor or relative intent.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ---------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1, API1 | Focused hook tests plus Chromium geometry | atomic/structured default; no ref at 1200px; wide/narrow initial container; first positive measurement; later resize | default uses the wrong basis, rescales after initialization, or supplied ref measures the wrong element |-| FR2, API2 | Axis tests and Chromium interaction | horizontal/vertical; LTR/RTL; reversed handle; no-ref vertical compatibility | vertical container sizing reads width, or compatibility stops using `innerWidth` |-| FR3, FR6-FR8 | Interaction and basis-change tests | structured default before/after interaction; viewport/container resize; Arrow, Shift+Arrow, Home, End; collapse/expand | selected state preserves a ratio, basis change rescales it, or existing pixel interactions change |-| FR4 | Structured floor/ceiling, mixed-bound, and invalid-order tests | canonical `percent(40, {min: pixel(333)})` / `percent(10, {max: pixel(400)})`; mixed units; min above max | descriptor bound is applied in the wrong direction, bounds use different bases, selection scales instead of clamps, or maximum does not win |-| FR5 | Hook, LayoutPanel, persistence, and ResizeHandle assertions | below/at/above max; basis shrink; controlled collapse intent | effective paint, state, storage, and ARIA diverge, or controlled rejection changes owned state |-| FR9 | Persistence compatibility tests | positive number; legacy zero; legacy object; structured default; corrupt entry | stored shape changes, a descriptor is persisted, an unused default measures a basis, or old state changes meaning |-| FR10, API5 | Callback tests | initialization; hydration correction; basis-only re-clamp; pointer/keyboard/programmatic change | callback receives a descriptor or reports a non-interaction layout correction |-| FR11 | Multi-region and shared-observer tests | two regions on one container; another hook observing the same node | regions use different bases, selected ratios are introduced, or one subscription removes another |-| FR12 | Production/development validation and state-preservation tests | malformed strings; missing/both descriptor bounds; invalid percent/pixels; invalid rerender; persisted selection; legacy Infinity | fallback differs by build, warning occurs in production, invalid input replaces legal state, or any path produces `NaN` |-| API3, API4, API6 | Type, export, runtime-validation, and warning tests | required helper options; XOR bound; server-safe subpath; old-only aliases; JS/`any` conflicts; `resize('50%')` | `percent(40)` or both bounds type-check, server import gains a client directive, alias overrides unified input, or `resize` accepts non-pixel input |-| Platform/SSR | Server render, hydration test, and Chromium evidence | no ref; ref not measured; hidden/zero container; first positive measurement; resize before layout; later bound activation | temporary basis persists, correction fires `onSizeChange`, default-only observation leaks, or a newly active bound clamps from a stale cached measurement |-| Compatibility | Existing Resizable, LayoutPanel, SideNav, and template suites | current pixel-only callsites; no-ref atomic percentage default; released broad `defaultSize` string | existing numeric/atomic percentage behavior, broad default typing, output, interaction, or persistence changes |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ---------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, API1 | Focused hook tests plus Chromium geometry | atomic/structured default; no ref at 1200px; wide/narrow initial container; first positive measurement; later resize | default uses the wrong basis, rescales after initialization, or supplied ref measures the wrong element |+| FR2, API2 | Axis tests and Chromium interaction | horizontal/vertical; LTR/RTL; reversed handle; no-ref vertical compatibility | vertical container sizing reads width, or compatibility stops using `innerWidth` |+| FR3, FR6-FR8 | Interaction and basis-change tests | structured default before/after interaction; viewport/container resize; Arrow, Shift+Arrow, Home, End; collapse/expand | selected state preserves a ratio, basis change rescales it, or existing pixel interactions change |+| FR4 | Structured floor/ceiling, mixed-bound, and invalid-order tests | canonical `percent(40, {min: pixel(333)})` / `percent(10, {max: pixel(400)})`; mixed units; min above max | descriptor bound is applied in the wrong direction, bounds use different bases, selection scales instead of clamps, or maximum does not win |+| FR5 | Hook, LayoutPanel, persistence, and ResizeHandle assertions | below/at/above max; basis shrink; controlled collapse intent | effective paint, state, storage, and ARIA diverge, or controlled rejection changes owned state |+| FR9 | Persistence compatibility tests | positive number; legacy zero; legacy object; structured default; corrupt entry | stored shape changes, a descriptor is persisted, an unused default measures a basis, or old state changes meaning |+| FR10, API5 | Callback tests | initialization; hydration correction; basis-only re-clamp; pointer/keyboard/programmatic change | callback receives a descriptor or reports a non-interaction layout correction |+| FR11 | Multi-region and shared-observer tests | two regions on one container; another hook observing the same node | regions use different bases, selected ratios are introduced, or one subscription removes another |+| FR12 | Production/development validation and state-preservation tests | malformed strings; missing/both descriptor bounds; invalid percent/pixels; invalid rerender; persisted selection; `Infinity` | fallback differs by build, warning occurs in production, invalid input replaces legal state, or any path produces `NaN` |+| API3, API4, API6 | Type, export, runtime-validation, and codemod tests | required helper options; XOR bound; server-safe subpath; removed alias type errors; `resize('50%')` | `percent(40)` or both bounds type-check, a removed alias still type-checks, server import gains a client directive, or `resize` accepts non-pixel input |+| Platform/SSR | Server render, hydration test, and Chromium evidence | no ref; ref not measured; hidden/zero container; first positive measurement; resize before layout; later bound activation | temporary basis persists, correction fires `onSizeChange`, default-only observation leaks, or a newly active bound clamps from a stale cached measurement |+| Compatibility | Existing Resizable, LayoutPanel, SideNav, and template suites | current pixel-only callsites; no-ref atomic percentage default; released broad `defaultSize` string | existing numeric/atomic percentage behavior, broad default typing, output, interaction, or persistence changes |### Completion criteria-This spec moves from `accepted` to `shipped` only when:+The shipped contract remains satisfied while:- no-ref atomic and structured percentage defaults preserve one-time`window.innerWidth` resolution and the 1200px SSR fallback without tracking@@ -399,14 +367,14 @@ This spec moves from `accepted` to `shipped` only when:resolves one `pixel` symbol and one `percent` symbol without collision;- pointer, keyboard, snap, collapse, expand, persistence, callbacks, and`resize(number)` preserve released pixel semantics;-- old-only `minSizePx` and `maxSizePx` callers remain unchanged, each old/new- pair is an exact mutually exclusive TypeScript union, and untyped conflicts- prefer the unified value with a clear ignored-alias warning;+- `minSizePx` and `maxSizePx` no longer type-check or receive runtime handling,+ and the 0.6 upgrade codemod rewrites static inline configurations to `minSize`+ and `maxSize`;- exact parsing accepts only non-negative finite numbers, complete `Npx` strings,and 0–100 `N%` strings; descriptor validation rejects a missing/both pixel boundor invalid numeric field. Invalid values use the documented 250px, 50px, or`Infinity` fallback without replacing persisted/legal selected state, while- explicit legacy `maxSizePx: Infinity` remains valid;+ explicit `maxSize: Infinity` remains valid;- inverted resolved bounds warn in development, deterministically choose themaximum, and never produce `NaN` or invalid geometry;- mixed bounds keep effective state, paint, storage, and separator ARIA aligned,@@ -457,22 +425,17 @@ one pixel floor and `percent(value, {max: pixel(value)})` adds one pixel ceilingMixing units across the initial size and bounds is valid. This gives builders onepredictable vocabulary without parallel percentage props or duplicate helpers.-Preserve `minSizePx` and `maxSizePx` as deprecated compatibility aliases so-old-only callers behave unchanged. TypeScript encodes each old/new pair as an exact-mutually exclusive union. If untyped JavaScript, an `any` cast, or an object spread-supplies both, the unified `minSize` or `maxSize` wins and development warns with-the ignored alias's name. The explicit migration target must not be silently-overridden by a deprecated value hidden in a spread; this keeps the runtime result-predictable and avoids an ambiguous configuration under `spec:AST-002`.+`minSizePx` and `maxSizePx` remained deprecated compatibility aliases through+0.5. Astryx 0.6 removes them after two stable releases; numeric `minSize` and+`maxSize` preserve their pixel meaning, and `astryx upgrade` rewrites static inline+configurations. Dynamically assembled configuration must rename the keys.Invalid inputs use deterministic role-specific fallbacks in every build: 250px for-`defaultSize`, 50px for either minimum spelling, and unbounded `Infinity` for-either maximum spelling. Development additionally warns. Explicit-`maxSizePx: Infinity` remains valid because that legacy form is shipped in an-Astryx template. If a resolved minimum exceeds its maximum, development warns and-the maximum wins under the released clamp order. These rules keep malformed input,-conflicts, and inverted bounds from producing `NaN` or replacing persisted/legal-selected state.+`defaultSize`, 50px for `minSize`, and unbounded `Infinity` for `maxSize`.+Development additionally warns. Explicit `maxSize: Infinity` remains valid. If a+resolved minimum exceeds its maximum, development warns and the maximum wins under+the released clamp order. These rules keep malformed input and inverted bounds+from producing `NaN` or replacing persisted/legal selected state.### DEC-3 — Bounded percentages use one explicit structured helper@@ -499,6 +462,21 @@ and does not imply arbitrary CSS composition. Rejected: recursive CSS `min()` /`max()` strings, optional helper options, descriptors with both bounds, and separatepercentage props.+### DEC-4 — Astryx 0.6 removes the deprecated pixel-bound aliases++**Reference:** `spec:AST-010/DEC-4`+**Decider:** `cixzhang`, `2026-09-07`++Remove `minSizePx` and `maxSizePx` in the 0.6 breaking window. Their replacements+have shipped across two stable releases, numeric `minSize` and `maxSize` preserve+the same pixel behavior, first-party callers migrate in the removal change, and+`astryx upgrade` rewrites inline configurations. Keeping both vocabularies would+retain type unions, runtime parsing, conflict warnings, tests, and documentation+without adding capability.++Rejected: retaining the aliases indefinitely. They were explicitly temporary and+the unified bounds cover every supported pixel case plus percentage constraints.+## Open questionsNone. Changing the released 1200px server fallback or adding a persistentdiff --git a/packages/cli/assets/codemods/transforms/next/__tests__/next-codemods.test.mjs b/packages/cli/assets/codemods/transforms/next/__tests__/next-codemods.test.mjsnew file mode 100644index 0000000000..6bce1bd6ea--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/__tests__/next-codemods.test.mjs@@ -0,0 +1,184 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @file Unit tests for staged next-release codemods. */++import {describe, expect, it} from 'vitest';+import jscodeshift from 'jscodeshift';++const j = jscodeshift.withParser('tsx');+const api = {jscodeshift: j, stats: () => {}, report: () => {}};++async function apply(name, source) {+ const {default: transform} = await import(`../${name}.mjs`);+ return transform({source, path: 'test.tsx'}, api) ?? source;+}++describe('remove-focus-isrtl-option', () => {+ it('removes the option from inline focus-hook configurations', async () => {+ const input = `import {useGridFocus as useGrid} from '@astryxdesign/core/hooks';+const focus = useGrid({columns: 3, isRtl: forceRtl, hasRovingTabIndex: true});`;+ const output = await apply('remove-focus-isrtl-option', input);+ expect(output).not.toContain('isRtl');+ expect(output).toContain('columns: 3');+ expect(output).toContain('hasRovingTabIndex: true');+ });++ it('leaves dynamic configurations and unrelated properties alone', async () => {+ const input = `import {useListFocus} from '@astryxdesign/core';+const config = {isRtl: true};+const focus = useListFocus(config);+const unrelated = {isRtl: false};`;+ const output = await apply('remove-focus-isrtl-option', input);+ expect(output).toBe(input);+ });++ it('does not rewrite a parameter that shadows the imported hook', async () => {+ const input = `import {useListFocus} from '@astryxdesign/core';+function wrapper(useListFocus) {+ return useListFocus({isRtl: true, keep: 1});+}`;+ const output = await apply('remove-focus-isrtl-option', input);+ expect(output).toBe(input);+ });+});++describe('move-ime-helper-import', () => {+ it('splits the helper out of a mixed hooks import', async () => {+ const input = `import {isImeKeyEvent, useFocusTrap} from '@astryxdesign/core/hooks';+const guarded = isImeKeyEvent(event);`;+ const output = await apply('move-ime-helper-import', input);+ expect(output).toMatch(+ /import \{\s*isImeKeyEvent\s*\} from '@astryxdesign\/core\/utils'/,+ );+ expect(output).toMatch(+ /import \{\s*useFocusTrap\s*\} from '@astryxdesign\/core\/hooks'/,+ );+ });++ it('merges with an existing utilities import and preserves aliases', async () => {+ const input = `import {isImeKeyEvent as isIme, useFocusTrap} from '@astryxdesign/core/hooks';+import {mergeProps} from '@astryxdesign/core/utils';+const guarded = isIme(event);`;+ const output = await apply('move-ime-helper-import', input);+ expect(output).toMatch(+ /import \{[^}]*mergeProps[^}]*isImeKeyEvent as isIme[^}]*\} from '@astryxdesign\/core\/utils'/s,+ );+ expect(output).not.toMatch(+ /isImeKeyEvent[^\n]*from '@astryxdesign\/core\/hooks'/,+ );+ });++ it('preserves unrelated side-effect imports', async () => {+ const input = `import './polyfill';+import {isImeKeyEvent} from '@astryxdesign/core/hooks';+const guarded = isImeKeyEvent(event);`;+ const output = await apply('move-ime-helper-import', input);+ expect(output).toContain("import './polyfill';");+ expect(output).toContain("from '@astryxdesign/core/utils'");+ });++ it('preserves a side-effect import from the mapped hooks path', async () => {+ const input = `import '@astryxdesign/core/hooks';+import {isImeKeyEvent} from '@astryxdesign/core/hooks';+const guarded = isImeKeyEvent(event);`;+ const output = await apply('move-ime-helper-import', input);+ expect(output).toContain("import '@astryxdesign/core/hooks';");+ expect(output).toContain("from '@astryxdesign/core/utils'");+ });++ it('creates a value import beside an existing type-only import', async () => {+ const input = `import {isImeKeyEvent} from '@astryxdesign/core/hooks';+import type {UtilityType} from '@astryxdesign/core/utils';+const guarded = isImeKeyEvent(event);`;+ const output = await apply('move-ime-helper-import', input);+ expect(output).toContain(+ "import type {UtilityType} from '@astryxdesign/core/utils';",+ );+ expect(output).toMatch(+ /import \{\s*isImeKeyEvent\s*\} from '@astryxdesign\/core\/utils'/,+ );+ expect(() => j(output)).not.toThrow();+ });++ it('creates a named import beside an existing namespace import', async () => {+ const input = `import {isImeKeyEvent} from '@astryxdesign/core/hooks';+import * as utils from '@astryxdesign/core/utils';+const guarded = isImeKeyEvent(event);`;+ const output = await apply('move-ime-helper-import', input);+ expect(output).toContain(+ "import * as utils from '@astryxdesign/core/utils';",+ );+ expect(output).toMatch(+ /import \{\s*isImeKeyEvent\s*\} from '@astryxdesign\/core\/utils'/,+ );+ expect(() => j(output)).not.toThrow();+ });++ it('is a fixed point after the import moves', async () => {+ const input = `import {isImeKeyEvent, useFocusTrap} from '@astryxdesign/core/hooks';+const guarded = isImeKeyEvent(event);`;+ const once = await apply('move-ime-helper-import', input);+ const twice = await apply('move-ime-helper-import', once);+ expect(twice).toBe(once);+ });+});++describe('rename-resizable-pixel-bounds', () => {+ it('renames inline single-region bounds', async () => {+ const input = `import {useResizable} from '@astryxdesign/core/Resizable';+const region = useResizable({defaultSize: 240, minSizePx: 120, maxSizePx: 480});`;+ const output = await apply('rename-resizable-pixel-bounds', input);+ expect(output).toContain('minSize: 120');+ expect(output).toContain('maxSize: 480');+ expect(output).not.toContain('minSizePx');+ expect(output).not.toContain('maxSizePx');+ });++ it('drops an old key when the unified key already exists', async () => {+ const input = `import {useResizable} from '@astryxdesign/core';+const region = useResizable({minSize: 160, minSizePx: 80});`;+ const output = await apply('rename-resizable-pixel-bounds', input);+ expect(output.match(/minSize:/g)).toHaveLength(1);+ expect(output).toContain('minSize: 160');+ expect(output).not.toContain('minSizePx');+ });++ it('preserves shorthand values while renaming their keys', async () => {+ const input = `import {useResizable} from '@astryxdesign/core/Resizable';+const minSizePx = 120;+const region = useResizable({minSizePx});`;+ const output = await apply('rename-resizable-pixel-bounds', input);+ expect(output).toContain('minSize: minSizePx');+ });++ it('renames bounds in inline multi-region configurations', async () => {+ const input = `import {useResizable as resize} from '@astryxdesign/core/Resizable';+const regions = resize({regions: {+ nav: {defaultSize: 240, minSizePx: 120},+ detail: {defaultSize: 480, maxSizePx: 900},+}});`;+ const output = await apply('rename-resizable-pixel-bounds', input);+ expect(output).toContain('minSize: 120');+ expect(output).toContain('maxSize: 900');+ expect(output).not.toContain('minSizePx: 120');+ expect(output).not.toContain('maxSizePx: 900');+ });++ it('leaves unrelated and dynamic configuration objects alone', async () => {+ const input = `import {useResizable} from '@astryxdesign/core/Resizable';+const config = {minSizePx: 120};+const region = useResizable(config);+const unrelated = {maxSizePx: 500};`;+ const output = await apply('rename-resizable-pixel-bounds', input);+ expect(output).toBe(input);+ });++ it('does not rewrite a parameter that shadows the imported hook', async () => {+ const input = `import {useResizable} from '@astryxdesign/core';+function wrapper(useResizable) {+ return useResizable({minSizePx: 120, keep: 1});+}`;+ const output = await apply('rename-resizable-pixel-bounds', input);+ expect(output).toBe(input);+ });+});diff --git a/packages/cli/assets/codemods/transforms/next/index.mjs b/packages/cli/assets/codemods/transforms/next/index.mjsindex 2af3bdfcf0..7d85271908 100644--- a/packages/cli/assets/codemods/transforms/next/index.mjs+++ b/packages/cli/assets/codemods/transforms/next/index.mjs@@ -7,4 +7,30 @@* this file into the resolved version folder.*/-export default [];+import moveImeHelperImport, {+ meta as moveImeHelperImportMeta,+} from './move-ime-helper-import.mjs';+import removeFocusIsrtlOption, {+ meta as removeFocusIsrtlOptionMeta,+} from './remove-focus-isrtl-option.mjs';+import renameResizablePixelBounds, {+ meta as renameResizablePixelBoundsMeta,+} from './rename-resizable-pixel-bounds.mjs';++export default [+ {+ name: 'move-ime-helper-import',+ transform: moveImeHelperImport,+ meta: moveImeHelperImportMeta,+ },+ {+ name: 'remove-focus-isrtl-option',+ transform: removeFocusIsrtlOption,+ meta: removeFocusIsrtlOptionMeta,+ },+ {+ name: 'rename-resizable-pixel-bounds',+ transform: renameResizablePixelBounds,+ meta: renameResizablePixelBoundsMeta,+ },+];diff --git a/packages/cli/assets/codemods/transforms/next/move-ime-helper-import.mjs b/packages/cli/assets/codemods/transforms/next/move-ime-helper-import.mjsnew file mode 100644index 0000000000..a7a5ac3b0e--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/move-ime-helper-import.mjs@@ -0,0 +1,116 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Codemod: move isImeKeyEvent imports to the server-safe utilities path+ */++export const meta = {+ title: 'Move isImeKeyEvent imports to core utilities',+ description:+ 'Moves `isImeKeyEvent` from the deprecated client-only hooks barrel to ' ++ 'the canonical `@astryxdesign/core/utils` path.',+};++const SOURCE_MAP = new Map([+ ['@astryxdesign/core/hooks', '@astryxdesign/core/utils'],+ ['@xds/core/hooks', '@xds/core/utils'],+]);++/**+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api+ * @returns {string | null | undefined}+ */+export default function transformer(file, api) {+ if (!file.source.includes('isImeKeyEvent')) return undefined;++ const j = api.jscodeshift;+ const root = j(file.source);+ /** @type {Map<string, string[]>} */+ const moved = new Map();+ /** @type {any[]} */+ const emptiedHooksImports = [];+ let changed = false;++ root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {+ const target = SOURCE_MAP.get(path.node.source.value);+ if (!target) return;++ /** @type {any[]} */+ const retained = [];+ let movedFromThisDeclaration = false;+ for (const specifier of path.node.specifiers ?? []) {+ if (+ specifier.type === 'ImportSpecifier' &&+ specifier.imported?.name === 'isImeKeyEvent'+ ) {+ const locals = moved.get(target) ?? [];+ locals.push(specifier.local?.name ?? 'isImeKeyEvent');+ moved.set(target, locals);+ movedFromThisDeclaration = true;+ changed = true;+ } else {+ retained.push(specifier);+ }+ }+ path.node.specifiers = retained;+ if (movedFromThisDeclaration && retained.length === 0) {+ emptiedHooksImports.push(path);+ }+ });++ if (!changed) return undefined;++ // Remove only hooks imports emptied by the migration. Unrelated side-effect+ // imports also have zero specifiers and must remain untouched.+ for (const path of emptiedHooksImports) j(path).remove();++ for (const [target, localNames] of moved) {+ /** @type {any} */+ let existing = null;+ root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {+ if (path.node.source.value !== target || existing != null) return;+ const specifiers = path.node.specifiers ?? [];+ const hasNamespace = specifiers.some(+ (/** @type {any} */ specifier) =>+ specifier.type === 'ImportNamespaceSpecifier',+ );+ // A value specifier cannot be appended to `import type`, and named+ // imports cannot share a declaration with a namespace import.+ if (path.node.importKind !== 'type' && !hasNamespace) existing = path;+ });++ const specifiers = [...new Set(localNames)].map(localName =>+ j.importSpecifier(+ j.identifier('isImeKeyEvent'),+ localName === 'isImeKeyEvent' ? null : j.identifier(localName),+ ),+ );++ if (existing) {+ const presentLocals = new Set(+ (existing.node.specifiers ?? [])+ .filter(+ (/** @type {any} */ specifier) =>+ specifier.type === 'ImportSpecifier',+ )+ .map(+ (/** @type {any} */ specifier) =>+ specifier.local?.name ?? specifier.imported?.name,+ ),+ );+ for (const specifier of specifiers) {+ const local = specifier.local?.name ?? specifier.imported.name;+ if (!presentLocals.has(local)) existing.node.specifiers.push(specifier);+ }+ } else {+ const declaration = j.importDeclaration(+ specifiers,+ j.stringLiteral(target),+ );+ root.get().node.program.body.unshift(declaration);+ }+ }++ return root.toSource({quote: 'single'});+}diff --git a/packages/cli/assets/codemods/transforms/next/remove-focus-isrtl-option.mjs b/packages/cli/assets/codemods/transforms/next/remove-focus-isrtl-option.mjsnew file mode 100644index 0000000000..fcfc03d8cd--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/remove-focus-isrtl-option.mjs@@ -0,0 +1,86 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Codemod: remove deprecated explicit RTL options from focus hooks+ *+ * useGridFocus and useListFocus derive direction from their container at the+ * moment a horizontal arrow key is pressed. This removes static `isRtl`+ * properties from inline option objects passed to those hooks.+ *+ * Dynamic config objects are deliberately left alone: removing a property from+ * an object whose ownership is unknown would be guesswork, and the 0.6 type+ * error makes those remaining sites visible.+ */++export const meta = {+ title: 'Remove explicit RTL options from focus hooks',+ description:+ 'Removes deprecated `isRtl` properties from inline useGridFocus and ' ++ 'useListFocus option objects. Direction is detected from the container.',+};++const IMPORT_SOURCES = new Set([+ '@astryxdesign/core',+ '@astryxdesign/core/hooks',+ '@xds/core',+ '@xds/core/hooks',+]);+const HOOKS = new Set(['useGridFocus', 'useListFocus']);++/** @param {any} property */+function staticPropertyName(property) {+ if (property.computed) return null;+ const key = property.key;+ if (key?.type === 'Identifier') return key.name;+ if (key?.type === 'StringLiteral' || key?.type === 'Literal') {+ return key.value;+ }+ return null;+}++/**+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api+ * @returns {string | null | undefined}+ */+export default function transformer(file, api) {+ if (!file.source.includes('isRtl')) return undefined;++ const j = api.jscodeshift;+ const root = j(file.source);+ /** @type {Map<string, any>} */+ const bindings = new Map();++ root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {+ if (!IMPORT_SOURCES.has(path.node.source.value)) return;+ for (const specifier of path.node.specifiers ?? []) {+ if (+ specifier.type === 'ImportSpecifier' &&+ HOOKS.has(specifier.imported?.name)+ ) {+ const local = specifier.local?.name ?? specifier.imported.name;+ bindings.set(local, path.scope.lookup(local) ?? path.scope);+ }+ }+ });+ if (bindings.size === 0) return undefined;++ let changed = false;+ root.find(j.CallExpression).forEach((/** @type {any} */ path) => {+ const callee = path.node.callee;+ if (callee.type !== 'Identifier' || !bindings.has(callee.name)) return;+ // A parameter/local with the same name shadows the imported hook. Only+ // rewrite calls whose lexical binding is the import we discovered.+ if (path.scope.lookup(callee.name) !== bindings.get(callee.name)) return;+ const options = path.node.arguments[0];+ if (options?.type !== 'ObjectExpression') return;++ const before = options.properties.length;+ options.properties = options.properties.filter(+ (/** @type {any} */ property) => staticPropertyName(property) !== 'isRtl',+ );+ changed ||= options.properties.length !== before;+ });++ return changed ? root.toSource({quote: 'single'}) : undefined;+}diff --git a/packages/cli/assets/codemods/transforms/next/rename-resizable-pixel-bounds.mjs b/packages/cli/assets/codemods/transforms/next/rename-resizable-pixel-bounds.mjsnew file mode 100644index 0000000000..4b5870f795--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/rename-resizable-pixel-bounds.mjs@@ -0,0 +1,140 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Codemod: rename useResizable pixel-bound aliases+ *+ * Numbers already mean pixels in minSize/maxSize. This rewrites inline single-+ * and multi-region configurations while preserving shorthand values and the+ * released conflict rule (the unified property wins when both are present).+ */++export const meta = {+ title: 'Rename useResizable pixel bounds',+ description:+ 'Renames deprecated `minSizePx`/`maxSizePx` properties to `minSize`/' ++ '`maxSize` in inline useResizable configurations.',+};++const IMPORT_SOURCES = new Set([+ '@astryxdesign/core',+ '@astryxdesign/core/Resizable',+ '@xds/core',+ '@xds/core/Resizable',+]);+const RENAMES = new Map([+ ['minSizePx', 'minSize'],+ ['maxSizePx', 'maxSize'],+]);++/** @param {any} property */+function staticPropertyName(property) {+ if (property.computed) return null;+ const key = property.key;+ if (key?.type === 'Identifier') return key.name;+ if (key?.type === 'StringLiteral' || key?.type === 'Literal') {+ return key.value;+ }+ return null;+}++/**+ * @param {any} j+ * @param {any} property+ * @param {string} nextName+ */+function renameKey(j, property, nextName) {+ if (property.shorthand) property.shorthand = false;+ if (property.key.type === 'Identifier') {+ property.key = j.identifier(nextName);+ } else {+ property.key.value = nextName;+ }+}++/**+ * @param {any} j+ * @param {any} object+ */+function migrateObject(j, object) {+ let changed = false;+ for (const [oldName, newName] of RENAMES) {+ const hasNew = object.properties.some(+ (/** @type {any} */ property) => staticPropertyName(property) === newName,+ );+ /** @type {any[]} */+ const next = [];+ for (const property of object.properties) {+ if (staticPropertyName(property) !== oldName) {+ next.push(property);+ continue;+ }+ changed = true;+ if (!hasNew) {+ renameKey(j, property, newName);+ next.push(property);+ }+ }+ object.properties = next;+ }+ return changed;+}++/**+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api+ * @returns {string | null | undefined}+ */+export default function transformer(file, api) {+ if (+ !file.source.includes('minSizePx') &&+ !file.source.includes('maxSizePx')+ ) {+ return undefined;+ }++ const j = api.jscodeshift;+ const root = j(file.source);+ /** @type {Map<string, any>} */+ const bindings = new Map();++ root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {+ if (!IMPORT_SOURCES.has(path.node.source.value)) return;+ for (const specifier of path.node.specifiers ?? []) {+ if (+ specifier.type === 'ImportSpecifier' &&+ specifier.imported?.name === 'useResizable'+ ) {+ const local = specifier.local?.name ?? 'useResizable';+ bindings.set(local, path.scope.lookup(local) ?? path.scope);+ }+ }+ });+ if (bindings.size === 0) return undefined;++ let changed = false;+ root.find(j.CallExpression).forEach((/** @type {any} */ path) => {+ const callee = path.node.callee;+ if (callee.type !== 'Identifier' || !bindings.has(callee.name)) return;+ if (path.scope.lookup(callee.name) !== bindings.get(callee.name)) return;+ const config = path.node.arguments[0];+ if (config?.type !== 'ObjectExpression') return;++ changed = migrateObject(j, config) || changed;++ const regions = config.properties.find(+ (/** @type {any} */ property) =>+ staticPropertyName(property) === 'regions',+ );+ if (!regions || !('value' in regions)) return;+ const regionsObject = regions.value;+ if (regionsObject?.type !== 'ObjectExpression') return;+ for (const region of regionsObject.properties) {+ if (!('value' in region) || region.value?.type !== 'ObjectExpression') {+ continue;+ }+ changed = migrateObject(j, region.value) || changed;+ }+ });++ return changed ? root.toSource({quote: 'single'}) : undefined;+}diff --git a/packages/cli/assets/docs/internationalization.doc.mjs b/packages/cli/assets/docs/internationalization.doc.mjsindex 325683312a..45d8504666 100644--- a/packages/cli/assets/docs/internationalization.doc.mjs+++ b/packages/cli/assets/docs/internationalization.doc.mjs@@ -146,7 +146,7 @@ export default function RootLayout({children, params}) {},{type: 'prose',- text: 'In a plain client app, set the same attribute on `<html>` whenever the locale changes. (`getLocaleDirection()` safely returns `\'ltr\'` for anything it doesn\'t recognize, so you can call it with any locale string.)',+ text: "In a plain client app, set the same attribute on `<html>` whenever the locale changes. (`getLocaleDirection()` safely returns `'ltr'` for anything it doesn't recognize, so you can call it with any locale string.)",},{type: 'prose',@@ -345,7 +345,7 @@ function SaveButton() {},{type: 'prose',- text: "When you author a component that needs to respond to direction, resolve it from the DOM, not from a render-time JavaScript read, and reach for the lightest tool that works. In priority order:",+ text: 'When you author a component that needs to respond to direction, resolve it from the DOM, not from a render-time JavaScript read, and reach for the lightest tool that works. In priority order:',},{type: 'heading',@@ -354,7 +354,7 @@ function SaveButton() {},{type: 'prose',- text: "Use `insetInlineStart`, `paddingInlineEnd`, `marginInline`, and friends instead of physical `left`/`right`. Most mirroring needs nothing more; the browser flips it from the ambient `dir`. The `@astryx/no-physical-properties` ESLint rule enforces this.",+ text: 'Use `insetInlineStart`, `paddingInlineEnd`, `marginInline`, and friends instead of physical `left`/`right`. Most mirroring needs nothing more; the browser flips it from the ambient `dir`. The `@astryx/no-physical-properties` ESLint rule enforces this.',},{type: 'heading',@@ -363,7 +363,7 @@ function SaveButton() {},{type: 'prose',- text: "Render one fixed glyph and wrap it in the shared `rtlStyles.mirror` (a `scaleX(-1)` that only applies under `[dir=\"rtl\"]`). It flips from the ancestor `dir` through the cascade, so it works on the server with no hydration flash. Do not pick `chevronLeft` vs `chevronRight` in JS. This is how Pagination, Calendar, and Carousel handle their chevrons.",+ text: 'Render one fixed glyph and wrap it in the shared `rtlStyles.mirror` (a `scaleX(-1)` that only applies under `[dir="rtl"]`). It flips from the ancestor `dir` through the cascade, so it works on the server with no hydration flash. Do not pick `chevronLeft` vs `chevronRight` in JS. This is how Pagination, Calendar, and Carousel handle their chevrons.',},{type: 'code',@@ -388,7 +388,7 @@ function NextButton() {},{type: 'prose',- text: "For things CSS can't express; keyboard arrow-key mapping, drag/scroll math; read direction at interaction time with `isRtlElement(el)` (a `getComputedStyle().direction` check), never during render. The focus primitives (`useListFocus`, `useGridFocus`, `useTreeFocus`) already auto-detect direction from their container, so arrow keys flip for free; don't pass a direction flag to them. (`isRtl` on `useListFocus`/`useGridFocus` is deprecated in favor of auto-detection, and new hooks don't accept it.)",+ text: "For things CSS can't express; keyboard arrow-key mapping, drag/scroll math; read direction at interaction time with `isRtlElement(el)` (a `getComputedStyle().direction` check), never during render. The focus primitives (`useListFocus`, `useGridFocus`, `useTreeFocus`) already auto-detect direction from their container, so arrow keys flip for free; don't pass a direction flag to them.",},{type: 'heading',diff --git a/packages/cli/assets/templates/blocks/components/Grid/GridResponsiveAutoFit.tsx b/packages/cli/assets/templates/blocks/components/Grid/GridResponsiveAutoFit.tsxindex 1082eafc22..97e9529613 100644--- a/packages/cli/assets/templates/blocks/components/Grid/GridResponsiveAutoFit.tsx+++ b/packages/cli/assets/templates/blocks/components/Grid/GridResponsiveAutoFit.tsx@@ -21,8 +21,8 @@ const teams = [export default function GridResponsiveAutoFit() {const gridPanel = useResizable({defaultSize: 480,- minSizePx: 100,- maxSizePx: 480,+ minSize: 100,+ maxSize: 480,});return (diff --git a/packages/cli/assets/templates/blocks/components/Resizable/ResizableShowcase.tsx b/packages/cli/assets/templates/blocks/components/Resizable/ResizableShowcase.tsxindex 63bd0e5220..9dd6a4dc8c 100644--- a/packages/cli/assets/templates/blocks/components/Resizable/ResizableShowcase.tsx+++ b/packages/cli/assets/templates/blocks/components/Resizable/ResizableShowcase.tsx@@ -15,8 +15,8 @@ import {Text, Heading} from '@astryxdesign/core/Text';export default function ResizableShowcase() {const sidebar = useResizable({defaultSize: 200,- minSizePx: 120,- maxSizePx: 400,+ minSize: 120,+ maxSize: 400,});return (diff --git a/packages/cli/assets/templates/blocks/components/Resizable/ResizableSidebar.tsx b/packages/cli/assets/templates/blocks/components/Resizable/ResizableSidebar.tsxindex d108a04eb7..2e1407a554 100644--- a/packages/cli/assets/templates/blocks/components/Resizable/ResizableSidebar.tsx+++ b/packages/cli/assets/templates/blocks/components/Resizable/ResizableSidebar.tsx@@ -16,8 +16,8 @@ import {Text} from '@astryxdesign/core/Text';export default function ResizableSidebar() {const sidebar = useResizable({defaultSize: 240,- minSizePx: 160,- maxSizePx: 360,+ minSize: 160,+ maxSize: 360,collapsible: true,snaps: [200, 280],});diff --git a/packages/cli/assets/templates/pages/ai-chat/page.tsx b/packages/cli/assets/templates/pages/ai-chat/page.tsxindex 3dadc45a41..549054eaa4 100644--- a/packages/cli/assets/templates/pages/ai-chat/page.tsx+++ b/packages/cli/assets/templates/pages/ai-chat/page.tsx@@ -276,8 +276,8 @@ export default function AIChatConversationTemplate() {const rootRef = useRef<HTMLElement>(null);const artifactResize = useResizable({defaultSize: 640,- minSizePx: 480,- maxSizePx: 960,+ minSize: 480,+ maxSize: 960,autoSaveId: 'ai-chat-artifact-panel',});diff --git a/packages/cli/assets/templates/pages/ide/page.tsx b/packages/cli/assets/templates/pages/ide/page.tsxindex d0b6c13721..3a9c026948 100644--- a/packages/cli/assets/templates/pages/ide/page.tsx+++ b/packages/cli/assets/templates/pages/ide/page.tsx@@ -202,24 +202,24 @@ export default function ResizableWorkspacePage() {const startPanel = useResizable({defaultSize: 256,- minSizePx: 160,- maxSizePx: 400,+ minSize: 160,+ maxSize: 400,collapsible: true,collapsedSize: 50,});const endPanel = useResizable({defaultSize: 320,- minSizePx: 180,- maxSizePx: 500,+ minSize: 180,+ maxSize: 500,collapsible: true,collapsedSize: 50,});const bottomPanel = useResizable({defaultSize: 300,- minSizePx: 80,- maxSizePx: Infinity,+ minSize: 80,+ maxSize: Infinity,direction: 'vertical',collapsible: true,collapsedSize: 40,diff --git a/packages/cli/assets/templates/pages/incident-console/page.tsx b/packages/cli/assets/templates/pages/incident-console/page.tsxindex 5ea2b85325..0410db28e2 100644--- a/packages/cli/assets/templates/pages/incident-console/page.tsx+++ b/packages/cli/assets/templates/pages/incident-console/page.tsx@@ -471,8 +471,8 @@ export default function IncidentConsolePage() {const inspectorPanel = useResizable({defaultSize: 380,- minSizePx: 320,- maxSizePx: 480,+ minSize: 320,+ maxSize: 480,});const visible = useMemo(() => {diff --git a/packages/cli/assets/templates/pages/table-filter/page.tsx b/packages/cli/assets/templates/pages/table-filter/page.tsxindex 85f079eea1..006516449d 100644--- a/packages/cli/assets/templates/pages/table-filter/page.tsx+++ b/packages/cli/assets/templates/pages/table-filter/page.tsx@@ -2227,8 +2227,8 @@ export default function TableFilterTemplate() {// much room that the table loses its sortable columns.const detailWidth = useResizable({defaultSize: 380,- minSizePx: 320,- maxSizePx: 560,+ minSize: 320,+ maxSize: 560,});// --- Sorting ---------------------------------------------------------------diff --git a/packages/cli/assets/templates/pages/table-grouped/page.tsx b/packages/cli/assets/templates/pages/table-grouped/page.tsxindex be9742881a..927f0b0c66 100644--- a/packages/cli/assets/templates/pages/table-grouped/page.tsx+++ b/packages/cli/assets/templates/pages/table-grouped/page.tsx@@ -886,8 +886,8 @@ export default function DataTableTemplate() {const detailPanel = useResizable({defaultSize: 360,- minSizePx: 280,- maxSizePx: 500,+ minSize: 280,+ maxSize: 500,});const COL_COUNT = columns.length;diff --git a/packages/cli/assets/templates/pages/table-inbox/page.tsx b/packages/cli/assets/templates/pages/table-inbox/page.tsxindex daaea1e392..b51d88c370 100644--- a/packages/cli/assets/templates/pages/table-inbox/page.tsx+++ b/packages/cli/assets/templates/pages/table-inbox/page.tsx@@ -2101,7 +2101,7 @@ export default function SupportInboxTemplate() {const pane = useResizable({defaultSize: '58%',- minSizePx: PANE_MIN_WIDTH,+ minSize: PANE_MIN_WIDTH,// Everything the surface has, less the list's floor — so the ceiling// tracks the screen and the list keeps its whole range on any of them,// stacked rows included.@@ -2113,7 +2113,7 @@ export default function SupportInboxTemplate() {// largest pane that still fits. The layout that is actually right down// there is the single-surface one, which `isPaneFullWidth` takes over// before this is on screen.- maxSizePx: isMeasured+ maxSize: isMeasured? Math.max(PANE_MIN_WIDTH, surfaceWidth - LIST_MIN_WIDTH): undefined,onSizeChange: onPaneSizeChange,diff --git a/packages/core/src/BottomSheet/BottomSheet.tsx b/packages/core/src/BottomSheet/BottomSheet.tsxindex d7d6e20595..69bb316da4 100644--- a/packages/core/src/BottomSheet/BottomSheet.tsx+++ b/packages/core/src/BottomSheet/BottomSheet.tsx@@ -39,7 +39,8 @@ import * as stylex from '@stylexjs/stylex';import type {BaseProps} from '../BaseProps';import type {DialogPurpose} from '../Dialog';import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';-import {isImeKeyEvent, useDevWarning, useScrollLock} from '../hooks';+import {useDevWarning, useScrollLock} from '../hooks';+import {isImeKeyEvent} from '../utils';import {BottomSheetPanel,type BottomSheetPanelMotion,diff --git a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx b/packages/core/src/BottomSheet/BottomSheetSwitcher.tsxindex 3012c53b75..d3366f7044 100644--- a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx+++ b/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx@@ -45,13 +45,8 @@ import * as stylex from '@stylexjs/stylex';import type {BaseProps} from '../BaseProps';import type {DialogPurpose} from '../Dialog';import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';-import {- hasActiveFocusTrapEscape,- isImeKeyEvent,- useFocusTrap,- useScrollLock,-} from '../hooks';-import {composeEventHandlers, mergeProps} from '../utils';+import {hasActiveFocusTrapEscape, useFocusTrap, useScrollLock} from '../hooks';+import {composeEventHandlers, isImeKeyEvent, mergeProps} from '../utils';import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';import {BottomSheetSwitcherContext,diff --git a/packages/core/src/Layout/LayoutPanel.tsx b/packages/core/src/Layout/LayoutPanel.tsxindex fda541d5a7..ef3428c270 100644--- a/packages/core/src/Layout/LayoutPanel.tsx+++ b/packages/core/src/Layout/LayoutPanel.tsx@@ -167,7 +167,7 @@ export interface LayoutPanelProps extends BaseProps<HTMLDivElement> {** @example* ```- * const sidebar = useResizable({ defaultSize: 250, minSizePx: 200 });+ * const sidebar = useResizable({ defaultSize: 250, minSize: 200 });* <LayoutPanel resizable={sidebar.props}>* <Navigation />* </LayoutPanel>diff --git a/packages/core/src/Resizable/Resizable.doc.mjs b/packages/core/src/Resizable/Resizable.doc.mjsindex 7519f78ef7..eb90a0b1bf 100644--- a/packages/core/src/Resizable/Resizable.doc.mjs+++ b/packages/core/src/Resizable/Resizable.doc.mjs@@ -147,19 +147,6 @@ const region = useResizable({'Live maximum. Numbers, exact Npx, and pixel(value) remain pixels; exact N% has no additional pixel bound; percent(value, {min: pixel(value)}) or percent(value, {max: pixel(value)}) adds exactly one.',default: 'Infinity',},- {- name: 'minSizePx',- type: 'number',- description: 'Deprecated pixel-only alias for minSize.',- default: '50',- },- {- name: 'maxSizePx',- type: 'number',- description:- 'Deprecated pixel-only alias for maxSize. Explicit Infinity remains valid.',- default: 'Infinity',- },{name: 'collapsible',type: 'boolean',diff --git a/packages/core/src/Resizable/Resizable.spec.md b/packages/core/src/Resizable/Resizable.spec.mdindex 947ef97341..5e11f9c502 100644--- a/packages/core/src/Resizable/Resizable.spec.md+++ b/packages/core/src/Resizable/Resizable.spec.md@@ -46,8 +46,8 @@ selected state, persistence, callbacks, paint, and ARIA in resolved pixels.- Released default preserved: `yes`; numeric and exact `Npx` stay pixels, exact`N%` retains released one-time default behavior, and the broad `defaultSize`string type remains source-compatible-- Compatibility class: additive `minSize` / `maxSize`, structured percentage helper,- and optional container basis; deprecated pixel aliases remain supported+- Compatibility class: 0.6 removes the deprecated pixel-bound aliases after two+ stable releases; numeric `minSize` / `maxSize` preserve their pixel semantics- Controlled/uncontrolled behavior: unchanged- Migration decision: CSS-like `min()` / `max()` strings are not supported. Use`percent(value, {min: pixel(value)})` or@@ -99,7 +99,7 @@ in `Resizable.doc.mjs` and `useResizable.doc.mjs`.| FR3 | Pointer, keyboard, collapse, snap, persistence, reversal, and size behavior remain owned by ResizeHandle and useResizable rather than layout-regions collaborators. | Current source, docs, and tests | Verified current ownership; resize semantics remain unchanged || FR4 | Resizable metadata advertises `direction` as a Handle visual state, but current runtime calls `themeProps('resize-handle')` without reflecting that value, so direction selectors cannot match. | Current source and public docs | Verified audit gap; deliberately not fixed in this change || FR5 | `percent(value, {min: pixel(value)})` and `percent(value, {max: pixel(value)})` resolve against the AST-010 basis; a default selects pixels once, while a bound re-resolves and clamps selected pixels. Both/neither bounds are invalid. | AST-010, source, tests, Chromium | New structured sizing behavior; selected state remains pixels |-| FR6 | Deprecated pixel aliases remain source-compatible and mutually exclusive with unified bounds; untyped exact atomic strings keep their released runtime behavior, and untyped conflicts prefer the unified value and warn. | AST-010, source, tests | Additive migration with deterministic precedence |+| FR6 | `minSize` and `maxSize` are the only bound spellings in 0.6; numeric values retain pixel semantics, and the upgrade codemod rewrites static inline uses of the removed aliases. | AST-010, source, codemod tests | Breaking cleanup with mechanical migration |### Allowed variation@@ -205,7 +205,7 @@ not emit the documented target state.| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts` | Pointer, keyboard, snap, collapse, persistence | Moving resize ownership or changing current transformations fails focused behavior coverage. | `audit:Resizable/behavior` || FR4 | Source and public metadata comparison | Horizontal and vertical Handle | No current test detects that documented `direction` is absent from runtime target-state reflection. | `audit:Resizable/theming` || FR5 | Hook/utils tests, typecheck, and Chromium | Canonical floor/ceiling/default; invalid XOR shape; SSR/hydration; basis changes; numeric `containerRef` parity | Wrong resolution, rescaling defaults, stale clamps, observer leaks, extra numeric renders/ref reads, or state/paint/storage/ARIA divergence fails. | `audit:Resizable/behavior` |-| FR6 | Hook type/runtime tests | Old-only aliases; untyped exact atomic strings; typed and untyped conflicts | Alias incompatibility, ambiguous config, or wrong precedence fails focused tests. | `audit:Resizable/behavior` |+| FR6 | Hook type/runtime and codemod tests | Removed alias type errors; single/multi-region inline migrations; numeric pixel bounds | A removed alias still type-checks, or migration changes its numeric meaning. | `audit:Resizable/behavior` || Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two current targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Resizable/theming` |Current tests exercise Handle and Grab zone structure and behavior but do notdiff --git a/packages/core/src/Resizable/ResizeHandle.test.tsx b/packages/core/src/Resizable/ResizeHandle.test.tsxindex a7d4002960..9407a9918e 100644--- a/packages/core/src/Resizable/ResizeHandle.test.tsx+++ b/packages/core/src/Resizable/ResizeHandle.test.tsx@@ -33,7 +33,7 @@ function Harness({handleProps?: Partial<ResizeHandleProps>;}) {const region = useResizable(- config ?? {defaultSize: 200, minSizePx: 100, maxSizePx: 400},+ config ?? {defaultSize: 200, minSize: 100, maxSize: 400},);return (<ResizeHandle resizable={region.props} label="Resize" {...handleProps} />@@ -143,8 +143,8 @@ describe('ResizeHandle', () => {<Harnessconfig={{defaultSize: 200,- minSizePx: 100,- maxSizePx: 400,+ minSize: 100,+ maxSize: 400,direction: 'vertical',}}handleProps={{direction: 'vertical'}}@@ -186,8 +186,8 @@ describe('ResizeHandle', () => {<Harnessconfig={{defaultSize: 200,- minSizePx: 100,- maxSizePx: 400,+ minSize: 100,+ maxSize: 400,collapsible: true,}}/>,@@ -207,8 +207,8 @@ describe('ResizeHandle', () => {<Harnessconfig={{defaultSize: 200,- minSizePx: 100,- maxSizePx: 400,+ minSize: 100,+ maxSize: 400,collapsible: true,}}/>,@@ -228,8 +228,8 @@ describe('ResizeHandle', () => {<Harnessconfig={{defaultSize: 200,- minSizePx: 100,- maxSizePx: 400,+ minSize: 100,+ maxSize: 400,collapsible: true,}}/>,@@ -467,8 +467,8 @@ describe('ResizeHandle', () => {<Harnessconfig={{defaultSize: 200,- minSizePx: 100,- maxSizePx: 400,+ minSize: 100,+ maxSize: 400,direction,}}handleProps={{direction, pillPlacement: 'start'}}diff --git a/packages/core/src/Resizable/useResizable.doc.mjs b/packages/core/src/Resizable/useResizable.doc.mjsindex 7918477444..b644a2c734 100644--- a/packages/core/src/Resizable/useResizable.doc.mjs+++ b/packages/core/src/Resizable/useResizable.doc.mjs@@ -50,18 +50,6 @@ export const docs = {"Which axis this region resizes along. Selects the container's inline or block content-box size as the percentage basis, and must match the direction given to ResizeHandle.",default: "'horizontal'",},- {- name: 'minSizePx',- type: 'number',- description:- 'Deprecated. Use minSize, which also accepts a percentage. Supplying both is a type error; if untyped code supplies both, minSize wins.',- },- {- name: 'maxSizePx',- type: 'number',- description:- 'Deprecated. Use maxSize, which also accepts a percentage. Explicit Infinity remains valid.',- },{name: 'collapsible',type: 'boolean',diff --git a/packages/core/src/Resizable/useResizable.test.ts b/packages/core/src/Resizable/useResizable.test.tsindex dac9a2fac2..73c9571988 100644--- a/packages/core/src/Resizable/useResizable.test.ts+++ b/packages/core/src/Resizable/useResizable.test.ts@@ -27,8 +27,8 @@ const KEY = `astryx-resizable:${AUTO_SAVE_ID}`;const BASE_CONFIG = {defaultSize: 260,- minSizePx: 180,- maxSizePx: 480,+ minSize: 180,+ maxSize: 480,autoSaveId: AUTO_SAVE_ID,};@@ -414,7 +414,7 @@ describe('useResizable live collapse state', () => {describe('useResizable identity', () => {it('keeps callbacks stable when optional snaps are omitted', () => {const {result, rerender} = renderHook(() =>- useResizable({defaultSize: 200, minSizePx: 100, maxSizePx: 400}),+ useResizable({defaultSize: 200, minSize: 100, maxSize: 400}),);const first = {expand: result.current.expand,@@ -433,7 +433,7 @@ describe('useResizable identity', () => {let passes = 0;const {result} = renderHook(() => {passes += 1;- return useResizable({defaultSize: 200, minSizePx: 100, maxSizePx: 400});+ return useResizable({defaultSize: 200, minSize: 100, maxSize: 400});});expect(passes).toBe(1);@@ -459,8 +459,8 @@ describe('useResizable identity', () => {passes += 1;useResizable({defaultSize: 200,- minSizePx: 100,- maxSizePx: 400,+ minSize: 100,+ maxSize: 400,containerRef,});return null;@@ -706,8 +706,8 @@ describe('useResizable percentage configuration (AST-010)', () => {expect(result.current.size).toBe(80);});- it('permanently re-clamps a legacy numeric maxSizePx recomputed by the caller', () => {- // #5934: a table-inbox reading pane derives `maxSizePx` itself, as+ it('permanently re-clamps a caller-recomputed numeric maxSize', () => {+ // #5934: a table-inbox reading pane derives `maxSize` itself, as// `Math.max(paneFloor, surfaceWidth - listFloor)`, from a plain// ResizeObserver measurement — no `containerRef`/`maxSize` percentage// in play, so this is the caller-recomputed-literal path, not FR1's@@ -716,9 +716,9 @@ describe('useResizable percentage configuration (AST-010)', () => {// this pins the exact table-inbox pane-widen-then-surface-narrow// sequence from the #5934 review so no fix on either side can drop it.const {result, rerender} = renderHook(- ({maxSizePx}: {maxSizePx: number}) =>- useResizable({defaultSize: 400, minSizePx: 300, maxSizePx}),- {initialProps: {maxSizePx: 1500}},+ ({maxSize}: {maxSize: number}) =>+ useResizable({defaultSize: 400, minSize: 300, maxSize}),+ {initialProps: {maxSize: 1500}},);// The user drags the separator out to 1066px, well inside the@@ -728,32 +728,32 @@ describe('useResizable percentage configuration (AST-010)', () => {// The surface then narrows (no drag involved), so the derived ceiling// drops under the size the user chose.- rerender({maxSizePx: 834});+ rerender({maxSize: 834});expect(result.current.size).toBe(834);expect(result.current.props._size).toBe(834);expect(result.current.props._maxSizePx).toBe(834);// Growing the surface again must not revive the pre-clamp selection.- rerender({maxSizePx: 1500});+ rerender({maxSize: 1500});expect(result.current.size).toBe(834);expect(result.current.props._size).toBe(834);expect(result.current.props._maxSizePx).toBe(1500);});- it('leaves an in-range user choice alone when a legacy maxSizePx shrinks', () => {+ it('leaves an in-range user choice alone when maxSize shrinks', () => {// The other half of #5934's fix: clamping must not become a second// proportional-resize mode. A selection that still fits the new// ceiling is the user's answer and stays exactly where they left it.const {result, rerender} = renderHook(- ({maxSizePx}: {maxSizePx: number}) =>- useResizable({defaultSize: 400, minSizePx: 300, maxSizePx}),- {initialProps: {maxSizePx: 1500}},+ ({maxSize}: {maxSize: number}) =>+ useResizable({defaultSize: 400, minSize: 300, maxSize}),+ {initialProps: {maxSize: 1500}},);act(() => result.current.resize(700));- rerender({maxSizePx: 834});+ rerender({maxSize: 834});expect(result.current.size).toBe(700);});@@ -1090,9 +1090,7 @@ describe('useResizable percentage configuration (AST-010)', () => {['Infinity', pixel(Infinity)],])('rejects an invalid direct PixelWidth: %s', (_label, invalid) => {const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});- const {result} = renderHook(() =>- useResizable({defaultSize: invalid as never}),- );+ const {result} = renderHook(() => useResizable({defaultSize: invalid}));expect(result.current.size).toBe(250);expect(warn).toHaveBeenCalledWith(expect.stringContaining('Falling back to 250'),@@ -1240,9 +1238,7 @@ describe('useResizable percentage configuration (AST-010)', () => {[-1, 'a negative number'],[Number.NaN, 'NaN'],])('falls back to 250px for defaultSize %s (%s)', (invalid, _why) => {- const {result} = renderHook(() =>- useResizable({defaultSize: invalid as never}),- );+ const {result} = renderHook(() => useResizable({defaultSize: invalid}));expect(result.current.size).toBe(250);});@@ -1286,81 +1282,6 @@ describe('useResizable percentage configuration (AST-010)', () => {);warn.mockRestore();});-- it('keeps explicit maxSizePx: Infinity valid', () => {- // A shipped template uses this spelling.- const {result} = renderHook(() =>- useResizable({defaultSize: 900, maxSizePx: Infinity}),- );- expect(result.current.size).toBe(900);- });- });-- describe('API4 — the unified bound beats its deprecated alias', () => {- it('prefers minSize over minSizePx when untyped input supplies both', () => {- // Typed callers cannot do this; a spread or an `any` can, and the- // explicit migration target must not lose to a stale alias.- const {result} = renderHook(() =>- useResizable({- defaultSize: 10,- ...({minSize: 300, minSizePx: 60} as object),- } as never),- );- expect(result.current.size).toBe(300);- });-- it('warns for both ignored aliases when untyped input supplies both pairs', () => {- const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});- const {result} = renderHook(() =>- useResizable({- defaultSize: 250,- ...({- minSize: 100,- minSizePx: 60,- maxSize: 500,- maxSizePx: 800,- } as object),- } as never),- );-- expect(result.current.size).toBe(250);- expect(warn).toHaveBeenCalledTimes(2);- expect(warn).toHaveBeenCalledWith(- 'useResizable: both `minSize` and `minSizePx` were supplied. ' +- '`minSize` wins; the deprecated `minSizePx` is ignored.',- );- expect(warn).toHaveBeenCalledWith(- 'useResizable: both `maxSize` and `maxSizePx` were supplied. ' +- '`maxSize` wins; the deprecated `maxSizePx` is ignored.',- );- warn.mockRestore();- });-- it('preserves exact atomic strings from untyped legacy aliases', () => {- const containerRef = makeContainer();- const {result} = renderHook(() =>- useResizable({- defaultSize: 1000,- containerRef,- ...({minSizePx: '180px', maxSizePx: '50%'} as object),- } as never),- );-- expect(result.current.props._minSizePx).toBe(180);- expect(result.current.props._maxSizePx).toBe(200);- expect(result.current.size).toBe(200);- });-- it('leaves an old-only caller exactly as it was', () => {- const {result} = renderHook(() =>- useResizable({defaultSize: 260, minSizePx: 180, maxSizePx: 480}),- );- expect(result.current.size).toBe(260);- act(() => {- result.current.resize(9999);- });- expect(result.current.size).toBe(480);- });});describe('API6 — resize stays pixels and keeps the last legal size', () => {@@ -1698,29 +1619,27 @@ describe('Resizable size source compatibility (AST-010 API3/API4)', () => {{defaultSize: percent(40, {min: pixel(333)})},{defaultSize: 0, minSize: percent(40, {min: pixel(333)})},{defaultSize: 500, maxSize: percent(10, {max: pixel(400)})},- {defaultSize: 260, minSizePx: 180, maxSizePx: 480},+ {defaultSize: 260, minSize: 180, maxSize: 480},] satisfies UseResizableSingleConfig[];expect(configs).toHaveLength(9);});- it('rejects unsupported bound strings and alias conflicts', () => {+ it('rejects unsupported bound strings and removed pixel aliases', () => {// @ts-expect-error bound strings are exact px/% onlyconst rem: UseResizableSingleConfig = {minSize: '10rem'};const cssMath: UseResizableSingleConfig = {// @ts-expect-error CSS functions are not part of ResizableSizeminSize: 'max(40%, 333px)',};- // @ts-expect-error unified minimum and legacy alias are mutually exclusive- const duplicateMin: UseResizableSingleConfig = {- minSize: '40%',+ const removedMin: UseResizableSingleConfig = {+ // @ts-expect-error minSizePx was removed in 0.6; use minSizeminSizePx: 100,};- // @ts-expect-error unified maximum and legacy alias are mutually exclusive- const duplicateMax: UseResizableSingleConfig = {- maxSize: percent(10, {max: pixel(400)}),+ const removedMax: UseResizableSingleConfig = {+ // @ts-expect-error maxSizePx was removed in 0.6; use maxSizemaxSizePx: 500,};- expect([rem, cssMath, duplicateMin, duplicateMax]).toHaveLength(4);+ expect([rem, cssMath, removedMin, removedMax]).toHaveLength(4);});});diff --git a/packages/core/src/Resizable/useResizable.ts b/packages/core/src/Resizable/useResizable.tsindex 44fbed1326..923a1f9ca1 100644--- a/packages/core/src/Resizable/useResizable.ts+++ b/packages/core/src/Resizable/useResizable.ts@@ -4,8 +4,8 @@/*** @file useResizable.ts- * @input Resize configuration (defaultSize, minSize, maxSize, legacy pixel- * aliases, snaps) and collapse configuration (collapsible,+ * @input Resize configuration (defaultSize, minSize, maxSize, snaps) and+ * collapse configuration (collapsible,* defaultIsCollapsed, isCollapsed)* @output Hook return: size, isCollapsed, collapse/expand/resize methods, props for handle* @position Public hook; consumed by layout components via `resizable` prop@@ -29,19 +29,11 @@ import type {ResizableSize} from './utils';// Types// =============================================================================-/**- * The minimum, in one of two spellings. Exactly one may be supplied: the union- * makes passing both a type error, so a migration cannot leave a stale- * deprecated value shadowing the new one (AST-010 API4).- */-export type ResizableMinConfig =- | {minSize?: ResizableSize; minSizePx?: never}- | {minSize?: never; minSizePx?: number};+/** Minimum size configuration. */+export type ResizableMinConfig = {minSize?: ResizableSize};-/** The maximum, in one of two spellings. See {@link ResizableMinConfig}. */-export type ResizableMaxConfig =- | {maxSize?: ResizableSize; maxSizePx?: never}- | {maxSize?: never; maxSizePx?: number};+/** Maximum size configuration. */+export type ResizableMaxConfig = {maxSize?: ResizableSize};export type ResizableDirection = 'horizontal' | 'vertical';@@ -315,9 +307,6 @@ const RESIZABLE_SIZE_GUIDANCE ='Use a non-negative number of pixels, an exact "Npx" string, an exact ' +'"N%" string from 0% to 100%, pixel(value), or ' +'percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)}).';-const LEGACY_PIXEL_GUIDANCE = 'Use a non-negative number of pixels.';-const LEGACY_MAX_PIXEL_GUIDANCE =- 'Use a non-negative number of pixels or explicit Infinity.';/** Parsed, validated input. */type ParsedSize =@@ -408,22 +397,6 @@ function parseSize(value: unknown): ParsedSize | null {return null;}-function parseLegacyPixel(- value: unknown,- allowInfinity: boolean,-): ParsedSize | null {- if (allowInfinity && value === Infinity) {- return {kind: 'px', value};- }- if (typeof value === 'number') {- return Number.isFinite(value) && value >= 0 ? {kind: 'px', value} : null;- }- // Preserve the released runtime compatibility for untyped callers. The- // public aliases remain number-only, but exact atomic strings worked before- // they were deprecated and continue to resolve through the same fast path.- return typeof value === 'string' ? parseSizeString(value) : null;-}-/** Whether this parsed value must be recomputed when its basis changes. */function dependsOnBasis(parsed: ParsedSize | null): boolean {return parsed?.kind === 'percent';@@ -513,8 +486,8 @@ function resolveBound(if (raw === undefined) {return fallback;}- // Preserve the released explicit unbounded maximum on both the unified and- // deprecated spellings. Other roles still reject non-finite numbers.+ // Preserve the released explicit unbounded maximum. Other roles still+ // reject non-finite numbers.if (raw === Infinity && fallback === Infinity) {return Infinity;}@@ -576,8 +549,6 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {defaultSize,minSize,maxSize,- minSizePx,- maxSizePx,containerRef,direction = 'horizontal',collapsible = false,@@ -592,24 +563,12 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {const emptySnapsRef = useRef<number[]>([]);const snaps = configuredSnaps ?? emptySnapsRef.current;- // The unified prop wins over its deprecated alias. The types make supplying- // both an error, so reaching here means untyped JavaScript, an `any`, or a- // spread — exactly the case where a stale alias hidden in an object would- // otherwise silently beat the explicit migration target.- const hasUnifiedMin = minSize !== undefined;- const hasUnifiedMax = maxSize !== undefined;- const minConflict = hasUnifiedMin && minSizePx !== undefined;- const maxConflict = hasUnifiedMax && maxSizePx !== undefined;- const rawMin = hasUnifiedMin ? minSize : minSizePx;- const rawMax = hasUnifiedMax ? maxSize : maxSizePx;+ const rawMin = minSize;+ const rawMax = maxSize;const parsedDefault = parseSize(defaultSize);- const parsedMin = hasUnifiedMin- ? parseSize(minSize)- : parseLegacyPixel(minSizePx, false);- const parsedMax = hasUnifiedMax- ? parseSize(maxSize)- : parseLegacyPixel(maxSizePx, true);+ const parsedMin = parseSize(minSize);+ const parsedMax = parseSize(maxSize);const hasContainer = containerRef != null;const persisted = autoSaveId ? loadPersistedState(autoSaveId) : null;const initialDefaultRef = useRef<{px: number; isFinal: boolean} | null>(null);@@ -771,8 +730,6 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {const didWarnMaxRef = useRef(false);const didWarnDefaultRef = useRef(false);const didWarnInvertedRef = useRef(false);- const didWarnMinAliasRef = useRef(false);- const didWarnMaxAliasRef = useRef(false);// Bounds re-resolve from the live basis on every render — that is the whole// point of a percentage bound — and clamp the pixel selection below.@@ -781,8 +738,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {parsedMin,basis,DEFAULT_MIN,- hasUnifiedMin ? 'minSize' : 'minSizePx',- hasUnifiedMin ? RESIZABLE_SIZE_GUIDANCE : LEGACY_PIXEL_GUIDANCE,+ 'minSize',+ RESIZABLE_SIZE_GUIDANCE,didWarnMinRef,);const resolvedMax = resolveBound(@@ -790,8 +747,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {parsedMax,basis,Infinity,- hasUnifiedMax ? 'maxSize' : 'maxSizePx',- hasUnifiedMax ? RESIZABLE_SIZE_GUIDANCE : LEGACY_MAX_PIXEL_GUIDANCE,+ 'maxSize',+ RESIZABLE_SIZE_GUIDANCE,didWarnMaxRef,);@@ -933,27 +890,6 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {[isControlled],);- // Configuration warnings live in an effect, not in render: render runs twice- // under StrictMode and must stay free of side effects.- useEffect(() => {- if (minConflict && !didWarnMinAliasRef.current) {- didWarnMinAliasRef.current = true;- devWarn(- 'useResizable',- 'both `minSize` and `minSizePx` were supplied. `minSize` wins; the ' +- 'deprecated `minSizePx` is ignored.',- );- }- if (maxConflict && !didWarnMaxAliasRef.current) {- didWarnMaxAliasRef.current = true;- devWarn(- 'useResizable',- 'both `maxSize` and `maxSizePx` were supplied. `maxSize` wins; the ' +- 'deprecated `maxSizePx` is ignored.',- );- }- }, [minConflict, maxConflict]);-useEffect(() => {if (resolvedMin > resolvedMax && !didWarnInvertedRef.current) {didWarnInvertedRef.current = true;diff --git a/packages/core/src/SideNav/SideNav.tsx b/packages/core/src/SideNav/SideNav.tsxindex d5227cdc55..4a3c3b3c18 100644--- a/packages/core/src/SideNav/SideNav.tsx+++ b/packages/core/src/SideNav/SideNav.tsx@@ -440,8 +440,8 @@ export function SideNav({// owner mounted when resize is toggled preserves the current collapse state.const resizableHook = useResizable({defaultSize: resizableConfig.defaultWidth ?? 260,- minSizePx: resizableConfig.minWidth ?? 180,- maxSizePx: resizableConfig.maxWidth ?? 480,+ minSize: resizableConfig.minWidth ?? 180,+ maxSize: resizableConfig.maxWidth ?? 480,collapsible: isCollapsible,collapsedSize: COLLAPSE_THRESHOLD,autoSaveId: resizableConfig.autoSaveId,diff --git a/packages/core/src/hooks/deprecatedApis.public.test.ts b/packages/core/src/hooks/deprecatedApis.public.test.tsnew file mode 100644index 0000000000..3dc04b70f7--- /dev/null+++ b/packages/core/src/hooks/deprecatedApis.public.test.ts@@ -0,0 +1,33 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file deprecatedApis.public.test.ts+ * @input Public hooks barrel and focus option types+ * @output Guards the 0.6 removal of explicitly deprecated hook APIs+ * @position Public API compatibility test; enforced by Vitest and Core typecheck+ */++import {describe, expect, it} from 'vitest';+import * as hooks from './index';+import type {UseGridFocusOptions} from './useGridFocus';+import type {UseListFocusOptions} from './useListFocus';++describe('0.6 removed hook APIs', () => {+ it('does not export isImeKeyEvent from the hooks barrel', () => {+ expect(hooks).not.toHaveProperty('isImeKeyEvent');+ });++ it('does not accept explicit direction overrides', () => {+ const grid: UseGridFocusOptions = {+ columns: 3,+ // @ts-expect-error isRtl was removed; direction comes from the container+ isRtl: true,+ };+ const list: UseListFocusOptions = {+ // @ts-expect-error isRtl was removed; direction comes from the container+ isRtl: false,+ };+ expect(grid.columns).toBe(3);+ expect(list).toBeDefined();+ });+});diff --git a/packages/core/src/hooks/index.ts b/packages/core/src/hooks/index.tsindex 5796d2bb32..854886c307 100644--- a/packages/core/src/hooks/index.ts+++ b/packages/core/src/hooks/index.ts@@ -14,14 +14,6 @@export {hasActiveFocusTrapEscape, useFocusTrap} from './useFocusTrap';export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';-/**- * @deprecated Import from `@astryxdesign/core/utils` instead — this is a pure- * predicate, not a hook, and the `hooks` barrel is a `'use client'` boundary.- * Re-exported here for one release so consumers can move; will be removed in- * an upcoming major.- */-export {isImeKeyEvent} from '../utils/ime';-export {useAnnounce} from './useAnnounce';export type {AnnounceFn, AnnouncePoliteness} from './useAnnounce';diff --git a/packages/core/src/hooks/useGridFocus.doc.mjs b/packages/core/src/hooks/useGridFocus.doc.mjsindex e0c021f90e..0d1e009021 100644--- a/packages/core/src/hooks/useGridFocus.doc.mjs+++ b/packages/core/src/hooks/useGridFocus.doc.mjs@@ -4,7 +4,17 @@export const docs = {name: 'useGridFocus',displayName: 'useGridFocus',- keywords: ['grid', 'focus', 'keyboard', 'navigation', 'arrow', 'calendar', 'a11y', 'wai-aria', 'cells'],+ keywords: [+ 'grid',+ 'focus',+ 'keyboard',+ 'navigation',+ 'arrow',+ 'calendar',+ 'a11y',+ 'wai-aria',+ 'cells',+ ],params: [{name: 'options',@@ -15,63 +25,65 @@ export const docs = {{name: 'options.columns',type: 'number',- description: 'Number of columns in the grid. Used for up/down navigation (moves by this many cells).',+ description:+ 'Number of columns in the grid. Used for up/down navigation (moves by this many cells).',required: true,},{name: 'options.cellSelector',type: 'string',- description: 'Selector for cells within the grid. Should match ALL cell positions in DOM order (including disabled/empty) so grid geometry is preserved.',- default: "'button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])'",+ description:+ 'Selector for cells within the grid. Should match ALL cell positions in DOM order (including disabled/empty) so grid geometry is preserved.',+ default: '\'button:not([disabled]), [tabindex]:not([tabindex="-1"])\'',required: false,},{name: 'options.isCellFocusable',type: '(cell: HTMLElement) => boolean',- description: 'Predicate for whether a matched cell can receive focus. Omit to treat every matched cell as focusable.',+ description:+ 'Predicate for whether a matched cell can receive focus. Omit to treat every matched cell as focusable.',required: false,},{name: 'options.getFocusTarget',type: '(cell: HTMLElement) => HTMLElement | null',- description: 'Resolves the element to focus for a cell, e.g. a button inside a role="gridcell" wrapper. Omit to focus the cell itself.',+ description:+ 'Resolves the element to focus for a cell, e.g. a button inside a role="gridcell" wrapper. Omit to focus the cell itself.',required: false,},{name: 'options.onNavigateBefore',type: '(column: number, offset: number) => void',- description: 'Callback when navigation would go before the first cell. Receives the column index and offset (1 for horizontal, columns for vertical).',+ description:+ 'Callback when navigation would go before the first cell. Receives the column index and offset (1 for horizontal, columns for vertical).',required: false,},{name: 'options.onNavigateAfter',type: '(column: number, offset: number) => void',- description: 'Callback when navigation would go after the last cell. Receives the column index and offset.',+ description:+ 'Callback when navigation would go after the last cell. Receives the column index and offset.',required: false,},{name: 'options.onPageUp',type: '() => void',- description: 'Callback for Page Up key (e.g., navigate to previous month in calendars).',+ description:+ 'Callback for Page Up key (e.g., navigate to previous month in calendars).',required: false,},{name: 'options.onPageDown',type: '() => void',- description: 'Callback for Page Down key (e.g., navigate to next month in calendars).',- required: false,- },- {- name: 'options.isRtl',- type: 'boolean',- description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts. When omitted, auto-detected from the container computed direction on keydown.',- default: "undefined (auto-detect from the container's computed direction)",+ description:+ 'Callback for Page Down key (e.g., navigate to next month in calendars).',required: false,},{name: 'options.hasRovingTabIndex',type: 'boolean',- description: 'Own a single roving tab stop across the grid: one focusable cell (its resolved focus target) carries tabindex="0", the rest -1. Stamped/repaired on render and moved with arrow navigation. Attach the returned handleFocus to the container onFocus.',+ description:+ 'Own a single roving tab stop across the grid: one focusable cell (its resolved focus target) carries tabindex="0", the rest -1. Stamped/repaired on render and moved with arrow navigation. Attach the returned handleFocus to the container onFocus.',default: 'false',required: false,},@@ -90,7 +102,8 @@ export const docs = {{name: 'handleFocus',type: '(e: React.FocusEvent) => void',- description: 'Focus handler for the grid container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so always safe to attach.',+ description:+ 'Focus handler for the grid container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so always safe to attach.',},{name: 'focusCell',@@ -112,10 +125,26 @@ export const docs = {description:'Manages keyboard navigation within a 2D grid following the WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, and Page Up/Down for custom callbacks (e.g., month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',bestPractices: [- { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation and onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },- { guidance: true, description: 'Attach both gridRef and handleKeyDown to the grid container element.' },- { guidance: true, description: 'For roving-tabindex grids (e.g. Calendar), set hasRovingTabIndex: true and attach handleFocus to the container onFocus; seed one focus target with tabindex=0 and the hook repairs and moves it.' },- { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },+ {+ guidance: true,+ description:+ 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation and onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.',+ },+ {+ guidance: true,+ description:+ 'Attach both gridRef and handleKeyDown to the grid container element.',+ },+ {+ guidance: true,+ description:+ 'For roving-tabindex grids (e.g. Calendar), set hasRovingTabIndex: true and attach handleFocus to the container onFocus; seed one focus target with tabindex=0 and the hook repairs and moves it.',+ },+ {+ guidance: false,+ description:+ 'Use for simple linear lists; prefer useListFocus for 1D navigation.',+ },],},relatedComponents: ['Calendar'],@@ -130,21 +159,30 @@ export const docsDense = {'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',paramDescriptions: {options: 'config for grid focus behavior.',- 'options.columns': '# columns in grid. Used for up/down navigation (moves by this many cells).',- 'options.cellSelector': 'selector for grid cells in DOM order (incl. disabled/empty) so geometry is preserved.',- 'options.isCellFocusable': 'predicate for whether a matched cell can take focus. Omit = all focusable.',- 'options.getFocusTarget': 'resolve element to focus for a cell (e.g. button inside gridcell wrapper). Omit = focus the cell.',- 'options.onNavigateBefore': 'callback when navigation would go before first cell. Receives column index + offset (1 for horizontal, columns for vertical).',- 'options.onNavigateAfter': 'callback when navigation would go after last cell. Receives column index + offset.',- 'options.onPageUp': 'callback for Page Up key (e.g. navigate to previous month in calendars).',- 'options.onPageDown': 'callback for Page Down key (e.g. navigate to next month in calendars).',- 'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default: auto-detect from container computed direction; explicit boolean wins.',- 'options.hasRovingTabIndex': 'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',+ 'options.columns':+ '# columns in grid. Used for up/down navigation (moves by this many cells).',+ 'options.cellSelector':+ 'selector for grid cells in DOM order (incl. disabled/empty) so geometry is preserved.',+ 'options.isCellFocusable':+ 'predicate for whether a matched cell can take focus. Omit = all focusable.',+ 'options.getFocusTarget':+ 'resolve element to focus for a cell (e.g. button inside gridcell wrapper). Omit = focus the cell.',+ 'options.onNavigateBefore':+ 'callback when navigation would go before first cell. Receives column index + offset (1 for horizontal, columns for vertical).',+ 'options.onNavigateAfter':+ 'callback when navigation would go after last cell. Receives column index + offset.',+ 'options.onPageUp':+ 'callback for Page Up key (e.g. navigate to previous month in calendars).',+ 'options.onPageDown':+ 'callback for Page Down key (e.g. navigate to next month in calendars).',+ 'options.hasRovingTabIndex':+ 'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',},returnDescriptions: {gridRef: 'ref to attach to grid container element.',handleKeyDown: 'key down handler for grid container.',- handleFocus: 'focus handler for grid container; syncs roving tab stop when hasRovingTabIndex on, else no-op.',+ handleFocus:+ 'focus handler for grid container; syncs roving tab stop when hasRovingTabIndex on, else no-op.',focusCell: 'focus specific cell by index (clamped to valid range).',focusFirst: 'focus first focusable cell in grid.',focusLast: 'focus last focusable cell in grid.',@@ -153,10 +191,26 @@ export const docsDense = {description:'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',bestPractices: [- { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation + onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },- { guidance: true, description: 'Attach both gridRef + handleKeyDown to grid container element.' },- { guidance: true, description: 'For roving-tabindex grids (e.g. Calendar): hasRovingTabIndex: true + attach handleFocus to onFocus; seed one focus target tabindex=0, hook repairs + moves it.' },- { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },+ {+ guidance: true,+ description:+ 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation + onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.',+ },+ {+ guidance: true,+ description:+ 'Attach both gridRef + handleKeyDown to grid container element.',+ },+ {+ guidance: true,+ description:+ 'For roving-tabindex grids (e.g. Calendar): hasRovingTabIndex: true + attach handleFocus to onFocus; seed one focus target tabindex=0, hook repairs + moves it.',+ },+ {+ guidance: false,+ description:+ 'Use for simple linear lists; prefer useListFocus for 1D navigation.',+ },],},};diff --git a/packages/core/src/hooks/useGridFocus.test.tsx b/packages/core/src/hooks/useGridFocus.test.tsxindex 8c58add7f6..28fbc20c84 100644--- a/packages/core/src/hooks/useGridFocus.test.tsx+++ b/packages/core/src/hooks/useGridFocus.test.tsx@@ -113,7 +113,7 @@ describe('useGridFocus roving tabindex (hasRovingTabIndex)', () => {});it('flips ArrowLeft/ArrowRight under RTL', () => {- render(<Grid seed={1} isRtl />);+ render(<Grid seed={1} dir="rtl" />);const grid = screen.getByRole('grid');screen.getByTestId('cell-1').focus();// In RTL, ArrowLeft is "forward" (moves to the next cell in DOM order).@@ -162,12 +162,4 @@ describe('useGridFocus RTL auto-detection (WCAG 1.3.2)', () => {fireEvent.keyDown(grid, {key: 'ArrowDown'});expect(screen.getByTestId('cell-3')).toHaveFocus();});-- it('explicit isRtl={false} overrides a dir="rtl" container', () => {- render(<Grid seed={1} dir="rtl" isRtl={false} />);- const grid = screen.getByRole('grid');- screen.getByTestId('cell-1').focus();- fireEvent.keyDown(grid, {key: 'ArrowRight'});- expect(screen.getByTestId('cell-2')).toHaveFocus();- });});diff --git a/packages/core/src/hooks/useGridFocus.ts b/packages/core/src/hooks/useGridFocus.tsindex 0268afdd93..ee8aa1e124 100644--- a/packages/core/src/hooks/useGridFocus.ts+++ b/packages/core/src/hooks/useGridFocus.ts@@ -89,20 +89,6 @@ export interface UseGridFocusOptions {*/onPageDown?: () => void;- /**- * @deprecated Direction is auto-detected from the container's computed- * `direction` — omit this. The explicit override is redundant (there's no- * valid reason to force RTL arrows in an LTR context) and will be removed in- * an upcoming major.- *- * When set, forces whether the grid is right-to-left: ArrowLeft/ArrowRight- * are swapped so horizontal navigation follows visual direction. When- * omitted (preferred), the direction is auto-detected from the container's- * computed `direction` (read lazily on keydown, horizontal arrows only).- * @default undefined (auto-detect from the container)- */- isRtl?: boolean;-/*** Roving-tabindex ownership. When true, the hook manages a single tab stop* across the grid: exactly one focusable cell carries `tabindex="0"` and the@@ -228,7 +214,6 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(onNavigateAfter,onPageUp,onPageDown,- isRtl,hasRovingTabIndex = false,} = options;@@ -468,11 +453,11 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(// follows visual direction. Vertical keys (Up/Down) are unaffected.// Direction is resolved lazily — getComputedStyle runs only when a// horizontal arrow key is actually pressed (SSR-safe, no layout thrash- // on unrelated keys) — and an explicit `isRtl` always wins.+ // on unrelated keys).let key = e.key;if ((key === 'ArrowLeft' || key === 'ArrowRight') &&- (isRtl ?? isRtlElement(gridRef.current))+ isRtlElement(gridRef.current)) {key = key === 'ArrowLeft' ? 'ArrowRight' : 'ArrowLeft';}@@ -595,7 +580,6 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(focusLast,getCells,getCurrentIndex,- isRtl,onNavigateAfter,onNavigateBefore,onPageDown,diff --git a/packages/core/src/hooks/useListFocus.doc.mjs b/packages/core/src/hooks/useListFocus.doc.mjsindex 8c644b3357..e0ba80a528 100644--- a/packages/core/src/hooks/useListFocus.doc.mjs+++ b/packages/core/src/hooks/useListFocus.doc.mjs@@ -4,19 +4,32 @@export const docs = {name: 'useListFocus',displayName: 'useListFocus',- keywords: ['list', 'focus', 'keyboard', 'navigation', 'menu', 'toolbar', 'roving', 'tabindex', 'a11y', 'arrow', 'wai-aria'],+ keywords: [+ 'list',+ 'focus',+ 'keyboard',+ 'navigation',+ 'menu',+ 'toolbar',+ 'roving',+ 'tabindex',+ 'a11y',+ 'arrow',+ 'wai-aria',+ ],params: [{name: 'options',type: 'UseListFocusOptions',- description: 'Configuration object for list focus behavior. All fields are optional.',+ description:+ 'Configuration object for list focus behavior. All fields are optional.',required: false,},{name: 'options.itemSelector',type: 'string',description: 'Selector for focusable items within the list.',- default: "'[role=\"menuitem\"]'",+ default: '\'[role="menuitem"]\'',required: false,},{@@ -36,13 +49,15 @@ export const docs = {{name: 'options.onEscape',type: '() => void',- description: 'Callback when Escape key is pressed (e.g., close menu). Supplying it also consumes the key (preventDefault); without it Escape passes through to the surrounding layer.',+ description:+ 'Callback when Escape key is pressed (e.g., close menu). Supplying it also consumes the key (preventDefault); without it Escape passes through to the surrounding layer.',required: false,},{name: 'options.orientation',type: "'horizontal' | 'vertical' | 'both'",- description: "Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",+ description:+ "Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",default: "'vertical'",required: false,},@@ -53,24 +68,19 @@ export const docs = {default: 'true',required: false,},- {- name: 'options.isRtl',- type: 'boolean',- description: 'Whether the list is in a right-to-left context. When true, ArrowLeft/ArrowRight are swapped for horizontal navigation so it follows visual direction. When omitted, auto-detected from the container computed direction on keydown.',- default: "undefined (auto-detect from the container's computed direction)",- required: false,- },{name: 'options.hasRovingTabIndex',type: 'boolean',- description: 'Opt into roving-tabindex ownership: the hook stamps a single tab stop (one item tabindex="0", the rest -1), repairs it as items mount/unmount or toggle disabled, and moves it with arrow navigation. When false, the hook only moves focus and never touches tabindex.',+ description:+ 'Opt into roving-tabindex ownership: the hook stamps a single tab stop (one item tabindex="0", the rest -1), repairs it as items mount/unmount or toggle disabled, and moves it with arrow navigation. When false, the hook only moves focus and never touches tabindex.',default: 'false',required: false,},{name: 'options.hasCaretGuard',type: 'boolean',- description: "When true, arrow keys are not stolen from a nested text input/textarea whose caret is not at the boundary in the direction of travel (or that has a selection), and are never stolen from a nested contenteditable (rich-text editor / chat composer). Preserves inline text editing within the list.",+ description:+ 'When true, arrow keys are not stolen from a nested text input/textarea whose caret is not at the boundary in the direction of travel (or that has a selection), and are never stolen from a nested contenteditable (rich-text editor / chat composer). Preserves inline text editing within the list.',default: 'false',required: false,},@@ -89,7 +99,8 @@ export const docs = {{name: 'handleFocus',type: '(e: React.FocusEvent) => void',- description: 'Focus handler for the container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so it is always safe to attach.',+ description:+ 'Focus handler for the container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so it is always safe to attach.',},{name: 'focusItem',@@ -99,18 +110,20 @@ export const docs = {{name: 'focusFirst',type: '() => boolean',- description: 'Focus the first enabled item. Returns true when an item was focused.',+ description:+ 'Focus the first enabled item. Returns true when an item was focused.',},{name: 'focusLast',type: '() => boolean',- description: 'Focus the last enabled item. Returns true when an item was focused.',+ description:+ 'Focus the last enabled item. Returns true when an item was focused.',},{name: 'ownsEvent',type: '(e: React.KeyboardEvent) => boolean',description:- "Whether a key event belongs to this list level rather than a nested list sharing the same boundarySelector. Always true when no boundarySelector is set. Use to guard consumer-added key handling (Enter/Space, typeahead).",+ 'Whether a key event belongs to this list level rather than a nested list sharing the same boundarySelector. Always true when no boundarySelector is set. Use to guard consumer-added key handling (Enter/Space, typeahead).',},{name: 'getItems',@@ -123,10 +136,26 @@ export const docs = {description:'Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical, horizontal, or both), Home/End for boundaries, optional wrap-around, RTL, and Escape to close. Opt into hasRovingTabIndex for composite widgets (toolbars, segmented controls, tab strips) that own a single tab stop. Suitable for dropdown menus, toolbars, and any 1D focusable list.',bestPractices: [- { guidance: true, description: "Set orientation to 'horizontal' for toolbars and tab bars, 'vertical' for dropdown menus." },- { guidance: true, description: 'Provide an onEscape callback for menus/dropdowns to return focus to the trigger.' },- { guidance: true, description: 'Enable hasRovingTabIndex (and hasCaretGuard when the widget can contain text inputs) for toolbar-style composites that should be a single tab stop.' },- { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids and calendars.' },+ {+ guidance: true,+ description:+ "Set orientation to 'horizontal' for toolbars and tab bars, 'vertical' for dropdown menus.",+ },+ {+ guidance: true,+ description:+ 'Provide an onEscape callback for menus/dropdowns to return focus to the trigger.',+ },+ {+ guidance: true,+ description:+ 'Enable hasRovingTabIndex (and hasCaretGuard when the widget can contain text inputs) for toolbar-style composites that should be a single tab stop.',+ },+ {+ guidance: false,+ description:+ 'Use for 2D grid navigation; prefer useGridFocus for grids and calendars.',+ },],},relatedComponents: ['TabMenu', 'Toolbar'],@@ -142,33 +171,56 @@ export const docsDense = {paramDescriptions: {options: 'config for list focus behavior. All fields optional.','options.itemSelector': 'selector for focusable items in list.',- 'options.boundarySelector': "boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.",+ 'options.boundarySelector':+ 'boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.','options.wrap': 'whether arrow navigation wraps around at ends.',- 'options.onEscape': 'callback when Escape key pressed (e.g. close menu). Also consumes the key; without it Escape passes through to the surrounding layer.',- 'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",+ 'options.onEscape':+ 'callback when Escape key pressed (e.g. close menu). Also consumes the key; without it Escape passes through to the surrounding layer.',+ 'options.orientation':+ "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',- 'options.isRtl': 'ArrowLeft/ArrowRight swap for horizontal nav (RTL). default: auto-detect from container computed direction; explicit boolean wins.',- 'options.hasRovingTabIndex': 'opt into roving-tabindex ownership: hook stamps + repairs a single tab stop across items.',- 'options.hasCaretGuard': "when true, don't steal arrow keys from a nested text input/textarea mid-line or from a contenteditable.",+ 'options.hasRovingTabIndex':+ 'opt into roving-tabindex ownership: hook stamps + repairs a single tab stop across items.',+ 'options.hasCaretGuard':+ "when true, don't steal arrow keys from a nested text input/textarea mid-line or from a contenteditable.",},returnDescriptions: {listRef: 'ref to attach to list container element.',handleKeyDown: 'key down handler for list container.',- handleFocus: 'focus handler; keeps roving tab stop in sync when hasRovingTabIndex is on (else no-op).',+ handleFocus:+ 'focus handler; keeps roving tab stop in sync when hasRovingTabIndex is on (else no-op).',focusItem: 'focus specific item by index (clamped to valid range).',focusFirst: 'focus first enabled item; returns true when focused.',focusLast: 'focus last enabled item; returns true when focused.',- ownsEvent: 'whether a key event is this level\'s vs a nested list\'s (boundarySelector); always true without one.',- getItems: "this level's focusable items in DOM order, scoped by boundarySelector.",+ ownsEvent:+ "whether a key event is this level's vs a nested list's (boundarySelector); always true without one.",+ getItems:+ "this level's focusable items in DOM order, scoped by boundarySelector.",},usage: {description:'Manages keyboard navigation within linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical / horizontal), Home/End for boundaries, optional wrap-around, Escape to close. Suitable for dropdown menus, toolbars, any 1D focusable list.',bestPractices: [- { guidance: true, description: "Set orientation to 'horizontal' for toolbars + tab bars, 'vertical' for dropdown menus." },- { guidance: true, description: 'Provide onEscape callback for menus/dropdowns to return focus to trigger.' },- { guidance: true, description: 'Enable hasRovingTabIndex (+ hasCaretGuard when widget can contain text inputs) for toolbar-style composites that should be a single tab stop.' },- { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids + calendars.' },+ {+ guidance: true,+ description:+ "Set orientation to 'horizontal' for toolbars + tab bars, 'vertical' for dropdown menus.",+ },+ {+ guidance: true,+ description:+ 'Provide onEscape callback for menus/dropdowns to return focus to trigger.',+ },+ {+ guidance: true,+ description:+ 'Enable hasRovingTabIndex (+ hasCaretGuard when widget can contain text inputs) for toolbar-style composites that should be a single tab stop.',+ },+ {+ guidance: false,+ description:+ 'Use for 2D grid navigation; prefer useGridFocus for grids + calendars.',+ },],},};diff --git a/packages/core/src/hooks/useListFocus.test.tsx b/packages/core/src/hooks/useListFocus.test.tsxindex b0aae73040..e85a56406d 100644--- a/packages/core/src/hooks/useListFocus.test.tsx+++ b/packages/core/src/hooks/useListFocus.test.tsx@@ -109,7 +109,7 @@ describe('useListFocus disabled-item skipping', () => {// ---------------------------------------------------------------------------// Roving-tabindex mode + composite navigation behaviors.-// These exercise the opt-in `hasRovingTabIndex`, `isRtl`, `orientation: 'both'`,+// These exercise the opt-in `hasRovingTabIndex`, `orientation: 'both'`,// `hasCaretGuard`, and shortcut-passthrough behaviors.// ---------------------------------------------------------------------------@@ -206,15 +206,6 @@ describe('useListFocus roving tabindex (hasRovingTabIndex)', () => {expect(screen.getByTestId('A')).toHaveFocus();});- it('flips ArrowLeft/ArrowRight under RTL', () => {- render(<RovingToolbar isRtl />);- const toolbar = screen.getByRole('toolbar');- screen.getByTestId('A').focus();- // In RTL, ArrowLeft is "forward".- fireEvent.keyDown(toolbar, {key: 'ArrowLeft'});- expect(screen.getByTestId('B')).toHaveFocus();- });-it('orientation "both" navigates with all four arrows', () => {render(<RovingToolbar orientation="both" />);const toolbar = screen.getByRole('toolbar');@@ -382,10 +373,9 @@ describe('useListFocus shortcut passthrough', () => {* `dir` is set on the list container itself — the element the hook reads via* listRef.*/-function HorizontalMenu({dir, isRtl}: {dir?: 'ltr' | 'rtl'; isRtl?: boolean}) {+function HorizontalMenu({dir}: {dir?: 'ltr' | 'rtl'}) {const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({orientation: 'horizontal',- isRtl,});const items = ['One', 'Two', 'Three'];return (@@ -423,22 +413,6 @@ describe('useListFocus RTL auto-detection (WCAG 1.3.2)', () => {fireEvent.keyDown(menu, {key: 'ArrowRight'});expect(screen.getByTestId('Two')).toHaveFocus();});-- it('explicit isRtl={false} overrides a dir="rtl" container', () => {- render(<HorizontalMenu dir="rtl" isRtl={false} />);- const menu = screen.getByRole('menu');- screen.getByTestId('One').focus();- fireEvent.keyDown(menu, {key: 'ArrowRight'});- expect(screen.getByTestId('Two')).toHaveFocus();- });-- it('explicit isRtl={true} flips arrows without a dir attribute', () => {- render(<HorizontalMenu isRtl />);- const menu = screen.getByRole('menu');- screen.getByTestId('One').focus();- fireEvent.keyDown(menu, {key: 'ArrowLeft'});- expect(screen.getByTestId('Two')).toHaveFocus();- });});// A menu whose second item contains a NESTED role="menu" (mirrors an inlinediff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.tsindex cdb6a491e7..7cca9766ed 100644--- a/packages/core/src/hooks/useListFocus.ts+++ b/packages/core/src/hooks/useListFocus.ts@@ -85,20 +85,6 @@ export interface UseListFocusOptions {*/hasHomeEnd?: boolean;- /**- * @deprecated Direction is auto-detected from the container's computed- * `direction` — omit this. The explicit override is redundant (there's no- * valid reason to force RTL arrows in an LTR context) and will be removed in- * an upcoming major.- *- * When set, forces whether the list is right-to-left: ArrowLeft/ArrowRight- * are swapped so horizontal navigation follows visual direction. When- * omitted (preferred), the direction is auto-detected from the container's- * computed `direction` (read lazily on keydown, horizontal arrows only).- * @default undefined (auto-detect from the container)- */- isRtl?: boolean;-/*** Roving-tabindex ownership. When true, the hook manages a single tab stop* across the items: exactly one enabled item carries `tabindex="0"` and the@@ -327,7 +313,6 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(onEscape,orientation = 'vertical',hasHomeEnd = true,- isRtl,hasRovingTabIndex = false,hasCaretGuard = false,} = options;@@ -580,13 +565,13 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(// Resolve which keys advance vs retreat, honoring RTL for horizontal.// Direction is resolved lazily — getComputedStyle runs only when a// horizontal arrow key is actually pressed (SSR-safe, no layout thrash- // on unrelated keys) — and an explicit `isRtl` always wins.+ // on unrelated keys).const nextKeys: string[] = [];const prevKeys: string[] = [];if (horizontal) {const rtl =e.key === 'ArrowLeft' || e.key === 'ArrowRight'- ? (isRtl ?? isRtlElement(listRef.current))+ ? isRtlElement(listRef.current): false;nextKeys.push(rtl ? 'ArrowLeft' : 'ArrowRight');prevKeys.push(rtl ? 'ArrowRight' : 'ArrowLeft');@@ -644,7 +629,6 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(getItems,wrap,orientation,- isRtl,hasHomeEnd,hasCaretGuard,findEnabledIndex,