Skip to content
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
cad762b
feat(core): createReorderable makes List rows reorderable
vjeux Oct 26, 2026
d0c1590
feat(List): reorder mode's hint, its moves and Done as buttons
vjeux Oct 26, 2026
6ff3d0b
fix(List): a move that renames a row keeps reorder mode
vjeux Nov 5, 2026
66fc409
fix(cli): a create* factory with its own hook lists beside that hook
vjeux Nov 6, 2026
32d137f
docs(List): split comment sentences over 25 words
vjeux Nov 6, 2026
13c6534
fix(List): a finger held on a reorder handle selects no text
vjeux Nov 6, 2026
ca8a76b
fix(List): a drag crossing rows reads no layout
vjeux Nov 6, 2026
8de33bf
fix(List): the reorder imports the touch hit area from internal
vjeux Nov 7, 2026
e5f5e02
fix(List): the reorder finds its scroller through core's shared walk
vjeux Nov 7, 2026
77fb567
fix(List): a dragged row's preview and line keep its inline start in RTL
vjeux Nov 7, 2026
1baf07c
fix(List): picking a row up lays the page out once
vjeux Nov 7, 2026
28b44c3
spec(AST-103): a held drag near a scroll edge scrolls toward it
vjeux Nov 7, 2026
0abe4b2
fix(List): a dragged row's preview joins no form or radio group
vjeux Nov 7, 2026
4b907b5
fix(List): a scroll during a drag keeps the drop under the pointer
vjeux Nov 7, 2026
c89aa9c
spec(react-component-runtime): INV18 allows the reorder's scroll read
vjeux Nov 7, 2026
6beee21
chore(lint): the provenance baseline drops List's two removed citations
vjeux Nov 8, 2026
05c5150
Merge branch 'main' into uikit/c13-list-reorder
cixzhang Nov 8, 2026
9a497c6
fix(List): a drop or key move reads its rows once, before it writes
vjeux Nov 8, 2026
3384ec6
docs(List): a key move's first glides cost a style pass per row
vjeux Nov 8, 2026
7a333bd
Merge main into createReorderable's List reorder
vjeux Nov 8, 2026
4678530
docs(motion): the reorder measurements name no batch label
vjeux Nov 8, 2026
ed28397
Merge branch 'main' into uikit/c13-list-reorder
cixzhang Nov 8, 2026
ff96b6f
Merge main into createReorderable's List reorder
vjeux Nov 8, 2026
92365e4
refactor(List): the reorder warns once through createDevWarnings
vjeux Nov 8, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/cli-hook-docs-create.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[feat] `astryx` lists a `create…` factory documented as a hook, such as `createReorderable`, with the hooks.

@vjeux
7 changes: 7 additions & 0 deletions .changeset/list-reorder-mode-hint.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[feat] While a reorderable `List` row is in reorder mode, a hint anchored to its handle, in the keyboard hint's layer and theme roles, shows the moves and Done. Each is a button that does what its key does and leaves the focus on the handle, so a row can be reordered by taps alone: the handle, the moves, then Done.

@vjeux
7 changes: 7 additions & 0 deletions .changeset/list-reorderable.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[feat] `createReorderable({onReorder, isReorderable})` makes a collection's reorder behavior, and `List` takes it as `reorderable`: each `ListItem` with an `itemKey` gets a reorder handle at its end, and each committed move calls `onReorder({key, to})` once, with the row's key and its index after the move. On a touch screen a finger held still on a handle picks up its row the way an iOS table's reorder control does (a flick on it still scrolls): the row stays in its place, dimmed, while a copy of it follows the finger and an accent line marks where it would land; the other rows stay still, the page scrolls near the edges, and on release the rows rearrange, gliding to their new places. A pen held on a handle picks up its row the same way where the primary pointer is coarse. A mouse, or a pen where the primary pointer is fine, drags a handle at once with the same copy and line, and rows take their places without motion; a cancelled drag puts everything back at once. Without a drag, a click, Space or Enter on a handle turns on reorder mode for its row: the insertion line marks the row's place, each arrow key moves it a place at once, announced with its place and neighbours, and Escape or another activation ends the mode, keeping the moves. The object's `start(key)` enters the same mode from the app's own UI, such as a row's context menu. A List without `reorderable` loads none of the reorder code.

@vjeux
179 changes: 178 additions & 1 deletion apps/storybook/stories/List.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,11 @@
* @position Storybook demonstrations for List consumers
*/

import {useEffect, useRef, useState} from 'react';
import {useEffect, useMemo, useRef, useState} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {Meta, StoryObj} from '@storybook/react';
import {List, ListItem} from '@astryxdesign/core/List';
import {createReorderable} from '@astryxdesign/core';
import {Avatar} from '@astryxdesign/core/Avatar';
import {Badge} from '@astryxdesign/core/Badge';
import {Button} from '@astryxdesign/core/Button';
Expand All @@ -21,6 +22,7 @@ import {Heading, Text} from '@astryxdesign/core/Text';
import {VStack} from '@astryxdesign/core/Layout';
import {useAnimatedLayout} from '@astryxdesign/core/hooks';
import {rtlStyles} from '@astryxdesign/core/utils';
import {ContextMenu} from '@astryxdesign/core/ContextMenu';
import {
Cog6ToothIcon,
BellIcon,
Expand Down Expand Up @@ -914,3 +916,178 @@ export const AnimatedChangesSwipe: Story = {
},
},
};

function moveKey(
rows: ReadonlyArray<string>,
key: unknown,
to: number,
): string[] {
const next = rows.filter(row => row !== key);
next.splice(to, 0, key as string);
return next;
}

function ReorderDemo({
initial,
pinned = [],
edge,
}: {
initial: ReadonlyArray<string>;
pinned?: ReadonlyArray<string>;
edge?: 'padded' | 'flush';
}) {
const [rows, setRows] = useState(initial);
return (
<List
hasDividers
edge={edge}
reorderable={createReorderable({
onReorder: ({key, to}) => setRows(current => moveKey(current, key, to)),
isReorderable: key => !pinned.includes(key as string),
})}>
{rows.map(label => (
<ListItem key={label} itemKey={label} label={label} />
))}
</List>
);
}

export const Reorderable: Story = {
render: () => (
<ReorderDemo
initial={['Inbox', 'Sent', 'Drafts', 'Archive', 'Spam', 'Trash']}
/>
),
parameters: {
docs: {
description: {
story:
'With `reorderable` (from `createReorderable`), each row with an ' +
'`itemKey` gets a reorder handle. On a touch screen, hold a handle ' +
'for a moment, then drag: the row dims in place, a copy follows ' +
'your finger and a line marks where it will land, and the rows ' +
'rearrange on release. A mouse drags a handle at once, the same ' +
'way. Or activate a handle (click it, or press Space ' +
'or Enter) to turn on reorder mode for its row: each arrow key, or ' +
'each move in the hint below the handle, moves it a place, and ' +
'Escape or Done ends the mode.',
},
},
},
};

export const ReorderFlush: Story = {
render: () => (
<ReorderDemo
initial={['Inbox', 'Sent', 'Drafts', 'Archive']}
edge="flush"
/>
),
parameters: {
docs: {
description: {
story:
'With `edge="flush"` the rows have no side padding, so each ' +
"reorder handle ends at the row's edge, inside the list.",
},
},
},
};

export const ReorderWithPinnedRows: Story = {
render: () => (
<ReorderDemo
initial={['Favorites', 'Inbox', 'Sent', 'All mail', 'Drafts', 'Spam']}
pinned={['Favorites', 'All mail']}
/>
),
parameters: {
docs: {
description: {
story:
'A row the object’s `isReorderable` rejects has no handle. At an ' +
'end of the list it also bounds the others (nothing drops above ' +
'Favorites); in the middle, other rows move past it.',
},
},
},
};

function ReorderFromYourUIDemo() {
const [rows, setRows] = useState([
'Inbox',
'Sent',
'Drafts',
'Archive',
'Spam',
'Trash',
]);
const [selected, setSelected] = useState('Sent');
const reorderable = useMemo(
() =>
createReorderable({
onReorder: ({key, to}) => setRows(current => moveKey(current, key, to)),
}),
[],
);
return (
<VStack gap={2}>
<Button
label={`Move ${selected}`}
onClick={() => reorderable.start(selected)}
/>
<ContextMenu
label="Row actions"
items={[
{
label: `Move ${selected}`,
onClick: () => reorderable.start(selected),
},
]}>
<List hasDividers reorderable={reorderable}>
{rows.map(label => (
<ListItem
key={label}
itemKey={label}
label={label}
isSelected={label === selected}
onClick={() => setSelected(label)}
/>
))}
</List>
</ContextMenu>
</VStack>
);
}

export const ReorderFromYourUI: Story = {
render: () => <ReorderFromYourUIDemo />,
parameters: {
docs: {
description: {
story:
'The object’s `start(key)` turns on reorder mode for a row from ' +
'your own UI, here a button and the list’s context menu: the ' +
'focus moves to the row’s handle, and its arrow keys, hint and ' +
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
'Done work as they do from the handle.',
},
},
},
};

export const ReorderLongList: Story = {
render: () => (
<ReorderDemo
initial={Array.from({length: 30}, (_, index) => `Item ${index + 1}`)}
/>
),
parameters: {
docs: {
description: {
story:
'Dragging a row near the top or bottom of the screen scrolls the ' +
'page, faster the further past the edge the row goes.',
},
},
},
};
10 changes: 7 additions & 3 deletions docs/architecture/react-component-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -372,9 +372,12 @@ those contracts.
measuring in JS, as `architecture:component-style-authoring` INV2 prefers. A
per-frame, scroll or resize path reads no layout, except a read a current
clause requires there: `architecture:layer-runtime`'s placement re-reads,
INV11's keyboard read, and INV12's and `component:Resizable` FR8's
before-and-after measurement. Each such read happens in one batched
measurement pass per change, never interleaved with writes. A read is one
INV11's keyboard read, INV12's and `component:Resizable` FR8's
before-and-after measurement, and the reorder drag's scroll read: during a
reorder drag, the engine reads its scroller's scroll offset once per frame
after a scroll it didn't cause, before its writes. Each such read happens
in one batched measurement pass per change, never interleaved with writes.
A read is one
measurement pass: a remaining read names its reason in a comment and happens
once per change, not per frame, or as the before-and-after pair a current
clause requires. INV11's keyboard hook, which makes at most one layout read
Expand Down Expand Up @@ -539,3 +542,4 @@ component suite is not blanket conformance with every invariant.
| INV16 | Review of each Core component that handles a concern Core owns in a shared hook or utility | A Core component that keeps its own effect, listener, or tracker for that concern fails, whether or not it also calls the hook or utility |
| INV16 (slot presence) | `no-nullish-jsx-guard` strict lint over Core and RichText, with no baseline, and `no-truthy-jsx-guard` strict lint over Core, with no baseline; both catch inline guards only, so review also checks for a presence test hoisted into a variable, converted (`!!value`, `Boolean(value)`), made by an early return or a `??` default, or passed through a prop spread, which the lints pass; empty-slot tests that pass `''`, `false`, `true`, and `null` and compare with an omitted slot, plus `0` as content, in Item, MetadataList, ChatSystemMessage, TreeList, TopNavMegaMenu, RichTextEditor, and RichTextEditorToolbar | A slot given `''`, `true`, or `false` draws a wrapper, lane, border, or separator that an omitted slot does not, an element loses the name it has without the slot, `0` does not render, or a new bare nullish or truthiness presence test, inline or hoisted, a truthiness guard past the baseline, a baseline entry added, or a hand-written copy of the check lands |
| INV18 | Review of every added read that forces layout: `getBoundingClientRect`, `getClientRects`, `offset*`, `client*`, `scroll*` (`scrollTop`, `scrollHeight`, and the rest), `inner*` and `outer*`, `visualViewport` geometry, and `getComputedStyle` (evidence gap: no automated finding yet) | A layout read in a per-frame, scroll or resize path that no current clause requires there, a read interleaved with writes, a read without a comment that names its reason, more than one measurement pass per change beyond the before-and-after pair a current clause requires, or JavaScript measurement where CSS placement serves |
| INV18 reorder | Browser tests of a mouse drag in a reorderable List while a wheel scrolls its scroller: one checks the preview, the drop line and the drop, and one traces layout and counts the offset reads | A wheel scroll mid-drag that leaves the drop line or the preview off the pointer, a drop away from the pointer, a layout the read forces, or more than one read in a scrolled frame |
Loading
Loading