@pienter/ui 0.7.1 → 0.9.0

package/components/layout/index/useIndex.ts

@@ -20,7 +20,8 @@ import {
 interface Options<T> {
     load: ListLoader<T>;
     queryOptions: QueryOptions;
-    syncQuery: boolean;
+    /** `true` syncs the bare keys; a string syncs `<prefix>.<key>` instead. */
+    syncQuery: boolean | string;
     searchDebounce: number;
 }
 
@@ -34,14 +35,21 @@ function isListParameter(key: string): boolean {
     );
 }
 
-function routeParams(values: LocationQuery): URLSearchParams {
+function listKey(key: string, prefix: string): string | undefined {
+    if (!key.startsWith(prefix)) return undefined;
+    const bare = key.slice(prefix.length);
+    return isListParameter(bare) ? bare : undefined;
+}
+
+function routeParams(values: LocationQuery, prefix: string): URLSearchParams {
     const params = new URLSearchParams();
     for (const [key, valuesForKey] of Object.entries(values)) {
-        if (!isListParameter(key)) continue;
+        const bare = listKey(key, prefix);
+        if (bare === undefined) continue;
         for (const value of Array.isArray(valuesForKey)
             ? valuesForKey
             : [valuesForKey])
-            params.append(key, value ?? '');
+            params.append(bare, value ?? '');
     }
     params.sort();
     return params;
@@ -78,6 +86,11 @@ interface Work {
 export function useIndex<T>(props: Options<T>) {
     const route = inject(routeLocationKey, undefined);
     const router = inject(routerKey, undefined);
+    const syncing = () => props.syncQuery !== false;
+    const prefix = () =>
+        typeof props.syncQuery === 'string' && props.syncQuery
+            ? `${props.syncQuery}.`
+            : '';
     const defaults = () =>
         normalizeListQuery(
             {
@@ -173,12 +186,12 @@ export function useIndex<T>(props: Options<T>) {
     }
 
     const urlQuery = computed(() =>
-        props.syncQuery && route ? routeParams(route.query).toString() : '',
+        syncing() && route ? routeParams(route.query, prefix()).toString() : '',
     );
     watch(
         [
             urlQuery,
-            () => (props.syncQuery ? route?.path : ''),
+            () => (syncing() ? route?.path : ''),
             () => props.syncQuery,
             () => props.queryOptions,
             () => props.load,
@@ -197,12 +210,12 @@ export function useIndex<T>(props: Options<T>) {
             navigation++;
             if (!preserveSearch) cancelSearch();
             cancelRequest();
-            if (props.syncQuery && (!route || !router))
+            if (syncing() && (!route || !router))
                 throw new Error(
                     'Index sync-query requires an installed Vue Router.',
                 );
             try {
-                const next = props.syncQuery
+                const next = syncing()
                     ? decodeListQuery(
                           new URLSearchParams(urlQuery.value),
                           props.queryOptions,
@@ -233,18 +246,22 @@ export function useIndex<T>(props: Options<T>) {
             work.finish();
             return work.promise;
         }
-        if (!props.syncQuery || !route || !router)
-            return accept(normalized, work);
+        if (!syncing() || !route || !router) return accept(normalized, work);
+        const keyPrefix = prefix();
         const values = { ...route.query };
         for (const key of Object.keys(values))
-            if (isListParameter(key)) delete values[key];
+            if (listKey(key, keyPrefix) !== undefined) delete values[key];
         for (const [key, value] of encodeListQuery(normalized))
-            values[key] = value;
+            values[keyPrefix + key] = value;
         query.value = normalized;
         search.value = normalized.search;
         const attempt = ++navigation;
         const path = route.path;
-        pendingUrl = { path, query: routeParams(values).toString(), work };
+        pendingUrl = {
+            path,
+            query: routeParams(values, keyPrefix).toString(),
+            work,
+        };
         loading.value = true;
         void (async () => {
             try {
@@ -285,7 +302,7 @@ export function useIndex<T>(props: Options<T>) {
         cancelRequest();
         try {
             query.value = decodeListQuery(
-                routeParams(route!.query),
+                routeParams(route!.query, prefix()),
                 props.queryOptions,
             );
             if (!preserveSearch) search.value = query.value.search;

package/components/layout/table/DataTable.vue

@@ -10,6 +10,8 @@
         :selectable="selectable"
         :clickable="clickable"
         :all-selected="allSelected"
+        :label="label"
+        :labelledby="labelledby"
         @toggle-all="toggleAll"
         @sort="(key) => emit('sort', key)"
     >
@@ -26,7 +28,7 @@
                     class="pui-table__check"
                     type="checkbox"
                     :checked="isSelected(keyOf(row))"
-                    aria-label="Select row"
+                    :aria-label="rowLabel(row)"
                     @click.stop
                     @change="toggle(keyOf(row))"
                 />
@@ -78,6 +80,10 @@ const props = withDefaults(
         sort?: SortState;
         /** Frosts and disables the body while the rows are stale, and suppresses the empty state. */
         loading?: boolean;
+        /** Accessible name, rendered as a visually hidden `<caption>`. */
+        label?: string;
+        /** `id` of a visible heading that names the table; wins over `label`. */
+        labelledby?: string;
     }>(),
     {
         rowKey: 'id',
@@ -86,6 +92,8 @@ const props = withDefaults(
         clickable: false,
         sort: null,
         loading: false,
+        label: undefined,
+        labelledby: undefined,
     },
 );
 
@@ -103,6 +111,11 @@ function cellValue(row: T, key: string): unknown {
 function keyOf(row: T): string | number {
     return cellValue(row, props.rowKey) as string | number;
 }
+function rowLabel(row: T): string {
+    const first = props.columns[0];
+    const value = first ? String(cellValue(row, first.key) ?? '').trim() : '';
+    return value ? `Select ${value}` : 'Select row';
+}
 function isSelected(key: string | number): boolean {
     return props.selected.includes(key);
 }

package/components/layout/table/Table.vue

@@ -8,7 +8,13 @@
             class="pui-table"
             :style="{ '--pui-table-cols': cols }"
             :aria-busy="loading || undefined"
+            :aria-labelledby="labelledby"
         >
+            <caption v-if="label" class="u-visually-hidden">
+                {{
+                    label
+                }}
+            </caption>
             <thead class="pui-table__head">
                 <tr class="pui-table__row" data-head>
                     <th
@@ -104,6 +110,10 @@ const props = withDefaults(
         sort?: SortState;
         /** Frosts and disables the body while the rows are stale, leaving the header usable. */
         loading?: boolean;
+        /** Accessible name, rendered as a visually hidden `<caption>`. */
+        label?: string;
+        /** `id` of a visible heading that names the table; wins over `label`. */
+        labelledby?: string;
     }>(),
     {
         selectable: false,
@@ -111,6 +121,8 @@ const props = withDefaults(
         allSelected: false,
         sort: null,
         loading: false,
+        label: undefined,
+        labelledby: undefined,
     },
 );
 

package/components/navigation/breadcrumb/breadcrumb.css

@@ -3,7 +3,7 @@
         display: flex;
         align-items: center;
         justify-content: space-between;
-        gap: var(--space-sm);
+        gap: var(--space-s);
     }
 
     .pui-breadcrumb__trail {
@@ -41,6 +41,11 @@
         color: var(--text-clr-base);
     }
 
+    .pui-breadcrumb__link:focus-visible {
+        outline: var(--outline-width) solid var(--outline-clr-base);
+        outline-offset: var(--outline-offset);
+    }
+
     .pui-breadcrumb__sep {
         color: var(--border-clr-base);
     }

package/components/navigation/sidebar/sidebar.css

@@ -290,7 +290,9 @@
         flex-direction: column;
         justify-content: center;
         gap: var(--space-3xs);
-        padding-inline: var(--space-3xs);
+        /* The panel's own inline padding already holds the focus ring; any
+           more and a nine-character caption ("Companies") breaks mid-word. */
+        padding-inline: 0;
         text-align: center;
     }
 
@@ -425,21 +427,6 @@
         padding-inline-start: var(--space-2xs);
     }
 
-    /* It travels, so it needs its own reduced-motion escape. */
-    @media (prefers-reduced-motion: reduce) {
-        .pui-sidebar[data-state='collapsed']
-            .pui-sidebar__group[data-submenu-state]
-            > .pui-sidebar__group-items {
-            transition: none;
-        }
-
-        .pui-sidebar[data-state='collapsed']
-            .pui-sidebar__group[data-submenu-state='closed']
-            > .pui-sidebar__group-items {
-            transform: none;
-        }
-    }
-
     /* Mobile drawer mode — below the breakpoint, the column transforms into a fixed-overlay drawer */
     @media (max-width: 767px) {
         .pui-sidebar,
@@ -568,4 +555,24 @@
             background: transparent;
         }
     }
+
+    /* Everything that travels or fades. After the drawer block: a media query
+       grants no extra specificity, so order decides. */
+    @media (prefers-reduced-motion: reduce) {
+        .pui-sidebar,
+        .pui-sidebar__panel,
+        .pui-sidebar__backdrop,
+        .pui-sidebar__group-caret,
+        .pui-sidebar[data-state='collapsed']
+            .pui-sidebar__group[data-submenu-state]
+            > .pui-sidebar__group-items {
+            transition: none;
+        }
+
+        .pui-sidebar[data-state='collapsed']
+            .pui-sidebar__group[data-submenu-state='closed']
+            > .pui-sidebar__group-items {
+            transform: none;
+        }
+    }
 }

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/useUrlTab.ts

@@ -0,0 +1,38 @@
+import { computed, type WritableComputedRef } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+
+/**
+ * Keeps the active `Tabs` key in the URL query, the single source of truth, so a shared
+ * link or a reload opens the same tab. Bind with `v-model`. The default key drops the
+ * parameter and an unknown value falls back to it; writes go through `router.replace`,
+ * so tab switches stay out of the back stack and other query parameters survive.
+ * Requires the optional `vue-router` peer dependency.
+ *
+ * @param keys - the tab keys the view renders.
+ * @param defaultKey - key used when the parameter is absent or unknown.
+ * @param param - query parameter name; defaults to `'tab'`.
+ */
+export function useUrlTab(
+    keys: readonly string[],
+    defaultKey: string,
+    param = 'tab',
+): WritableComputedRef<string> {
+    const route = useRoute();
+    const router = useRouter();
+
+    return computed<string>({
+        get: () => {
+            const raw = route.query[param];
+            const value = Array.isArray(raw) ? raw[0] : raw;
+            return typeof value === 'string' && keys.includes(value)
+                ? value
+                : defaultKey;
+        },
+        set: (key) => {
+            const query = { ...route.query };
+            if (key === defaultKey) delete query[param];
+            else query[param] = key;
+            void router.replace({ query });
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pienter/ui",
-  "version": "0.7.1",
+  "version": "0.9.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",
@@ -84,10 +87,13 @@
     "./composables/useMenu": "./composables/useMenu.ts",
     "./composables/usePopover": "./composables/usePopover.ts",
     "./composables/useUrlSort": "./composables/useUrlSort.ts",
+    "./composables/useUrlTab": "./composables/useUrlTab.ts",
     "./icons": "./icons/index.ts",
     "./icons/*": "./icons/*",
     "./utils": "./utils/index.ts",
     "./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",

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/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

@@ -281,3 +281,24 @@ export function errorsFor(
         )
         .flatMap((issue) => issue.messages);
 }
+
+export interface FormFailure {
+    issues: ValidationIssue[];
+    errors: string[];
+}
+
+/**
+ * Turns a failed save into RecordForm's `issues` and `errors` props. A caught value
+ * carrying the `ErrorResponse` envelope (`{ error: ApiError }`) contributes its field
+ * issues; without issues, `errors` holds the caught `Error` message, falling back to
+ * `fallback`.
+ */
+export function formFailure(cause: unknown, fallback: string): FormFailure {
+    const error = (cause as Partial<ErrorResponse> | null | undefined)?.error;
+    const issues = Array.isArray(error?.issues) ? error.issues : [];
+    if (issues.length) return { issues, errors: [] };
+    return {
+        issues: [],
+        errors: [cause instanceof Error ? cause.message : fallback],
+    };
+}