Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Resizable): a pull past a limit rubber-bands and only the lift closes (#10292)

Christopher Chedeau916a8e2fa7e4
diff --git a/.changeset/layout-panel-slides-on-collapse.md b/.changeset/layout-panel-slides-on-collapse.md
index 33cb88601f..a4eb55d409 100644
--- a/.changeset/layout-panel-slides-on-collapse.md
+++ b/.changeset/layout-panel-slides-on-collapse.md
@@ -2,6 +2,6 @@
'@astryxdesign/core': patch
---
-[feat] A `LayoutPanel` that takes a `useResizable` region in its `resizable` prop slides closed and open from the edge facing its `ResizeHandle` when the region collapses or opens, under every pointer, with the content beside it moving on the same motion: through `collapse()`, `expand()`, Enter, a double-click, the grow arrow, a controlled `isCollapsed`, or a drag past the collapse threshold. A drag that reopens the panel follows the pointer, and Reduce Motion is honored. A hand-built `ResizableProps` object does not slide. No prop or option is added.
+[feat] A `LayoutPanel` that takes a `useResizable` region in its `resizable` prop slides closed and open from the edge facing its `ResizeHandle` when the region collapses or opens, under every pointer, with the content beside it moving on the same motion: through `collapse()`, `expand()`, Enter, a double-click, the grow arrow, a controlled `isCollapsed`, or a lift past the collapse threshold. A drag that reopens the panel follows the pointer, and Reduce Motion is honored. A hand-built `ResizableProps` object does not slide. No prop or option is added.
@vjeux
diff --git a/.changeset/resizable-limits-rubber-band.md b/.changeset/resizable-limits-rubber-band.md
new file mode 100644
index 0000000000..9761c58d5c
--- /dev/null
+++ b/.changeset/resizable-limits-rubber-band.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] A `ResizeHandle` that any pointer pulls past the maximum, or under the minimum, of a region whose pane a `LayoutPanel` renders now moves the handle with resistance, at most about 8 px past the limit and over the content beside it, while the panes keep their sizes, and the handle springs back to the limit after the lift. A panel sized by the region's `size` alone stops at the limit. A collapsible region no longer collapses mid-drag: only the lift collapses it, when the pointer is past `collapsedSize`, or released fast enough to come to rest past it, and a `LayoutPanel`'s pane slides shut on a spring from the release velocity. Any other lift under the minimum returns to the minimum. A pointer that grabs the handle again catches it where it shows. Arrow keys still stop at the limit. Reduce Motion lands both at once.
+
+@vjeux
diff --git a/apps/storybook/stories/Resizable.stories.tsx b/apps/storybook/stories/Resizable.stories.tsx
index a907a2b5a5..f9eedc8358 100644
--- a/apps/storybook/stories/Resizable.stories.tsx
+++ b/apps/storybook/stories/Resizable.stories.tsx
@@ -851,13 +851,15 @@ export const CollapsingScrollPanelFixture: Story = {
function SlidingPanelSplit({
side,
lineCount = 0,
+ minSize = 120,
}: {
side: 'start' | 'end';
lineCount?: number;
+ minSize?: number;
}) {
const resizable = useResizable({
defaultSize: 200,
- minSize: 120,
+ minSize,
maxSize: 320,
collapsible: true,
});
@@ -933,6 +935,15 @@ export const SlidingScrolledPanelFixture: Story = {
render: () => <SlidingPanelSplit side="start" lineCount={40} />,
};
+/**
+ * A sliding start panel at the hook's default minimum (50 px), so a key step
+ * from it ends under the collapsed size.
+ */
+export const SlidingPanelAtDefaultMinimumFixture: Story = {
+ tags: ['!autodocs', 'no-visual'],
+ render: () => <SlidingPanelSplit side="start" minSize={50} />,
+};
+
/**
* A start LayoutPanel whose collapse state its parent owns: `isCollapsed`
* with `onCollapseChange`, and a toggle that flips the parent's state. The
diff --git a/docs/specs/AST-094-touch-presentations/motion-roles.md b/docs/specs/AST-094-touch-presentations/motion-roles.md
index 656bc09318..fa5f0477ac 100644
--- a/docs/specs/AST-094-touch-presentations/motion-roles.md
+++ b/docs/specs/AST-094-touch-presentations/motion-roles.md
@@ -2,7 +2,7 @@
# Motion roles
-The owner's goal: "The main goals are consistent timings and well-coordinated pieces." The rules serve it: springs for a component whose main interaction is a gesture, including the moves a tap starts inside it; curve tokens for a component whose main interaction is a tap, tap-to-expand included; the nearest-token mapping for a measured duration; one coordinated scale for springs and curves through `tempo`, each spring paired with a timing tier (`spec:AST-094` FR45); and no per-component exceptions and no platform-native option. The owner's guidance: "The guidance im thinking is: timing should be coordinated between spring and motion curve tokens, then use spring for gestures where velocity matters, use motion curves for taps presses and other non gesture motion." A component whose main interaction is a gesture plays springs for its motion, including moves a tap starts inside it (a tap on a sheet detent or a close button settles on the same spring), so its pieces stay coordinated. A component whose main interaction is a tap plays the theme's curve tokens (duration and easing, scaled by `tempo`), never a spring, since a tap carries no velocity; no character or option plays a platform-measured curve for it (owner decision, 2026-11-04). `spec:AST-094` FR45 lists which components each covers. Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. In a component whose main interaction is a tap, a role plays only for motion a gesture drives; in a gesture component, its roles also settle the moves a tap, a key or the program starts (`spec:AST-094` FR45). In a component whose main interaction is a tap, motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Two approved motions keep their springs until their own records change: the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are tap-started layout motion and play the theme's curve tokens (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.
+The owner's goal: "The main goals are consistent timings and well-coordinated pieces." The rules serve it: springs for a component whose main interaction is a gesture, including the moves a tap starts inside it; curve tokens for a component whose main interaction is a tap, tap-to-expand included; the nearest-token mapping for a measured duration; one coordinated scale for springs and curves through `tempo`, each spring paired with a timing tier (`spec:AST-094` FR45); and no per-component exceptions and no platform-native option. The owner's guidance: "The guidance im thinking is: timing should be coordinated between spring and motion curve tokens, then use spring for gestures where velocity matters, use motion curves for taps presses and other non gesture motion." A component whose main interaction is a gesture plays springs for its motion, including moves a tap starts inside it (a tap on a sheet detent or a close button settles on the same spring), so its pieces stay coordinated. A component whose main interaction is a tap plays the theme's curve tokens (duration and easing, scaled by `tempo`), never a spring, since a tap carries no velocity; no character or option plays a platform-measured curve for it (owner decision, 2026-11-04). `spec:AST-094` FR45 lists which components each covers. Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. In a component whose main interaction is a tap, a role plays only for motion a gesture drives; in a gesture component, its roles also settle the moves a tap, a key or the program starts (`spec:AST-094` FR45). In a component whose main interaction is a tap, motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Two approved motions keep their springs until their own records change: the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are tap-started layout motion and play the theme's curve tokens, except a gesture's release, which settles on its spring (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.
| Role | Kind | Default | Named by |
| ------------------------------- | -------- | --------------------------------------------------------------- | ----------------------- |
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index 068161c04f..219175b686 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -223,8 +223,9 @@ a measured, sourced difference exists.
(FR7). Two approved motions keep their springs until their own records change:
the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s
`settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are
- tap-started layout motion and play the theme's curve tokens (`spec:AST-105`
- FR4). Reduce Motion substitutions and continuous busy loops (such as
+ tap-started layout motion and play the theme's curve tokens, except a
+ gesture's release, which settles on its spring (`spec:AST-105` FR4). Reduce
+ Motion substitutions and continuous busy loops (such as
ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their
named roles; they are neither gesture- nor interaction-started motion. A
component's own record states which of its roles a gesture drives.
@@ -334,8 +335,9 @@ a measured, sourced difference exists.
pointer, a finger included. Two approved motions keep their springs until
their own records change: the animator's `animate` (`spec:AST-107` FR3) and
`useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and
- edge reveal are tap-started layout motion and play the theme's curve tokens
- (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops
+ edge reveal are tap-started layout motion and play the theme's curve tokens,
+ except a gesture's release, which settles on its spring (`spec:AST-105` FR4).
+ Reduce Motion substitutions and continuous busy loops
(such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep
their named roles; they are neither gesture- nor interaction-started motion. A
tap has no velocity, so it is not a gesture. Springs drive the motion of a
diff --git a/docs/specs/AST-105-animated-layout/spec.md b/docs/specs/AST-105-animated-layout/spec.md
index 2264e88c57..71c825efa9 100644
--- a/docs/specs/AST-105-animated-layout/spec.md
+++ b/docs/specs/AST-105-animated-layout/spec.md
@@ -95,8 +95,10 @@ const animatedLayout = useAnimatedLayout({containerRef: scrollRef});
`--ease-move`, over `--duration-medium`, which follow the theme's
`character` and `tempo` (`spec:AST-108` FR1, FR2). The glide is curve
tokens, never a spring, and no character or option plays a
- platform-measured curve for it (`spec:AST-094` FR45). Both start on the same
- frame, and Reduce Motion reaches both, as `design:reduced-motion` DR1–DR3
+ platform-measured curve for it (`spec:AST-094` FR45). A gesture's release
+ settles on `spec:AST-094`'s spring from its release velocity; curve tokens
+ govern glides that no gesture releases. Both start on the same frame, and
+ Reduce Motion reaches both, as `design:reduced-motion` DR1–DR3
require: a cross-fade under a coarse primary pointer, an immediate change
otherwise.
- **FR5 — Every pointer.** The glide applies under every pointer, a mouse
@@ -157,11 +159,12 @@ const animatedLayout = useAnimatedLayout({containerRef: scrollRef});
- A resizable pane that a LayoutPanel renders conceals and reveals by the edge
facing its ResizeHandle each time it collapses or opens, and LayoutContent
beside it moves on the same motion (`component:Resizable` FR8,
- `component:LayoutPanel` FR7). A drag that crosses the collapse threshold plays
- the conceal; a drag that reopens a collapsed pane plays nothing, because the
- pointer drives the edge. A pane the caller renders at `useResizable`'s size
- alone shows no reveal, because Core never holds that element, and so does
- a LayoutPanel given the configuration-object form, a hand-built
+ `component:LayoutPanel` FR7). Only a lift closes the pane, and its conceal
+ settles from the lift's release velocity (FR4); a drag that reopens a
+ collapsed pane plays nothing, because the pointer drives the edge. A pane
+ the caller renders at `useResizable`'s size alone shows no reveal,
+ because Core never holds that element, and so does a LayoutPanel given
+ the configuration-object form, a hand-built
`ResizableProps` object that `useResizable` did not return; the hook's own
`props` passed through `resizable` slide.
@@ -242,10 +245,10 @@ Out of coverage, each taking its final place at once:
| ------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FR1, FR2 | Unit and browser tests with and without a handle | a handle on TreeList; no handle; a ScrollableArea ref | a handle with public members, behavior that changes without a handle, or ScrollableArea registering itself fails |
| FR3, Coverage | Real-browser tests, one per Coverage row | each Coverage row; mixed Astryx and plain content; two changes in one frame; an area scrolled mid-list | an element that behaves other than its row says, an element moved twice for one frame, content past the area that moves, or the area scrolling fails |
-| FR4 | Real-browser frame capture under a coarse and a fine pointer, with and without Reduce Motion | a changed element and its visible followers at each `character`, and at `tempo` 0.75 and 1.5 | starting on different frames or reading different motion, a component-specific timing, a glide that ignores the theme's `character` or `tempo`, a spring or a platform-measured curve played for the glide, or Reduce Motion applied to one and not the other fails |
+| FR4 | Real-browser frame capture under a coarse and a fine pointer, with and without Reduce Motion | a changed element and its visible followers at each `character`, and at `tempo` 0.75 and 1.5; a lift that closes a LayoutPanel, from its release velocity | starting on different frames or reading different motion, a component's own timing, a glide that ignores the theme's `character` or `tempo`, a spring or a measured curve for a glide no gesture releases, or Reduce Motion applied to one and not the other, fails |
| FR5 | Fine-pointer before-and-after evidence on each adopting pull request, from the component's Storybook story | a mouse on each adopting component | a glide missing under a mouse, or an adopting pull request without that evidence, fails |
| FR8 | Unit tests of the swap and real-browser proofs of its adopters | a fast load, a slow load, a forward and a back page change, Reduce Motion | an empty area during a swap, a placeholder flashed for a fast load, travel under Reduce Motion, a layer exit played by it, or a public export fails |
-| FR9 | Unit tests of the reveal's measurement and real-browser frame capture of each adopter | Collapsible opening; the SideNav rail collapsing and expanding; a start and an end LayoutPanel collapsing and opening by toggle, Enter, the grow arrow, a controlled change and a drag past the threshold; a drag reopening a pane; a hook-only pane; focus inside a collapsing pane; Reduce Motion | a gap opening beside a moving edge, two motions for one rail collapse, a reveal during a drag that reopens a pane, a reveal on a hook-only pane, focus left inside a concealed pane, a concealed pane reachable by Tab, or a public export fails |
+| FR9 | Unit tests of the reveal's measurement and real-browser frame capture of each adopter | Collapsible opening; the SideNav rail collapsing and expanding; a start and an end LayoutPanel collapsing and opening by toggle, Enter, the grow arrow, a controlled change and a lift past the threshold; a drag reopening a pane; a hook-only pane; focus inside a collapsing pane; Reduce Motion | a gap opening beside a moving edge, two motions for one rail collapse, a reveal during a drag that reopens a pane, a reveal on a hook-only pane, focus left inside a concealed pane, a concealed pane reachable by Tab, or a public export fails |
## Decision log
@@ -274,7 +277,9 @@ A glide is a move like any other, so it takes the theme's move curve and
duration, and a theme that sets `character` or `tempo` sees its glides change
with the rest of its motion, under every pointer. A tap that expands or
collapses content carries no velocity, so the glide that follows plays curve
-tokens, never a spring (`spec:AST-094` FR45).
+tokens, never a spring (`spec:AST-094` FR45). A gesture's release settles on
+`spec:AST-094`'s spring from its release velocity; curve tokens govern glides
+that no gesture releases.
Rejected: the measured spring as the glide; a platform-measured opt-in, such as a separate character.
diff --git a/docs/specs/components/Resizable/Resizable.spec.md b/docs/specs/components/Resizable/Resizable.spec.md
index 45b81c6feb..d42fecf591 100644
--- a/docs/specs/components/Resizable/Resizable.spec.md
+++ b/docs/specs/components/Resizable/Resizable.spec.md
@@ -126,30 +126,30 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ---------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- | --------------------- | --------- | ------------------------------------------------------------------------- |
-| Size value | pixel number; exact `Npx`; exact `N%`; `pixel()`; `percent(value, {min} or {max})` | A size or bound in pixels or a percentage of the container, or of the viewport without a `containerRef`. | `defaultSize`, `minSize`, `maxSize` | `defaultSize` 250, `minSize` 50, `maxSize` unbounded | `component:Resizable` | Stable | Invalid strings and descriptors fail runtime validation (`spec:AST-010`). |
-| Collapse | collapsible; collapsed; expanded | A collapsible region collapses to 0 when a drag goes below `collapsedSize`, and restores its previous size. | `collapsible` | not collapsible; `collapsedSize` 40 (drag threshold) | `component:Resizable` | Stable | — |
-| Snaps | pixel list | The only positions the region rests on, for drag, keyboard, and `resize()`. | Optional | none | `component:Resizable` | Stable | — |
-| Persistence | `autoSaveId` | Remembers the pixel size across sessions. | Optional | none | `component:Resizable` | Stable | — |
-| Axis | `horizontal`; `vertical` | The axis the region resizes along. | Handle and hook | `horizontal` | `component:Resizable` | Stable | Closed union. |
-| Handle placement | `position` `inline`, `overlay`; `isReversed`; `pillPlacement` `auto`, `start`, `center`, `end` | Whether the Handle takes layout space or overlays its parent; which side grows; where the pill sits. | Handle | `inline`; not reversed; `auto` | `component:Resizable` | Stable | Closed union. |
-| Handle state | enabled; disabled; divider; always-visible pill | Interaction and paint options. | Handle | enabled; no divider; pill visible | `component:Resizable` | Stable | — |
-| Grip content | caller `children` | Replaces the Grip pill. | Handle | Grip pill | caller | Stable | — |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- | --------------------- | --------- | ------------------------------------------------------------------------- |
+| Size value | pixel number; exact `Npx`; exact `N%`; `pixel()`; `percent(value, {min} or {max})` | A size or bound in pixels or a percentage of the container, or of the viewport without a `containerRef`. | `defaultSize`, `minSize`, `maxSize` | `defaultSize` 250, `minSize` 50, `maxSize` unbounded | `component:Resizable` | Stable | Invalid strings and descriptors fail runtime validation (`spec:AST-010`). |
+| Collapse | collapsible; collapsed; expanded | A collapsible region collapses to 0 when a drag's lift is below `collapsedSize`, or flicked to rest below it, and restores its previous size. | `collapsible` | not collapsible; `collapsedSize` 40 (drag threshold) | `component:Resizable` | Stable | — |
+| Snaps | pixel list | The only positions the region rests on, for drag, keyboard, and `resize()`. | Optional | none | `component:Resizable` | Stable | — |
+| Persistence | `autoSaveId` | Remembers the pixel size across sessions. | Optional | none | `component:Resizable` | Stable | — |
+| Axis | `horizontal`; `vertical` | The axis the region resizes along. | Handle and hook | `horizontal` | `component:Resizable` | Stable | Closed union. |
+| Handle placement | `position` `inline`, `overlay`; `isReversed`; `pillPlacement` `auto`, `start`, `center`, `end` | Whether the Handle takes layout space or overlays its parent; which side grows; where the pill sits. | Handle | `inline`; not reversed; `auto` | `component:Resizable` | Stable | Closed union. |
+| Handle state | enabled; disabled; divider; always-visible pill | Interaction and paint options. | Handle | enabled; no divider; pill visible | `component:Resizable` | Stable | — |
+| Grip content | caller `children` | Replaces the Grip pill. | Handle | Grip pill | caller | Stable | — |
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone (a `--spacing-4` strip on the resize axis); the default render also contains a Grip pill, and caller `children` replace the pill. The grab zone is centred on the Handle for every `pillPlacement`, and the painted pill is its own grab target. On a pane too short for the full strip, the zone shrinks so the pane keeps at least half of itself. A pill shown only on hover also takes the pointer across the gap between it and the Grab zone, never past the pill's far side. | Current source, docs, tests, and an owner ruling |
-| FR2 | The Handle carries `resize-handle`, the Grip pill carries `resize-handle-pill`, and the Grab zone carries no public target. | Current source and docs |
-| FR3 | Pointer drag, keyboard, double-click collapse, snapping, persistence, reversal, and size behavior are owned by ResizeHandle and useResizable; dragging under right-to-left inverts the pointer delta so the divider follows the pointer. A disabled Handle ignores pointer and keyboard input and exposes `aria-disabled`, and keeps its tab stop (`spec:AST-085` FR1). With `autoSaveId`, storage holds the last settled size and receives the final size once when a drag ends, cancels, or unmounts. | Current source, docs, and tests |
-| FR4 | The Handle reflects the documented `direction` visual state on its target (`architecture:component-theming-surface` INV6). Implementation gap: it reflects no `direction` (Current-state impact). | Current source and docs |
-| FR5 | A `percent(value, {min: pixel(value)})` or `percent(value, {max: pixel(value)})` resolves against one basis — the supplied container, or the viewport when no `containerRef` is given (`spec:AST-010` FR1, FR2); as a default it selects pixels once, and as a bound it stays live and clamps the selected pixels. A descriptor with both or neither bound is invalid. Selected state, persistence, callbacks, paint, and ARIA are pixels. | `spec:AST-010`; current source and tests |
-| FR6 | `minSize` and `maxSize` are the bound props; numeric values are pixels. When resolved bounds conflict, the maximum wins. | `spec:AST-010`; current source and tests |
-| FR7 | `ref`, DOM, data, ARIA, and event props reach the Handle, and a caller's explicit `role`, ARIA attribute, or `tabIndex` reaches it as given; a caller `onKeyDown` runs before the Handle's own key handling; caller `onFocus`, `onBlur`, and `onDoubleClick` compose with the Handle's own focus tracking and double-click collapse (`architecture:public-component-api` INV5, INV7); `xstyle` and `className` compose after component styles, and `style` is not accepted. Implementation gap: caller `onFocus`, `onBlur`, and `onDoubleClick` replace the Handle's own handlers (Current-state impact). | Current source; `architecture:public-component-api` INV5–INV8 |
-| FR8 | When a region collapses or opens, its pane slides by `spec:AST-105` FR9's edge reveal when a LayoutPanel renders it (`component:LayoutPanel` FR7): the resize controller measures the pane's box before and after the collapse state commits, before its subscribers hear of it, and the pane's edge facing its ResizeHandle, read from the region's direction and reversal, moves with the content on that edge's side on one motion. Every collapse and open plays it: `collapse()`, `expand()`, a resize out of collapse, Enter, a double-click, the grow arrow, a controlled `isCollapsed` change, and a drag that crosses `collapsedSize` to collapse. A drag that reopens a collapsed pane plays nothing, because the pointer drives the edge; a resize that neither collapses nor opens, and the first render, play nothing. A pane the caller renders at the hook's size alone, and a LayoutPanel given the configuration-object form, a hand-built `ResizableProps` object that `useResizable` did not return passed through its `resizable`, show no slide; the hook's own `props` passed through `resizable` do slide. No prop, option or return member is added; size, `isCollapsed`, callbacks, persistence and the Handle's ARIA values are unchanged. Focus inside a collapsing pane follows `component:LayoutPanel` AR2. A ResizeHandle given the props holds a panel at the hook's size collapsed. | `spec:AST-105` FR9; `component:LayoutPanel` FR7, AR2 |
-| FR9 | `resizable` takes useResizable's output directly; the region's `props` is still accepted (owner decision, 2026-11-04). Components take the hook's value through the `resizable` slot prop (owner decision, 2026-11-04): LayoutPanel (`component:LayoutPanel` FR8), ResizeHandle, and SideNav (`component:SideNav` FR7). Any other element can use the hook's `size`. | `architecture:public-component-api` INV21, INV22 |
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone (a `--spacing-4` strip on the resize axis); the default render also contains a Grip pill, and caller `children` replace the pill. The grab zone is centred on the Handle for every `pillPlacement`, and the painted pill is its own grab target. On a pane too short for the full strip, the zone shrinks so the pane keeps at least half of itself. A pill shown only on hover also takes the pointer across the gap between it and the Grab zone, never past the pill's far side. | Current source, docs, tests, and an owner ruling |
+| FR2 | The Handle carries `resize-handle`, the Grip pill carries `resize-handle-pill`, and the Grab zone carries no public target. | Current source and docs |
+| FR3 | Pointer drag, keyboard, double-click collapse, snapping, persistence, reversal, and size behavior are owned by ResizeHandle and useResizable; dragging under right-to-left inverts the pointer delta so the divider follows the pointer. A disabled Handle ignores pointer and keyboard input and exposes `aria-disabled`, and keeps its tab stop (`spec:AST-085` FR1). With `autoSaveId`, storage holds the last settled size and receives the final size once when a drag ends, cancels, or unmounts. | Current source, docs, and tests |
+| FR4 | The Handle reflects the documented `direction` visual state on its target (`architecture:component-theming-surface` INV6). Implementation gap: it reflects no `direction` (Current-state impact). | Current source and docs |
+| FR5 | A `percent(value, {min: pixel(value)})` or `percent(value, {max: pixel(value)})` resolves against one basis — the supplied container, or the viewport when no `containerRef` is given (`spec:AST-010` FR1, FR2); as a default it selects pixels once, and as a bound it stays live and clamps the selected pixels. A descriptor with both or neither bound is invalid. Selected state, persistence, callbacks, paint, and ARIA are pixels. | `spec:AST-010`; current source and tests |
+| FR6 | `minSize` and `maxSize` are the bound props; numeric values are pixels. When resolved bounds conflict, the maximum wins. | `spec:AST-010`; current source and tests |
+| FR7 | `ref`, DOM, data, ARIA, and event props reach the Handle, and a caller's explicit `role`, ARIA attribute, or `tabIndex` reaches it as given; a caller `onKeyDown` runs before the Handle's own key handling; caller `onFocus`, `onBlur`, and `onDoubleClick` compose with the Handle's own focus tracking and double-click collapse (`architecture:public-component-api` INV5, INV7); `xstyle` and `className` compose after component styles, and `style` is not accepted. Implementation gap: caller `onFocus`, `onBlur`, and `onDoubleClick` replace the Handle's own handlers (Current-state impact). | Current source; `architecture:public-component-api` INV5–INV8 |
+| FR8 | When a region collapses or opens, its pane slides by `spec:AST-105` FR9's edge reveal when a LayoutPanel renders it (`component:LayoutPanel` FR7): the resize controller measures the pane's box before and after the collapse state commits, before its subscribers hear of it, and the pane's edge facing its ResizeHandle, read from the region's direction and reversal, moves with the content on that edge's side on one motion. Every collapse and open plays it: `collapse()`, `expand()`, a resize out of collapse, Enter, a double-click, the grow arrow, a controlled `isCollapsed` change, and a lift that closes the pane. A drag that reopens a collapsed pane plays nothing, because the pointer drives the edge; a resize that neither collapses nor opens, and the first render, play nothing. A pane the caller renders at the hook's size alone, and a LayoutPanel given the configuration-object form, a hand-built `ResizableProps` object that `useResizable` did not return passed through its `resizable`, show no slide; the hook's own `props` passed through `resizable` do slide. No prop, option or return member is added. The reported size, persistence and the Handle's ARIA values keep to the limits. Focus inside a collapsing pane follows `component:LayoutPanel` AR2. A ResizeHandle given the props holds a panel at the hook's size collapsed. When a LayoutPanel renders the pane, a pointer pulled past the maximum, or under the minimum, moves the Handle past the limit. Core's shared rubber band keeps that travel to about 8 px (`spec:AST-094` FR5). The rubber band's extra length does not change the panes' widths; it extends the handle and overlaps the content a little. (Owner direction, Nov 6 2026 (Cindy): "the extra length of the rubber band should ideally not affect the widths of the content but be kind of treated as just extending the handle and overlapping a bit".) After the lift the Handle springs back to the limit on `springs.settle` from the release velocity. The rubber band is a drag's give for every pointer: mouse, trackpad, pen and finger. An arrow key at a limit does not band. A pane rendered at the hook's size alone stops at the limit (`spec:AST-094` FR5). A drag never collapses the pane mid-way: only its lift closes the pane, when the pointer, or the rest its release velocity projects, is past `collapsedSize`, and that close slides on `springs.settle` from the release velocity. Any other lift under the minimum returns to the minimum. A press on the Handle where it shows mid-slide takes the Handle where it shows. During a spring-back the Handle follows the pointer 1:1 back toward the limit and over the overshoot it held, then resists again. During a close the pane opens at the size it shows. Between snap points, the edge then follows the pointer to the next snap point; a lift before that lands on the nearest one. | `spec:AST-105` FR9; `component:LayoutPanel` FR7, AR2; Owner direction, Nov 5 2026 (Cindy): rubber band at the limits on both sides, so hitting a limit doesn't read as a bug; Owner direction, Nov 6 2026 (Cindy): rubber-band travel for a panel resize is at most about 8 px; the panel closes only on release; Specs decision, Nov 5 2026: snap-to-close decided on lift, with resistance below the minimum (the iPadOS Split View model); Specs decision, Nov 6 2026: the band is a drag's give for every pointer, and an arrow key at a limit does not band |
+| FR9 | `resizable` takes useResizable's output directly; the region's `props` is still accepted (owner decision, 2026-11-04). Components take the hook's value through the `resizable` slot prop (owner decision, 2026-11-04): LayoutPanel (`component:LayoutPanel` FR8), ResizeHandle, and SideNav (`component:SideNav` FR7). Any other element can use the hook's `size`. | `architecture:public-component-api` INV21, INV22 |
### Allowed variation
@@ -265,21 +265,21 @@ Consumer migration instructions belong in consumer docs and release notes.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
-| FR1 | `ResizeHandle.test.tsx`; `grabZone.interaction.browser.spec.ts` for the zone's place and its short-pane limit; stable visual baseline `core-resizable--horizontal-split` | Default, collapsed, both axes | Handle and Grab zone regressions fail focused tests; a changed default handle comes back changed for review. Gap: no test renders `children` to prove they replace the Grip pill. | `audit:Resizable/anatomy` |
-| FR2 | `themingTargets.test.ts`; source review | Handle, Grip pill, Grab zone | A removed target fails the inventory. `themingTargets.test.ts` catches only a renamed or undocumented target; no check fails if the Handle or Grip pill stops carrying its target. | `audit:Resizable/theming` |
-| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts`; storage timing: `ResizeHandle.test.tsx` ("saves the size once, when a drag ends on …", "saves the dragged size once when the split unmounts mid-drag", "still saves each keyboard step at once") and `useResizable.test.ts` ("writes the size a drag reached once, after … releases it", "writes the final size once when the release comes before the last move renders", "keeps the size a region was dragged to when it unmounts mid-drag", "writes only the re-clamped size when the container shrank mid-drag") | Pointer, keyboard, snap, collapse, persistence; RTL drag; disabled keyboard | A changed transformation, an RTL drag that moves against the pointer, keyboard input that resizes a disabled Handle, or a per-move, stale or missing final storage write fails. Gap: no test covers disabled pointer input. | `audit:Resizable/behavior` |
-| FR4 | Source and docs comparison | Horizontal and vertical Handle | Gap: no test detects that the documented `direction` is not reflected. | `audit:Resizable/theming` |
-| FR5, ORD1–ORD3 | `useResizable.test.ts`, `utils.test.ts`, typecheck | Floor, ceiling, default; invalid shapes; basis changes; numeric container parity | Wrong resolution, a rescaled default, a stale clamp, an observer leak, or state, paint, storage, and ARIA that disagree fails. | `audit:Resizable/behavior` |
-| FR6 | `useResizable.test.ts`; typecheck | Numeric bounds; conflicting bounds | A removed alias that type-checks, a numeric bound that is not pixels, or a minimum that wins a conflict fails. | `audit:Resizable/behavior` |
-| FR7 | `ResizeHandle.test.tsx` consumer `onKeyDown` test; source review | Caller props and `onKeyDown` | A consumer `onKeyDown` that stops keyboard resizing, or keyboard resizing that skips the consumer handler, fails. Gap: no test covers other caller props, the styling merge, caller `onFocus`, `onBlur`, or `onDoubleClick`, or a caller `role` or ARIA attribute. | `audit:Resizable/api` |
-| FR8 | `paneSlide.interaction.browser.spec.ts`: a start and an end LayoutPanel collapsed from inside and opened with Enter, a toggle, a controlled `isCollapsed`, a double-click, the grow arrow, a drag past the threshold, a reopening drag, a hand-built `ResizableProps` pane, and Reduce Motion; `paneReveal.test.tsx` for `expand()`, `resize()` out of collapse, and a hook-only pane | Start and end panes; `collapse()`, `expand()`, Enter, double-click, the grow arrow, a controlled `isCollapsed` change, a drag across `collapsedSize`; a reopening drag; the hook's `props` and a hand-built object through `resizable`; Reduce Motion | A jump instead of a slide, a slide from the wrong edge, a slide during a reopening drag or on first render, a slide for a hook-only pane or a hand-built object, no slide for the hook's `props`, or a new prop, option or return member fails. | `audit:Resizable/behavior` |
-| AR1 | `ResizeHandle.test.tsx` ("makes the separator focusable", "exposes the region size and bounds via ARIA", "grows the panel by a step on ArrowRight", "shrinks the panel by a step on ArrowLeft", "uses the large step when Shift is held", "jumps to the minimum on Home", "jumps to the maximum on End", "collapses on Enter when the region is collapsible", "inverts the pointer delta under RTL so dragging resizes intuitively", "restores the previous size, not the minimum, when Enter reopens a collapsed pane", "reopens on Enter even when the minimum size sits below the collapse threshold", "reports the window basis as aria-valuemax when no maximum is configured; End leaves an unbounded region alone", "reports the container basis as aria-valuemax while a percentage bound already observes it", "never reports aria-valuemax below aria-valuemin while collapsed in a small window", "reports no aria-valuemax for an unbounded pixel-only region in a container, which stays unobserved", "a grow arrow opens a collapsed pane one step above its minimum; the shrink arrow leaves it collapsed", "a grow arrow opens a collapsed pane at its collapsedSize when the minimum sits below it", "a grow arrow opens a collapsed pane in the reversed layout and under RTL too", "in a reversed layout, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "under RTL, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "a grow arrow opens a hand-built collapsed region one step above its minimum", "with snap points, an arrow moves to the adjacent point in its direction and Shift moves two, clamped to the ends", "with snap points past the bounds, a point beyond maxSize or minSize counts as that bound", "with snap points, the arrows follow the reversed layout and the reading direction", "with snap points in a reversed layout, ArrowLeft moves to the next point and ArrowRight to the previous", "with snap points, the grow arrow opens a collapsed pane at the snap point nearest one step above its minimum") and `shippedDirections.test.ts`; `SideNav.test.tsx` ("names the nav it resizes with aria-controls (APG window splitter)"); RTL keyboard mirroring, and the disabled state under the Window Splitter accessibility contract (`internal/a11y-spec`, pending); `ResizeHandle.a11y.test.tsx` and `ResizeHandle.a11y.chromium.spec.ts` | Inline and block axes; LTR and RTL; collapsed; disabled | The Handle loses its role, name, orientation, or value properties; an arrow, Home, End, or Enter stops moving the divider or moves it against the reading direction. | `audit:Resizable/accessibility` |
-| PR1 | `useResizable.test.ts` observer tests | Pixel, percentage default, percentage bound | An observer on a pixel-only path, or one that outlives a final default, fails. | `audit:Resizable/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two targets | Missing, extra, or stale mappings fail repository validation. | `audit:Resizable/theming` |
-| RTL relation (ResizeHandle) | RTL audit curated D4 target (`apps/storybook/rtl-audit/targets.json`) on the `Horizontal split` story, beside the Resizable target | Horizontal split; LTR and RTL | A handle that does not move to the mirrored side of the layout in RTL fails D4. | `audit:Resizable/i18n-rtl` |
-| FR9 | `resizableSlot.test.tsx`: a LayoutPanel and its ResizeHandle given the region, and given its `props` | The region; its `props` | A panel that ignores the region's size, a handle that does not drive it, or a collapse that leaves the panel reachable fails | `audit:Resizable/api` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1 | `ResizeHandle.test.tsx`; `grabZone.interaction.browser.spec.ts` for the zone's place and its short-pane limit; stable visual baseline `core-resizable--horizontal-split` | Default, collapsed, both axes | Handle and Grab zone regressions fail focused tests; a changed default handle comes back changed for review. Gap: no test renders `children` to prove they replace the Grip pill. | `audit:Resizable/anatomy` |
+| FR2 | `themingTargets.test.ts`; source review | Handle, Grip pill, Grab zone | A removed target fails the inventory. `themingTargets.test.ts` catches only a renamed or undocumented target; no check fails if the Handle or Grip pill stops carrying its target. | `audit:Resizable/theming` |
+| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts`; storage timing: `ResizeHandle.test.tsx` ("saves the size once, when a drag ends on …", "saves the dragged size once when the split unmounts mid-drag", "still saves each keyboard step at once") and `useResizable.test.ts` ("writes the size a drag reached once, after … releases it", "writes the final size once when the release comes before the last move renders", "keeps the size a region was dragged to when it unmounts mid-drag", "writes only the re-clamped size when the container shrank mid-drag") | Pointer, keyboard, snap, collapse, persistence; RTL drag; disabled keyboard | A changed transformation, an RTL drag that moves against the pointer, keyboard input that resizes a disabled Handle, or a per-move, stale or missing final storage write fails. Gap: no test covers disabled pointer input. | `audit:Resizable/behavior` |
+| FR4 | Source and docs comparison | Horizontal and vertical Handle | Gap: no test detects that the documented `direction` is not reflected. | `audit:Resizable/theming` |
+| FR5, ORD1–ORD3 | `useResizable.test.ts`, `utils.test.ts`, typecheck | Floor, ceiling, default; invalid shapes; basis changes; numeric container parity | Wrong resolution, a rescaled default, a stale clamp, an observer leak, or state, paint, storage, and ARIA that disagree fails. | `audit:Resizable/behavior` |
+| FR6 | `useResizable.test.ts`; typecheck | Numeric bounds; conflicting bounds | A removed alias that type-checks, a numeric bound that is not pixels, or a minimum that wins a conflict fails. | `audit:Resizable/behavior` |
+| FR7 | `ResizeHandle.test.tsx` consumer `onKeyDown` test; source review | Caller props and `onKeyDown` | A consumer `onKeyDown` that stops keyboard resizing, or keyboard resizing that skips the consumer handler, fails. Gap: no test covers other caller props, the styling merge, caller `onFocus`, `onBlur`, or `onDoubleClick`, or a caller `role` or ARIA attribute. | `audit:Resizable/api` |
+| FR8 | `paneSlide.interaction.browser.spec.ts`: a start and an end LayoutPanel collapsed from inside and opened with Enter, a toggle, a controlled `isCollapsed`, a double-click, the grow arrow, a lift past the threshold, a flick toward closing, a pull past the maximum and under the minimum, each at most about 8 px with no reflow, the Handle alone moving over the content, an arrow key at the maximum that draws no band, a panel at the hook's size alone at a limit, a press on the Handle mid-slide, a re-grab at once, 50 ms after and mid-settle after a pull past the maximum, a reopening drag, a hand-built `ResizableProps` pane, and Reduce Motion; `paneReveal.test.tsx` for `expand()`, `resize()` out of collapse, a re-grab while the pane slides shut, and a hook-only pane; source review: the resize gesture takes every pointer type alike | Start and end panes; `collapse()`, `expand()`, Enter, double-click, the grow arrow, a controlled `isCollapsed` change, a lift past `collapsedSize` and a flick; a pull past each limit and its spring-back, for every pointer type; an arrow key at a limit; a press mid-slide; a reopening drag; the hook's `props` and a hand-built object through `resizable`; Reduce Motion | A jump instead of a slide, a slide from the wrong edge, a hard stop at a limit, an edge more than about 8 px past a limit, content that reflows past a limit, a band from an arrow key at a limit, a collapse before the lift, a close not on `springs.settle`, a press mid-slide that misses the Handle, a slide during a reopening drag or on first render, a slide for a hook-only pane or a hand-built object, no slide for the hook's `props`, or a new prop, option or return member fails. | `audit:Resizable/behavior` |
+| AR1 | `ResizeHandle.test.tsx` ("makes the separator focusable", "exposes the region size and bounds via ARIA", "grows the panel by a step on ArrowRight", "shrinks the panel by a step on ArrowLeft", "uses the large step when Shift is held", "jumps to the minimum on Home", "jumps to the maximum on End", "collapses on Enter when the region is collapsible", "inverts the pointer delta under RTL so dragging resizes intuitively", "restores the previous size, not the minimum, when Enter reopens a collapsed pane", "reopens on Enter even when the minimum size sits below the collapse threshold", "reports the window basis as aria-valuemax when no maximum is configured; End leaves an unbounded region alone", "reports the container basis as aria-valuemax while a percentage bound already observes it", "never reports aria-valuemax below aria-valuemin while collapsed in a small window", "reports no aria-valuemax for an unbounded pixel-only region in a container, which stays unobserved", "a grow arrow opens a collapsed pane one step above its minimum; the shrink arrow leaves it collapsed", "a grow arrow opens a collapsed pane at its collapsedSize when the minimum sits below it", "a grow arrow opens a collapsed pane in the reversed layout and under RTL too", "in a reversed layout, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "under RTL, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "a grow arrow opens a hand-built collapsed region one step above its minimum", "with snap points, an arrow moves to the adjacent point in its direction and Shift moves two, clamped to the ends", "with snap points past the bounds, a point beyond maxSize or minSize counts as that bound", "with snap points, the arrows follow the reversed layout and the reading direction", "with snap points in a reversed layout, ArrowLeft moves to the next point and ArrowRight to the previous", "with snap points, the grow arrow opens a collapsed pane at the snap point nearest one step above its minimum") and `shippedDirections.test.ts`; `SideNav.test.tsx` ("names the nav it resizes with aria-controls (APG window splitter)"); RTL keyboard mirroring, and the disabled state under the Window Splitter accessibility contract (`internal/a11y-spec`, pending); `ResizeHandle.a11y.test.tsx` and `ResizeHandle.a11y.chromium.spec.ts` | Inline and block axes; LTR and RTL; collapsed; disabled | The Handle loses its role, name, orientation, or value properties; an arrow, Home, End, or Enter stops moving the divider or moves it against the reading direction. | `audit:Resizable/accessibility` |
+| PR1 | `useResizable.test.ts` observer tests | Pixel, percentage default, percentage bound | An observer on a pixel-only path, or one that outlives a final default, fails. | `audit:Resizable/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two targets | Missing, extra, or stale mappings fail repository validation. | `audit:Resizable/theming` |
+| RTL relation (ResizeHandle) | RTL audit curated D4 target (`apps/storybook/rtl-audit/targets.json`) on the `Horizontal split` story, beside the Resizable target | Horizontal split; LTR and RTL | A handle that does not move to the mirrored side of the layout in RTL fails D4. | `audit:Resizable/i18n-rtl` |
+| FR9 | `resizableSlot.test.tsx`: a LayoutPanel and its ResizeHandle given the region, and given its `props` | The region; its `props` | A panel that ignores the region's size, a handle that does not drive it, or a collapse that leaves the panel reachable fails | `audit:Resizable/api` |
## Decision log
diff --git a/packages/core/src/Resizable/Resizable.doc.mjs b/packages/core/src/Resizable/Resizable.doc.mjs
index cfea5f238d..af2d813ca4 100644
--- a/packages/core/src/Resizable/Resizable.doc.mjs
+++ b/packages/core/src/Resizable/Resizable.doc.mjs
@@ -184,7 +184,8 @@ export default function InvoicePreviewSplit() {
{
name: 'collapsedSize',
type: 'number',
- description: 'Pixel threshold that triggers collapse during drag.',
+ description:
+ 'Pixel threshold under which the lift of a drag collapses the region.',
default: '40',
},
{
@@ -325,7 +326,7 @@ export const docsDense = {
maxSize:
'live maximum: pixels, exact N%, or percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)})',
collapsible: 'region can collapse to size 0?',
- collapsedSize: 'px threshold triggering collapse during drag',
+ collapsedSize: 'px threshold under which a drag lift collapses',
snaps: 'px values to snap to during resize',
shrinkOrder: 'cascade priority: lower number shrinks first',
autoSaveId: 'key for persisting sizes + collapse state to localStorage',
diff --git a/packages/core/src/Resizable/ResizeHandle.tsx b/packages/core/src/Resizable/ResizeHandle.tsx
index 817d346292..cc02dfd1c5 100644
--- a/packages/core/src/Resizable/ResizeHandle.tsx
+++ b/packages/core/src/Resizable/ResizeHandle.tsx
@@ -26,6 +26,7 @@ import {
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {mergeProps, rtlStyles} from '../utils';
import {
+ endResizeAt,
getCollapseControls,
getEffectiveMaxPx,
resizablePropsOf,
@@ -465,10 +466,12 @@ export function ResizeHandle({
resizableRef.current?._onResizeStart();
},
move: delta => resizableRef.current?._onResizeMove(delta),
- end: () => {
+ end: velocity => {
const region = resizableRef.current ?? dragRegionRef.current;
dragRegionRef.current = undefined;
- region?._onResizeEnd();
+ if (region != null) {
+ endResizeAt(region, velocity ?? 0);
+ }
},
// Not a resize end, but the gesture is over. The region froze its state
// for the drag, so it must hear that the drag ended.
diff --git a/packages/core/src/Resizable/__tests__/paneSlide.interaction.browser.spec.ts b/packages/core/src/Resizable/__tests__/paneSlide.interaction.browser.spec.ts
index 77a9873b2d..4946d33c74 100644
--- a/packages/core/src/Resizable/__tests__/paneSlide.interaction.browser.spec.ts
+++ b/packages/core/src/Resizable/__tests__/paneSlide.interaction.browser.spec.ts
@@ -14,6 +14,8 @@
import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';
import {openStory, withStorybook} from '@astryxdesign/interaction-harness';
+import {settlingDuration, toSpring} from '../../motion/spring';
+import {springs} from '../../motion/uikit/springs';
const storybook = withStorybook(test);
@@ -26,6 +28,7 @@ const STORY = {
handBuilt: 'core-resizable--panel-with-hand-built-props',
controlled: 'core-resizable--sliding-controlled-panel',
scrolled: 'core-resizable--sliding-scrolled-panel-fixture',
+ defaultMinimum: 'core-resizable--sliding-panel-at-default-minimum-fixture',
} as const;
/** How many evenly spaced moments of a motion are captured. */
@@ -680,7 +683,49 @@ test('the grow arrow opens a collapsed panel with a slide', async ({page}) => {
expect((await pane.boundingBox())?.width ?? 0).toBeGreaterThan(100);
});
-test('a drag past the threshold slides the panel closed, and a drag that reopens it follows the pointer with no slide', async ({
+test('a key step under the collapsed size slides the panel closed on the theme curve, as a collapse does, not on the release spring', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.defaultMinimum);
+ await expectPresent(page);
+ const pane = page.getByTestId('sliding-panel');
+ const handle = page.getByRole('separator', {name: 'Resize panel'});
+ // A collapse from inside plays the theme's curve: the reference.
+ await page.getByRole('button', {name: 'Close panel'}).focus();
+ const collapse = await captureMotion(page, 'start', async () => {
+ await page.keyboard.press('Enter');
+ });
+ await handle.focus();
+ await captureMotion(page, 'start', async () => {
+ await page.keyboard.press('Enter');
+ });
+ // Down to the minimum, 50 px, in large steps: 150, 100, 50.
+ for (const width of [150, 100, 50]) {
+ await page.keyboard.press('Shift+ArrowLeft');
+ await expect
+ .poll(async () => (await pane.boundingBox())?.width ?? 0, {
+ message: `the pane steps to ${width} px`,
+ timeout: 2_000,
+ })
+ .toBeCloseTo(width, 0);
+ }
+ // One more step ends at 0, under the collapsed size (40 px).
+ const closing = await captureMotion(page, 'start', async () => {
+ await page.keyboard.press('Shift+ArrowLeft');
+ });
+ expectSlid(closing);
+ expect(closing.durationMs).toBeCloseTo(collapse.durationMs, -1);
+ expect(closing.durationMs).toBeLessThan(
+ settlingDuration(toSpring(springs.settle)) * 1000 - 100,
+ );
+ expect((await pane.boundingBox())?.width).toBeCloseTo(
+ await collapsedWidthOf(page),
+ 0,
+ );
+ await expect(pane).toHaveAttribute('inert', '');
+});
+
+test('a lift past the threshold slides the panel closed on the settle spring, and a drag that reopens it follows the pointer with no slide', async ({
page,
}) => {
await openFixture(page, STORY.start);
@@ -694,12 +739,19 @@ test('a drag past the threshold slides the panel closed, and a drag that reopens
const y = start.y + start.height / 2;
await page.mouse.move(start.x + start.width / 2, y);
await page.mouse.down();
- expectSlid(
- await captureMotion(page, 'start', async () => {
- await page.mouse.move(start.x + start.width / 2 - 190, y, {steps: 4});
- }),
+ await page.mouse.move(start.x + start.width / 2 - 190, y, {steps: 4});
+ // Still before the lift, so it releases with no velocity.
+ await page.waitForTimeout(200);
+ await expect(pane).not.toHaveAttribute('inert', '');
+ const closing = await captureMotion(page, 'start', async () => {
+ await page.mouse.up();
+ });
+ expectSlid(closing);
+ // It closes on the settle spring from the release velocity, here none.
+ expect(closing.durationMs).toBeCloseTo(
+ settlingDuration(toSpring(springs.settle)) * 1000,
+ -1,
);
- await page.mouse.up();
expect((await pane.boundingBox())?.width).toBeCloseTo(
await collapsedWidthOf(page),
0,
@@ -724,6 +776,523 @@ test('a drag past the threshold slides the panel closed, and a drag that reopens
await expect(pane).not.toHaveAttribute('inert', '');
});
+/** Presses the handle where it shows and returns that point. */
+async function pressHandle(page: Page): Promise<{x: number; y: number}> {
+ const box = await page
+ .getByRole('separator', {name: 'Resize panel'})
+ .boundingBox();
+ if (box == null) {
+ throw new Error('the handle is not laid out');
+ }
+ const at = {x: box.x + box.width / 2, y: box.y + box.height / 2};
+ await page.mouse.move(at.x, at.y);
+ await page.mouse.down();
+ return at;
+}
+
+interface EdgeFrame {
+ laidOut: number;
+ buttonWidth: number;
+ drawnEdge: number;
+ handle: number;
+ contentStart: number;
+}
+
+/** Records the pane, its first button, its handle and the content each frame. */
+async function recordEdgeFrames(page: Page): Promise<void> {
+ await page.evaluate(() => {
+ const pane = document.querySelector<HTMLElement>(
+ '[data-testid="sliding-panel"]',
+ );
+ const content = document.querySelector('[data-testid="sliding-content"]');
+ const handle = document.querySelector(
+ '[role="separator"][aria-label="Resize panel"]',
+ );
+ const button = pane?.querySelector('button');
+ const frames: EdgeFrame[] = [];
+ (window as unknown as {edgeFrames: EdgeFrame[]}).edgeFrames = frames;
+ const step = () => {
+ if (pane == null || content == null || handle == null || button == null) {
+ return;
+ }
+ const handleBox = handle.getBoundingClientRect();
+ frames.push({
+ laidOut: pane.offsetWidth,
+ buttonWidth: button.offsetWidth,
+ drawnEdge: pane.getBoundingClientRect().right,
+ handle: handleBox.left + handleBox.width / 2,
+ contentStart: content.getBoundingClientRect().left,
+ });
+ if (frames.length < 2000) {
+ requestAnimationFrame(step);
+ }
+ };
+ requestAnimationFrame(step);
+ });
+}
+
+/**
+ * Waits until no motion runs in the story, then two more frames, so the
+ * frames end at rest. It waits on the motion, not on time.
+ */
+async function waitForSettledMotion(page: Page): Promise<void> {
+ await page.waitForFunction(() => {
+ const root = document.getElementById('storybook-root');
+ return document
+ .getAnimations()
+ .every(
+ animation =>
+ animation.playState !== 'running' ||
+ !(animation.effect instanceof KeyframeEffect) ||
+ !(animation.effect.target instanceof Node) ||
+ root?.contains(animation.effect.target) !== true,
+ );
+ });
+ await page.evaluate(
+ async () =>
+ new Promise(resolve =>
+ requestAnimationFrame(() => requestAnimationFrame(resolve)),
+ ),
+ );
+}
+
+async function edgeFrames(page: Page): Promise<EdgeFrame[]> {
+ return page.evaluate(
+ () => (window as unknown as {edgeFrames: EdgeFrame[]}).edgeFrames,
+ );
+}
+
+test('past the maximum the edge moves at most 8 px, the pane never reflows, and the edge springs back after the lift', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const at = await pressHandle(page);
+ const rest = at.x + 120;
+ await recordEdgeFrames(page);
+ // 200 px plus 260 px of pull would be 460 px against a 320 px maximum.
+ await page.mouse.move(at.x + 260, at.y, {steps: 6});
+ await page.waitForTimeout(100);
+ await page.mouse.up();
+ await waitForSettledMotion(page);
+ const frames = await edgeFrames(page);
+ const past = frames.filter(frame => frame.laidOut === 320);
+ expect(past.length).toBeGreaterThan(2);
+ // The pane keeps its laid-out width and its button never reflows.
+ expect(new Set(past.map(frame => frame.buttonWidth)).size).toBe(1);
+ expect(Math.max(...frames.map(frame => frame.laidOut))).toBe(320);
+ // The edge stands past the limit by at most 8 px, then returns to it.
+ const furthest = Math.max(...past.map(frame => frame.handle));
+ expect(furthest).toBeGreaterThan(rest + 1);
+ expect(furthest).toBeLessThanOrEqual(rest + 8.5);
+ expect(frames.at(-1)?.handle).toBeCloseTo(rest, 0);
+ await expect(
+ page.getByRole('separator', {name: 'Resize panel'}),
+ ).toHaveAttribute('aria-valuenow', '320');
+});
+
+test('past the maximum the handle alone moves, over the content beside it: the pane and the content keep their places', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const at = await pressHandle(page);
+ await recordEdgeFrames(page);
+ await page.mouse.move(at.x + 260, at.y, {steps: 6});
+ await page.waitForTimeout(100);
+ await page.mouse.up();
+ await waitForSettledMotion(page);
+ const frames = await edgeFrames(page);
+ const past = frames.filter(frame => frame.laidOut === 320);
+ expect(past.length).toBeGreaterThan(2);
+ const spread = (values: number[]) =>
+ Math.max(...values) - Math.min(...values);
+ // The pane's drawn edge and the content's start stay where they lie.
+ expect(spread(past.map(frame => frame.drawnEdge))).toBeLessThanOrEqual(0.5);
+ expect(spread(past.map(frame => frame.contentStart))).toBeLessThanOrEqual(
+ 0.5,
+ );
+ // The handle passes over the content by at most 8 px.
+ const restHandle = past.at(-1)?.handle ?? 0;
+ const furthest = Math.max(...past.map(frame => frame.handle));
+ expect(furthest).toBeGreaterThan(restHandle + 1);
+ expect(furthest).toBeLessThanOrEqual(restHandle + 8.5);
+});
+
+test("a panel at the hook's size alone stops at the maximum, and nothing springs back after the lift", async ({
+ page,
+}) => {
+ await openFixture(page, 'core-resizable--horizontal-split');
+ const handle = page.getByRole('separator', {name: 'Resize sidebar'});
+ await expect(handle).toHaveAttribute('aria-valuenow', '250');
+ const start = await handle.boundingBox();
+ if (start == null) {
+ throw new Error('the handle is not laid out');
+ }
+ const at = {x: start.x + start.width / 2, y: start.y + start.height / 2};
+ await page.mouse.move(at.x, at.y);
+ await page.mouse.down();
+ // 250 px plus 400 px of pull would be 650 px against a 500 px maximum.
+ await page.mouse.move(at.x + 400, at.y, {steps: 6});
+ const pulled = await handle.boundingBox();
+ expect(Math.round((pulled?.x ?? 0) - start.x)).toBe(250);
+ await page.mouse.up();
+ const lifted = await handle.boundingBox();
+ expect(Math.round((lifted?.x ?? 0) - start.x)).toBe(250);
+ await expect(handle).toHaveAttribute('aria-valuenow', '500');
+});
+
+test('a spring-back past a limit lays out no frame: the edge glides back over the held pane', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const at = await pressHandle(page);
+ await page.mouse.move(at.x + 260, at.y, {steps: 6});
+ // Each frame from here on: the pane's laid-out width and the handle's
+ // drawn middle.
+ await page.evaluate(() => {
+ const pane = document.querySelector<HTMLElement>(
+ '[data-testid="sliding-panel"]',
+ );
+ const handle = document.querySelector(
+ '[role="separator"][aria-label="Resize panel"]',
+ );
+ const trace: {laidOut: number; drawn: number}[] = [];
+ (window as unknown as {springTrace: typeof trace}).springTrace = trace;
+ const startedAt = performance.now();
+ const step = () => {
+ if (pane == null || handle == null) {
+ return;
+ }
+ const box = handle.getBoundingClientRect();
+ trace.push({laidOut: pane.offsetWidth, drawn: box.x + box.width / 2});
+ if (performance.now() - startedAt < 1200) {
+ requestAnimationFrame(step);
+ }
+ };
+ requestAnimationFrame(step);
+ });
+ await page.mouse.up();
+ await page.waitForTimeout(1300);
+ const trace = await page.evaluate(
+ () =>
+ (
+ window as unknown as {
+ springTrace: {laidOut: number; drawn: number}[];
+ }
+ ).springTrace,
+ );
+ // The pane keeps the width it was pulled to until it takes the maximum,
+ // once: no frame in between lays the row out.
+ const widths = [...new Set(trace.map(frame => frame.laidOut))];
+ expect(widths.length).toBeLessThanOrEqual(2);
+ expect(widths.at(-1)).toBe(320);
+ // The edge still passes through the places in between.
+ const first = trace[0]?.drawn ?? 0;
+ const last = trace.at(-1)?.drawn ?? 0;
+ const between = trace.filter(
+ frame => frame.drawn < first - 1 && frame.drawn > last + 1,
+ );
+ expect(between.length).toBeGreaterThanOrEqual(3);
+});
+
+for (const [label, waitMs] of [
+ ['at once', 0],
+ ['50 ms after', 50],
+ ['mid-settle', 120],
+] as const) {
+ test(`a re-grab ${label} the lift past the maximum moves the edge 1:1 from where it shows`, async ({
+ page,
+ }) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const handle = page.getByRole('separator', {name: 'Resize panel'});
+ const at = await pressHandle(page);
+ // 200 px plus 260 px of pull would be 460 px against a 320 px maximum.
+ await page.mouse.move(at.x + 260, at.y, {steps: 6});
+ await page.mouse.up();
+ if (waitMs > 0) {
+ await page.waitForTimeout(waitMs);
+ }
+ const shown = await handle.boundingBox();
+ if (shown == null) {
+ throw new Error('the handle is not laid out');
+ }
+ const grab = {x: shown.x + shown.width / 2, y: at.y};
+ await page.mouse.move(grab.x, grab.y);
+ await page.mouse.down();
+ await page.mouse.move(grab.x - 40, grab.y, {steps: 4});
+ // The edge left from where it showed, past the maximum. It followed the
+ // finger 40 px back, so the pane is about 40 px under it. A spring-back
+ // from an outward release can carry the edge a few px past the band.
+ const now = Number(await handle.getAttribute('aria-valuenow'));
+ expect(now).toBeLessThan(295);
+ expect(now).toBeGreaterThan(270);
+ await page.mouse.up();
+ });
+}
+
+/** The handle's drawn middle, the pane's shown edge and the content's start. */
+async function shownParts(page: Page): Promise<{
+ handle: number;
+ paneEdge: number;
+ paneStart: number;
+ content: number;
+}> {
+ return page.evaluate(() => {
+ const pane = document.querySelector<HTMLElement>(
+ '[data-testid="sliding-panel"]',
+ );
+ const handle = document.querySelector(
+ '[role="separator"][aria-label="Resize panel"]',
+ );
+ const content = document.querySelector('[data-testid="sliding-content"]');
+ if (pane == null || handle == null || content == null) {
+ throw new Error('the sliding panel story did not render');
+ }
+ const box = pane.getBoundingClientRect();
+ // inset(top right bottom left): the clip on the edge facing the handle.
+ const insets = (
+ getComputedStyle(pane).clipPath.match(/-?[\d.]+(px|%)?/g) ?? []
+ ).map(value =>
+ value.endsWith('%')
+ ? (parseFloat(value) / 100) * box.width
+ : parseFloat(value),
+ );
+ const handleBox = handle.getBoundingClientRect();
+ return {
+ handle: handleBox.left + handleBox.width / 2,
+ paneEdge: box.right - (insets[1] ?? 0),
+ paneStart: box.left,
+ content: content.getBoundingClientRect().left,
+ };
+ });
+}
+
+/** The script motions still on the row's children: none once a slide lands. */
+async function rowMotions(page: Page): Promise<number> {
+ return page.evaluate(() => {
+ const row = document.querySelector(
+ '[data-testid="sliding-panel"]',
+ )?.parentElement;
+ return [...(row?.children ?? [])]
+ .flatMap(child => child.getAnimations())
+ .filter(
+ motion =>
+ !('transitionProperty' in motion) && !('animationName' in motion),
+ ).length;
+ });
+}
+
+/** Lifts past the threshold with no velocity and holds the close `atMs` in. */
+async function liftToCloseAndHold(
+ page: Page,
+ atMs: number,
+): Promise<{x: number; y: number}> {
+ const at = await pressHandle(page);
+ // 200 px less 190 px is 10 px: under the 40 px collapse threshold.
+ await page.mouse.move(at.x - 190, at.y, {steps: 4});
+ // Still before the lift, so it releases with no velocity.
+ await page.waitForTimeout(200);
+ await holdMotionAt(page, atMs, async () => {
+ await page.mouse.up();
+ });
+ return at;
+}
+
+test('a re-grab while the panel slides shut holds it where it shows, and the finger moves the slide, with no jump', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const pane = page.getByTestId('sliding-panel');
+ const handle = page.getByRole('separator', {name: 'Resize panel'});
+ // Open, the pane overlaps its handle by its collapse spacing; while it
+ // slides it does not.
+ const open = await shownParts(page);
+ const at = await liftToCloseAndHold(page, 120);
+ await expect(pane).toHaveAttribute('inert', '');
+ const held = await shownParts(page);
+ // The size the handle stands at: the pane opens at 200 px.
+ const sizeAt = (handleX: number) => 200 + handleX - open.handle;
+ const heldSize = sizeAt(held.handle);
+ expect(heldSize).toBeLessThan(110);
+ await page.mouse.move(held.handle, at.y);
+ await page.mouse.down();
+ await page.mouse.move(held.handle + 10, at.y, {steps: 2});
+ // Nothing finished the held slide: the finger moved it 10 px.
+ const moved = await shownParts(page);
+ expect(Math.abs(moved.handle - (held.handle + 10))).toBeLessThan(1);
+ // The pane's shown edge and the content keep their places beside the handle.
+ expect(
+ Math.abs(moved.handle - moved.paneEdge - (held.handle - held.paneEdge)),
+ ).toBeLessThan(1);
+ expect(
+ Math.abs(moved.content - moved.handle - (held.content - held.handle)),
+ ).toBeLessThan(1);
+ await expect(pane).toHaveAttribute('inert', '');
+ // Past the 120 px minimum the pane opens at the finger's size, with no
+ // slide left to play over it.
+ const travel = 120 - heldSize + 20;
+ await page.mouse.move(held.handle + travel, at.y, {steps: 4});
+ await expect(pane).not.toHaveAttribute('inert', '');
+ const opened = await shownParts(page);
+ expect(Math.abs(opened.handle - (held.handle + travel))).toBeLessThan(1);
+ expect(
+ Math.abs(opened.handle - opened.paneEdge - (open.handle - open.paneEdge)),
+ ).toBeLessThan(1);
+ expect(
+ Math.abs(opened.content - opened.handle - (open.content - open.handle)),
+ ).toBeLessThan(1);
+ expect(
+ Math.abs(
+ Number(await handle.getAttribute('aria-valuenow')) - (heldSize + travel),
+ ),
+ ).toBeLessThan(1.5);
+ expect(await rowMotions(page)).toBe(0);
+ await page.mouse.up();
+});
+
+for (const side of ['start', 'end'] as const) {
+ test(`a closing lift slides the ${side} panel's handle shut from where it shows, never back toward open`, async ({
+ page,
+ }) => {
+ await openFixture(page, STORY[side]);
+ await expectPresent(page);
+ // Toward closed is left for a start panel and right for an end one.
+ const towardOpen = side === 'start' ? 1 : -1;
+ const at = await pressHandle(page);
+ // 190 px toward closed: past the minimum, where the handle bands, and
+ // under the 40 px collapse threshold.
+ await page.mouse.move(at.x - towardOpen * 190, at.y, {steps: 4});
+ // Still before the lift, so it releases with no velocity.
+ await page.waitForTimeout(250);
+ await recordEdgeFrames(page);
+ await page.waitForTimeout(50);
+ await page.mouse.up();
+ await waitForSettledMotion(page);
+ const frames = await page.evaluate(
+ () => (window as unknown as {edgeFrames: EdgeFrame[]}).edgeFrames,
+ );
+ expect(frames.length).toBeGreaterThan(10);
+ for (let index = 1; index < frames.length; index++) {
+ expect(
+ towardOpen * (frames[index].handle - frames[index - 1].handle),
+ ).toBeLessThan(0.5);
+ }
+ });
+}
+
+test('a lift while a re-grab holds the closing panel shuts it under the collapse threshold', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const pane = page.getByTestId('sliding-panel');
+ const open = await shownParts(page);
+ const at = await liftToCloseAndHold(page, 120);
+ const held = await shownParts(page);
+ // The size the handle stands at: the pane opens at 200 px.
+ const heldSize = 200 + held.handle - open.handle;
+ await page.mouse.move(held.handle, at.y);
+ await page.mouse.down();
+ // Down to about 20 px, under the 40 px threshold.
+ await page.mouse.move(held.handle - (heldSize - 20), at.y, {steps: 3});
+ await page.mouse.up();
+ await waitForSettledMotion(page);
+ await expect(pane).toHaveAttribute('inert', '');
+ expect((await pane.boundingBox())?.width).toBeCloseTo(
+ await collapsedWidthOf(page),
+ 0,
+ );
+});
+
+test('a lift while a re-grab holds the closing panel above the collapse threshold opens it to the minimum', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const pane = page.getByTestId('sliding-panel');
+ const handle = page.getByRole('separator', {name: 'Resize panel'});
+ const open = await shownParts(page);
+ const at = await liftToCloseAndHold(page, 120);
+ const held = await shownParts(page);
+ await page.mouse.move(held.handle, at.y);
+ await page.mouse.down();
+ await page.mouse.move(held.handle + 5, at.y, {steps: 2});
+ await page.mouse.up();
+ await waitForSettledMotion(page);
+ await expect(pane).not.toHaveAttribute('inert', '');
+ await expect(handle).toHaveAttribute('aria-valuenow', '120');
+ const rest = await shownParts(page);
+ expect(
+ Math.abs(rest.handle - rest.paneEdge - (open.handle - open.paneEdge)),
+ ).toBeLessThan(1);
+ expect(
+ Math.abs(rest.content - rest.handle - (open.content - open.handle)),
+ ).toBeLessThan(1);
+ // No paused motion of the held slide is left to hold a stale transform.
+ expect(await rowMotions(page)).toBe(0);
+});
+
+test('an arrow key at the maximum moves nothing past it: no band, no spring-back', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const handle = page.getByRole('separator', {name: 'Resize panel'});
+ await handle.focus();
+ await page.keyboard.press('End');
+ const max = await handle.getAttribute('aria-valuemax');
+ await expect(handle).toHaveAttribute('aria-valuenow', max ?? '');
+ await page.keyboard.press('ArrowRight');
+ // The handle carries no drawn offset and plays no motion of its own.
+ const drawn = await handle.evaluate(node => ({
+ translate: getComputedStyle(node).translate,
+ motions: node.getAnimations().length,
+ }));
+ expect(drawn).toEqual({translate: 'none', motions: 0});
+ await expect(handle).toHaveAttribute('aria-valuenow', max ?? '');
+});
+
+test('below the minimum the edge moves at most 8 px, the pane keeps its minimum, and a slow lift above the threshold springs the edge back', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const pane = page.getByTestId('sliding-panel');
+ const at = await pressHandle(page);
+ const minimum = at.x - 80;
+ await recordEdgeFrames(page);
+ // 200 px less 130 px is 70 px: under the 120 px minimum, over the 40 px
+ // collapse threshold.
+ await page.mouse.move(at.x - 130, at.y, {steps: 6});
+ await page.waitForTimeout(200);
+ await page.mouse.up();
+ await waitForSettledMotion(page);
+ const frames = await edgeFrames(page);
+ expect(Math.min(...frames.map(frame => frame.laidOut))).toBe(120);
+ const nearest = Math.min(...frames.map(frame => frame.handle));
+ expect(nearest).toBeLessThan(minimum - 1);
+ expect(nearest).toBeGreaterThanOrEqual(minimum - 8.5);
+ expect(frames.at(-1)?.handle).toBeCloseTo(minimum, 0);
+ await expect(pane).not.toHaveAttribute('inert', '');
+});
+
+test('a flick toward closing from above the threshold closes on its lift', async ({
+ page,
+}) => {
+ await openFixture(page, STORY.start);
+ await expectPresent(page);
+ const pane = page.getByTestId('sliding-panel');
+ const at = await pressHandle(page);
+ // 110 px is over the threshold; the release velocity carries it past.
+ await page.mouse.move(at.x - 90, at.y, {steps: 3});
+ await page.mouse.up();
+ await expect(pane).toHaveAttribute('inert', '');
+});
+
test('a press where the handle shows lands on it at every moment of a slide, on both sides', async ({
page,
}) => {
diff --git a/packages/core/src/Resizable/createResizable.ts b/packages/core/src/Resizable/createResizable.ts
index 3b95cb85be..5245b79472 100644
--- a/packages/core/src/Resizable/createResizable.ts
+++ b/packages/core/src/Resizable/createResizable.ts
@@ -16,6 +16,12 @@ import {registerEnglishFallback} from '../i18n/englishFallback';
import english from '../i18n/generated-english/Resizable/createResizable.generated';
import {observeResize} from '../utils/sharedResizeObserver';
import {devWarn} from '../utils/devWarning';
+import {project} from '../motion/projection';
+import {
+ rubberBand,
+ rubberBandInverse,
+ rubberBandSlope,
+} from '../motion/rubberBand';
import type {SizeValue} from '../utils/types';
import {
DEFAULT_COLLAPSED_SIZE,
@@ -40,13 +46,21 @@ import {
type ResizeGestureState,
} from './resizeGesture';
import {
+ createOvershootDrawing,
createPaneReveal,
handOverPane,
+ type OvershootDrawing,
type PaneListener,
type RegionPaneSlot,
type ResizablePane,
+ isScriptMotion,
+ shownSizeReader,
+ slideMotionsOf,
+ slideNextOnRelease,
} from './resizablePane';
import {separatorAttributes} from './separatorAttributes';
+import {resolveMotion} from '../motion/resolveMotion';
+import {springs} from '../motion/uikit/springs';
import type {ResizableSize} from './utils';
// The English for the two messages it names, and nothing more of the catalog.
@@ -172,6 +186,9 @@ function readWindowExtent(direction: ResizableDirection): number | null {
/** Starts as warned: the factory warns, and this first-render read does not. */
const QUIET = {current: true};
+/** How far a pull past a size bound can move the handle, in px. */
+const RUBBER_BAND_TRAVEL_PX = 8;
+
/**
* The state a region with `options` starts in, before its handle exists: the
* server's render and a hook's first render. A container is not measured
@@ -391,6 +408,18 @@ export function createResizable(
*/
export type ResizableWarningSource = 'createResizable' | 'useResizable';
+/** A slide a closing lift plays. */
+interface ClosingSlide {
+ /** The size the handle shows at the lift, where its slide starts. */
+ fromSize: number;
+ /** When it started, on the page clock. */
+ startedAt: number;
+ /** The share still to go by ms since it started. */
+ remaining: (elapsedMs: number) => number;
+ /** Reads the size the pane shows from its handle's drawn middle. */
+ readShown: (() => number) | null;
+}
+
/**
* createResizable, with its development warnings in the words of `source`:
* the package's own entry, for useResizable.
@@ -435,7 +464,36 @@ export function createResizableAs(
// otherwise move the bound under the pointer.
let gestureBasis: number | null = null;
let isGestureActive = false;
+ // A catch between snap points: the edge follows the finger until it
+ // reaches one, and the snaps hold again from there.
+ let isCarryingToSnap = false;
let dragStartSize = 0;
+ let pointerSize = 0;
+ // The open size a drag started from, which a close on its lift keeps.
+ let sizeBeforeDrag: number | null = null;
+ // Past a bound the handle is drawn this far past it. The panes keep their
+ // sizes. It springs back to 0 after the lift.
+ let overshoot = 0;
+ // A finger that catches the drawn handle holds it where it shows: inside
+ // this much overshoot the handle follows the finger 1:1.
+ let caught = 0;
+ let drawing: OvershootDrawing | null = null;
+ // A closing lift keeps the drawn handle until the slide has measured it,
+ // so the slide starts from where the handle shows.
+ let isDrawingHeldForSlide = false;
+ // The drawn handle springs back to its limit after a lift.
+ let isSpringingBack = false;
+ // The slide a closing lift plays.
+ let closingSlide: ClosingSlide | null = null;
+ // A finger holds a pane that was sliding shut. The slide's motions are
+ // paused, and the finger moves them until it passes the minimum.
+ let held: {
+ slide: ClosingSlide;
+ motions: Animation[];
+ durationMs: number;
+ // The size the pane shows when the slide ends.
+ shutSize: number;
+ } | null = null;
let initialDefault: {px: number; isFinal: boolean} | null = null;
let chosenSize: number | null | undefined;
@@ -471,6 +529,8 @@ export function createResizableAs(
let pendingFlip: {toCollapsed: boolean; isPlayable: boolean} | null = null;
let expectedFlip: boolean | null = null;
let isPointerReopening = false;
+ // Whether a pointer drives the gesture under way; a key's step does not.
+ let isPointerGesture = false;
const direction = (): ResizableDirection => opts.direction ?? 'horizontal';
const collapsible = (): boolean => opts.collapsible ?? false;
@@ -614,7 +674,8 @@ export function createResizableAs(
chosenSize = clampSize(chosenSize, min, max, snaps());
}
}
- const size = clampSize(chosenSize ?? defaultPx, min, max, snaps());
+ const restsOn = isGestureActive && isCarryingToSnap ? [] : snaps();
+ const size = clampSize(chosenSize ?? defaultPx, min, max, restsOn);
const isCollapsed =
collapsible() &&
(isControlled() ? Boolean(opts.isCollapsed) : uncontrolledIsCollapsed);
@@ -751,6 +812,7 @@ export function createResizableAs(
} else {
paneReveal.land();
}
+ dropHeldDrawing();
return;
}
// The pane renders a collapse or open this factory has not made yet,
@@ -762,8 +824,11 @@ export function createResizableAs(
expectedFlip = toCollapsed;
paneReveal.measure(current, current.contentFacingEdge());
}
+ dropHeldDrawing();
},
committed() {
+ // The slide's after-measure reads the handle without its drawing.
+ dropHeldDrawing();
if (pane != null) {
paneReveal.committed(pane);
}
@@ -777,6 +842,9 @@ export function createResizableAs(
paneReveal.land();
pendingFlip = null;
expectedFlip = null;
+ isDrawingHeldForSlide = false;
+ drawing?.clear();
+ drawing = next == null ? null : createOvershootDrawing(next);
pane = handOverPane(pane, next, paneListener, derived.isCollapsed, handle);
}
@@ -925,29 +993,78 @@ export function createResizableAs(
};
},
start() {
+ dropHeldDrawing();
// The basis holds still for the whole gesture.
gestureBasis = readLiveBasis();
isGestureActive = true;
- dragStartSize = derived.isCollapsed ? 0 : derived.size;
+ isCarryingToSnap = false;
+ // Only a pointer catches a slide or a spring-back; a key steps.
+ const isPointer = regionSlot?.isPointerDragging() === true;
+ isPointerGesture = isPointer;
+ const closing = derived.isCollapsed && isPointer ? closingShown() : 0;
+ const slide = closingSlide;
+ closingSlide = null;
+ if (closing > 0 && slide != null) {
+ catchClosing(closing, slide);
+ return;
+ }
+ // A finger catches a spring-back where it shows.
+ const shown = !isPointer
+ ? 0
+ : isSpringingBack
+ ? (drawing?.shown() ?? 0)
+ : overshoot;
+ isSpringingBack = false;
+ overshoot = shown;
+ caught = shown;
+ drawing?.draw(shown);
+ dragStartSize = (derived.isCollapsed ? 0 : derived.size) + shown;
+ pointerSize = dragStartSize;
+ sizeBeforeDrag = derived.isCollapsed ? null : derived.size;
},
move(delta) {
+ const previous = pointerSize;
const raw = dragStartSize + delta;
- const collapsedSize = opts.collapsedSize ?? DEFAULT_COLLAPSED_SIZE;
- if (collapsible() && raw < collapsedSize) {
- if (!derived.isCollapsed) {
- setCollapsed(true);
- commit();
- opts.onCollapseChange?.(true);
- opts.onSizeChange?.(0);
+ pointerSize = raw;
+ if (held != null) {
+ if (raw < derived.min) {
+ holdAt(raw);
+ return;
}
+ held = null;
+ reopenAt(raw);
+ return;
+ }
+ if (
+ isCarryingToSnap &&
+ snaps().some(snap => (snap - previous) * (snap - raw) <= 0)
+ ) {
+ isCarryingToSnap = false;
+ }
+ const collapsedSize = opts.collapsedSize ?? DEFAULT_COLLAPSED_SIZE;
+ // A collapsed pane opens once the pointer passes the collapsed size.
+ // An open one never collapses mid-drag: the lift decides.
+ if (derived.isCollapsed && raw < collapsedSize) {
return;
}
const reopens = derived.isCollapsed && raw >= collapsedSize;
if (reopens) {
setCollapsed(false);
}
- const clamped = clampSize(raw, derived.min, derived.max, snaps());
+ const clamped = clampSize(
+ raw,
+ derived.min,
+ derived.max,
+ isCarryingToSnap ? [] : snaps(),
+ );
chosenSize = clamped;
+ // Only a pointer on a pane a LayoutPanel lends shows the rubber band. A
+ // panel at the hook's size alone, and a key, stop at the limit.
+ overshoot =
+ pane == null || regionSlot?.isPointerDragging() !== true
+ ? 0
+ : overshootPast(raw);
+ drawing?.draw(overshoot);
// Only a pointer reopens without a reveal; a key's step plays one.
isPointerReopening = reopens && regionSlot?.isPointerDragging() === true;
commit();
@@ -957,18 +1074,350 @@ export function createResizableAs(
}
opts.onSizeChange?.(clamped);
},
- end() {
+ // The lift decides a close: past the collapsed size, or released fast
+ // enough to come to rest past it. Anything else springs back.
+ end(velocity = 0) {
+ if (held != null) {
+ letGoOfHeldSlide(velocity);
+ endGesture();
+ return;
+ }
+ const collapsedSize = opts.collapsedSize ?? DEFAULT_COLLAPSED_SIZE;
+ const closes =
+ collapsible() &&
+ !derived.isCollapsed &&
+ Math.min(pointerSize, project(pointerSize, velocity)) < collapsedSize;
+ if (closes && !isPointerGesture) {
+ closeOnStep();
+ } else if (closes) {
+ closeOnRelease(velocity);
+ } else if (isCarryingToSnap) {
+ settleOnNearestSnap(velocity);
+ } else {
+ settleOvershoot(velocity);
+ }
endGesture();
},
// A cancelled gesture is still over: the basis it held comes back, and
// the size it reached is saved once, like a completed one.
cancel() {
+ if (held != null) {
+ letGoOfHeldSlide(-Infinity);
+ endGesture();
+ return;
+ }
+ if (isCarryingToSnap) {
+ settleOnNearestSnap(0);
+ } else {
+ settleOvershoot(0);
+ }
endGesture();
},
collapse,
expand,
};
+ /**
+ * A finger catches a pane that is still sliding shut, where it shows. Past
+ * the minimum it opens there at once. Under it the slide stops, and the
+ * finger moves the slide. The pane's edge, the handle and the content stay
+ * together under the finger until it passes the minimum.
+ */
+ function catchClosing(shownSize: number, slide: ClosingSlide): void {
+ dragStartSize = shownSize;
+ pointerSize = shownSize;
+ if (shownSize >= derived.min) {
+ reopenAt(shownSize);
+ return;
+ }
+ const motions = pane == null ? [] : slideMotionsOf(pane);
+ for (const motion of motions) {
+ motion.pause();
+ }
+ const elapsed = Number(motions[0]?.currentTime ?? 0);
+ const share = slide.remaining(Number.isFinite(elapsed) ? elapsed : 0);
+ // The shown size moves with the share of the slide still to go. It runs
+ // from the size laid out at the lift down to the size it shuts to.
+ const shutSize =
+ share < 0.98 ? (shownSize - slide.fromSize * share) / (1 - share) : 0;
+ held = {
+ slide,
+ motions,
+ durationMs: Number(motions[0]?.effect?.getComputedTiming().duration ?? 0),
+ shutSize,
+ };
+ }
+
+ /** The held slide shows `size`: its motions move to the time it shows it. */
+ function holdAt(size: number): void {
+ if (held == null) {
+ return;
+ }
+ const {slide, motions, durationMs, shutSize} = held;
+ const span = slide.fromSize - shutSize;
+ const share =
+ span > 0 ? Math.min(1, Math.max(0, (size - shutSize) / span)) : 0;
+ // The share still to go falls over the slide's time.
+ let low = 0;
+ let high = durationMs;
+ while (high - low > 0.05) {
+ const mid = (low + high) / 2;
+ if (slide.remaining(mid) > share) {
+ low = mid;
+ } else {
+ high = mid;
+ }
+ }
+ for (const motion of motions) {
+ motion.currentTime = (low + high) / 2;
+ }
+ }
+
+ /**
+ * A lift while a finger holds a closing pane. Under the collapse threshold,
+ * or fast enough to come to rest under it, the slide plays on and shuts.
+ * Any other lift opens the pane to its minimum from where it shows.
+ */
+ function letGoOfHeldSlide(velocity: number): void {
+ const current = held;
+ held = null;
+ if (current == null) {
+ return;
+ }
+ const collapsedSize = opts.collapsedSize ?? DEFAULT_COLLAPSED_SIZE;
+ if (Math.min(pointerSize, project(pointerSize, velocity)) < collapsedSize) {
+ for (const motion of current.motions) {
+ motion.play();
+ }
+ const view = pane?.element.ownerDocument.defaultView;
+ const elapsed = Number(current.motions[0]?.currentTime ?? 0);
+ if (view != null && Number.isFinite(elapsed)) {
+ closingSlide = {
+ ...current.slide,
+ startedAt: view.performance.now() - elapsed,
+ };
+ }
+ return;
+ }
+ const row = pane?.element.parentElement;
+ if (row != null) {
+ slideNextOnRelease(row, velocity, Math.max(derived.min - pointerSize, 1));
+ }
+ setCollapsed(false);
+ chosenSize = derived.min;
+ // The open plays: the paused slide reverses from what it shows.
+ commit();
+ opts.onCollapseChange?.(false);
+ opts.onSizeChange?.(derived.min);
+ }
+
+ /** The pane opens at once at `size`, under the pointer, with no slide. */
+ function reopenAt(size: number): void {
+ setCollapsed(false);
+ const clamped = clampSize(size, derived.min, derived.max, []);
+ isCarryingToSnap = snaps().length > 0 && !snaps().includes(clamped);
+ chosenSize = clamped;
+ sizeBeforeDrag = clamped;
+ caught = 0;
+ overshoot = pane == null ? 0 : overshootPast(size);
+ drawing?.draw(overshoot);
+ // Only a pointer reopens; the paused slide lands with what glides beside.
+ isPointerReopening = true;
+ commit();
+ isPointerReopening = false;
+ opts.onCollapseChange?.(false);
+ opts.onSizeChange?.(clamped);
+ }
+
+ /**
+ * A lift between snap points, after a catch: the edge glides from where it
+ * shows to the snap nearest it.
+ */
+ function settleOnNearestSnap(velocity: number): void {
+ isCarryingToSnap = false;
+ const shown = derived.size + overshoot;
+ isSpringingBack = false;
+ overshoot = 0;
+ drawing?.clear();
+ const target = clampSize(shown, derived.min, derived.max, snaps());
+ const row = pane?.element.parentElement;
+ const distance = Math.abs(target - shown);
+ if (row != null && distance > 0) {
+ slideNextOnRelease(row, Math.sign(target - shown) * velocity, distance);
+ }
+ chosenSize = target;
+ commit();
+ opts.onSizeChange?.(target);
+ }
+
+ /** How far the shown size runs past the bound `raw` is beyond. */
+ function overshootPast(raw: number): number {
+ const {min, max} = derived;
+ if (raw >= min && raw <= max) {
+ caught = 0;
+ return 0;
+ }
+ const bound = raw > max ? max : min;
+ const excess = raw - bound;
+ const held = Math.sign(caught) === Math.sign(excess) ? caught : 0;
+ // The band resumes past what a catch held, over the rest of its extent.
+ const shown =
+ Math.abs(excess) <= Math.abs(held)
+ ? excess
+ : held +
+ rubberBand(
+ excess - held,
+ Math.max(RUBBER_BAND_TRAVEL_PX - Math.abs(held), 0),
+ );
+ // Below the minimum the drawn handle stops at 0, never past it.
+ return Math.max(bound + shown, 0) - bound;
+ }
+
+ /**
+ * The drawn handle springs back to the bound on the settle spring from the
+ * release velocity, on the compositor. The size never left the bound, so
+ * nothing is laid out.
+ */
+ function settleOvershoot(velocity: number): void {
+ const from = overshoot;
+ isSpringingBack = false;
+ overshoot = 0;
+ if (from === 0 || drawing == null || pane == null) {
+ drawing?.clear();
+ return;
+ }
+ const element = pane.element;
+ const view = element.ownerDocument.defaultView;
+ if (
+ view == null ||
+ view.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true
+ ) {
+ drawing.clear();
+ return;
+ }
+ // The drawn handle moved at the pointer's speed times the band's slope.
+ const dimension = RUBBER_BAND_TRAVEL_PX;
+ const slope = rubberBandSlope(
+ rubberBandInverse(from, dimension),
+ dimension,
+ );
+ isSpringingBack = drawing.springBack(
+ resolveMotion(element, springs.settle),
+ velocity * slope,
+ );
+ }
+
+ /** Drops the drawn handle a closing lift kept for its slide to measure. */
+ function dropHeldDrawing(): void {
+ if (isDrawingHeldForSlide) {
+ isDrawingHeldForSlide = false;
+ drawing?.clear();
+ }
+ }
+
+ /** The size a pane still sliding shut shows now; 0 once it is shut. */
+ function closingShown(): number {
+ const element = pane?.element;
+ const view = element?.ownerDocument.defaultView;
+ if (closingSlide == null || element == null || view == null) {
+ return 0;
+ }
+ // The slide's own motion on the pane tells how far it has run. A held
+ // slide keeps its time, and a landed one reads past its end. Without the
+ // animation API, the time since the lift tells it.
+ const elapsed =
+ typeof element.getAnimations === 'function'
+ ? Number(
+ element
+ .getAnimations()
+ .find(
+ motion =>
+ (motion.playState === 'running' ||
+ motion.playState === 'paused') &&
+ isScriptMotion(motion),
+ )?.currentTime ?? Infinity,
+ )
+ : view.performance.now() - closingSlide.startedAt;
+ const share = closingSlide.remaining(elapsed);
+ if (!(share > 0)) {
+ return 0;
+ }
+ // The handle stays under the finger: the size is read from where it shows.
+ return closingSlide.readShown?.() ?? closingSlide.fromSize * share;
+ }
+
+ /**
+ * A key step that ends under the collapsed size closes as `collapse()`
+ * does, on the theme's curve: no gesture releases it.
+ */
+ function closeOnStep(): void {
+ // An open restores the size the step started from.
+ if (sizeBeforeDrag != null) {
+ chosenSize = sizeBeforeDrag;
+ }
+ setCollapsed(true);
+ commit();
+ opts.onCollapseChange?.(true);
+ opts.onSizeChange?.(0);
+ }
+
+ /**
+ * A lift that closes: the pane slides shut from what it shows, on the
+ * settle spring from the release velocity. The handle slides from where it
+ * is drawn.
+ */
+ function closeOnRelease(velocity: number): void {
+ isSpringingBack = false;
+ const drawnAtLift = overshoot;
+ const shown = derived.size + overshoot;
+ // Measured while the edge still shows where the lift left it.
+ const readShown = pane == null ? null : shownSizeReader(pane, shown);
+ overshoot = 0;
+ isDrawingHeldForSlide = drawing != null;
+ // An open restores the size the drag started from.
+ if (sizeBeforeDrag != null) {
+ chosenSize = sizeBeforeDrag;
+ }
+ const row = pane?.element.parentElement;
+ const remaining =
+ row == null ? null : slideNextOnRelease(row, -velocity, shown);
+ const view = pane?.element.ownerDocument.defaultView;
+ // Under Reduce Motion the pane shuts at once: nothing is left to catch.
+ closingSlide =
+ remaining == null ||
+ view == null ||
+ view.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true
+ ? null
+ : {
+ fromSize: shown,
+ startedAt: view.performance.now(),
+ remaining,
+ readShown,
+ };
+ setCollapsed(true);
+ commit();
+ opts.onCollapseChange?.(true);
+ opts.onSizeChange?.(0);
+ // A close the owner keeps open (a controlled isCollapsed) renders no
+ // slide to measure the drawing. By the next frame the handle springs back
+ // from where it is drawn.
+ if (isDrawingHeldForSlide) {
+ const springBackIfKept = () => {
+ if (!isDrawingHeldForSlide) {
+ return;
+ }
+ isDrawingHeldForSlide = false;
+ overshoot = drawnAtLift;
+ settleOvershoot(velocity);
+ };
+ if (typeof view?.requestAnimationFrame === 'function') {
+ view.requestAnimationFrame(springBackIfKept);
+ } else {
+ setTimeout(springBackIfKept, 16);
+ }
+ }
+ }
+
function readLiveBasis(): number {
const needs = observation();
if (!needs.hasContainer) {
@@ -1096,6 +1545,10 @@ export function createResizableAs(
// A gesture a ResizeHandle drove through the region's model, rather
// than the factory's own, ends the same way.
endGesture();
+ isSpringingBack = false;
+ overshoot = 0;
+ drawing?.clear();
+ drawing = null;
isDestroyed = true;
stopFollowingRegion?.();
stopFollowingRegion = null;
diff --git a/packages/core/src/Resizable/paneReveal.test.tsx b/packages/core/src/Resizable/paneReveal.test.tsx
index 9ea40aba4c..c3d3be2ef8 100644
--- a/packages/core/src/Resizable/paneReveal.test.tsx
+++ b/packages/core/src/Resizable/paneReveal.test.tsx
@@ -281,13 +281,17 @@ describe("a LayoutPanel's pane slides on collapse and open (component:Resizable
expect(reveals.every(r => r.animate.mock.calls.length === 1)).toBe(true);
});
- it('plays a drag that crosses the collapse threshold, plays nothing for a drag that reopens, and lands a running conceal then', () => {
+ it('plays the close a lift past the collapse threshold makes, plays nothing for a drag that reopens, and lands a running conceal then', () => {
render(<PropsSplit />);
fireEvent.pointerDown(grabZone(), {pointerId: 1, clientX: 300});
fireEvent.pointerMove(grabZone(), {pointerId: 1, clientX: 110});
+ expect(propsRegion?.isCollapsed).toBe(false);
+ expect(reveals).toHaveLength(0);
+ fireEvent.pointerUp(grabZone(), {pointerId: 1, clientX: 110});
expect(propsRegion?.isCollapsed).toBe(true);
expect(reveals).toHaveLength(1);
expect(reveals[0].animate).toHaveBeenCalledTimes(1);
+ fireEvent.pointerDown(grabZone(), {pointerId: 1, clientX: 110});
fireEvent.pointerMove(grabZone(), {pointerId: 1, clientX: 320});
expect(propsRegion?.isCollapsed).toBe(false);
expect(reveals).toHaveLength(1);
@@ -295,6 +299,135 @@ describe("a LayoutPanel's pane slides on collapse and open (component:Resizable
fireEvent.pointerUp(grabZone(), {pointerId: 1, clientX: 320});
});
+ it('reads no layout while a drag moves inside the limits', () => {
+ render(<PropsSplit />);
+ // The role query reads computed styles, so it runs before the spies.
+ const zone = grabZone();
+ fireEvent.pointerDown(zone, {pointerId: 1, clientX: 300});
+ const widths = vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get');
+ const styles = vi.spyOn(window, 'getComputedStyle');
+ for (const clientX of [290, 280, 270, 260]) {
+ fireEvent.pointerMove(zone, {pointerId: 1, clientX});
+ }
+ expect(widths).not.toHaveBeenCalled();
+ expect(styles).not.toHaveBeenCalled();
+ widths.mockRestore();
+ styles.mockRestore();
+ fireEvent.pointerUp(zone, {pointerId: 1, clientX: 260});
+ });
+
+ it('holds a pane still sliding shut where it shows, and opens it at the finger once the finger passes the minimum', () => {
+ render(<PropsSplit />);
+ const zone = grabZone();
+ fireEvent.pointerDown(zone, {pointerId: 1, clientX: 300});
+ fireEvent.pointerMove(zone, {pointerId: 1, clientX: 110});
+ fireEvent.pointerUp(zone, {pointerId: 1, clientX: 110});
+ expect(propsRegion?.isCollapsed).toBe(true);
+ // At once, while it slides shut: the lift left the edge near 43 px, the
+ // 50 px minimum less the band. The finger holds it there, still shut.
+ fireEvent.pointerDown(zone, {pointerId: 2, clientX: 110});
+ fireEvent.pointerMove(zone, {pointerId: 2, clientX: 113});
+ expect(propsRegion?.isCollapsed).toBe(true);
+ fireEvent.pointerMove(zone, {pointerId: 2, clientX: 140});
+ // The finger passed the minimum 30 px from where it caught the edge.
+ expect(propsRegion?.isCollapsed).toBe(false);
+ expect(propsRegion?.size).toBeGreaterThan(65);
+ expect(propsRegion?.size).toBeLessThan(80);
+ fireEvent.pointerUp(zone, {pointerId: 2, clientX: 140});
+ });
+
+ it('opens a held closing pane to its minimum on a lift above the collapse threshold', () => {
+ render(<PropsSplit />);
+ const zone = grabZone();
+ fireEvent.pointerDown(zone, {pointerId: 1, clientX: 300});
+ fireEvent.pointerMove(zone, {pointerId: 1, clientX: 110});
+ fireEvent.pointerUp(zone, {pointerId: 1, clientX: 110});
+ fireEvent.pointerDown(zone, {pointerId: 2, clientX: 110});
+ fireEvent.pointerMove(zone, {pointerId: 2, clientX: 112});
+ fireEvent.pointerUp(zone, {pointerId: 2, clientX: 112});
+ expect(propsRegion?.isCollapsed).toBe(false);
+ expect(propsRegion?.size).toBe(50);
+ });
+
+ it('springs the drawn handle back by the next frame when a controlled owner keeps the pane open on a closing lift', async () => {
+ const keepsOpen = vi.fn();
+ // At its 50 px minimum already, so the lift restores no other size.
+ render(
+ <PropsSplit
+ config={{
+ defaultSize: 50,
+ isCollapsed: false,
+ onCollapseChange: keepsOpen,
+ }}
+ />,
+ );
+ const zone = grabZone();
+ fireEvent.pointerDown(zone, {pointerId: 1, clientX: 300});
+ // 190 px toward closed: past the minimum, where the handle bands, and
+ // under the collapse threshold.
+ fireEvent.pointerMove(zone, {pointerId: 1, clientX: 110});
+ const drawn = separator().style.translate;
+ expect(drawn).not.toBe('');
+ fireEvent.pointerUp(zone, {pointerId: 1, clientX: 110});
+ expect(keepsOpen).toHaveBeenCalledWith(true);
+ expect(propsRegion?.isCollapsed).toBe(false);
+ await new Promise(resolve => setTimeout(resolve, 50));
+ expect(separator().style.translate).not.toBe(drawn);
+ });
+
+ it('keeps a held closing pane shut on a lift under the collapse threshold', () => {
+ render(<PropsSplit />);
+ const zone = grabZone();
+ fireEvent.pointerDown(zone, {pointerId: 1, clientX: 300});
+ fireEvent.pointerMove(zone, {pointerId: 1, clientX: 110});
+ fireEvent.pointerUp(zone, {pointerId: 1, clientX: 110});
+ fireEvent.pointerDown(zone, {pointerId: 2, clientX: 110});
+ // Down to about 13 px, under the 40 px threshold.
+ fireEvent.pointerMove(zone, {pointerId: 2, clientX: 80});
+ fireEvent.pointerUp(zone, {pointerId: 2, clientX: 80});
+ expect(propsRegion?.isCollapsed).toBe(true);
+ });
+
+ it('catches a pane sliding shut between snap points where it shows, and follows the finger to a snap', () => {
+ render(<PropsSplit config={{snaps: [50, 150, 300]}} />);
+ const zone = grabZone();
+ fireEvent.pointerDown(zone, {pointerId: 1, clientX: 300});
+ fireEvent.pointerMove(zone, {pointerId: 1, clientX: 110});
+ fireEvent.pointerUp(zone, {pointerId: 1, clientX: 110});
+ expect(propsRegion?.isCollapsed).toBe(true);
+ // The lift left the edge near 42 px. Mid-slide, the handle shows 133 px
+ // further out, so the pane shows about 175 px.
+ vi.spyOn(separator(), 'getBoundingClientRect').mockReturnValue(
+ DOMRect.fromRect({x: 133, y: 0, width: 0, height: 0}),
+ );
+ fireEvent.pointerDown(zone, {pointerId: 2, clientX: 110});
+ fireEvent.pointerMove(zone, {pointerId: 2, clientX: 120});
+ // The edge followed the finger 10 px from where it showed, between snaps.
+ expect(propsRegion?.size).toBeGreaterThan(180);
+ expect(propsRegion?.size).toBeLessThan(190);
+ // Past a snap point, the snaps hold again.
+ fireEvent.pointerMove(zone, {pointerId: 2, clientX: 245});
+ expect(propsRegion?.size).toBe(300);
+ fireEvent.pointerUp(zone, {pointerId: 2, clientX: 245});
+ expect(propsRegion?.size).toBe(300);
+ });
+
+ it('lands a caught pane on the snap nearest its edge when the finger lifts between snaps', () => {
+ render(<PropsSplit config={{snaps: [50, 150, 300]}} />);
+ const zone = grabZone();
+ fireEvent.pointerDown(zone, {pointerId: 1, clientX: 300});
+ fireEvent.pointerMove(zone, {pointerId: 1, clientX: 110});
+ fireEvent.pointerUp(zone, {pointerId: 1, clientX: 110});
+ vi.spyOn(separator(), 'getBoundingClientRect').mockReturnValue(
+ DOMRect.fromRect({x: 133, y: 0, width: 0, height: 0}),
+ );
+ fireEvent.pointerDown(zone, {pointerId: 2, clientX: 110});
+ fireEvent.pointerMove(zone, {pointerId: 2, clientX: 120});
+ fireEvent.pointerUp(zone, {pointerId: 2, clientX: 120});
+ expect(propsRegion?.isCollapsed).toBe(false);
+ expect(propsRegion?.size).toBe(150);
+ });
+
it('plays nothing for the first render or a resize that neither collapses nor opens', () => {
render(<PropsSplit config={{defaultIsCollapsed: true}} />);
act(() => {
@@ -420,9 +553,12 @@ describe("a LayoutPanel's pane slides on collapse and open (component:Resizable
}
fireEvent.pointerDown(grabZone(), {pointerId: 1, clientX: 300});
fireEvent.pointerMove(grabZone(), {pointerId: 1, clientX: 100});
+ expect(propsRegion?.isCollapsed).toBe(false);
+ fireEvent.pointerUp(grabZone(), {pointerId: 1, clientX: 100});
expect(propsRegion?.isCollapsed).toBe(true);
expect(reveals).toHaveLength(7);
expect(reveals[6].animate).toHaveBeenCalledTimes(1);
+ fireEvent.pointerDown(grabZone(), {pointerId: 1, clientX: 100});
fireEvent.pointerMove(grabZone(), {pointerId: 1, clientX: 340});
expect(propsRegion?.isCollapsed).toBe(false);
expect(reveals).toHaveLength(7);
diff --git a/packages/core/src/Resizable/resizablePane.tempo.test.ts b/packages/core/src/Resizable/resizablePane.tempo.test.ts
new file mode 100644
index 0000000000..4e015ee328
--- /dev/null
+++ b/packages/core/src/Resizable/resizablePane.tempo.test.ts
@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resizablePane.tempo.test.ts
+ * @input resizablePane.ts, the shared springs table, a stubbed computed style
+ * that writes a theme's tempo
+ * @output Proof that a release slide plays the settle spring at the theme's
+ * tempo
+ * @position Testing for /packages/core/src/Resizable/resizablePane.ts
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {settlingDuration, toSpring} from '../motion/spring';
+import {registerSpringsTable, springs} from '../motion/uikit';
+import {slideNextOnRelease} from './resizablePane';
+
+registerSpringsTable();
+
+const TEMPO_PROPERTY = '--_astryx-motion-tempo';
+
+/** The tempo the stubbed theme writes; empty where no theme sets one. */
+let tempo: string;
+
+beforeEach(() => {
+ tempo = '';
+ vi.spyOn(window, 'getComputedStyle').mockImplementation(
+ () =>
+ ({
+ getPropertyValue: (name: string) =>
+ name === TEMPO_PROPERTY ? tempo : '',
+ }) as unknown as CSSStyleDeclaration,
+ );
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ document.body.innerHTML = '';
+});
+
+function row(): HTMLElement {
+ const element = document.createElement('div');
+ document.body.append(element);
+ return element;
+}
+
+describe("a release slide at the theme's tempo", () => {
+ it('plays the settle spring tempo times as long', () => {
+ const settleMs = settlingDuration(toSpring(springs.settle)) * 1000;
+ const atOne = slideNextOnRelease(row(), 0, 100);
+ tempo = '1.5';
+ const atSlow = slideNextOnRelease(row(), 0, 100);
+
+ expect(atOne?.(settleMs * 1.2)).toBe(0);
+ expect(atSlow?.(settleMs * 1.2)).toBeGreaterThan(0);
+ expect(atSlow?.(settleMs * 1.6)).toBe(0);
+ });
+});
diff --git a/packages/core/src/Resizable/resizablePane.ts b/packages/core/src/Resizable/resizablePane.ts
index 3865c2433e..8b8070a7ea 100644
--- a/packages/core/src/Resizable/resizablePane.ts
+++ b/packages/core/src/Resizable/resizablePane.ts
@@ -13,9 +13,17 @@
import {
createAnimatedLayout,
- reportLayoutEdge,
+ glideNextChange,
+ glideOf,
+ landLayoutGlide,
type LayoutEdge,
+ reportLayoutEdge,
+ springGlide,
} from '../motion/animatedLayout';
+import {animatorFor, type MotionHandle} from '../motion/animator';
+import {resolveMotion} from '../motion/resolveMotion';
+import type {SpringDescription} from '../motion/spring';
+import {springs} from '../motion/uikit/springs';
import type {ResizableProps} from './useResizable';
export type {LayoutEdge};
@@ -346,6 +354,11 @@ export function createPaneReveal(getRow: () => Element | null): PaneReveal {
pending = null;
played?.cancel();
played = null;
+ // What glides beside the pane lands with it, so no motion plays over the
+ // layout that replaces it.
+ for (const child of getRow()?.children ?? []) {
+ landLayoutGlide(child);
+ }
};
return {
@@ -375,3 +388,207 @@ export function createPaneReveal(getRow: () => Element | null): PaneReveal {
land,
};
}
+
+/**
+ * The next slide in `row` plays the settle spring at the theme's tempo, not
+ * the theme's curve.
+ * It starts from a release `velocity` (px per second toward the end) over
+ * `distance` px. Returns the share of the distance still to go, by ms since
+ * the slide began, or null when nothing slides.
+ */
+export function slideNextOnRelease(
+ row: Element,
+ velocity: number,
+ distance: number,
+): ((elapsedMs: number) => number) | null {
+ if (!(distance > 0)) {
+ return null;
+ }
+ const progress = springGlide(
+ resolveMotion(row, springs.settle),
+ velocity / distance,
+ );
+ glideNextChange(row, progress);
+ return elapsedMs =>
+ elapsedMs >= progress.durationMs ? 0 : progress.remaining(elapsedMs);
+}
+
+/**
+ * Reads the size the pane's edge shows from its handle's drawn middle,
+ * glides included. Measured while the pane shows `size`.
+ */
+export function shownSizeReader(
+ pane: ResizablePane,
+ size: number,
+): (() => number) | null {
+ const element = pane.element;
+ const handle = resizeHandleBeside(element, null);
+ if (handle == null) {
+ return null;
+ }
+ const edge = pane.contentFacingEdge();
+ const isInline = edge.startsWith('inline');
+ const isRtl =
+ isInline &&
+ element.ownerDocument.defaultView?.getComputedStyle(element).direction ===
+ 'rtl';
+ const isForward = isInline
+ ? edge.endsWith('end') !== isRtl
+ : edge.endsWith('end');
+ const rect = element.getBoundingClientRect();
+ const far = isInline
+ ? isForward
+ ? rect.left
+ : rect.right
+ : isForward
+ ? rect.top
+ : rect.bottom;
+ const sign = isForward ? 1 : -1;
+ const middle = () => {
+ const box = handle.getBoundingClientRect();
+ return isInline ? box.left + box.width / 2 : box.top + box.height / 2;
+ };
+ // The handle's middle stands this far past the pane's shown edge.
+ const offset = sign * (middle() - far) - size;
+ return () => Math.max(sign * (middle() - far) - offset, 0);
+}
+
+/** A motion a script plays: not a CSS transition or a CSS animation. */
+export function isScriptMotion(motion: Animation): boolean {
+ return !('transitionProperty' in motion) && !('animationName' in motion);
+}
+
+/**
+ * The motions a slide of `pane` plays now: what glides beside it, and its own
+ * edge's motion on the same clock. None once the slide lands.
+ */
+export function slideMotionsOf(pane: ResizablePane): Animation[] {
+ const element = pane.element;
+ const beside = [...(element.parentElement?.children ?? [])]
+ .filter(child => child !== element)
+ .map(glideOf)
+ .filter((motion): motion is Animation => motion != null);
+ const durationOf = (motion: Animation) =>
+ Number(motion.effect?.getComputedTiming().duration ?? 0);
+ const durationMs = beside.length > 0 ? durationOf(beside[0]) : null;
+ const own =
+ typeof element.getAnimations === 'function'
+ ? element
+ .getAnimations()
+ .filter(
+ motion =>
+ isScriptMotion(motion) &&
+ (durationMs == null ||
+ Math.abs(durationOf(motion) - durationMs) < 1),
+ )
+ : [];
+ return [...own, ...beside];
+}
+
+/** A pull past a limit, drawn on a pane a LayoutPanel renders. */
+export interface OvershootDrawing {
+ /** Draws the handle `amount` px past its limit: positive past the maximum. */
+ draw(amount: number): void;
+ /**
+ * Springs the drawn handle back to the limit on the handle's own animator,
+ * on `spring` from a release `velocity`. The velocity is the amount's own
+ * rate in px per second, positive past the maximum. Returns false when
+ * nothing is drawn.
+ */
+ springBack(spring: SpringDescription, velocity: number): boolean;
+ /** How far past its limit the handle shows now, a spring-back included. */
+ shown(): number;
+ /** Drops the drawing at once. */
+ clear(): void;
+}
+
+/**
+ * Draws a pull past a limit with no layout change. The handle alone moves
+ * past the limit, over the content beside it, so the panes keep their sizes
+ * and nothing reflows. The geometry is measured once, as the overshoot
+ * starts.
+ */
+export function createOvershootDrawing(pane: ResizablePane): OvershootDrawing {
+ const element = pane.element;
+ let geometry: {
+ sign: number;
+ axis: 'x' | 'y';
+ handle: HTMLElement | null;
+ } | null = null;
+ let drawn = 0;
+ let springing: MotionHandle | null = null;
+
+ const measure = () => {
+ if (geometry != null) {
+ return geometry;
+ }
+ const edge = pane.contentFacingEdge();
+ const isInline = edge.startsWith('inline');
+ const isRtl =
+ isInline &&
+ element.ownerDocument.defaultView?.getComputedStyle(element).direction ===
+ 'rtl';
+ geometry = {
+ sign: (edge.endsWith('end') ? 1 : -1) * (isRtl ? -1 : 1),
+ axis: isInline ? 'x' : 'y',
+ handle: resizeHandleBeside(element, null),
+ };
+ return geometry;
+ };
+ const animator = () => {
+ const handle = geometry?.handle;
+ return handle == null ? null : animatorFor(handle);
+ };
+
+ return {
+ draw(amount) {
+ const isAtRest = drawn === 0 && springing == null;
+ if (isAtRest && amount === 0) {
+ return;
+ }
+ if (isAtRest) {
+ // A new overshoot measures once: the layout can change between pulls.
+ geometry = null;
+ }
+ springing = null;
+ drawn = amount;
+ const {sign, axis} = measure();
+ animator()?.set({[axis]: sign * amount});
+ },
+ springBack(spring, velocity) {
+ const motion = animator();
+ if (drawn === 0 || motion == null || geometry == null) {
+ return false;
+ }
+ const {sign, axis} = geometry;
+ drawn = 0;
+ const played = motion.animate(
+ {[axis]: 0},
+ {spring, velocity: {[axis]: sign * velocity}},
+ );
+ springing = played;
+ void played.finished.then(() => {
+ if (springing === played) {
+ springing = null;
+ }
+ });
+ return true;
+ },
+ shown() {
+ const motion = animator();
+ if (springing == null || motion == null || geometry == null) {
+ return drawn;
+ }
+ return geometry.sign * motion.get(geometry.axis);
+ },
+ clear() {
+ if (geometry != null && (drawn !== 0 || springing != null)) {
+ // Only the value: the drawing gives the handle no layer to keep.
+ animator()?.set({[geometry.axis]: 0}, {promote: false});
+ }
+ springing = null;
+ drawn = 0;
+ geometry = null;
+ },
+ };
+}
diff --git a/packages/core/src/Resizable/resizeGesture.ts b/packages/core/src/Resizable/resizeGesture.ts
index ce5f44819c..f534389602 100644
--- a/packages/core/src/Resizable/resizeGesture.ts
+++ b/packages/core/src/Resizable/resizeGesture.ts
@@ -11,6 +11,7 @@
* events to it. No React, and no DOM work on import
*/
+import {VelocityTracker} from '../gestures/VelocityTracker';
import type {ResizableDirection} from './resizableModel';
/** Pixels an arrow key moves the separator; Shift moves it further. */
@@ -37,8 +38,11 @@ export interface ResizeGestureModel {
start(): void;
/** The gesture has moved `delta` px from where it began. */
move(delta: number): void;
- /** The gesture ends as completed. */
- end(): void;
+ /**
+ * The gesture ends as completed. A pointer's lift passes its velocity along
+ * the resize axis, in px per second, signed as `move`'s delta.
+ */
+ end(velocity?: number): void;
/** The gesture ends without completing. */
cancel(): void;
/**
@@ -62,6 +66,7 @@ export interface ResizeGesturePointerEvent {
readonly pointerId: number;
readonly clientX: number;
readonly clientY: number;
+ readonly timeStamp?: number;
readonly currentTarget: EventTarget | null;
preventDefault(): void;
stopPropagation(): void;
@@ -177,6 +182,8 @@ export function createResizeGesture(
rtl: number;
target: Element | null;
} | null = null;
+ // The pointer's velocity at its lift, for the region's release.
+ const tracker = new VelocityTracker();
const rtlMultiplier = (): number => {
const handle = getHandle();
@@ -229,6 +236,8 @@ export function createResizeGesture(
rtl: isHorizontal ? rtlMultiplier() : 1,
target,
};
+ tracker.reset();
+ tracker.add(event.clientX, event.clientY, event.timeStamp ?? 0);
onDraggingChange?.(true);
model.start();
applyBodyDragStyles(isHorizontal);
@@ -242,6 +251,7 @@ export function createResizeGesture(
const position =
config.direction === 'horizontal' ? event.clientX : event.clientY;
const sign = config.isReversed ? -1 : 1;
+ tracker.add(event.clientX, event.clientY, event.timeStamp ?? 0);
model.move((position - drag.startPos) * drag.rtl * sign);
},
@@ -249,8 +259,13 @@ export function createResizeGesture(
if (drag?.pointerId !== event.pointerId) {
return;
}
+ const config = getConfig();
+ const {x, y} = tracker.velocity(event.timeStamp ?? 0);
+ const sign = config.isReversed ? -1 : 1;
+ const velocity =
+ (config.direction === 'horizontal' ? x : y) * drag.rtl * sign;
clearDrag();
- model.end();
+ model.end(velocity);
},
// Serves pointercancel and lostpointercapture alike: an interrupted drag
diff --git a/packages/core/src/Resizable/separatorAttributes.test.ts b/packages/core/src/Resizable/separatorAttributes.test.ts
index 0bbae066e0..166d6c10a5 100644
--- a/packages/core/src/Resizable/separatorAttributes.test.ts
+++ b/packages/core/src/Resizable/separatorAttributes.test.ts
@@ -72,4 +72,16 @@ describe('separatorAttributes', () => {
expect(bare['aria-valuemax']).toBeUndefined();
expect(bare.tabIndex).toBe(0);
});
+
+ it('keeps its value to the bounds while a pull past one shows the size beyond it', () => {
+ const at = (size: number) =>
+ separatorAttributes({
+ direction: 'horizontal',
+ isDisabled: false,
+ value: {...value, size, minPx: 120, maxPx: 320},
+ })['aria-valuenow'];
+ expect(at(360.4)).toBe(320);
+ expect(at(80)).toBe(120);
+ expect(at(200)).toBe(200);
+ });
});
diff --git a/packages/core/src/Resizable/separatorAttributes.ts b/packages/core/src/Resizable/separatorAttributes.ts
index 38f67409fe..88eee586f3 100644
--- a/packages/core/src/Resizable/separatorAttributes.ts
+++ b/packages/core/src/Resizable/separatorAttributes.ts
@@ -55,12 +55,11 @@ export function separatorAttributes(
return {
'aria-orientation':
state.direction === 'horizontal' ? 'vertical' : 'horizontal',
+ // The value stays within aria-valuemin and aria-valuemax.
'aria-valuenow':
value == null
? undefined
- : value.isCollapsed
- ? Math.max(value.size, value.minPx)
- : value.size,
+ : Math.min(Math.max(value.size, value.minPx), value.maxPx ?? Infinity),
'aria-valuemin': value?.minPx,
'aria-valuemax':
value?.maxPx != null && Number.isFinite(value.maxPx)
diff --git a/packages/core/src/Resizable/useResizable.doc.mjs b/packages/core/src/Resizable/useResizable.doc.mjs
index 41a494aed4..ff84a385d9 100644
--- a/packages/core/src/Resizable/useResizable.doc.mjs
+++ b/packages/core/src/Resizable/useResizable.doc.mjs
@@ -56,7 +56,7 @@ export const docs = {
name: 'collapsible',
type: 'boolean',
description:
- 'Whether dragging below the collapsed threshold collapses the region to zero.',
+ 'Whether a drag lifted below the collapsed threshold collapses the region to zero.',
default: 'false',
},
{
@@ -179,7 +179,7 @@ export const docsDense = {
containerRef: 'the element a percentage is a share of.',
direction: 'which axis to resize along.',
collapsible:
- 'whether dragging below collapsed threshold collapses region to zero.',
+ 'whether a drag lifted below collapsed threshold collapses region to zero.',
snaps: 'px values to snap to during drag.',
autoSaveId:
'key for localStorage persistence of size + collapse state across sessions.',
diff --git a/packages/core/src/Resizable/useResizable.test.ts b/packages/core/src/Resizable/useResizable.test.ts
index 9e68c78844..79964c2499 100644
--- a/packages/core/src/Resizable/useResizable.test.ts
+++ b/packages/core/src/Resizable/useResizable.test.ts
@@ -23,7 +23,7 @@ import {flushSync} from 'react-dom';
import {renderToString} from 'react-dom/server';
import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
import {render, renderHook, act, waitFor} from '@testing-library/react';
-import {useResizable} from './useResizable';
+import {endResizeAt, useResizable} from './useResizable';
import type {
ResizableProps,
ResizableRegion,
@@ -168,11 +168,12 @@ describe('useResizable persistence', () => {
act(() => result.current.resize(300));
act(() => result.current.props._onResizeStart());
act(() => result.current.props._onResizeMove(-270));
- expect(result.current.isCollapsed).toBe(true);
-
- // A continued drag below the threshold must not clobber the saved width.
+ // The lift decides the close; a drag below the threshold must not
+ // clobber the saved width either.
+ expect(result.current.isCollapsed).toBe(false);
act(() => result.current.props._onResizeMove(-275));
act(() => result.current.props._onResizeEnd());
+ expect(result.current.isCollapsed).toBe(true);
expect(readStored()).toEqual({size: 300, isCollapsed: true});
act(() => result.current.expand());
@@ -318,6 +319,8 @@ describe('useResizable uncontrolled collapse', () => {
act(() => result.current.props._onResizeStart());
act(() => result.current.props._onResizeMove(-240));
+ expect(result.current.isCollapsed).toBe(false);
+ act(() => result.current.props._onResizeEnd());
expect(result.current.isCollapsed).toBe(true);
expect(onCollapseChange).toHaveBeenCalledWith(true);
@@ -371,6 +374,7 @@ describe('useResizable controlled collapse', () => {
act(() => result.current.props._onResizeStart());
act(() => result.current.props._onResizeMove(-240));
+ act(() => result.current.props._onResizeEnd());
expect(onCollapseChange).toHaveBeenCalledWith(true);
expect(result.current.isCollapsed).toBe(false);
@@ -426,12 +430,14 @@ describe('useResizable live collapse state', () => {
for (const delta of [-240, -245, -250, -255, -260]) {
act(() => gesture._onResizeMove(delta));
}
+ expect(onCollapseChange).not.toHaveBeenCalled();
+ act(() => gesture._onResizeEnd());
expect(onCollapseChange).toHaveBeenCalledExactlyOnceWith(true);
expect(result.current.isCollapsed).toBe(true);
});
- it('re-expands mid-gesture when the drag crosses back above the threshold', () => {
+ it('stays open when the drag crosses back above the threshold before the lift', () => {
const onCollapseChange = vi.fn();
const {result} = renderHook(() =>
useResizable({...BASE_CONFIG, collapsible: true, onCollapseChange}),
@@ -441,12 +447,41 @@ describe('useResizable live collapse state', () => {
const gesture = result.current.props;
act(() => gesture._onResizeMove(-240));
act(() => gesture._onResizeMove(-20));
+ act(() => gesture._onResizeEnd());
- expect(onCollapseChange.mock.calls).toEqual([[true], [false]]);
+ expect(onCollapseChange).not.toHaveBeenCalled();
expect(result.current.isCollapsed).toBe(false);
expect(result.current.size).toBe(240);
});
+ it('closes on a lift released fast enough to come to rest past the threshold', () => {
+ const onCollapseChange = vi.fn();
+ const {result} = renderHook(() =>
+ useResizable({...BASE_CONFIG, collapsible: true, onCollapseChange}),
+ );
+
+ act(() => result.current.props._onResizeStart());
+ act(() => result.current.props._onResizeMove(-100));
+ // 1,500 px/s toward closing projects about 750 px further.
+ act(() => endResizeAt(result.current.props, -1500));
+
+ expect(onCollapseChange).toHaveBeenCalledExactlyOnceWith(true);
+ expect(result.current.isCollapsed).toBe(true);
+ });
+
+ it('springs back to the minimum from a slow lift above the threshold', () => {
+ const {result} = renderHook(() =>
+ useResizable({...BASE_CONFIG, collapsible: true}),
+ );
+
+ act(() => result.current.props._onResizeStart());
+ act(() => result.current.props._onResizeMove(-130));
+ act(() => endResizeAt(result.current.props, 0));
+
+ expect(result.current.isCollapsed).toBe(false);
+ expect(result.current.size).toBe(BASE_CONFIG.minSize);
+ });
+
it('notifies when resize() lifts the panel out of collapse', () => {
const onCollapseChange = vi.fn();
const {result} = renderHook(() =>
diff --git a/packages/core/src/Resizable/useResizable.ts b/packages/core/src/Resizable/useResizable.ts
index 76a9b91a54..6cdf343a2f 100644
--- a/packages/core/src/Resizable/useResizable.ts
+++ b/packages/core/src/Resizable/useResizable.ts
@@ -69,7 +69,10 @@ export interface ResizableRegionSizing {
defaultSize?: ResizableSize | SizeValue;
/** Whether this region can collapse to 0. @default false */
collapsible?: boolean;
- /** Size in px at which dragging triggers collapse. @default 40 */
+ /**
+ * Size in px under which a lift or a key step collapses the region.
+ * @default 40
+ */
collapsedSize?: number;
/** Pixel values to snap to during resize. */
snaps?: number[];
@@ -132,8 +135,8 @@ export interface UseResizableSingleOptions {
defaultIsCollapsed?: boolean;
/**
* Controlled collapse state. When set, the caller owns collapse:
- * `collapse()`, `expand()` and a drag past the collapse threshold report
- * through `onCollapseChange` instead of changing state here.
+ * `collapse()`, `expand()` and a drag lifted past the collapse threshold
+ * report through `onCollapseChange` instead of changing state here.
*/
isCollapsed?: boolean;
/** Called when size changes during drag. */
@@ -245,6 +248,12 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
const onResizeEnd = useCallback(() => {
model()?.end();
}, [model]);
+ const onResizeRelease = useCallback(
+ (velocity: number) => {
+ model()?.end(velocity);
+ },
+ [model],
+ );
const onResizeCancel = useCallback(() => {
model()?.cancel();
}, [model]);
@@ -265,6 +274,7 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
_isResizableProps: true,
};
collapseControls.set(props, {collapse, expand});
+ releaseEnds.set(props, onResizeRelease);
// The LayoutPanel that takes these props hands its pane to the region, and
// the ResizeHandle that takes them says when a pointer drags it.
registerPropsRegion(props, regionSlot);
@@ -336,6 +346,13 @@ function useMultiResizable(
type CollapseControls = {collapse: () => void; expand: () => void};
const collapseControls = new WeakMap<ResizableProps, CollapseControls>();
+/**
+ * A drag's end with its release velocity, in px per second and signed like
+ * the move's delta. Kept off the exported `ResizableProps` for the same reason
+ * as the collapse controls; {@link endResizeAt} is internal.
+ */
+const releaseEnds = new WeakMap<ResizableProps, (velocity: number) => void>();
+
/**
* The maximum an unbounded region reports as `aria-valuemax`: a measured
* extent that stands in for the missing configured maximum — the container's
@@ -379,6 +396,19 @@ export function getCollapseControls(
return collapseControls.get(props);
}
+/**
+ * Ends the drag `props` follows at a release `velocity`. A props object the
+ * hook did not return ends without one. Internal to the package.
+ */
+export function endResizeAt(props: ResizableProps, velocity: number): void {
+ const end = releaseEnds.get(props);
+ if (end == null) {
+ props._onResizeEnd();
+ return;
+ }
+ end(velocity);
+}
+
/** Removed keys must fail even when a variable bypasses excess-property checks. */
type RejectRemovedPixelBounds<Config> = Config extends unknown
? Config & {minSizePx?: never; maxSizePx?: never}
diff --git a/packages/core/src/Resizable/useResizableForms.test.tsx b/packages/core/src/Resizable/useResizableForms.test.tsx
index ad6777b18a..0d949e03fe 100644
--- a/packages/core/src/Resizable/useResizableForms.test.tsx
+++ b/packages/core/src/Resizable/useResizableForms.test.tsx
@@ -115,9 +115,14 @@ describe('size and isCollapsed land in the same commit as onCollapseChange (comp
fireEvent.doubleClick(separator());
expect(region?.isCollapsed).toBe(false);
expectInStep();
+ // The lift past the threshold closes, in step with its report.
fireEvent.pointerDown(grabZone(), {pointerId: 1, clientX: 300});
fireEvent.pointerMove(grabZone(), {pointerId: 1, clientX: 110});
+ expect(region?.isCollapsed).toBe(false);
+ fireEvent.pointerUp(grabZone(), {pointerId: 1, clientX: 110});
expect(region?.isCollapsed).toBe(true);
+ expectInStep();
+ fireEvent.pointerDown(grabZone(), {pointerId: 1, clientX: 110});
fireEvent.pointerMove(grabZone(), {pointerId: 1, clientX: 320});
fireEvent.pointerUp(grabZone(), {pointerId: 1, clientX: 320});
expect(region?.isCollapsed).toBe(false);
diff --git a/packages/core/src/motion/animatedLayout.ts b/packages/core/src/motion/animatedLayout.ts
index 7f2d386324..923697d7bb 100644
--- a/packages/core/src/motion/animatedLayout.ts
+++ b/packages/core/src/motion/animatedLayout.ts
@@ -92,6 +92,12 @@ import {
wrapText,
} from './transientCopy';
import {readThemeTiming, readThemeTokenText} from './themeTiming';
+import {
+ settlingDuration,
+ solveSpring,
+ toSpring,
+ type SpringDescription,
+} from './spring';
import {themeReducesMotion} from '../privateAttributes/reducedMotion.stylex';
import {reducedMotionCrossFade} from './uikit/timing';
import {
@@ -123,7 +129,7 @@ type LayoutMotion =
| {readonly kind: 'instant'};
/** The move curve as remaining distance (1 → 0) over its duration. */
-interface GlideProgress {
+export interface GlideProgress {
readonly durationMs: number;
/** The move curve's CSS text, as read where the area is. */
readonly easing: string;
@@ -161,6 +167,63 @@ function glideProgress(area: Element): GlideProgress | null {
};
}
+// A glide a gesture's release asks for, for the changes in one area.
+const releaseGlides = new WeakMap<Element, GlideProgress>();
+
+/**
+ * Times the changes `area` and what it holds play in the next frame by
+ * `progress`, not the theme's move curve. A release settles on its spring.
+ * Reduce Motion still wins.
+ */
+export function glideNextChange(area: Element, progress: GlideProgress): void {
+ releaseGlides.set(area, progress);
+ const view = area.ownerDocument.defaultView;
+ view?.requestAnimationFrame(() => {
+ view.requestAnimationFrame(() => releaseGlides.delete(area));
+ });
+}
+
+/**
+ * `spring` from rest toward the end, released at `velocity` (fractions of
+ * the move per second, toward the end), as a glide's progress.
+ */
+export function springGlide(
+ spring: SpringDescription,
+ velocity: number,
+): GlideProgress {
+ const physics = toSpring(spring);
+ const curve = solveSpring(physics, {from: 0, to: 1, velocity});
+ const durationMs =
+ settlingDuration(physics, {initialVelocity: velocity}) * 1000;
+ const remaining = (t: number) =>
+ t >= durationMs ? 0 : 1 - curve.value(t / 1000);
+ return {durationMs, easing: linearEasing(durationMs, remaining), remaining};
+}
+
+/** A move's remaining fraction over time as CSS `linear()` easing text. */
+function linearEasing(
+ durationMs: number,
+ remaining: (t: number) => number,
+): string {
+ const count = sampleCount(durationMs);
+ const stops: string[] = [];
+ for (let i = 0; i < count; i++) {
+ const done = 1 - remaining((i / (count - 1)) * durationMs);
+ stops.push(String(Math.round(done * 10000) / 10000));
+ }
+ return `linear(${stops.join(', ')})`;
+}
+
+function releaseGlideFor(area: Element): GlideProgress | undefined {
+ for (let at: Element | null = area; at != null; at = at.parentElement) {
+ const progress = releaseGlides.get(at);
+ if (progress != null) {
+ return progress;
+ }
+ }
+ return undefined;
+}
+
/** The motion a change in `area` plays now. */
function layoutMotion(area: Element): LayoutMotion {
if (
@@ -180,7 +243,7 @@ function layoutMotion(area: Element): LayoutMotion {
easing: `cubic-bezier(${x1}, ${y1}, ${x2}, ${y2})`,
};
}
- const progress = glideProgress(area);
+ const progress = releaseGlideFor(area) ?? glideProgress(area);
return progress == null ? {kind: 'instant'} : {kind: 'glide', progress};
}
diff --git a/scripts/motion-roles-table.mjs b/scripts/motion-roles-table.mjs
index cba6cf219d..9fce5fbddf 100644
--- a/scripts/motion-roles-table.mjs
+++ b/scripts/motion-roles-table.mjs
@@ -109,7 +109,7 @@ export function renderMotionRoleTable(roles, {fr4, records}) {
'',
'# Motion roles',
'',
- "The owner's goal: \"The main goals are consistent timings and well-coordinated pieces.\" The rules serve it: springs for a component whose main interaction is a gesture, including the moves a tap starts inside it; curve tokens for a component whose main interaction is a tap, tap-to-expand included; the nearest-token mapping for a measured duration; one coordinated scale for springs and curves through `tempo`, each spring paired with a timing tier (`spec:AST-094` FR45); and no per-component exceptions and no platform-native option. The owner's guidance: \"The guidance im thinking is: timing should be coordinated between spring and motion curve tokens, then use spring for gestures where velocity matters, use motion curves for taps presses and other non gesture motion.\" A component whose main interaction is a gesture plays springs for its motion, including moves a tap starts inside it (a tap on a sheet detent or a close button settles on the same spring), so its pieces stay coordinated. A component whose main interaction is a tap plays the theme's curve tokens (duration and easing, scaled by `tempo`), never a spring, since a tap carries no velocity; no character or option plays a platform-measured curve for it (owner decision, 2026-11-04). `spec:AST-094` FR45 lists which components each covers. Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. In a component whose main interaction is a tap, a role plays only for motion a gesture drives; in a gesture component, its roles also settle the moves a tap, a key or the program starts (`spec:AST-094` FR45). In a component whose main interaction is a tap, motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Two approved motions keep their springs until their own records change: the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are tap-started layout motion and play the theme's curve tokens (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.",
+ "The owner's goal: \"The main goals are consistent timings and well-coordinated pieces.\" The rules serve it: springs for a component whose main interaction is a gesture, including the moves a tap starts inside it; curve tokens for a component whose main interaction is a tap, tap-to-expand included; the nearest-token mapping for a measured duration; one coordinated scale for springs and curves through `tempo`, each spring paired with a timing tier (`spec:AST-094` FR45); and no per-component exceptions and no platform-native option. The owner's guidance: \"The guidance im thinking is: timing should be coordinated between spring and motion curve tokens, then use spring for gestures where velocity matters, use motion curves for taps presses and other non gesture motion.\" A component whose main interaction is a gesture plays springs for its motion, including moves a tap starts inside it (a tap on a sheet detent or a close button settles on the same spring), so its pieces stay coordinated. A component whose main interaction is a tap plays the theme's curve tokens (duration and easing, scaled by `tempo`), never a spring, since a tap carries no velocity; no character or option plays a platform-measured curve for it (owner decision, 2026-11-04). `spec:AST-094` FR45 lists which components each covers. Every motion role a registered table lists (`spec:AST-094` FR4, DEC-5): its kind, its default as the table measures it, and the record that names it. A role FR4 lists is named by FR4; any other role is one a component's own record measures, named by the current component records that carry its id. In a component whose main interaction is a tap, a role plays only for motion a gesture drives; in a gesture component, its roles also settle the moves a tap, a key or the program starts (`spec:AST-094` FR45). In a component whose main interaction is a tap, motion that a tap, a click, a hold, a key or the program starts plays the theme's duration and easing tokens, and an exit it starts plays the theme's exit duration and easing (`spec:AST-094` FR7), and a role measured for that motion stays as the native reference. Two approved motions keep their springs until their own records change: the animator's `animate` (`spec:AST-107` FR3) and `useDragToSnapPoints`'s `settleTo` (`spec:AST-107`). AST-105's glide, swap and edge reveal are tap-started layout motion and play the theme's curve tokens, except a gesture's release, which settles on its spring (`spec:AST-105` FR4). Reduce Motion substitutions and continuous busy loops (such as ProgressBar's indeterminate pulse, `component:ProgressBar` FR6) keep their named roles; they are neither gesture- nor interaction-started motion. Measured input timings, such as gesture thresholds, hold durations and flick speeds, are not motion roles.",
'',
'| Role | Kind | Default | Named by |',
'| --- | --- | --- | --- |',
diff --git a/scripts/touch-support-bundle.test.mjs b/scripts/touch-support-bundle.test.mjs
index 04893260aa..77996810ad 100644
--- a/scripts/touch-support-bundle.test.mjs
+++ b/scripts/touch-support-bundle.test.mjs
@@ -209,6 +209,9 @@ const GESTURE_USERS = new Set([
'Tokenizer',
// Slider's thumb.
'Slider',
+ // Resizable: its drag tracks the release velocity that the lift's close and
+ // the handle's spring-back start from.
+ 'Resizable',
// Switch: its press tracking and its drag, for every pointer.
'Switch',
// SegmentedControl: its press tracking and its drag, for every pointer.