components/sortable-list/sortable-list.ts

Functions

Imports

It imports no other module of this repo. Imported by components/sortable-list/sortable-list.react.tsx, components/tree/tree.react.tsx, components/tree/tree.ts.

Source

1// The sortable list: rows or cards a person puts in order, by dragging a handle, by the
2// keyboard (pick up, move, drop) or by the Move up and Move down buttons, which are also the
3// one-pointer way that WCAG 2.5.7 asks for and, as submit buttons, the way with no script.
4// The list owns no storage: every finished move is a `cap:sortable-change` event with the
5// new order, and the host saves it. No framework; the React wrapper uses the same functions.
6
7// ---------------------------------------------------------------------------------------
8// Pure functions.
9
10export interface SortMove {
11  id: string;
12  // Zero-based positions, before and after.
13  from: number;
14  to: number;
15}
16
17// The order with `id` moved to position `to` (clamped to the list).
18export function moveId(order: readonly string[], id: string, to: number): string[] {
19  const from = order.indexOf(id);
20  if (from < 0) return [...order];
21  const out = order.filter((x) => x !== id);
22  out.splice(Math.max(0, Math.min(out.length, to)), 0, id);
23  return out;
24}
25
26export interface Box {
27  top: number;
28  left: number;
29  width: number;
30  height: number;
31}
32
33// Where an item dragged to (x, y) belongs, from the boxes of the other items in their
34// current order. Rows: how many other rows have their middle above the pointer. Cards (a
35// wrapping grid): how many other cards come before the pointer in reading order, that is
36// above its line, or on its line and left of it. Counting the others, never the dragged
37// item, keeps the answer steady as the list rearranges under the pointer.
38export function indexAtPoint(others: readonly Box[], x: number, y: number, layout: Layout = "rows"): number {
39  let n = 0;
40  for (const b of others) {
41    const midY = b.top + b.height / 2;
42    if (layout === "rows") {
43      if (midY < y) n += 1;
44    } else if (b.top + b.height <= y) n += 1;
45    else if (b.top <= y && b.left + b.width / 2 < x) n += 1;
46  }
47  return n;
48}
49
50export type Layout = "rows" | "cards";
51
52// What a polite live region says. Positions are one-based here, as people count.
53export const sortText = {
54  help: "To move an item with the keyboard, press Space or Enter on its handle, move it with the arrow keys, and press Space or Enter to drop it. Escape puts it back.",
55  lift: (label: string, pos: number, count: number) => `Picked up ${label}. Position ${pos} of ${count}. Arrow keys move it, Space drops it, Escape puts it back.`,
56  over: (label: string, pos: number, count: number) => `${label}: position ${pos} of ${count}.`,
57  drop: (label: string, pos: number, count: number, moved: boolean) =>
58    moved ? `Dropped ${label} at position ${pos} of ${count}.` : `Dropped ${label}. It stays at position ${pos} of ${count}.`,
59  cancel: (label: string, pos: number, count: number) => `Put ${label} back at position ${pos} of ${count}.`,
60  step: (label: string, pos: number, count: number) => `Moved ${label} to position ${pos} of ${count}.`,
61};
62
63// The position a key moves a lifted item to, or null for a key that does not move it.
64// In cards every arrow is "previous" or "next" in reading order.
65export function keyTarget(key: string, index: number, count: number): number | null {
66  if (key === "ArrowUp" || key === "ArrowLeft") return Math.max(0, index - 1);
67  if (key === "ArrowDown" || key === "ArrowRight") return Math.min(count - 1, index + 1);
68  if (key === "Home") return 0;
69  if (key === "End") return count - 1;
70  return null;
71}
72
73// ---------------------------------------------------------------------------------------
74// A pointer drag, shared with the tree. It starts once the pointer has moved a few pixels
75// (so a click stays a click), follows the pointer, and ends on release (drop), or on
76// Escape or a cancelled pointer (cancel). After a drag, the click the release makes is
77// swallowed, so a dragged link is not followed.
78
79export interface DragHandlers {
80  onStart(): void;
81  onMove(x: number, y: number): void;
82  onDrop(x: number, y: number): void;
83  onCancel(): void;
84}
85
86export const DRAG_THRESHOLD = 4;
87
88export function startPointerDrag(down: PointerEvent, h: DragHandlers, threshold = DRAG_THRESHOLD): void {
89  if (down.button !== 0) return;
90  const x0 = down.clientX;
91  const y0 = down.clientY;
92  let started = false;
93  const off = () => {
94    window.removeEventListener("pointermove", move, true);
95    window.removeEventListener("pointerup", up, true);
96    window.removeEventListener("pointercancel", cancel, true);
97    window.removeEventListener("keydown", key, true);
98  };
99  const swallowClick = () => {
100    const stop = (e: Event) => {
101      e.preventDefault();
102      e.stopPropagation();
103    };
104    window.addEventListener("click", stop, { capture: true, once: true });
105    setTimeout(() => window.removeEventListener("click", stop, true), 0);
106  };
107  const move = (e: PointerEvent) => {
108    if (!started) {
109      if (Math.hypot(e.clientX - x0, e.clientY - y0) < threshold) return;
110      started = true;
111      h.onStart();
112    }
113    e.preventDefault();
114    h.onMove(e.clientX, e.clientY);
115  };
116  const up = (e: PointerEvent) => {
117    off();
118    if (!started) return;
119    swallowClick();
120    h.onDrop(e.clientX, e.clientY);
121  };
122  const cancel = () => {
123    off();
124    if (started) h.onCancel();
125  };
126  const key = (e: KeyboardEvent) => {
127    if (e.key !== "Escape" || !started) return;
128    e.preventDefault();
129    e.stopPropagation();
130    off();
131    swallowClick();
132    h.onCancel();
133  };
134  window.addEventListener("pointermove", move, true);
135  window.addEventListener("pointerup", up, true);
136  window.addEventListener("pointercancel", cancel, true);
137  window.addEventListener("keydown", key, true);
138}
139
140const boxOf = (el: Element): Box => {
141  const r = el.getBoundingClientRect();
142  return { top: r.top, left: r.left, width: r.width, height: r.height };
143};
144
145// The polite live region for a list: `[data-cap-part="announce"]` beside it, made when missing.
146export function announcer(el: HTMLElement): { region: HTMLElement; made: boolean } {
147  const near = el.parentElement?.querySelector<HTMLElement>(":scope > [data-cap-part='announce']");
148  if (near) return { region: near, made: false };
149  const region = document.createElement("div");
150  region.className = "cap-sr-only";
151  region.dataset.capPart = "announce";
152  region.setAttribute("role", "status");
153  region.setAttribute("aria-atomic", "true");
154  el.after(region);
155  return { region, made: true };
156}
157
158// ---------------------------------------------------------------------------------------
159// The controller, over the HTML contract: `[data-cap="sortable-list"]`.
160
161export interface SortChangeDetail extends SortMove {
162  order: string[];
163  // How it moved: "keyboard", "pointer" or "button".
164  by: "keyboard" | "pointer" | "button";
165}
166
167export interface SortableList {
168  readonly el: HTMLElement;
169  order(): string[];
170  // Moves an item as a finished move: emits cap:sortable-change and announces it.
171  move(id: string, to: number): void;
172  detach(): void;
173}
174
175const itemsOf = (el: HTMLElement) => Array.from(el.querySelectorAll<HTMLElement>(":scope > .cap-sortable-item"));
176const idOf = (item: HTMLElement) => item.dataset.value ?? "";
177const labelOf = (item: HTMLElement) =>
178  (item.dataset.label ?? item.querySelector(".cap-sortable-label")?.textContent ?? item.textContent ?? "").trim().replace(/\s+/g, " ");
179
180// Puts `item` at position `to` by moving its neighbours around it, never the item itself,
181// so the handle or button that has focus keeps it.
182export function placeItem(item: HTMLElement, to: number): void {
183  const list = item.parentElement;
184  if (!list) return;
185  const index = () => itemsOf(list).indexOf(item);
186  for (let guard = 0; index() > to && guard < 1000; guard++) {
187    const prev = item.previousElementSibling;
188    if (!prev) break;
189    item.after(prev);
190  }
191  for (let guard = 0; index() < to && guard < 1000; guard++) {
192    const next = item.nextElementSibling;
193    if (!next) break;
194    item.before(next);
195  }
196}
197
198export function createSortableList(el: HTMLElement): SortableList {
199  const layout: Layout = el.dataset.layout === "cards" ? "cards" : "rows";
200  const { region, made } = announcer(el);
201  const say = (text: string) => {
202    // Cleared first, so the same words twice are still read.
203    region.textContent = "";
204    requestAnimationFrame(() => (region.textContent = text));
205  };
206  const order = () => itemsOf(el).map(idOf);
207  const posOf = (item: HTMLElement) => itemsOf(el).indexOf(item);
208
209  // The step buttons at the ends cannot move further: disabled, and focus moves to the
210  // other button when the one it was on stops working.
211  const syncSteps = () => {
212    // Read before disabling: a browser drops focus from a button the moment it is disabled.
213    const had = document.activeElement;
214    const items = itemsOf(el);
215    items.forEach((item, i) => {
216      const up = item.querySelector<HTMLButtonElement>("[data-cap-part='up']");
217      const down = item.querySelector<HTMLButtonElement>("[data-cap-part='down']");
218      if (up) up.disabled = i === 0;
219      if (down) down.disabled = i === items.length - 1;
220      if (had && had === up && up.disabled) down?.focus();
221      if (had && had === down && down.disabled) up?.focus();
222    });
223  };
224
225  const emit = (item: HTMLElement, from: number, by: SortChangeDetail["by"]) => {
226    const to = posOf(item);
227    if (to === from) return;
228    const detail: SortChangeDetail = { id: idOf(item), from, to, order: order(), by };
229    const ok = el.dispatchEvent(new CustomEvent("cap:sortable-change", { bubbles: true, cancelable: true, detail }));
230    // The host refused it: back where it was.
231    if (!ok) placeItem(item, from);
232    syncSteps();
233  };
234
235  // ---- keyboard: pick up, move, drop
236  let lifted: { item: HTMLElement; from: number } | null = null;
237  const handleOf = (item: HTMLElement) => item.querySelector<HTMLElement>(".cap-sortable-handle");
238  const setLifted = (item: HTMLElement | null) => {
239    for (const i of itemsOf(el)) {
240      const on = i === item;
241      i.toggleAttribute("data-lifted", on);
242      handleOf(i)?.setAttribute("aria-pressed", String(on));
243    }
244  };
245  const lift = (item: HTMLElement) => {
246    lifted = { item, from: posOf(item) };
247    setLifted(item);
248    say(sortText.lift(labelOf(item), lifted.from + 1, itemsOf(el).length));
249  };
250  const drop = () => {
251    if (!lifted) return;
252    const { item, from } = lifted;
253    lifted = null;
254    setLifted(null);
255    const to = posOf(item);
256    say(sortText.drop(labelOf(item), to + 1, itemsOf(el).length, to !== from));
257    emit(item, from, "keyboard");
258  };
259  const cancel = () => {
260    if (!lifted) return;
261    const { item, from } = lifted;
262    lifted = null;
263    setLifted(null);
264    placeItem(item, from);
265    say(sortText.cancel(labelOf(item), from + 1, itemsOf(el).length));
266  };
267
268  const onKey = (e: KeyboardEvent) => {
269    const handle = (e.target as Element | null)?.closest<HTMLElement>(".cap-sortable-handle");
270    const item = handle?.closest<HTMLElement>(".cap-sortable-item");
271    if (!handle || !item || item.parentElement !== el || e.ctrlKey || e.metaKey || e.altKey) return;
272    if (e.key === " " || e.key === "Enter") {
273      e.preventDefault();
274      if (lifted?.item === item) drop();
275      else {
276        cancel();
277        lift(item);
278      }
279      return;
280    }
281    if (lifted?.item !== item) return;
282    if (e.key === "Escape") {
283      e.preventDefault();
284      cancel();
285      return;
286    }
287    const count = itemsOf(el).length;
288    const to = keyTarget(e.key, posOf(item), count);
289    if (to === null) return;
290    e.preventDefault();
291    placeItem(item, to);
292    say(sortText.over(labelOf(item), posOf(item) + 1, count));
293  };
294  // Leaving the list while an item is up puts it back.
295  const onFocusOut = (e: FocusEvent) => {
296    const to = e.relatedTarget as Node | null;
297    if (lifted && to && !el.contains(to)) cancel();
298  };
299
300  // ---- the step buttons
301  const onClick = (e: MouseEvent) => {
302    const b = (e.target as Element | null)?.closest<HTMLButtonElement>("[data-cap-part='up'], [data-cap-part='down']");
303    const item = b?.closest<HTMLElement>(".cap-sortable-item");
304    if (!b || !item || item.parentElement !== el) return;
305    // With script the move happens here; with none the button posts the form.
306    e.preventDefault();
307    if (b.disabled) return;
308    cancel();
309    const from = posOf(item);
310    placeItem(item, from + (b.dataset.capPart === "up" ? -1 : 1));
311    say(sortText.step(labelOf(item), posOf(item) + 1, itemsOf(el).length));
312    emit(item, from, "button");
313  };
314
315  // ---- the pointer
316  const onDown = (e: PointerEvent) => {
317    const handle = (e.target as Element | null)?.closest<HTMLElement>(".cap-sortable-handle");
318    const item = handle?.closest<HTMLElement>(".cap-sortable-item");
319    if (!handle || !item || item.parentElement !== el) return;
320    const from = posOf(item);
321    startPointerDrag(e, {
322      onStart() {
323        cancel();
324        item.setAttribute("data-dragging", "");
325        el.setAttribute("data-sorting", "");
326      },
327      onMove(x, y) {
328        const others = itemsOf(el).filter((i) => i !== item);
329        placeItem(item, indexAtPoint(others.map(boxOf), x, y, layout));
330      },
331      onDrop() {
332        item.removeAttribute("data-dragging");
333        el.removeAttribute("data-sorting");
334        const to = posOf(item);
335        say(sortText.drop(labelOf(item), to + 1, itemsOf(el).length, to !== from));
336        emit(item, from, "pointer");
337      },
338      onCancel() {
339        item.removeAttribute("data-dragging");
340        el.removeAttribute("data-sorting");
341        placeItem(item, from);
342        say(sortText.cancel(labelOf(item), from + 1, itemsOf(el).length));
343      },
344    });
345  };
346
347  el.addEventListener("keydown", onKey);
348  el.addEventListener("focusout", onFocusOut);
349  el.addEventListener("click", onClick);
350  el.addEventListener("pointerdown", onDown);
351  for (const item of itemsOf(el)) {
352    const h = handleOf(item);
353    h?.setAttribute("aria-pressed", "false");
354    // A native drag of the handle (an image, a link in the card) would fight the pointer drag.
355    item.querySelectorAll("a, img").forEach((n) => n.setAttribute("draggable", "false"));
356  }
357  syncSteps();
358
359  return {
360    el,
361    order,
362    move(id, to) {
363      const item = itemsOf(el).find((i) => idOf(i) === id);
364      if (!item) return;
365      const from = posOf(item);
366      placeItem(item, to);
367      say(sortText.step(labelOf(item), posOf(item) + 1, itemsOf(el).length));
368      emit(item, from, "button");
369    },
370    detach() {
371      el.removeEventListener("keydown", onKey);
372      el.removeEventListener("focusout", onFocusOut);
373      el.removeEventListener("click", onClick);
374      el.removeEventListener("pointerdown", onDown);
375      if (made) region.remove();
376      delete el.dataset.capReady;
377    },
378  };
379}
380
381// Attaches to every `[data-cap="sortable-list"]` under root not yet marked `data-cap-ready`.
382// Returns a function that detaches them all.
383export function enhance(root: ParentNode = document): () => void {
384  const undo: Array<() => void> = [];
385  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='sortable-list']:not([data-cap-ready])")) {
386    el.dataset.capReady = "";
387    undo.push(createSortableList(el).detach);
388  }
389  return () => undo.forEach((f) => f());
390}