@pienter/ui 0.2.0 → 0.5.0

package/components/navigation/sidebar/Sidebar.vue

@@ -4,67 +4,102 @@
         class="pui-sidebar"
         data-pui-sidebar
         :data-state="collapsed ? 'collapsed' : 'expanded'"
-        data-drawer-state="closed"
+        :data-drawer-state="drawerOpen ? 'open' : 'closed'"
+        :data-collapsed-submenu="collapsedSubmenu"
         :aria-label="ariaLabel"
+        @pointerleave="onPointerLeave"
+        @focusout="onFocusOut"
     >
         <div
             class="pui-sidebar__backdrop"
             data-sidebar-backdrop
             aria-hidden="true"
+            @click="emit('update:drawerOpen', false)"
         />
-        <div class="pui-sidebar__panel" data-sidebar-panel>
-            <div v-if="$slots.brand" class="pui-sidebar__brand">
+        <div
+            ref="panelRef"
+            class="pui-sidebar__panel"
+            data-sidebar-panel
+            v-bind="drawerAria"
+        >
+            <div
+                v-if="$slots.brand"
+                ref="brandRef"
+                class="pui-sidebar__brand"
+                data-sidebar-brand
+            >
                 <slot name="brand" />
             </div>
 
-            <ul class="pui-sidebar__menu" data-sidebar-menu>
-                <SidebarItemRender
-                    v-for="(item, idx) in items"
+            <ul class="pui-sidebar__top-nav" data-sidebar-menu>
+                <SidebarMenuItem
+                    v-for="(item, idx) in topItems"
                     :key="itemKey(item, idx)"
                     :item="item"
                 />
             </ul>
 
-            <div v-if="$slots.footer" class="pui-sidebar__footer">
-                <slot name="footer" />
+            <div
+                v-if="$slots.bottom || bottomItems.length"
+                class="pui-sidebar__bottom"
+            >
+                <ul
+                    v-if="bottomItems.length"
+                    class="pui-sidebar__bottom-nav"
+                    data-sidebar-menu
+                >
+                    <SidebarMenuItem
+                        v-for="(item, idx) in bottomItems"
+                        :key="itemKey(item, idx)"
+                        :item="item"
+                    />
+                </ul>
+                <slot name="bottom" />
             </div>
         </div>
     </nav>
 </template>
 
 <script setup lang="ts">
-import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
+// Reactive orchestration over the primitives in
+// `utils/navigation/sidebar.ts`. See ADR 0007.
+import { computed, nextTick, onBeforeUnmount, provide, ref, watch } from 'vue';
+import { createFocusTrap, type FocusTrap } from '../../../utils/a11y/focus.js';
+import { lockScroll } from '../../../utils/dom/scroll-lock.js';
 import {
-    mountSidebar,
+    computeSubmenuPosition,
     deriveGroupKey,
-    type SidebarControl,
-} from '../../../utils/controllers/sidebar.js';
-import SidebarItemRender from './SidebarItemRender.vue';
+    isSubmenuActive,
+    SUBMENU_CLOSE_DELAY,
+    type SubmenuPosition,
+} from '../../../utils/navigation/sidebar.js';
+import { useWindowListener } from '../../../composables/useEventListener.js';
+import SidebarMenuItem from './SidebarMenuItem.vue';
+import { SIDEBAR_CONTEXT } from './context.js';
 import type { SidebarItem } from './types.js';
 
 const props = withDefaults(
     defineProps<{
-        items: SidebarItem[];
+        /** The main navigation — the top nav of the column. */
+        topItems: SidebarItem[];
+        /** Pinned to the foot of the column, below a divider. */
+        bottomItems?: SidebarItem[];
         activeHref?: string | null;
         collapsed?: boolean;
         drawerOpen?: boolean;
-        /**
-         * Controlled set of expanded group keys. Leave undefined to let the
-         * controller honor `defaultOpen` markup hints — passing an explicit
-         * array (even `[]`) signals "consumer is in control" and overrides
-         * markup defaults.
-         */
+        /** Leave undefined to honor each group's `defaultOpen`. */
         expandedGroups?: string[];
+        /** `'panel'` gives a collapsed group a flyout beside the rail. */
+        collapsedSubmenu?: 'hidden' | 'panel';
         ariaLabel?: string;
         drawerBreakpoint?: number;
     }>(),
     {
+        bottomItems: () => [],
         activeHref: null,
         collapsed: false,
         drawerOpen: false,
-        // Intentionally undefined: the controller's `defaultOpen` heuristic
-        // only fires when `config.expandedGroups` is undefined. With
-        // `() => []`, the heuristic was permanently disabled from Vue.
+        collapsedSubmenu: 'hidden',
         expandedGroups: undefined,
         ariaLabel: 'Main navigation',
         drawerBreakpoint: 768,
@@ -72,13 +107,13 @@ const props = withDefaults(
 );
 
 const emit = defineEmits<{
-    'update:collapsed': [value: boolean];
     'update:drawerOpen': [value: boolean];
     'update:expandedGroups': [value: string[]];
 }>();
 
 const rootRef = ref<HTMLElement | null>(null);
-let control: SidebarControl | null = null;
+const panelRef = ref<HTMLElement | null>(null);
+const brandRef = ref<HTMLElement | null>(null);
 
 function itemKey(item: SidebarItem, idx: number): string {
     if (item.type === 'link') return `link:${item.href}`;
@@ -87,85 +122,292 @@ function itemKey(item: SidebarItem, idx: number): string {
     return `section:${item.label}:${idx}`;
 }
 
-onMounted(() => {
-    if (!rootRef.value) return;
-    control = mountSidebar(rootRef.value, {
-        collapsed: props.collapsed,
-        drawerOpen: props.drawerOpen,
-        drawerBreakpoint: props.drawerBreakpoint,
-        expandedGroups: props.expandedGroups,
-        activeHref: props.activeHref,
-        onDrawerOpenChange: (open) => emit('update:drawerOpen', open),
-        onGroupExpandedChange: (key, expanded) => {
-            const next = new Set(props.expandedGroups);
-            if (expanded) next.add(key);
-            else next.delete(key);
-            emit('update:expandedGroups', Array.from(next));
-        },
-    });
-    if (props.drawerOpen) control.openDrawer();
-});
+function defaultOpenKeys(items: SidebarItem[]): string[] {
+    return items.flatMap((item) =>
+        item.type === 'group'
+            ? [
+                  ...(item.defaultOpen
+                      ? [item.key ?? deriveGroupKey(item.label)]
+                      : []),
+                  ...defaultOpenKeys(item.items),
+              ]
+            : [],
+    );
+}
+
+const expandedKeys = ref<Set<string>>(
+    new Set(
+        props.expandedGroups ??
+            defaultOpenKeys([...props.topItems, ...props.bottomItems]),
+    ),
+);
 
 watch(
-    () => props.collapsed,
-    (v) => {
-        if (!control) return;
-        if (v) control.collapse();
-        else control.expand();
+    () => props.expandedGroups,
+    (next) => {
+        if (next) expandedKeys.value = new Set(next);
     },
+    { deep: true },
+);
+
+const viewportWidth = ref(
+    typeof window === 'undefined'
+        ? Number.POSITIVE_INFINITY
+        : window.innerWidth,
+);
+
+const submenuActive = computed(() =>
+    isSubmenuActive({
+        policy: props.collapsedSubmenu,
+        collapsed: props.collapsed,
+        viewportWidth: viewportWidth.value,
+        drawerBreakpoint: props.drawerBreakpoint,
+    }),
 );
 
+const openKey = ref<string | null>(null);
+/** Opened by click; survives pointer-out, unlike a hover/focus open. */
+const pinned = ref(false);
+const submenuPos = ref<SubmenuPosition | null>(null);
+let closeTimer: ReturnType<typeof setTimeout> | null = null;
+
+function clearCloseTimer(): void {
+    if (closeTimer === null) return;
+    clearTimeout(closeTimer);
+    closeTimer = null;
+}
+
+function closeSubmenu(): void {
+    clearCloseTimer();
+    openKey.value = null;
+    pinned.value = false;
+}
+
+function scheduleClose(): void {
+    if (!openKey.value || pinned.value) return;
+    clearCloseTimer();
+    // Grace period so a diagonal path into the flyout doesn't drop it.
+    closeTimer = setTimeout(closeSubmenu, SUBMENU_CLOSE_DELAY);
+}
+
+/** One measurement serves every flyout: same edge, same height. */
+function measureSubmenu(): void {
+    const root = rootRef.value;
+    if (!root) return;
+    submenuPos.value = computeSubmenuPosition(
+        root.getBoundingClientRect(),
+        brandRef.value?.getBoundingClientRect() ?? null,
+    );
+}
+
 watch(
-    () => props.drawerOpen,
-    (v) => {
-        if (!control) return;
-        if (v) control.openDrawer();
-        else control.closeDrawer();
+    submenuActive,
+    (active) => {
+        if (active) void nextTick(measureSubmenu);
+        else closeSubmenu();
     },
+    { immediate: true },
 );
 
-watch(
-    () => props.activeHref,
-    (v) => {
-        control?.setActiveHref(v);
+watch(openKey, (key) => {
+    if (key) void nextTick(measureSubmenu);
+});
+
+useWindowListener(
+    'resize',
+    () => {
+        viewportWidth.value = window.innerWidth;
+        if (submenuActive.value) measureSubmenu();
     },
+    { passive: true },
 );
 
-watch(
-    () => props.expandedGroups,
-    (next) => {
-        if (!control) return;
-        // Sync each declared group: expand the ones in `next`, collapse
-        // any currently-expanded group that's no longer in `next`.
-        const set = new Set(next);
-        // Walk the markup to find every group key — that's the universe.
-        if (!rootRef.value) return;
-        const groups = rootRef.value.querySelectorAll<HTMLElement>(
-            '[data-sidebar-group][data-group-key]',
-        );
-        groups.forEach((el) => {
-            const key = el.dataset.groupKey ?? '';
-            if (!key) return;
-            if (set.has(key)) control!.expandGroup(key);
-            else control!.collapseGroup(key);
-        });
+// Capture phase catches scrolls in any ancestor.
+useWindowListener(
+    'scroll',
+    () => {
+        if (openKey.value) measureSubmenu();
     },
-    { deep: true },
+    { capture: true, passive: true },
 );
 
+function onToggle(key: string, isTopLevel: boolean): void {
+    // A collapsed rail pins the flyout instead of rewriting `expandedGroups`,
+    // which describes the expanded sidebar.
+    if (submenuActive.value && isTopLevel) {
+        if (openKey.value === key && pinned.value) {
+            closeSubmenu();
+        } else {
+            clearCloseTimer();
+            openKey.value = key;
+            pinned.value = true;
+        }
+        return;
+    }
+
+    const next = new Set(expandedKeys.value);
+    if (next.has(key)) next.delete(key);
+    else next.add(key);
+    expandedKeys.value = next;
+    emit('update:expandedGroups', [...next]);
+}
+
+/** Pointer and focus share this path, so the two cannot drift apart. */
+function onEntryEnter(topLevelKey: string | null): void {
+    if (!submenuActive.value) return;
+    if (topLevelKey) {
+        clearCloseTimer();
+        if (openKey.value !== topLevelKey) {
+            openKey.value = topLevelKey;
+            pinned.value = false;
+        }
+        return;
+    }
+    if (!pinned.value) scheduleClose();
+}
+
+provide(SIDEBAR_CONTEXT, {
+    activeHref: computed(() => props.activeHref),
+    expandedKeys,
+    openKey,
+    submenuActive,
+    submenuPos,
+    onToggle,
+    onEntryEnter,
+    onEntryKeydown,
+});
+
+function onPointerLeave(): void {
+    if (!submenuActive.value || pinned.value) return;
+    scheduleClose();
+}
+
+function onFocusOut(event: FocusEvent): void {
+    if (!openKey.value) return;
+    const next = event.relatedTarget;
+    // A pin survives the pointer, not the focus.
+    if (next instanceof Node && rootRef.value?.contains(next)) return;
+    closeSubmenu();
+}
+
+/** Entries in DOM order that focus can actually reach. */
+function focusableEntries(): HTMLElement[] {
+    const root = rootRef.value;
+    if (!root) return [];
+    return [
+        ...root.querySelectorAll<HTMLElement>(
+            '[data-sidebar-menu-item]:not([data-disabled="true"])',
+        ),
+        // `visibilityProperty` is not the default, and a closed flyout hides
+        // with `visibility` — without it, Arrow-Down walks into dead entries.
+    ].filter((el) => el.checkVisibility({ visibilityProperty: true }));
+}
+
+function onEntryKeydown(event: KeyboardEvent): void {
+    // The flyout is the innermost dismissible layer, so it goes first.
+    if (event.key === 'Escape' && openKey.value) {
+        event.preventDefault();
+        const selector = `[data-group-key="${CSS.escape(openKey.value)}"] [data-sidebar-group-toggle]`;
+        const toggle = rootRef.value?.querySelector<HTMLElement>(selector);
+        closeSubmenu();
+        toggle?.focus();
+        return;
+    }
+
+    if (event.key === 'Escape' && props.drawerOpen) {
+        event.preventDefault();
+        emit('update:drawerOpen', false);
+        return;
+    }
+
+    const item = event.currentTarget;
+    if (!(item instanceof HTMLElement)) return;
+
+    const entries = focusableEntries();
+    const idx = entries.indexOf(item);
+
+    switch (event.key) {
+        case 'ArrowDown':
+            event.preventDefault();
+            entries[Math.min(idx + 1, entries.length - 1)]?.focus();
+            return;
+        case 'ArrowUp':
+            event.preventDefault();
+            entries[Math.max(idx - 1, 0)]?.focus();
+            return;
+        case 'Home':
+            event.preventDefault();
+            entries[0]?.focus();
+            return;
+        case 'End':
+            event.preventDefault();
+            entries[entries.length - 1]?.focus();
+            return;
+        case ' ':
+        case 'Spacebar':
+            // `<a>` doesn't activate on Space natively.
+            if (item.matches('[data-sidebar-link]')) {
+                event.preventDefault();
+                item.click();
+            }
+            return;
+        default:
+            return;
+    }
+}
+
+const drawerAria = computed(() =>
+    props.drawerOpen
+        ? {
+              role: 'dialog',
+              // Booleans, so Vue renders "true"/"false" instead of dropping it.
+              'aria-modal': true,
+              'aria-label': props.ariaLabel,
+          }
+        : {},
+);
+
+let trap: FocusTrap | null = null;
+let unlockScroll: (() => void) | null = null;
+let triggerEl: HTMLElement | null = null;
+
 watch(
-    () => props.items,
-    () => {
-        // Item shape changed → re-derive active-href on the new DOM.
-        // Vue re-renders the `<ul>` first; defer one tick.
-        queueMicrotask(() => control?.setActiveHref(props.activeHref));
+    () => props.drawerOpen,
+    async (open) => {
+        if (open) {
+            const active = document.activeElement;
+            triggerEl =
+                active instanceof HTMLElement &&
+                active !== document.body &&
+                !rootRef.value?.contains(active)
+                    ? active
+                    : null;
+
+            unlockScroll = lockScroll();
+            await nextTick();
+            if (!panelRef.value) return;
+            trap = createFocusTrap(panelRef.value);
+            const first = focusableEntries()[0];
+            if (first) first.focus();
+            else panelRef.value.focus();
+            return;
+        }
+
+        trap?.release();
+        trap = null;
+        unlockScroll?.();
+        unlockScroll = null;
+
+        const trigger = triggerEl;
+        triggerEl = null;
+        if (trigger && document.contains(trigger)) trigger.focus();
     },
-    { deep: true },
 );
 
 onBeforeUnmount(() => {
-    control?.teardown();
-    control = null;
+    clearCloseTimer();
+    trap?.release();
+    unlockScroll?.();
 });
 </script>
 

package/components/navigation/sidebar/SidebarMenuItem.vue

@@ -0,0 +1,199 @@
+<template>
+    <li v-if="item.type === 'link'" class="pui-sidebar__item">
+        <a
+            class="pui-sidebar__link"
+            data-sidebar-menu-item
+            data-sidebar-link
+            :href="item.href"
+            :data-disabled="item.disabled ? 'true' : undefined"
+            :aria-disabled="item.disabled ? 'true' : undefined"
+            :tabindex="item.disabled ? '-1' : undefined"
+            :aria-current="isCurrent ? 'page' : undefined"
+            @pointerover="ctx.onEntryEnter(topLevelKey)"
+            @focus="ctx.onEntryEnter(topLevelKey)"
+            @keydown="ctx.onEntryKeydown"
+        >
+            <Icon v-if="item.icon" :name="item.icon as IconName" size="sm" />
+            <span class="pui-sidebar__link-label">{{ item.label }}</span>
+            <span v-if="item.badge !== undefined" class="pui-sidebar__badge">{{
+                item.badge
+            }}</span>
+        </a>
+    </li>
+
+    <li
+        v-else-if="item.type === 'group'"
+        class="pui-sidebar__group"
+        data-sidebar-group
+        :data-group-key="groupKey"
+        :data-default-open="item.defaultOpen ? 'true' : undefined"
+        :data-state="isExpanded ? 'expanded' : 'collapsed'"
+        :data-active="containsCurrent ? 'true' : undefined"
+        :data-submenu-state="submenuState"
+    >
+        <!-- With an `href` the row is a link and the caret is its own
+             toggle; one control cannot both navigate and expand in place.
+             Without one, the whole row is the toggle. -->
+        <component
+            :is="item.href ? 'a' : 'button'"
+            class="pui-sidebar__group-toggle"
+            data-sidebar-menu-item
+            data-sidebar-group-toggle
+            :data-sidebar-link="item.href ? '' : undefined"
+            :type="item.href ? undefined : 'button'"
+            :href="item.href"
+            :aria-current="isCurrent ? 'page' : undefined"
+            :aria-expanded="
+                item.href && !isFlyout ? undefined : isFlyoutOrExpanded
+            "
+            :aria-controls="item.href && !isFlyout ? undefined : itemsId"
+            @click="item.href ? undefined : ctx.onToggle(groupKey, isTopLevel)"
+            @pointerover="ctx.onEntryEnter(ownKey)"
+            @focus="ctx.onEntryEnter(ownKey)"
+            @keydown="ctx.onEntryKeydown"
+        >
+            <Icon v-if="item.icon" :name="item.icon as IconName" size="sm" />
+            <span class="pui-sidebar__link-label">{{ item.label }}</span>
+            <Icon
+                v-if="!item.href"
+                name="chevron-down"
+                size="sm"
+                class="pui-sidebar__group-caret"
+            />
+        </component>
+        <button
+            v-if="item.href"
+            type="button"
+            class="pui-sidebar__group-caret-toggle"
+            :aria-expanded="isFlyoutOrExpanded"
+            :aria-controls="itemsId"
+            :aria-label="`${isFlyoutOrExpanded ? 'Collapse' : 'Expand'} ${item.label}`"
+            @click="ctx.onToggle(groupKey, isTopLevel)"
+        >
+            <Icon
+                name="chevron-down"
+                size="sm"
+                class="pui-sidebar__group-caret"
+            />
+        </button>
+        <ul
+            :id="itemsId"
+            class="pui-sidebar__group-items"
+            data-sidebar-group-items
+            role="group"
+            :hidden="isFlyout ? false : !isExpanded"
+            :style="flyoutStyle"
+        >
+            <SidebarMenuItem
+                v-for="(child, idx) in item.items"
+                :key="childKey(child, idx)"
+                :item="child"
+                :top-level-key="ownKey"
+            />
+        </ul>
+    </li>
+
+    <li
+        v-else-if="item.type === 'section'"
+        class="pui-sidebar__section"
+        role="presentation"
+    >
+        <span class="pui-sidebar__section-label">{{ item.label }}</span>
+    </li>
+</template>
+
+<script setup lang="ts">
+import { computed, inject, type CSSProperties } from 'vue';
+import Icon from '../../display/icon/Icon.vue';
+import type { IconName } from '../../../icons/index.js';
+import { generateId } from '../../../utils/a11y/id.js';
+import {
+    deriveGroupKey,
+    groupContainsActive,
+    isHrefActive,
+} from '../../../utils/navigation/sidebar.js';
+import { SIDEBAR_CONTEXT } from './context.js';
+import type { SidebarItem } from './types.js';
+
+const props = withDefaults(
+    defineProps<{
+        item: SidebarItem;
+        /** The rail group this entry belongs to; null if it has none. */
+        topLevelKey?: string | null;
+    }>(),
+    { topLevelKey: null },
+);
+
+const ctx = inject(SIDEBAR_CONTEXT)!;
+
+const itemsId = generateId('pui-sidebar-group');
+
+const groupKey = computed(() =>
+    props.item.type === 'group'
+        ? (props.item.key ?? deriveGroupKey(props.item.label))
+        : '',
+);
+
+const isTopLevel = computed(() => props.topLevelKey === null);
+
+/** What descendants inherit as their `topLevelKey`. */
+const ownKey = computed(() =>
+    props.item.type === 'group' && isTopLevel.value
+        ? groupKey.value
+        : props.topLevelKey,
+);
+
+const isCurrent = computed(() => {
+    const href =
+        props.item.type === 'link'
+            ? props.item.href
+            : props.item.type === 'group'
+              ? props.item.href
+              : undefined;
+    return href !== undefined && isHrefActive(ctx.activeHref.value, href);
+});
+
+const containsCurrent = computed(
+    () =>
+        props.item.type === 'group' &&
+        groupContainsActive(props.item.items, ctx.activeHref.value),
+);
+
+const isExpanded = computed(() => ctx.expandedKeys.value.has(groupKey.value));
+
+const isFlyout = computed(
+    () =>
+        ctx.submenuActive.value &&
+        props.item.type === 'group' &&
+        isTopLevel.value,
+);
+
+const isFlyoutOpen = computed(
+    () => isFlyout.value && ctx.openKey.value === groupKey.value,
+);
+
+/** What `aria-expanded` reports: flyout state on the rail, else disclosure. */
+const isFlyoutOrExpanded = computed(() =>
+    isFlyout.value ? isFlyoutOpen.value : isExpanded.value,
+);
+
+// The stylesheet keys on the attribute's presence, not just its value.
+const submenuState = computed(() =>
+    isFlyout.value ? (isFlyoutOpen.value ? 'open' : 'closed') : undefined,
+);
+
+// Positioned even when closed: a fixed box with no coordinates falls back
+// to its static position, inside the rail.
+const flyoutStyle = computed<CSSProperties | undefined>(() => {
+    if (!isFlyout.value || !ctx.submenuPos.value) return undefined;
+    const { left, top, height } = ctx.submenuPos.value;
+    return { left: `${left}px`, top: `${top}px`, height: `${height}px` };
+});
+
+function childKey(child: SidebarItem, idx: number): string {
+    if (child.type === 'link') return `link:${child.href}`;
+    if (child.type === 'group')
+        return `group:${child.key ?? deriveGroupKey(child.label)}`;
+    return `section:${child.label}:${idx}`;
+}
+</script>