@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/Resizable/Resizable.spec.md

@@ -152,6 +152,31 @@ orientation, collapsed value text, focus, pointer, or keyboard behavior. Its
 `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` remain the same resolved pixel
 values used by hook state and painted geometry.
 
+- **AR1 — ResizeHandle adopts the APG Window Splitter pattern**
+  (`spec:AST-020/FR15`), as one composite control: the Handle is a focusable
+  `role="separator"` with an accessible name, `aria-orientation` (the axis the
+  divider lies along), `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` in
+  pixels, `aria-valuetext` while collapsed, and `aria-disabled` when disabled.
+  ArrowRight and ArrowDown move the divider toward the end of its axis and
+  ArrowLeft and ArrowUp toward the start, the inline arrows following the
+  reading direction under RTL, with Shift for a larger step, so the pane grows
+  or shrinks by the side of the Handle it sits on; with snap points set, an
+  arrow moves to the adjacent snap point, a point beyond `minSize` or `maxSize`
+  counting as that bound (Shift, two); Home moves to the minimum size and End to
+  the maximum; Enter collapses a collapsible pane and restores it, and the arrow
+  that grows a collapsed pane opens it one step above its minimum, or at its
+  `collapsedSize` when that is larger (with snap points, at the snap point
+  nearest that size; the shrinking arrow leaves it collapsed). An unbounded
+  Handle reports a measured stand-in as `aria-valuemax`: the window's extent
+  along its axis when no container is supplied, or its container's content box
+  while a percentage bound observes it, never below its current size or, while
+  collapsed, its minimum. Implementation gaps under `spec:AST-020/FR15`: the
+  Handle names the pane it resizes with `aria-controls` only when its caller
+  passes one (SideNav does); an unbounded Handle in a container that no
+  percentage bound observes carries no `aria-valuemax`, because measuring that
+  container would add an observer to a region whose bounds are all in pixels
+  (Performance and resources); and End does not move an unbounded Handle.
+
 ## Design relationships
 
 | Anatomy or state | Design requirement                                                      | Representation authority       | Hierarchy role | Component contract |
@@ -198,15 +223,16 @@ not emit the documented target state.
 
 ## Verification map
 
-| Contract            | Verification                                       | Representative states                                                                                           | Mutation or failure expectation                                                                                                                    | Audit section              |
-| ------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1                 | `ResizeHandle.test.tsx` plus source inspection     | Default, custom, collapsed, disabled, both axes                                                                 | Handle and Grab zone regressions fail focused tests; custom Grip replacement currently relies on source review.                                    | `audit:Resizable/anatomy`  |
-| FR2                 | Source inspection and `themingTargets.test.ts`     | Handle, Grip pill, and Grab zone                                                                                | Removing a target or documenting an unshipped Grab zone target fails evidence or inventory.                                                        | `audit:Resizable/theming`  |
-| FR3                 | `ResizeHandle.test.tsx` and `useResizable.test.ts` | Pointer, keyboard, snap, collapse, persistence                                                                  | Moving resize ownership or changing current transformations fails focused behavior coverage.                                                       | `audit:Resizable/behavior` |
-| FR4                 | Source and public metadata comparison              | Horizontal and vertical Handle                                                                                  | No current test detects that documented `direction` is absent from runtime target-state reflection.                                                | `audit:Resizable/theming`  |
-| FR5                 | Hook/utils tests, typecheck, and Chromium          | Canonical floor/ceiling/default; invalid XOR shape; SSR/hydration; basis changes; numeric `containerRef` parity | Wrong resolution, rescaling defaults, stale clamps, observer leaks, extra numeric renders/ref reads, or state/paint/storage/ARIA divergence fails. | `audit:Resizable/behavior` |
-| FR6                 | Hook type/runtime and codemod tests                | Removed alias type errors; single/multi-region inline migrations; numeric pixel bounds                          | A removed alias still type-checks, or migration changes its numeric meaning.                                                                       | `audit:Resizable/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                      | Canonical anatomy and two current targets                                                                       | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.                                                         | `audit:Resizable/theming`  |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Representative states                                                                                           | Mutation or failure expectation                                                                                                                                   | Audit section                   |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1                 | `ResizeHandle.test.tsx` plus source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Default, custom, collapsed, disabled, both axes                                                                 | Handle and Grab zone regressions fail focused tests; custom Grip replacement currently relies on source review.                                                   | `audit:Resizable/anatomy`       |
+| 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) | 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` |
+| FR2                 | Source inspection and `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Handle, Grip pill, and Grab zone                                                                                | Removing a target or documenting an unshipped Grab zone target fails evidence or inventory.                                                                       | `audit:Resizable/theming`       |
+| FR3                 | `ResizeHandle.test.tsx` and `useResizable.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Pointer, keyboard, snap, collapse, persistence                                                                  | Moving resize ownership or changing current transformations fails focused behavior coverage.                                                                      | `audit:Resizable/behavior`      |
+| FR4                 | Source and public metadata comparison                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Horizontal and vertical Handle                                                                                  | No current test detects that documented `direction` is absent from runtime target-state reflection.                                                               | `audit:Resizable/theming`       |
+| FR5                 | Hook/utils tests, typecheck, and Chromium                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Canonical floor/ceiling/default; invalid XOR shape; SSR/hydration; basis changes; numeric `containerRef` parity | Wrong resolution, rescaling defaults, stale clamps, observer leaks, extra numeric renders/ref reads, or state/paint/storage/ARIA divergence fails.                | `audit:Resizable/behavior`      |
+| FR6                 | Hook type/runtime and codemod tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Removed alias type errors; single/multi-region inline migrations; numeric pixel bounds                          | A removed alias still type-checks, or migration changes its numeric meaning.                                                                                      | `audit:Resizable/behavior`      |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Canonical anatomy and two current targets                                                                       | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.                                                                        | `audit:Resizable/theming`       |
 
 Current tests exercise Handle and Grab zone structure and behavior but do not
 render `children` to prove that custom content replaces Grip pill. That branch is
@@ -232,6 +258,12 @@ literal percentage.
 partial second CSS implementation without a demonstrated need for arbitrary
 composition.
 
+### The Handle is an APG window splitter
+
+**Decision:** ResizeHandle already acts as one composite control with the splitter's role, value properties, and keyboard, so it adopts the pattern's required parts and its keyboard (AR1), with `aria-controls` the caller does not pass, `aria-valuemax` on an unbounded Handle in a container that no percentage bound observes, and End on an unbounded Handle recorded as implementation gaps; the inline arrows follow the reading direction because a key that moves the divider against the way it travels on screen is a defect. Decided by `cixzhang`, `2026-10-13`.
+
+**Rejected:** a separate button to collapse the pane; a direction-free ArrowLeft under RTL.
+
 ## Open questions
 
 - **OQ1 — Which follow-up should add and verify the missing Handle `direction`