@pienter/ui 0.2.0

package/components/navigation/sidebar/sidebar.css

@@ -0,0 +1,303 @@
+@layer components {
+    /* ============================================================
+   * Block — the navigation landmark, also the drawer mount point on
+   * mobile. Desktop: a fixed-width column owned by the consumer's
+   * layout shell. Mobile: occupies the full viewport with a backdrop
+   * sibling and a slide-in panel.
+   * ============================================================ */
+    .pui-sidebar {
+        --pui-sidebar-width: var(--space-sidebar-width);
+        --pui-sidebar-width-collapsed: var(--space-sidebar-width-collapsed);
+
+        display: block;
+        width: var(--pui-sidebar-width);
+        flex-shrink: 0;
+        background: var(--bg-clr-surface);
+        border-inline-end: var(--stroke-sm) solid var(--border-clr-base);
+        transition: width 180ms ease;
+    }
+
+    .pui-sidebar[data-state='collapsed'] {
+        width: var(--pui-sidebar-width-collapsed);
+    }
+
+    /* ============================================================
+   * Panel — the visible column / drawer body containing brand, menu,
+   * footer.
+   * ============================================================ */
+    .pui-sidebar__panel {
+        display: flex;
+        flex-direction: column;
+        height: 100%;
+        min-height: 100%;
+        padding: var(--space-s);
+        gap: var(--space-s);
+        background: var(--bg-clr-surface);
+    }
+
+    /* ============================================================
+   * Backdrop — only meaningful in mobile drawer mode. Hidden on desktop.
+   * ============================================================ */
+    .pui-sidebar__backdrop {
+        display: none;
+    }
+
+    /* ============================================================
+   * Brand region — top of the panel. Layout owned by consumer markup
+   * inside the slot; we just provide consistent spacing.
+   * ============================================================ */
+    .pui-sidebar__brand {
+        display: flex;
+        align-items: center;
+        gap: var(--space-2xs);
+        padding-block: var(--space-2xs);
+    }
+
+    /* Hide brand inner text when collapsed; consumer markup with
+   * `data-keep-when-collapsed` survives. */
+    .pui-sidebar[data-state='collapsed']
+        .pui-sidebar__brand
+        > :not([data-keep-when-collapsed]) {
+        /* leave layout untouched — many consumers want a wordmark to fade
+     * out while the mark stays — this is the default rule. Consumers
+     * mark the persistent element. */
+    }
+
+    /* ============================================================
+   * Menu list — the data-driven menu region.
+   * ============================================================ */
+    .pui-sidebar__menu {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-3xs);
+        flex: 1;
+        min-height: 0;
+        overflow-y: auto;
+    }
+
+    .pui-sidebar__item {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+    }
+
+    /* ============================================================
+   * Link / group-toggle — share visual treatment so the menu reads
+   * as one column of equally-weighted entries.
+   * ============================================================ */
+    .pui-sidebar__link,
+    .pui-sidebar__group-toggle {
+        display: flex;
+        align-items: center;
+        gap: var(--space-2xs);
+        width: 100%;
+        padding: var(--space-2xs) var(--space-xs);
+        border-radius: var(--radius-sm);
+        background: transparent;
+        border: 0;
+        color: var(--text-clr-base);
+        text-decoration: none;
+        font: inherit;
+        font-size: var(--step--1);
+        font-weight: var(--fw-semibold);
+        text-align: start;
+        cursor: pointer;
+    }
+
+    .pui-sidebar__link:hover,
+    .pui-sidebar__group-toggle:hover {
+        background: var(--bg-clr-accent);
+        color: var(--text-clr-brand);
+    }
+
+    .pui-sidebar__link[aria-current='page'] {
+        background: var(--bg-clr-accent);
+        color: var(--text-clr-brand-selected);
+    }
+
+    .pui-sidebar__link[aria-disabled='true'] {
+        color: var(--text-clr-muted);
+        pointer-events: none;
+    }
+
+    .pui-sidebar__link:focus-visible,
+    .pui-sidebar__group-toggle:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+
+    .pui-sidebar__link-label {
+        flex: 1;
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .pui-sidebar__badge {
+        margin-inline-start: auto;
+        padding-inline: var(--space-3xs);
+        border-radius: var(--radius-pill);
+        background: var(--bg-clr-brand);
+        color: var(--bg-clr-brand-ink);
+        font-size: var(--step--2);
+        font-weight: var(--fw-bold);
+        line-height: 1.4;
+        min-width: 1.25rem;
+        text-align: center;
+    }
+
+    /* ============================================================
+   * Group — collapsible container.
+   * ============================================================ */
+    .pui-sidebar__group {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+    }
+
+    .pui-sidebar__group-caret {
+        margin-inline-start: auto;
+        transition: transform 150ms ease;
+    }
+
+    .pui-sidebar__group-toggle[aria-expanded='true'] .pui-sidebar__group-caret {
+        transform: rotate(180deg);
+    }
+
+    .pui-sidebar__group[data-active='true'] > .pui-sidebar__group-toggle {
+        color: var(--text-clr-brand-selected);
+    }
+
+    .pui-sidebar__group-items {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        padding-inline-start: var(--space-m);
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-3xs);
+    }
+
+    .pui-sidebar__group-items[hidden] {
+        display: none;
+    }
+
+    /* ============================================================
+   * Section header — non-interactive label.
+   * ============================================================ */
+    .pui-sidebar__section {
+        list-style: none;
+        margin: 0;
+        padding: var(--space-s) var(--space-xs) var(--space-3xs);
+    }
+
+    .pui-sidebar__section-label {
+        font-family: var(--ff-mono);
+        font-size: var(--step--2);
+        text-transform: uppercase;
+        letter-spacing: var(--ls-eyebrow);
+        color: var(--text-clr-muted);
+    }
+
+    /* ============================================================
+   * Footer region — bottom of the panel.
+   * ============================================================ */
+    .pui-sidebar__footer {
+        margin-block-start: auto;
+        padding-block-start: var(--space-2xs);
+        border-block-start: var(--stroke-sm) solid var(--border-clr-base);
+    }
+
+    /* ============================================================
+   * Collapsed-state visual rules — hide labels and badges, keep icons.
+   * Section headers also hidden because they're label-only.
+   * ============================================================ */
+    .pui-sidebar[data-state='collapsed'] .pui-sidebar__link-label,
+    .pui-sidebar[data-state='collapsed'] .pui-sidebar__badge,
+    .pui-sidebar[data-state='collapsed'] .pui-sidebar__group-caret,
+    .pui-sidebar[data-state='collapsed'] .pui-sidebar__section {
+        display: none;
+    }
+
+    .pui-sidebar[data-state='collapsed'] .pui-sidebar__link,
+    .pui-sidebar[data-state='collapsed'] .pui-sidebar__group-toggle {
+        justify-content: center;
+        padding-inline: var(--space-3xs);
+    }
+
+    /* In collapsed mode we also hide nested group items (they'd
+   * overflow the narrow column). Hover-to-expand with tooltip is a
+   * Phase 4 deferral. */
+    .pui-sidebar[data-state='collapsed'] .pui-sidebar__group-items {
+        display: none;
+    }
+
+    /* ============================================================
+   * Mobile drawer mode — below the breakpoint, the column transforms
+   * into a fixed-overlay drawer. The breakpoint default lives in JS
+   * (768px), CSS mirrors with the same number. If a consumer changes
+   * `:drawer-breakpoint`, they're responsible for matching CSS via
+   * a custom stylesheet — out of scope for v1.
+   * ============================================================ */
+    @media (max-width: 767px) {
+        .pui-sidebar {
+            width: 0;
+            border-inline-end: none;
+            transition: none;
+        }
+
+        .pui-sidebar__panel {
+            position: fixed;
+            inset-block: 0;
+            inset-inline-start: 0;
+            width: min(20rem, 80vw);
+            box-shadow: var(--shadow-spark-lg);
+            transform: translateX(-100%);
+            transition: transform 220ms ease;
+            z-index: 50;
+        }
+
+        .pui-sidebar[data-drawer-state='open'] .pui-sidebar__panel {
+            transform: translateX(0);
+        }
+
+        .pui-sidebar__backdrop {
+            display: block;
+            position: fixed;
+            inset: 0;
+            background: var(--bg-clr-backdrop);
+            opacity: 0;
+            pointer-events: none;
+            transition: opacity 220ms ease;
+            z-index: 40;
+        }
+
+        .pui-sidebar[data-drawer-state='open'] .pui-sidebar__backdrop {
+            opacity: 1;
+            pointer-events: auto;
+        }
+
+        /* In drawer mode, the desktop "collapsed" state is irrelevant —
+     * the panel is full-width drawer when open and hidden otherwise. */
+        .pui-sidebar[data-state='collapsed'] .pui-sidebar__link-label,
+        .pui-sidebar[data-state='collapsed'] .pui-sidebar__badge,
+        .pui-sidebar[data-state='collapsed'] .pui-sidebar__group-caret,
+        .pui-sidebar[data-state='collapsed'] .pui-sidebar__section {
+            display: revert;
+        }
+
+        .pui-sidebar[data-state='collapsed'] .pui-sidebar__link,
+        .pui-sidebar[data-state='collapsed'] .pui-sidebar__group-toggle {
+            justify-content: flex-start;
+            padding-inline: var(--space-xs);
+        }
+
+        .pui-sidebar[data-state='collapsed'] .pui-sidebar__group-items {
+            display: flex;
+        }
+    }
+}

package/components/navigation/sidebar/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Sidebar driver-data discriminated union.
+ *
+ * The Sidebar component takes an `:items` prop of `SidebarItem[]`. Each
+ * entry is one of three shapes, distinguished by the `type` field:
+ *
+ * - `link`     — a navigable menu entry (renders as `<a>`)
+ * - `group`    — an expandable container with nested items
+ * - `section`  — a non-interactive section header / divider with a label
+ *
+ * Active-state highlighting is derived from the Sidebar's `:active-href`
+ * prop using the hierarchical-match algorithm documented in
+ * `packages/ui/CONVENTIONS.md`. Consumers do NOT mark items active.
+ *
+ * See the Sidebar audit in `./AUDIT.md` for the
+ * full hybrid-API archetype rules.
+ */
+
+/** A navigable menu entry. */
+export interface SidebarLink {
+    type: 'link';
+    /** Visible label. */
+    label: string;
+    /** Target href; matched against the Sidebar's `activeHref` prop. */
+    href: string;
+    /**
+     * Optional icon name from the @pienter/ui icon set. Rendered as a
+     * leading icon. v1 accepts a string (icon name); may grow to
+     * `string | Component` if rich icon shapes become a need.
+     */
+    icon?: string;
+    /** Optional trailing badge (e.g. unread count or "New"). */
+    badge?: string | number;
+    /** Disabled items are non-interactive and skipped by keyboard nav. */
+    disabled?: boolean;
+}
+
+/** An expandable container with nested items. */
+export interface SidebarGroup {
+    type: 'group';
+    /** Visible label on the group toggle button. */
+    label: string;
+    /** Optional leading icon on the group toggle. */
+    icon?: string;
+    /** Nested items — links, sections, or further groups. */
+    items: SidebarItem[];
+    /**
+     * Whether the group starts expanded on first mount. Ignored after
+     * the consumer has explicit control of `expandedGroups`. Default
+     * `false`.
+     */
+    defaultOpen?: boolean;
+    /**
+     * Optional explicit key used by the controller's `expandGroup` /
+     * `collapseGroup` methods and by the Sidebar's `expandedGroups`
+     * prop. When omitted, the key is derived from `label` via
+     * kebab-case slugification (e.g. "Member admin" → "member-admin").
+     * REQUIRED when multiple groups share a label, otherwise their
+     * derived keys would collide.
+     */
+    key?: string;
+}
+
+/** A non-interactive section header / divider with a label. */
+export interface SidebarSection {
+    type: 'section';
+    /** Visible label rendered as a small caption. */
+    label: string;
+}
+
+/** Discriminated union over all sidebar item shapes. */
+export type SidebarItem = SidebarLink | SidebarGroup | SidebarSection;

package/components/navigation/tabs/Tabs.vue

@@ -0,0 +1,84 @@
+<template>
+    <div class="pui-tabs" role="tablist">
+        <button
+            v-for="tab in tabs"
+            :key="tab.key"
+            type="button"
+            class="pui-tabs__item"
+            role="tab"
+            :aria-selected="modelValue === tab.key ? 'true' : 'false'"
+            :tabindex="modelValue === tab.key ? 0 : -1"
+            :disabled="tab.disabled || undefined"
+            @click="emit('update:modelValue', tab.key)"
+            @keydown="handleKeydown($event)"
+        >
+            {{ tab.label }}
+        </button>
+    </div>
+</template>
+
+<script setup lang="ts">
+interface TabItem {
+    key: string;
+    label: string;
+    disabled?: boolean;
+}
+
+const props = withDefaults(
+    defineProps<{
+        modelValue?: string;
+        tabs: TabItem[];
+    }>(),
+    {
+        modelValue: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:modelValue': [value: string];
+}>();
+
+function handleKeydown(event: KeyboardEvent): void {
+    const target = event.currentTarget as HTMLElement;
+    const items = Array.from(
+        target.parentElement!.querySelectorAll<HTMLElement>(
+            '.pui-tabs__item:not([disabled])',
+        ),
+    );
+    if (items.length === 0) return;
+    const currentIndex = items.indexOf(target);
+    let nextIndex: number;
+
+    switch (event.key) {
+        case 'ArrowRight':
+            nextIndex = (currentIndex + 1) % items.length;
+            break;
+        case 'ArrowLeft':
+            nextIndex = (currentIndex - 1 + items.length) % items.length;
+            break;
+        case 'Home':
+            nextIndex = 0;
+            break;
+        case 'End':
+            nextIndex = items.length - 1;
+            break;
+        default:
+            return;
+    }
+
+    event.preventDefault();
+    // Disabled tabs are excluded from both `items` (`:not([disabled])`) and
+    // `enabledTabs`, so the indices line up.
+    const enabledTabs = props.tabs.filter((t) => !t.disabled);
+    const nextEl = items[nextIndex];
+    const nextTab = enabledTabs[nextIndex];
+    if (nextEl && nextTab) {
+        nextEl.focus();
+        emit('update:modelValue', nextTab.key);
+    }
+}
+</script>
+
+<style>
+@import './tabs.css';
+</style>

package/components/navigation/tabs/tabs.css

@@ -0,0 +1,39 @@
+@layer components {
+    .pui-tabs {
+        display: flex;
+        gap: var(--space-s);
+        border-block-end: var(--stroke-sm) solid var(--border-clr-base);
+    }
+    .pui-tabs__item {
+        appearance: none;
+        background: transparent;
+        border: 0;
+        padding: var(--space-2xs) 0;
+        font: inherit;
+        font-size: var(--step--1);
+        font-weight: var(--fw-semibold);
+        color: var(--text-clr-muted);
+        cursor: pointer;
+        border-block-end: 2px solid transparent;
+        margin-block-end: -1px;
+        transition: color 0.12s ease;
+    }
+    .pui-tabs__item[aria-selected='true'] {
+        color: var(--text-clr-base);
+        border-block-end-color: var(--border-clr-brand);
+    }
+    .pui-tabs__item:hover {
+        color: var(--text-clr-base);
+    }
+    .pui-tabs__item:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+    .pui-tabs__item:disabled {
+        opacity: 0.4;
+        cursor: not-allowed;
+    }
+    .pui-tabs__item:disabled:hover {
+        color: var(--text-clr-muted);
+    }
+}

package/components/overlay/alert-dialog/AlertDialog.astro

@@ -0,0 +1,112 @@
+---
+import './alert-dialog.css';
+import { generateId } from '../../../utils/a11y/id.js';
+
+interface Props {
+  id?: string;
+  open?: boolean;
+  title: string;
+  description: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  destructive?: boolean;
+}
+
+const {
+  id,
+  open = false,
+  title,
+  description,
+  confirmLabel = 'Confirm',
+  cancelLabel = 'Cancel',
+  destructive = false,
+  ...rest
+} = Astro.props;
+
+const dialogId = id ?? generateId('alertdialog');
+const titleId = `${dialogId}-title`;
+const descriptionId = `${dialogId}-desc`;
+---
+
+<dialog
+  id={dialogId}
+  class="pui-alert-dialog"
+  data-state="closed"
+  data-pui-alert-dialog
+  data-open-initially={open ? 'true' : undefined}
+  aria-labelledby={titleId}
+  aria-describedby={descriptionId}
+  {...rest}
+>
+  <div class="pui-alert-dialog__head">
+    <h2 id={titleId} class="pui-alert-dialog__title">{title}</h2>
+    <p id={descriptionId} class="pui-alert-dialog__description">
+      {description}
+    </p>
+  </div>
+  <div class="pui-alert-dialog__actions">
+    <button
+      type="button"
+      class="pui-btn"
+      data-size="md"
+      data-dialog-cancel
+      data-alert-dialog-action="cancel">{cancelLabel}</button
+    >
+    <button
+      type="button"
+      class="pui-btn"
+      data-variant={destructive ? 'danger' : 'primary'}
+      data-size="md"
+      data-alert-dialog-action="confirm">{confirmLabel}</button
+    >
+  </div>
+</dialog>
+
+<script>
+  import { mountDialog } from '@pienter/ui/utils/controllers/dialog.js';
+
+  // AlertDialog uses its own selector marker (`data-pui-alert-dialog`) so the
+  // mount block can hard-code the locked alertdialog config (role,
+  // persistent, initialFocus: 'cancel') without branching on data-attrs.
+  document
+    .querySelectorAll<HTMLDialogElement>('dialog[data-pui-alert-dialog]')
+    .forEach((el) => {
+      // Idempotent — guard against double-mounts (HMR, multiple <AlertDialog> imports).
+      if ((el as unknown as { _dialog?: unknown })._dialog) return;
+      const control = mountDialog(el, {
+        role: 'alertdialog',
+        persistent: true,
+        initialFocus: 'cancel',
+      });
+      (el as unknown as { _dialog: typeof control })._dialog = control;
+      if (el.dataset.openInitially === 'true') control.open();
+    });
+
+  // Event-delegated confirm/cancel button handlers. Dispatching custom
+  // `confirm` / `cancel` events on the dialog lets Astro consumers wire
+  // callbacks via `myDialog.addEventListener('confirm', ...)` without
+  // touching the controller. The controller's close() is invoked here so
+  // consumers don't have to repeat the boilerplate at every call-site.
+  document.addEventListener('click', (e) => {
+    const target = e.target as HTMLElement | null;
+    if (!target) return;
+    const action = target.closest<HTMLElement>('[data-alert-dialog-action]');
+    if (!action) return;
+    const dialog = action.closest<HTMLDialogElement>(
+      'dialog[data-pui-alert-dialog]',
+    );
+    if (!dialog) return;
+    const actionName = action.getAttribute('data-alert-dialog-action');
+    const detail = { dialogId: dialog.id };
+    if (actionName === 'confirm') {
+      dialog.dispatchEvent(
+        new CustomEvent('confirm', { bubbles: true, detail }),
+      );
+    } else if (actionName === 'cancel') {
+      dialog.dispatchEvent(
+        new CustomEvent('cancel', { bubbles: true, detail }),
+      );
+    }
+    (dialog as unknown as { _dialog?: { close(): void } })._dialog?.close();
+  });
+</script>