@lyeve-labs/ui-kit 0.12.1 → 0.13.0

package/dist/internal/listbox.svelte.js

@@ -0,0 +1,438 @@
+/**
+ * One owner for the open state, the active row, the keyboard model and the
+ * dismissal that every list-bearing control needs.
+ *
+ * MultiSelect, Autocomplete, DatePicker and Dropdown each hand-rolled all four,
+ * and every copy is wrong somewhere different. The dismiss effect is written
+ * out four times: MultiSelect.svelte:84-93, DatePicker.svelte:151-160 and
+ * Dropdown.svelte:45-54 are byte identical, and Autocomplete.svelte:117-120 is
+ * the same minus the keydown, so Escape does nothing there at all.
+ * Autocomplete.svelte:90-107 is the kit's only arrow-key implementation and it
+ * is incomplete: ArrowUp on a closed list decrements the index without opening
+ * anything, Home and End do nothing, there is no typeahead and there is no
+ * wrap. Nothing in the kit sets aria-activedescendant, so a screen reader is
+ * never told which row the keyboard is resting on, and Autocomplete marks that
+ * row with a background tint alone, which reads 1.09:1. The rows are buttons
+ * carrying role="option" and no tabindex, so Tab walks into the list instead of
+ * leaving the field. Autocomplete.svelte:146 closes on a 150ms blur timer, so
+ * clicking an option works only because mousedown-to-click beats the timer. And
+ * no copy stops the Escape event, so a listbox inside a Modal closes both.
+ *
+ * One thing deliberately stays at the call site: what a selection means. This
+ * fires onSelect and leaves the list open, because MultiSelect collects several
+ * values in one pass and a factory that closed on every pick could not serve
+ * it. A single-value control calls close('select') from its own onSelect, which
+ * is why that reason exists.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+import { normalize } from './filter.js';
+/**
+ * How long a typed run stays open for another character.
+ *
+ * A pause longer than this starts a new run, so "ne" pauses "n" reaches the
+ * first N again rather than searching for a label starting "nn".
+ */
+const TYPEAHEAD_WINDOW_MS = 500;
+/**
+ * What counts as the trigger inside an anchor: the first element in the tab
+ * sequence. Rows are excluded by construction, since optionAttrs gives every
+ * one of them tabindex -1.
+ */
+const TRIGGER = 'input:not([disabled]), button:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+export function createListbox(config) {
+    let open = $state(false);
+    let activeIndex = $state(-1);
+    let anchorNode = null;
+    let panelNode = null;
+    let listening = false;
+    // The typed run and when it was last extended. Plain variables rather than
+    // $state: nothing renders them, and a reactive keystroke buffer would
+    // invalidate every reader of the list on every letter.
+    let typed = '';
+    let typedAt = 0;
+    const items = () => config.items();
+    const loop = () => config.loop?.() ?? false;
+    const typeahead = () => config.typeahead?.() ?? false;
+    const listId = () => `${config.baseId()}-list`;
+    const optionId = (index) => `${config.baseId()}-option-${index}`;
+    /**
+     * The active row, clamped into the list as it stands now.
+     *
+     * A filter that narrows the list under an active index leaves the index
+     * pointing past the end, and aria-activedescendant then names an element that
+     * was never rendered, which a screen reader reports as nothing at all.
+     * Clamping on read rather than on write means the answer is right even when
+     * the list changed without anyone telling the listbox.
+     */
+    function activeRow() {
+        const count = items().length;
+        if (count === 0 || activeIndex < 0)
+            return -1;
+        return activeIndex < count ? activeIndex : count - 1;
+    }
+    function selectable(index) {
+        const item = items()[index];
+        return item !== undefined && item.disabled !== true;
+    }
+    function firstSelectable() {
+        const count = items().length;
+        for (let i = 0; i < count; i++) {
+            if (selectable(i))
+                return i;
+        }
+        return -1;
+    }
+    function lastSelectable() {
+        for (let i = items().length - 1; i >= 0; i--) {
+            if (selectable(i))
+                return i;
+        }
+        return -1;
+    }
+    /**
+     * The next selectable row in one direction.
+     *
+     * Disabled rows are stepped over rather than landed on, because Enter refuses
+     * them: resting the active ring on a row that cannot be chosen tells the user
+     * the opposite of the truth. With loop off the move holds at the row it
+     * started from, so arrowing into the end of the list does not silently do
+     * nothing visible and then jump on the next press.
+     */
+    function step(from, direction) {
+        const count = items().length;
+        if (count === 0)
+            return -1;
+        if (from < 0)
+            return direction === 1 ? firstSelectable() : lastSelectable();
+        let cursor = from;
+        for (let taken = 0; taken < count; taken++) {
+            cursor += direction;
+            if (cursor < 0 || cursor >= count) {
+                if (!loop())
+                    return from;
+                cursor = cursor < 0 ? count - 1 : 0;
+            }
+            if (selectable(cursor))
+                return cursor;
+        }
+        return from;
+    }
+    function moveTo(index) {
+        if (index < 0)
+            return;
+        activeIndex = index;
+        scrollActiveIntoView();
+    }
+    /**
+     * Scrolls the active row far enough to be seen and no further.
+     *
+     * block: 'nearest' rather than 'center', so arrowing one row down moves the
+     * list by one row instead of jumping the whole panel to put that row in the
+     * middle of it.
+     */
+    function scrollActiveIntoView() {
+        const node = panelNode;
+        if (node === null || !open || typeof document === 'undefined')
+            return;
+        const index = activeRow();
+        if (index < 0)
+            return;
+        const row = document.getElementById(optionId(index));
+        if (row === null || !node.contains(row))
+            return;
+        // A DOM without scrollIntoView must not take the keyboard down with it.
+        if (typeof row.scrollIntoView !== 'function')
+            return;
+        row.scrollIntoView({ block: 'nearest' });
+    }
+    function openList(index) {
+        const fallback = activeRow() >= 0 && selectable(activeRow()) ? activeRow() : firstSelectable();
+        const wanted = index === undefined ? fallback : index;
+        activeIndex = wanted >= 0 && wanted < items().length && selectable(wanted) ? wanted : fallback;
+        if (!open) {
+            open = true;
+            listenForOutside();
+            config.onOpenChange?.(true);
+        }
+        scrollActiveIntoView();
+    }
+    function closeList(reason) {
+        // Idempotent because two dismissals race on every outside click: the
+        // pointer closes the list and the focus leaving the field closes it again.
+        if (!open)
+            return;
+        open = false;
+        stopListeningForOutside();
+        config.onOpenChange?.(false);
+        config.onClose?.(reason);
+    }
+    function toggleList() {
+        // A trigger click that closes an open list is a dismissal with nothing
+        // chosen, which is what every consumer of 'outside' already does.
+        if (open)
+            closeList('outside');
+        else
+            openList();
+    }
+    function setActive(index) {
+        if (index < 0) {
+            activeIndex = -1;
+            return;
+        }
+        // A pointer must not put the active ring somewhere the keyboard refuses to
+        // go, or hovering a disabled row promises an Enter that will not fire.
+        if (index >= items().length || !selectable(index))
+            return;
+        moveTo(index);
+    }
+    function selectActive() {
+        const index = activeRow();
+        if (index < 0)
+            return false;
+        const item = items()[index];
+        if (item === undefined || item.disabled === true)
+            return false;
+        config.onSelect(item, index);
+        return true;
+    }
+    /**
+     * Returns focus to the field itself.
+     *
+     * Rows are never in the tab sequence, so focus is usually still on the
+     * trigger and this is a no-op. It matters after a pointer lands on a row,
+     * which focuses it in every browser that supports tabindex -1.
+     */
+    function focusTrigger() {
+        const node = anchorNode;
+        if (node === null)
+            return;
+        const trigger = node.querySelector(TRIGGER);
+        if (trigger !== null)
+            trigger.focus();
+    }
+    /**
+     * Matches the accumulated run against the labels.
+     *
+     * A one-character run searches from the row after the active one, so pressing
+     * N repeatedly cycles the N entries. A longer run searches from the active
+     * row itself, so typing "ne" lands on Netherlands rather than skipping past
+     * the row "n" just reached. Comparison goes through the filter contract's
+     * normalize, so an accent on either side folds away and typing "zu" reaches a
+     * label spelled with an umlaut.
+     */
+    function matchRun(run) {
+        const needle = normalize(run);
+        if (needle === '')
+            return -1;
+        const list = items();
+        if (list.length === 0)
+            return -1;
+        const current = activeRow();
+        const from = run.length === 1 ? Math.max(current, -1) + 1 : Math.max(current, 0);
+        for (let offset = 0; offset < list.length; offset++) {
+            const index = (from + offset) % list.length;
+            if (!selectable(index))
+                continue;
+            if (normalize(list[index].label).startsWith(needle))
+                return index;
+        }
+        return -1;
+    }
+    function handleTypeahead(event) {
+        if (!typeahead())
+            return false;
+        if (event.key.length !== 1)
+            return false;
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return false;
+        // Space opens or chooses on a trigger. It extends a run in progress and
+        // never starts one, so that meaning survives.
+        if (event.key === ' ' && typed === '')
+            return false;
+        // Date.now is a timestamp, not a timer: nothing is scheduled and nothing
+        // has to be cancelled when the control unmounts mid-run.
+        const now = Date.now();
+        typed = now - typedAt > TYPEAHEAD_WINDOW_MS ? event.key : typed + event.key;
+        typedAt = now;
+        if (!open)
+            openList();
+        const index = matchRun(typed);
+        if (index >= 0)
+            moveTo(index);
+        // Consumed either way. The run is open, so the next character extends it
+        // rather than reaching the trigger as a fresh key.
+        event.preventDefault();
+        return true;
+    }
+    function handleKeydown(event) {
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                if (open)
+                    moveTo(step(activeRow(), 1));
+                else
+                    openList(firstSelectable());
+                return true;
+            case 'ArrowUp':
+                event.preventDefault();
+                // Opening on ArrowUp lands on the last row. Autocomplete decremented a
+                // hidden index instead, so the first ArrowUp opened nothing and the
+                // list, once opened, was already scrolled somewhere unexplained.
+                if (open)
+                    moveTo(step(activeRow(), -1));
+                else
+                    openList(lastSelectable());
+                return true;
+            case 'Home':
+                // Closed, Home and End belong to the caret in a combobox input.
+                if (!open)
+                    return false;
+                event.preventDefault();
+                moveTo(firstSelectable());
+                return true;
+            case 'End':
+                if (!open)
+                    return false;
+                event.preventDefault();
+                moveTo(lastSelectable());
+                return true;
+            case 'Enter':
+                // A closed list consumes nothing, so Enter still submits the form.
+                if (!open)
+                    return false;
+                if (!selectActive())
+                    return false;
+                event.preventDefault();
+                return true;
+            case 'Escape':
+                // Only an open list consumes Escape. Unstopped, one press closed both
+                // a listbox and the Modal holding it; consumed while closed, Escape
+                // never reached the Modal at all.
+                if (!open)
+                    return false;
+                event.preventDefault();
+                event.stopPropagation();
+                closeList('escape');
+                focusTrigger();
+                return true;
+            case 'Tab':
+                // Never preventDefault: Tab is how focus leaves the field, and the rows
+                // are out of the tab sequence so there is nothing else for it to reach.
+                closeList('tab');
+                return false;
+            default:
+                return handleTypeahead(event);
+        }
+    }
+    function handlePointerDown(event) {
+        const target = event.target;
+        if (!(target instanceof Node))
+            return;
+        if (anchorNode !== null && anchorNode.contains(target))
+            return;
+        if (panelNode !== null && panelNode.contains(target))
+            return;
+        closeList('outside');
+    }
+    function handleFocusOut(event) {
+        if (!open)
+            return;
+        // relatedTarget is where focus went. A row inside the panel counts as
+        // staying, which is what the 150ms blur timer was standing in for.
+        const next = event.relatedTarget;
+        if (next instanceof Node) {
+            if (anchorNode !== null && anchorNode.contains(next))
+                return;
+            if (panelNode !== null && panelNode.contains(next))
+                return;
+        }
+        closeList('focusout');
+    }
+    function listenForOutside() {
+        if (listening || typeof document === 'undefined')
+            return;
+        // pointerdown, not click: a press that starts outside has already dismissed
+        // the list by the time the click lands, so the click reaches what the user
+        // aimed at instead of being spent closing the panel.
+        document.addEventListener('pointerdown', handlePointerDown, true);
+        listening = true;
+    }
+    function stopListeningForOutside() {
+        if (!listening || typeof document === 'undefined')
+            return;
+        document.removeEventListener('pointerdown', handlePointerDown, true);
+        listening = false;
+    }
+    function anchor(node) {
+        anchorNode = node;
+        node.addEventListener('focusout', handleFocusOut);
+        if (open)
+            listenForOutside();
+        return {
+            destroy() {
+                node.removeEventListener('focusout', handleFocusOut);
+                stopListeningForOutside();
+                if (anchorNode === node)
+                    anchorNode = null;
+            },
+        };
+    }
+    function panel(node) {
+        panelNode = node;
+        // The rows exist for the first time here, so this is where a list opened at
+        // its last row gets scrolled to it.
+        scrollActiveIntoView();
+        return {
+            destroy() {
+                if (panelNode === node)
+                    panelNode = null;
+            },
+        };
+    }
+    return {
+        get open() {
+            return open;
+        },
+        get activeIndex() {
+            return activeRow();
+        },
+        get triggerAttrs() {
+            const index = activeRow();
+            return {
+                'aria-haspopup': 'listbox',
+                'aria-expanded': open ? 'true' : 'false',
+                // Both point at elements that exist only while the panel is mounted. A
+                // dangling idref is announced as nothing, which reads to the user as a
+                // control that has stopped responding.
+                'aria-controls': open ? listId() : undefined,
+                'aria-activedescendant': open && index >= 0 ? optionId(index) : undefined,
+            };
+        },
+        get listAttrs() {
+            // A menu spreads these and then states role="menu" and its own
+            // aria-haspopup: the later attribute wins, and the id and the open state
+            // are the parts worth sharing.
+            return { id: listId(), role: 'listbox' };
+        },
+        optionAttrs(index) {
+            const item = items()[index];
+            return {
+                id: optionId(index),
+                role: 'option',
+                // Out of the tab sequence on purpose: focus stays on the trigger and
+                // the active row travels by aria-activedescendant. As plain buttons the
+                // rows put every option between the field and the next control.
+                tabindex: -1,
+                'aria-disabled': item?.disabled === true ? 'true' : undefined,
+            };
+        },
+        openList,
+        close: closeList,
+        toggle: toggleList,
+        setActive,
+        onkeydown: handleKeydown,
+        anchor,
+        panel,
+    };
+}

package/dist/internal/nav-expansion.svelte.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which groups in a sidebar are open, and why.
+ *
+ * Expansion looks like one boolean per group and is really three sources
+ * disagreeing: the tree says a group ships open, the current page says its
+ * ancestors have to be open or the reader cannot see where they are, and the
+ * reader says they closed that group and meant it. A component that keeps a
+ * flat set of open ids loses the third one the moment the second changes,
+ * which is how a group reopens itself every time the reader navigates inside
+ * it.
+ *
+ * So the state here is not "open ids". It is the decisions the reader has
+ * made, which are the only part worth persisting, and a default computed from
+ * the tree and the path underneath them. A reader decision always wins, and
+ * until there is one the group follows the page.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+import { type NavTree } from './nav-tree.js';
+export interface NavExpansionOptions {
+    items: () => NavTree;
+    activePath: () => string;
+    /** Open the ancestors of the current page. */
+    expandActive: () => boolean;
+    /** Only one group open at a time. */
+    exclusive: () => boolean;
+    /** localStorage key. Undefined keeps expansion in memory. */
+    storageKey: () => string | undefined;
+}
+export interface NavExpansion {
+    readonly isExpanded: (id: string) => boolean;
+    toggle(id: string): void;
+    expand(id: string): void;
+    collapse(id: string): void;
+}
+export declare function createNavExpansion(options: NavExpansionOptions): NavExpansion;

package/dist/internal/nav-expansion.svelte.js

@@ -0,0 +1,144 @@
+/**
+ * Which groups in a sidebar are open, and why.
+ *
+ * Expansion looks like one boolean per group and is really three sources
+ * disagreeing: the tree says a group ships open, the current page says its
+ * ancestors have to be open or the reader cannot see where they are, and the
+ * reader says they closed that group and meant it. A component that keeps a
+ * flat set of open ids loses the third one the moment the second changes,
+ * which is how a group reopens itself every time the reader navigates inside
+ * it.
+ *
+ * So the state here is not "open ids". It is the decisions the reader has
+ * made, which are the only part worth persisting, and a default computed from
+ * the tree and the path underneath them. A reader decision always wins, and
+ * until there is one the group follows the page.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+import { activeTrail, flattenNav } from './nav-tree.js';
+/**
+ * localStorage is absent on the server and throws on access in a private
+ * window and wherever the reader has blocked site data, so it is reached for
+ * behind both a typeof guard and a catch. Expansion is a convenience; nothing
+ * here may be the reason a sidebar fails to render.
+ */
+function storage() {
+    try {
+        return typeof localStorage === 'undefined' ? undefined : localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readStored(key) {
+    if (!key)
+        return {};
+    const store = storage();
+    if (!store)
+        return {};
+    try {
+        const raw = store.getItem(key);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        // Another version of the app, or a reader editing the value by hand, can
+        // leave anything at all under this key. Only booleans survive the read.
+        const out = {};
+        for (const [id, open] of Object.entries(parsed)) {
+            if (typeof open === 'boolean')
+                out[id] = open;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function writeStored(key, value) {
+    if (!key)
+        return;
+    const store = storage();
+    if (!store)
+        return;
+    try {
+        store.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // A private window answers a write with a quota error. The session keeps
+        // its expansion in memory instead.
+    }
+}
+function hasChildren(node) {
+    return Array.isArray(node.children) && node.children.length > 0;
+}
+export function createNavExpansion(options) {
+    // Read once, with the key the sidebar mounted with. A key that changes later
+    // names a different sidebar, which is a different component instance.
+    const key = options.storageKey();
+    /** The reader's own decisions. An id absent here has not been decided. */
+    let overrides = $state(readStored(key));
+    const trail = $derived(options.expandActive()
+        ? new Set(activeTrail(options.items(), options.activePath()))
+        : new Set());
+    const nodes = $derived(flattenNav(options.items()));
+    function commit(next) {
+        overrides = next;
+        writeStored(key, next);
+    }
+    function ancestorsOf(id) {
+        const walk = (branch, chain) => {
+            for (const node of branch) {
+                if (node.id === id)
+                    return chain;
+                if (node.children && node.children.length > 0) {
+                    const found = walk(node.children, [...chain, node.id]);
+                    if (found)
+                        return found;
+                }
+            }
+            return undefined;
+        };
+        return walk(options.items(), []) ?? [];
+    }
+    function isExpanded(id) {
+        if (Object.prototype.hasOwnProperty.call(overrides, id))
+            return overrides[id];
+        if (nodes.some((entry) => entry.node.id === id && entry.node.defaultExpanded))
+            return true;
+        return trail.has(id);
+    }
+    function expand(id) {
+        if (!options.exclusive()) {
+            commit({ ...overrides, [id]: true });
+            return;
+        }
+        // Exclusive closes every other group, except the ones the opened node sits
+        // inside: collapsing an ancestor would hide the group that was just asked
+        // for. Ids the tree no longer holds keep whatever they had, so a stored
+        // key survives a tree that has not finished loading.
+        const keep = new Set([id, ...ancestorsOf(id)]);
+        const next = { ...overrides };
+        for (const { node } of nodes) {
+            if (hasChildren(node))
+                next[node.id] = keep.has(node.id);
+        }
+        commit(next);
+    }
+    function collapse(id) {
+        // Descendants keep their own decisions. They are not on screen while this
+        // group is shut, and reopening it should restore what the reader left.
+        commit({ ...overrides, [id]: false });
+    }
+    function toggle(id) {
+        if (isExpanded(id)) {
+            collapse(id);
+        }
+        else {
+            expand(id);
+        }
+    }
+    return { isExpanded, toggle, expand, collapse };
+}

package/dist/internal/nav-tree.d.ts

@@ -0,0 +1,68 @@
+/**
+ * How a sidebar decides which of its links is the current page.
+ *
+ * The rule every app shell reaches for is
+ *
+ *     pathname === href || pathname.startsWith(href + '/')
+ *
+ * applied to every entry in the list. It is wrong in two ways that only show
+ * up once the list has more than one level. A parent link keeps claiming the
+ * page while the reader is on one of its children, so a settings sub-page
+ * lights two rows at once and neither of them is where the reader is. And two
+ * leaves where one href is a prefix of the other, /settings beside
+ * /settings/team, mark themselves together for the same reason, even though
+ * they are siblings and only one of them can be open.
+ *
+ * The fix is that prefix matching is a property of a node that owns a section,
+ * not of every node. A leaf answers for its own path and nothing below it; a
+ * node with children answers for its whole subtree, because that is what makes
+ * an ancestor able to say "you are somewhere in here" while its child says
+ * "you are here". Either default is overridable per node, and 'none' opts a
+ * node out of path matching entirely.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+import type { Component } from 'svelte';
+import type { AccentTone } from './tone.js';
+export interface NavNode {
+    /** Stable across renders. aria-controls is built from it and an each is keyed by it. */
+    id: string;
+    label: string;
+    href?: string;
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    children?: NavNode[];
+    /** A count or status beside the label. */
+    badge?: string | number;
+    badgeTone?: AccentTone;
+    /** Open on first render. */
+    defaultExpanded?: boolean;
+    /** How activePath matches. Defaults to 'exact' for a leaf and 'prefix' for a node with children. */
+    match?: 'exact' | 'prefix' | 'none';
+    disabled?: boolean;
+}
+export type NavTree = NavNode[];
+/**
+ * True when this node is the current page.
+ *
+ * Path only. A disabled node still reports the truth about its href; whether
+ * it is rendered as a link is a separate decision the component makes.
+ */
+export declare function isActive(node: NavNode, activePath: string): boolean;
+/**
+ * The ids from the root down to the matched leaf, so its ancestors can open
+ * and mark themselves.
+ *
+ * Children are searched before the node itself, so a group never shadows the
+ * child that holds the more specific answer. The first match in document order
+ * wins: two nodes claiming one path is a tree the author has to fix, and
+ * silently picking one of them by length would hide it.
+ */
+export declare function activeTrail(items: NavTree, activePath: string): string[];
+/** Depth-first flatten, for tests and for keyboard order. */
+export declare function flattenNav(items: NavTree): {
+    node: NavNode;
+    depth: number;
+}[];