@pienter/ui 0.5.0 → 0.8.0

package/components/navigation/tabs/Tabs.vue

@@ -2,10 +2,12 @@
     <div class="pui-tabs" role="tablist">
         <button
             v-for="tab in tabs"
+            :id="tab.id"
             :key="tab.key"
             type="button"
             class="pui-tabs__item"
             role="tab"
+            :aria-controls="tab.controls"
             :aria-selected="modelValue === tab.key ? 'true' : 'false'"
             :tabindex="modelValue === tab.key ? 0 : -1"
             :disabled="tab.disabled || undefined"
@@ -22,6 +24,8 @@ interface TabItem {
     key: string;
     label: string;
     disabled?: boolean;
+    id?: string;
+    controls?: string;
 }
 
 const props = withDefaults(
@@ -39,6 +43,8 @@ const emit = defineEmits<{
 }>();
 
 function handleKeydown(event: KeyboardEvent): void {
+    if (!['ArrowRight', 'ArrowLeft', 'Home', 'End'].includes(event.key)) return;
+
     const target = event.currentTarget as HTMLElement;
     const items = Array.from(
         target.parentElement!.querySelectorAll<HTMLElement>(

package/components/navigation/tabs/tabs.css

@@ -2,7 +2,7 @@
     .pui-tabs {
         display: flex;
         gap: var(--space-s);
-        border-block-end: var(--stroke-sm) solid var(--border-clr-base);
+        border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
     }
     .pui-tabs__item {
         appearance: none;
@@ -14,9 +14,9 @@
         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;
+        border-block-end: var(--stroke-lg) solid transparent;
+        margin-block-end: calc(-1 * var(--stroke-sm));
+        transition: color var(--duration-fast) var(--ease-base);
     }
     .pui-tabs__item[aria-selected='true'] {
         color: var(--text-clr-base);
@@ -26,11 +26,11 @@
         color: var(--text-clr-base);
     }
     .pui-tabs__item:focus-visible {
-        outline: 3px solid var(--outline-clr-base);
-        outline-offset: 2px;
+        outline: var(--outline-width) solid var(--outline-clr-base);
+        outline-offset: var(--outline-offset);
     }
     .pui-tabs__item:disabled {
-        opacity: 0.4;
+        opacity: var(--opacity-disabled);
         cursor: not-allowed;
     }
     .pui-tabs__item:disabled:hover {

package/composables/useMenu.ts

@@ -85,31 +85,30 @@ export function useMenu(
         return getItems().filter((it) => !isDisabled(it));
     }
 
-    // Initial roving tabindex — every item starts at `-1`. The first
-    // enabled item is promoted to `0` so a Tab into the menu (rare —
-    // the trigger usually opens with explicit focus) lands somewhere.
+    function setRovingTabindex(
+        activeItem: HTMLElement | undefined,
+        items = getItems(),
+    ): void {
+        for (const item of items) {
+            item.setAttribute('tabindex', item === activeItem ? '0' : '-1');
+        }
+    }
+
     function initRovingTabindex(): void {
         const items = getItems();
-        items.forEach((item, idx) => {
-            if (isDisabled(item)) {
-                item.setAttribute('tabindex', '-1');
-                return;
-            }
-            const firstEnabledIdx = items.findIndex((i) => !isDisabled(i));
-            item.setAttribute('tabindex', idx === firstEnabledIdx ? '0' : '-1');
-        });
+        setRovingTabindex(
+            items.find((item) => !isDisabled(item)),
+            items,
+        );
     }
 
     function focusItem(item: HTMLElement): void {
-        // Promote the focus target to `tabindex="0"` and demote the
-        // rest to `-1` BEFORE focusing — focus on a `tabindex="-1"`
-        // element works fine, but the rove must reflect the new state
-        // so a subsequent Tab leaves the menu cleanly.
-        const items = getItems();
-        items.forEach((it) => {
-            it.setAttribute('tabindex', it === item ? '0' : '-1');
-        });
-        item.focus();
+        // Focusing the current item does not fire focusin.
+        if (document.activeElement === item) setRovingTabindex(item);
+        else {
+            item.setAttribute('tabindex', '0');
+            item.focus();
+        }
     }
 
     function moveFocus(direction: 1 | -1): void {
@@ -191,13 +190,7 @@ export function useMenu(
         if (!menuEl || !target) return;
         const item = target.closest<HTMLElement>(itemSelector);
         if (!item || !menuEl.contains(item) || isDisabled(item)) return;
-        // Re-rove so only the freshly-focused item carries
-        // `tabindex="0"`. This catches focus that didn't go through
-        // `focusItem` (e.g., a click that focused an item directly).
-        const items = getItems();
-        items.forEach((it) => {
-            it.setAttribute('tabindex', it === item ? '0' : '-1');
-        });
+        setRovingTabindex(item);
     }
 
     onMounted(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pienter/ui",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Shared Pienter UI components, styles, icons, and browser utilities.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,8 @@
     "./components/Skeleton.vue": "./components/feedback/skeleton/Skeleton.vue",
     "./components/Spinner.vue": "./components/feedback/spinner/Spinner.vue",
     "./components/Toast.vue": "./components/feedback/toast/Toast.vue",
+    "./components/ToastHost.vue": "./components/feedback/toast/ToastHost.vue",
+    "./components/Toast.types": "./components/feedback/toast/types.ts",
     "./components/Checkbox.vue": "./components/form/checkbox/Checkbox.vue",
     "./components/Combobox.vue": "./components/form/combobox/Combobox.vue",
     "./components/DateInput.vue": "./components/form/date-input/DateInput.vue",
@@ -60,6 +62,7 @@
     "./components/Accordion.vue": "./components/layout/accordion/Accordion.vue",
     "./components/Card.vue": "./components/layout/card/Card.vue",
     "./components/Collapsible.vue": "./components/layout/collapsible/Collapsible.vue",
+    "./components/AppLayout.vue": "./components/layout/app-layout/AppLayout.vue",
     "./components/Separator.vue": "./components/layout/separator/Separator.vue",
     "./components/Table.vue": "./components/layout/table/Table.vue",
     "./components/TableRow.vue": "./components/layout/table/TableRow.vue",
@@ -87,7 +90,19 @@
     "./icons": "./icons/index.ts",
     "./icons/*": "./icons/*",
     "./utils": "./utils/index.ts",
-    "./utils/*": "./utils/*"
+    "./utils/*": "./utils/*",
+    "./toast": "./components/feedback/toast/toast.ts",
+    "./utils/a11y": "./utils/a11y/index.ts",
+    "./components/Index.vue": "./components/layout/index/Index.vue",
+    "./components/RecordForm.vue": "./components/form/record-form/RecordForm.vue",
+    "./components/RecordForm.types": "./components/form/record-form/types.ts",
+    "./components/RecordDetails.vue": "./components/display/record-details/RecordDetails.vue",
+    "./components/RecordDetails.types": "./components/display/record-details/types.ts",
+    "./utils/cms": "./utils/cms/index.ts",
+    "./utils/cms/schema.json": "./utils/cms/schema.json",
+    "./components/RecordFields.vue": "./components/form/record-form/RecordFields.vue",
+    "./components/BlockEditor.vue": "./components/form/block-editor/BlockEditor.vue",
+    "./components/BlockEditor.types": "./components/form/block-editor/types.ts"
   },
   "files": [
     "styles",

package/styles/0-settings/colors.css

@@ -195,6 +195,11 @@
     /* ---- Background -------------------------------------------------- */
     --bg-clr-base: var(--clr-mantle);
     --bg-clr-surface: var(--clr-base);
+    --bg-clr-canvas: color-mix(
+        in oklab,
+        var(--bg-clr-base),
+        var(--bg-clr-surface) 65%
+    );
     --bg-clr-surface-2: var(--clr-surface-0);
     --bg-clr-accent: var(--clr-surface-0);
     /* The neutral "selected" rung — one step past the hover fill, so a chosen
@@ -236,6 +241,11 @@
 
     /* ---- Border ------------------------------------------------------ */
     --border-clr-base: var(--clr-surface-1);
+    --border-clr-subtle: color-mix(
+        in oklab,
+        var(--border-clr-base) 40%,
+        var(--bg-clr-surface)
+    );
     --border-clr-strong: var(--clr-text);
     --border-clr-input: var(--clr-overlay);
     --border-clr-brand: var(--clr-blue-fg);

package/styles/4-components/form-field.css

@@ -0,0 +1,112 @@
+@layer components {
+    /* The form-primitive scaffold shared by every form control: the
+     * `.pui-field` wrapper, its label / hint / required marker, and the
+     * `.pui-input` / `.pui-textarea` control surface. Loaded with the
+     * styles entry so it does not depend on which component is on the page. */
+
+    .pui-field {
+        display: grid;
+        align-content: start;
+        gap: var(--space-2xs);
+    }
+
+    /* Zero the UA fieldset chrome (groove border, padding, and the
+     * `min-inline-size: min-content` that stops it shrinking) so a
+     * grouped control can host the grid scaffold. */
+    .pui-field:where(fieldset) {
+        border: 0;
+        padding: 0;
+        margin: 0;
+        min-inline-size: 0;
+    }
+
+    /* A legend floats and pads itself inside a grid fieldset; reset it to
+     * an ordinary grid item so the row gap governs label spacing. */
+    .pui-field__label:where(legend) {
+        padding: 0;
+        float: none;
+    }
+
+    /* `data-layout="inline"`: control first in DOM order, label beside it,
+     * hint and errors below spanning both columns. */
+    .pui-field[data-layout='inline'] {
+        grid-template-columns: max-content 1fr;
+        column-gap: var(--space-xs);
+        align-items: center;
+    }
+
+    .pui-field[data-layout='inline'] .pui-field__label {
+        cursor: pointer;
+        user-select: none;
+    }
+
+    .pui-field[data-layout='inline'] .pui-field__hint {
+        grid-column: 1 / -1;
+    }
+
+    .pui-field__label {
+        margin-block: 0;
+        font-size: var(--step--1);
+        font-weight: var(--fw-bold);
+    }
+
+    .pui-field__required {
+        margin-inline-start: var(--space-3xs);
+        color: var(--text-clr-danger);
+    }
+
+    .pui-field__hint {
+        font-size: var(--step--2);
+        color: var(--text-clr-muted);
+        margin: 0;
+    }
+
+    .pui-field[data-status='error'] .pui-field__hint {
+        color: var(--text-clr-danger);
+    }
+
+    .pui-field[data-status='success'] .pui-field__hint {
+        color: var(--text-clr-success);
+    }
+
+    .pui-input,
+    .pui-textarea {
+        width: 100%;
+        padding: 0.65em 0.85em;
+        font: inherit;
+        background: var(--bg-clr-surface);
+        border: var(--stroke-sm) solid var(--border-clr-input);
+        border-radius: var(--radius-sm);
+        color: var(--text-clr-base);
+        transition: border-color var(--duration-fast) var(--ease-base);
+    }
+
+    .pui-textarea {
+        min-height: 6rem;
+        resize: vertical;
+    }
+
+    .pui-input:focus-visible,
+    .pui-textarea:focus-visible {
+        border-color: var(--border-clr-brand);
+        outline: var(--outline-width) solid var(--outline-clr-base);
+        outline-offset: var(--outline-offset);
+    }
+
+    .pui-input:disabled,
+    .pui-textarea:disabled {
+        background: var(--bg-clr-surface-2);
+        color: var(--text-clr-muted);
+        cursor: not-allowed;
+    }
+
+    .pui-field[data-status='error'] .pui-input,
+    .pui-field[data-status='error'] .pui-textarea {
+        border-color: var(--border-clr-danger);
+    }
+
+    .pui-field[data-status='success'] .pui-input,
+    .pui-field[data-status='success'] .pui-textarea {
+        border-color: var(--border-clr-success);
+    }
+}

package/styles/4-components/index.css

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

package/styles/main.css

@@ -5,4 +5,5 @@
 @import url('./1-reset/index.css');
 @import url('./2-base/index.css');
 @import url('./3-layout/index.css');
+@import url('./4-components/index.css');
 @import url('./5-utilities/index.css');

package/utils/a11y/focus.ts

@@ -45,8 +45,12 @@ export function createFocusTrap(container: HTMLElement): FocusTrap {
 }
 
 export function focusFirstInvalid(formEl: HTMLElement): boolean {
-    const firstInvalid = formEl.querySelector<HTMLElement>(
-        '[aria-invalid="true"]',
+    const firstInvalid = Array.from(
+        formEl.querySelectorAll<HTMLElement>('[aria-invalid="true"]'),
+    ).find(
+        (element) =>
+            !element.matches(':disabled') &&
+            element.checkVisibility({ visibilityProperty: true }),
     );
     if (!firstInvalid) return false;
 
@@ -56,7 +60,9 @@ export function focusFirstInvalid(formEl: HTMLElement): boolean {
     // primitives (fieldsets of date pickers, checkbox groups, etc.) inherit
     // this behaviour without re-derivation.
     if (firstInvalid instanceof HTMLFieldSetElement) {
-        const firstFocusable = getFocusableElements(firstInvalid)[0];
+        const firstFocusable = getFocusableElements(firstInvalid).find(
+            (element) => element.checkVisibility({ visibilityProperty: true }),
+        );
         if (firstFocusable) {
             firstFocusable.focus();
             return true;

package/utils/a11y/index.ts

@@ -6,4 +6,8 @@ export {
     type FocusTrap,
 } from './focus.js';
 export { onKeyboardNav, type KeyboardNavHandlers } from './keyboard.js';
-export { announce, type LiveRegionPriority } from './live-region.js';
+export {
+    announce,
+    ensureLiveRegion,
+    type LiveRegionPriority,
+} from './live-region.js';

package/utils/a11y/live-region.ts

@@ -2,7 +2,8 @@ export type LiveRegionPriority = 'polite' | 'assertive';
 
 const REGION_ID = 'pienter-ui-live-region';
 
-function ensureLiveRegion(): HTMLElement {
+/** Creates the shared live region if missing; call on mount so the first `announce()` is not dropped. */
+export function ensureLiveRegion(): HTMLElement {
     let region = document.getElementById(REGION_ID);
     if (!region) {
         region = document.createElement('div');

package/utils/cms/index.ts

@@ -0,0 +1,283 @@
+import { formatSort, parseSort, type SortState } from '../sort/index.js';
+
+export type JsonValue =
+    string | number | boolean | null | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type ValuePath = readonly (string | number)[];
+export interface ValidationIssue {
+    path: ValuePath;
+    messages: string[];
+}
+export interface ApiError {
+    code: string;
+    message: string;
+    issues?: ValidationIssue[];
+}
+export interface ErrorResponse {
+    error: ApiError;
+}
+export interface ItemResponse<T> {
+    data: T;
+}
+export interface ListResponse<T> {
+    data: T[];
+    meta: { page: number; page_size: number; total: number };
+}
+export type ListLoader<T> = (
+    query: ListQuery,
+    context: { signal: AbortSignal },
+) => Promise<ListResponse<T>>;
+export interface ListQuery {
+    page: number;
+    page_size: number;
+    search: string;
+    sort: SortState;
+    filters: Record<string, string>;
+}
+export interface QueryOptions {
+    sorts: readonly string[];
+    filters: readonly string[];
+    defaultPageSize?: number;
+    maxPageSize?: number;
+}
+
+export class QueryError extends Error {
+    readonly code = 'invalid_query';
+    constructor(message: string) {
+        super(message);
+        this.name = 'QueryError';
+    }
+}
+
+function pageSizes(options: QueryOptions) {
+    const max = options.maxPageSize ?? 100;
+    const size = options.defaultPageSize ?? 20;
+    if (
+        !Number.isInteger(max) ||
+        max < 1 ||
+        max > 100 ||
+        !Number.isInteger(size) ||
+        size < 1 ||
+        size > max
+    ) {
+        throw new QueryError(
+            'Page size defaults must fit the supported range 1–100.',
+        );
+    }
+    return { max, size };
+}
+
+function integer(
+    value: number,
+    name: string,
+    max = Number.MAX_SAFE_INTEGER,
+): number {
+    if (!Number.isSafeInteger(value) || value < 1 || value > max) {
+        throw new QueryError(
+            `${name} must be an integer between 1 and ${max}.`,
+        );
+    }
+    return value;
+}
+
+function filterName(name: string): boolean {
+    return (
+        /^[a-zA-Z0-9_]+$/.test(name) &&
+        !['__proto__', 'prototype', 'constructor'].includes(name)
+    );
+}
+
+export function normalizeListQuery(
+    query: ListQuery,
+    options: QueryOptions,
+): ListQuery {
+    const { max } = pageSizes(options);
+    const page = integer(query.page, 'page');
+    const page_size = integer(query.page_size, 'page_size', max);
+    if (typeof query.search !== 'string')
+        throw new QueryError('Expected a search string.');
+    const sort = query.sort;
+    if (
+        sort !== null &&
+        (typeof sort !== 'object' ||
+            typeof sort.key !== 'string' ||
+            !sort.key ||
+            sort.key.startsWith('-') ||
+            !['asc', 'desc'].includes(sort.direction))
+    )
+        throw new QueryError(
+            'Expected a sort field and asc or desc direction.',
+        );
+    if (sort && !options.sorts.includes(sort.key))
+        throw new QueryError('Unsupported sort field.');
+    if (
+        !query.filters ||
+        typeof query.filters !== 'object' ||
+        Array.isArray(query.filters)
+    )
+        throw new QueryError('Expected a filter map.');
+    const filters: Record<string, string> = {};
+    for (const key of Object.keys(query.filters).sort()) {
+        if (!filterName(key) || !options.filters.includes(key))
+            throw new QueryError(
+                `Unsupported filter parameter: filter[${key}].`,
+            );
+        const value = query.filters[key];
+        if (typeof value !== 'string')
+            throw new QueryError(`Expected a string filter value: ${key}.`);
+        filters[key] = value;
+    }
+    return {
+        page,
+        page_size,
+        search: query.search,
+        sort: sort ? { key: sort.key, direction: sort.direction } : null,
+        filters,
+    };
+}
+
+export function decodeListQuery(
+    params: URLSearchParams,
+    options: QueryOptions,
+): ListQuery {
+    const { max, size } = pageSizes(options);
+    for (const key of ['page', 'page_size', 'search', 'sort']) {
+        if (params.getAll(key).length > 1)
+            throw new QueryError(`Duplicate ${key} parameter.`);
+    }
+    const rawSort = params.get('sort') ?? '';
+    const sort = rawSort ? parseSort(rawSort) : null;
+    if (rawSort && (!sort || sort.key.startsWith('-')))
+        throw new QueryError('Unsupported sort field.');
+    const filters: Record<string, string> = {};
+    for (const [key, value] of params) {
+        if (
+            ['page', 'page_size', 'search', 'sort'].some((name) =>
+                key.startsWith(`${name}[`),
+            )
+        )
+            throw new QueryError(`Expected a scalar parameter: ${key}.`);
+        if (key !== 'filter' && !key.startsWith('filter[')) continue;
+        const match = /^filter\[([a-zA-Z0-9_]+)\]$/.exec(key);
+        const name = match?.[1];
+        if (!name || !filterName(name))
+            throw new QueryError(`Unsupported filter parameter: ${key}.`);
+        if (params.getAll(key).length !== 1)
+            throw new QueryError(`Duplicate filter: ${name}.`);
+        filters[name] = value;
+    }
+    function number(name: string, fallback: number, max: number): number {
+        const value = params.get(name);
+        if (value === null) return fallback;
+        if (!/^[1-9]\d*$/.test(value))
+            throw new QueryError(
+                `${name} must be an integer between 1 and ${max}.`,
+            );
+        return Number(value);
+    }
+    return normalizeListQuery(
+        {
+            page: number('page', 1, Number.MAX_SAFE_INTEGER),
+            page_size: number('page_size', size, max),
+            search: params.get('search') ?? '',
+            sort,
+            filters,
+        },
+        options,
+    );
+}
+
+export function encodeListQuery(query: ListQuery): URLSearchParams {
+    const normalized = normalizeListQuery(query, {
+        sorts: query.sort ? [query.sort.key] : [],
+        filters: query.filters ? Object.keys(query.filters) : [],
+    });
+    const params = new URLSearchParams({
+        page: String(normalized.page),
+        page_size: String(normalized.page_size),
+    });
+    if (normalized.search) params.set('search', normalized.search);
+    if (normalized.sort) params.set('sort', formatSort(normalized.sort)!);
+    for (const [key, value] of Object.entries(normalized.filters))
+        params.set(`filter[${key}]`, value);
+    return params;
+}
+
+export function cloneRecord<T>(record: T): T {
+    return JSON.parse(JSON.stringify(record)) as T;
+}
+
+export function readPath(record: unknown, path: ValuePath): unknown {
+    let value = record;
+    for (const key of path) {
+        if (
+            value === null ||
+            typeof value !== 'object' ||
+            ['__proto__', 'prototype', 'constructor'].includes(String(key))
+        )
+            return undefined;
+        if (
+            Array.isArray(value) !== (typeof key === 'number') ||
+            !Object.hasOwn(value, key)
+        )
+            return undefined;
+        value = (value as Record<string | number, unknown>)[key];
+    }
+    return value;
+}
+
+export function updatePath<T extends object>(
+    record: T,
+    path: ValuePath,
+    value: unknown,
+): T {
+    if (
+        !path.length ||
+        typeof path[0] !== 'string' ||
+        path.some((key) =>
+            typeof key === 'number'
+                ? !Number.isInteger(key) || key < 0 || key > 4294967294
+                : !key ||
+                  ['__proto__', 'prototype', 'constructor'].includes(key),
+        )
+    ) {
+        throw new TypeError(
+            'Expected a non-empty path of safe object keys and array indices.',
+        );
+    }
+    const copy = cloneRecord(record);
+    let target = copy as Record<string | number, unknown>;
+    for (let i = 0; i < path.length; i++) {
+        const key = path[i]!;
+        if (Array.isArray(target) !== (typeof key === 'number'))
+            throw new TypeError(
+                'Path does not match its object or array container.',
+            );
+        if (Array.isArray(target) && Number(key) > target.length)
+            throw new TypeError('Array paths cannot create sparse records.');
+        if (i === path.length - 1) {
+            target[key] = value === undefined ? undefined : cloneRecord(value);
+            break;
+        }
+        const next = target[key];
+        if (next === null || typeof next !== 'object')
+            target[key] = typeof path[i + 1] === 'number' ? [] : {};
+        target = target[key] as Record<string | number, unknown>;
+    }
+    return copy;
+}
+
+export function errorsFor(
+    issues: readonly ValidationIssue[],
+    path: ValuePath,
+): string[] {
+    return issues
+        .filter(
+            (issue) =>
+                issue.path.length === path.length &&
+                issue.path.every((part, index) => part === path[index]),
+        )
+        .flatMap((issue) => issue.messages);
+}