@pienter/ui 0.2.0

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

@@ -0,0 +1,117 @@
+<template>
+    <dialog
+        ref="rootRef"
+        v-bind="$attrs"
+        class="pui-alert-dialog"
+        data-state="closed"
+        data-pui-alert-dialog
+        :aria-labelledby="titleId"
+        :aria-describedby="descriptionId"
+    >
+        <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
+                @click="onCancel"
+            >
+                {{ cancelLabel }}
+            </button>
+            <button
+                type="button"
+                class="pui-btn"
+                :data-variant="destructive ? 'danger' : 'primary'"
+                data-size="md"
+                @click="onConfirm"
+            >
+                {{ confirmLabel }}
+            </button>
+        </div>
+    </dialog>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
+import { generateId } from '../../../utils/a11y/id.js';
+import {
+    mountDialog,
+    type DialogControl,
+} from '../../../utils/controllers/dialog.js';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+    defineProps<{
+        open: boolean;
+        title: string;
+        description: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+        destructive?: boolean;
+    }>(),
+    {
+        confirmLabel: 'Confirm',
+        cancelLabel: 'Cancel',
+        destructive: false,
+    },
+);
+
+const emit = defineEmits<{
+    'update:open': [value: boolean];
+    confirm: [];
+    cancel: [];
+}>();
+
+const rootRef = ref<HTMLDialogElement | null>(null);
+const titleId = generateId('alertdialog-title');
+const descriptionId = generateId('alertdialog-desc');
+let control: DialogControl | null = null;
+
+function onConfirm(): void {
+    emit('confirm');
+    emit('update:open', false);
+}
+
+function onCancel(): void {
+    emit('cancel');
+    emit('update:open', false);
+}
+
+onMounted(() => {
+    if (!rootRef.value) return;
+    control = mountDialog(rootRef.value, {
+        role: 'alertdialog',
+        persistent: true,
+        initialFocus: 'cancel',
+        // No onClose — persistent dialogs suppress Escape and backdrop-click
+        // dismissal at the controller layer. Close happens only through the
+        // explicit confirm/cancel buttons wired in the template.
+    });
+    if (props.open) control.open();
+});
+
+watch(
+    () => props.open,
+    (isOpen) => {
+        if (!control) return;
+        if (isOpen) control.open();
+        else control.close();
+    },
+);
+
+onBeforeUnmount(() => {
+    control?.teardown();
+    control = null;
+});
+</script>
+
+<style>
+@import './alert-dialog.css';
+</style>

package/components/overlay/alert-dialog/alert-dialog.css

@@ -0,0 +1,57 @@
+@layer components {
+    .pui-alert-dialog {
+        /* Reset browser default <dialog> styles when shown. */
+        margin: auto;
+        padding: 0;
+        border: var(--stroke-md) solid var(--border-clr-strong);
+        inset: 0;
+
+        /* Surface styling — mirrors Modal but tightened for confirm dialogs. */
+        background: var(--bg-clr-surface);
+        border-radius: var(--radius-md);
+        box-shadow: var(--shadow-spark-lg);
+
+        /* Layout — alert dialogs are typically narrower than full Modals. */
+        max-width: 24rem;
+        width: calc(100% - var(--space-m) * 2);
+    }
+    /* Apply layout-driving display only when the dialog is actually open.
+     Browser default for <dialog>:not([open]) is display: none — preserve
+     that by NOT declaring display in the base rule. The data-state="closed"
+     attribute is preserved as a CSS hook for future transition work. */
+    .pui-alert-dialog[open] {
+        display: grid;
+    }
+    .pui-alert-dialog::backdrop {
+        background: hsl(from var(--border-clr-strong) h s l / 0.5);
+    }
+    .pui-alert-dialog:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+    .pui-alert-dialog__head {
+        padding: var(--space-m) var(--space-m) 0;
+        display: grid;
+        gap: var(--space-2xs);
+    }
+    .pui-alert-dialog__title {
+        font-family: var(--ff-display);
+        font-weight: var(--fw-display);
+        letter-spacing: var(--ls-display);
+        font-size: var(--step-1);
+        margin: 0;
+    }
+    .pui-alert-dialog__description {
+        color: var(--text-clr-muted);
+        margin: 0;
+        font-size: var(--step--1);
+    }
+    .pui-alert-dialog__actions {
+        padding: var(--space-s) var(--space-m) var(--space-m);
+        display: flex;
+        gap: var(--space-2xs);
+        justify-content: flex-end;
+        border-block-start: var(--stroke-sm) solid var(--border-clr-base);
+        margin-block-start: var(--space-s);
+    }
+}

package/components/overlay/command/Command.vue

@@ -0,0 +1,356 @@
+<template>
+    <dialog
+        ref="dialogRef"
+        v-bind="$attrs"
+        class="pui-command"
+        data-state="closed"
+        :aria-labelledby="titleId"
+    >
+        <h2 :id="titleId" class="pui-command__title">{{ title }}</h2>
+        <div class="pui-command__inputwrap">
+            <Icon name="search" size="sm" class="pui-command__searchicon" />
+            <input
+                :id="inputId"
+                ref="inputRef"
+                class="pui-command__input"
+                type="text"
+                role="combobox"
+                :value="query"
+                :placeholder="placeholder"
+                :aria-expanded="commandsOpen ? 'true' : 'false'"
+                :aria-controls="listboxId"
+                :aria-activedescendant="activeOptionDomId || undefined"
+                aria-autocomplete="list"
+                @input="onInput"
+                @keydown="onKeydown"
+            />
+        </div>
+        <ul
+            :id="listboxId"
+            ref="listboxRef"
+            class="pui-command__listbox"
+            role="listbox"
+            :aria-label="title"
+        >
+            <!--
+              ARIA APG combobox/listbox pattern: keyboard interaction is owned
+              by the <input role="combobox"> above via aria-activedescendant
+              (Arrow/Home/End/Enter handled in onKeydown), so the option rows
+              are intentionally NOT focusable (no tabindex) and carry no per-row
+              key handlers. The @click / @mouseenter here are pointer affordances
+              that mirror the already-complete keyboard path. These three rules
+              assume a self-contained interactive element and false-positive on
+              this pattern; the keyboard behaviour they ask for already exists at
+              the combobox level. See W3C WAI-ARIA APG "Combobox".
+            -->
+            <!-- eslint-disable-next-line vuejs-accessibility/click-events-have-key-events, vuejs-accessibility/interactive-supports-focus, vuejs-accessibility/mouse-events-have-key-events -->
+            <li
+                v-for="(cmd, idx) in filteredCommands"
+                :id="`${listboxId}-opt-${idx}`"
+                :key="cmd.id"
+                class="pui-command__option"
+                role="option"
+                :aria-selected="activeIndex === idx ? 'true' : 'false'"
+                :aria-disabled="cmd.disabled ? 'true' : undefined"
+                :data-active="activeIndex === idx ? 'true' : undefined"
+                :data-disabled="cmd.disabled ? 'true' : undefined"
+                @mousedown.prevent
+                @click="onOptionClick(cmd)"
+                @mouseenter="onOptionMouseEnter(idx)"
+            >
+                <span
+                    v-if="cmd.icon"
+                    class="pui-command__icon"
+                    aria-hidden="true"
+                >
+                    <Icon :name="cmd.icon" size="sm" />
+                </span>
+                <span class="pui-command__label">{{ cmd.label }}</span>
+                <kbd v-if="cmd.shortcut" class="pui-command__kbd">{{
+                    cmd.shortcut
+                }}</kbd>
+            </li>
+            <li
+                v-if="filteredCommands.length === 0"
+                class="pui-command__empty"
+                role="presentation"
+            >
+                {{ emptyMessage }}
+            </li>
+        </ul>
+    </dialog>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch, onMounted, onBeforeUnmount } from 'vue';
+import {
+    mountDialog,
+    type DialogControl,
+} from '../../../utils/controllers/dialog.js';
+import { generateId } from '../../../utils/a11y/id.js';
+import Icon from '../../display/icon/Icon.vue';
+import type { IconName } from '../../../icons/index.js';
+
+defineOptions({ inheritAttrs: false });
+
+interface CommandItem {
+    id: string;
+    label: string;
+    icon?: IconName;
+    shortcut?: string;
+    disabled?: boolean;
+    onSelect: () => void;
+}
+
+const props = withDefaults(
+    defineProps<{
+        /**
+         * Controlled open state (paired via `v-model:open`). The parent
+         * owns the boolean; the component reflects it onto the native
+         * `<dialog>.showModal()` lifecycle. Consumers wire their own
+         * `Cmd+K` (or other) shortcut and flip `open` from the handler.
+         */
+        open: boolean;
+        /**
+         * The list of commands to render. Each command needs a stable
+         * `id`, a `label`, and an `onSelect` callback fired when the
+         * user activates the row (click or Enter on the active option).
+         * Optional `icon` (token from the icon registry) and
+         * `shortcut` (display-only string, e.g. `"⌘K"`) decorate the
+         * row; `disabled` mutes the row and skips it in keyboard nav.
+         */
+        commands: CommandItem[];
+        /**
+         * Visually hidden title for the dialog. Used as the dialog's
+         * `aria-labelledby` target so screen readers announce the
+         * palette's purpose on open. Default: "Command palette".
+         */
+        title?: string;
+        /** Placeholder for the search input. Default: "Search commands…". */
+        placeholder?: string;
+        /**
+         * Empty-state message when no commands match the current query.
+         * Default: "No commands found".
+         */
+        emptyMessage?: string;
+        /**
+         * Optional custom filter. Default: case-insensitive substring
+         * match on the command label. Receives the command and the
+         * current query; returns `true` to keep the command visible.
+         */
+        filter?: (command: CommandItem, query: string) => boolean;
+    }>(),
+    {
+        title: 'Command palette',
+        placeholder: 'Search commands…',
+        emptyMessage: 'No commands found',
+        filter: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:open': [value: boolean];
+    close: [];
+}>();
+
+const inputId = generateId('command-input');
+const listboxId = `${inputId}-listbox`;
+const titleId = generateId('command-title');
+
+const dialogRef = ref<HTMLDialogElement | null>(null);
+const inputRef = ref<HTMLInputElement | null>(null);
+const listboxRef = ref<HTMLUListElement | null>(null);
+
+const query = ref('');
+const activeIndex = ref<number | null>(null);
+
+let control: DialogControl | null = null;
+
+// `commandsOpen` mirrors the parent's `open` for the input's
+// `aria-expanded` state — when the dialog is open, the listbox
+// inside is also "open" (visible), so the combobox is expanded.
+const commandsOpen = computed(() => props.open);
+
+function defaultFilter(command: CommandItem, q: string): boolean {
+    if (!q) return true;
+    return command.label.toLowerCase().includes(q.toLowerCase());
+}
+
+const filteredCommands = computed(() => {
+    const fn = props.filter ?? defaultFilter;
+    return props.commands.filter((cmd) => fn(cmd, query.value));
+});
+
+const activeOptionDomId = computed(() => {
+    if (activeIndex.value == null) return null;
+    return `${listboxId}-opt-${activeIndex.value}`;
+});
+
+function requestClose(): void {
+    emit('update:open', false);
+    emit('close');
+}
+
+function moveActive(direction: 1 | -1): void {
+    const len = filteredCommands.value.length;
+    if (len === 0) {
+        activeIndex.value = null;
+        return;
+    }
+    let idx = activeIndex.value;
+    for (let i = 0; i < len; i += 1) {
+        if (idx == null) {
+            idx = direction === 1 ? 0 : len - 1;
+        } else {
+            idx = (idx + direction + len) % len;
+        }
+        if (!filteredCommands.value[idx]?.disabled) {
+            activeIndex.value = idx;
+            scrollActiveIntoView();
+            return;
+        }
+    }
+}
+
+function scrollActiveIntoView(): void {
+    if (activeIndex.value == null || !listboxRef.value) return;
+    const el = listboxRef.value.querySelector<HTMLElement>(
+        `#${CSS.escape(`${listboxId}-opt-${activeIndex.value}`)}`,
+    );
+    el?.scrollIntoView({ block: 'nearest' });
+}
+
+function activateCommand(cmd: CommandItem): void {
+    if (cmd.disabled) return;
+    // Close the palette FIRST so focus returns to the original
+    // trigger, then run the consumer's action. Running the action
+    // first risks a race where the action navigates and focus
+    // restoration lands somewhere unexpected.
+    requestClose();
+    // Defer to a microtask so the close transition starts before
+    // the action fires; for simple actions this is unobservable but
+    // for actions that open another dialog it gives the close path
+    // a clean exit.
+    queueMicrotask(() => cmd.onSelect());
+}
+
+function onInput(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    query.value = target.value;
+    // Reset to first match so Enter has an obvious target.
+    const firstEnabled = filteredCommands.value.findIndex((o) => !o.disabled);
+    activeIndex.value = firstEnabled >= 0 ? firstEnabled : null;
+}
+
+function onOptionClick(cmd: CommandItem): void {
+    activateCommand(cmd);
+}
+
+function onOptionMouseEnter(idx: number): void {
+    if (filteredCommands.value[idx]?.disabled) return;
+    activeIndex.value = idx;
+}
+
+function onKeydown(event: KeyboardEvent): void {
+    switch (event.key) {
+        case 'ArrowDown':
+            event.preventDefault();
+            moveActive(1);
+            break;
+        case 'ArrowUp':
+            event.preventDefault();
+            moveActive(-1);
+            break;
+        case 'Home':
+            event.preventDefault();
+            {
+                const firstEnabled = filteredCommands.value.findIndex(
+                    (o) => !o.disabled,
+                );
+                if (firstEnabled >= 0) {
+                    activeIndex.value = firstEnabled;
+                    scrollActiveIntoView();
+                }
+            }
+            break;
+        case 'End':
+            event.preventDefault();
+            {
+                let lastEnabled = -1;
+                for (
+                    let i = filteredCommands.value.length - 1;
+                    i >= 0;
+                    i -= 1
+                ) {
+                    if (!filteredCommands.value[i]?.disabled) {
+                        lastEnabled = i;
+                        break;
+                    }
+                }
+                if (lastEnabled >= 0) {
+                    activeIndex.value = lastEnabled;
+                    scrollActiveIntoView();
+                }
+            }
+            break;
+        case 'Enter':
+            if (activeIndex.value == null) return;
+            event.preventDefault();
+            {
+                const cmd = filteredCommands.value[activeIndex.value];
+                if (cmd) activateCommand(cmd);
+            }
+            break;
+        // Escape is handled by the native <dialog>'s `cancel` event
+        // via the dialog controller's `onClose`. No need to wire it
+        // here — that would double-fire close.
+        default:
+            break;
+    }
+}
+
+function resetState(): void {
+    query.value = '';
+    // Initial active row is the first enabled command so a single
+    // Enter immediately after opening fires the most likely action.
+    const firstEnabled = props.commands.findIndex((c) => !c.disabled);
+    activeIndex.value = firstEnabled >= 0 ? firstEnabled : null;
+}
+
+onMounted(() => {
+    if (!dialogRef.value) return;
+    control = mountDialog(dialogRef.value, {
+        role: 'dialog',
+        onClose: requestClose,
+    });
+    if (props.open) {
+        resetState();
+        control.open();
+    }
+});
+
+watch(
+    () => props.open,
+    (isOpen) => {
+        if (!control) return;
+        if (isOpen) {
+            // Reset state on every open so the palette always starts
+            // fresh — the canonical Cmd+K UX. Prior query / cursor
+            // position are not preserved between sessions.
+            resetState();
+            control.open();
+        } else {
+            control.close();
+        }
+    },
+);
+
+onBeforeUnmount(() => {
+    control?.teardown();
+    control = null;
+});
+</script>
+
+<style>
+@import './command.css';
+</style>

package/components/overlay/command/command.css

@@ -0,0 +1,179 @@
+@layer components {
+    /* ===== pui-command =====
+   *
+   * Search palette built on the native `<dialog>` element via
+   * `mountDialog`. Reuses the combobox-pattern input + listbox
+   * inside the dialog chrome (search field at the top, scrollable
+   * commands below). The dialog provides top-layer rendering, focus
+   * trapping, and Escape dismissal; the controller layers on
+   * scroll-lock and backdrop-click handling.
+   *
+   * Distinct from Combobox CSS: Command does NOT use the `.pui-field`
+   * form-primitive scaffold (no label/hint/errors — the palette is
+   * an action launcher, not a form control). The input chrome is
+   * minimal (no border, just a leading search icon) since the
+   * dialog's own border supplies the visual frame.
+   */
+
+    .pui-command {
+        /* Reset native <dialog> chrome — the palette supplies its own
+       layout. */
+        margin: 0;
+        padding: 0;
+        border: var(--stroke-md) solid var(--border-clr-strong);
+        inset: 0;
+
+        /* Surface */
+        background: var(--bg-clr-surface);
+        border-radius: var(--radius-md);
+        box-shadow: var(--shadow-spark-lg);
+        color: var(--text-clr-base);
+
+        /* Sizing — palette sits centered, generous max-width so long
+       command labels and shortcuts fit comfortably. The dialog
+       defaults to centered (margin: auto on the [open] state). */
+        width: calc(100% - var(--space-m) * 2);
+        max-width: 36rem;
+        max-height: min(32rem, calc(100vh - var(--space-l) * 2));
+
+        /* Center via the [open] grid layout below. */
+    }
+
+    .pui-command[open] {
+        display: grid;
+        grid-template-rows: auto 1fr;
+        margin: auto;
+    }
+
+    .pui-command::backdrop {
+        background: hsl(from var(--border-clr-strong) h s l / 0.5);
+    }
+
+    .pui-command:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+
+    /* Visually-hidden title — the palette doesn't need a visible
+     heading since the search input + leading icon already explain
+     the surface, but `aria-labelledby` requires a real DOM node
+     with text content. */
+    .pui-command__title {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+    }
+
+    .pui-command__inputwrap {
+        position: relative;
+        display: flex;
+        align-items: center;
+        padding: var(--space-2xs) var(--space-s);
+        border-block-end: var(--stroke-sm) solid var(--border-clr-base);
+    }
+
+    .pui-command__searchicon {
+        color: var(--text-clr-muted);
+        margin-inline-end: var(--space-2xs);
+        flex-shrink: 0;
+    }
+
+    .pui-command__input {
+        /* Borderless input — the dialog's border + the wrap's
+       block-end border supply the visual frame. The search icon
+       precedes the input so the surface reads as a search field. */
+        appearance: none;
+        border: 0;
+        outline: none;
+        background: transparent;
+        width: 100%;
+        padding: var(--space-2xs) 0;
+        font: inherit;
+        font-size: var(--step-0);
+        color: var(--text-clr-base);
+    }
+
+    .pui-command__input::placeholder {
+        color: var(--text-clr-muted);
+    }
+
+    .pui-command__listbox {
+        list-style: none;
+        margin: 0;
+        padding: var(--space-3xs);
+        overflow-y: auto;
+        display: flex;
+        flex-direction: column;
+        gap: 1px;
+    }
+
+    .pui-command__option {
+        appearance: none;
+        background: transparent;
+        border: 0;
+        text-align: start;
+        width: 100%;
+        padding: var(--space-2xs) var(--space-xs);
+        font: inherit;
+        font-size: var(--step--1);
+        color: var(--text-clr-base);
+        border-radius: var(--radius-xs);
+        cursor: pointer;
+
+        /* Three-column row: leading icon, label, trailing shortcut. */
+        display: grid;
+        grid-template-columns: auto 1fr auto;
+        align-items: center;
+        gap: var(--space-2xs);
+    }
+
+    .pui-command__option[data-active='true']:not([data-disabled='true']) {
+        background: var(--bg-clr-surface-2);
+    }
+
+    .pui-command__option[data-disabled='true'] {
+        color: var(--text-clr-muted);
+        cursor: not-allowed;
+        opacity: 0.6;
+    }
+
+    .pui-command__icon {
+        color: var(--text-clr-muted);
+        display: inline-flex;
+        align-items: center;
+    }
+
+    .pui-command__label {
+        /* Truncate single-line labels gracefully; long descriptions
+       belong in a Tooltip on the row, not in the row itself. */
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .pui-command__kbd {
+        /* Display-only shortcut hint. Uses the mono-style font and a
+       tiny pill so the row visually reads as "label — shortcut". */
+        font-family: var(--ff-mono);
+        font-size: var(--step--2);
+        color: var(--text-clr-muted);
+        background: var(--bg-clr-surface-2);
+        border: var(--stroke-sm) solid var(--border-clr-base);
+        border-radius: var(--radius-xs);
+        padding: 2px var(--space-3xs);
+    }
+
+    .pui-command__empty {
+        padding: var(--space-s) var(--space-xs);
+        color: var(--text-clr-muted);
+        font-size: var(--step--1);
+        font-style: italic;
+        text-align: center;
+    }
+}