Skip to content

Build your personal knowledge base with Trilium Notes

29.7 KB
Raw Blame
import "./SortableCard.css";

import clsx from "clsx";
import { ComponentChildren } from "preact";
import { flushSync } from "preact/compat";
import {
    useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState
} from "preact/hooks";

import { t } from "../../services/i18n";
import { Card, type CardProps, ItemCreationRow, type ItemCreationRowButton } from "./Card";
import { createEdgeScroller, type Insets, type ScrollTarget } from "./edge_scroll";
import { useFlip } from "./flip";
import Icon from "./Icon";

/** How many creation buttons fit at the foot of a card before each is too narrow to read. */
const MAX_CREATION_BUTTONS = 3;

/**
 * How long a touch must stay still before the drag starts. A touch that moves first scrolls the
 * page instead. Matches the board's cards.
 */
const TOUCH_HOLD_MS = 400;

/** How far the touch can move within `TOUCH_HOLD_MS` and still count as still. */
const TOUCH_SLACK_PX = 8;

/**
 * How near an edge the pointer must come, in pixels, before the card scrolls. Wider for touch: a
 * finger covers the strip it has to reach.
 */
const SCROLL_MARGIN = 60;
const TOUCH_SCROLL_MARGIN = 100;

/**
 * How fast the card scrolls with the pointer at the very edge, in pixels a second. Slower than the
 * edge scroller's default: a card's segments are short, so the whole list passes by in a few
 * hundred pixels.
 */
const SCROLL_SPEED = 600;

/**
 * Elements that handle a press themselves, so a press starting on one never drags the segment.
 * `renderItem` can draw anything, so ARIA roles and `contenteditable` count as well as the native
 * controls.
 */
const CONTROLS = "button, a, input, select, textarea, label, [contenteditable]:not([contenteditable=false]), "
    + "[role=button], [role=link], [role=checkbox], [role=switch], [role=textbox], [role=menuitem]";

/** One entry of a {@link SortableCard}, identified by a `key` independent of its position. */
export interface SortableItem {
    key: string;
    /** Text of the segment, used when `renderItem` is not given. */
    caption?: ComponentChildren;
    /** An icon class, `bx` prefix included, drawn before the caption. */
    icon?: string;
}

/**
 * One way of creating an entry, rendered as a button at the foot of the card.
 *
 * `onCreateItem` decides what the entry is, and can open a dialog or a picker first. Returning
 * nothing creates no entry.
 */
export interface ItemCreationButton<T extends SortableItem>
    extends Pick<ItemCreationRowButton, "label" | "icon" | "disabled"> {
    /** Answers with the entry to add, or with nothing where none was made. */
    onCreateItem: (event?: MouseEvent) => T | undefined | Promise<T | undefined>;
}

export interface SortableCardProps<T extends SortableItem> extends CardProps {
    /** The entries, in display order. */
    items: T[];
    /** Called with the whole list in its new order after every change. */
    onChange: (items: T[]) => void;
    /**
     * Renders the contents of a segment, for a card showing more than a name. Without it, the
     * segment shows the item's `caption` and `icon`.
     */
    renderItem?: (item: T, index: number) => ComponentChildren;
    /**
     * The ways to create an entry, rendered as a row of buttons at the foot of the card and omitted
     * when empty. Up to three; more than that makes each button too narrow to read.
     *
     * Enter on a segment uses the first of them.
     */
    itemCreationButtons?: ItemCreationButton<T>[];
    /**
     * Which edge of a segment holds the grip. Defaults to the trailing edge; use the leading one
     * when the entries carry their own controls on the trailing side.
     */
    gripPlacement?: "start" | "end";
    /**
     * Whether the reader can reorder the entries. Off, the card draws no grip and ignores drags
     * and Ctrl+arrow keys, for a caller that sorts the entries itself. Defaults to true.
     */
    isReorderable?: boolean;
    /**
     * Called for a key the card does not answer itself, with the entry that had the focus. For a
     * caller whose entries have commands of their own.
     */
    onItemKeyDown?: (item: T, event: KeyboardEvent) => void;
    /** The selected entry, for a caller that keeps the selection itself. */
    selectedKey?: string;
    onSelect?: (key: string) => void;
}

/**
 * A card whose segments can be reordered by dragging the grip or with the keyboard. A drag moves
 * vertically only and is clamped to the card.
 *
 * The caller owns the order: `onChange` reports every change and the card renders what it is given
 * back. Entries are not interpreted, so anything identified by a key can be sorted.
 */
export function SortableCard<T extends SortableItem>({
    items, onChange, renderItem, itemCreationButtons, gripPlacement = "end", isReorderable = true,
    onItemKeyDown, selectedKey, onSelect, className, ...card
}: SortableCardProps<T>) {
    if ((itemCreationButtons?.length ?? 0) > MAX_CREATION_BUTTONS) {
        throw new Error("Up to three item creation buttons are supported");
    }

    const listRef = useRef<HTMLDivElement>(null);
    const adderRef = useRef<HTMLElement>(null);
    const dragRef = useRef<Drag<T> | undefined>(undefined);
    /** A touch waiting out `TOUCH_HOLD_MS`, after which it becomes a drag. */
    const holdRef = useRef<Hold | undefined>(undefined);
    /** The last pointer position, needed when scrolling moves the list under a still pointer. */
    const pointerRef = useRef({ x: 0, y: 0 });
    /** The current `dragTo`, so the scroller can reposition the segment without a stale closure. */
    const dragToRef = useRef<(clientY: number) => void>(() => {});
    /** Fixed chrome covering the screen edges, measured when a drag starts. */
    const reachRef = useRef<Insets>({ top: 0, bottom: 0, left: 0, right: 0 });
    /**
     * Scrolls the card's containers while a segment is dragged to an edge, so a card taller than
     * the viewport can be reordered end to end. Created once, so its frames outlive the render.
     */
    const scroller = useMemo(() => createEdgeScroller({
        margin: matchMedia("(pointer: coarse)").matches
            ? TOUCH_SCROLL_MARGIN
            : SCROLL_MARGIN,
        speed: SCROLL_SPEED,
        reach: () => reachRef.current,
        // The pointer has not moved, but the content under it has.
        onScroll: () => dragToRef.current(pointerRef.current.y)
    }), []);

    useEffect(() => () => scroller.stop(), [ scroller ]);

    /**
     * The order during a drag, reported to the caller when it ends. Kept until the caller renders
     * its own order, so the segments do not spring back in between.
     */
    const [ draft, setDraft ] = useState<T[] | null>(null);
    const [ draggedKey, setDraggedKey ] = useState<string>();
    const [ ownSelection, setOwnSelection ] = useState<string>();
    /** The entry just added, which grows and fades in. */
    const [ addedKey, setAddedKey ] = useState<string>();
    /** The segment to focus after the next render: moving an element drops its focus. */
    const pendingFocus = useRef<string | undefined>(undefined);

    const shown = draft ?? items;
    // The current list and `onChange`, for a callback that resumes after an await.
    const shownRef = useRef(shown);
    const onChangeRef = useRef(onChange);
    /** Read before the commit, which can remove the focused segment. */
    const focused = focusedEntry(listRef.current, shownRef.current);
    shownRef.current = shown;
    onChangeRef.current = onChange;
    const selected = selectedKey ?? ownSelection;

    useEffect(() => {
        // The caller rendered its own order, so the draft can go. Not during a drag, where the
        // order is still changing.
        if (!dragRef.current) {
            setDraft(null);
        }
    }, [ items ]);

    const segmentOf = useCallback((key: string) => {
        // Compared instead of interpolated into a selector: a key holding a quote or a backslash
        // would throw or match the wrong segment.
        const segments = listRef.current?.querySelectorAll<HTMLElement>(".tn-sortable-segment");
        return [ ...segments ?? [] ].find((segment) => segment.dataset.key === key);
    }, []);

    // The dragged segment is excluded: it follows the pointer, and useFlip would slide it back.
    useFlip(listRef, {
        selector: ".tn-sortable-segment:not(.tn-sortable-dragging)",
        grow: (segment) => segment.dataset.key === addedKey
    });


    useLayoutEffect(() => {
        const key = pendingFocus.current;
        if (!key) {
            return;
        }

        pendingFocus.current = undefined;
        segmentOf(key)?.focus();
    });

    const select = useCallback((key: string) => {
        setOwnSelection(key);
        onSelect?.(key);
    }, [ onSelect ]);

    /** Moves focus and selection to the entry at `index`. */
    const focusEntry = useCallback((index: number) => {
        const key = shown[index]?.key;
        if (!key) {
            return;
        }

        pendingFocus.current = key;
        select(key);
        segmentOf(key)?.focus();
    }, [ segmentOf, select, shown ]);

    // Removing the focused segment leaves the focus on `document.body`, so it moves to the entry
    // in its place, else the one before it, else the creation row.
    useLayoutEffect(() => {
        if (!focused || shown.some((item) => item.key === focused.key)
                || (document.activeElement && document.activeElement !== document.body)) {
            return;
        }

        if (shown.length) {
            focusEntry(Math.min(focused.index, shown.length - 1));
        } else {
            adderRef.current?.querySelector<HTMLElement>(".tn-card-adder")?.focus();
        }
    });

    /** Moves the entry at `from` to `to`, keeping the focus on it. */
    const moveItem = useCallback((from: number, to: number) => {
        const order = moved(shown, from, to);
        if (!order) {
            return;
        }

        pendingFocus.current = shown[from].key;
        setDraft(order);
        onChange(order);
    }, [ onChange, shown ]);

    /** Ends the drag, keeping the new order or restoring the one the drag started from. */
    const endDrag = useCallback((keep: boolean) => {
        const drag = dragRef.current;
        if (!drag) {
            return;
        }

        dragRef.current = undefined;
        const segment = segmentOf(drag.key);
        if (segment) {
            segment.style.transform = "";
        }

        listRef.current?.releasePointerCapture?.(drag.pointerId);
        scroller.stop();
        setDraggedKey(undefined);
        pendingFocus.current = drag.key;

        if (!keep) {
            setDraft(null);
            return;
        }

        setDraft(drag.order);
        if (drag.order.some((item, index) => item.key !== drag.was[index].key)) {
            onChange(drag.order);
        }
    }, [ onChange, scroller, segmentOf ]);

    /** Starts the drag: records what is being moved and marks the segment as dragging. */
    const startDrag = useCallback((key: string, pointerId: number, clientY: number) => {
        const segment = segmentOf(key);
        if (!segment) {
            return;
        }

        reachRef.current = fixedChrome(segment);

        // Throws when the pointer is no longer active, usually a touch lifted during the hold.
        // Touch captures to the segment implicitly, so the drag works without this.
        try {
            listRef.current?.setPointerCapture?.(pointerId);
        } catch {
            // Nothing to do: pointermove reaches the list either way.
        }

        dragRef.current = {
            key,
            pointerId,
            grabbedAt: clientY,
            at: listRef.current?.getBoundingClientRect().top ?? 0,
            from: segment.offsetTop,
            height: segment.offsetHeight,
            order: shown,
            was: shown
        };

        setDraggedKey(key);
        select(key);
        segment.focus();
    }, [ segmentOf, select, shown ]);

    const cancelHold = useCallback(() => {
        const held = holdRef.current;
        holdRef.current = undefined;
        if (!held) {
            return;
        }

        window.clearTimeout(held.timer);
        held.stopWatching();
    }, []);

    useEffect(() => () => cancelHold(), [ cancelHold ]);

    const beginDrag = useCallback((event: PointerEvent, key: string) => {
        if (!isReorderable || !listRef.current || !segmentOf(key)) {
            return;
        }

        const target = event.target as HTMLElement | null;
        const onGrip = !!target?.closest(".tn-sortable-grip");

        // A mouse drags from the grip only, since it can aim at one. A touch drags from anywhere
        // on the segment, which a thumb reaches far more easily.
        if (event.pointerType === "mouse") {
            if (!onGrip || event.button !== 0) {
                return;
            }

            // Stops the press from starting a text selection.
            event.preventDefault();
            startDrag(key, event.pointerId, event.clientY);
            return;
        }

        // A press starting on a control belongs to that control. The segment is not one, although
        // it handles keys and carries a tabindex.
        const control = target?.closest(CONTROLS);
        if (!onGrip && control && control !== segmentOf(key)) {
            return;
        }


        cancelHold();

        // The list captures the pointer only once the drag begins, so a finger lifted before that
        // and outside the list reports to the page. Without this the timer drags a pointer that is
        // no longer down.
        const dropped = (ended: PointerEvent) => {
            if (ended.pointerId === holdRef.current?.pointerId) {
                cancelHold();
            }
        };

        document.addEventListener("pointerup", dropped);
        document.addEventListener("pointercancel", dropped);

        holdRef.current = {
            pointerId: event.pointerId,
            from: { x: event.clientX, y: event.clientY },
            // Where the finger is once the hold ends, so a small drift does not offset the drag.
            at: event.clientY,
            stopWatching: () => {
                document.removeEventListener("pointerup", dropped);
                document.removeEventListener("pointercancel", dropped);
            },
            timer: window.setTimeout(() => {
                const held = holdRef.current;
                holdRef.current = undefined;
                if (held) {
                    held.stopWatching();
                    startDrag(key, held.pointerId, held.at);
                }
            }, TOUCH_HOLD_MS)
        };
    }, [ cancelHold, isReorderable, segmentOf, startDrag ]);

    const dragTo = useCallback((clientY: number) => {
        const drag = dragRef.current;
        const list = listRef.current;
        const segment = drag && segmentOf(drag.key);
        if (!drag || !list || !segment) {
            return;
        }

        // How far the pointer has moved, less how far the list has scrolled under it: the segment
        // follows the position in the card, not the position on screen it started from.
        const carried = clientY - drag.grabbedAt - (list.getBoundingClientRect().top - drag.at);
        // Clamped to the card: the segment cannot pass the first or last position, whatever the
        // pointer does.
        const room = Math.max(0, list.clientHeight - drag.height);
        const top = Math.min(Math.max(drag.from + carried, 0), room);

        const order = orderFor(drag, segment, top, segmentOf);
        if (order) {
            drag.order = order;
            // Rendered before the segment is positioned, so it is measured against its new slot.
            flushSync(() => setDraft(order));
        }

        segment.style.transform = `translateY(${top - segment.offsetTop}px)`;
    }, [ segmentOf ]);

    dragToRef.current = dragTo;

    /**
     * Creates an entry at `at`, or appends it when no index is given. An entry created among the
     * others takes the focus; an appended one leaves it on the button, so several can be made.
     */
    const add = useCallback(async (
        create: ItemCreationButton<T>["onCreateItem"], at?: number, event?: MouseEvent
    ) => {
        const created = await create(event);
        if (!created) {
            return;
        }

        // Both read again instead of closed over: `create` can open a dialog, and the stale list or
        // `onChange` would undo a change made meanwhile.
        const order = [ ...shownRef.current ];
        order.splice(at ?? order.length, 0, created);
        setAddedKey(created.key);
        setDraft(order);
        if (at !== undefined) {
            pendingFocus.current = created.key;
        }

        onChangeRef.current(order);
    }, []);

    /**
     * Ends what `event.pointerId` was doing, and nothing else: a second finger pressed and lifted
     * in the list would otherwise cancel or commit the first one's drag.
     */
    const finish = useCallback((event: PointerEvent, keep: boolean) => {
        if (holdRef.current?.pointerId === event.pointerId) {
            cancelHold();
            return;
        }

        if (dragRef.current?.pointerId === event.pointerId) {
            endDrag(keep);
        }
    }, [ cancelHold, endDrag ]);

    const onSegmentKeyDown = useCallback((event: KeyboardEvent, index: number) => {
        if (event.key === "Escape" && dragRef.current) {
            event.preventDefault();
            endDrag(false);
            return;
        }

        // A key pressed on a control `renderItem` drew belongs to that control: Enter and Space
        // activate a button, and the card would otherwise act on the entry at the same time.
        if (event.target !== event.currentTarget) {
            return;
        }

        // Creates an entry below the focused one, or above it with Shift, the way a spreadsheet
        // adds a row. Uses the first creation button, since no button was pressed.
        const leading = itemCreationButtons?.[0];
        if (event.key === "Enter" && leading && !leading.disabled
                && !event.ctrlKey && !event.metaKey) {
            event.preventDefault();
            add(leading.onCreateItem, event.shiftKey ? index : index + 1);
            return;
        }

        const control = event.ctrlKey || event.metaKey;
        const last = shown.length - 1;
        const to = placeFor(event, index, last);

        if (to === undefined) {
            // Left to the caller, whose entries can handle keys of their own.
            if (!control) {
                onItemKeyDown?.(shown[index], event);
            }

            // Down from the last entry moves onto the creation row. It holds no entry, so
            // Ctrl+Down moves nothing there.
            if (!control && event.key === "ArrowDown" && index === last) {
                event.preventDefault();
                adderRef.current?.querySelector<HTMLElement>(".tn-card-adder")?.focus();
            }

            return;
        }

        if (control && !isReorderable) {
            return;
        }

        event.preventDefault();
        if (control) {
            moveItem(index, to);
        } else {
            focusEntry(to);
        }
    }, [
        add, endDrag, focusEntry, isReorderable, itemCreationButtons, moveItem, onItemKeyDown, shown
    ]);

    const onAddKeyDown = useCallback((event: KeyboardEvent) => {
        // Moves back into the entries. Home and End address the first and last entry, as they do
        // on an entry: the creation row is a focus stop, not an entry.
        const control = event.ctrlKey || event.metaKey;
        const to = control || !shown.length ? undefined : lastPlaceFor(event, shown.length - 1);
        if (to === undefined) {
            return;
        }

        event.preventDefault();
        focusEntry(to);
    }, [ focusEntry, shown ]);

    /**
     * The drag handle, drawn on the edge `gripPlacement` names. An affordance rather than the hit
     * area: the segment handles the press, so only a mouse has to aim at the grip.
     */
    const grip = () => (
        <span
            className="tn-sortable-grip"
            title={t("sortable_card.reorder")}
            aria-hidden="true"
        >
            <svg viewBox="0 0 16 16">
                <line x1="3" y1="6" x2="13" y2="6" />
                <line x1="3" y1="10" x2="13" y2="10" />
            </svg>
        </span>
    );

    return (
        <Card className={clsx("tn-sortable-card", className)} {...card}>
            <div
                ref={listRef}
                className="tn-sortable-list"
                role="list"
                onPointerMove={(event) => {
                    const held = holdRef.current;
                    if (held?.pointerId === event.pointerId) {
                        // Gone before it settled, which is a finger on its way somewhere else.
                        held.at = event.clientY;
                        if (Math.hypot(event.clientX - held.from.x, event.clientY - held.from.y)
                                > TOUCH_SLACK_PX) {
                            cancelHold();
                        }

                        return;
                    }

                    if (dragRef.current?.pointerId === event.pointerId) {
                        event.preventDefault();
                        pointerRef.current = { x: event.clientX, y: event.clientY };
                        scroller.update(scrolledBy(listRef.current), event.clientX, event.clientY);
                        dragTo(event.clientY);
                    }
                }}
                // Prevented during a drag only, so a touch meant to scroll still scrolls.
                onTouchMove={(event) => {
                    if (dragRef.current) {
                        event.preventDefault();
                    }
                }}
                onPointerUp={(event) => finish(event, true)}
                onPointerCancel={(event) => finish(event, false)}
            >
                {shown.map((item, index) => (
                    <section
                        key={item.key}
                        data-key={item.key}
                        role="listitem"
                        tabIndex={0}
                        aria-current={item.key === selected ? "true" : undefined}
                        className={clsx("tn-card-section tn-sortable-segment", {
                            "tn-sortable-dragging": item.key === draggedKey,
                            "tn-sortable-selected": item.key === selected,
                            "tn-sortable-appearing": item.key === addedKey
                        })}
                        onFocus={() => select(item.key)}
                        onPointerDown={(event) => beginDrag(event, item.key)}
                        onKeyDown={(event) => onSegmentKeyDown(event, index)}
                        onAnimationEnd={() => setAddedKey(undefined)}
                    >
                        {isReorderable && gripPlacement === "start" && grip()}

                        <span className="tn-sortable-content">
                            {renderItem
                                ? renderItem(item, index)
                                : <>
                                    {item.icon && <Icon icon={item.icon} />}
                                    <span className="tn-sortable-caption">{item.caption}</span>
                                </>}
                        </span>

                        {isReorderable && gripPlacement === "end" && grip()}
                    </section>
                ))}

                {!!itemCreationButtons?.length && (
                    <ItemCreationRow
                        elementRef={adderRef}
                        onKeyDown={onAddKeyDown}
                        buttons={itemCreationButtons.map((button) => ({
                            label: button.label,
                            icon: button.icon,
                            disabled: button.disabled,
                            onClick: (event) => add(button.onCreateItem, undefined, event)
                        }))}
                    />
                )}
            </div>
        </Card>
    );
}

/** The entry whose segment holds the focus, directly or through a control, and its index. */
function focusedEntry(list: HTMLElement | null, shown: SortableItem[]) {
    const segment = document.activeElement?.closest<HTMLElement>(".tn-sortable-segment");
    const index = segment && segment.parentElement === list
        ? shown.findIndex((item) => item.key === segment.dataset.key)
        : -1;
    return index < 0 ? undefined : { key: shown[index].key, index };
}

/**
 * How much of the viewport's top and bottom edges fixed chrome covers, a toolbar or a tab bar.
 *
 * A pointer cannot reach under a toolbar, so an edge behind one never triggers the edge scroll.
 * Measured at the middle of each edge and read once per drag.
 */
function fixedChrome(carried: HTMLElement): Insets {
    const insets = { top: 0, bottom: 0, left: 0, right: 0 };
    const middle = window.innerWidth / 2;

    for (const edge of [ "top", "bottom" ] as const) {
        const y = edge === "top" ? 1 : window.innerHeight - 1;

        for (const element of document.elementsFromPoint?.(middle, y) ?? []) {
            // Whatever contains the dragged segment covers nothing: the pointer is on it.
            if (element.contains(carried) || getComputedStyle(element).position !== "fixed") {
                continue;
            }

            const box = element.getBoundingClientRect();
            const depth = edge === "top" ? box.bottom : window.innerHeight - box.top;
            insets[edge] = Math.max(insets[edge], Math.min(depth, window.innerHeight / 3));
        }
    }

    return insets;
}

/**
 * The scrollable ancestors of the card, nearest first, which the edge scroller walks. A card in a
 * scrolling pane inside a scrolling page needs both.
 */
function scrolledBy(list: HTMLElement | null): ScrollTarget[] {
    const targets: ScrollTarget[] = [];

    for (let element = list?.parentElement; element; element = element.parentElement) {
        const style = getComputedStyle(element);
        const scrolls = style.overflowY === "auto" || style.overflowY === "scroll";
        if (scrolls && element.scrollHeight > element.clientHeight) {
            targets.push({ element, axis: "y" });
        }
    }

    const page = document.scrollingElement;
    if (page instanceof HTMLElement && page.scrollHeight > page.clientHeight) {
        targets.push({ element: page, axis: "y" });
    }

    return targets;
}

/** A touch waiting out `TOUCH_HOLD_MS` before it becomes a drag. */
interface Hold {
    pointerId: number;
    /** Where the pointer went down, which movement is measured against. */
    from: { x: number, y: number };
    /** Where the pointer is now, which the drag starts from. */
    at: number;
    timer: number;
    /** Removes the document listeners watching for a lift outside the list. */
    stopWatching: () => void;
}

/** A drag in progress: where the segment started, and the order it has reached. */
interface Drag<T extends SortableItem> {
    key: string;
    pointerId: number;
    /** Where the pointer went down, against which everything after it is measured. */
    grabbedAt: number;
    /** The list's position on screen when the drag started, against which scrolling is measured. */
    at: number;
    /** The segment's offsetTop when the drag started. */
    from: number;
    height: number;
    /** The current order, which is what `onChange` reports. */
    order: T[];
    /** The order the drag started from, for telling whether it changed anything. */
    was: T[];
}

/**
 * The index the dragged segment now belongs at. The others are measured at their current
 * positions, which for one already sliding is the position it slides to.
 *
 * A segment gives way once the dragged one's near edge passes its middle: the bottom edge for a
 * segment below, the top edge for one above. Comparing middles would put the last slot exactly at
 * the clamp, leaving the last position unreachable.
 */
function orderFor<T extends SortableItem>(
    drag: Drag<T>, carried: HTMLElement, top: number,
    segmentOf: (key: string) => HTMLElement | null | undefined
) {
    const from = drag.order.findIndex((item) => item.key === drag.key);
    let to = 0;

    for (const item of drag.order) {
        const segment = item.key !== drag.key && segmentOf(item.key);
        if (!segment) {
            continue;
        }

        const middle = segment.offsetTop + segment.offsetHeight / 2;
        const isBelow = segment.offsetTop > carried.offsetTop;
        if (isBelow ? middle < top + drag.height : middle <= top) {
            to++;
        }
    }

    return from === to ? undefined : moved(drag.order, from, to);
}

/** The list with one entry moved, or `undefined` when the order would not change. */
function moved<T>(items: T[], from: number, to: number) {
    const place = Math.min(Math.max(to, 0), items.length - 1);
    if (from < 0 || from >= items.length || place === from) {
        return undefined;
    }

    const order = [ ...items ];
    order.splice(place, 0, ...order.splice(from, 1));
    return order;
}

/** Which entry a key addresses from the creation row. */
function lastPlaceFor(event: KeyboardEvent, last: number) {
    switch (event.key) {
        case "ArrowUp":
        case "End":
            return last;
        case "Home":
            return 0;
        default:
            return undefined;
    }
}

/**
 * Which index a key addresses, or `undefined` for a key the card ignores. The same keys move a
 * segment and step between them, Control telling them apart, as the board's cards do.
 */
function placeFor(event: KeyboardEvent, index: number, last: number) {
    switch (event.key) {
        case "ArrowUp":
            return index - 1 < 0 ? undefined : index - 1;
        case "ArrowDown":
            return index + 1 > last ? undefined : index + 1;
        case "Home":
            return index === 0 ? undefined : 0;
        case "End":
            return index === last ? undefined : last;
        default:
            return undefined;
    }
}