@lyeve-labs/ui-kit 0.11.2 → 0.13.0

package/dist/internal/layout.js

@@ -0,0 +1,132 @@
+/**
+ * The single source of truth for how a page, a card, a table and a modal are
+ * spaced.
+ *
+ * Nothing in the library owned the page frame, so every page invented one. The
+ * same gutter ships in four spellings, five content caps are in use with no
+ * rule for picking between them, a section heading is spelled fourteen ways,
+ * and card surfaces are hand-rolled in nine paddings while Card itself goes
+ * unused. The components disagree with each other too: Card pads its header
+ * 16px down and its footer 12px down for no reason a reader can infer, and
+ * Modal insets its panel 20px where Dialog insets the same kind of panel 24px.
+ *
+ * Every value composes from a `--spacing-*` token rather than a Tailwind
+ * number. That is the only thing that makes the tokens real. Of the ten the
+ * theme declares, `--spacing-control` was the one with any uses, and it had
+ * them because the field contract composes from it.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * The gutter a page sits in, stated once.
+ *
+ * Two pages in the same shell started their content at different distances
+ * from the edge because each spelled its own gutter. The horizontal and
+ * vertical tokens resolve to the same 24px and keep separate names, so a
+ * design that wants a taller page gutter changes one token, not every page.
+ */
+export const PAGE_PAD = 'mx-auto w-full px-page-x py-page-y';
+/**
+ * Content cap by name. Four named slots replace the five raw max-w values
+ * chosen per page with no rule.
+ *
+ * `narrow` is one column: a form, a settings pane, a page of prose. `default`
+ * is a page of stacked cards. `wide` is a data page whose table needs the
+ * room. `full` opts out, for a canvas or a split pane that owns the viewport.
+ * The names carry the decision, so a page picks a role rather than a number.
+ */
+export const PAGE_WIDTH = {
+    narrow: 'max-w-3xl',
+    default: 'max-w-5xl',
+    wide: 'max-w-7xl',
+    full: 'max-w-full',
+};
+/**
+ * The vertical rhythm between a page's top-level sections. A property of the
+ * shell, so a page cannot choose its own.
+ *
+ * PageHeader already drops 32px below the title and every page that sets a
+ * section gap sets the same 32px, so the value was agreed and unstated. A gap
+ * on the shell also means adding a section is appending a child, rather than
+ * remembering to put a margin on it.
+ */
+export const PAGE_STACK = 'flex flex-col gap-section';
+/**
+ * The card surface, without its padding.
+ *
+ * Padding is separate because a card wrapping a table or a list wants its
+ * children flush to the border. `overflow-hidden` is deliberately absent: the
+ * focus ring sits 2px outside the element it belongs to, so a clipping surface
+ * crops the ring of every button inside it down to whichever edge fits.
+ */
+export const CARD_SURFACE = 'bg-surface border border-line rounded-xl';
+/**
+ * Card padding by name.
+ *
+ * `md` is the 20px the theme names `--spacing-card`: the measured mode across
+ * the card surfaces in use, and what Card itself paints. `lg` is the page
+ * gutter, so a card padded `lg` holds its content on the same rhythm as the
+ * page around it. Nine hand-rolled paddings collapse onto these four.
+ */
+export const CARD_PAD = {
+    none: '',
+    sm: 'p-card-sm',
+    md: 'p-card',
+    lg: 'p-page-x',
+};
+/**
+ * The band above a card's content.
+ *
+ * Card insets its header 20px across and 16px down, and its footer 20px across
+ * and 12px down. Nothing tells the two bands apart, so they share one inset
+ * here and differ only in which edge carries the rule.
+ */
+export const CARD_HEADER = 'px-card py-card-sm border-b border-line';
+/** The band below a card's content. CARD_HEADER's inset, with the rule on top. */
+export const CARD_FOOTER = 'px-card py-card-sm border-t border-line bg-surface-2/40';
+/**
+ * A placeholder inside a card, where three spellings of the same centred muted
+ * line currently ship.
+ *
+ * An empty list is not an error, so it reads as muted body copy and not as a
+ * warning. The section gap above and below keeps a card holding nothing from
+ * collapsing to a single line of text.
+ */
+export const CARD_EMPTY = 'py-section text-center text-sm text-muted';
+/**
+ * The head cell of a table: its padding and the type treatment that marks it
+ * as a label rather than data.
+ *
+ * The hand-rolled tables split four ways on cell padding, so two tables on one
+ * page ran at different row heights. Horizontal is the compact card step, so a
+ * full-bleed table inside a card lines its first column up with the card's own
+ * text. Vertical is the control step: 12px and 8px were both already in use in
+ * near equal numbers, and 8px is the one the token scale names.
+ */
+export const TABLE_CELL_HEAD = 'px-card-sm py-input-y text-xs font-medium uppercase tracking-wider whitespace-nowrap text-faint';
+/** The body cell of a table. TABLE_CELL_HEAD's padding, at body weight and colour. */
+export const TABLE_CELL_BODY = 'px-card-sm py-input-y text-fg align-middle';
+/**
+ * The gutter every modal surface uses. Modal paints 20px and Dialog paints
+ * 24px for the same kind of surface.
+ *
+ * A dialog opened over a modal showed both insets at once. A modal panel is a
+ * card lifted off the page, so a banded modal takes CARD_HEADER and
+ * CARD_FOOTER, which resolve to this same inset.
+ */
+export const MODAL_PAD = 'px-card py-card-sm';
+/**
+ * A section heading below the page title. Level 2 sits under the title, level 3
+ * inside a card.
+ *
+ * Fourteen distinct class strings serve this role, so two sections on the same
+ * page can render at different sizes and weights. Taking the level rather than
+ * a free-form string means the class cannot disagree with the heading element
+ * the caller is already writing.
+ */
+export function sectionHeading(level) {
+    // Level 3 drops a size rather than a weight. Inside a card it sits under the
+    // card's own semibold title, and two semibold lines at the same size read as
+    // one heading broken in half.
+    return level === 2 ? 'text-lg font-semibold text-fg' : 'text-sm font-semibold text-fg';
+}

package/dist/internal/listbox.svelte.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+/** The least a row has to be for the keyboard model to work on it. */
+export interface ListboxItem {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * Why the list closed. A consumer that resets a search query on dismissal but
+ * keeps it on a pick needs to tell the two apart, and the four controls each
+ * guessed.
+ */
+export type ListboxCloseReason = 'escape' | 'select' | 'outside' | 'focusout' | 'tab';
+export interface ListboxConfig<T extends ListboxItem> {
+    items: () => readonly T[];
+    /** Stable across the SSR boundary. Pass $props.id(). */
+    baseId: () => string;
+    onSelect: (item: T, index: number) => void;
+    onOpenChange?: (open: boolean) => void;
+    onClose?: (reason: ListboxCloseReason) => void;
+    /** Typeahead jumps to the next item whose label starts with the typed run. Off for a control with its own text input, where letters are query text. */
+    typeahead?: () => boolean;
+    /** The active row wraps past the ends. */
+    loop?: () => boolean;
+}
+export interface Listbox {
+    readonly open: boolean;
+    readonly activeIndex: number;
+    /** Attributes for the trigger or the combobox input. */
+    readonly triggerAttrs: Record<string, string | undefined>;
+    /** Attributes for the panel. */
+    readonly listAttrs: Record<string, string | undefined>;
+    /** Attributes for one row. tabindex is -1: focus stays on the trigger and position travels by aria-activedescendant. */
+    optionAttrs(index: number): Record<string, string | number | undefined>;
+    openList(active?: number): void;
+    close(reason: ListboxCloseReason): void;
+    toggle(): void;
+    setActive(index: number): void;
+    /** Returns true when it consumed the event. */
+    onkeydown(event: KeyboardEvent): boolean;
+    /** use:listbox.anchor on the wrapper. Registers outside-click and focusout dismissal. */
+    anchor: (node: HTMLElement) => {
+        destroy(): void;
+    };
+    /** use:listbox.panel on the panel. Keeps the active row scrolled into view. */
+    panel: (node: HTMLElement) => {
+        destroy(): void;
+    };
+}
+export declare function createListbox<T extends ListboxItem>(config: ListboxConfig<T>): Listbox;

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;