@pienter/ui 0.2.0

package/components/overlay/dropdown-menu/DropdownMenu.vue

@@ -0,0 +1,143 @@
+<template>
+    <div
+        :id="id"
+        ref="menuRef"
+        v-bind="$attrs"
+        class="pui-dropdown-menu"
+        role="menu"
+        data-state="closed"
+        :aria-labelledby="ariaLabelledBy"
+    >
+        <slot />
+    </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
+import {
+    mountPopover,
+    type PopoverControl,
+    type Placement,
+} from '../../../utils/controllers/popover.js';
+import { mountMenu } from '../../../utils/controllers/menu.js';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+    defineProps<{
+        /**
+         * Required `id` for the dropdown menu element. The consumer
+         * wires their trigger button via the native HTML
+         * `popovertarget="<id>"` attribute, which `mountPopover`
+         * auto-detects on mount as the positioning anchor and as the
+         * focus-restore target on close.
+         */
+        id: string;
+        /**
+         * Optional controlled open state. When provided the parent
+         * owns the value via `v-model:open`; the component reflects
+         * it onto the native popover open state. When omitted the
+         * menu opens on declarative `popovertarget` clicks (the
+         * native pattern) and the `update:open` emit reports the
+         * change in either direction.
+         */
+        open?: boolean;
+        /**
+         * Initial placement; the controller flips automatically on
+         * viewport collision. Default: `'bottom-start'` — the
+         * convention for menus, which align under the trigger's left
+         * edge in LTR.
+         */
+        placement?: Placement;
+        /**
+         * Offset from the anchor edge in pixels. Default: `4` —
+         * tighter than Popover (8) because menus are extensions of
+         * their trigger button visually rather than separate
+         * surfaces.
+         */
+        offset?: number;
+        /**
+         * Optional id of a label element that names the menu (e.g. a
+         * visually-hidden heading describing the actions inside).
+         * Most dropdowns labeled by their trigger don't need this —
+         * the trigger already names the menu via the
+         * `popovertarget` association — so the prop is optional.
+         */
+        ariaLabelledBy?: string;
+    }>(),
+    {
+        open: undefined,
+        placement: 'bottom-start',
+        offset: 4,
+        ariaLabelledBy: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:open': [value: boolean];
+}>();
+
+const menuRef = ref<HTMLElement | null>(null);
+let popoverControl: PopoverControl | null = null;
+let menuTeardown: (() => void) | null = null;
+
+onMounted(() => {
+    if (!menuRef.value) return;
+    popoverControl = mountPopover(menuRef.value, {
+        placement: props.placement,
+        offset: props.offset,
+        // `modal: false` (default) → `popover="auto"` so the browser
+        // handles outside-click / focus-loss / Escape light-dismiss.
+        // The menu is non-modal — page content remains visible and
+        // interactive once the menu closes.
+        onOpen: () => {
+            emit('update:open', true);
+            // Move focus to the first menu item on open per the
+            // WAI-ARIA Menu pattern. The browser does NOT auto-focus
+            // popover content; the controller leaves focus management
+            // to consumers, so we explicitly walk into the menu here.
+            const firstItem = menuRef.value?.querySelector<HTMLElement>(
+                '[role="menuitem"]:not([disabled]):not([aria-disabled="true"]),' +
+                    ' [role="menuitemcheckbox"]:not([disabled]):not([aria-disabled="true"]),' +
+                    ' [role="menuitemradio"]:not([disabled]):not([aria-disabled="true"])',
+            );
+            firstItem?.focus();
+        },
+        onClose: () => emit('update:open', false),
+    });
+    menuTeardown = mountMenu({
+        menuEl: menuRef.value,
+        // Escape closes the menu and lets `popover="auto"`'s
+        // light-dismiss + the controller's `toggle` event handle
+        // focus restoration to the trigger.
+        onEscape: () => popoverControl?.hide(),
+        // Auto-close on item click is the standard menu UX. The
+        // consumer's own `@click` on each `<button role="menuitem">`
+        // runs first (DOM bubble); this callback fires from
+        // `mountMenu`'s container-level click listener and closes
+        // the menu after the action.
+        onItemActivate: () => popoverControl?.hide(),
+    });
+    if (props.open) popoverControl.show();
+});
+
+watch(
+    () => props.open,
+    (isOpen) => {
+        if (!popoverControl || isOpen === undefined) return;
+        if (isOpen) popoverControl.show();
+        else popoverControl.hide();
+    },
+);
+
+onBeforeUnmount(() => {
+    menuTeardown?.();
+    menuTeardown = null;
+    popoverControl?.teardown();
+    popoverControl = null;
+});
+</script>
+
+<style>
+@import './dropdown-menu.css';
+</style>

package/components/overlay/dropdown-menu/dropdown-menu.css

@@ -0,0 +1,120 @@
+@layer components {
+    .pui-dropdown-menu {
+        /* Reset native popover defaults — the user-agent centers
+       a popover at the viewport origin via inset/margin/padding
+       defaults that interfere with anchor positioning. */
+        margin: 0;
+        border: 0;
+        inset: auto;
+
+        /* Surface — lighter weight than Popover (uses --shadow-spark
+       instead of --shadow-spark-lg, --stroke-sm instead of
+       --stroke-md) because menus are extensions of their trigger
+       rather than standalone content surfaces. */
+        background: var(--bg-clr-surface);
+        border: var(--stroke-sm) solid var(--border-clr-base);
+        border-radius: var(--radius-sm);
+        box-shadow: var(--shadow-spark);
+        color: var(--text-clr-base);
+        min-width: 12rem;
+        padding: var(--space-3xs);
+
+        /* Position is set by the controller via inline `left`/`top`.
+       `position: fixed` is declared explicitly for self-doc — the
+       Popover API's top-layer rendering already produces the same
+       effect via the user-agent rule. */
+        position: fixed;
+
+        /* Stack items vertically with a hair-line gap so the
+       :focus-visible outline of one item never touches the
+       hover-bg of the neighbour. */
+        display: flex;
+        flex-direction: column;
+        gap: 1px;
+    }
+
+    /* Menu items — the consumer's `<button role="menuitem">`
+     elements (or the checkbox / radio variants). All three roles
+     get the same surface treatment so the menu reads visually
+     consistent regardless of which variant a row uses. */
+    .pui-dropdown-menu [role='menuitem'],
+    .pui-dropdown-menu [role='menuitemcheckbox'],
+    .pui-dropdown-menu [role='menuitemradio'] {
+        /* Reset button styles — menu items are intentionally borderless
+       full-width rows that look like list rows, not Buttons. */
+        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;
+
+        /* Multi-element row layout — icon + label + (optional) trailing
+       shortcut. Consumers compose freely inside the menuitem; the
+       flex container makes that composition look right by default. */
+        display: flex;
+        align-items: center;
+        gap: var(--space-2xs);
+    }
+
+    .pui-dropdown-menu
+        [role='menuitem']:hover:not(:disabled):not([aria-disabled='true']),
+    .pui-dropdown-menu
+        [role='menuitemcheckbox']:hover:not(:disabled):not(
+            [aria-disabled='true']
+        ),
+    .pui-dropdown-menu
+        [role='menuitemradio']:hover:not(:disabled):not(
+            [aria-disabled='true']
+        ) {
+        background: var(--bg-clr-surface-2);
+    }
+
+    .pui-dropdown-menu [role='menuitem']:focus-visible,
+    .pui-dropdown-menu [role='menuitemcheckbox']:focus-visible,
+    .pui-dropdown-menu [role='menuitemradio']:focus-visible {
+        /* Inset outline so the keyboard-focus ring stays inside the
+       menu surface rather than clipping against the menu's own
+       border. -2px offset matches the item's hover bg padding so
+       the outline traces the row precisely. */
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: -2px;
+    }
+
+    .pui-dropdown-menu [role='menuitem']:disabled,
+    .pui-dropdown-menu [role='menuitem'][aria-disabled='true'],
+    .pui-dropdown-menu [role='menuitemcheckbox']:disabled,
+    .pui-dropdown-menu [role='menuitemcheckbox'][aria-disabled='true'],
+    .pui-dropdown-menu [role='menuitemradio']:disabled,
+    .pui-dropdown-menu [role='menuitemradio'][aria-disabled='true'] {
+        color: var(--text-clr-muted);
+        cursor: not-allowed;
+        opacity: 0.6;
+    }
+
+    /* Separators between groups — `<hr role="separator">` is the
+     canonical pattern. Reset the user-agent's <hr> styling and
+     replace with a thin in-menu rule. */
+    .pui-dropdown-menu hr[role='separator'],
+    .pui-dropdown-menu [role='separator'] {
+        border: 0;
+        border-block-start: var(--stroke-sm) solid var(--border-clr-base);
+        margin: var(--space-3xs) 0;
+        block-size: 0;
+    }
+
+    /* Group labels — non-interactive headings introducing a section
+     of menu items. Rendered as `<div role="presentation">` or a
+     `<span>` by the consumer. */
+    .pui-dropdown-menu [role='presentation']:not(hr) {
+        padding: var(--space-2xs) var(--space-xs);
+        font-size: var(--step--2);
+        color: var(--text-clr-muted);
+        font-weight: var(--fw-semibold);
+    }
+}

package/components/overlay/modal/Modal.astro

@@ -0,0 +1,66 @@
+---
+import './modal.css';
+import { generateId } from '../../../utils/a11y/id.js';
+
+interface Props {
+  id?: string;
+  open?: boolean;
+  persistent?: boolean;
+  title: string;
+  subtitle?: string;
+}
+
+const {
+  id,
+  open = false,
+  persistent = false,
+  title,
+  subtitle,
+  ...rest
+} = Astro.props;
+
+const modalId = id ?? generateId('modal');
+const titleId = `${modalId}-title`;
+---
+
+<dialog
+  id={modalId}
+  class="pui-modal"
+  data-state="closed"
+  data-pui-modal
+  data-persistent={persistent ? 'true' : undefined}
+  data-open-initially={open ? 'true' : undefined}
+  aria-labelledby={titleId}
+  {...rest}
+>
+  <div class="pui-modal__head">
+    <h2 id={titleId} class="pui-modal__title">{title}</h2>
+    {subtitle && <p class="pui-modal__sub">{subtitle}</p>}
+  </div>
+  <div class="pui-modal__body"><slot /></div>
+  {
+    Astro.slots.has('footer') && (
+      <div class="pui-modal__foot">
+        <slot name="footer" />
+      </div>
+    )
+  }
+</dialog>
+
+<script>
+  import { mountDialog } from '@pienter/ui/utils/controllers/dialog.js';
+
+  document
+    .querySelectorAll<HTMLDialogElement>('dialog[data-pui-modal]')
+    .forEach((el) => {
+      const node = el as HTMLDialogElement & {
+        _dialog?: ReturnType<typeof mountDialog>;
+      };
+      if (node._dialog) return; // idempotent — guard against double-mounts (HMR, multiple <Modal> imports)
+      const persistent = el.dataset.persistent === 'true';
+      const openInitially = el.dataset.openInitially === 'true';
+      const control = mountDialog(el, { persistent });
+      node._dialog = control;
+      if (openInitially) control.open();
+    });
+</script>

package/components/overlay/modal/Modal.vue

@@ -0,0 +1,85 @@
+<template>
+    <dialog
+        ref="rootRef"
+        v-bind="$attrs"
+        class="pui-modal"
+        data-state="closed"
+        data-pui-modal
+        :aria-labelledby="titleId"
+    >
+        <div class="pui-modal__head">
+            <h2 :id="titleId" class="pui-modal__title">{{ title }}</h2>
+            <p v-if="subtitle" class="pui-modal__sub">{{ subtitle }}</p>
+        </div>
+        <div class="pui-modal__body"><slot /></div>
+        <div v-if="$slots.footer" class="pui-modal__foot">
+            <slot name="footer" />
+        </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;
+        subtitle?: string;
+        persistent?: boolean;
+    }>(),
+    {
+        subtitle: undefined,
+        persistent: false,
+    },
+);
+
+const emit = defineEmits<{
+    'update:open': [value: boolean];
+    close: [];
+}>();
+
+const rootRef = ref<HTMLDialogElement | null>(null);
+const titleId = generateId('modal-title');
+let control: DialogControl | null = null;
+
+function requestClose() {
+    emit('update:open', false);
+    emit('close');
+}
+
+onMounted(() => {
+    if (!rootRef.value) return;
+    control = mountDialog(rootRef.value, {
+        role: 'dialog',
+        persistent: props.persistent,
+        onClose: requestClose,
+    });
+    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 './modal.css';
+</style>

package/components/overlay/modal/modal.css

@@ -0,0 +1,60 @@
+@layer components {
+    .pui-modal {
+        /* Reset browser default <dialog> styles when shown. */
+        margin: auto;
+        padding: 0;
+        border: var(--stroke-md) solid var(--border-clr-strong);
+        inset: 0;
+
+        /* Surface styling. */
+        background: var(--bg-clr-surface);
+        border-radius: var(--radius-md);
+        box-shadow: var(--shadow-spark-lg);
+
+        /* Layout (max-width / width — these don't affect display). */
+        max-width: 32rem;
+        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-modal[open] {
+        display: grid;
+    }
+    .pui-modal::backdrop {
+        background: hsl(from var(--border-clr-strong) h s l / 0.5);
+    }
+    .pui-modal:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+    .pui-modal__head {
+        padding: var(--space-m) var(--space-m) 0;
+        display: grid;
+        gap: var(--space-2xs);
+    }
+    .pui-modal__title {
+        font-family: var(--ff-display);
+        font-weight: var(--fw-display);
+        letter-spacing: var(--ls-display);
+        font-size: var(--step-1);
+        margin: 0;
+    }
+    .pui-modal__sub {
+        color: var(--text-clr-muted);
+        margin: 0;
+        font-size: var(--step--1);
+    }
+    .pui-modal__body {
+        padding: var(--space-s) var(--space-m);
+    }
+    .pui-modal__foot {
+        padding: var(--space-xs) 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-2xs);
+    }
+}

package/components/overlay/popover/Popover.vue

@@ -0,0 +1,113 @@
+<template>
+    <div
+        :id="id"
+        ref="rootRef"
+        v-bind="$attrs"
+        class="pui-popover"
+        role="dialog"
+        data-state="closed"
+        data-pui-popover
+        :aria-labelledby="ariaLabelledBy"
+    >
+        <slot />
+    </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
+import {
+    mountPopover,
+    type PopoverControl,
+    type Placement,
+} from '../../../utils/controllers/popover.js';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+    defineProps<{
+        /**
+         * Required `id` for the popover element. Consumers wire their
+         * trigger button via the native HTML `popovertarget="<id>"`
+         * attribute, which the controller auto-detects on mount —
+         * this is the link between the trigger and the popover.
+         */
+        id: string;
+        /**
+         * Optional controlled open state. When provided, the parent
+         * owns the value via `v-model:open`; the component reflects
+         * it onto the native popover open state. When omitted the
+         * popover opens on declarative `popovertarget` clicks (the
+         * native pattern) and the `update:open` emit reports the
+         * change.
+         */
+        open?: boolean;
+        /**
+         * Initial placement; the controller flips automatically on
+         * viewport collision. Default: `'bottom-start'`.
+         */
+        placement?: Placement;
+        /**
+         * Offset from the anchor edge in pixels. Default: `8`.
+         */
+        offset?: number;
+        /**
+         * When `true`, uses `popover="manual"` — the popover stays
+         * open until programmatically dismissed (no light-dismiss).
+         * When `false` (default), uses `popover="auto"` for the
+         * standard click-outside / focus-out / Escape dismissal.
+         */
+        modal?: boolean;
+        /**
+         * Optional id of the heading element inside the popover, used
+         * for `aria-labelledby`. Consumers supply this when the
+         * popover has a visible title; tooltips skip it (the trigger
+         * already labels the surface).
+         */
+        ariaLabelledBy?: string;
+    }>(),
+    {
+        open: undefined,
+        placement: 'bottom-start',
+        offset: 8,
+        modal: false,
+        ariaLabelledBy: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:open': [value: boolean];
+}>();
+
+const rootRef = ref<HTMLElement | null>(null);
+let control: PopoverControl | null = null;
+
+onMounted(() => {
+    if (!rootRef.value) return;
+    control = mountPopover(rootRef.value, {
+        placement: props.placement,
+        offset: props.offset,
+        modal: props.modal,
+        onOpen: () => emit('update:open', true),
+        onClose: () => emit('update:open', false),
+    });
+    if (props.open) control.show();
+});
+
+watch(
+    () => props.open,
+    (isOpen) => {
+        if (!control || isOpen === undefined) return;
+        if (isOpen) control.show();
+        else control.hide();
+    },
+);
+
+onBeforeUnmount(() => {
+    control?.teardown();
+    control = null;
+});
+</script>
+
+<style>
+@import './popover.css';
+</style>

package/components/overlay/popover/popover.css

@@ -0,0 +1,53 @@
+@layer components {
+    .pui-popover {
+        /* Reset native popover defaults — the browser centers a popover
+       at the viewport origin via inset/margin/padding/border defaults
+       that interfere with anchor positioning. */
+        margin: 0;
+        padding: 0;
+        border: 0;
+        inset: auto;
+
+        /* Surface — matches the dialog family for visual consistency
+       across overlays. */
+        background: var(--bg-clr-surface);
+        border: var(--stroke-md) solid var(--border-clr-strong);
+        border-radius: var(--radius-md);
+        box-shadow: var(--shadow-spark-lg);
+        color: var(--text-clr-base);
+
+        /* Default sizing — generous max-width prevents narrow popovers
+       on long content; consumers override via class for surfaces
+       that need a fixed width (combobox listbox, dropdown menu). */
+        max-width: min(20rem, calc(100vw - 1rem));
+
+        /* The Popover API places the element in the top layer and
+       defaults to `position: fixed`. Inline `left`/`top` from the
+       controller drive the actual placement. We declare `position:
+       fixed` explicitly here so authors who inspect the rule see
+       the contract; the browser's user-agent rules already produce
+       the same effect. */
+        position: fixed;
+
+        /* Internal padding — the popover's content uses tokens. */
+        padding: var(--space-2xs);
+    }
+
+    /* Visible-state styling via the native pseudo-class. The popover
+     is hidden by default (`display: none` per the user-agent) until
+     `:popover-open` matches; we add no additional `display` rule so
+     the browser default keeps working. */
+    .pui-popover:popover-open {
+        /* Surface visibility is the browser default; hook left for
+       per-consumer animation overrides keyed off `data-state`. */
+    }
+
+    .pui-popover:focus-visible {
+        outline: 3px solid var(--outline-clr-base);
+        outline-offset: 2px;
+    }
+
+    /* The browser does NOT render a backdrop for `popover` (unlike
+     `<dialog>.showModal()`). We intentionally do NOT style
+     `::backdrop` — popovers are non-modal by design. */
+}