zabi-components 8.0.0 → 8.1.0

package/dist/util/segmented-control.d.ts

@@ -0,0 +1,15 @@
+import type { Component } from "svelte";
+/** An icon component, as `@lucide/svelte` icons are. */
+export type SegmentedControlIcon = Component<{
+    size?: number;
+    class?: string;
+}>;
+/** One entry of SegmentedControl's `options`. */
+export interface SegmentedControlOption {
+    value: string;
+    label: string;
+    /** Rendered before the label. Decorative: the label names the segment. */
+    icon?: SegmentedControlIcon;
+    /** A disabled segment cannot be chosen, and the arrow keys skip it. */
+    disabled?: boolean;
+}

package/dist/util/segmented-control.js

@@ -0,0 +1 @@
+export {};

package/dist/util/select.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Every word a `Select` says by itself, shown or only read out. An app in
+ * another language passes its own through `strings`; what it leaves out stays
+ * as it is here. The older props for six of them (`placeholder`,
+ * `searchPlaceholder`, `noResultsText`, `loadingText`, `emptyStateTitle`,
+ * `emptyStateDescription`) still work, and win over `strings`.
+ */
+export interface SelectStrings {
+    /** Shown in the field while nothing is chosen, and the first, empty option of the native select. */
+    placeholder: string;
+    /** Placeholder and accessible name of the search field above the options. */
+    searchPlaceholder: string;
+    /** Shown in the list when the search matches nothing. */
+    noResults: string;
+    /** Shown in the field and in the list while `isLoading`. */
+    loading: string;
+    /** Heading of the box shown in the list when there are no options at all. */
+    emptyTitle: string;
+    /** The line under that heading. */
+    emptyDescription: string;
+    /** Accessible name of the list of options. */
+    listLabel: string;
+    /** Accessible name of the close button of the sheet the list opens in on a phone. */
+    closeLabel: string;
+    /** Accessible name of that sheet's grip while its button takes the sheet up to full height. */
+    expandLabel: string;
+    /** The same, while it takes the sheet back down. */
+    collapseLabel: string;
+}
+export declare const DEFAULT_SELECT_STRINGS: SelectStrings;
+/** How a Select shows its options. See the `presentation` prop. */
+export type SelectPresentation = "auto" | "popover" | "sheet" | "native";
+/** Marks the native `<select>` a Select renders, so a choice made in it before the page hydrates can be found. */
+export declare const NATIVE_SELECT_ATTRIBUTE = "data-zabi-select";
+/**
+ * What the visitor (or the browser, restoring a form) chose in `element`
+ * before its component mounted; `undefined` when it still has the value the
+ * server rendered, and for an element this module never saw.
+ */
+export declare function choiceBeforeMount(element: Element): string | undefined;

package/dist/util/select.js

@@ -0,0 +1,63 @@
+export const DEFAULT_SELECT_STRINGS = {
+    placeholder: "Select an option",
+    searchPlaceholder: "Search options",
+    noResults: "No results found",
+    loading: "Loading options...",
+    emptyTitle: "No options available",
+    emptyDescription: "Add an option to start making selections.",
+    listLabel: "Select options",
+    closeLabel: "Close",
+    expandLabel: "Expand",
+    collapseLabel: "Collapse",
+};
+/** Marks the native `<select>` a Select renders, so a choice made in it before the page hydrates can be found. */
+export const NATIVE_SELECT_ATTRIBUTE = "data-zabi-select";
+/**
+ * What a visitor chose in each server-rendered native select before the
+ * component took it over.
+ *
+ * The server's HTML carries a real `<select>`, and it works at once: a
+ * visitor can choose from it while the scripts are still on their way, and
+ * the browser may put an earlier choice back into it after a reload or a
+ * step back. When the component then hydrates it renders the value it was
+ * given, which would silently undo that. So when this module loads, which is
+ * before anything hydrates, each select's value is noted beside the value
+ * the server rendered it with (its `selected` option, or else its first),
+ * and every change after that is noted too. The component asks for its own
+ * element's when it mounts.
+ *
+ * Only a value that differs from the rendered one is a choice. A select that
+ * nobody touched is not, whatever it shows: it used to be compared with the
+ * component's prop instead, and a value with no option of its own (its
+ * options still loading, or simply not among them) was replaced by whatever
+ * the select happened to fall back to.
+ */
+const seenBeforeMount = new WeakMap();
+/** The value a select has when nobody has touched it: that of the option with the `selected` attribute, or of the first. */
+function renderedValue(element) {
+    const options = [...element.options];
+    return (options.find((option) => option.defaultSelected) ?? options[0])?.value ?? "";
+}
+if (typeof document !== "undefined") {
+    const selector = `select[${NATIVE_SELECT_ATTRIBUTE}]`;
+    for (const element of document.querySelectorAll(selector)) {
+        seenBeforeMount.set(element, { rendered: renderedValue(element), value: element.value });
+    }
+    document.addEventListener("change", (event) => {
+        const target = event.target;
+        if (target instanceof HTMLSelectElement && target.matches(selector)) {
+            const seen = seenBeforeMount.get(target);
+            if (seen)
+                seen.value = target.value;
+        }
+    }, true);
+}
+/**
+ * What the visitor (or the browser, restoring a form) chose in `element`
+ * before its component mounted; `undefined` when it still has the value the
+ * server rendered, and for an element this module never saw.
+ */
+export function choiceBeforeMount(element) {
+    const seen = seenBeforeMount.get(element);
+    return seen && seen.value !== seen.rendered ? seen.value : undefined;
+}

package/dist/util/sheet-drag.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+export interface SheetDragCallbacks {
+    /** Asked when a gesture could begin. Return false to leave it alone. */
+    canStart?: () => boolean;
+    onStart?: () => void;
+    /** `distance` in px since the drag began; positive is down. */
+    onMove: (distance: number) => void;
+    /** `velocity` in px per ms over the last moments of the drag; positive is down. */
+    onEnd: (distance: number, velocity: number, event: Event) => void;
+    /** The browser took the gesture back (a call came in, the pointer was lost). */
+    onCancel?: () => void;
+}
+export interface SheetDragTargets {
+    /**
+     * The grip and the area around it. A drag that starts here moves the
+     * sheet in either direction. Give it `touch-action: none`.
+     */
+    handleZone: HTMLElement;
+    /**
+     * The scrolling content. A touch that starts here scrolls it; only a
+     * downward swipe that begins with the content at its top moves the sheet.
+     */
+    scroller?: HTMLElement | null;
+}
+/** Movement under this many px is a press, not a drag. */
+export declare const DRAG_SLOP = 6;
+/**
+ * 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 declare function timeOf(event: Event): number;
+/**
+ * How fast a pointer was moving over the last moments of a gesture, on one
+ * axis. Also used by `PhotoViewer`, for both axes.
+ */
+export declare function createVelocityTracker(): {
+    reset(y: number, time: number): void;
+    add(y: number, time: number): void;
+    velocity(): number;
+};
+/**
+ * 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 declare function attachSheetDrag({ handleZone, scroller }: SheetDragTargets, callbacks: SheetDragCallbacks): () => void;
+/** A flick: faster than this, in px per ms, and the direction decides, not the distance. */
+export declare const FLICK_VELOCITY = 0.5;
+/** True where the user has asked for less motion, or where that cannot be asked. */
+export declare function prefersReducedMotion(): boolean;

package/dist/util/sheet-drag.js

@@ -0,0 +1,241 @@
+/**
+ * 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;
+/** 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]";
+/** 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 touchDragging = false;
+    let startedAtTop = 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;
+        touchDragging = false;
+        startedAtTop = (scroller?.scrollTop ?? 0) <= 0;
+    }
+    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 (!startedAtTop || (scroller?.scrollTop ?? 0) > 0)
+                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/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;
+}