An open source design system that's fully customizable and agent ready
TypeScript
docs: specify percentage-based useResizable sizing (#5803)
Cindy Zhang8824ca1baee2
diff --git a/docs/specs/AST-010/spec.md b/docs/specs/AST-010/spec.mdnew file mode 100644index 0000000000..9231a3f448--- /dev/null+++ b/docs/specs/AST-010/spec.md@@ -0,0 +1,414 @@+---+schema_version: 1+template_version: 1+kind: system-spec+id: spec:AST-010+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-08-31+phase: accepted+owners: [cixzhang]+affects_architecture: [architecture:public-component-api]+affects_families: [family:layout-regions]+affects_contributing: []+affects_consumer_docs: [Resizable]+---++# Percentage-based useResizable configuration system spec++## Intent++A person resizing a panel should get the same panel size that the handle presents+and assistive technology announces. Builders may configure an initial size or+bounds as percentages, but every user-selected size remains pixels so pointer,+keyboard, persistence, and programmatic behavior stay predictable.++This spec preserves the released meaning of `defaultSize: 'N%'` when no+`containerRef` is supplied: resolve once against `window.innerWidth` (or the+1200px server fallback), then continue as pixels. Supplying `containerRef`+changes only the basis used by percentage configuration: the container's+content-box active axis replaces the viewport. It does not create a persistent+relative sizing mode.++Numeric inputs are pixels. Resolved public outputs remain pixels. Shipped source,+tests, and consumer docs remain the evidence for current behavior until the+implementation and verification below land; the draft `component:Resizable`+record is updated alongside that implementation.++## Non-goals++- Implementing runtime behavior in this specification pull request.+- Preserving a percentage ratio after pointer, keyboard, or programmatic resize.+- Automatically distributing remaining space or requiring independently sized+ regions to total 100%.+- Supporting arbitrary CSS units such as `rem`, `vw`, or `calc()`.+- Adding percentage snap points or percentage collapse thresholds.+- Adding controlled size state; current controlled collapse behavior is+ unchanged.+- Widening `resize()` beyond its released numeric pixel input.+- Changing the persisted state shape or adding a relative-size field.+- Widening SideNav's simplified `defaultWidth`, `minWidth`, and `maxWidth`+ configuration. That integration requires a separate component decision because+ SideNav owns its root and handle.+- Changing LayoutPanel's ownership of structure, scrolling, inset, or divider+ presentation.++## Requirements++- **FR1 — Percentage configuration uses an explicit basis.** Without+ `containerRef`, a percentage `defaultSize` MUST resolve once against+ `window.innerWidth`, or 1200px when `window` is unavailable, preserving the+ released fallback. With `containerRef`, it MUST resolve once against that+ container's measured content-box active axis. After either resolution, the+ selected size is pixels and MUST NOT scale when the viewport or container+ changes.+- **FR2 — Direction selects the container basis.** With `containerRef`,+ horizontal resizing MUST use the container's content-box inline size and+ vertical resizing MUST use its content-box block size. RTL may reverse pointer+ delta, but MUST NOT change the percentage basis. Without `containerRef`, the+ compatibility basis remains `window.innerWidth` regardless of direction.+- **FR3 — Interactions remain pixel-based.** Numeric defaults and every result of+ a percentage default resolve to pixels. Pointer, keyboard, snap, collapse,+ expand, persistence, callback, and programmatic resize paths MUST continue to+ read and write pixel selections exactly as the released API does. No+ interaction may create or preserve a percentage-selected mode.+- **FR4 — Mixed bounds remain valid.** Builders MAY combine pixel and percentage+ values across `defaultSize`, `minSize`, and `maxSize`. Numeric bounds remain+ pixels. Percentage bounds resolve against the same viewport or container basis+ as FR1 and MUST re-resolve whenever that basis changes. Re-resolved bounds clamp+ the existing pixel selection; they MUST NOT scale it proportionally. If the+ resolved minimum exceeds the resolved maximum, development MUST warn and the+ maximum MUST win, preserving the released `Math.min(max, Math.max(min, size))`+ ordering and guaranteeing finite, non-`NaN` geometry.+- **FR5 — Effective geometry stays synchronized.** The effective selected pixel+ size, LayoutPanel or caller-rendered size, persisted expanded value, and+ ResizeHandle's `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` MUST describe+ the same resolved geometry. CSS-only clamping that leaves hook state outside the+ painted bounds is prohibited. Existing controlled-collapse callbacks remain an+ explicit exception: they report a rejected collapse or expand intent without+ claiming that the controlled owner changed the rendered size.+- **FR6 — Basis changes update only percentage constraints.** Once a percentage+ default has initialized the selected pixel size, a viewport or container resize+ MUST NOT re-resolve that default. Percentage bounds MUST re-resolve and clamp the+ selected pixel size. A basis-only layout change MUST NOT fire an interaction+ callback or otherwise claim that a person selected a new size.+- **FR7 — Pointer gestures preserve released behavior.** Pointer deltas continue+ from the selected pixel size. Percentage bounds MUST use one stable basis during+ a gesture; a basis change during the gesture takes effect after the gesture ends+ so the handle does not move away from the pointer.+- **FR8 — Keyboard, snap, and collapse semantics continue.** Arrow-key steps,+ Shift+Arrow steps, Home, End, collapse thresholds, and snap points remain+ pixel-based. Collapse retains the expanded pixel size, and expand restores that+ pixel size subject to the currently resolved bounds.+- **FR9 — Persistence remains pixel-only.** Existing positive plain numbers and+ `{size, isCollapsed}` entries MUST continue to restore as pixel choices. A+ legacy plain `0` MUST retain its current meaning: collapsed with no saved+ expanded size when collapse is enabled, otherwise no usable saved size. New+ percentage configuration MUST use the current persisted pixel shape; no+ percentage or relative-mode field is added.+- **FR10 — Callbacks report resolved pixels.** `onSizeChange` MUST continue to+ receive resolved pixel numbers for user interactions and released programmatic+ transitions. Initialization, hydration correction, viewport resize, container+ resize, and bounds-only re-clamping MUST NOT be reported as user interaction.+- **FR11 — Single and multi-region configurations share the contract.** A+ multi-region call MUST use one optional container and axis for all regions.+ Regions remain independently pixel-selected; this change MUST NOT add balancing,+ ratio preservation, or a 100% total invariant.+- **FR12 — Invalid configuration has safe deterministic fallbacks.** Accepted+ configuration is a non-negative finite number, an exact non-negative finite+ `Npx` string, or an exact `N%` string from 0% through 100%. An invalid,+ malformed, negative, or non-finite `defaultSize` MUST use 250px before normal+ bounds clamping; an invalid `minSize` or `minSizePx` MUST use 50px; and an+ invalid `maxSize` or `maxSizePx` MUST use unbounded `Infinity`. Explicit+ `maxSizePx: Infinity` remains valid for compatibility because a shipped template+ uses it. Development MUST warn for every fallback; production MUST use the same+ fallback without warning. After initialization, an invalid raw value MUST NOT+ directly replace a persisted or otherwise legal selected pixel size; a+ fallback-normalized bound may affect that size only through normal clamping.++### Public API requirements++- **API1 — `containerRef` opts into a container basis, not a relative mode.**+ Single- and multi-region config MAY accept+ `containerRef?: React.RefObject<HTMLElement | null>`. When omitted, percentage+ configuration uses the released viewport basis. When supplied, every percentage+ default or bound uses that container's content-box active axis. The ref is+ caller-owned because only the caller can identify the intended layout container;+ the hook MUST NOT infer a panel or ResizeHandle ancestor.+- **API2 — Direction is explicit.** Single-region config MAY accept+ `direction?: 'horizontal' | 'vertical'`, defaulting to `horizontal`.+ Multi-region config's existing top-level `direction` supplies every region's+ axis. ResizeHandle direction and hook direction MUST agree; the implementation+ MUST make a mismatch detectable in development. Direction affects the+ container basis only when `containerRef` is present.+- **API3 — One configuration vocabulary covers both units.** Add `minSize` and+ `maxSize` with the same `number | string` shape as `defaultSize`. Accepted+ numbers are finite and non-negative. Accepted strings match the complete input:+ a finite non-negative `Npx`, or `N%` from 0% through 100%; partial parses,+ trailing text, other units, negatives, and non-finite values are invalid. The+ deprecated `maxSizePx` alone additionally accepts explicit `Infinity` to+ preserve released usage. Apply FR12's role-specific fallback in development and+ production, warning only in development. Do not add parallel+ `defaultSizePercent`, `minSizePercent`, or `maxSizePercent` props.+- **API4 — Pixel aliases are exactly mutually exclusive with unified bounds.**+ `minSizePx` and `maxSizePx` remain supported but become deprecated. TypeScript+ MUST encode each old/new pair as an exact union, equivalent to:++ ```ts+ type MinSizeConfig =+ | {minSize?: SizeValue; minSizePx?: never}+ | {minSize?: never; minSizePx?: number};+ type MaxSizeConfig =+ | {maxSize?: SizeValue; maxSizePx?: never}+ | {maxSize?: never; maxSizePx?: number};+ ```++ Old-only callers remain unchanged. If JavaScript, an `any` cast, or an object+ spread supplies both, the unified `minSize` or `maxSize` MUST win and development+ MUST emit a clear conflict/deprecation warning naming the ignored alias.++- **API5 — Resolved output and state stay pixels.** `ResizableRegion.size`,+ `onSizeChange`, internal `ResizableProps` geometry, and persisted state remain+ pixel numbers. Existing `width={region.size}`, arithmetic, persistence, and ARIA+ callsites MUST continue to type-check and behave as before. Controlled-collapse+ callbacks keep their released intent-reporting behavior: when the owner rejects+ a requested state change, the rendered size remains owner-controlled even+ though the callback reported the requested transition.+- **API6 — Programmatic resize remains pixels.** `resize(size: number)` retains+ its released signature and selects a clamped pixel size. Percentage strings are+ unsupported and MUST remain a type error; runtime-invalid, negative, or+ non-finite values warn in development and do not replace the last legal pixel+ selection.++### Invalid configuration behavior++| Input | Accepted values | Invalid fallback | Development behavior | Production behavior |+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | ---------------------------------- |+| `defaultSize` | non-negative finite number; exact non-negative finite `Npx`; exact `N%` from 0–100 | 250px, then normal bounds clamp | warn and use fallback | use same fallback without warning |+| `minSize` / `minSizePx` | non-negative finite number; unified prop also accepts exact `Npx` and 0–100 `N%` | 50px | warn and use fallback | use same fallback without warning |+| `maxSize` | non-negative finite number; exact non-negative finite `Npx`; exact `N%` from 0–100 | unbounded `Infinity` | warn and use fallback | use same fallback without warning |+| `maxSizePx` | non-negative finite number or explicit `Infinity` | unbounded `Infinity` | warn for invalid values; do not warn for explicit `Infinity` | use same fallback without warning |+| old/new bound pair supplied together through untyped input | unified value is authoritative | ignore deprecated alias | warn and name the ignored alias | unified value wins without warning |+| resolved minimum above resolved maximum | both values are individually valid | maximum wins | warn and use released clamp order | use same ordering without warning |++A fallback repairs configuration; it is not a new user selection. After+initialization, an invalid raw value never directly replaces persisted or otherwise+legal selected pixel state. Effective fallback bounds may affect that state only+through normal clamping.++### Platform support++- Supported feature/engine floor: every browser supported by Astryx Core with+ `ResizeObserver`; the shared observer remains the one runtime owner for a+ supplied container.+- Before a supplied container has a positive measurement, percentage configuration+ MAY use the released deterministic 1200px basis as a temporary fallback. The+ first valid measurement resolves the percentage default to its final initial+ pixel size and resolves percentage bounds without persisting or announcing the+ temporary fallback.+- Browser evidence: real Chromium MUST verify nested containers, horizontal and+ vertical axes, pointer and keyboard resizing, live basis changes, and the+ unchanged viewport-compatibility and pixel paths. jsdom geometry stubs alone are+ not sufficient.+- SSR: without `containerRef`, percentage defaults preserve the released 1200px+ server basis and client viewport initialization behavior. With `containerRef`,+ the server uses the same temporary 1200px basis until the first client+ measurement. Hydration MAY make one documented correction, but MUST NOT write the+ temporary fallback to storage or fire `onSizeChange` for that correction.++## Current-state impact++Current `main` accepts a percentage string only for `defaultSize`. It resolves+that value once against `window.innerWidth`, with a 1200px server fallback, and+stores the result as pixels. It does not follow later viewport changes. This+released behavior remains the compatibility path when `containerRef` is omitted.++`minSizePx` and `maxSizePx` cannot express percentage bounds. Builders can apply a+CSS percentage maximum, but CSS then clamps paint without clamping hook state.+ResizeHandle publishes the hook's `_size` as `aria-valuenow`, so the separator can+announce a value larger than the panel a person sees.++The proposed `containerRef` passes both gates in current+[AST-002](../AST-002/spec.md): the caller owns which element is the intended+percentage basis, and the hook cannot derive that choice safely. Keeping all+selected state in pixels makes the result predictable under AST-002 FR8 and avoids+an invalid split between selected state, paint, persistence, callbacks, and ARIA+under AST-002 FR10.++The open implementation spike in+[PR #5783](https://github.com/facebook/astryx/pull/5783) demonstrates+container-relative defaults and bounds and supplies browser measurements. It is+evidence for this proposal, not the governing contract. Before implementation is+accepted it must preserve one-time default resolution, pixel-only interaction and+persistence, vertical-axis behavior, multi-region behavior, collapse/expand, and+SSR requirements in this spec.++This change reviews the current owning records:++- `architecture:public-component-api` owns the additive API, stable pixel output,+ deprecation, and migration boundary;+- `family:layout-regions` continues to delegate resize state and interaction to+ useResizable and ResizeHandle while LayoutPanel consumes only resolved size;+- `spec:AST-002` requires the new caller-owned basis to remain understandable,+ predictable, and correct in every supported state;+- shipped Resizable source, tests, and consumer docs remain the evidence for+ current pointer, keyboard, collapse, snap, persistence, handle, and ARIA+ behavior until implementation lands; and+- the draft `component:Resizable` record and Resizable consumer docs change when+ the implementation ships, not in this specification pull request.++### Persistence representation++The persisted representation does not change:++```ts+interface PersistedResizableState {+ size: number | null;+ isCollapsed: boolean | null;+}+```++A percentage default becomes a pixel selection before it is persisted. A+persisted pixel selection wins over `defaultSize` on restore and is clamped by the+currently resolved bounds. A legacy plain `0` remains a collapse marker with no+expanded size, so expand falls back to the configured default; when collapse is+disabled it supplies no usable saved size. Pointer, keyboard, collapse, expand, and+numeric programmatic resize continue to persist pixels. Basis changes never write+a percentage or relative intent.++### Implementation requirements++1. Preserve the current no-ref resolver for valid percentage defaults:+ `window.innerWidth` on the client and 1200px when `window` is unavailable.+2. Parse the complete configuration value, apply FR12's 250px/50px/`Infinity`+ fallbacks before clamping, and warn only in development. Preserve explicit+ `maxSizePx: Infinity` as valid legacy input.+3. Encode each unified/deprecated bound pair as the exact API4 union. At runtime,+ prefer a unified bound over a simultaneously supplied alias and warn in+ development with the ignored alias's name.+4. When `containerRef` is supplied, measure its content box on the configured axis+ and observe it through Astryx's shared ResizeObserver.+5. Resolve a percentage default once into selected pixel state. Re-resolve only+ percentage bounds when their viewport or container basis changes, then clamp+ the selected pixel state so paint, persistence, and ARIA stay synchronized.+6. Preserve the released maximum-wins clamp order when a resolved minimum exceeds+ its maximum, warn in development, and never emit `NaN` or invalid geometry.+7. Keep pointer, keyboard, snap, collapse, expand, callback, persistence, and+ `resize(number)` behavior pixel-based. Do not add a relative mode or widen+ `resize()` to strings. Invalid later configuration must not replace persisted or+ otherwise legal selected state.+8. Preserve all current controlled-collapse and legacy persistence behavior not+ explicitly changed by this spec.+9. If multiple hooks must observe the same container, update the shared observer+ to support independent callbacks and remove only the unmounting callback. Keep+ that reusable prerequisite independently reviewable.+10. Update `component:Resizable`, `useResizable.doc.mjs`, aggregate Resizable docs,+ stories, release notes, and focused tests in the implementation pull request.+11. Keep SideNav's simplified resize configuration pixel-only until a separate+ integration spec or compatibility decision authorizes widening it.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| ---------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |+| FR1, API1 | Focused hook tests plus Chromium geometry | no ref at 1200px viewport; nested container; first positive measurement | no-ref default changes semantics, or supplied ref measures viewport/panel/handle ancestor |+| FR2, API2 | Axis tests and Chromium interaction | horizontal/vertical; LTR/RTL; reversed handle; no-ref vertical compatibility | vertical container sizing reads width, or compatibility stops using `innerWidth` |+| FR3, FR6-FR8 | Interaction and basis-change tests | percentage default before/after drag; viewport/container resize; Arrow, Shift+Arrow, Home, End; collapse/expand | selected size preserves a ratio, basis change scales it, or existing pixel interactions change |+| FR4 | Mixed-bound and invalid-order tests | percent default + pixel minimum; pixel default + percent maximum; percentage min + pixel max; min above max | bounds use different bases, selection scales instead of clamps, maximum does not win, warning is absent, or geometry becomes invalid |+| FR5 | Hook, LayoutPanel, persistence, and ResizeHandle assertions | below/at/above max; basis shrink; controlled collapse intent | effective paint, state, storage, and ARIA diverge, or controlled rejection changes owned state |+| FR9 | Persistence compatibility tests | positive number; legacy zero; legacy object; percentage default; corrupt entry | stored shape changes, a percentage is persisted, or old state changes meaning |+| FR10, API5 | Callback tests | initialization; hydration correction; basis-only re-clamp; pointer/keyboard/programmatic change | callback receives a percentage or reports a non-interaction layout correction |+| FR11 | Multi-region and shared-observer tests | two regions on one container; another hook observing the same node | regions use different bases, selected ratios are introduced, or one subscription removes another |+| FR12 | Production/development parser and state-preservation tests | negative/non-finite number; partial/malformed string; wrong unit; invalid rerender; persisted selection; explicit legacy Infinity | fallback differs by build, warning occurs in production, invalid input replaces legal state, or any path produces `NaN` |+| API3, API4, API6 | Type, runtime validation, and development-warning tests | exact valid strings; old-only aliases; exact-union duplicate rejection; JS/`any`/spread conflicts; `resize('50%')` | duplicate pairs type-check, deprecated alias overrides unified input, warning omits ignored alias, exact parsing is skipped, or resize accepts strings |+| Platform/SSR | Server render, hydration test, and Chromium evidence | no ref; ref not measured; hidden/zero container; first positive measurement | 1200px fallback changes, temporary fallback persists, or correction fires `onSizeChange` |+| Compatibility | Existing Resizable, LayoutPanel, SideNav, and template suites | current pixel-only callsites and no-ref percentage default | existing numeric configuration, percentage fallback, output, interaction, or persistence changes |++### Completion criteria++This spec moves from `accepted` to `shipped` only when:++- no-ref percentage defaults preserve one-time `window.innerWidth` resolution and+ the 1200px SSR fallback without tracking viewport resize;+- supplied-container percentage defaults resolve once against the content-box+ active axis, then remain pixel selections through basis changes and every+ interaction path;+- percentage bounds in both basis modes re-resolve and clamp existing pixel state+ without proportionally scaling it;+- pointer, keyboard, snap, collapse, expand, persistence, callbacks, and+ `resize(number)` preserve released pixel semantics;+- old-only `minSizePx` and `maxSizePx` callers remain unchanged, each old/new+ pair is an exact mutually exclusive TypeScript union, and untyped conflicts+ prefer the unified value with a clear ignored-alias warning;+- exact parsing accepts only non-negative finite numbers, complete `Npx` strings,+ and 0–100 `N%` strings; invalid values use the documented 250px, 50px, or+ `Infinity` fallback in every build without replacing persisted/legal selected+ state, while explicit legacy `maxSizePx: Infinity` remains valid;+- inverted resolved bounds warn in development, deterministically choose the+ maximum, and never produce `NaN` or invalid geometry;+- mixed bounds keep effective state, paint, storage, and separator ARIA aligned,+ while controlled-collapse callbacks preserve released intent reporting;+- single and multi-region subscriptions coexist with every other observer of the+ same element;+- focused tests fail against the old implementation and pass against the new one;+- real Chromium proves both container-basis behavior and unchanged compatibility+ and pixel paths; and+- `component:Resizable` and consumer docs describe the shipped contract in the+ same pull request as the implementation.++## Decision log++### DEC-1 — Percentages configure pixel state; they do not create relative state++**Reference:** `spec:AST-010/DEC-1`+**Decider:** `cixzhang`, `2026-08-31`++Preserve the released no-ref percentage default: resolve once against+`window.innerWidth`, use 1200px when `window` is unavailable, and then behave as+pixels. An optional caller-owned `containerRef` changes the basis for percentage+defaults and bounds to the container's content-box active axis. It does not make a+selected size responsive.++All user interaction, programmatic `resize()`, collapse/expand, callbacks, and+persistence remain pixel-only. Percentage bounds may re-resolve with their basis+and clamp that pixel state. This keeps the API predictable and every represented+state valid under `spec:AST-002` while avoiding a second persistent sizing mode.++Rejected: preserving a percentage ratio after drag or widening `resize()` to+accept percentage strings. Both would change released pixel-based interaction and+add unit-aware state, persistence, callback, and restoration semantics that the+caller did not request.++### DEC-2 — Initial size and bounds share one configuration vocabulary++**Reference:** `spec:AST-010/DEC-2`+**Decider:** `cixzhang`, `2026-08-31`++Add `minSize` and `maxSize` with the same accepted vocabulary as `defaultSize`.+Numbers remain static pixels; strings accept finite non-negative `Npx` or `N%`;+and mixing units across the initial size and bounds is valid. This gives builders+one predictable size vocabulary without parallel percentage props.++Preserve `minSizePx` and `maxSizePx` as deprecated compatibility aliases so+old-only callers behave unchanged. TypeScript encodes each old/new pair as an exact+mutually exclusive union. If untyped JavaScript, an `any` cast, or an object spread+supplies both, the unified `minSize` or `maxSize` wins and development warns with+the ignored alias's name. The explicit migration target must not be silently+overridden by a deprecated value hidden in a spread; this keeps the runtime result+predictable and avoids an ambiguous configuration under `spec:AST-002`.++Invalid inputs use deterministic role-specific fallbacks in every build: 250px for+`defaultSize`, 50px for either minimum spelling, and unbounded `Infinity` for+either maximum spelling. Development additionally warns. Explicit+`maxSizePx: Infinity` remains valid because that legacy form is shipped in an+Astryx template. If a resolved minimum exceeds its maximum, development warns and+the maximum wins under the released clamp order. These rules keep malformed input,+conflicts, and inverted bounds from producing `NaN` or replacing persisted/legal+selected state.++## Open questions++None. Changing the released 1200px server fallback or adding a persistent+relative-size mode requires a separate decision.