@pienter/ui 0.5.0 → 0.8.0

package/components/layout/index/useIndex.ts

@@ -0,0 +1,407 @@
+import { computed, inject, onScopeDispose, ref, shallowRef, watch } from 'vue';
+import {
+    routeLocationKey,
+    routerKey,
+    isNavigationFailure,
+    NavigationFailureType,
+    type LocationQuery,
+} from 'vue-router';
+import {
+    cloneRecord,
+    decodeListQuery,
+    encodeListQuery,
+    normalizeListQuery,
+    type ApiError,
+    type ListLoader,
+    type ListQuery,
+    type QueryOptions,
+} from '../../../utils/cms/index.js';
+
+interface Options<T> {
+    load: ListLoader<T>;
+    queryOptions: QueryOptions;
+    /** `true` syncs the bare keys; a string syncs `<prefix>.<key>` instead. */
+    syncQuery: boolean | string;
+    searchDebounce: number;
+}
+
+function isListParameter(key: string): boolean {
+    return (
+        key === 'filter' ||
+        key.startsWith('filter[') ||
+        ['page', 'page_size', 'search', 'sort'].some(
+            (name) => key === name || key.startsWith(`${name}[`),
+        )
+    );
+}
+
+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)) {
+        const bare = listKey(key, prefix);
+        if (bare === undefined) continue;
+        for (const value of Array.isArray(valuesForKey)
+            ? valuesForKey
+            : [valuesForKey])
+            params.append(bare, value ?? '');
+    }
+    params.sort();
+    return params;
+}
+
+function apiError(cause: unknown): ApiError {
+    const candidate =
+        cause && typeof cause === 'object' && 'error' in cause
+            ? cause.error
+            : cause;
+    if (
+        candidate &&
+        typeof candidate === 'object' &&
+        'code' in candidate &&
+        typeof candidate.code === 'string' &&
+        'message' in candidate &&
+        typeof candidate.message === 'string'
+    )
+        return candidate as ApiError;
+    return {
+        code: 'load_failed',
+        message:
+            cause instanceof Error
+                ? cause.message
+                : 'The list could not be loaded.',
+    };
+}
+
+interface Work {
+    promise: Promise<void>;
+    finish: () => void;
+}
+
+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(
+            {
+                page: 1,
+                page_size: props.queryOptions.defaultPageSize ?? 20,
+                search: '',
+                sort: null,
+                filters: {},
+            },
+            props.queryOptions,
+        );
+    const query = shallowRef<ListQuery>(defaults());
+    const search = ref(query.value.search);
+    const rows = shallowRef<T[]>([]);
+    const meta = shallowRef({
+        page: query.value.page,
+        page_size: query.value.page_size,
+        total: 0,
+    });
+    const loading = ref(false);
+    const error = shallowRef<ApiError | null>(null);
+    const errors = computed(() => (error.value ? [error.value.message] : []));
+    const invalidQuery = ref(false);
+    let request = 0;
+    let navigation = 0;
+    let controller: AbortController | undefined;
+    let searchTimer: ReturnType<typeof setTimeout> | undefined;
+    let disposed = false;
+    let activeWork: Work | undefined;
+    let pendingUrl: { path: string; query: string; work: Work } | undefined;
+
+    function startWork(): Work {
+        activeWork?.finish();
+        cancelRequest();
+        let finish!: () => void;
+        const promise = new Promise<void>((resolve) => {
+            finish = resolve;
+        });
+        activeWork = { promise, finish };
+        return activeWork;
+    }
+
+    function fail(cause: unknown) {
+        error.value = apiError(cause);
+        invalidQuery.value = error.value.code === 'invalid_query';
+    }
+
+    function cancelSearch() {
+        clearTimeout(searchTimer);
+        searchTimer = undefined;
+    }
+
+    function cancelRequest() {
+        request++;
+        controller?.abort();
+        loading.value = false;
+    }
+
+    function fetchRows(work = startWork()): Promise<void> {
+        cancelRequest();
+        if (disposed || invalidQuery.value) {
+            work.finish();
+            return work.promise;
+        }
+        const current = request;
+        controller = new AbortController();
+        const { signal } = controller;
+        loading.value = true;
+        error.value = null;
+        void (async () => {
+            try {
+                const response = await props.load(cloneRecord(query.value), {
+                    signal,
+                });
+                if (current !== request) return;
+                rows.value = response.data;
+                meta.value = response.meta;
+            } catch (cause) {
+                if (current === request) fail(cause);
+            } finally {
+                if (current === request) loading.value = false;
+                work.finish();
+            }
+        })();
+        return work.promise;
+    }
+
+    function accept(next: ListQuery, work: Work) {
+        query.value = next;
+        search.value = next.search;
+        invalidQuery.value = false;
+        return fetchRows(work);
+    }
+
+    const urlQuery = computed(() =>
+        syncing() && route ? routeParams(route.query, prefix()).toString() : '',
+    );
+    watch(
+        [
+            urlQuery,
+            () => (syncing() ? route?.path : ''),
+            () => props.syncQuery,
+            () => props.queryOptions,
+            () => props.load,
+        ],
+        () => {
+            const matchesPending =
+                pendingUrl?.path === route?.path &&
+                pendingUrl?.query === urlQuery.value;
+            const preserveSearch = searchTimer !== undefined && matchesPending;
+            const work = preserveSearch
+                ? activeWork!
+                : matchesPending
+                  ? pendingUrl!.work
+                  : startWork();
+            pendingUrl = undefined;
+            navigation++;
+            if (!preserveSearch) cancelSearch();
+            cancelRequest();
+            if (syncing() && (!route || !router))
+                throw new Error(
+                    'Index sync-query requires an installed Vue Router.',
+                );
+            try {
+                const next = syncing()
+                    ? decodeListQuery(
+                          new URLSearchParams(urlQuery.value),
+                          props.queryOptions,
+                      )
+                    : normalizeListQuery(query.value, props.queryOptions);
+                if (preserveSearch) {
+                    query.value = next;
+                    invalidQuery.value = false;
+                    loading.value = true;
+                } else void accept(next, work);
+            } catch (cause) {
+                fail(cause);
+                work.finish();
+            }
+        },
+        { immediate: true, deep: true },
+    );
+
+    function commit(next: ListQuery, replace = false): Promise<void> {
+        if (disposed) return Promise.resolve();
+        cancelSearch();
+        const work = startWork();
+        let normalized: ListQuery;
+        try {
+            normalized = normalizeListQuery(next, props.queryOptions);
+        } catch (cause) {
+            fail(cause);
+            work.finish();
+            return work.promise;
+        }
+        if (!syncing() || !route || !router) return accept(normalized, work);
+        const keyPrefix = prefix();
+        const values = { ...route.query };
+        for (const key of Object.keys(values))
+            if (listKey(key, keyPrefix) !== undefined) delete values[key];
+        for (const [key, value] of encodeListQuery(normalized))
+            values[keyPrefix + key] = value;
+        query.value = normalized;
+        search.value = normalized.search;
+        const attempt = ++navigation;
+        const path = route.path;
+        pendingUrl = {
+            path,
+            query: routeParams(values, keyPrefix).toString(),
+            work,
+        };
+        loading.value = true;
+        void (async () => {
+            try {
+                const failure = await router[replace ? 'replace' : 'push']({
+                    query: values,
+                    hash: route.hash,
+                });
+                if (disposed || attempt !== navigation || route.path !== path)
+                    return;
+                if (
+                    isNavigationFailure(
+                        failure,
+                        NavigationFailureType.duplicated,
+                    )
+                ) {
+                    pendingUrl = undefined;
+                    if (searchTimer !== undefined) {
+                        query.value = normalized;
+                        invalidQuery.value = false;
+                    } else void accept(normalized, work);
+                } else if (failure)
+                    failNavigation(
+                        new Error('The list URL could not be updated.'),
+                        work,
+                    );
+            } catch (cause) {
+                if (disposed || attempt !== navigation || route.path !== path)
+                    return;
+                failNavigation(cause, work);
+            }
+        })();
+        return work.promise;
+    }
+
+    function failNavigation(cause: unknown, work: Work) {
+        pendingUrl = undefined;
+        const preserveSearch = searchTimer !== undefined;
+        cancelRequest();
+        try {
+            query.value = decodeListQuery(
+                routeParams(route!.query, prefix()),
+                props.queryOptions,
+            );
+            if (!preserveSearch) search.value = query.value.search;
+            invalidQuery.value = false;
+        } catch {
+            invalidQuery.value = true;
+        }
+        error.value = apiError(cause);
+        loading.value = preserveSearch;
+        work.finish();
+    }
+
+    function updateCriteria(patch: Partial<Omit<ListQuery, 'page'>>) {
+        void commit({
+            ...query.value,
+            search: search.value,
+            ...patch,
+            page: 1,
+        });
+    }
+
+    function setSearch(value: string) {
+        if (disposed) return;
+        cancelSearch();
+        startWork();
+        search.value = value;
+        loading.value = true;
+        searchTimer = setTimeout(
+            () => {
+                void commit({ ...query.value, search: value, page: 1 }, true);
+            },
+            Math.max(0, props.searchDebounce),
+        );
+    }
+
+    function reload(): Promise<void> {
+        cancelSearch();
+        if (pendingUrl || search.value !== query.value.search)
+            return commit(
+                {
+                    ...query.value,
+                    search: search.value,
+                    page:
+                        search.value !== query.value.search
+                            ? 1
+                            : query.value.page,
+                },
+                true,
+            );
+        return fetchRows();
+    }
+
+    function reset(): Promise<void> {
+        return commit(defaults(), true);
+    }
+    function setPage(page: number) {
+        void commit({
+            ...query.value,
+            search: search.value,
+            page: search.value !== query.value.search ? 1 : page,
+        });
+    }
+    function setFilters(filters: ListQuery['filters']) {
+        updateCriteria({ filters: { ...filters } });
+    }
+
+    function setFilter(name: string, value: string | undefined) {
+        if (value !== undefined) {
+            setFilters({ ...query.value.filters, [name]: value });
+            return;
+        }
+        const filters = { ...query.value.filters };
+        delete filters[name];
+        setFilters(filters);
+    }
+
+    onScopeDispose(() => {
+        disposed = true;
+        navigation++;
+        cancelSearch();
+        cancelRequest();
+        activeWork?.finish();
+    });
+
+    return {
+        query,
+        search,
+        rows,
+        meta,
+        loading,
+        error,
+        errors,
+        invalidQuery,
+        updateCriteria,
+        setSearch,
+        setPage,
+        setFilters,
+        setFilter,
+        reload,
+        reset,
+    };
+}

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/layout/table/table.css

@@ -66,7 +66,8 @@
         align-items: center;
         gap: var(--space-2xs);
         min-width: 0;
-        padding: var(--space-xs) var(--space-s);
+        padding-block: var(--pui-table-cell-padding-block, var(--space-xs));
+        padding-inline: var(--space-s);
         text-align: left;
 
         &[data-head] {

package/components/navigation/breadcrumb/Breadcrumb.vue

@@ -1,6 +1,6 @@
 <template>
-    <nav aria-label="Breadcrumb">
-        <ol class="pui-breadcrumb">
+    <nav aria-label="Breadcrumb" class="pui-breadcrumb">
+        <ol class="pui-breadcrumb__trail">
             <template v-for="(item, index) in items" :key="index">
                 <li
                     v-if="index > 0"
@@ -13,15 +13,25 @@
                     v-if="index < items.length - 1"
                     class="pui-breadcrumb__item"
                 >
-                    <a :href="item.href" class="pui-breadcrumb__link">{{
-                        item.label
-                    }}</a>
+                    <slot
+                        name="link"
+                        :item="item"
+                        :index="index"
+                        link-class="pui-breadcrumb__link"
+                    >
+                        <a :href="item.href" class="pui-breadcrumb__link">{{
+                            item.label
+                        }}</a>
+                    </slot>
                 </li>
                 <li v-else class="pui-breadcrumb__item" aria-current="page">
                     {{ item.label }}
                 </li>
             </template>
         </ol>
+        <div v-if="$slots.actions" class="pui-breadcrumb__actions">
+            <slot name="actions" />
+        </div>
     </nav>
 </template>
 
@@ -29,6 +39,15 @@
 defineProps<{
     items: { label: string; href?: string }[];
 }>();
+
+defineSlots<{
+    link?: (scope: {
+        item: { label: string; href?: string };
+        index: number;
+        linkClass: string;
+    }) => unknown;
+    actions?: () => unknown;
+}>();
 </script>
 
 <style>

package/components/navigation/breadcrumb/breadcrumb.css

@@ -1,5 +1,12 @@
 @layer components {
     .pui-breadcrumb {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--space-s);
+    }
+
+    .pui-breadcrumb__trail {
         display: flex;
         align-items: center;
         gap: var(--space-2xs);
@@ -9,6 +16,14 @@
         padding: 0;
         margin: 0;
         flex-wrap: wrap;
+        min-inline-size: 0;
+    }
+
+    .pui-breadcrumb__actions {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--space-2xs);
+        flex: none;
     }
 
     .pui-breadcrumb__item {
@@ -26,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.vue

@@ -323,6 +323,17 @@ function onEntryKeydown(event: KeyboardEvent): void {
     const item = event.currentTarget;
     if (!(item instanceof HTMLElement)) return;
 
+    if (event.key === ' ' || event.key === 'Spacebar') {
+        // `<a>` doesn't activate on Space natively.
+        if (item.matches('[data-sidebar-link]')) {
+            event.preventDefault();
+            item.click();
+        }
+        return;
+    }
+
+    if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;
+
     const entries = focusableEntries();
     const idx = entries.indexOf(item);
 
@@ -343,14 +354,6 @@ function onEntryKeydown(event: KeyboardEvent): void {
             event.preventDefault();
             entries[entries.length - 1]?.focus();
             return;
-        case ' ':
-        case 'Spacebar':
-            // `<a>` doesn't activate on Space natively.
-            if (item.matches('[data-sidebar-link]')) {
-                event.preventDefault();
-                item.click();
-            }
-            return;
         default:
             return;
     }

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;
+        }
+    }
 }