@pienter/ui 0.2.0 → 0.5.0

package/utils/controllers/sidebar.ts

@@ -1,610 +0,0 @@
-import { createFocusTrap, type FocusTrap } from '../a11y/focus.js';
-import { lockScroll } from '../dom/scroll-lock.js';
-
-/**
- * Imperative control surface returned by `mountSidebar`.
- *
- * Three independent state-machines composed inside one controller:
- * 1. Desktop collapse/expand — narrows the panel to icon-only width.
- * 2. Mobile drawer open/closed — overlay slide-in with focus trap +
- *    body-scroll lock; only meaningful below `drawerBreakpoint`.
- * 3. Per-group expand/collapse — each group identified by a stable
- *    string key; multiple groups may be expanded at once.
- *
- * Plus: roving-tabindex keyboard navigation across menu items.
- *
- * The controller is the source of truth for runtime side-effects
- * (DOM attributes, focus, scroll lock, listeners). The framework
- * (Vue prop / Astro consumer script) is the trigger source — it
- * calls `collapse()` / `openDrawer()` / `expandGroup()` and reflects
- * controller-emitted callbacks back into reactive state.
- */
-export interface SidebarControl {
-    // Desktop collapse state.
-    collapse(): void;
-    expand(): void;
-    isCollapsed(): boolean;
-
-    // Mobile drawer state.
-    openDrawer(): void;
-    closeDrawer(): void;
-    isDrawerOpen(): boolean;
-
-    // Per-group expand/collapse.
-    expandGroup(groupKey: string): void;
-    collapseGroup(groupKey: string): void;
-    isGroupExpanded(groupKey: string): boolean;
-
-    /** Re-derive `aria-current="page"` for every link from the new active href. */
-    setActiveHref(href: string | null | undefined): void;
-
-    /** Release listeners, focus trap, scroll lock, and stored references. */
-    teardown(): void;
-}
-
-export interface SidebarConfig {
-    /** Initial desktop collapsed state. Default `false`. */
-    collapsed?: boolean;
-    /** Initial mobile drawer state. Default `false`. */
-    drawerOpen?: boolean;
-    /**
-     * Pixel breakpoint below which drawer mode applies. Above this
-     * width, the sidebar is a persistent column and drawer state has no
-     * visual effect (the controller still tracks it but
-     * `[data-drawer-state]` is meaningful only with the mobile-drawer
-     * CSS media query). Default `768`.
-     */
-    drawerBreakpoint?: number;
-    /** Initial set of expanded group keys. */
-    expandedGroups?: string[];
-    /** Initial active href used to derive `aria-current="page"`. */
-    activeHref?: string | null;
-    /**
-     * Called after the user toggles the desktop collapse via internal
-     * affordances (none in v1 — collapse is consumer-driven only).
-     * Reserved for symmetry with other change callbacks.
-     */
-    onCollapsedChange?: (collapsed: boolean) => void;
-    /**
-     * Called when the user requests drawer close (Escape, backdrop
-     * click). Mirrors `mountDialog`'s `onClose` — controller does NOT
-     * auto-close; the caller flips its reactive state and calls
-     * `closeDrawer()`.
-     */
-    onDrawerOpenChange?: (open: boolean) => void;
-    /** Called when a group's expanded state changes via internal affordance (toggle click, keyboard). */
-    onGroupExpandedChange?: (groupKey: string, expanded: boolean) => void;
-}
-
-// DOM hooks — locked markup contract between controller and component templates.
-const PANEL_SELECTOR = '[data-sidebar-panel]';
-const BACKDROP_SELECTOR = '[data-sidebar-backdrop]';
-const MENU_ITEM_SELECTOR =
-    '[data-sidebar-menu-item]:not([data-disabled="true"])';
-const GROUP_SELECTOR = '[data-sidebar-group]';
-const GROUP_TOGGLE_SELECTOR = '[data-sidebar-group-toggle]';
-const GROUP_ITEMS_SELECTOR = '[data-sidebar-group-items]';
-const LINK_SELECTOR = '[data-sidebar-link]';
-
-/**
- * Hierarchical-href match — locked algorithm. Returns true when
- * `itemHref` is the prefix of `activeHref` honoring path boundaries.
- *
- * - `/` (root) is special-cased to strict equality so it doesn't
- *   greedily match every URL.
- * - Substring-only matches are rejected (`/admin/members-old` does
- *   NOT match `/admin/members`).
- *
- * See CONVENTIONS.md § Active-href hierarchical-match algorithm.
- */
-export function isHrefActive(
-    activeHref: string | null | undefined,
-    itemHref: string,
-): boolean {
-    if (!activeHref) return false;
-    if (itemHref === '/') return activeHref === '/';
-    if (activeHref === itemHref) return true;
-    return activeHref.startsWith(itemHref + '/');
-}
-
-export function mountSidebar(
-    el: HTMLElement,
-    config: SidebarConfig = {},
-): SidebarControl {
-    const onClose = config.onDrawerOpenChange;
-    const onGroup = config.onGroupExpandedChange;
-
-    // Internal state.
-    let collapsedState = config.collapsed ?? false;
-    let drawerOpenState = false; // start closed; if config.drawerOpen, open() is called below
-    const expandedGroups = new Set<string>(config.expandedGroups ?? []);
-    let activeHref = config.activeHref ?? null;
-
-    // Drawer-only transient state.
-    let trap: FocusTrap | null = null;
-    let unlockScrollFn: (() => void) | null = null;
-    let triggerEl: HTMLElement | null = null;
-    // Whether the controller installed `aria-label` on the panel during
-    // openDrawer(). Used in closeDrawer() so we only strip the attribute
-    // we added — a consumer-supplied `aria-label` on the panel must not
-    // be clobbered.
-    let panelAriaLabelSetByController = false;
-    // Tracks whether THIS controller added the `tabindex="-1"` fallback to
-    // the panel (when no focusable menu item existed at open time). If we
-    // set it, we own removing it on close so the attribute doesn't persist
-    // across open/close cycles. Mirrors `dialog.ts`'s `tabindexWasSetByUs`.
-    let panelTabindexWasSetByController = false;
-    const panel = el.querySelector<HTMLElement>(PANEL_SELECTOR) ?? el;
-
-    // ---------------------------------------------------------------------------
-    // Initial DOM sync.
-    // ---------------------------------------------------------------------------
-
-    el.setAttribute('data-state', collapsedState ? 'collapsed' : 'expanded');
-    el.setAttribute('data-drawer-state', 'closed');
-
-    // Sync per-group state from config.expandedGroups + the markup-level
-    // `data-default-open` hint that templates emit for groups whose item
-    // declared `defaultOpen: true`. The Set wins when both are present.
-    el.querySelectorAll<HTMLElement>(GROUP_SELECTOR).forEach((groupEl) => {
-        const key = groupEl.dataset.groupKey ?? '';
-        if (!key) return;
-        const defaultOpen = groupEl.dataset.defaultOpen === 'true';
-        if (defaultOpen && !config.expandedGroups) {
-            // Only honor markup defaults when the consumer didn't pass an
-            // explicit expandedGroups override.
-            expandedGroups.add(key);
-        }
-        syncGroupAttrs(groupEl, key, expandedGroups.has(key));
-    });
-
-    // Wire active-href.
-    applyActiveHref();
-
-    // Wire roving-tabindex initial state.
-    syncRovingTabindex();
-
-    // ---------------------------------------------------------------------------
-    // Listeners.
-    // ---------------------------------------------------------------------------
-
-    el.addEventListener('click', handleClick);
-    el.addEventListener('keydown', handleKeydown);
-    el.addEventListener('focusin', handleFocusIn);
-
-    function handleClick(event: MouseEvent): void {
-        const target = event.target;
-        if (!(target instanceof Element)) return;
-
-        // Backdrop click → close drawer.
-        const backdrop = target.closest(BACKDROP_SELECTOR);
-        if (backdrop && drawerOpenState) {
-            onClose?.(false);
-            return;
-        }
-
-        // Group toggle click → toggle expand state.
-        const toggle = target.closest<HTMLElement>(GROUP_TOGGLE_SELECTOR);
-        if (toggle) {
-            const group = toggle.closest<HTMLElement>(GROUP_SELECTOR);
-            if (!group) return;
-            const key = group.dataset.groupKey ?? '';
-            if (!key) return;
-            const next = !expandedGroups.has(key);
-            if (next) {
-                expandedGroups.add(key);
-            } else {
-                expandedGroups.delete(key);
-            }
-            syncGroupAttrs(group, key, next);
-            // After expand/collapse, the visible-item set changed; refresh
-            // the roving tabindex so keyboard nav skips collapsed children.
-            syncRovingTabindex();
-            onGroup?.(key, next);
-        }
-    }
-
-    function handleKeydown(event: KeyboardEvent): void {
-        // Escape closes the drawer when open (only meaningful on mobile).
-        if (event.key === 'Escape' && drawerOpenState) {
-            event.preventDefault();
-            onClose?.(false);
-            return;
-        }
-
-        const target = event.target;
-        if (!(target instanceof HTMLElement)) return;
-        const item = target.closest<HTMLElement>(MENU_ITEM_SELECTOR);
-        if (!item) return;
-
-        switch (event.key) {
-            case 'ArrowDown': {
-                event.preventDefault();
-                const items = visibleMenuItems();
-                const idx = items.indexOf(item);
-                const next = items[Math.min(idx + 1, items.length - 1)];
-                if (next) focusItem(next);
-                return;
-            }
-            case 'ArrowUp': {
-                event.preventDefault();
-                const items = visibleMenuItems();
-                const idx = items.indexOf(item);
-                const next = items[Math.max(idx - 1, 0)];
-                if (next) focusItem(next);
-                return;
-            }
-            case 'Home': {
-                event.preventDefault();
-                const items = visibleMenuItems();
-                if (items[0]) focusItem(items[0]);
-                return;
-            }
-            case 'End': {
-                event.preventDefault();
-                const items = visibleMenuItems();
-                const last = items[items.length - 1];
-                if (last) focusItem(last);
-                return;
-            }
-            case 'ArrowRight': {
-                // On a group toggle: if collapsed, expand; if already expanded,
-                // move into first child item.
-                if (item.matches(GROUP_TOGGLE_SELECTOR)) {
-                    event.preventDefault();
-                    const group = item.closest<HTMLElement>(GROUP_SELECTOR);
-                    if (!group) return;
-                    const key = group.dataset.groupKey ?? '';
-                    if (!expandedGroups.has(key)) {
-                        expandedGroups.add(key);
-                        syncGroupAttrs(group, key, true);
-                        syncRovingTabindex();
-                        onGroup?.(key, true);
-                    } else {
-                        const groupItems =
-                            group.querySelector<HTMLElement>(
-                                GROUP_ITEMS_SELECTOR,
-                            );
-                        const firstChild =
-                            groupItems?.querySelector<HTMLElement>(
-                                MENU_ITEM_SELECTOR,
-                            );
-                        if (firstChild) focusItem(firstChild);
-                    }
-                }
-                return;
-            }
-            case 'ArrowLeft': {
-                // On a child of an expanded group: collapse parent group and
-                // move focus to its toggle.
-                const parentGroup =
-                    item.parentElement?.closest<HTMLElement>(GROUP_SELECTOR);
-                if (parentGroup && !item.matches(GROUP_TOGGLE_SELECTOR)) {
-                    event.preventDefault();
-                    const key = parentGroup.dataset.groupKey ?? '';
-                    if (expandedGroups.has(key)) {
-                        expandedGroups.delete(key);
-                        syncGroupAttrs(parentGroup, key, false);
-                        syncRovingTabindex();
-                        onGroup?.(key, false);
-                    }
-                    const toggle = parentGroup.querySelector<HTMLElement>(
-                        GROUP_TOGGLE_SELECTOR,
-                    );
-                    if (toggle) focusItem(toggle);
-                }
-                return;
-            }
-            case ' ': // Space
-            case 'Spacebar': {
-                // Native button activation handles Space on the group toggle
-                // already; for `<a>` links we forward Space to a click so links
-                // feel button-like inside a menu.
-                if (item.matches(LINK_SELECTOR)) {
-                    event.preventDefault();
-                    item.click();
-                }
-                return;
-            }
-            default:
-                return;
-        }
-    }
-
-    function handleFocusIn(event: FocusEvent): void {
-        const target = event.target;
-        if (!(target instanceof HTMLElement)) return;
-        const item = target.closest<HTMLElement>(MENU_ITEM_SELECTOR);
-        if (!item) return;
-        // Promote the focused item to tabindex=0; demote the previous.
-        const items = el.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR);
-        items.forEach((it) => {
-            it.setAttribute('tabindex', it === item ? '0' : '-1');
-        });
-    }
-
-    // ---------------------------------------------------------------------------
-    // Public API.
-    // ---------------------------------------------------------------------------
-
-    function collapse(): void {
-        if (collapsedState) return;
-        collapsedState = true;
-        el.setAttribute('data-state', 'collapsed');
-    }
-
-    function expand(): void {
-        if (!collapsedState) return;
-        collapsedState = false;
-        el.setAttribute('data-state', 'expanded');
-    }
-
-    function isCollapsed(): boolean {
-        return collapsedState;
-    }
-
-    function openDrawer(): void {
-        if (drawerOpenState) return;
-        drawerOpenState = true;
-
-        // Capture trigger for restore-on-close.
-        const active = document.activeElement;
-        triggerEl =
-            active instanceof HTMLElement &&
-            active !== document.body &&
-            !el.contains(active)
-                ? active
-                : null;
-
-        el.setAttribute('data-drawer-state', 'open');
-
-        // Promote the panel to a modal dialog while drawer is open.
-        // ARIA requires `role="dialog"` to have an accessible name, so
-        // mirror the wrapper `<nav>`'s `aria-label` onto the panel. If the
-        // panel already has its own `aria-label` (consumer-supplied), leave
-        // it alone — closeDrawer() only strips what we added.
-        panel.setAttribute('role', 'dialog');
-        panel.setAttribute('aria-modal', 'true');
-        if (!panel.hasAttribute('aria-label')) {
-            const wrapperLabel = el.getAttribute('aria-label') ?? 'Navigation';
-            panel.setAttribute('aria-label', wrapperLabel);
-            panelAriaLabelSetByController = true;
-        }
-
-        unlockScrollFn = lockScroll();
-        trap = createFocusTrap(panel);
-
-        // Move focus inside the panel — first menu item, deferred a frame
-        // so any CSS slide-in transition doesn't race with focus.
-        requestAnimationFrame(() => {
-            if (!drawerOpenState) return;
-            const first = visibleMenuItems()[0];
-            if (first) {
-                focusItem(first);
-            } else {
-                // Fall back to focusing the panel so screen readers announce
-                // the drawer. The panel needs to be focusable; if it isn't,
-                // give it tabindex=-1 transiently. Track that we set it so
-                // closeDrawer() can remove it again — we don't want to leave a
-                // stray `tabindex` on the panel across open/close cycles.
-                if (!panel.hasAttribute('tabindex')) {
-                    panel.setAttribute('tabindex', '-1');
-                    panelTabindexWasSetByController = true;
-                }
-                panel.focus();
-            }
-        });
-    }
-
-    function closeDrawer(): void {
-        if (!drawerOpenState) return;
-        drawerOpenState = false;
-
-        el.setAttribute('data-drawer-state', 'closed');
-        panel.removeAttribute('role');
-        panel.removeAttribute('aria-modal');
-        if (panelAriaLabelSetByController) {
-            panel.removeAttribute('aria-label');
-            panelAriaLabelSetByController = false;
-        }
-        // If we added the transient `tabindex="-1"` focus fallback in
-        // openDrawer(), remove it now so it doesn't persist across
-        // open/close cycles.
-        if (panelTabindexWasSetByController) {
-            panel.removeAttribute('tabindex');
-            panelTabindexWasSetByController = false;
-        }
-
-        trap?.release();
-        trap = null;
-
-        unlockScrollFn?.();
-        unlockScrollFn = null;
-
-        // Restore focus to the trigger that opened the drawer.
-        const trigger = triggerEl;
-        triggerEl = null;
-        if (trigger && document.contains(trigger)) {
-            requestAnimationFrame(() => trigger.focus());
-        }
-    }
-
-    function isDrawerOpen(): boolean {
-        return drawerOpenState;
-    }
-
-    function expandGroup(key: string): void {
-        if (!key || expandedGroups.has(key)) return;
-        expandedGroups.add(key);
-        const group = findGroup(key);
-        if (group) {
-            syncGroupAttrs(group, key, true);
-            syncRovingTabindex();
-        }
-    }
-
-    function collapseGroup(key: string): void {
-        if (!key || !expandedGroups.has(key)) return;
-        expandedGroups.delete(key);
-        const group = findGroup(key);
-        if (group) {
-            syncGroupAttrs(group, key, false);
-            syncRovingTabindex();
-        }
-    }
-
-    function isGroupExpanded(key: string): boolean {
-        return expandedGroups.has(key);
-    }
-
-    function setActiveHref(href: string | null | undefined): void {
-        activeHref = href ?? null;
-        applyActiveHref();
-        // Active item changed — re-roving-tabindex so the active item gets
-        // tabindex=0 (or the first item if no active match).
-        syncRovingTabindex();
-    }
-
-    function teardown(): void {
-        if (drawerOpenState) closeDrawer();
-        el.removeEventListener('click', handleClick);
-        el.removeEventListener('keydown', handleKeydown);
-        el.removeEventListener('focusin', handleFocusIn);
-    }
-
-    // ---------------------------------------------------------------------------
-    // Internal helpers.
-    // ---------------------------------------------------------------------------
-
-    function findGroup(key: string): HTMLElement | null {
-        return el.querySelector<HTMLElement>(
-            `${GROUP_SELECTOR}[data-group-key="${cssEscape(key)}"]`,
-        );
-    }
-
-    function syncGroupAttrs(
-        group: HTMLElement,
-        _key: string,
-        expanded: boolean,
-    ): void {
-        group.setAttribute('data-state', expanded ? 'expanded' : 'collapsed');
-        const toggle = group.querySelector<HTMLElement>(GROUP_TOGGLE_SELECTOR);
-        if (toggle)
-            toggle.setAttribute('aria-expanded', expanded ? 'true' : 'false');
-        const items = group.querySelector<HTMLElement>(GROUP_ITEMS_SELECTOR);
-        if (items) items.hidden = !expanded;
-    }
-
-    function applyActiveHref(): void {
-        const links = el.querySelectorAll<HTMLAnchorElement>(LINK_SELECTOR);
-        links.forEach((link) => {
-            const href = link.getAttribute('href') ?? '';
-            const active = isHrefActive(activeHref, href);
-            if (active) {
-                link.setAttribute('aria-current', 'page');
-            } else {
-                link.removeAttribute('aria-current');
-            }
-        });
-
-        // Group active-state — true when any descendant link is active.
-        el.querySelectorAll<HTMLElement>(GROUP_SELECTOR).forEach((group) => {
-            const hasActive = !!group.querySelector('[aria-current="page"]');
-            if (hasActive) {
-                group.setAttribute('data-active', 'true');
-            } else {
-                group.removeAttribute('data-active');
-            }
-        });
-    }
-
-    function visibleMenuItems(): HTMLElement[] {
-        // Items that aren't disabled, aren't hidden by an ancestor with
-        // `hidden`, and aren't inside a collapsed group.
-        return Array.from(
-            el.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
-        ).filter((item) => !isInsideCollapsedGroup(item));
-    }
-
-    function isInsideCollapsedGroup(item: HTMLElement): boolean {
-        // Walk up looking for an ancestor `[data-sidebar-group-items]` that
-        // is hidden — if found, the item is inside a collapsed group.
-        let cur: HTMLElement | null = item.parentElement;
-        while (cur && cur !== el) {
-            if (cur.matches(GROUP_ITEMS_SELECTOR) && cur.hidden) return true;
-            cur = cur.parentElement;
-        }
-        return false;
-    }
-
-    function syncRovingTabindex(): void {
-        const items = Array.from(
-            el.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
-        );
-        if (items.length === 0) return;
-        // Prefer the active item; fall back to the first visible item.
-        const activeItem =
-            items.find(
-                (it) =>
-                    it.getAttribute('aria-current') === 'page' &&
-                    !isInsideCollapsedGroup(it),
-            ) ??
-            items.find((it) => !isInsideCollapsedGroup(it)) ??
-            items[0];
-        items.forEach((it) => {
-            it.setAttribute('tabindex', it === activeItem ? '0' : '-1');
-        });
-    }
-
-    function focusItem(item: HTMLElement): void {
-        // Roving tabindex: promote the target before focusing so the
-        // following focusin handler doesn't fight us.
-        el.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR).forEach((it) => {
-            it.setAttribute('tabindex', it === item ? '0' : '-1');
-        });
-        item.focus();
-    }
-
-    // -- public surface -- //
-    return {
-        collapse,
-        expand,
-        isCollapsed,
-        openDrawer,
-        closeDrawer,
-        isDrawerOpen,
-        expandGroup,
-        collapseGroup,
-        isGroupExpanded,
-        setActiveHref,
-        teardown,
-    };
-}
-
-/**
- * Lightweight CSS.escape fallback for the few places we build attribute
- * selectors from group keys. Not exhaustive — group keys are
- * kebab-case slugs by convention so the common cases work; we still
- * escape quotes and backslashes for safety.
- */
-function cssEscape(value: string): string {
-    if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
-        return CSS.escape(value);
-    }
-    return value.replace(/["\\]/g, '\\$&');
-}
-
-/**
- * Public helper — kebab-case slug for deriving a group key from a
- * label when the consumer didn't supply an explicit `key`. Lowercases,
- * strips diacritics, replaces non-alphanumerics with `-`, and trims
- * leading/trailing dashes.
- */
-export function deriveGroupKey(label: string): string {
-    return label
-        .normalize('NFKD')
-        .replace(/[̀-ͯ]/g, '')
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}