@pienter/ui 0.2.0

package/utils/controllers/sidebar.ts

@@ -0,0 +1,610 @@
+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, '');
+}