@pienter/ui 0.2.0

package/styles/0-settings/spacing.css

@@ -0,0 +1,15 @@
+:root {
+    --space-3xs: 0.25rem;
+    --space-2xs: 0.5rem;
+    --space-xs: 0.75rem;
+    --space-s: 1rem;
+    --space-m: 1.5rem;
+    --space-l: 2rem;
+    --space-xl: 3rem;
+    --space-2xl: 4rem;
+    --space-3xl: 6rem;
+
+    /* Layout-shell widths (used by Sidebar et al.) */
+    --space-sidebar-width: 16rem;
+    --space-sidebar-width-collapsed: 4rem;
+}

package/styles/0-settings/typography.css

@@ -0,0 +1,37 @@
+:root {
+    /* The lower rungs are cut for dense admin surfaces: --step--1 is the size UI
+     text and controls actually run at, and --step-0 stays the reading size for
+     prose. Anything below --step--2 is for legal/meta text only. */
+    --step--3: 0.625rem; /* 10px */
+    --step--2: 0.75rem; /* 12px — badges, uppercase section labels */
+    --step--1: 0.875rem; /* 14px — body, controls, table cells */
+    --step-0: 1rem;
+    --step-1: 1.25rem;
+    --step-2: 1.5rem;
+    --step-3: 2rem;
+    --step-4: 2.5rem;
+    --step-5: 3rem;
+    --step-6: 4rem;
+
+    --ff-base:
+        system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,
+        sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';
+    --ff-mono:
+        ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
+    --fw-regular: 400;
+    --fw-semibold: 600;
+    --fw-control: 650;
+    --fw-bold: 700;
+
+    --lh-tight: 1.1;
+    --lh-base: 1.5;
+    --lh-control: 1.2;
+
+    --ff-display: var(--ff-base);
+    --fs-display: var(--step-4);
+    --fw-display: 800;
+
+    --ls-display: -0.04em;
+    --ls-eyebrow: 0.12em;
+    --ls-label: 0.04em; /* uppercase section headers — a fraction of --ls-eyebrow's spread */
+}

package/styles/0-utils/index.css

@@ -0,0 +1 @@
+/* Reserved for shared CSS utility helpers that are not tied to one layer. */

package/styles/1-reset/index.css

@@ -0,0 +1 @@
+@import url('./reset.css');

package/styles/1-reset/reset.css

@@ -0,0 +1,26 @@
+@layer reset {
+    *,
+    *::before,
+    *::after {
+        box-sizing: border-box;
+    }
+
+    body,
+    h1,
+    h2,
+    h3,
+    p,
+    ul,
+    ol,
+    figure,
+    blockquote {
+        margin: 0;
+    }
+
+    img,
+    picture,
+    svg {
+        display: block;
+        max-width: 100%;
+    }
+}

package/styles/2-base/base.css

@@ -0,0 +1,42 @@
+@layer base {
+    html,
+    body {
+        min-height: 100%;
+    }
+
+    body {
+        font-family: var(--ff-base);
+        font-size: var(--step--1);
+        line-height: var(--lh-base);
+        color: var(--text-clr-base);
+        background: var(--bg-clr-gradient);
+    }
+
+    h1,
+    h2,
+    h3 {
+        line-height: var(--lh-tight);
+        text-wrap: balance;
+    }
+
+    h1 {
+        font-size: var(--step-2);
+    }
+
+    h2 {
+        font-size: var(--step-1);
+    }
+
+    p {
+        color: var(--text-clr-muted);
+    }
+
+    a {
+        color: var(--text-clr-brand);
+        text-underline-offset: 0.14em;
+    }
+
+    a:hover {
+        color: var(--text-clr-brand-hover);
+    }
+}

package/styles/2-base/forms.css

@@ -0,0 +1,23 @@
+@layer base {
+    label {
+        display: block;
+        font-weight: var(--fw-semibold);
+        margin-bottom: var(--space-xs);
+    }
+
+    input,
+    textarea,
+    select {
+        width: 100%;
+        border: var(--stroke-sm) solid var(--border-clr-base);
+        border-radius: var(--radius-sm);
+        padding: var(--space-s);
+        font: inherit;
+        color: var(--text-clr-base);
+        background: var(--bg-clr-surface);
+    }
+
+    button {
+        font: inherit;
+    }
+}

package/styles/2-base/index.css

@@ -0,0 +1,2 @@
+@import url('./base.css');
+@import url('./forms.css');

package/styles/3-layout/container.css

@@ -0,0 +1,57 @@
+@layer layout {
+    .container {
+        display: grid;
+        gap: var(--gap);
+        grid-template-columns:
+            calc((100vw - var(--container-width-md)) / 2) repeat(
+                var(--grid-columns),
+                1fr
+            )
+            calc((100vw - var(--container-width-md)) / 2);
+        width: 100%;
+
+        &[data-container-width='sm'] {
+            grid-template-columns:
+                calc((100vw - var(--container-width-sm)) / 2) repeat(
+                    var(--grid-columns),
+                    1fr
+                )
+                calc((100vw - var(--container-width-sm)) / 2);
+        }
+
+        &[data-container-width='lg'] {
+            grid-template-columns:
+                calc((100vw - var(--container-width-lg)) / 2) repeat(
+                    var(--grid-columns),
+                    1fr
+                )
+                calc((100vw - var(--container-width-lg)) / 2);
+        }
+    }
+
+    .container__content {
+        grid-column: 2;
+        min-width: 0;
+    }
+
+    .container__full-content {
+        grid-column: 1 / -1;
+        min-width: 0;
+    }
+
+    .container__grid-content {
+        grid-column: 2;
+        display: grid;
+        grid-template-columns: repeat(var(--grid-columns), minmax(0, 1fr));
+        gap: var(--gap);
+    }
+
+    @media (max-width: 48rem) {
+        .container[data-decorator-title]::after {
+            position: static;
+            display: block;
+            margin-block-end: var(--space-s);
+            text-align: right;
+        }
+    }
+}

package/styles/3-layout/index.css

@@ -0,0 +1,2 @@
+@import url('./section.css');
+@import url('./container.css');

package/styles/3-layout/section.css

@@ -0,0 +1,17 @@
+@layer layout {
+    .section {
+        padding-block: var(--space-3xl);
+    }
+
+    .section[data-spacing='small'] {
+        padding-block: var(--space-2xl);
+    }
+
+    .section[data-spacing='large'] {
+        padding-block: var(--space-3xl);
+    }
+
+    .section + .section {
+        padding-block-start: 0;
+    }
+}

package/styles/5-utilities/accessibility.css

@@ -0,0 +1,13 @@
+@layer utilities {
+    .u-visually-hidden {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+    }
+}

package/styles/5-utilities/index.css

@@ -0,0 +1,2 @@
+@import url('./accessibility.css');
+@import url('./text.css');

package/styles/5-utilities/text.css

@@ -0,0 +1,5 @@
+@layer utilities {
+    .u-muted {
+        color: var(--text-clr-muted);
+    }
+}

package/styles/main.css

@@ -0,0 +1,8 @@
+@layer reset, base, layout, components, utilities;
+
+@import url('./0-settings/index.css');
+@import url('./0-utils/index.css');
+@import url('./1-reset/index.css');
+@import url('./2-base/index.css');
+@import url('./3-layout/index.css');
+@import url('./5-utilities/index.css');

package/styles/styles.d.ts

@@ -0,0 +1,6 @@
+// Type stub for the `@pienter/ui/styles` subpath. That export is a CSS bundle
+// imported only for its side effects (`import '@pienter/ui/styles'`). Under
+// `moduleResolution: bundler`, TypeScript needs a declaration for the bare
+// specifier or it raises TS2882; this empty module provides one. Wired via the
+// `types` condition on the `./styles` export in package.json.
+export {};

package/utils/a11y/focus.ts

@@ -0,0 +1,68 @@
+export interface FocusTrap {
+    release: () => void;
+}
+
+const focusableSelector =
+    'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export function getFocusableElements(container: HTMLElement): HTMLElement[] {
+    return Array.from(
+        container.querySelectorAll<HTMLElement>(focusableSelector),
+    );
+}
+
+export function createFocusTrap(container: HTMLElement): FocusTrap {
+    function handleKeyDown(event: KeyboardEvent): void {
+        if (event.key !== 'Tab') return;
+
+        const focusable = getFocusableElements(container);
+        if (focusable.length === 0) return;
+
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        if (!first || !last) return;
+
+        if (event.shiftKey) {
+            if (document.activeElement === first) {
+                event.preventDefault();
+                last.focus();
+            }
+        } else {
+            if (document.activeElement === last) {
+                event.preventDefault();
+                first.focus();
+            }
+        }
+    }
+
+    container.addEventListener('keydown', handleKeyDown);
+
+    return {
+        release() {
+            container.removeEventListener('keydown', handleKeyDown);
+        },
+    };
+}
+
+export function focusFirstInvalid(formEl: HTMLElement): boolean {
+    const firstInvalid = formEl.querySelector<HTMLElement>(
+        '[aria-invalid="true"]',
+    );
+    if (!firstInvalid) return false;
+
+    // <fieldset> isn't focusable by default; if the matched element is a
+    // fieldset (e.g., RadioGroup's group-level aria-invalid), drill in and
+    // focus the first non-disabled focusable child. Future grouped-control
+    // primitives (fieldsets of date pickers, checkbox groups, etc.) inherit
+    // this behaviour without re-derivation.
+    if (firstInvalid instanceof HTMLFieldSetElement) {
+        const firstFocusable = getFocusableElements(firstInvalid)[0];
+        if (firstFocusable) {
+            firstFocusable.focus();
+            return true;
+        }
+    }
+
+    firstInvalid.focus();
+    return true;
+}

package/utils/a11y/id.ts

@@ -0,0 +1,10 @@
+let counter = 0;
+
+export function generateId(prefix: string): string {
+    counter += 1;
+    return `${prefix}-${counter}`;
+}
+
+export function resetIdCounter(): void {
+    counter = 0;
+}

package/utils/a11y/index.ts

@@ -0,0 +1,9 @@
+export { generateId, resetIdCounter } from './id.js';
+export {
+    createFocusTrap,
+    getFocusableElements,
+    focusFirstInvalid,
+    type FocusTrap,
+} from './focus.js';
+export { onKeyboardNav, type KeyboardNavHandlers } from './keyboard.js';
+export { announce, type LiveRegionPriority } from './live-region.js';

package/utils/a11y/keyboard.ts

@@ -0,0 +1,32 @@
+export type KeyboardNavHandlers = {
+    ArrowUp?: (event: KeyboardEvent) => void;
+    ArrowDown?: (event: KeyboardEvent) => void;
+    ArrowLeft?: (event: KeyboardEvent) => void;
+    ArrowRight?: (event: KeyboardEvent) => void;
+    Enter?: (event: KeyboardEvent) => void;
+    Escape?: (event: KeyboardEvent) => void;
+    Space?: (event: KeyboardEvent) => void;
+    Home?: (event: KeyboardEvent) => void;
+    End?: (event: KeyboardEvent) => void;
+    PageUp?: (event: KeyboardEvent) => void;
+    PageDown?: (event: KeyboardEvent) => void;
+};
+
+export function onKeyboardNav(
+    element: HTMLElement,
+    handlers: KeyboardNavHandlers,
+): () => void {
+    function handleKeyDown(event: KeyboardEvent): void {
+        const key = event.key === ' ' ? 'Space' : event.key;
+        const handler = handlers[key as keyof KeyboardNavHandlers];
+        if (handler) {
+            handler(event);
+        }
+    }
+
+    element.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+        element.removeEventListener('keydown', handleKeyDown);
+    };
+}

package/utils/a11y/live-region.ts

@@ -0,0 +1,36 @@
+export type LiveRegionPriority = 'polite' | 'assertive';
+
+const REGION_ID = 'pienter-ui-live-region';
+
+function ensureLiveRegion(): HTMLElement {
+    let region = document.getElementById(REGION_ID);
+    if (!region) {
+        region = document.createElement('div');
+        region.id = REGION_ID;
+        region.setAttribute('aria-live', 'polite');
+        region.setAttribute('aria-atomic', 'true');
+        region.style.position = 'absolute';
+        region.style.width = '1px';
+        region.style.height = '1px';
+        region.style.padding = '0';
+        region.style.margin = '-1px';
+        region.style.overflow = 'hidden';
+        region.style.clip = 'rect(0, 0, 0, 0)';
+        region.style.whiteSpace = 'nowrap';
+        region.style.border = '0';
+        document.body.appendChild(region);
+    }
+    return region;
+}
+
+export function announce(
+    text: string,
+    priority: LiveRegionPriority = 'polite',
+): void {
+    const region = ensureLiveRegion();
+    region.setAttribute('aria-live', priority);
+    region.textContent = '';
+    setTimeout(() => {
+        region.textContent = text;
+    }, 50);
+}

package/utils/controllers/dialog.ts

@@ -0,0 +1,205 @@
+import { lockScroll } from '../dom/scroll-lock.js';
+
+/**
+ * Imperative control surface returned by `mountDialog`. The controller
+ * owns the dialog's runtime state (open/closed, scroll lock) and lets the
+ * native `<dialog>` element handle top-layer rendering, focus trapping,
+ * and Escape dismissal. Frameworks (Vue, Astro consumer scripts) act as
+ * the trigger source — they call `open()` / `close()` and watch incoming
+ * prop changes — but they never own state directly. This avoids the dual
+ * state-machine problem where framework state and controller state desync.
+ */
+export interface DialogControl {
+    open(): void;
+    close(): void;
+    isOpen(): boolean;
+    teardown(): void;
+}
+
+export interface DialogConfig {
+    /**
+     * ARIA role assigned to the `<dialog>` element. The browser's default
+     * for `<dialog>` is `'dialog'`; only override (e.g. for AlertDialog)
+     * when needed. Setting this calls `setAttribute('role', …)`.
+     */
+    role?: 'dialog' | 'alertdialog';
+    /**
+     * When `true`, the controller suppresses the default close behavior on
+     * Escape (by calling `event.preventDefault()` on the `cancel` event)
+     * and ignores backdrop clicks. Used by AlertDialog. Default: `false`.
+     */
+    persistent?: boolean;
+    /**
+     * Where focus lands when the dialog opens.
+     *
+     * The native `<dialog>.showModal()` already auto-focuses the first
+     * focusable child (or the element with `[autofocus]`). This config
+     * lets callers override that default:
+     * - `'first'` (default): defer to the browser's native behavior.
+     * - `'cancel'`: focus the element marked `[data-dialog-cancel]`
+     *   (used by AlertDialog).
+     * - `HTMLElement`: explicit element to focus.
+     * - `null`: skip override; defer to the browser's native behavior.
+     *
+     * If a `[data-dialog-initial-focus]` element exists inside the dialog,
+     * it ALWAYS wins over the configured value (consumer override).
+     */
+    initialFocus?: 'first' | 'cancel' | HTMLElement | null;
+    /**
+     * Called when the user requests close (Escape key, backdrop click).
+     * The controller does NOT auto-close in this case — the framework
+     * reflects the close intent back through its prop/v-model and calls
+     * `close()` itself, keeping framework state authoritative for the
+     * open/closed boolean.
+     */
+    onClose?: () => void;
+}
+
+/**
+ * Mount the dialog controller on `el`, which MUST be a `<dialog>`
+ * element. The native element provides top-layer rendering, focus
+ * trapping, Escape dismissal (via the `cancel` event), and the
+ * `::backdrop` pseudo-element; this controller layers on body-scroll
+ * lock, backdrop-click dismissal, persistent suppression, an
+ * `initialFocus` override, and `data-state` reflection so the existing
+ * CSS conventions keep working.
+ *
+ * Lifecycle:
+ * 1. On mount: optionally set `role` (AlertDialog uses `'alertdialog'`),
+ *    wire `cancel` and `click` listeners.
+ * 2. `open()`: capture trigger, call `el.showModal()` (native top-layer
+ *    + focus trap), set `data-state="open"`, lock scroll, apply
+ *    `initialFocus` override after a frame.
+ * 3. `close()`: call `el.close()` (native focus restoration to trigger),
+ *    set `data-state="closed"`, unlock scroll. A backup focus restore
+ *    runs only when the browser fails to restore (e.g., the trigger
+ *    was removed from the DOM mid-open).
+ * 4. `teardown()`: ensures close ran, then removes listeners.
+ *
+ * The controller does NOT decide when to close — `onClose` is invoked
+ * on user-requested close (Escape, backdrop click). The caller is
+ * responsible for reflecting that into framework state and calling
+ * `close()`. The framework's reactive prop is the source of truth for
+ * open/closed; the controller is the source of truth for runtime
+ * side-effects (focus override, scroll lock).
+ */
+export function mountDialog(
+    el: HTMLDialogElement,
+    config: DialogConfig = {},
+): DialogControl {
+    const onClose = config.onClose;
+    const persistent = config.persistent ?? false;
+
+    // Optional role override — AlertDialog uses `'alertdialog'`. The
+    // browser's default for `<dialog>` is already `'dialog'`, so we only
+    // setAttribute when the caller asks for something different.
+    if (config.role && config.role !== 'dialog') {
+        el.setAttribute('role', config.role);
+    }
+
+    // Initial state.
+    el.setAttribute('data-state', 'closed');
+
+    // Per-open transient state.
+    let triggerEl: HTMLElement | null = null;
+    let unlockScrollFn: (() => void) | null = null;
+
+    // The native `cancel` event fires on Escape press. Browser default:
+    // closes the dialog. For persistent dialogs, suppress the close.
+    function handleCancel(event: Event): void {
+        if (persistent) {
+            event.preventDefault();
+            return;
+        }
+        onClose?.();
+    }
+
+    // Backdrop click — `<dialog>` IS the backdrop element. Clicks on its
+    // children bubble through with `event.target` set to the inner content,
+    // so a target equal to `el` means the click landed on the backdrop.
+    function handleBackdropClick(event: MouseEvent): void {
+        if (persistent) return;
+        if (event.target !== el) return;
+        onClose?.();
+    }
+
+    el.addEventListener('cancel', handleCancel);
+    el.addEventListener('click', handleBackdropClick);
+
+    function resolveInitialFocus(): HTMLElement | null {
+        // Consumer override always wins.
+        const override = el.querySelector<HTMLElement>(
+            '[data-dialog-initial-focus]',
+        );
+        if (override) return override;
+
+        const target = config.initialFocus ?? 'first';
+        if (target === null) return null;
+        if (target instanceof HTMLElement) return target;
+        if (target === 'cancel') {
+            return el.querySelector<HTMLElement>('[data-dialog-cancel]');
+        }
+        // 'first' — defer to the native showModal() auto-focus, no override.
+        return null;
+    }
+
+    function open(): void {
+        if (el.open) return; // idempotent
+
+        // Capture the element that had focus before the dialog opened so
+        // we can restore it on close if the browser fails to do so.
+        const active = document.activeElement;
+        triggerEl =
+            active instanceof HTMLElement && active !== document.body
+                ? active
+                : null;
+
+        el.showModal(); // native top-layer + focus trap
+        el.setAttribute('data-state', 'open');
+        unlockScrollFn = lockScroll();
+
+        // Apply initialFocus override after a frame so the dialog has
+        // settled into place. The browser auto-focuses the first focusable
+        // child by default — only override when the consumer asked for it.
+        requestAnimationFrame(() => {
+            if (!el.open) return; // guard against rapid open→close
+            const target = resolveInitialFocus();
+            if (target) target.focus();
+        });
+    }
+
+    function close(): void {
+        if (!el.open) return; // idempotent
+
+        el.close(); // native focus restoration to the trigger
+        el.setAttribute('data-state', 'closed');
+        unlockScrollFn?.();
+        unlockScrollFn = null;
+
+        // Backup: if the browser failed to restore focus (e.g. the trigger
+        // was removed from the DOM during the open, or the page lost focus),
+        // restore manually. We check for activeElement === body which is
+        // the browser's "no specific element focused" state.
+        const trigger = triggerEl;
+        triggerEl = null;
+        if (
+            trigger &&
+            document.contains(trigger) &&
+            document.activeElement === document.body
+        ) {
+            trigger.focus();
+        }
+    }
+
+    function isOpen(): boolean {
+        return el.open;
+    }
+
+    function teardown(): void {
+        if (el.open) close();
+        el.removeEventListener('cancel', handleCancel);
+        el.removeEventListener('click', handleBackdropClick);
+    }
+
+    return { open, close, isOpen, teardown };
+}