@pienter/ui 0.3.0 → 0.7.1

package/components/layout/index/useIndex.ts

@@ -0,0 +1,390 @@
+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;
+    syncQuery: boolean;
+    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 routeParams(values: LocationQuery): URLSearchParams {
+    const params = new URLSearchParams();
+    for (const [key, valuesForKey] of Object.entries(values)) {
+        if (!isListParameter(key)) continue;
+        for (const value of Array.isArray(valuesForKey)
+            ? valuesForKey
+            : [valuesForKey])
+            params.append(key, 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 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(() =>
+        props.syncQuery && route ? routeParams(route.query).toString() : '',
+    );
+    watch(
+        [
+            urlQuery,
+            () => (props.syncQuery ? 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 (props.syncQuery && (!route || !router))
+                throw new Error(
+                    'Index sync-query requires an installed Vue Router.',
+                );
+            try {
+                const next = props.syncQuery
+                    ? 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 (!props.syncQuery || !route || !router)
+            return accept(normalized, work);
+        const values = { ...route.query };
+        for (const key of Object.keys(values))
+            if (isListParameter(key)) delete values[key];
+        for (const [key, value] of encodeListQuery(normalized))
+            values[key] = value;
+        query.value = normalized;
+        search.value = normalized.search;
+        const attempt = ++navigation;
+        const path = route.path;
+        pendingUrl = { path, query: routeParams(values).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),
+                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/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] {
@@ -93,8 +94,8 @@
 
     /* ===== sort affordance ===== */
 
-    /* One rule for both tiers — a <button> in Vue, an <a> in Astro — so the resets below
-       deliberately cover both elements. */
+    /* Rendered as a <button>; the resets below also cover <a> so a
+       consumer-supplied link header behaves identically. */
     .pui-table__sort {
         display: inline-flex;
         align-items: center;
@@ -167,7 +168,7 @@
     .pui-table__loading {
         position: absolute;
         inset: 0;
-        z-index: 1;
+        z-index: var(--layer-1);
 
         /* the tint gives the blur a surface to sit in; without it the frosting
            reads as a smudge rather than a pane */

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-sm);
+    }
+
+    .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 {