Skip to content

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.md
index 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 presentation
switch, a lift from the trigger (`architecture:layer-runtime` INV15), or a
handoff 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 1
second 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 an
exception. A change to a component prefers removing or
merging nodes; any added element is justified against this invariant with
measured 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.md
index 75bf4129c6..81a8591a7e 100644
--- a/docs/design/ordered-collection-reordering.md
+++ b/docs/design/ordered-collection-reordering.md
@@ -3,22 +3,35 @@ schema_version: 1
template_version: 1
kind: design
id: design:ordered-collection-reordering
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-26
owners: [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 intent
A 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 questions
diff --git a/docs/specs/AST-103-reorderable/spec.md b/docs/specs/AST-103-reorderable/spec.md
index 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 once
for 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 keeps
every 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 moves
for its axis and a Done control, with the same layer, anchoring, and
theme 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 added
element is the handle, the interactive drag target, with its role. Its grip
is 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 per
collection or on the document, never per row (`spec:AST-094` FR24).
- **FR6 — Stable from the start.** `createReorderable`, its options, and a
collection'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