@pienter/ui 0.5.0 → 0.8.0

package/components/layout/app-layout/app-layout.css

@@ -0,0 +1,115 @@
+@layer components {
+    .pui-app-layout {
+        display: grid;
+        grid-template-rows: auto minmax(0, 1fr);
+        min-block-size: 100vh;
+
+        & .pui-app-layout__skip-link {
+            position: fixed;
+            inset-block-start: var(--space-2xs);
+            inset-inline-start: var(--space-2xs);
+            z-index: var(--layer-top);
+            inline-size: var(--stroke-sm);
+            block-size: var(--stroke-sm);
+            padding: 0;
+            overflow: hidden;
+            clip-path: inset(50%);
+            white-space: nowrap;
+
+            &:focus {
+                inline-size: auto;
+                block-size: auto;
+                padding: var(--space-2xs) var(--space-s);
+                overflow: visible;
+                clip-path: none;
+                border-radius: var(--radius-pill);
+                color: var(--text-clr-inverse);
+                background: var(--bg-clr-brand);
+                font-weight: var(--fw-semibold);
+                text-decoration: none;
+                outline: var(--outline-width) solid var(--outline-clr-base);
+                outline-offset: var(--outline-offset);
+            }
+        }
+
+        & .pui-app-layout__header {
+            position: sticky;
+            inset-block-start: 0;
+            z-index: var(--layer-4);
+            display: flex;
+            align-items: center;
+            gap: var(--space-s);
+            min-block-size: var(--space-2xl);
+            padding-inline: var(--space-s);
+            background: var(--bg-clr-surface);
+            border-block-end: var(--stroke-sm) solid var(--border-clr-base);
+        }
+
+        & .pui-app-layout__brand {
+            min-inline-size: 0;
+        }
+
+        & .pui-app-layout__tools {
+            display: flex;
+            align-items: center;
+            gap: var(--space-2xs);
+            min-inline-size: 0;
+            margin-inline-start: auto;
+        }
+
+        & .pui-app-layout__body {
+            display: grid;
+            grid-template-columns: auto minmax(0, 1fr);
+            min-block-size: 0;
+        }
+
+        & .pui-app-layout__navigation {
+            min-block-size: 0;
+        }
+
+        & .pui-app-layout__main {
+            display: grid;
+            grid-template-rows: minmax(0, 1fr);
+            min-inline-size: 0;
+            padding: var(
+                --pui-app-layout-main-padding,
+                var(--space-m) var(--space-l) var(--space-xl)
+            );
+
+            &:focus:not(:focus-visible) {
+                outline: none;
+            }
+
+            &:focus-visible {
+                outline: var(--outline-width) solid var(--outline-clr-base);
+                outline-offset: calc(-1 * var(--outline-width));
+            }
+        }
+
+        & .pui-app-layout__drawer-toggle {
+            display: none;
+            flex-shrink: 0;
+        }
+
+        @media (min-width: 48em) {
+            & .pui-app-layout__navigation {
+                position: sticky;
+                inset-block-start: var(--space-2xl);
+                block-size: calc(100vh - var(--space-2xl));
+            }
+        }
+
+        @media (max-width: 47.999em) {
+            & .pui-app-layout__drawer-toggle {
+                display: inline-flex;
+            }
+
+            & .pui-app-layout__main {
+                padding: var(
+                    --pui-app-layout-main-padding-mobile,
+                    var(--space-s)
+                );
+            }
+        }
+    }
+}

package/components/layout/index/Index.vue

@@ -0,0 +1,373 @@
+<template>
+    <div
+        class="pui-index"
+        :data-placement="placement"
+        :data-state="loading ? 'loading' : undefined"
+    >
+        <header
+            v-if="title || description || $slots.actions"
+            class="pui-index__header"
+        >
+            <div v-if="title || description" class="pui-index__heading">
+                <component
+                    :is="placement === 'related' ? 'h2' : 'h1'"
+                    v-if="title"
+                    :id="titleId"
+                    class="pui-index__title"
+                    >{{ title }}</component
+                >
+                <p v-if="description" class="pui-index__description">
+                    {{ description }}
+                </p>
+            </div>
+            <div v-if="$slots.actions" class="pui-index__actions">
+                <slot name="actions" :reload="reload" :loading="loading" />
+            </div>
+        </header>
+
+        <div class="pui-index__body">
+            <div
+                v-if="
+                    !invalidQuery &&
+                    (searchable || $slots.filters || queryOptions.sorts.length)
+                "
+                class="pui-index__toolbar"
+            >
+                <div v-if="searchable" class="pui-index__search">
+                    <TextInput
+                        type="search"
+                        :label="searchLabel"
+                        :placeholder="searchPlaceholder"
+                        :model-value="search"
+                        @update:model-value="setSearch"
+                    />
+                </div>
+                <slot
+                    name="filters"
+                    :filters="query.filters"
+                    :set-filters="setFilters"
+                    :set-filter="setFilter"
+                />
+                <div v-if="queryOptions.sorts.length" class="pui-index__sort">
+                    <Select
+                        :label="sortLabel"
+                        :aria-label="sortLabel"
+                        :model-value="formatSort(query.sort) ?? ''"
+                        :options="sortOptions"
+                        @update:model-value="
+                            updateCriteria({ sort: parseSort($event) })
+                        "
+                    />
+                </div>
+            </div>
+
+            <div class="pui-index__selection" role="status">
+                <slot
+                    v-if="selectable && selected.length && $slots.selection"
+                    name="selection"
+                    :selected="selected"
+                    :reload="reload"
+                    :loading="loading"
+                />
+            </div>
+
+            <div v-if="errors.length" class="pui-index__error">
+                <slot
+                    name="error"
+                    :error="error"
+                    :errors="errors"
+                    :retry="reload"
+                    :reset="reset"
+                    :invalid-query="invalidQuery"
+                >
+                    <Alert
+                        tone="danger"
+                        :title="
+                            invalidQuery
+                                ? 'This list query is invalid'
+                                : 'Could not load results'
+                        "
+                    >
+                        <ul>
+                            <li v-for="message in errors" :key="message">
+                                {{ message }}
+                            </li>
+                        </ul>
+                        <Button
+                            size="sm"
+                            @click="invalidQuery ? reset() : reload()"
+                            >{{
+                                invalidQuery ? 'Reset filters' : 'Try again'
+                            }}</Button
+                        >
+                    </Alert>
+                </slot>
+            </div>
+
+            <div v-if="showResults" class="pui-index__results">
+                <DataTable
+                    class="pui-index__table"
+                    :rows="rows"
+                    :columns="columns"
+                    :row-key="rowKey"
+                    :sort="query.sort"
+                    :loading="loading"
+                    :selectable="selectable"
+                    :selected="selected"
+                    :clickable="clickable"
+                    :label="title ? undefined : tableLabel"
+                    :labelledby="title ? titleId : undefined"
+                    @sort="
+                        updateCriteria({ sort: toggleSort(query.sort, $event) })
+                    "
+                    @update:selected="emit('update:selected', $event)"
+                    @row-click="emit('row-click', $event)"
+                >
+                    <template
+                        v-for="name in cellSlots"
+                        :key="name"
+                        #[name]="scope"
+                    >
+                        <slot :name="name" v-bind="scope" />
+                    </template>
+                    <template #empty
+                        ><slot name="empty">No results.</slot></template
+                    >
+                </DataTable>
+            </div>
+        </div>
+
+        <PaginationFooter v-if="showResults" class="pui-index__footer">
+            <template #summary>
+                <div class="pui-index__summary" role="status">
+                    <slot name="summary" :total="total" :from="from" :to="to">
+                        {{ from }}–{{ to }} of {{ total }}
+                    </slot>
+                </div>
+            </template>
+            <div class="pui-index__pagination">
+                <div v-if="pageSizes.length" class="pui-index__page-size">
+                    <Select
+                        :label="pageSizeLabel"
+                        :aria-label="pageSizeLabel"
+                        :model-value="String(query.page_size)"
+                        :options="pageSizeOptions"
+                        @update:model-value="
+                            updateCriteria({
+                                page_size: Number($event),
+                            })
+                        "
+                    />
+                </div>
+                <Pagination
+                    :current-page="query.page"
+                    :total-pages="totalPages"
+                    @update:current-page="setPage($event)"
+                />
+            </div>
+        </PaginationFooter>
+    </div>
+</template>
+
+<script setup lang="ts" generic="T extends object">
+import { computed, watch } from 'vue';
+import DataTable from '../table/DataTable.vue';
+import type { Column } from '../table/types.js';
+import TextInput from '../../form/text-input/TextInput.vue';
+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,
+} from '../../../utils/cms/index.js';
+import Button from '../../action/button/Button.vue';
+import { generateId } from '../../../utils/a11y/id.js';
+import { useIndex } from './useIndex.js';
+import {
+    formatSort,
+    parseSort,
+    toggleSort,
+} from '../../../utils/sort/index.js';
+
+const props = withDefaults(
+    defineProps<{
+        /** Returns the matching page using the shared backend response contract. */
+        load: ListLoader<T>;
+        columns: Column[];
+        queryOptions: QueryOptions;
+        /** `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`). */
+        syncQuery?: boolean | string;
+        /** Delay in milliseconds before committing typed search text. */
+        searchDebounce?: number;
+        title?: string;
+        description?: string;
+        /** Accessible name for the table when there is no `title` to reference. */
+        tableLabel?: string;
+        searchable?: boolean;
+        searchLabel?: string;
+        searchPlaceholder?: string;
+        sortLabel?: string;
+        /** Labels for sort keys, including fields without a visible column. */
+        sortLabels?: Record<string, string>;
+        /** An empty array hides the page-size control. */
+        pageSizes?: number[];
+        pageSizeLabel?: string;
+        rowKey?: string;
+        selectable?: boolean;
+        selected?: (string | number)[];
+        clickable?: boolean;
+    }>(),
+    {
+        placement: 'module',
+        syncQuery: false,
+        searchDebounce: 250,
+        title: undefined,
+        description: undefined,
+        tableLabel: undefined,
+        searchable: true,
+        searchLabel: 'Search',
+        searchPlaceholder: undefined,
+        sortLabel: 'Sort by',
+        sortLabels: () => ({}),
+        pageSizes: () => [10, 20, 50],
+        pageSizeLabel: 'Rows per page',
+        rowKey: 'id',
+        selectable: false,
+        selected: () => [],
+        clickable: false,
+    },
+);
+
+const emit = defineEmits<{
+    'update:selected': [keys: (string | number)[]];
+    'row-click': [row: T];
+}>();
+
+const slots = defineSlots<{
+    actions?: (scope: {
+        reload: () => Promise<void>;
+        loading: boolean;
+    }) => unknown;
+    filters?: (scope: {
+        filters: ListQuery['filters'];
+        setFilters: (filters: ListQuery['filters']) => void;
+        setFilter: (name: string, value: string | undefined) => void;
+    }) => unknown;
+    selection?: (scope: {
+        selected: (string | number)[];
+        reload: () => Promise<void>;
+        loading: boolean;
+    }) => unknown;
+    error?: (scope: {
+        error: ApiError | null;
+        errors: string[];
+        retry: () => Promise<void>;
+        reset: () => Promise<void>;
+        invalidQuery: boolean;
+    }) => unknown;
+    empty?: () => unknown;
+    summary?: (scope: { total: number; from: number; to: number }) => unknown;
+    [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) {
+        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);
+
+const {
+    query,
+    search,
+    rows,
+    meta,
+    loading,
+    error,
+    errors,
+    invalidQuery,
+    updateCriteria,
+    setSearch,
+    setPage,
+    setFilters,
+    setFilter,
+    reload,
+    reset,
+} = useIndex<T>(props);
+defineExpose({ reload });
+const titleId = generateId('index-title');
+const total = computed(() => meta.value.total);
+const showResults = computed(
+    () =>
+        !invalidQuery.value &&
+        (!errors.value.length || rows.value.length > 0 || loading.value),
+);
+const sortOptions = computed(() => [
+    { value: '', label: 'Default order' },
+    ...props.queryOptions.sorts.flatMap((key) => {
+        const label =
+            props.sortLabels[key] ??
+            props.columns.find((column) => column.key === key)?.label ??
+            key
+                .replaceAll('_', ' ')
+                .replace(/^./, (letter) => letter.toUpperCase());
+        return [
+            {
+                value: formatSort({ key, direction: 'asc' })!,
+                label: `${label} (ascending)`,
+            },
+            {
+                value: formatSort({ key, direction: 'desc' })!,
+                label: `${label} (descending)`,
+            },
+        ];
+    }),
+]);
+
+const cellSlots = computed(() =>
+    props.columns
+        .map((column) => `cell:${column.key}` as const)
+        .filter((name) => slots[name]),
+);
+const totalPages = computed(() =>
+    Math.max(1, Math.ceil(total.value / query.value.page_size)),
+);
+const from = computed(() =>
+    rows.value.length ? (meta.value.page - 1) * meta.value.page_size + 1 : 0,
+);
+const to = computed(() =>
+    rows.value.length
+        ? Math.min(total.value, from.value + rows.value.length - 1)
+        : 0,
+);
+const pageSizeOptions = computed(() =>
+    [...new Set([...props.pageSizes, query.value.page_size])]
+        .filter(
+            (size) =>
+                Number.isInteger(size) &&
+                size > 0 &&
+                size <= (props.queryOptions.maxPageSize ?? 100),
+        )
+        .sort((a, b) => a - b)
+        .map((size) => ({ value: String(size), label: String(size) })),
+);
+</script>
+
+<style>
+@import './index.css';
+</style>

package/components/layout/index/index.css

@@ -0,0 +1,157 @@
+@layer components {
+    .pui-index {
+        display: grid;
+        min-inline-size: 0;
+        gap: var(--space-s);
+        color: var(--text-clr-base);
+    }
+
+    .pui-index__header {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--space-s);
+        padding-block-end: var(--space-s);
+        border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
+    }
+
+    .pui-index__heading {
+        display: grid;
+        gap: var(--space-3xs);
+        min-inline-size: 0;
+    }
+
+    .pui-index__title {
+        margin: 0;
+        font-family: var(--ff-display);
+        font-size: var(--step-2);
+        font-weight: var(--fw-display);
+        letter-spacing: var(--ls-display);
+    }
+
+    .pui-index__description {
+        margin: 0;
+        font-size: var(--step--1);
+        color: var(--text-clr-muted);
+    }
+
+    .pui-index__actions,
+    .pui-index__selection {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--space-xs);
+    }
+
+    .pui-index__body {
+        min-inline-size: 0;
+    }
+
+    .pui-index__toolbar {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: end;
+        gap: var(--space-s);
+    }
+
+    .pui-index__search {
+        flex: 0 1 calc(var(--space-sidebar-width) * 1.5);
+        min-inline-size: min(100%, var(--space-sidebar-width));
+
+        @media (max-width: 48em) {
+            flex-grow: 1;
+        }
+    }
+
+    .pui-index__sort {
+        flex: 0 1 auto;
+        min-inline-size: 0;
+        max-inline-size: 100%;
+    }
+
+    .pui-index__results {
+        min-inline-size: 0;
+    }
+
+    .pui-index__table {
+        --pui-table-cell-padding-block: var(--space-2xs);
+    }
+
+    .pui-index__page-size > .pui-field {
+        display: flex;
+        align-items: center;
+        gap: var(--space-xs);
+
+        & > .pui-field__label {
+            white-space: nowrap;
+        }
+    }
+
+    .pui-index__pagination {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: end;
+        gap: var(--space-s);
+
+        & > .pui-pagination-nav {
+            flex: 1;
+        }
+    }
+
+    /* ===== placements ===== */
+
+    /* Module: flat in the page; the table keeps DataTable's own border. The
+       selection region is always rendered, so it spaces itself only when filled. */
+    .pui-index[data-placement='module'] {
+        & .pui-index__toolbar,
+        & .pui-index__selection:not(:empty),
+        & .pui-index__error {
+            margin-block-end: var(--space-s);
+        }
+
+        & .pui-index__body > :last-child {
+            margin-block-end: 0;
+        }
+    }
+
+    /* Related: one bordered region; header, toolbar, table and footer are its bands. */
+    .pui-index[data-placement='related'] {
+        gap: 0;
+        background: var(--bg-clr-surface);
+        border: var(--stroke-sm) solid var(--border-clr-subtle);
+        border-radius: var(--radius-md);
+
+        & > .pui-index__header {
+            padding: var(--space-s);
+        }
+
+        & .pui-index__title {
+            font-size: var(--step-1);
+            font-weight: var(--fw-semibold);
+            letter-spacing: normal;
+        }
+
+        & .pui-index__toolbar {
+            padding: var(--space-s);
+            border-block-end: var(--stroke-sm) solid var(--border-clr-subtle);
+        }
+
+        & .pui-index__selection:not(:empty),
+        & .pui-index__error {
+            padding: var(--space-s);
+        }
+
+        & .pui-index__table {
+            border: 0;
+            border-radius: 0;
+        }
+
+        & > .pui-index__footer {
+            border-block-start-color: var(--border-clr-subtle);
+            border-end-start-radius: inherit;
+            border-end-end-radius: inherit;
+        }
+    }
+}