@pienter/ui 0.5.0 → 0.7.1

package/components/form/number-field/NumberField.vue

@@ -146,7 +146,6 @@ function handleStep(direction: 'decrement' | 'increment'): void {
     // listeners observe stepper clicks the same as typed edits.
     input.dispatchEvent(new Event('input', { bubbles: true }));
     input.dispatchEvent(new Event('change', { bubbles: true }));
-    emit('update:modelValue', input.valueAsNumber);
 }
 </script>
 

package/components/form/record-form/RecordFields.vue

@@ -0,0 +1,128 @@
+<script lang="ts">
+export type { RecordFormField } from './types.js';
+</script>
+
+<script setup lang="ts" generic="T extends object">
+import { computed } from 'vue';
+import TextInput from '../text-input/TextInput.vue';
+import PuiTextarea from '../textarea/Textarea.vue';
+import PuiSelect from '../select/Select.vue';
+import Checkbox from '../checkbox/Checkbox.vue';
+import {
+    readPath,
+    updatePath,
+    type ValidationIssue,
+    type ValuePath,
+} from '../../../utils/cms/index.js';
+import type { RecordFormField } from './types.js';
+import { pathFor, messagesFor } from './fields.js';
+
+const props = withDefaults(
+    defineProps<{
+        modelValue: T;
+        fields: readonly RecordFormField[];
+        issues?: readonly ValidationIssue[];
+        busy?: boolean;
+    }>(),
+    { issues: () => [], busy: false },
+);
+const emit = defineEmits<{
+    'update:modelValue': [value: T];
+    'field-change': [path: ValuePath];
+}>();
+const fieldsWithErrors = computed(() =>
+    props.fields.map((field) => ({
+        field,
+        errors: messagesFor(field, props.issues),
+    })),
+);
+
+function valueFor(field: RecordFormField): unknown {
+    return readPath(props.modelValue, pathFor(field));
+}
+function textFor(field: RecordFormField): string {
+    const value = valueFor(field);
+    return typeof value === 'string' ? value : '';
+}
+function update(field: RecordFormField, value: unknown): void {
+    if (props.busy || field.disabled) return;
+    const path = pathFor(field);
+    emit('update:modelValue', updatePath(props.modelValue, path, value));
+    emit('field-change', path);
+}
+</script>
+
+<template>
+    <div class="pui-record-fields">
+        <template
+            v-for="{ field, errors } in fieldsWithErrors"
+            :key="field.name"
+        >
+            <slot name="before-field" :field="field" />
+            <slot
+                :name="`field:${field.name}`"
+                :field="field"
+                :value="valueFor(field)"
+                :update="(value: unknown) => update(field, value)"
+                :errors="errors"
+                :disabled="busy || !!field.disabled"
+            >
+                <PuiTextarea
+                    v-if="field.type === 'textarea'"
+                    :label="field.label"
+                    :name="JSON.stringify(pathFor(field))"
+                    :model-value="textFor(field)"
+                    :hint="field.hint"
+                    :required="field.required"
+                    :disabled="busy || field.disabled"
+                    :placeholder="field.placeholder"
+                    :rows="field.rows"
+                    :errors="errors"
+                    @update:model-value="update(field, $event)"
+                />
+                <PuiSelect
+                    v-else-if="field.type === 'select'"
+                    :label="field.label"
+                    :name="JSON.stringify(pathFor(field))"
+                    :model-value="textFor(field)"
+                    :hint="field.hint"
+                    :required="field.required"
+                    :disabled="busy || field.disabled"
+                    :placeholder="field.placeholder"
+                    :options="field.options"
+                    :errors="errors"
+                    @update:model-value="update(field, $event)"
+                />
+                <Checkbox
+                    v-else-if="field.type === 'checkbox'"
+                    :label="field.label"
+                    :name="JSON.stringify(pathFor(field))"
+                    :model-value="valueFor(field) === true"
+                    :hint="field.hint"
+                    :required="field.required"
+                    :disabled="busy || field.disabled"
+                    :errors="errors"
+                    @update:model-value="update(field, $event)"
+                />
+                <TextInput
+                    v-else-if="field.type !== 'custom'"
+                    :label="field.label"
+                    :name="JSON.stringify(pathFor(field))"
+                    :model-value="textFor(field)"
+                    :type="field.type ?? 'text'"
+                    :hint="field.hint"
+                    :required="field.required"
+                    :disabled="busy || field.disabled"
+                    :placeholder="field.placeholder"
+                    :autocomplete="field.autocomplete"
+                    :errors="errors"
+                    @update:model-value="update(field, $event)"
+                />
+            </slot>
+        </template>
+    </div>
+</template>
+
+<style>
+@import './record-form.css';
+</style>

package/components/form/record-form/RecordForm.vue

@@ -0,0 +1,116 @@
+<script lang="ts">
+export type { RecordFormField } from './types.js';
+</script>
+
+<script setup lang="ts" generic="T extends object">
+import { computed } from 'vue';
+import Button from '../../action/button/Button.vue';
+import Form from '../form/Form.vue';
+import RecordFields from './RecordFields.vue';
+import {
+    cloneRecord,
+    type ValidationIssue,
+    type ValuePath,
+} from '../../../utils/cms/index.js';
+import { pathFor, containsPath, messagesFor } from './fields.js';
+import type { RecordFormField } from './types.js';
+
+const props = withDefaults(
+    defineProps<{
+        /** Caller-owned write payload; every supplied property is retained. */
+        modelValue: T;
+        fields: readonly RecordFormField[];
+        issues?: readonly ValidationIssue[];
+        errors?: string[];
+        busy?: boolean;
+        submitLabel?: string;
+        statusMessage?: string;
+    }>(),
+    {
+        issues: () => [],
+        errors: () => [],
+        busy: false,
+        submitLabel: 'Save changes',
+        statusMessage: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:modelValue': [value: T];
+    'field-change': [path: ValuePath];
+    submit: [value: T];
+}>();
+
+const fieldErrors = computed(() =>
+    Object.fromEntries(
+        props.fields.map((field) => [
+            JSON.stringify(pathFor(field)),
+            messagesFor(field, props.issues),
+        ]),
+    ),
+);
+
+const summary = computed(() => [
+    ...props.errors,
+    ...props.issues.flatMap((issue) => {
+        const field = props.fields.find((field) =>
+            containsPath(pathFor(field), issue.path),
+        );
+        const label = field?.label ?? issue.path.join(' / ');
+        return issue.messages.map((message) =>
+            label ? `${label}: ${message}` : message,
+        );
+    }),
+]);
+
+function submit(): void {
+    if (!props.busy) emit('submit', cloneRecord(props.modelValue));
+}
+</script>
+
+<template>
+    <Form
+        class="pui-record-form"
+        :busy="busy"
+        :errors="summary"
+        :field-errors="fieldErrors"
+        :status-message="statusMessage"
+        @submit="submit"
+    >
+        <slot name="fields">
+            <RecordFields
+                class="pui-record-form__fields"
+                :model-value="modelValue"
+                :fields="fields"
+                :issues="issues"
+                :busy="busy"
+                @update:model-value="emit('update:modelValue', $event)"
+                @field-change="emit('field-change', $event)"
+            >
+                <template
+                    v-for="name in Object.keys($slots).filter(
+                        (name) =>
+                            name === 'before-field' ||
+                            name.startsWith('field:'),
+                    )"
+                    :key="name"
+                    #[name]="scope"
+                >
+                    <slot :name="name" v-bind="scope" />
+                </template>
+            </RecordFields>
+        </slot>
+        <slot />
+        <template #actions>
+            <slot name="actions" :busy="busy">
+                <Button type="submit" variant="primary" :loading="busy">
+                    {{ submitLabel }}
+                </Button>
+            </slot>
+        </template>
+    </Form>
+</template>
+
+<style>
+@import './record-form.css';
+</style>

package/components/form/record-form/fields.ts

@@ -0,0 +1,20 @@
+import type { ValidationIssue, ValuePath } from '../../../utils/cms/index.js';
+import type { RecordFormField } from './types.js';
+
+export function pathFor(field: RecordFormField): ValuePath {
+    return field.path ?? [field.name];
+}
+export function containsPath(parent: ValuePath, child: ValuePath): boolean {
+    return (
+        parent.length <= child.length &&
+        parent.every((part, index) => part === child[index])
+    );
+}
+export function messagesFor(
+    field: RecordFormField,
+    issues: readonly ValidationIssue[],
+): string[] {
+    return issues
+        .filter((issue) => containsPath(pathFor(field), issue.path))
+        .flatMap((issue) => issue.messages);
+}

package/components/form/record-form/record-form.css

@@ -0,0 +1,15 @@
+@layer components {
+    .pui-record-form {
+        gap: var(--space-s);
+    }
+
+    .pui-record-fields {
+        display: grid;
+        grid-template-columns: var(
+            --pui-record-fields-columns,
+            var(--pui-record-form-columns, minmax(0, 1fr))
+        );
+        gap: var(--space-s);
+        min-inline-size: 0;
+    }
+}

package/components/form/record-form/types.ts

@@ -0,0 +1,28 @@
+import type { ValuePath } from '../../../utils/cms/index.js';
+
+interface RecordFieldBase {
+    name: string;
+    label: string;
+    /** Defaults to the literal property name, without splitting dots. */
+    path?: ValuePath;
+    hint?: string;
+    required?: boolean;
+    disabled?: boolean;
+}
+
+export type RecordFormField = RecordFieldBase &
+    (
+        | {
+              type?: 'text' | 'email';
+              placeholder?: string;
+              autocomplete?: string;
+          }
+        | { type: 'textarea'; placeholder?: string; rows?: number }
+        | {
+              type: 'select';
+              options: { value: string; label: string }[];
+              placeholder?: string;
+          }
+        | { type: 'checkbox' }
+        | { type: 'custom' }
+    );

package/components/form/text-input/text-input.css

@@ -16,6 +16,7 @@
 
     .pui-field {
         display: grid;
+        align-content: start;
         gap: var(--space-2xs);
     }
 
@@ -59,6 +60,7 @@
     }
 
     .pui-field__label {
+        margin-block: 0;
         font-size: var(--step--1);
         font-weight: var(--fw-bold);
     }

package/components/layout/index/Index.vue

@@ -0,0 +1,353 @@
+<template>
+    <div class="pui-index" :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">
+                <h1 v-if="title" class="pui-index__title">{{ title }}</h1>
+                <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
+                v-if="selectable && selected.length && $slots.selection"
+                class="pui-index__selection"
+            >
+                <slot
+                    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"
+                    @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>
+                <slot name="summary" :total="total" :from="from" :to="to">
+                    {{ from }}–{{ to }} of {{ total }}
+                </slot>
+            </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 { 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;
+        /** Synchronize list parameters with the current Vue Router route. */
+        syncQuery?: boolean;
+        /** Delay in milliseconds before committing typed search text. */
+        searchDebounce?: number;
+        title?: string;
+        description?: 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;
+    }>(),
+    {
+        syncQuery: false,
+        searchDebounce: 250,
+        title: undefined,
+        description: 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 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>