@pienter/ui 0.17.0 → 0.19.0

package/components/layout/index/Index.vue

@@ -19,7 +19,7 @@
             <div
                 v-if="
                     !invalidQuery &&
-                    (searchable || $slots.filters || queryOptions.sorts.length)
+                    (searchable || $slots.filters || vocabulary.sorts.length)
                 "
                 class="pui-index__toolbar"
             >
@@ -38,7 +38,7 @@
                     :set-filters="setFilters"
                     :set-filter="setFilter"
                 />
-                <div v-if="queryOptions.sorts.length" class="pui-index__sort">
+                <div v-if="vocabulary.sorts.length" class="pui-index__sort">
                     <Select
                         :label="sortLabel"
                         :aria-label="sortLabel"
@@ -51,6 +51,34 @@
                 </div>
             </div>
 
+            <div
+                v-if="!invalidQuery && activeFilters.length"
+                class="pui-index__filters"
+            >
+                <ul class="pui-index__chips" aria-label="Active filters">
+                    <li
+                        v-for="chip in activeFilters"
+                        :key="`${chip.name}=${chip.value}`"
+                    >
+                        <Badge>
+                            {{ chip.label }}: {{ chip.valueLabel }}
+                            <IconButton
+                                name="x"
+                                size="sm"
+                                variant="ghost"
+                                :label="`Remove ${chip.label} ${chip.valueLabel}`"
+                                @click="
+                                    removeFilterValue(chip.name, chip.value)
+                                "
+                            />
+                        </Badge>
+                    </li>
+                </ul>
+                <Button size="sm" variant="ghost" @click="clearFilters()"
+                    >Clear all</Button
+                >
+            </div>
+
             <div class="pui-index__selection" role="status">
                 <slot
                     v-if="selectable && selected.length && $slots.selection"
@@ -170,15 +198,24 @@ import Select from '../../form/select/Select.vue';
 import Alert from '../../feedback/alert/Alert.vue';
 import Pagination from '../../navigation/pagination/Pagination.vue';
 import PaginationFooter from '../../navigation/pagination/PaginationFooter.vue';
-import type {
-    ApiError,
-    ListQuery,
-    ListLoader,
-    QueryOptions,
+import {
+    joinFilterValues,
+    splitFilterValues,
+    type ApiError,
+    type ListQuery,
+    type ListLoader,
+    type QueryOptions,
 } from '../../../utils/cms/index.js';
 import Button from '../../action/button/Button.vue';
+import IconButton from '../../action/button/IconButton.vue';
+import Badge from '../../display/badge/Badge.vue';
 import { generateId } from '../../../utils/a11y/id.js';
-import { useIndex } from './useIndex.js';
+import {
+    provideIndexQuery,
+    useIndexQuery,
+    type IndexQuery,
+    type IndexQueryOptions,
+} from './useIndexQuery.js';
 import {
     formatSort,
     parseSort,
@@ -187,10 +224,13 @@ import {
 
 const props = withDefaults(
     defineProps<{
-        /** Returns the matching page using the shared backend response contract. */
-        load: ListLoader<T>;
+        /** Returns the matching page using the shared backend response contract. Required unless `state` is passed. */
+        load?: ListLoader<T>;
         columns: Column[];
-        queryOptions: QueryOptions;
+        /** Required unless `state` is passed. */
+        queryOptions?: QueryOptions;
+        /** Query state from `useIndexQuery`, when the definition owns it; `load`, `queryOptions`, `syncQuery` and `searchDebounce` then come from there. */
+        state?: IndexQuery<T>;
         /** `module` is the page itself (flat, h1); `related` sits inside a record's detail page (one bordered region, h2). */
         placement?: 'module' | 'related';
         /** Synchronize list parameters with the current Vue Router route; a string prefixes every key (`contacts.page`). */
@@ -207,6 +247,10 @@ const props = withDefaults(
         sortLabel?: string;
         /** Labels for sort keys, including fields without a visible column. */
         sortLabels?: Record<string, string>;
+        /** Labels for filter names in the active-filters row; the raw name otherwise. */
+        filterLabels?: Record<string, string>;
+        /** Labels for filter values in the active-filters row, per filter name; the raw value otherwise. */
+        filterValueLabels?: Record<string, Record<string, string>>;
         /** An empty array hides the page-size control. */
         pageSizes?: number[];
         pageSizeLabel?: string;
@@ -216,6 +260,9 @@ const props = withDefaults(
         clickable?: boolean;
     }>(),
     {
+        load: undefined,
+        queryOptions: undefined,
+        state: undefined,
         placement: 'module',
         syncQuery: false,
         searchDebounce: 250,
@@ -227,6 +274,8 @@ const props = withDefaults(
         searchPlaceholder: undefined,
         sortLabel: 'Sort by',
         sortLabels: () => ({}),
+        filterLabels: () => ({}),
+        filterValueLabels: () => ({}),
         pageSizes: () => [10, 20, 50],
         pageSizeLabel: 'Rows per page',
         rowKey: 'id',
@@ -268,23 +317,17 @@ const slots = defineSlots<{
     [name: `cell:${string}`]: (scope: { row: T; value: unknown }) => unknown;
 }>();
 
-const unsupportedSortColumns = computed(() =>
-    props.columns.filter(
-        (column) =>
-            column.sortable && !props.queryOptions.sorts.includes(column.key),
-    ),
-);
-function validateSortColumns(unsupported: Column[]) {
-    if (unsupported.length) {
+function ownState() {
+    if (!props.load || !props.queryOptions)
         throw new Error(
-            `[pui] Index sortable columns must be allowed by queryOptions.sorts: ${unsupported.map((column) => column.key).join(', ')}.`,
+            '[pui] Index needs load and queryOptions, or a state from useIndexQuery.',
         );
-    }
+    return useIndexQuery<T>(props as IndexQueryOptions<T>);
 }
-validateSortColumns(unsupportedSortColumns.value);
-watch(unsupportedSortColumns, validateSortColumns);
-
+const state = props.state ?? ownState();
+provideIndexQuery(state);
 const {
+    queryOptions: vocabulary,
     query,
     search,
     rows,
@@ -298,9 +341,27 @@ const {
     setPage,
     setFilters,
     setFilter,
+    clearFilters,
     reload,
     reset,
-} = useIndex<T>(props);
+} = state;
+
+const unsupportedSortColumns = computed(() =>
+    props.columns.filter(
+        (column) =>
+            column.sortable && !vocabulary.value.sorts.includes(column.key),
+    ),
+);
+function validateSortColumns(unsupported: Column[]) {
+    if (unsupported.length) {
+        throw new Error(
+            `[pui] Index sortable columns must be allowed by queryOptions.sorts: ${unsupported.map((column) => column.key).join(', ')}.`,
+        );
+    }
+}
+validateSortColumns(unsupportedSortColumns.value);
+watch(unsupportedSortColumns, validateSortColumns);
+
 defineExpose({ reload });
 const titleId = generateId('index-title');
 const total = computed(() => meta.value.total);
@@ -311,7 +372,7 @@ const showResults = computed(
 );
 const sortOptions = computed(() => [
     { value: '', label: 'Default order' },
-    ...props.queryOptions.sorts.flatMap((key) => {
+    ...vocabulary.value.sorts.flatMap((key) => {
         const label =
             props.sortLabels[key] ??
             props.columns.find((column) => column.key === key)?.label ??
@@ -331,6 +392,27 @@ const sortOptions = computed(() => [
     }),
 ]);
 
+const activeFilters = computed(() =>
+    Object.entries(query.value.filters).flatMap(([name, raw]) =>
+        splitFilterValues(raw).map((value) => ({
+            name,
+            value,
+            label: props.filterLabels[name] ?? name,
+            valueLabel: props.filterValueLabels[name]?.[value] ?? value,
+        })),
+    ),
+);
+function removeFilterValue(name: string, value: string) {
+    setFilter(
+        name,
+        joinFilterValues(
+            splitFilterValues(query.value.filters[name]).filter(
+                (other) => other !== value,
+            ),
+        ),
+    );
+}
+
 const cellSlots = computed(() =>
     props.columns
         .map((column) => `cell:${column.key}` as const)
@@ -353,7 +435,7 @@ const pageSizeOptions = computed(() =>
             (size) =>
                 Number.isInteger(size) &&
                 size > 0 &&
-                size <= (props.queryOptions.maxPageSize ?? 100),
+                size <= (vocabulary.value.maxPageSize ?? 100),
         )
         .sort((a, b) => a - b)
         .map((size) => ({ value: String(size), label: String(size) })),

package/components/layout/index/index.css

@@ -39,6 +39,22 @@
         max-inline-size: 100%;
     }
 
+    .pui-index__filters {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--space-2xs);
+    }
+
+    .pui-index__chips {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--space-2xs);
+        list-style: none;
+        padding: 0;
+    }
+
     .pui-index__results {
         min-inline-size: 0;
     }
@@ -76,6 +92,7 @@
        selection region is always rendered, so it spaces itself only when filled. */
     .pui-index[data-placement='module'] {
         & .pui-index__toolbar,
+        & .pui-index__filters,
         & .pui-index__selection:not(:empty),
         & .pui-index__error {
             margin-block-end: var(--space-s);
@@ -102,6 +119,7 @@
             border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
         }
 
+        & .pui-index__filters,
         & .pui-index__selection:not(:empty),
         & .pui-index__error {
             padding: var(--space-s);

package/components/layout/index/{useIndex.ts → useIndexQuery.ts}

@@ -1,4 +1,13 @@
-import { computed, inject, onScopeDispose, ref, shallowRef, watch } from 'vue';
+import {
+    computed,
+    inject,
+    onScopeDispose,
+    provide,
+    ref,
+    shallowRef,
+    watch,
+    type InjectionKey,
+} from 'vue';
 import {
     routeLocationKey,
     routerKey,
@@ -17,12 +26,50 @@ import {
     type QueryOptions,
 } from '../../../utils/cms/index.js';
 
-interface Options<T> {
+export interface IndexQueryOptions<T> {
+    /** Returns the matching page using the shared backend response contract. */
     load: ListLoader<T>;
     queryOptions: QueryOptions;
-    /** `true` syncs the bare keys; a string syncs `<prefix>.<key>` instead. */
-    syncQuery: boolean | string;
-    searchDebounce: number;
+    /** `true` syncs the bare keys; a string syncs `<prefix>.<key>` instead. Default `false`. */
+    syncQuery?: boolean | string;
+    /** Delay in milliseconds before committing typed search text. Default 250. */
+    searchDebounce?: number;
+}
+
+/** The query state of one index, shared by `Index` and any filter control bound to it. */
+export type IndexQuery<T> = ReturnType<typeof useIndexQuery<T>>;
+
+const indexQueryKey: InjectionKey<IndexQuery<unknown>> =
+    Symbol('pui-index-query');
+
+/** Makes `state` the index every `useIndexFilters()` below reads; `Index` does this for its own subtree. */
+export function provideIndexQuery<T>(state: IndexQuery<T>) {
+    provide(indexQueryKey, state);
+}
+
+/** The state provided above the caller, or `undefined` outside an Index and without a provider. */
+export function injectIndexQuery(): IndexQuery<unknown> | undefined {
+    return inject(indexQueryKey, undefined);
+}
+
+/** What a filter control needs from the index it belongs to: the provided state, or an explicit one. */
+export function useIndexFilters(state?: IndexQuery<unknown>) {
+    const index = state ?? injectIndexQuery();
+    if (!index)
+        throw new Error(
+            '[pui] useIndexFilters needs an Index above it or a state from useIndexQuery.',
+        );
+    return {
+        filters: computed<Readonly<ListQuery['filters']>>(
+            () => index.query.value.filters,
+        ),
+        /** Allowed filter names, from `queryOptions.filters`. */
+        filterNames: computed(() => index.queryOptions.value.filters),
+        loading: computed(() => index.loading.value),
+        setFilter: index.setFilter,
+        setFilters: index.setFilters,
+        clearFilters: index.clearFilters,
+    };
 }
 
 function isListParameter(key: string): boolean {
@@ -83,10 +130,11 @@ interface Work {
     finish: () => void;
 }
 
-export function useIndex<T>(props: Options<T>) {
+export function useIndexQuery<T>(props: IndexQueryOptions<T>) {
     const route = inject(routeLocationKey, undefined);
     const router = inject(routerKey, undefined);
-    const syncing = () => props.syncQuery !== false;
+    const syncing = () =>
+        props.syncQuery !== undefined && props.syncQuery !== false;
     const prefix = () =>
         typeof props.syncQuery === 'string' && props.syncQuery
             ? `${props.syncQuery}.`
@@ -334,7 +382,7 @@ export function useIndex<T>(props: Options<T>) {
             () => {
                 void commit({ ...query.value, search: value, page: 1 }, true);
             },
-            Math.max(0, props.searchDebounce),
+            Math.max(0, props.searchDebounce ?? 250),
         );
     }
 
@@ -379,6 +427,10 @@ export function useIndex<T>(props: Options<T>) {
         setFilters(filters);
     }
 
+    function clearFilters() {
+        setFilters({});
+    }
+
     onScopeDispose(() => {
         disposed = true;
         navigation++;
@@ -388,6 +440,7 @@ export function useIndex<T>(props: Options<T>) {
     });
 
     return {
+        queryOptions: computed(() => props.queryOptions),
         query,
         search,
         rows,
@@ -401,6 +454,7 @@ export function useIndex<T>(props: Options<T>) {
         setPage,
         setFilters,
         setFilter,
+        clearFilters,
         reload,
         reset,
     };

package/components/layout/index-filters/FilterCheckbox.vue

@@ -0,0 +1,29 @@
+<template>
+    <Checkbox
+        :label="label"
+        :model-value="filters[name] === 'true'"
+        @update:model-value="setFilter(name, $event ? 'true' : undefined)"
+    />
+</template>
+
+<script setup lang="ts">
+import Checkbox from '../../form/checkbox/Checkbox.vue';
+import type { IndexQuery } from '../index/useIndexQuery.js';
+import { useFilterControl } from './useFilterControl.js';
+
+const props = withDefaults(
+    defineProps<{
+        /** The allowlisted filter name: `'true'` while checked, deleted otherwise. */
+        name: string;
+        label: string;
+        /** The index state, for a control rendered outside an Index without a provider above it. */
+        state?: IndexQuery<unknown>;
+    }>(),
+    { state: undefined },
+);
+
+const { filters, setFilter } = useFilterControl(
+    () => [props.name],
+    props.state,
+);
+</script>

package/components/layout/index-filters/FilterMultiSelect.vue

@@ -0,0 +1,110 @@
+<template>
+    <fieldset class="pui-field pui-filter-multi-select">
+        <legend class="pui-field__label">
+            {{ label }} ({{ selected.length }})
+        </legend>
+        <Button
+            v-if="selected.length"
+            class="pui-filter-multi-select__clear"
+            size="sm"
+            variant="ghost"
+            :aria-label="`Clear ${label}`"
+            @click="setFilter(name, undefined)"
+            >Clear</Button
+        >
+        <input
+            v-if="searchable"
+            v-model="search"
+            class="pui-input pui-filter-multi-select__search"
+            type="search"
+            :aria-label="`Search ${label}`"
+            :placeholder="searchPlaceholder ?? `Search ${label}`"
+        />
+        <div class="pui-filter-multi-select__options">
+            <label
+                v-for="option in visibleOptions"
+                :key="option.value"
+                class="pui-filter-multi-select__option"
+            >
+                <input
+                    class="pui-checkbox"
+                    type="checkbox"
+                    :name="name"
+                    :value="option.value"
+                    :checked="selected.includes(option.value)"
+                    :aria-checked="
+                        selected.includes(option.value) ? 'true' : 'false'
+                    "
+                    @change="
+                        toggle(
+                            option.value,
+                            ($event.target as HTMLInputElement).checked,
+                        )
+                    "
+                />
+                <span class="pui-filter-multi-select__label">{{
+                    option.label
+                }}</span>
+                <span
+                    v-if="typeof option.count === 'number'"
+                    class="pui-filter-multi-select__count"
+                    >({{ option.count }})</span
+                >
+            </label>
+            <p v-if="!visibleOptions.length" class="pui-field__hint">
+                No matching options.
+            </p>
+        </div>
+    </fieldset>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import Button from '../../action/button/Button.vue';
+import {
+    joinFilterValues,
+    splitFilterValues,
+} from '../../../utils/cms/index.js';
+import type { IndexQuery } from '../index/useIndexQuery.js';
+import { useFilterControl } from './useFilterControl.js';
+
+const props = withDefaults(
+    defineProps<{
+        /** The allowlisted filter name; values join as one comma-separated string (ADR 0009). */
+        name: string;
+        label: string;
+        /** `count` renders muted after the label when it is a number. */
+        options: { value: string; label: string; count?: number }[];
+        /** Shows a search box that narrows the options by case-insensitive substring of the label. */
+        searchable?: boolean;
+        searchPlaceholder?: string;
+        /** The index state, for a control rendered outside an Index without a provider above it. */
+        state?: IndexQuery<unknown>;
+    }>(),
+    { searchable: false, searchPlaceholder: undefined, state: undefined },
+);
+
+const { filters, setFilter } = useFilterControl(
+    () => [props.name],
+    props.state,
+);
+const search = ref('');
+const selected = computed(() => splitFilterValues(filters.value[props.name]));
+const visibleOptions = computed(() => {
+    const needle = props.searchable ? search.value.trim().toLowerCase() : '';
+    return needle
+        ? props.options.filter((option) =>
+              option.label.toLowerCase().includes(needle),
+          )
+        : props.options;
+});
+
+function toggle(value: string, checked: boolean) {
+    const rest = selected.value.filter((other) => other !== value);
+    setFilter(props.name, joinFilterValues(checked ? [...rest, value] : rest));
+}
+</script>
+
+<style>
+@import './filters.css';
+</style>

package/components/layout/index-filters/FilterRange.vue

@@ -0,0 +1,80 @@
+<template>
+    <fieldset class="pui-field pui-filter-range">
+        <legend class="pui-field__label">{{ label }}</legend>
+        <div class="pui-filter-range__bounds">
+            <NumberField
+                label="Min"
+                layout="inline"
+                :steppers="false"
+                :min="min"
+                :max="max"
+                :step="step"
+                :model-value="bound(minName)"
+                @change="
+                    commit(
+                        minName,
+                        ($event.target as HTMLInputElement).valueAsNumber,
+                    )
+                "
+            />
+            <NumberField
+                label="Max"
+                layout="inline"
+                :steppers="false"
+                :min="min"
+                :max="max"
+                :step="step"
+                :model-value="bound(maxName)"
+                @change="
+                    commit(
+                        maxName,
+                        ($event.target as HTMLInputElement).valueAsNumber,
+                    )
+                "
+            />
+        </div>
+    </fieldset>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import NumberField from '../../form/number-field/NumberField.vue';
+import type { IndexQuery } from '../index/useIndexQuery.js';
+import { useFilterControl } from './useFilterControl.js';
+
+const props = withDefaults(
+    defineProps<{
+        /** The range name; the bounds are the allowlisted filters `<name>_min` and `<name>_max` (ADR 0009). */
+        name: string;
+        label: string;
+        min?: number;
+        max?: number;
+        step?: number | string;
+        /** The index state, for a control rendered outside an Index without a provider above it. */
+        state?: IndexQuery<unknown>;
+    }>(),
+    { min: undefined, max: undefined, step: undefined, state: undefined },
+);
+
+const minName = computed(() => `${props.name}_min`);
+const maxName = computed(() => `${props.name}_max`);
+const { filters, setFilter } = useFilterControl(
+    () => [minName.value, maxName.value],
+    props.state,
+);
+
+function bound(name: string): number | undefined {
+    const value = filters.value[name];
+    const number = Number(value);
+    return value && Number.isFinite(number) ? number : undefined;
+}
+
+function commit(name: string, value: number) {
+    const next = Number.isFinite(value) ? String(value) : undefined;
+    if (next !== filters.value[name]) setFilter(name, next);
+}
+</script>
+
+<style>
+@import './filters.css';
+</style>

package/components/layout/index-filters/FilterSelect.vue

@@ -0,0 +1,38 @@
+<template>
+    <SelectField
+        :label="label"
+        :options="allOptions"
+        :model-value="filters[name] ?? ''"
+        @update:model-value="setFilter(name, $event || undefined)"
+    />
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import SelectField from '../../form/select/Select.vue';
+import type { IndexQuery } from '../index/useIndexQuery.js';
+import { useFilterControl } from './useFilterControl.js';
+
+const props = withDefaults(
+    defineProps<{
+        /** The allowlisted filter name; the empty option deletes it. */
+        name: string;
+        label: string;
+        options: { value: string; label: string }[];
+        /** Label of the first option, which clears the filter. */
+        emptyLabel?: string;
+        /** The index state, for a control rendered outside an Index without a provider above it. */
+        state?: IndexQuery<unknown>;
+    }>(),
+    { emptyLabel: 'All', state: undefined },
+);
+
+const { filters, setFilter } = useFilterControl(
+    () => [props.name],
+    props.state,
+);
+const allOptions = computed(() => [
+    { value: '', label: props.emptyLabel },
+    ...props.options,
+]);
+</script>