An open source design system that's fully customizable and agent ready
schema_version: 4 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: shipped owners: [cixzhang] affects_architecture: [architecture:public-component-api] affects_families: [family:layout-regions] affects_contributing: [] affects_consumer_docs: [Resizable]
Structured percentage 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, optionally with one explicit pixel floor or ceiling through
percent(value, {min: pixel(value)}) or
percent(value, {max: pixel(value)}). 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, functions, expressions, or recursive composition,
including
rem,vw,calc(), CSSmin(), and CSSmax(). - 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, andmaxWidthconfiguration. 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 leaf indefaultSizeMUST resolve once againstwindow.innerWidth, or 1200px whenwindowis unavailable, preserving the released fallback. WithcontainerRef, it MUST resolve once against that container's first positive measured content-box active axis. A structured percentage MUST then apply its single pixel floor or ceiling. After 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. WithoutcontainerRef, the compatibility basis remainswindow.innerWidthregardless of direction. - FR3 — Interactions remain pixel-based. Numeric defaults and every result of an atomic or structured 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, atomic
percentage, and structured percentage values across
defaultSize,minSize, andmaxSize. Numeric bounds remain pixels. Percentage values resolve against the same viewport or container basis as FR1; a structured value then applies its one pixel floor or ceiling. Percentage bounds 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 releasedMath.min(max, Math.max(min, size))ordering and guaranteeing finite, non-NaNgeometry. - 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, andaria-valuemaxMUST 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 an atomic or structured percentage default has initialized the selected pixel size, a viewport or container resize MUST NOT re-resolve that default. Percentage bounds MUST re-resolve, apply their optional pixel floor or ceiling, 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 plain0MUST 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.
onSizeChangeMUST 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
Npxstring, an exactN%string from 0% through 100%, or a structuredpercent()value whose percentage is finite and within 0–100 and whose oneminormaxvalue is a finite non-negativePixelWidth. A structured value with neither bound, both bounds, another discriminator, or any invalid number is invalid. An invaliddefaultSizeMUST use 250px before normal bounds clamping; an invalidminSizeMUST use 50px; and an invalidmaxSizeMUST use unboundedInfinity. ExplicitmaxSize: Infinityremains valid. Development MUST warn for every fallback; production MUST use the same fallback without warning. After initialization, an invalid raw value MUST NOT directly replace a persisted or otherwise legal selected pixel size; a fallback-normalized bound may affect that size only through normal clamping.
Public API requirements
API1 —
containerRefopts into a container basis, not a relative mode. Single- and multi-region config MAY acceptcontainerRef?: 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 tohorizontal. Multi-region config's existing top-leveldirectionsupplies 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 whencontainerRefis present.API3 — One explicit Resizable vocabulary covers pixels and bounded percentages. Add the server-safe helper and types:
type ResizablePercentSize = { type: 'percent'; value: number; } & ({min: PixelWidth; max?: never} | {min?: never; max: PixelWidth}); type ResizableSize = number | `${number}px` | `${number}%` | PixelWidth | ResizablePercentSize; function percent( value: number, options: {min: PixelWidth; max?: never} | {min?: never; max: PixelWidth}, ): ResizablePercentSize;minSizeandmaxSizeuseResizableSize.defaultSizekeeps its released broadSizeValueand addsPixelWidth | ResizablePercentSize, preserving every existingnumber | stringcaller while runtime validation remains authoritative. Reuse Table's exactpixel()binding andPixelWidth; do not create a second fixed-size helper. Thepercent()options argument is REQUIRED and carries exactly oneminormaxwhose value is a validPixelWidth. An unbounded percentage keeps the existing canonicalN%spelling;percent(40)is deliberately not a second spelling for'40%'. Numbers, exactNpx, andpixel(value)remain pixels. ExactN%andpercent()percentages are finite and 0–100. Do not acceptproportional()(a sibling weight, not a literal percentage), CSS functions, arithmetic, variables, other units, bothminandmax, or neither bound. Do not add parallel percentage props.Configuration mapping:
333or'333px'→ unchanged;pixel(333)is the canonical structured static form for new compositions;'40%'→ unchanged canonical unbounded percentage;max(40%, 333px)intent →percent(40, {min: pixel(333)});min(10%, 400px)intent →percent(10, {max: pixel(400)}).
API4 — Unified bounds are the only public spellings in 0.6.
minSizeandmaxSizeare the complete bound vocabulary. The deprecatedminSizePxandmaxSizePxaliases were supported through 0.5 and are removed in 0.6. NumericminSizeandmaxSizeretain identical pixel semantics, including explicitmaxSize: Infinity. The 0.6 upgrade codemod rewrites static inline configurations; dynamically assembled configuration must rename the keys.API5 — Resolved output and state stay pixels.
ResizableRegion.size,onSizeChange, internalResizablePropsgeometry, and persisted state remain pixel numbers. Existingwidth={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 |
released SizeValue plus PixelWidth or ResizablePercentSize; structured default resolves once |
250px, then normal bounds clamp | warn and use fallback | use same fallback without warning |
minSize |
ResizableSize; full-match atomic strings; valid pixel(value) or percent(value, {min XOR max: PixelWidth}) |
50px | warn and use fallback | use same fallback without warning |
maxSize |
ResizableSize; full-match atomic strings; valid structured values; explicit Infinity remains unbounded |
unbounded Infinity |
warn and use fallback | use same fallback without warning |
| resolved minimum above resolved maximum | both values are individually valid | maximum wins | warn and use released clamp order | use same ordering without warning |
A fallback repairs configuration; it is not a new user selection. After initialization, an invalid raw value never directly replaces persisted or otherwise 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, basis-dependent configuration MAY use the released deterministic 1200px basis as a temporary fallback. The first valid measurement resolves a basis-dependent default to its final initial pixel size and resolves percentage bounds without persisting or announcing the temporary fallback. A default-only observer MUST be removed after that initial choice; persisted pixel state MUST skip an otherwise unused default measurement.
- Browser evidence: real Chromium MUST verify the three canonical structured calls, wide and narrow initial containers, later basis changes, storage and ARIA, plus the unchanged viewport-compatibility and pixel paths. jsdom geometry stubs alone are not sufficient.
- SSR: without
containerRef, atomic and structured percentage defaults preserve the released 1200px server basis and client initialization behavior. WithcontainerRef, 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 fireonSizeChangefor that correction.
Current-state impact
Current main ships the complete AST-010 model: defaultSize, minSize, and
maxSize accept pixel and percentage forms; containerRef supplies the optional
content-box basis; percentage defaults resolve once; and percentage bounds remain
live while selected state, paint, persistence, callbacks, and separator ARIA stay
in resolved pixels. The no-ref path retains the released window.innerWidth basis
and deterministic 1200px server fallback.
Before the unified bounds shipped, the pixel-only API could not express percentage
constraints. Applying CSS constraints separately could make paint disagree with
hook state and ResizeHandle ARIA. The unified bounds now own both forms. Astryx 0.6
removes the deprecated pixel-only key aliases while preserving numeric pixel
behavior under minSize and maxSize.
The shipped contract remains distributed across its current owners:
architecture:public-component-apiowns stable export and component contract shape;spec:AST-017— Release Compatibility & Versioning system spec owns classification, deprecation/cleanup state, Changesets, and migration evidence; this spec keeps the exact Resizable mapping and its direct transition requirement;family:layout-regionsdelegates resize state and interaction to useResizable and ResizeHandle while LayoutPanel consumes resolved size;spec:AST-002governs the caller-owned container basis and predictable state;- shipped Resizable source, tests, browser evidence, and consumer docs verify pointer, keyboard, collapse, snap, persistence, handle, SSR, and ARIA behavior; and
component:Resizablerecords the component-specific implementation contract.
Persistence representation
The persisted representation does not change:
interface PersistedResizableState {
size: number | null;
isCollapsed: boolean | null;
}
An atomic or structured 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 descriptor or relative intent.
Implementation requirements
- Preserve the current no-ref resolver for every percentage default:
window.innerWidthon the client and 1200px whenwindowis unavailable. - Parse complete atomic strings and validate the complete
percent()descriptor, including its XOR bound shape. Apply FR12's 250px/50px/Infinityfallbacks before clamping and warn only in development. Preserve explicitmaxSize: Infinityas valid unbounded input. - Export
percent,ResizablePercentSize, andResizableSizefrom Resizable; exposepercent, the same Tablepixelbinding,PixelWidth, and the Resizable types from the server-safeResizable/utilssubpath. - Expose only
minSizeandmaxSizefor bounds. Do not retain runtime parsing, conflict warnings, or source types for the removed pixel aliases. - When
containerRefis supplied, measure its content box on the configured axis and observe it through Astryx's shared ResizeObserver. - Resolve a percentage default once into selected pixel state. Remove default-only observation once that selection is final. Re-resolve only percentage bounds when their viewport or container basis changes, apply their one pixel floor or ceiling, then clamp selected pixel state so paint, persistence, and ARIA stay synchronized.
- Refresh a stale cached basis before a newly activated percentage bound can clamp,
and remove default-only observation even when
resize()selected pixels before the first positive measurement. - Preserve the released maximum-wins clamp order when a resolved minimum exceeds
its maximum, warn in development, and never emit
NaNor invalid geometry. - Keep pointer, keyboard, snap, collapse, expand, callback, persistence, and
resize(number)behavior pixel-based. Do not add a relative mode or widenresize()to strings. Invalid later configuration must not replace persisted or otherwise legal selected state. - Preserve all current controlled-collapse and legacy persistence behavior not explicitly changed by this spec.
- 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 | atomic/structured default; no ref at 1200px; wide/narrow initial container; first positive measurement; later resize | default uses the wrong basis, rescales after initialization, or supplied ref measures the wrong element |
| FR2, API2 | Axis tests and Chromium interaction | horizontal/vertical; LTR/RTL; reversed handle; no-ref vertical compatibility | vertical container sizing reads width, or compatibility stops using innerWidth |
| FR3, FR6-FR8 | Interaction and basis-change tests | structured default before/after interaction; viewport/container resize; Arrow, Shift+Arrow, Home, End; collapse/expand | selected state preserves a ratio, basis change rescales it, or existing pixel interactions change |
| FR4 | Structured floor/ceiling, mixed-bound, and invalid-order tests | canonical percent(40, {min: pixel(333)}) / percent(10, {max: pixel(400)}); mixed units; min above max |
descriptor bound is applied in the wrong direction, bounds use different bases, selection scales instead of clamps, or maximum does not win |
| FR5 | Hook, LayoutPanel, persistence, and ResizeHandle assertions | below/at/above max; basis shrink; controlled collapse intent | effective paint, state, storage, and ARIA diverge, or controlled rejection changes owned state |
| FR9 | Persistence compatibility tests | positive number; legacy zero; legacy object; structured default; corrupt entry | stored shape changes, a descriptor is persisted, an unused default measures a basis, or old state changes meaning |
| FR10, API5 | Callback tests | initialization; hydration correction; basis-only re-clamp; pointer/keyboard/programmatic change | callback receives a descriptor or reports a non-interaction layout correction |
| FR11 | Multi-region and shared-observer tests | two regions on one container; another hook observing the same node | regions use different bases, selected ratios are introduced, or one subscription removes another |
| FR12 | Production/development validation and state-preservation tests | malformed strings; missing/both descriptor bounds; invalid percent/pixels; invalid rerender; persisted selection; Infinity |
fallback differs by build, warning occurs in production, invalid input replaces legal state, or any path produces NaN |
| API3, API4, API6 | Type, export, runtime-validation, and codemod tests | required helper options; XOR bound; server-safe subpath; removed alias type errors; resize('50%') |
percent(40) or both bounds type-check, a removed alias still type-checks, server import gains a client directive, or resize accepts non-pixel input |
| Platform/SSR | Server render, hydration test, and Chromium evidence | no ref; ref not measured; hidden/zero container; first positive measurement; resize before layout; later bound activation | temporary basis persists, correction fires onSizeChange, default-only observation leaks, or a newly active bound clamps from a stale cached measurement |
| Compatibility | Existing Resizable, LayoutPanel, SideNav, and template suites | current pixel-only callsites; no-ref atomic percentage default; released broad defaultSize string |
existing numeric/atomic percentage behavior, broad default typing, output, interaction, or persistence changes |
Completion criteria
The shipped contract remains satisfied while:
- no-ref atomic and structured percentage defaults preserve one-time
window.innerWidthresolution and the 1200px SSR fallback without tracking viewport resize; - supplied-container structured defaults resolve once against the first positive content-box active axis, remove default-only observation after that choice, and remain pixel selections through basis changes and every interaction path;
- atomic and structured percentage bounds re-resolve in both basis modes, apply their optional pixel floor or ceiling, and clamp existing pixel state without proportionally scaling it;
percent()requires options and exactly one ofmin/max, carrying a validPixelWidth, in both the type system and runtime validation;percent(40)is not an alias for'40%';Resizable/utilsremains server-safe, re-exports Table's exactpixelbinding andPixelWidth, and exportspercentplus the Resizable types; the root package resolves onepixelsymbol and onepercentsymbol without collision;- pointer, keyboard, snap, collapse, expand, persistence, callbacks, and
resize(number)preserve released pixel semantics; minSizePxandmaxSizePxno longer type-check or receive runtime handling, and the 0.6 upgrade codemod rewrites static inline configurations tominSizeandmaxSize;- exact parsing accepts only non-negative finite numbers, complete
Npxstrings, and 0–100N%strings; descriptor validation rejects a missing/both pixel bound or invalid numeric field. Invalid values use the documented 250px, 50px, orInfinityfallback without replacing persisted/legal selected state, while explicitmaxSize: Infinityremains valid; - inverted resolved bounds warn in development, deterministically choose the
maximum, and never produce
NaNor invalid geometry; - mixed bounds keep effective state, paint, storage, and separator ARIA aligned, while controlled-collapse callbacks preserve released intent reporting;
- default-only subscriptions terminate even after a pre-measurement
resize(), and newly activated percentage bounds measure the current basis before clamping; - 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 the three canonical structured calls across wide/narrow bases, later resizes, storage, and ARIA, plus unchanged compatibility paths; and
component:Resizableand 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 atomic values as defaultSize and the
structured ResizablePercentSize descriptor. Numbers and exact Npx remain
pixels; strings also accept finite 0–100 N%; Table's existing pixel(value) is
the canonical structured static value; percent(value, {min: pixel(value)}) adds
one pixel floor and percent(value, {max: pixel(value)}) adds one pixel ceiling.
Mixing units across the initial size and bounds is valid. This gives builders one
predictable vocabulary without parallel percentage props or duplicate helpers.
minSizePx and maxSizePx remained deprecated compatibility aliases through
0.5. Astryx 0.6 removes them after two stable releases; numeric minSize and
maxSize preserve their pixel meaning, and astryx upgrade rewrites static inline
configurations. Dynamically assembled configuration must rename the keys.
Invalid inputs use deterministic role-specific fallbacks in every build: 250px for
defaultSize, 50px for minSize, and unbounded Infinity for maxSize.
Development additionally warns. Explicit maxSize: Infinity remains valid. If a
resolved minimum exceeds its maximum, development warns and the maximum wins under
the released clamp order. These rules keep malformed input and inverted bounds
from producing NaN or replacing persisted/legal selected state.
DEC-3 — Bounded percentages use one explicit structured helper
Reference: spec:AST-010/DEC-3
Decider: cixzhang, 2026-09-03
Use a Table-style discriminated value created by percent(), not a JavaScript
parser for CSS functions. The descriptor carries a percentage and exactly one
min or max whose value is Table's existing PixelWidth. Its options argument
is required: the existing exact N% string remains the only spelling for an
unbounded percentage.
pixel(333);
percent(40, {min: pixel(333)});
percent(10, {max: pixel(400)});
Reuse Table's exact pixel() binding; do not create another fixed-value helper.
Do not reuse proportional(): it represents relative weight among sibling columns,
not a literal percentage of one measured basis. This fixed shape exposes every
supported combination to TypeScript, remains constant-time to validate and resolve,
and does not imply arbitrary CSS composition. Rejected: recursive CSS min() /
max() strings, optional helper options, descriptors with both bounds, and separate
percentage props.
DEC-4 — Astryx 0.6 removes the deprecated pixel-bound aliases
Reference: spec:AST-010/DEC-4
Decider: cixzhang, 2026-09-07
Remove minSizePx and maxSizePx in the 0.6 breaking window. Their replacements
have shipped across two stable releases, numeric minSize and maxSize preserve
the same pixel behavior, first-party callers migrate in the removal change, and
astryx upgrade rewrites inline configurations. Keeping both vocabularies would
retain type unions, runtime parsing, conflict warnings, tests, and documentation
without adding capability.
Rejected: retaining the aliases indefinitely. They were explicitly temporary and the unified bounds cover every supported pixel case plus percentage constraints.
Open questions
None. Changing the released 1200px server fallback or adding a persistent relative-size mode requires a separate decision.