An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file createReorderable.ts
* @input The reorder's options, and List's reorder machinery
* (List/listReorderEngine.ts: the session, its handle and its touch layer)
* @output `createReorderable`, which makes the object a collection's
* `reorderable` prop takes, whose one public method, `start(key)`, enters
* reorder mode from the app's own UI. And its types: `Reorderable`,
* `ReorderableOptions`, `ReorderMove`
* @position Public Core API, exported from the package root.
* The machinery ships here, on the object: a collection imports only the
* object's type, so one without `reorderable` loads no reorder code
*
* SYNC: When modified, update reorderable/createReorderable.doc.mjs,
* List/listReorderContext.ts and List/List.doc.mjs.
*/
import {
REORDER_ENGINE,
type ListReorderOptions,
type ReorderableInternals,
} from '../List/listReorderContext';
import {listReorderEngine} from '../List/listReorderEngine';
/** A committed move: the item that moved and where it went. */
export interface ReorderMove<
TKey extends string | number = string | number,
TTo = number,
> {
/**
* The moved item's key: its ListItem's `itemKey`. A collection built from
* data takes it through its `idKey`, a field name or a function of the
* item, as Table's does.
*/
readonly key: TKey;
/**
* Its index after the move, in the full order of the collection's items,
* mounted or not. A tree reports `{parent, index}`.
*/
readonly to: TTo;
}
/** What `createReorderable` takes. */
export interface ReorderableOptions<
TKey extends string | number = string | number,
TTo = number,
> {
/**
* Called once per committed move: a drop, or each move in reorder mode.
* Apply it by rendering the items in their new order. A cancelled move calls nothing. The latest function given is the one
* called, so the object may be made on every render.
*/
onReorder: (move: ReorderMove<TKey, TTo>) => void;
/**
* Whether the item with `key` can move. An item it rejects shows no handle
* and cannot be picked up. One at either end of the collection also bounds
* the others, so nothing drops beyond it and a keyboard move into it is
* refused. Every item moves without it.
*/
isReorderable?: (key: TKey) => boolean;
}
declare const reorderableBrand: unique symbol;
/**
* A collection's reorder behavior, made by `createReorderable` and passed as
* its `reorderable` prop. It applies to the whole collection; each item's key
* and `isReorderable` decide which items move.
*/
export interface Reorderable<
TKey extends string | number = string | number,
TTo = number,
> {
/** The keys and places it reports; a type, not a value. */
readonly [reorderableBrand]: {readonly key: TKey; readonly to: TTo};
/**
* Enters reorder mode for the item with `key` from the app's own UI, as
* activating its handle does. A Move item in a context menu or a toolbar
* button can call it. The focus moves to the handle, which scrolls into
* view, and the mode's keys, hint, announcements and exits follow. A key
* that cannot move, or whose item is not mounted, does nothing. It warns in
* development. On an object passed to two collections, it starts the mode
* in the one mounted last.
*/
start(key: TKey): void;
}
/**
* Makes a collection's rows reorderable: pass the result as the collection's
* `reorderable` prop (`<List reorderable={createReorderable({onReorder})}>`),
* with an `itemKey` on each ListItem. Make it once per collection (with
* `useMemo`); one made again on each render still works.
*
* @example
* ```
* const reorderable = useMemo(
* () =>
* createReorderable({
* onReorder: ({key, to}) => setTasks(tasks => moveItem(tasks, key, to)),
* }),
* [],
* );
* <List reorderable={reorderable}>
* {tasks.map(task => (
* <ListItem key={task.id} itemKey={task.id} label={task.title} />
* ))}
* </List>
* ```
*/
export function createReorderable<
TKey extends string | number = string | number,
TTo = number,
>(options: ReorderableOptions<TKey, TTo>): Reorderable<TKey, TTo> {
const internals: ReorderableInternals = {
options: options as unknown as ListReorderOptions,
[REORDER_ENGINE]: listReorderEngine,
start: key => listReorderEngine.start(internals.options, key),
};
return internals as unknown as Reorderable<TKey, TTo>;
}