Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/.changeset/remove-deprecated-core-apis.md b/.changeset/remove-deprecated-core-apis.md
new file mode 100644
index 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`.
+
+@cixzhang
diff --git a/apps/docsite/src/app/playground/PlaygroundClient.tsx b/apps/docsite/src/app/playground/PlaygroundClient.tsx
index 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.tsx
index 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.tsx
index 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.md
index df7d3fae07..4d90e9a2ad 100644
--- a/docs/specs/AST-010/spec.md
+++ b/docs/specs/AST-010/spec.md
@@ -8,7 +8,7 @@ archive_reason: null
superseded_by: null
approved_by: cixzhang
approved_at: 2026-08-31
-phase: accepted
+phase: shipped
owners: [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 value
with neither bound, both bounds, another discriminator, or any invalid number is
invalid. 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 fallback
without warning. After initialization, an invalid raw value MUST NOT directly
replace 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. After
initialization, 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` fallbacks
before 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 the
Resizable 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 axis
and 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 bound
or 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 the
maximum, 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 ceiling
Mixing units across the initial size and bounds is valid. This gives builders one
predictable 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 separate
percentage 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 questions
None. Changing the released 1200px server fallback or adding a persistent
diff --git a/packages/cli/assets/codemods/transforms/next/__tests__/next-codemods.test.mjs b/packages/cli/assets/codemods/transforms/next/__tests__/next-codemods.test.mjs
new file mode 100644
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.mjs
index 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.md
index 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 not
diff --git a/packages/core/src/Resizable/ResizeHandle.test.tsx b/packages/core/src/Resizable/ResizeHandle.test.tsx
index 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', () => {
<Harness
config={{
defaultSize: 200,
- minSizePx: 100,
- maxSizePx: 400,
+ minSize: 100,
+ maxSize: 400,
direction: 'vertical',
}}
handleProps={{direction: 'vertical'}}
@@ -186,8 +186,8 @@ describe('ResizeHandle', () => {
<Harness
config={{
defaultSize: 200,
- minSizePx: 100,
- maxSizePx: 400,
+ minSize: 100,
+ maxSize: 400,
collapsible: true,
}}
/>,
@@ -207,8 +207,8 @@ describe('ResizeHandle', () => {
<Harness
config={{
defaultSize: 200,
- minSizePx: 100,
- maxSizePx: 400,
+ minSize: 100,
+ maxSize: 400,
collapsible: true,
}}
/>,
@@ -228,8 +228,8 @@ describe('ResizeHandle', () => {
<Harness
config={{
defaultSize: 200,
- minSizePx: 100,
- maxSizePx: 400,
+ minSize: 100,
+ maxSize: 400,
collapsible: true,
}}
/>,
@@ -467,8 +467,8 @@ describe('ResizeHandle', () => {
<Harness
config={{
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.mjs
index 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.ts
index 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/% only
const rem: UseResizableSingleConfig = {minSize: '10rem'};
const cssMath: UseResizableSingleConfig = {
// @ts-expect-error CSS functions are not part of ResizableSize
minSize: '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 minSize
minSizePx: 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 maxSize
maxSizePx: 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.ts
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
index 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.mjs
index 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.tsx
index 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.ts
index 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.mjs
index 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.tsx
index 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 inline
diff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.ts
index 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,