An open source design system that's fully customizable and agent ready
TypeScript
design(ordered-collection-reordering): current — insertion line, stable rows, commit on drop (AST-103 reorder mode) (#8625)
Cindy Zhanga1a512d9e30b
diff --git a/docs/architecture/component-style-authoring.md b/docs/architecture/component-style-authoring.mdindex a267e49c07..7ec48755ba 100644--- a/docs/architecture/component-style-authoring.md+++ b/docs/architecture/component-style-authoring.md@@ -137,10 +137,12 @@ not evidence of conformance or violation.only second copy is one transient copy during an exit, a presentationswitch, a lift from the trigger (`architecture:layer-runtime` INV15), or ahandoff between sheets, such as the cross-fade- `design:reduced-motion` DR2 requires; it is made by one Core mechanism that- every layer uses, rather than by each component, and is removed within 1+ `design:reduced-motion` DR2 requires, or one moving preview while a+ reorderable item is dragged (`design:ordered-collection-reordering`); it is+ made by one Core mechanism for its kind, rather than by each component, and is removed within 1second of the transition ending. Until that shared mechanism exists, a- layer's own exit, presentation-switch, or handoff copy is a recorded conformance gap, not an+ layer's own exit, presentation-switch, or handoff copy, or a reorderable+ collection's own drag preview, is a recorded conformance gap, not anexception. A change to a component prefers removing ormerging nodes; any added element is justified against this invariant withmeasured element counts before and after. Two budgets follow from it:@@ -292,13 +294,13 @@ RSC owners retain the delegated decisions above.## Verification-| Invariant | Evidence | Failure signal |-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1 | StyleX capability scan plus component-source mutation | Shipped component styling bypasses the maintained lowering path without another named owner, including component-local raw CSS where that path supports the same result |-| INV2 | Equivalent CSS/JS mutation fixtures and real-browser presentation | JavaScript recreates CSS-resolvable presentation, flashes intermediate state, or disagrees with CSS conditions |-| INV3 | StyleX compile fixtures and independent consumer-property override mutations | Input lowers to invalid CSS or changing one supported property cannot compose without removing another |-| INV4 | Nested unrelated-owner browser fixture across hover, focus-within, active, and disabled states | Outer component state activates an inner component's visual treatment |-| INV5 | Wrapper mutations in default and host-composed render paths | Removing a wrapper changes no semantic, behavior/ref, formatting-context, outside-border-spacing, or required style-bearing DOM boundary |-| INV6 | Pull-request size report against base, with value-table import fixtures | A changed component with no base-against-head gzip JavaScript or CSS figure; a touch-only feature over 2 KB gzip JavaScript or 1 KB gzip CSS per component that is not flagged; importing a component pulls in value-table rows only other components read |-| INV7 | Story element counts (`document.body.querySelectorAll('*').length`) at rest and open under a fine and a coarse pointer, base against head, plus render inspection for duplicated content | An element beyond the component's roles, themable parts, and INV5 wrappers, or a duplicated or hidden twin of content; a state or variant rendered as an extra element; a pseudo-element repeating content; a layer with two presentations mounted outside the transient copy, content mounted twice, more elements under a coarse pointer than a fine one beyond the allowance of `spec:AST-017` FR60, a transient copy made by a component itself, or one left past 1 second; an added element with no measured counts, or a budget exceeded with no recorded owner exception |-| Capability registry | Registry generation against the installed StyleX package | Recorded and installed StyleX versions differ, so capability-dependent cases are untestable |+| Invariant | Evidence | Failure signal |+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1 | StyleX capability scan plus component-source mutation | Shipped component styling bypasses the maintained lowering path without another named owner, including component-local raw CSS where that path supports the same result |+| INV2 | Equivalent CSS/JS mutation fixtures and real-browser presentation | JavaScript recreates CSS-resolvable presentation, flashes intermediate state, or disagrees with CSS conditions |+| INV3 | StyleX compile fixtures and independent consumer-property override mutations | Input lowers to invalid CSS or changing one supported property cannot compose without removing another |+| INV4 | Nested unrelated-owner browser fixture across hover, focus-within, active, and disabled states | Outer component state activates an inner component's visual treatment |+| INV5 | Wrapper mutations in default and host-composed render paths | Removing a wrapper changes no semantic, behavior/ref, formatting-context, outside-border-spacing, or required style-bearing DOM boundary |+| INV6 | Pull-request size report against base, with value-table import fixtures | A changed component with no base-against-head gzip JavaScript or CSS figure; a touch-only feature over 2 KB gzip JavaScript or 1 KB gzip CSS per component that is not flagged; importing a component pulls in value-table rows only other components read |+| INV7 | Story element counts (`document.body.querySelectorAll('*').length`) at rest and open under a fine and a coarse pointer, base against head, plus render inspection for duplicated content | An element beyond the component's roles, themable parts, and INV5 wrappers, or a duplicated or hidden twin of content; a state or variant rendered as an extra element; a pseudo-element repeating content; a layer with two presentations mounted outside the transient copy, content mounted twice, more elements under a coarse pointer than a fine one beyond the allowance of `spec:AST-017` FR60, a transient copy made by a component itself, or one left past 1 second; an added element with no measured counts, or a budget exceeded with no recorded owner exception; a second reorder preview, or one left after the drop |+| Capability registry | Registry generation against the installed StyleX package | Recorded and installed StyleX versions differ, so capability-dependent cases are untestable |diff --git a/docs/design/ordered-collection-reordering.md b/docs/design/ordered-collection-reordering.mdindex 75bf4129c6..81a8591a7e 100644--- a/docs/design/ordered-collection-reordering.md+++ b/docs/design/ordered-collection-reordering.md@@ -3,22 +3,35 @@ schema_version: 1template_version: 1kind: designid: design:ordered-collection-reordering-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-26owners: [ernestt, cixzhang]review_triggers: [visual, interaction, accessibility, motion]-verified_by: []+verified_by:+ [packages/lab/src/__tests__/ReorderGripPinchZoom.a11y.chromium.spec.ts]architecture: [architecture:interaction-modality, architecture:theme-tokens]components: []families: []-deciding_specs: []+deciding_specs: [spec:AST-103]---# Ordered collection reordering design specification+<!-- path-applicability:v1 -->++```json+{+ "paths": [+ "packages/lab/src/reorderStyles.ts",+ "packages/lab/src/ListInput/**",+ "packages/lab/src/TransferList/**"+ ]+}+```+## User intentA person reordering a list or row collection should understand what is moving,@@ -98,21 +111,35 @@ belong to component and family contracts.## Visual references-No normative assets are included in this seed draft. Pointer and keyboard-sequences should be added under-`docs/design/assets/ordered-collection-reordering/` before promotion.+No normative assets are included. Pointer and keyboard sequences belong under+`docs/design/assets/ordered-collection-reordering/`.## Component contract links-No component contract links are asserted in this seed draft. A collection-component should link these requirements only after its input and accessibility-contracts define reordering semantics.+`spec:AST-103` applies this treatment to every reorderable collection, its+keyboard reorder mode included (DR7).++Implementation gap: Lab's ListInput and TransferList draw no insertion line+when reordering by keyboard (DR7); ListInput's keyboard grab mode moves the+rows before the commit (DR3); and both build their own drag preview+(`architecture:component-style-authoring` INV7).## Decision log-No repository design decision has approved this record yet. The draft isolates-the reordering treatment from the broader user-state vocabulary so its distinct-interaction and accessibility requirements can be reviewed independently.+### DEC-1 — Reordering follows this design, not a slide-aside++**Reference:** `design:ordered-collection-reordering/DEC-1`+**Decider:** `cixzhang`, `2026-10-26`++While an item is dragged, the surrounding items stay where they are, the+source stays in place and dimmed, a moving preview follows the pointer, and an+accent insertion line between items marks where it will land; the items+rearrange once, at the drop, and a cancel restores at once. Keyboard+reordering shows the same insertion line. A drop marker, with motion only on+the release, is more accurate for small drop targets than neighbors that move+under the pointer.++Rejected: neighbors sliding aside during the drag.## Open questionsdiff --git a/docs/specs/AST-103-reorderable/spec.md b/docs/specs/AST-103-reorderable/spec.mdindex 75a6f97239..40e9dd855b 100644--- a/docs/specs/AST-103-reorderable/spec.md+++ b/docs/specs/AST-103-reorderable/spec.md@@ -134,7 +134,7 @@ announcements are those of FR3 and FR4, and the tree adds no option.`spec:AST-094`'s values, and a flick still scrolls;- a drag commits once, at the drop (DR4), and `onReorder` is called oncefor it; a cancelled drag calls nothing;- - under Reduce Motion the dragged row still follows the finger or pointer,+ - under Reduce Motion the moving preview still follows the finger or pointer,and the other rows and the drop take their places without travel(`design:reduced-motion` DR1–DR3; a mouse drop follows DR3).- **FR4 — Reorder mode is the one path without a drag.** Each reorderable@@ -167,6 +167,9 @@ announcements are those of FR3 and FR4, and the tree adds no option.- Escape, or activating the handle again, leaves reorder mode and keepsevery move, announcing "Done" with the item's position, such as "Done,Milk at position 3 of 5";+ - while the item is in reorder mode, the same accent insertion line a drag+ shows marks the item's place, moving with each move+ (`design:ordered-collection-reordering` DR7);- while the item is in reorder mode, a hint anchored to it shows the movesfor its axis and a Done control, with the same layer, anchoring, andtheme roles as Core's keyboard hint, and stays until the mode ends; each@@ -191,8 +194,11 @@ announcements are those of FR3 and FR4, and the tree adds no option.- **FR5 — Reordering adds at most one element to a row.** The one addedelement is the handle, the interactive drag target, with its role. Its gripis decoration, drawn by a pseudo-element or a theme-role glyph, not by- elements. The moving row is the row itself, moved in place, not a copy- (`architecture:component-style-authoring` INV7). Reorder listeners are per+ elements. While a row is dragged, the source row stays in place, dimmed, and one+ moving preview follows the pointer (`design:ordered-collection-reordering`):+ the preview is the one transient copy+ `architecture:component-style-authoring` INV7 allows, inert, hidden from+ assistive technology, and removed at the drop. Reorder listeners are percollection or on the document, never per row (`spec:AST-094` FR24).- **FR6 — Stable from the start.** `createReorderable`, its options, and acollection's `reorderable` prop are stable public Core API: no@@ -224,7 +230,7 @@ announcements are those of FR3 and FR4, and the tree adds no option.| FR4 hint | Browser tests with a mouse, a finger, and a keyboard | the hint's axis in vertical, horizontal, and grid collections; each move button and Done; a tap-only reorder; the hint's theme roles | a hint off the keyboard hint's layer, anchoring, or theme roles, buttons that ignore taps or are hidden from assistive technology, a button whose move or announcement differs from its key, focus leaving the handle, or a hint that outlives the mode fails || FR4 two-dimensional | Keyboard and announcement-routing tests on a wrapping card grid, left-to-right and right-to-left | Left and Right across a row end; Up and Down between full rows and into a short last row; announcements with row and column; the hint's four buttons; a resize that changes the column count | a move off reading order, a mirrored direction wrong in right-to-left, a short-row move that is not clamped to its last position, a missing row or column, or a column count read from anything but layout fails || FR4a | Keyboard, mouse, and announcement-routing tests of `start(key)` | `start` from a context-menu item and a toolbar button; a key that is not reorderable, not mounted, or unknown; an object re-created each render; one object on two collections | `start` that does not focus and scroll to the handle, a hint or announcement that differs from the handle's mode, a missing-key call that throws or acts, or a two-collection call without a development warning fails |-| FR5 | Element and listener counts of a list with and without the prop | a row at rest; a row picked up | more than one added element per row, a grip drawn with elements, a per-row listener, or a copy of the moving row, fails |+| FR5 | Element and listener counts of a list with and without the prop | a row at rest; a row picked up; a row dropped | more than one added element per row, a grip drawn with elements, a per-row listener, a second preview, a source that leaves its place, a preview left after the drop, or a preview that assistive technology reaches, fails |## Decision log