feat(lab): ListInput reorders through core's createReorderable

.changeset/cli-hook-docs-create.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] `astryx` lists a `create…` factory documented as a hook, such as `createReorderable`, with the hooks.
+
+@vjeux

.changeset/list-reorder-mode-hint.md

@@ -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

.changeset/list-reorderable.md

@@ -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

apps/storybook/stories/List.stories.tsx

@@ -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';
@@ -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,
@@ -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 ' +
+          '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.',
+      },
+    },
+  },
+};

apps/storybook/stories/ListInput.stories.tsx

@@ -9,11 +9,18 @@
 
 import * as stylex from '@stylexjs/stylex';
 import type {Meta, StoryObj} from '@storybook/react';
-import {useCallback, useMemo, useState} from 'react';
+import {
+  useCallback,
+  useMemo,
+  useState,
+  type Dispatch,
+  type SetStateAction,
+} from 'react';
 import type {ISODateString} from '@astryxdesign/core/Calendar';
 import {DateInput} from '@astryxdesign/core/DateInput';
 import {NumberInput} from '@astryxdesign/core/NumberInput';
 import {Selector} from '@astryxdesign/core/Selector';
+import {createReorderable} from '@astryxdesign/core';
 import {pixel, proportional} from '@astryxdesign/core/Table';
 import {Text} from '@astryxdesign/core/Text';
 import {TextInput} from '@astryxdesign/core/TextInput';
@@ -189,8 +196,33 @@ function createTagColumns(
   ];
 }
 
+/**
+ * The owner's reorder: each move ListInput reports lands in the records,
+ * found by `getItemKey`'s key.
+ */
+function useRecordReorder<T extends {id: string}>(
+  setRecords: Dispatch<SetStateAction<T[]>>,
+) {
+  return useMemo(
+    () =>
+      createReorderable({
+        onReorder: ({key, to}: {key: string | number; to: number}) =>
+          setRecords(current => {
+            const moved = current.find(record => record.id === key);
+            if (moved == null) {
+              return current;
+            }
+            const rest = current.filter(record => record !== moved);
+            return [...rest.slice(0, to), moved, ...rest.slice(to)];
+          }),
+      }),
+    [setRecords],
+  );
+}
+
 function TagOptionsExample({isReorderable}: {isReorderable?: boolean}) {
   const [tags, setTags] = useState(INITIAL_TAGS);
+  const reorderable = useRecordReorder(setTags);
   const {isFieldTouched, markFieldTouched} = useTouchedFields();
   const columns = useMemo(
     () => createTagColumns(markFieldTouched),
@@ -235,7 +267,7 @@ function TagOptionsExample({isReorderable}: {isReorderable?: boolean}) {
           ? {type: 'error', message: 'Enter a label.'}
           : undefined
       }
-      isReorderable={isReorderable || undefined}
+      reorderable={isReorderable ? reorderable : undefined}
     />
   );
 }
@@ -800,6 +832,7 @@ const INITIAL_TRIP_LEGS: TripLeg[] = [
 
 function ResponsiveItineraryExample() {
   const [legs, setLegs] = useState(INITIAL_TRIP_LEGS);
+  const reorderable = useRecordReorder(setLegs);
   const {isFieldTouched, markFieldTouched} = useTouchedFields();
   const columns = useMemo<ListInputColumn<TripLeg>[]>(
     () => [
@@ -906,7 +939,7 @@ function ResponsiveItineraryExample() {
           }
           return undefined;
         }}
-        isReorderable
+        reorderable={reorderable}
         isRequired
       />
     </div>
@@ -940,6 +973,7 @@ function StaticTagsExample({
   status?: React.ComponentProps<typeof ListInput<TagOption>>['status'];
 }) {
   const [tags, setTags] = useState(INITIAL_TAGS.slice(0, 3));
+  const reorderable = useRecordReorder(setTags);
   const columns = useMemo(() => createTagColumns(() => {}), []);
 
   return (
@@ -955,7 +989,7 @@ function StaticTagsExample({
       isDisabled={isDisabled}
       isLoading={isLoading}
       status={status}
-      isReorderable
+      reorderable={reorderable}
     />
   );
 }
@@ -1025,6 +1059,7 @@ const STRESS_TAGS: TagOption[] = Array.from({length: 25}, (_, index) => ({
 
 function StressExample() {
   const [tags, setTags] = useState(STRESS_TAGS);
+  const reorderable = useRecordReorder(setTags);
   const columns = useMemo(() => createTagColumns(() => {}), []);
 
   return (
@@ -1037,7 +1072,7 @@ function StressExample() {
       createItem={() => ({id: crypto.randomUUID(), color: 'blue', label: ''})}
       columns={columns}
       itemName="tag"
-      isReorderable
+      reorderable={reorderable}
     />
   );
 }