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

.changeset/core-internal-reorder-lab-listinput.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the undocumented `@astryxdesign/core/internal/reorder` entry also gives Lab's `ListInput` List's reorder session for rows that are not ListItems: `useListReorderScope` and `ListReorderScope`. `List` runs its own rows' session through the same session hooks, so its callers see no change. A ListInput string joins Core's message catalog. Internal entries are outside the public API and its compatibility promise.
+
+@vjeux

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}
     />
   );
 }

apps/storybook/stories/ListInputA11y.stories.tsx

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ListInputA11y.stories.tsx
+ * @input ListInput with reordering, where the owner keeps the first record in
+ *   its place
+ * @output A fixture for the Chromium check that a record that stays put keeps
+ *   its Remove in the column of every other record's Remove. It is excluded
+ *   from the visual matrix
+ * @position Browser fixture for ListInput's record columns
+ */
+
+import {useMemo, useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {createReorderable} from '@astryxdesign/core';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {ListInput, type ListInputColumn} from '@astryxdesign/lab';
+
+const meta: Meta = {
+  title: 'A11y/ListInput',
+  tags: ['no-visual'],
+};
+
+export default meta;
+
+interface Guest {
+  id: string;
+  name: string;
+}
+
+const COLUMNS: ListInputColumn<Guest>[] = [
+  {
+    key: 'name',
+    header: 'Name',
+    renderInput: ({item, label, isLabelHidden, isDisabled, updateItem}) => (
+      <TextInput
+        label={label}
+        isLabelHidden={isLabelHidden}
+        value={item.name}
+        onChange={name => updateItem({...item, name}, 'name')}
+        isDisabled={isDisabled}
+      />
+    ),
+  },
+];
+
+export const FixedRecord: StoryObj = {
+  render: function FixedRecordStory() {
+    const [guests, setGuests] = useState<Guest[]>([
+      {id: 'host', name: 'Host'},
+      {id: 'ada', name: 'Ada'},
+      {id: 'grace', name: 'Grace'},
+    ]);
+    const reorderable = useMemo(
+      () =>
+        createReorderable({
+          // The host stays first.
+          isReorderable: (key: string | number) => key !== 'host',
+          onReorder: ({key, to}: {key: string | number; to: number}) =>
+            setGuests(current => {
+              const moved = current.find(guest => guest.id === key);
+              if (moved == null) {
+                return current;
+              }
+              const rest = current.filter(guest => guest !== moved);
+              return [...rest.slice(0, to), moved, ...rest.slice(to)];
+            }),
+        }),
+      [],
+    );
+    return (
+      <ListInput<Guest>
+        label="Guests"
+        value={guests}
+        onChange={setGuests}
+        getItemKey={guest => guest.id}
+        createItem={() => ({id: crypto.randomUUID(), name: ''})}
+        columns={COLUMNS}
+        itemName="guest"
+        reorderable={reorderable}
+      />
+    );
+  },
+};

docs/design/ordered-collection-reordering.md

@@ -24,11 +24,7 @@ deciding_specs: [spec:AST-103]
 
 ```json
 {
-  "paths": [
-    "packages/lab/src/reorderStyles.ts",
-    "packages/lab/src/ListInput/**",
-    "packages/lab/src/TransferList/**"
-  ]
+  "paths": ["packages/lab/src/ListInput/**", "packages/lab/src/TransferList/**"]
 }
 ```
 
@@ -119,11 +115,6 @@ No normative assets are included. Pointer and keyboard sequences belong under
 `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
 
 ### DEC-1 — Reordering follows this design, not a slide-aside

packages/core/locales/en.json

@@ -695,6 +695,10 @@
     "defaultMessage": "Reorder {itemName} {position, number}",
     "description": "Accessible label on the drag-handle button that reorders one record in a lab ListInput. `{itemName}` is the consumer's singular noun for one record; `{position}` is its 1-based row number (e.g. \"Reorder guest 2\")."
   },
+  "@astryx.listInput.itemName": {
+    "defaultMessage": "{itemName} {position, number}",
+    "description": "The name of one record in a lab ListInput, which its reorder handle (\"Reorder guest 2\") and the reorder announcements use. `{itemName}` is the consumer's singular noun for one record; `{position}` is its 1-based row number (e.g. \"guest 2\")."
+  },
   "@astryx.listInput.fieldLabelWithPosition": {
     "defaultMessage": "{header}, {itemName} {position, number} of {total, number}",
     "description": "Accessible name for a field inside a lab ListInput row after the first row, disambiguating repeated column labels. `{header}` is the column's own label (e.g. \"Name\"); `{itemName}` is the consumer's singular noun for one record; `{position}`/`{total}` are the row's 1-based index and the total row count (e.g. \"Name, guest 2 of 3\")."

packages/core/src/List/List.tsx

@@ -11,10 +11,11 @@
  *   types
  * @position Core implementation. Consumed by index.ts, tested by List.test.tsx
  *
- * `animatedLayout` runs the layout updates (List/listLayoutUpdates.ts);
+ * `animatedLayout` runs the layout updates (List/listLayoutUpdates.ts).
  * `reorderable` runs the reorder session after them. List imports only the
- * reorderable object's type and its key (List/listReorderContext.ts). It
- * hands the reorder to its rows through ListContext. The session, its handle
+ * reorderable object's type and List/listReorderContext.ts, which holds the
+ * object's key and the session hooks. It hands the reorder to its rows
+ * through ListContext. The session, its handle
  * and its listeners come with the object (reorderable/createReorderable.ts).
  * So a List without it loads no reorder code.
  *
@@ -44,11 +45,10 @@ import {LayoutChangeSnapshot} from '../motion/LayoutChangeSnapshot';
 import type {AnimatedLayout} from '../motion/animatedLayout';
 import {themeProps} from '../utils/themeProps';
 import {useDevWarning} from '../hooks/useDevWarning';
-import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {
-  REORDER_ENGINE,
+  useReorderCommit,
+  useReorderSession,
   type ListReorderOptions,
-  type ReorderableInternals,
 } from './listReorderContext';
 
 export {
@@ -346,16 +346,12 @@ export function List({
 }: ListProps) {
   const headerId = useId();
   const listRef = useRef<HTMLUListElement & HTMLOListElement>(null);
-  // The reorder's machinery comes with the object. The
-  // object may be made on every render: the session lasts as long as its
-  // machinery, and reads the object's latest callbacks.
-  const reorder = reorderable as ReorderableInternals | undefined;
-  const reorderEngine = reorder?.[REORDER_ENGINE];
-  const reorderOptions = reorder?.options;
-  // The handles' instructions take the header's id with a suffix.
-  const reorderSession = useMemo(
-    () => reorderEngine?.createSession(() => listRef.current, `${headerId}h`),
-    [reorderEngine, headerId],
+  // The reorder's machinery comes with the object. The handles'
+  // instructions take the header's id with a suffix.
+  const {session: reorderSession, options: reorderOptions} = useReorderSession(
+    reorderable,
+    () => listRef.current,
+    `${headerId}h`,
   );
   const measureRows = useListLayoutUpdates(listRef, animatedLayout);
   // A drag's or a reorder-mode move's commits are the reorder's to move, so
@@ -365,11 +361,8 @@ export function List({
       measureRows();
     }
   }, [measureRows, reorderSession]);
-  // Syncs the reorder session, which lives outside React, after each commit.
-  // It runs after the layout updates, so a drop's commit is the reorder's.
-  useIsomorphicLayoutEffect(() => {
-    reorderSession?.commit();
-  });
+  // After the layout updates, so a drop's commit is the reorder's.
+  useReorderCommit(reorderSession);
   const mergedRef = useMergedRefs(
     listRef,
     ref as React.Ref<HTMLUListElement & HTMLOListElement>,

packages/core/src/List/ListReorderScope.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ListReorderScope.tsx
+ * @input A reorderable object made by createReorderable, and the element
+ *   whose children are the rows
+ * @output `useListReorderScope`, a reorder session over rows that are not
+ *   ListItems. `ListReorderScope` gives those rows the session as a
+ *   reorderable List gives its own: `ListReorderHandle` inside a row finds it
+ * @position Internal to core; Lab's ListInput reaches it through
+ *   `@astryxdesign/core/internal/reorder`. It runs the same engine a
+ *   reorderable List runs, List/listReorderEngine.tsx, which ships with the
+ *   object. So the rows drag, take keys and announce their moves alike.
+ *
+ * SYNC: When modified, update List/List.tsx, which runs the same session for
+ * its own rows through the hooks in List/listReorderContext.ts.
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import type {Reorderable} from '../reorderable/createReorderable';
+import {ListContext, type ListContextValue} from './ListContext';
+import {
+  useReorderCommit,
+  useReorderSession,
+  type ListReorderContextValue,
+} from './listReorderContext';
+
+/**
+ * The reorder session over the children of the element `getList` returns,
+ * run by `reorderable`'s engine, or null without an object. `hintId` names
+ * the handles' instructions, which `ListReorderScope` renders. The object may
+ * be made on every render: the session lasts as long as its engine and reads
+ * the object's latest callbacks.
+ */
+export function useListReorderScope(
+  reorderable: Reorderable | undefined,
+  getList: () => HTMLElement | null,
+  hintId: string,
+): ListReorderContextValue | null {
+  const {session, options} = useReorderSession(reorderable, getList, hintId);
+  useReorderCommit(session);
+  return useMemo(
+    () => (session == null || options == null ? null : {session, options}),
+    [session, options],
+  );
+}
+
+/**
+ * Gives the rows inside it the reorder session, so `ListReorderHandle` in a
+ * row drags that row, and renders the session's instructions and reorder-mode
+ * hint. Without a session it renders its children alone.
+ */
+export function ListReorderScope({
+  reorder,
+  children,
+}: {
+  reorder: ListReorderContextValue | null;
+  children: ReactNode;
+}): ReactNode {
+  // Only `reorder` is read inside a reorder scope; the rest is a List's
+  // defaults for any row that reads it.
+  const value = useMemo<ListContextValue | null>(
+    () =>
+      reorder == null
+        ? null
+        : {
+            density: 'balanced',
+            hasDividers: false,
+            edge: 'padded',
+            listStyle: 'none',
+            reorder,
+          },
+    [reorder],
+  );
+  if (reorder == null || value == null) {
+    return children;
+  }
+  return (
+    <ListContext value={value}>
+      {children}
+      <reorder.session.Host reorder={reorder} />
+    </ListContext>
+  );
+}