Skip to content

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.md
index 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 on
its own elements, and follows INV3 and INV5. The hook follows INV3 and
INV5.
+- **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, kept
internal 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 records
remain authoritative for the other user-facing outcomes delegated above.
@@ -292,13 +310,14 @@ observable-behavior predicates require review or runtime evidence. Likewise, a
focused test proves only its named behavior and mutation expectation; a green
component 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.md
new file mode 100644
index 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.