zabi-components 8.0.0 → 9.0.0

package/dist/util/sheet-drag.js

@@ -0,0 +1,311 @@
+/**
+ * Dragging a bottom sheet with a finger or a pointer. Shared by `BottomSheet`
+ * and `SlideUp`, so the two cannot disagree on what a swipe is.
+ *
+ * It only reports the gesture: how far the pointer has travelled since the
+ * drag began and how fast it was going at the end. What that means (move the
+ * panel, snap, close) is the caller's.
+ */
+/** Movement under this many px is a press, not a drag. */
+export const DRAG_SLOP = 6;
+/**
+ * Movement, on either axis, after which a touch in the content has an axis:
+ * more across than down is sideways (a carousel, a row that scrolls, a
+ * swipeable item), and stays so until the finger lifts.
+ */
+export const AXIS_SLOP = 8;
+/** Controls in the handle zone that keep their own press, except the grip itself. */
+const INTERACTIVE = "button, a[href], input, select, textarea, [data-sheet-no-drag]";
+const GRIP = "[data-sheet-grip]";
+/**
+ * Content that is dragged by a finger on its own and so is never the sheet's:
+ * anything carrying `data-sheet-no-drag`, and a range input. Read on a touch
+ * that starts in the content.
+ */
+const OWN_DRAG = "[data-sheet-no-drag], input[type='range']";
+/**
+ * Whether a computed `touch-action` hands vertical gestures to the element's
+ * own code: `none`, or panning on the x axis only. `auto`, `manipulation`,
+ * `pan-y` and the like let the browser pan vertically, which is the sheet's
+ * to take.
+ */
+function ownsVerticalGesture(touchAction) {
+    const tokens = touchAction.trim().split(/\s+/);
+    if (tokens.includes("none"))
+        return true;
+    const sideways = tokens.some((token) => token === "pan-x" || token === "pan-left" || token === "pan-right");
+    const vertical = tokens.some((token) => token === "pan-y" || token === "pan-up" || token === "pan-down");
+    return sideways && !vertical;
+}
+/**
+ * Whether a touch that begins on `target` belongs to the content and not to the
+ * sheet: it started on something that is dragged itself (`OWN_DRAG`), or it
+ * has, between it and the sheet's `scroller`, a box that scrolls on the y axis
+ * or one whose `touch-action` leaves vertical panning to the page's own code
+ * (`ownsVerticalGesture`: a map, a canvas, a drawing pad, a slider).
+ * A box that can scroll keeps the gesture whether it is at its top or not: a
+ * drag that sometimes scrolls a list and sometimes closes the sheet cannot be
+ * predicted, and the list does not hand over what it cannot use
+ * (`overscroll-contain`). The scroller itself is not asked here; it is the
+ * sheet's own content, and hands a pull down at its top to the sheet.
+ */
+export function contentTakesTouch(target, scroller) {
+    if (!(target instanceof Element))
+        return false;
+    if (target.closest(OWN_DRAG))
+        return true;
+    for (let node = target; node && node !== scroller; node = node.parentElement) {
+        const style = getComputedStyle(node);
+        if (ownsVerticalGesture(style.getPropertyValue("touch-action")))
+            return true;
+        const overflow = style.overflowY;
+        if ((overflow === "auto" || overflow === "scroll") && node.scrollHeight > node.clientHeight) {
+            return true;
+        }
+    }
+    return false;
+}
+/** The clock of this page, for when an event's own time cannot be used. */
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+/**
+ * When a pointer or touch event happened: its own `timeStamp`, which is when
+ * the finger moved. The time the handler runs is later by however busy the
+ * page is, and unevenly so, which made a flick on a janky frame (or a loaded
+ * machine) measure slower than it was and spring back. An event without a
+ * usable stamp gets the clock.
+ */
+export function timeOf(event) {
+    const stamp = event.timeStamp;
+    return typeof stamp === "number" && stamp > 0 ? stamp : now();
+}
+/** How far back the velocity looks, in ms. */
+const VELOCITY_WINDOW = 100;
+/**
+ * How fast a pointer was moving over the last moments of a gesture, on one
+ * axis. Also used by `PhotoViewer`, for both axes.
+ */
+export function createVelocityTracker() {
+    /** `time` is the event's; `clock` is when it was handled. */
+    let samples = [];
+    return {
+        reset(y, time) {
+            samples = [{ time, clock: now(), y }];
+        },
+        add(y, time) {
+            samples.push({ time, clock: now(), y });
+            while (samples.length > 2 && time - samples[0].time > VELOCITY_WINDOW)
+                samples.shift();
+        },
+        velocity() {
+            if (samples.length < 2)
+                return 0;
+            const first = samples[0];
+            const last = samples[samples.length - 1];
+            // Some browsers hand every event of one frame the same stamp:
+            // such a flick has no duration by the events, and is timed by
+            // the clock instead.
+            const byEvents = last.time - first.time;
+            const elapsed = byEvents > 0 ? byEvents : last.clock - first.clock;
+            return elapsed > 0 ? (last.y - first.y) / elapsed : 0;
+        },
+    };
+}
+/**
+ * Listens for drags on a sheet. Call it when the sheet is open, in the
+ * browser, and call the returned function when it closes.
+ */
+export function attachSheetDrag({ handleZone, scroller }, callbacks) {
+    const tracker = createVelocityTracker();
+    const allowed = () => callbacks.canStart?.() ?? true;
+    // --- The handle zone: pointer events, so a mouse and a pen drag it too.
+    let pointerId = null;
+    let pointerStart = 0;
+    let pointerDragging = false;
+    function swallowClick(event) {
+        // The click that ends a drag on the grip is not a press of the grip.
+        event.preventDefault();
+        event.stopPropagation();
+    }
+    function onPointerDown(event) {
+        if (pointerId !== null || touchDragging)
+            return;
+        if (event.pointerType === "mouse" && event.button !== 0)
+            return;
+        const target = event.target;
+        if (target?.closest(INTERACTIVE) && !target.closest(GRIP))
+            return;
+        if (!allowed())
+            return;
+        pointerId = event.pointerId;
+        pointerStart = event.clientY;
+        pointerDragging = false;
+        tracker.reset(event.clientY, timeOf(event));
+        // Not captured yet. A captured pointer delivers its `pointerup` and
+        // the click that follows to the handle zone, not to what was
+        // pressed: a mouse click on the grip then never reached the grip's
+        // button. It is captured once the press has become a drag. A mouse
+        // can leave the zone before that, so its moves are followed on the
+        // window meanwhile; a finger stays with the element it went down on.
+        window.addEventListener("pointermove", onPointerMove);
+        window.addEventListener("pointerup", onPointerUp);
+        window.addEventListener("pointercancel", onPointerCancel);
+    }
+    function stopFollowing() {
+        window.removeEventListener("pointermove", onPointerMove);
+        window.removeEventListener("pointerup", onPointerUp);
+        window.removeEventListener("pointercancel", onPointerCancel);
+    }
+    function onPointerMove(event) {
+        if (event.pointerId !== pointerId)
+            return;
+        const distance = event.clientY - pointerStart;
+        if (!pointerDragging) {
+            if (Math.abs(distance) < DRAG_SLOP)
+                return;
+            pointerDragging = true;
+            try {
+                handleZone.setPointerCapture(event.pointerId);
+            }
+            catch {
+                /* a test DOM, or a pointer that is already gone */
+            }
+            // Measured from where the drag was recognised, so the sheet does
+            // not jump by the slop.
+            pointerStart = event.clientY;
+            tracker.reset(event.clientY, timeOf(event));
+            callbacks.onStart?.();
+            callbacks.onMove(0);
+            return;
+        }
+        tracker.add(event.clientY, timeOf(event));
+        callbacks.onMove(distance);
+    }
+    function finishPointer(event, cancelled) {
+        if (event.pointerId !== pointerId)
+            return;
+        const wasDragging = pointerDragging;
+        const distance = event.clientY - pointerStart;
+        pointerId = null;
+        pointerDragging = false;
+        stopFollowing();
+        try {
+            handleZone.releasePointerCapture(event.pointerId);
+        }
+        catch {
+            /* never captured */
+        }
+        if (!wasDragging)
+            return;
+        if (cancelled) {
+            callbacks.onCancel?.();
+            return;
+        }
+        tracker.add(event.clientY, timeOf(event));
+        handleZone.addEventListener("click", swallowClick, { capture: true, once: true });
+        // No click follows a drag that ends off the element it began on.
+        setTimeout(() => handleZone.removeEventListener("click", swallowClick, true), 0);
+        callbacks.onEnd(distance, tracker.velocity(), event);
+    }
+    const onPointerUp = (event) => finishPointer(event, false);
+    const onPointerCancel = (event) => finishPointer(event, true);
+    // --- The content: touch events, because here the browser owns the
+    // gesture (it scrolls) until we take it, and only a touch listener that
+    // is not passive can take it.
+    let touchId = null;
+    let touchStart = 0;
+    let touchStartX = 0;
+    /** Decided once per gesture, after `AXIS_SLOP`: null until then. */
+    let touchAxis = null;
+    let touchDragging = false;
+    let startedAtTop = false;
+    /** The touch began on something inside the content that keeps it. */
+    let contentOwns = false;
+    const touchOf = (event, list) => Array.from(list).find((touch) => touch.identifier === touchId);
+    function onTouchStart(event) {
+        if (touchId !== null || pointerId !== null || event.touches.length !== 1)
+            return;
+        const touch = event.touches[0];
+        touchId = touch.identifier;
+        touchStart = touch.clientY;
+        touchStartX = touch.clientX;
+        touchAxis = null;
+        touchDragging = false;
+        startedAtTop = (scroller?.scrollTop ?? 0) <= 0;
+        contentOwns = !!scroller && contentTakesTouch(event.target, scroller);
+    }
+    function onTouchMove(event) {
+        const touch = touchOf(event, event.touches);
+        if (!touch)
+            return;
+        const distance = touch.clientY - touchStart;
+        if (!touchDragging) {
+            // Content that has scrolled, or a swipe upwards: the content's.
+            if (contentOwns || touchAxis === "x" || !startedAtTop || (scroller?.scrollTop ?? 0) > 0)
+                return;
+            if (touchAxis === null) {
+                const across = Math.abs(touch.clientX - touchStartX);
+                if (Math.max(across, Math.abs(distance)) < AXIS_SLOP)
+                    return;
+                touchAxis = across > Math.abs(distance) ? "x" : "y";
+                if (touchAxis === "x")
+                    return;
+            }
+            if (distance < DRAG_SLOP || !allowed())
+                return;
+            touchDragging = true;
+            touchStart = touch.clientY;
+            tracker.reset(touch.clientY, timeOf(event));
+            callbacks.onStart?.();
+            if (event.cancelable)
+                event.preventDefault();
+            callbacks.onMove(0);
+            return;
+        }
+        // Ours now: no scrolling, no pull-to-refresh.
+        if (event.cancelable)
+            event.preventDefault();
+        tracker.add(touch.clientY, timeOf(event));
+        callbacks.onMove(distance);
+    }
+    function finishTouch(event, cancelled) {
+        const touch = touchOf(event, event.changedTouches);
+        if (!touch)
+            return;
+        const wasDragging = touchDragging;
+        const distance = touch.clientY - touchStart;
+        touchId = null;
+        touchDragging = false;
+        if (!wasDragging)
+            return;
+        if (cancelled) {
+            callbacks.onCancel?.();
+            return;
+        }
+        tracker.add(touch.clientY, timeOf(event));
+        callbacks.onEnd(distance, tracker.velocity(), event);
+    }
+    const onTouchEnd = (event) => finishTouch(event, false);
+    const onTouchCancel = (event) => finishTouch(event, true);
+    handleZone.addEventListener("pointerdown", onPointerDown);
+    scroller?.addEventListener("touchstart", onTouchStart, { passive: true });
+    scroller?.addEventListener("touchmove", onTouchMove, { passive: false });
+    scroller?.addEventListener("touchend", onTouchEnd);
+    scroller?.addEventListener("touchcancel", onTouchCancel);
+    return () => {
+        handleZone.removeEventListener("pointerdown", onPointerDown);
+        stopFollowing();
+        handleZone.removeEventListener("click", swallowClick, true);
+        scroller?.removeEventListener("touchstart", onTouchStart);
+        scroller?.removeEventListener("touchmove", onTouchMove);
+        scroller?.removeEventListener("touchend", onTouchEnd);
+        scroller?.removeEventListener("touchcancel", onTouchCancel);
+    };
+}
+/** A flick: faster than this, in px per ms, and the direction decides, not the distance. */
+export const FLICK_VELOCITY = 0.5;
+/** True where the user has asked for less motion, or where that cannot be asked. */
+export function prefersReducedMotion() {
+    return (typeof window === "undefined" ||
+        typeof window.matchMedia !== "function" ||
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches);
+}

package/dist/util/sidebar.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The words the sidebar components say by themselves. Each takes its own as
+ * `strings`; `SidebarNavigation` takes them all and hands the footer and the
+ * brand header theirs.
+ */
+/** `SidebarBrandHeader`. */
+export interface SidebarBrandHeaderStrings {
+    /** The logo's alt text when neither `logoAlt` nor `brandName` is given. */
+    brandAlt: string;
+}
+export declare const DEFAULT_SIDEBAR_BRAND_HEADER_STRINGS: SidebarBrandHeaderStrings;
+/** `SidebarFooter`. */
+export interface SidebarFooterStrings {
+    /** Accessible name of the footer. */
+    accountAndSettings: string;
+    /** Accessible name of the profile button in a collapsed rail. */
+    openAccountPanel: string;
+    /** The same button in an expanded sidebar, with the profile's name. */
+    openAccountPanelFor: (name: string) => string;
+}
+export declare const DEFAULT_SIDEBAR_FOOTER_STRINGS: SidebarFooterStrings;
+/** `SidebarAccountPanel`. */
+export interface SidebarAccountPanelStrings {
+    /** Accessible name of the panel. */
+    panelLabel: string;
+    /** The panel's heading. */
+    title: string;
+    /** Accessible name of the close button. */
+    closeLabel: string;
+    /** Accessible name of the list of rows. */
+    listLabel: string;
+    /** The first row, above the profile's name. */
+    account: string;
+    /** The row that switches the theme. */
+    theme: string;
+    /** That row's second line, in each mode. */
+    lightMode: string;
+    darkMode: string;
+    /** With `themeModes="three"`: the mode that follows the system. */
+    systemMode: string;
+    /** The badge on that row, in each mode. */
+    light: string;
+    dark: string;
+    system: string;
+    /** The second line of the log-out row. Its first line is `logoutLabel`. */
+    signOut: string;
+}
+export declare const DEFAULT_SIDEBAR_ACCOUNT_PANEL_STRINGS: SidebarAccountPanelStrings;
+/** `SidebarNavigation`: its own words, and those of the footer and the brand header in it. */
+export interface SidebarNavigationStrings extends SidebarFooterStrings, SidebarBrandHeaderStrings {
+    /** Accessible name of the main list of links, when it has no section heading. */
+    primaryNavigation: string;
+    /** Accessible name of the second list of links. */
+    secondaryNavigation: string;
+    /** Accessible name of a list under a section heading, from the heading. */
+    sectionNavigation: (section: string) => string;
+    /** Shown when a search matches no link: the heading. */
+    noMatchesTitle: string;
+    /** And the line under it, with what was searched for. */
+    noMatchesDescription: (term: string) => string;
+}
+export declare const DEFAULT_SIDEBAR_NAVIGATION_STRINGS: SidebarNavigationStrings;

package/dist/util/sidebar.js

@@ -0,0 +1,38 @@
+/**
+ * The words the sidebar components say by themselves. Each takes its own as
+ * `strings`; `SidebarNavigation` takes them all and hands the footer and the
+ * brand header theirs.
+ */
+export const DEFAULT_SIDEBAR_BRAND_HEADER_STRINGS = {
+    brandAlt: "Brand",
+};
+export const DEFAULT_SIDEBAR_FOOTER_STRINGS = {
+    accountAndSettings: "Account and settings",
+    openAccountPanel: "Open account panel",
+    openAccountPanelFor: (name) => `Open account panel for ${name}`,
+};
+export const DEFAULT_SIDEBAR_ACCOUNT_PANEL_STRINGS = {
+    panelLabel: "Account panel",
+    title: "Account",
+    closeLabel: "Close account panel",
+    listLabel: "Select item",
+    account: "Account",
+    theme: "Theme",
+    lightMode: "Light mode",
+    darkMode: "Dark mode",
+    // Not "System": the badge beside it says that, and the row read "Theme System System".
+    systemMode: "Follows the system",
+    light: "Light",
+    dark: "Dark",
+    system: "System",
+    signOut: "Sign out of this account",
+};
+export const DEFAULT_SIDEBAR_NAVIGATION_STRINGS = {
+    ...DEFAULT_SIDEBAR_FOOTER_STRINGS,
+    ...DEFAULT_SIDEBAR_BRAND_HEADER_STRINGS,
+    primaryNavigation: "Primary navigation",
+    secondaryNavigation: "Secondary navigation",
+    sectionNavigation: (section) => `${section} navigation`,
+    noMatchesTitle: "No matching navigation items",
+    noMatchesDescription: (term) => `No results found for "${term}". Try another keyword.`,
+};

package/dist/util/skeleton.d.ts

@@ -0,0 +1,14 @@
+/** Every built-in string. Pass a partial object to `strings` to translate. */
+export interface SkeletonStrings {
+    /** The name of the loading status, for a lone `Skeleton` and for a `SkeletonGroup`. */
+    label: string;
+}
+export declare const DEFAULT_SKELETON_STRINGS: SkeletonStrings;
+/** The fewest and the most lines a text `Skeleton` draws with `lines`. */
+export declare const SKELETON_LINES_MAX = 20;
+/** `lines` as a whole number from 1 to 20, or 0 for "not a paragraph" (unset, below 1, not a number). */
+export declare function skeletonLineCount(lines: number | undefined): number;
+/** For `SkeletonGroup`: marks everything below it as pieces of one status. Call while the component initialises. */
+export declare function provideSkeletonGroup(): void;
+/** For `Skeleton`: whether it sits under a `SkeletonGroup`. Call while the component initialises. */
+export declare function inSkeletonGroup(): boolean;

package/dist/util/skeleton.js

@@ -0,0 +1,22 @@
+/** Types and helpers shared by `Skeleton` and `SkeletonGroup`. Kept out of the components so they can be tested without a DOM. */
+import { getContext, setContext } from "svelte";
+export const DEFAULT_SKELETON_STRINGS = {
+    label: "Loading…",
+};
+/** The fewest and the most lines a text `Skeleton` draws with `lines`. */
+export const SKELETON_LINES_MAX = 20;
+/** `lines` as a whole number from 1 to 20, or 0 for "not a paragraph" (unset, below 1, not a number). */
+export function skeletonLineCount(lines) {
+    if (lines === undefined || !Number.isFinite(lines) || lines < 1)
+        return 0;
+    return Math.min(SKELETON_LINES_MAX, Math.floor(lines));
+}
+const GROUP_KEY = Symbol("zabi-skeleton-group");
+/** For `SkeletonGroup`: marks everything below it as pieces of one status. Call while the component initialises. */
+export function provideSkeletonGroup() {
+    setContext(GROUP_KEY, true);
+}
+/** For `Skeleton`: whether it sits under a `SkeletonGroup`. Call while the component initialises. */
+export function inSkeletonGroup() {
+    return getContext(GROUP_KEY) === true;
+}

package/dist/util/sliding-indicator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Measuring for the sliding indicator of Tabs and SegmentedControl. The
+ * component paints its selected item itself until a box has been measured, so
+ * a server render, a page that has not hydrated and an engine that cannot
+ * measure all keep the static look.
+ */
+export interface IndicatorBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The `item`'s box in the coordinates an absolutely positioned child of
+ * `container` uses: from the container's padding box, plus what the container
+ * has scrolled (so an indicator inside a scrolling list stays on its item).
+ * Measured as physical boxes, so a right-to-left layout needs nothing extra.
+ * Null where nothing can be measured (no layout, or the item is not shown).
+ */
+export declare function measureIndicator(container: HTMLElement, item: HTMLElement): IndicatorBox | null;
+/** Calls `onChange` when any of the `targets` changes size; a no-op without ResizeObserver. */
+export declare function observeSizes(targets: Array<Element | null | undefined>, onChange: () => void): () => void;
+/** Runs `callback` after the next frame; the timer stands in where there are no frames. */
+export declare function afterFrame(callback: () => void): () => void;

package/dist/util/sliding-indicator.js

@@ -0,0 +1,44 @@
+/**
+ * Measuring for the sliding indicator of Tabs and SegmentedControl. The
+ * component paints its selected item itself until a box has been measured, so
+ * a server render, a page that has not hydrated and an engine that cannot
+ * measure all keep the static look.
+ */
+/**
+ * The `item`'s box in the coordinates an absolutely positioned child of
+ * `container` uses: from the container's padding box, plus what the container
+ * has scrolled (so an indicator inside a scrolling list stays on its item).
+ * Measured as physical boxes, so a right-to-left layout needs nothing extra.
+ * Null where nothing can be measured (no layout, or the item is not shown).
+ */
+export function measureIndicator(container, item) {
+    const outer = container.getBoundingClientRect();
+    const inner = item.getBoundingClientRect();
+    if (inner.width === 0 && inner.height === 0)
+        return null;
+    return {
+        x: inner.left - outer.left - container.clientLeft + container.scrollLeft,
+        y: inner.top - outer.top - container.clientTop + container.scrollTop,
+        width: inner.width,
+        height: inner.height,
+    };
+}
+/** Calls `onChange` when any of the `targets` changes size; a no-op without ResizeObserver. */
+export function observeSizes(targets, onChange) {
+    if (typeof ResizeObserver === "undefined")
+        return () => { };
+    const observer = new ResizeObserver(onChange);
+    for (const target of targets)
+        if (target)
+            observer.observe(target);
+    return () => observer.disconnect();
+}
+/** Runs `callback` after the next frame; the timer stands in where there are no frames. */
+export function afterFrame(callback) {
+    if (typeof requestAnimationFrame === "function") {
+        const id = requestAnimationFrame(callback);
+        return () => cancelAnimationFrame(id);
+    }
+    const id = setTimeout(callback, 16);
+    return () => clearTimeout(id);
+}

package/dist/util/sortable-list.d.ts

@@ -0,0 +1,64 @@
+/** Types and pure helpers for `SortableList`. Kept out of the component so they can be tested without a DOM. */
+import type { Snippet } from "svelte";
+/** Payload of `onreorder`: which item moved, and between which zero-based indexes. */
+export interface SortableListReorderDetail<T> {
+    item: T;
+    from: number;
+    to: number;
+    /** The list in its new order (the same array `bind:items` receives). */
+    items: T[];
+}
+/** What a live-region message is built from. `position` is one-based. */
+export interface SortableListAnnouncement {
+    label: string;
+    position: number;
+    total: number;
+}
+/** Second argument of the `item` snippet. */
+export interface SortableListRow {
+    /** Zero-based index in the current order. */
+    index: number;
+    /** True while this row is being dragged with a pointer. */
+    dragging: boolean;
+    /** True when the list or this item is disabled. */
+    disabled: boolean;
+    /** The drag handle. Render it yourself when `controls="manual"`. */
+    handle: Snippet;
+    /** The move up / move down buttons. Render them yourself when `controls="manual"`. */
+    moveButtons: Snippet;
+}
+/** Every built-in string. Pass a partial object to `strings` to translate. */
+export interface SortableListStrings {
+    /** Accessible name of the drag handle. */
+    handleLabel: (label: string) => string;
+    /** How to use the handle; referenced by every handle through `aria-describedby`. */
+    handleDescription: string;
+    moveUp: (label: string) => string;
+    moveDown: (label: string) => string;
+    /** Announced after every move. */
+    moved: (detail: SortableListAnnouncement) => string;
+    /** Announced when Escape (or a cancelled pointer) abandons a drag. */
+    cancelled: (detail: SortableListAnnouncement) => string;
+    /** Announced when Arrow Up or Home is pressed on the first item. */
+    atStart: (detail: SortableListAnnouncement) => string;
+    /** Announced when Arrow Down or End is pressed on the last item. */
+    atEnd: (detail: SortableListAnnouncement) => string;
+}
+export declare const SORTABLE_LIST_STRINGS: SortableListStrings;
+/** A copy of `items` with the entry at `from` moved to `to`. Out-of-range indexes are clamped. */
+export declare function moveItem<T>(items: readonly T[], from: number, to: number): T[];
+/** Top edge and height of a row, measured once when a drag starts. */
+export interface SortableSlot {
+    top: number;
+    height: number;
+}
+/**
+ * Index the dragged row would land on, given how far it has travelled.
+ *
+ * A row below counts as passed once the dragged row's bottom edge crosses its
+ * centre, and a row above once the top edge does. Both are read from the
+ * positions measured at drag start, so the answer depends on the pointer
+ * alone: rows sliding out of the way cannot feed back into it and make the
+ * target flicker, which is what happens when the live positions are compared.
+ */
+export declare function dropIndex(slots: readonly SortableSlot[], from: number, offset: number): number;

package/dist/util/sortable-list.js

@@ -0,0 +1,53 @@
+/** Types and pure helpers for `SortableList`. Kept out of the component so they can be tested without a DOM. */
+export const SORTABLE_LIST_STRINGS = {
+    handleLabel: (label) => `Reorder ${label}`,
+    // Kept short: a screen reader reads it after the name each time the
+    // handle takes focus, and a move down can hand focus back to the handle.
+    handleDescription: "Arrow keys move this item. Home and End move it to the start or the end.",
+    moveUp: (label) => `Move ${label} up`,
+    moveDown: (label) => `Move ${label} down`,
+    moved: ({ label, position, total }) => `${label}, moved to position ${position} of ${total}`,
+    cancelled: ({ label, position, total }) => `${label}, move cancelled, still at position ${position} of ${total}`,
+    atStart: ({ label }) => `${label}, already first`,
+    atEnd: ({ label }) => `${label}, already last`,
+};
+/** A copy of `items` with the entry at `from` moved to `to`. Out-of-range indexes are clamped. */
+export function moveItem(items, from, to) {
+    const next = [...items];
+    if (from < 0 || from >= next.length)
+        return next;
+    const target = Math.max(0, Math.min(next.length - 1, to));
+    const [moved] = next.splice(from, 1);
+    next.splice(target, 0, moved);
+    return next;
+}
+/**
+ * Index the dragged row would land on, given how far it has travelled.
+ *
+ * A row below counts as passed once the dragged row's bottom edge crosses its
+ * centre, and a row above once the top edge does. Both are read from the
+ * positions measured at drag start, so the answer depends on the pointer
+ * alone: rows sliding out of the way cannot feed back into it and make the
+ * target flicker, which is what happens when the live positions are compared.
+ */
+export function dropIndex(slots, from, offset) {
+    const dragged = slots[from];
+    if (!dragged)
+        return from;
+    const top = dragged.top + offset;
+    const bottom = top + dragged.height;
+    let to = from;
+    for (let i = from + 1; i < slots.length; i += 1) {
+        if (bottom > slots[i].top + slots[i].height / 2)
+            to = i;
+        else
+            break;
+    }
+    for (let i = from - 1; i >= 0; i -= 1) {
+        if (top < slots[i].top + slots[i].height / 2)
+            to = i;
+        else
+            break;
+    }
+    return to;
+}