components/sortable-list/sortable-list.react.tsx

Functions

Imports

It imports components/sortable-list/sortable-list.ts. Imported by components/sortable-list/examples.tsx.

Source

1import { useId, useLayoutEffect, useRef, useState, type KeyboardEvent, type PointerEvent, type ReactNode } from "react";
2import { indexAtPoint, keyTarget, moveId, sortText, startPointerDrag, type Layout, type SortMove } from "./sortable-list.ts";
3
4export { indexAtPoint, keyTarget, moveId, sortText } from "./sortable-list.ts";
5export type { Layout, SortMove } from "./sortable-list.ts";
6
7// The sortable list's HTML contract, rendered from props. The items are the caller's: a
8// finished move calls `onReorder` with the new order, and the list shows the caller's
9// `items` again on the next render, so a host that does not save the order sees it go back.
10// While an item is up (keyboard) or under the pointer, the list holds a draft order of its
11// own. With `name`, every item carries a hidden `name` input with its id, and Move up and
12// Move down are submit buttons (`up=<id>`, `down=<id>`), so a server-rendered list inside a
13// form reorders with no script. Nothing here sets a `style` prop.
14
15export interface SortableListProps<T> {
16  items: readonly T[];
17  getId: (item: T) => string;
18  // The words a person knows the item by: "Move {label}", "Picked up {label}".
19  getLabel: (item: T) => string;
20  // The item's own content, beside the handle and the buttons. No drag handle of its own.
21  renderItem: (item: T, state: { index: number; lifted: boolean }) => ReactNode;
22  onReorder: (order: string[], move: SortMove) => void;
23  layout?: Layout;
24  "aria-label"?: string;
25  "aria-labelledby"?: string;
26  // The form field name for the order; turns the buttons into submit buttons.
27  name?: string;
28  className?: string;
29}
30
31const Grip = () => (
32  <svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false">
33    <circle cx="6" cy="3.5" r="1.25" />
34    <circle cx="10" cy="3.5" r="1.25" />
35    <circle cx="6" cy="8" r="1.25" />
36    <circle cx="10" cy="8" r="1.25" />
37    <circle cx="6" cy="12.5" r="1.25" />
38    <circle cx="10" cy="12.5" r="1.25" />
39  </svg>
40);
41const Arrow = ({ up }: { up: boolean }) => (
42  <svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" focusable="false">
43    <path d={up ? "M8 13V3M3.5 7.5 8 3l4.5 4.5" : "M8 3v10M3.5 8.5 8 13l4.5-4.5"} />
44  </svg>
45);
46
47export function SortableList<T>({ items, getId, getLabel, renderItem, onReorder, layout = "rows", name, className, ...label }: SortableListProps<T>) {
48  const ids = items.map(getId);
49  const byId = new Map(items.map((it) => [getId(it), it]));
50  const [draft, setDraft] = useState<string[] | null>(null);
51  const [lifted, setLifted] = useState<{ id: string; from: number } | null>(null);
52  const [dragging, setDragging] = useState<string | null>(null);
53  const [said, setSaid] = useState("");
54  const order = (draft ?? ids).filter((id) => byId.has(id));
55  const helpId = useId();
56  const handles = useRef(new Map<string, HTMLElement>());
57  const steps = useRef(new Map<string, HTMLButtonElement>());
58  const itemEls = useRef(new Map<string, HTMLElement>());
59  const wantFocus = useRef<{ id: string; part: "handle" | "up" | "down" } | null>(null);
60  const live = useRef<string[]>(order);
61  live.current = order;
62
63  // React may move the focused element when it reorders: put focus back where it was.
64  useLayoutEffect(() => {
65    const w = wantFocus.current;
66    if (!w) return;
67    wantFocus.current = null;
68    const i = live.current.indexOf(w.id);
69    let part = w.part;
70    if (part === "up" && i === 0) part = "down";
71    if (part === "down" && i === live.current.length - 1) part = "up";
72    const el = part === "handle" ? handles.current.get(w.id) : steps.current.get(`${w.id}:${part}`);
73    if (el && document.activeElement !== el) el.focus({ preventScroll: true });
74  });
75
76  const say = (text: string) => setSaid((prev) => (prev === text ? `${text} ` : text));
77  const labelOf = (id: string) => {
78    const it = byId.get(id);
79    return it === undefined ? id : getLabel(it);
80  };
81  const finish = (next: string[], id: string, from: number) => {
82    const to = next.indexOf(id);
83    setDraft(null);
84    if (to !== from) onReorder(next, { id, from, to });
85  };
86
87  const onHandleKey = (e: KeyboardEvent, id: string) => {
88    if (e.ctrlKey || e.metaKey || e.altKey) return;
89    const count = order.length;
90    if (e.key === " " || e.key === "Enter") {
91      e.preventDefault();
92      if (lifted?.id === id) {
93        const to = order.indexOf(id);
94        say(sortText.drop(labelOf(id), to + 1, count, to !== lifted.from));
95        setLifted(null);
96        finish(order, id, lifted.from);
97      } else {
98        const from = ids.indexOf(id);
99        setDraft(null);
100        setLifted({ id, from });
101        say(sortText.lift(labelOf(id), from + 1, count));
102      }
103      return;
104    }
105    if (lifted?.id !== id) return;
106    if (e.key === "Escape") {
107      e.preventDefault();
108      cancel();
109      return;
110    }
111    const to = keyTarget(e.key, order.indexOf(id), count);
112    if (to === null) return;
113    e.preventDefault();
114    setDraft(moveId(order, id, to));
115    say(sortText.over(labelOf(id), to + 1, count));
116    wantFocus.current = { id, part: "handle" };
117  };
118  const cancel = () => {
119    if (!lifted) return;
120    say(sortText.cancel(labelOf(lifted.id), lifted.from + 1, ids.length));
121    setLifted(null);
122    setDraft(null);
123    wantFocus.current = { id: lifted.id, part: "handle" };
124  };
125
126  const step = (id: string, by: -1 | 1) => {
127    const from = ids.indexOf(id);
128    const to = from + by;
129    if (to < 0 || to >= ids.length) return;
130    setLifted(null);
131    const next = moveId(ids, id, to);
132    say(sortText.step(labelOf(id), to + 1, ids.length));
133    wantFocus.current = { id, part: by < 0 ? "up" : "down" };
134    finish(next, id, from);
135  };
136
137  const onPointerDown = (e: PointerEvent, id: string) => {
138    const from = ids.indexOf(id);
139    let current = ids;
140    startPointerDrag(e.nativeEvent, {
141      onStart() {
142        setLifted(null);
143        setDragging(id);
144      },
145      onMove(x, y) {
146        const others = current.filter((k) => k !== id).map((k) => itemEls.current.get(k)!.getBoundingClientRect());
147        const to = indexAtPoint(others, x, y, layout);
148        if (current.indexOf(id) === to) return;
149        current = moveId(current, id, to);
150        setDraft(current);
151      },
152      onDrop() {
153        setDragging(null);
154        const to = current.indexOf(id);
155        say(sortText.drop(labelOf(id), to + 1, ids.length, to !== from));
156        finish(current, id, from);
157      },
158      onCancel() {
159        setDragging(null);
160        setDraft(null);
161        say(sortText.cancel(labelOf(id), from + 1, ids.length));
162      },
163    });
164  };
165
166  return (
167    <>
168      <ol
169        {...label}
170        className={className ? `cap-sortable ${className}` : "cap-sortable"}
171        data-layout={layout}
172        data-sorting={dragging ? "" : undefined}
173        data-cap-ready=""
174        onBlur={(e) => {
175          const to = e.relatedTarget as Node | null;
176          if (lifted && to && !e.currentTarget.contains(to)) cancel();
177        }}
178      >
179        {order.map((id, index) => {
180          const item = byId.get(id)!;
181          const up = lifted?.id === id;
182          const text = labelOf(id);
183          return (
184            <li
185              key={id}
186              ref={(el) => {
187                if (el) itemEls.current.set(id, el);
188                else itemEls.current.delete(id);
189              }}
190              className="cap-sortable-item"
191              data-value={id}
192              data-lifted={up ? "" : undefined}
193              data-dragging={dragging === id ? "" : undefined}
194            >
195              <button
196                ref={(el) => {
197                  if (el) handles.current.set(id, el);
198                  else handles.current.delete(id);
199                }}
200                type="button"
201                className="cap-sortable-handle"
202                aria-pressed={up}
203                aria-describedby={helpId}
204                onKeyDown={(e) => onHandleKey(e, id)}
205                onPointerDown={(e) => onPointerDown(e, id)}
206              >
207                <Grip />
208                <span className="cap-sr-only">Move {text}</span>
209              </button>
210              <div className="cap-sortable-body">{renderItem(item, { index, lifted: up })}</div>
211              <span className="cap-sortable-steps">
212                {(["up", "down"] as const).map((part) => (
213                  <button
214                    key={part}
215                    ref={(el) => {
216                      if (el) steps.current.set(`${id}:${part}`, el);
217                      else steps.current.delete(`${id}:${part}`);
218                    }}
219                    type={name ? "submit" : "button"}
220                    name={name ? part : undefined}
221                    value={name ? id : undefined}
222                    className="cap-btn"
223                    data-variant="quiet"
224                    data-size="sm"
225                    data-icon-only=""
226                    data-cap-part={part}
227                    disabled={part === "up" ? index === 0 : index === order.length - 1}
228                    onClick={(e) => {
229                      e.preventDefault();
230                      step(id, part === "up" ? -1 : 1);
231                    }}
232                  >
233                    <Arrow up={part === "up"} />
234                    <span className="cap-sr-only">
235                      Move {text} {part}
236                    </span>
237                  </button>
238                ))}
239              </span>
240              {name ? <input type="hidden" name={name} value={id} /> : null}
241            </li>
242          );
243        })}
244      </ol>
245      <p className="cap-sr-only" id={helpId}>
246        {sortText.help}
247      </p>
248      <div className="cap-sr-only" role="status" aria-atomic="true" data-cap-part="announce">
249        {said}
250      </div>
251    </>
252  );
253}