An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-105): animated layout; architecture(react-component-runtime): its mechanism (INV12) (#8463)
Cindy Zhang423aaab8f8ed
diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.mdindex d4c3042915..55aa43644f 100644--- a/docs/architecture/react-component-runtime.md+++ b/docs/architecture/react-component-runtime.md@@ -15,7 +15,7 @@ verified_by:packages/core/src/Layer/useLayer.test.tsx,packages/core/src/utils/sharedResizeObserver.test.ts,]-deciding_specs: [spec:AST-086/DEC-2, spec:AST-099/DEC-1]+deciding_specs: [spec:AST-086/DEC-2, spec:AST-099/DEC-1, spec:AST-105/DEC-1]---# React component runtime architecture@@ -35,7 +35,8 @@ deciding_specs: [spec:AST-086/DEC-2, spec:AST-099/DEC-1]"INV6","INV8","INV10",- "INV11"+ "INV11",+ "INV12"]}}@@ -158,6 +159,21 @@ those contracts.does, blurs as FR5 does, applies the height through a functional style onits own elements, and follows INV3 and INV5. The hook follows INV3 andINV5.+- **INV12 — Size changes inside a container have one module.** In+ `@astryxdesign/core`, one internal module produces the size-change glide+ `spec:AST-105` defines. It measures the layout before and after a reported+ change and moves shifted content with a compositor-only translate played+ through the shared rectangle morph (`architecture:layer-runtime` INV15;+ `spec:AST-094` FR5); it never animates height. Its walk visits only the+ following element siblings at each ancestor level up to the area, through+ `parentElement` and `nextElementSibling`, descending only into an element+ with `display: contents`, so its cost grows with depth plus following+ siblings. Changes in one area in the same frame are measured together. A+ component reports a change through an internal, non-exported function that+ takes the `useAnimatedLayout` handle, so the handle stays member-free, and+ each moving element is one the page already renders+ (`architecture:component-style-authoring` INV7). The module follows INV3+ and INV5.## Authoring guidance@@ -279,6 +295,8 @@ contracts.component that announces its own rendered content (INV10).- `spec:AST-099/DEC-1` — one keyboard height for every component, keptinternal and applied through functional styles (INV11).+- `spec:AST-105/DEC-1` — the size-change glide's public shape and behavior+ (INV12).Component, family, API, accessibility, layer, interaction, and style recordsremain authoritative for the other user-facing outcomes delegated above.@@ -292,13 +310,14 @@ observable-behavior predicates require review or runtime evidence. Likewise, afocused test proves only its named behavior and mutation expectation; a greencomponent suite is not blanket conformance with every invariant.-| Invariant | Evidence | Failure signal |-| ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |-| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |-| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |-| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |-| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |-| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |-| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |-| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |+| Invariant | Evidence | Failure signal |+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1–INV2 | Initial-render and interaction tests | Output flashes a known-wrong state, or one action is delayed or repeated through an Effect |+| INV3, INV5 | StrictMode setup/cleanup and dependency-change tests | Duplicate callback, leaked work, stale subscription, or missing resynchronization |+| INV1, INV4, INV6 | Ref attach/null/replacement, DOM-in-state rejection, and old-node cleanup-before-new-attach mutations | A DOM node or collection enters state, old node remains active, cleanup misses replacement, or ref mutation changes semantics silently |+| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber |+| INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced |+| INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |+| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |+| INV11 | Source boundary check plus hook tests across StrictMode replay and unmount | A second keyboard listener or measurement in Core; a consumer reading a CSS custom property on the root or a shared ancestor for the height; an export of the hook; a component outside Core measuring by a rule other than AST-099 FR2, or riding the keyboard; a listener left after unmount; a Core rider driven by JavaScript per frame or by its own transition; or more than one layout read per keyboard change |+| INV12 | Source boundary check plus real-browser tests on a throttled phone profile over a 10-level by 50-sibling tree and two changes in one frame | A per-frame height or layout, a walk past the area or into a subtree other than `display: contents`, an element moved twice for one frame, an added element, or an exported reporting function fails |diff --git a/docs/specs/AST-105-animated-layout/spec.md b/docs/specs/AST-105-animated-layout/spec.mdnew file mode 100644index 0000000000..da6e3b060e--- /dev/null+++ b/docs/specs/AST-105-animated-layout/spec.md@@ -0,0 +1,166 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-105+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-25+phase: accepted+owners: [cixzhang]+affects_architecture: [architecture:react-component-runtime]+affects_families: []+affects_contributing: []+affects_consumer_docs: [useAnimatedLayout, TreeList, Collapsible]+---++# Animated layout system spec++<!-- path-applicability:v1 -->++```json+{+ "paths": ["packages/core/src/**"]+}+```++<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->++## Intent++When something inside an area changes size, the changed element and the+content after it animate together on one shared motion role instead of+jumping. An app opts in once per area; without it, nothing changes.++## Non-goals++- Content outside the area, and content in another document or an iframe.+- How the glide is produced, which `architecture:react-component-runtime`+ INV12 owns.++## Public contract++```tsx+const scrollRef = useRef(null);+const animatedLayout = useAnimatedLayout({containerRef: scrollRef});+<ScrollableArea ref={scrollRef} label="Project">+ <TreeList items={items} animatedLayout={animatedLayout} />+ <p>Notes</p>+</ScrollableArea>;+```++## Requirements++- **FR1 — One hook, one handle, one prop.** `useAnimatedLayout({containerRef})`+ returns an opaque `animatedLayout` handle with no public methods or fields.+ An app passes it to a component whose size changes through that+ component's `animatedLayout` prop, and the component reports each change.+ `containerRef` names the area; ScrollableArea does not register itself, and+ an app passes the ref it already gives ScrollableArea, which reaches the+ native scroll viewport. Each adopting component's record documents its+ `animatedLayout` prop.+- **FR2 — Without a handle, nothing changes.** A component without a handle+ keeps its behavior: the changed element shows its change as its own record+ says, and content after it takes its place at once.+- **FR3 — The content after a change glides within the area.** For any change+ a component holding the handle reports, such as a disclosure opening,+ content loading in, a message appearing, or an item inserted or removed,+ the content after it inside the area moves from its old place to its new+ one instead of jumping, at every ancestor level up to the area and never+ past it. An element moves only when its layout rectangle changed and it is+ in the area's visible part. Which elements move is listed under Coverage.+ Shifted content may mix Astryx components and plain app elements, and none+ of it opts in. Several changes in one area, nested or not, compose: each+ element moves once, by its total change. The area never scrolls because of+ the glide.+- **FR4 — One shared motion.** The changed element plays its own animation,+ entering, exiting, or resizing, and the content after it moves with it.+ Both read the same motion role, `springs.settle` (`spec:AST-094`+ FR4), so the timing is governed centrally, never per component; both start+ on the same frame, and Reduce Motion reaches both through that role, 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+ included: it removes a layout jump that people using a fine pointer see+ too, so it is a named fine-pointer change under `spec:AST-017` FR59, and+ adopting pull requests show fine-pointer evidence before and after.+- **FR6 — Admission.** Two otherwise identical pages differ in whether content+ after a size change glides or jumps, and in which container bounds it,+ which only the caller knows (`spec:AST-002` FR1, FR5). The handle is+ configuration, not a rendered slot; no other API does this job; and it is+ not a visual boolean.+- **FR7 — Documentation.** The hook's documentation reads: "Returns a handle+ to pass to a component whose size changes, such as TreeList or Collapsible.+ When that component changes size, it and the content after it inside+ `containerRef` animate together on one shared motion role. Fixed and stuck+ sticky elements stay put, the glide never scrolls the area, and Reduce+ Motion is respected."++## Coverage++What moves inside an area, each case with its test:++| Case | Behavior | Test |+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |+| Normal-flow block siblings after the changed element, at each ancestor level up to the area | Moves when its rectangle changed | Nested changed element with block siblings at three levels |+| An element with `display: contents` | Has no box; its children are taken in its place | A following `display: contents` wrapper with two children |+| Absolutely positioned or fixed elements | Skipped and take their final place; an absolute child of a moving element rides with it | One of each, plus an absolute badge on a moving row |+| Sticky elements | In flow while unstuck, so moves when its rectangle changed; a stuck element takes its final place | A sticky header above and below its stuck point |+| Floats | Moves when its rectangle changed | A float after the changed element |+| Flex and grid items after the changed element, including wrap and row direction | Moves when its rectangle changed | A wrapping flex row and a row-direction neighbor that does not shift |+| Hidden, `display: none`, or zero-size elements | Skipped | One of each after the changed element |+| Changed elements outside the area's visible part | Take their final place without animation | A long list with changed rows above and below the fold |+| Elements under a scaled or transformed ancestor | Moves by its layout change, corrected for the ancestor's scale | A moving row inside a scaled panel |+| Portals and top-layer content | Never moved | A popover open from a following row |+| Elements already moving | Keep their running motion and add the new move to it | Two changes 100 ms apart |+| Nested areas | Motion stops at the area of the handle the changed component holds; an inner area moves as one unit within an outer one | An area inside an area, changed in the inner one |++Out of coverage, each taking its final place at once:++- content outside the area, and content in another document or an iframe;+- inline text and other non-replaced inline content, which cannot take a+ transform;+- flex or grid items earlier in the DOM that `order` places after the change,+ since only content after the change in the DOM moves;+- text reflowing inside a paragraph beside a float;+- elements the app moves itself with its own transforms;+- an anchored popover tied to a moving element, which layer anchoring keeps+ in place (`architecture:layer-runtime`).++## Current-state impact++- No Core component takes `animatedLayout` yet; TreeList and Collapsible are+ the first adopters, and their docs gain the `animatedLayout` prop.+- Core gains the `useAnimatedLayout` export and its documentation (FR7).+- `architecture:react-component-runtime` INV12 produces the glide.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |+| 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 | starting on different frames or reading different motion, a component-specific timing, 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 |++## Decision log++### DEC-1 — One opt-in handle per area; the content after a change glides++**Reference:** `spec:AST-105/DEC-1`+**Decider:** `cixzhang`, `2026-10-25`++Content that jumps when something above it changes size is disorienting, on+any pointer. An app passes one handle per area to the components whose size+changes, so the opt-in is explicit and composes without wrappers; the+content after a change glides on one shared motion role with the changed+element, inside the area and only where it is visible.++Rejected: wrapping following content in an element, and opting in each+following element.++## Open questions++None.