@pienter/ui 0.2.0

package/components/navigation/pagination/pagination.css

@@ -0,0 +1,53 @@
+@layer components {
+    .pui-pagination {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--space-3xs);
+        list-style: none;
+        padding: 0;
+        margin: 0;
+    }
+
+    .pui-pagination__item {
+        appearance: none;
+        border: var(--stroke-sm) solid var(--border-clr-base);
+        background: var(--bg-clr-surface);
+        font: inherit;
+        font-size: var(--step--1);
+        font-weight: var(--fw-semibold);
+        min-width: 2.2rem;
+        height: 2.2rem;
+        display: inline-grid;
+        place-items: center;
+        cursor: pointer;
+        border-radius: var(--radius-sm);
+        text-decoration: none;
+        color: var(--text-clr-base);
+    }
+
+    .pui-pagination__item:hover {
+        background: var(--bg-clr-surface-2);
+    }
+
+    .pui-pagination__item:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+
+    .pui-pagination__item[aria-current='page'] {
+        background: var(--bg-clr-dark);
+        color: var(--text-clr-inverse);
+        border-color: var(--border-clr-strong);
+    }
+
+    .pui-pagination__item:disabled,
+    .pui-pagination__item[aria-disabled='true'] {
+        opacity: 0.4;
+        cursor: not-allowed;
+    }
+
+    .pui-pagination__ellipsis {
+        color: var(--text-clr-muted);
+        padding-inline: var(--space-2xs);
+    }
+}

package/components/navigation/sidebar/Sidebar.astro

@@ -0,0 +1,132 @@
+---
+import './sidebar.css';
+import { generateId } from '../../../utils/a11y/id.js';
+import { deriveGroupKey } from '../../../utils/controllers/sidebar.js';
+import SidebarItemRender from './SidebarItemRender.astro';
+import type { SidebarItem } from './types.js';
+
+interface Props {
+  id?: string;
+  items: SidebarItem[];
+  activeHref?: string | null;
+  collapsed?: boolean;
+  drawerOpen?: boolean;
+  expandedGroups?: string[];
+  ariaLabel?: string;
+  drawerBreakpoint?: number;
+}
+
+const {
+  id,
+  items,
+  activeHref = null,
+  collapsed = false,
+  drawerOpen = false,
+  expandedGroups,
+  ariaLabel = 'Main navigation',
+  drawerBreakpoint = 768,
+  ...rest
+} = Astro.props;
+
+const sidebarId = id ?? generateId('pui-sidebar');
+
+// Pre-compute the initial expanded-groups set as a JSON string so the
+// mount script can hydrate `mountSidebar` with it.
+const initialExpanded = expandedGroups
+  ? JSON.stringify(expandedGroups)
+  : JSON.stringify(
+      // Fall back to defaultOpen=true groups derived from item shape.
+      collectDefaultOpenKeys(items),
+    );
+
+function collectDefaultOpenKeys(arr: SidebarItem[]): string[] {
+  const keys: string[] = [];
+  arr.forEach((it) => {
+    if (it.type === 'group') {
+      if (it.defaultOpen) keys.push(it.key ?? deriveGroupKey(it.label));
+      keys.push(...collectDefaultOpenKeys(it.items));
+    }
+  });
+  return keys;
+}
+---
+
+<nav
+  id={sidebarId}
+  class="pui-sidebar"
+  data-pui-sidebar
+  data-state={collapsed ? 'collapsed' : 'expanded'}
+  data-drawer-state="closed"
+  aria-label={ariaLabel}
+  data-collapsed-initially={collapsed ? 'true' : undefined}
+  data-drawer-open-initially={drawerOpen ? 'true' : undefined}
+  data-active-href={activeHref ?? undefined}
+  data-drawer-breakpoint={String(drawerBreakpoint)}
+  data-expanded-groups={initialExpanded}
+  {...rest}
+>
+  <div class="pui-sidebar__backdrop" data-sidebar-backdrop aria-hidden="true">
+  </div>
+  <div class="pui-sidebar__panel" data-sidebar-panel>
+    {
+      Astro.slots.has('brand') && (
+        <div class="pui-sidebar__brand">
+          <slot name="brand" />
+        </div>
+      )
+    }
+
+    <ul class="pui-sidebar__menu" data-sidebar-menu>
+      {items.map((item) => <SidebarItemRender item={item} />)}
+    </ul>
+
+    {
+      Astro.slots.has('footer') && (
+        <div class="pui-sidebar__footer">
+          <slot name="footer" />
+        </div>
+      )
+    }
+  </div>
+</nav>
+
+<script>
+  import { mountSidebar } from '@pienter/ui/utils/controllers/sidebar.js';
+
+  document.querySelectorAll<HTMLElement>('[data-pui-sidebar]').forEach((el) => {
+    const node = el as HTMLElement & {
+      _sidebar?: ReturnType<typeof mountSidebar>;
+    };
+    if (node._sidebar) return; // idempotent — guard against double-mounts
+
+    const collapsed = el.dataset.collapsedInitially === 'true';
+    const drawerOpenInitially = el.dataset.drawerOpenInitially === 'true';
+    const activeHref = el.dataset.activeHref ?? null;
+    const drawerBreakpoint = Number(el.dataset.drawerBreakpoint ?? '768');
+    let expandedGroups: string[];
+    try {
+      expandedGroups = JSON.parse(el.dataset.expandedGroups ?? '[]');
+    } catch {
+      expandedGroups = [];
+    }
+
+    const control = mountSidebar(el, {
+      collapsed,
+      drawerBreakpoint,
+      expandedGroups,
+      activeHref,
+      // Vue mirrors `onDrawerOpenChange` into a reactive prop whose
+      // watcher then calls openDrawer()/closeDrawer(). Astro has no
+      // reactivity, so the mount script wires the callback directly to
+      // the imperative API. Without this, backdrop click and Escape —
+      // both of which emit `onDrawerOpenChange(false)` from the
+      // controller — are no-ops in Astro.
+      onDrawerOpenChange: (open) => {
+        if (open) control.openDrawer();
+        else control.closeDrawer();
+      },
+    });
+    node._sidebar = control;
+    if (drawerOpenInitially) control.openDrawer();
+  });
+</script>

package/components/navigation/sidebar/Sidebar.vue

@@ -0,0 +1,174 @@
+<template>
+    <nav
+        ref="rootRef"
+        class="pui-sidebar"
+        data-pui-sidebar
+        :data-state="collapsed ? 'collapsed' : 'expanded'"
+        data-drawer-state="closed"
+        :aria-label="ariaLabel"
+    >
+        <div
+            class="pui-sidebar__backdrop"
+            data-sidebar-backdrop
+            aria-hidden="true"
+        />
+        <div class="pui-sidebar__panel" data-sidebar-panel>
+            <div v-if="$slots.brand" class="pui-sidebar__brand">
+                <slot name="brand" />
+            </div>
+
+            <ul class="pui-sidebar__menu" data-sidebar-menu>
+                <SidebarItemRender
+                    v-for="(item, idx) in items"
+                    :key="itemKey(item, idx)"
+                    :item="item"
+                />
+            </ul>
+
+            <div v-if="$slots.footer" class="pui-sidebar__footer">
+                <slot name="footer" />
+            </div>
+        </div>
+    </nav>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
+import {
+    mountSidebar,
+    deriveGroupKey,
+    type SidebarControl,
+} from '../../../utils/controllers/sidebar.js';
+import SidebarItemRender from './SidebarItemRender.vue';
+import type { SidebarItem } from './types.js';
+
+const props = withDefaults(
+    defineProps<{
+        items: 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.
+         */
+        expandedGroups?: string[];
+        ariaLabel?: string;
+        drawerBreakpoint?: number;
+    }>(),
+    {
+        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.
+        expandedGroups: undefined,
+        ariaLabel: 'Main navigation',
+        drawerBreakpoint: 768,
+    },
+);
+
+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;
+
+function itemKey(item: SidebarItem, idx: number): string {
+    if (item.type === 'link') return `link:${item.href}`;
+    if (item.type === 'group')
+        return `group:${item.key ?? deriveGroupKey(item.label)}`;
+    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();
+});
+
+watch(
+    () => props.collapsed,
+    (v) => {
+        if (!control) return;
+        if (v) control.collapse();
+        else control.expand();
+    },
+);
+
+watch(
+    () => props.drawerOpen,
+    (v) => {
+        if (!control) return;
+        if (v) control.openDrawer();
+        else control.closeDrawer();
+    },
+);
+
+watch(
+    () => props.activeHref,
+    (v) => {
+        control?.setActiveHref(v);
+    },
+);
+
+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);
+        });
+    },
+    { deep: true },
+);
+
+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));
+    },
+    { deep: true },
+);
+
+onBeforeUnmount(() => {
+    control?.teardown();
+    control = null;
+});
+</script>
+
+<style>
+@import './sidebar.css';
+</style>

package/components/navigation/sidebar/SidebarItemRender.astro

@@ -0,0 +1,83 @@
+---
+import Icon from '../../display/icon/Icon.astro';
+import type { IconName } from '../../../icons/index.js';
+import { generateId } from '../../../utils/a11y/id.js';
+import { deriveGroupKey } from '../../../utils/controllers/sidebar.js';
+import type { SidebarItem } from './types.js';
+
+interface Props {
+  item: SidebarItem;
+}
+
+const { item } = Astro.props;
+const itemsId = generateId('pui-sidebar-group');
+const resolvedKey =
+  item.type === 'group' ? (item.key ?? deriveGroupKey(item.label)) : '';
+---
+
+{
+  item.type === 'link' && (
+    <li 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="-1"
+      >
+        {item.icon && <Icon name={item.icon as IconName} size="sm" />}
+        <span class="pui-sidebar__link-label">{item.label}</span>
+        {item.badge !== undefined && (
+          <span class="pui-sidebar__badge">{item.badge}</span>
+        )}
+      </a>
+    </li>
+  )
+}
+
+{
+  item.type === 'group' && (
+    <li
+      class="pui-sidebar__group"
+      data-sidebar-group
+      data-group-key={resolvedKey}
+      data-default-open={item.defaultOpen ? 'true' : undefined}
+      data-state="collapsed"
+    >
+      <button
+        type="button"
+        class="pui-sidebar__group-toggle"
+        data-sidebar-menu-item
+        data-sidebar-group-toggle
+        aria-expanded="false"
+        aria-controls={itemsId}
+        tabindex="-1"
+      >
+        {item.icon && <Icon name={item.icon as IconName} size="sm" />}
+        <span class="pui-sidebar__link-label">{item.label}</span>
+        <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
+      >
+        {item.items.map((child) => (
+          <Astro.self item={child} />
+        ))}
+      </ul>
+    </li>
+  )
+}
+
+{
+  item.type === 'section' && (
+    <li class="pui-sidebar__section" role="presentation">
+      <span class="pui-sidebar__section-label">{item.label}</span>
+    </li>
+  )
+}

package/components/navigation/sidebar/SidebarItemRender.vue

@@ -0,0 +1,98 @@
+<template>
+    <!-- link -->
+    <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="-1"
+        >
+            <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>
+
+    <!-- group -->
+    <li
+        v-else-if="item.type === 'group'"
+        class="pui-sidebar__group"
+        data-sidebar-group
+        :data-group-key="resolvedKey"
+        :data-default-open="item.defaultOpen ? 'true' : undefined"
+        data-state="collapsed"
+    >
+        <button
+            type="button"
+            class="pui-sidebar__group-toggle"
+            data-sidebar-menu-item
+            data-sidebar-group-toggle
+            :aria-expanded="'false'"
+            :aria-controls="itemsId"
+            tabindex="-1"
+        >
+            <Icon v-if="item.icon" :name="item.icon as IconName" size="sm" />
+            <span class="pui-sidebar__link-label">{{ item.label }}</span>
+            <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
+        >
+            <SidebarItemRender
+                v-for="(child, idx) in item.items"
+                :key="childKey(child, idx)"
+                :item="child"
+            />
+        </ul>
+    </li>
+
+    <!-- section -->
+    <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 } 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 } from '../../../utils/controllers/sidebar.js';
+import type { SidebarItem } from './types.js';
+
+const props = defineProps<{ item: SidebarItem }>();
+
+// Stable id for the group's child list (linked from `aria-controls` on
+// the toggle). Generated once per render of this component instance.
+const itemsId = generateId('pui-sidebar-group');
+
+const resolvedKey = computed(() =>
+    props.item.type === 'group'
+        ? (props.item.key ?? deriveGroupKey(props.item.label))
+        : '',
+);
+
+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>