@pienter/ui 0.3.0 → 0.7.1

package/README.md

@@ -1,20 +1,13 @@
 # @pienter/ui
 
-Shared Pienter UI package with framework-specific components, CSS, icons, and browser utilities.
+Shared Pienter UI package with Vue components, CSS, icons, and browser utilities.
 
-This package publishes raw source files. Consuming projects compile the Vue, Astro, TypeScript, and CSS files with their own toolchain.
+This package publishes raw source files. Consuming projects compile the Vue, TypeScript, and CSS files with their own toolchain.
 
 ## Install
 
 ```sh
-npm install @pienter/ui
-```
-
-Install the framework peer you use:
-
-```sh
-npm install vue
-npm install astro
+npm install @pienter/ui vue
 ```
 
 ## Usage
@@ -24,14 +17,6 @@ import Button from '@pienter/ui/components/Button.vue';
 import '@pienter/ui/styles';
 ```
 
-Astro components are available beside Vue components:
-
-```astro
----
-import Button from '@pienter/ui/components/Button.astro';
----
-```
-
 Components use explicit flat public entrypoints. Intentional shared types are
 available through module type entrypoints:
 
@@ -47,6 +32,36 @@ import { icons } from '@pienter/ui/icons';
 import { generateId } from '@pienter/ui/utils/a11y/id.js';
 ```
 
+### CMS pages
+
+Compose ordinary Vue routes with `Index`, `RecordForm`, and `RecordDetails`:
+
+```ts
+import Index from '@pienter/ui/components/Index.vue';
+import RecordForm from '@pienter/ui/components/RecordForm.vue';
+import RecordFields from '@pienter/ui/components/RecordFields.vue';
+import BlockEditor from '@pienter/ui/components/BlockEditor.vue';
+import RecordDetails from '@pienter/ui/components/RecordDetails.vue';
+import type { RecordFormField } from '@pienter/ui/components/RecordForm.types';
+import { decodeListQuery, encodeListQuery } from '@pienter/ui/utils/cms';
+```
+
+Index receives `load(query, { signal })`, columns and query options. It handles
+loading, search, pagination, errors and retry; `sync-query` enables Vue Router URL
+synchronization. Index requires the `vue-router` package; an installed router
+instance is needed only when synchronization is enabled. RecordForm receives `v-model`, fields and validation issues,
+emitting a JSON payload on `submit`. RecordDetails receives a record and fields.
+Use slots for custom cells, controls, values and actions. Your pages own route
+declarations, endpoint functions and saving. Use RecordForm’s `fields` slot and
+RecordFields to put groups in sidebars and tab panels while retaining one form.
+BlockEditor accepts `v-model`, block creation factories and a `block` slot; it
+provides drag-and-drop, keyboard movement, add/remove and collapse controls.
+
+The [CMS guide](../../docs/cms/README.md) contains working examples. The
+[backend contract](../../docs/cms/backend-contract.md) defines query parameters,
+response envelopes and validation paths; its JSON Schema ships at
+`@pienter/ui/utils/cms/schema.json`.
+
 ### Themes
 
 The default theme follows the operating-system color preference, using

package/components/display/record-details/RecordDetails.vue

@@ -0,0 +1,61 @@
+<script lang="ts">
+export type { RecordDetailsField } from './types.js';
+</script>
+
+<script setup lang="ts" generic="T extends object">
+import { readPath } from '../../../utils/cms/index.js';
+import type { RecordDetailsField } from './types.js';
+
+const props = withDefaults(
+    defineProps<{
+        record: T;
+        fields: readonly RecordDetailsField[];
+        emptyValue?: string;
+    }>(),
+    { emptyValue: '—' },
+);
+
+function valueFor(field: RecordDetailsField): unknown {
+    return readPath(props.record, field.path ?? [field.name]);
+}
+
+function displayValue(value: unknown): string {
+    if (value === undefined || value === null || value === '')
+        return props.emptyValue;
+    if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+    if (typeof value === 'object') return JSON.stringify(value);
+    return String(value);
+}
+</script>
+
+<template>
+    <div class="pui-record-details">
+        <dl class="pui-record-details__list">
+            <div
+                v-for="field in fields"
+                :key="field.name"
+                class="pui-record-details__field"
+            >
+                <dt class="pui-record-details__label">{{ field.label }}</dt>
+                <dd class="pui-record-details__value">
+                    <slot
+                        :name="`field:${field.name}`"
+                        :field="field"
+                        :value="valueFor(field)"
+                        :record="record"
+                    >
+                        {{ displayValue(valueFor(field)) }}
+                    </slot>
+                </dd>
+            </div>
+        </dl>
+        <slot />
+        <div v-if="$slots.actions" class="pui-record-details__actions">
+            <slot name="actions" :record="record" />
+        </div>
+    </div>
+</template>
+
+<style>
+@import './record-details.css';
+</style>

package/components/display/record-details/record-details.css

@@ -0,0 +1,37 @@
+@layer components {
+    .pui-record-details {
+        display: grid;
+        gap: var(--space-s);
+
+        & .pui-record-details__list {
+            display: grid;
+            margin: 0;
+        }
+
+        & .pui-record-details__field {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) minmax(0, 3fr);
+            gap: var(--space-s);
+            padding-block: var(--space-xs);
+            border-block-end: var(--stroke-sm) solid var(--border-clr-base);
+        }
+
+        & .pui-record-details__label {
+            color: var(--text-clr-dim);
+            font-size: var(--step--1);
+        }
+
+        & .pui-record-details__value {
+            margin: 0;
+            min-inline-size: 0;
+            overflow-wrap: anywhere;
+            white-space: pre-wrap;
+        }
+
+        & .pui-record-details__actions {
+            display: flex;
+            flex-wrap: wrap;
+            gap: var(--space-xs);
+        }
+    }
+}

package/components/display/record-details/types.ts

@@ -0,0 +1,8 @@
+import type { ValuePath } from '../../../utils/cms/index.js';
+
+export interface RecordDetailsField {
+    name: string;
+    label: string;
+    /** Defaults to the literal property name, without splitting dots. */
+    path?: ValuePath;
+}

package/components/feedback/toast/toast.css

@@ -9,7 +9,7 @@
         display: flex;
         flex-direction: column;
         gap: var(--space-2xs);
-        z-index: 1000;
+        z-index: var(--layer-top);
         pointer-events: none;
         max-width: calc(100vw - var(--space-s) * 2);
     }

package/components/form/block-editor/BlockEditor.vue

@@ -0,0 +1,454 @@
+<script lang="ts">
+export type { BlockType, ContentBlock, BlockPatch } from './types.js';
+</script>
+
+<script setup lang="ts" generic="T extends ContentBlock">
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue';
+import Button from '../../action/button/Button.vue';
+import IconButton from '../../action/button/IconButton.vue';
+import Icon from '../../display/icon/Icon.vue';
+import { announce } from '../../../utils/a11y/live-region.js';
+import { generateId } from '../../../utils/a11y/id.js';
+import type { BlockPatch, BlockType, ContentBlock } from './types.js';
+
+const props = withDefaults(
+    defineProps<{
+        modelValue: readonly T[];
+        blockTypes: readonly BlockType<T>[];
+        /** Optional controlled list of collapsed block ids. */
+        collapsed?: readonly string[];
+        disabled?: boolean;
+        label?: string;
+        blockLabel?: (block: T, index: number) => string;
+    }>(),
+    {
+        disabled: false,
+        collapsed: undefined,
+        label: 'Content blocks',
+        blockLabel: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:modelValue': [blocks: T[]];
+    'update:collapsed': [ids: string[]];
+}>();
+defineSlots<{
+    block: (scope: {
+        block: T;
+        index: number;
+        update: (patch: BlockPatch<T>) => void;
+        disabled: boolean;
+    }) => unknown;
+    summary?: (scope: { block: T; index: number }) => unknown;
+    empty?: () => unknown;
+}>();
+
+const id = generateId('blocks');
+const localCollapsed = ref<string[]>([]);
+const collapsed = computed(
+    () => new Set(props.collapsed ?? localCollapsed.value),
+);
+const dragging = ref<string>();
+const dropIndex = ref(0);
+const items = new Map<string, HTMLElement>();
+let gesture:
+    | {
+          id: string;
+          pointerId: number;
+          startX: number;
+          startY: number;
+          y: number;
+      }
+    | undefined;
+let pointerListeners: AbortController | undefined;
+let scrollFrame = 0;
+let scrollParent: HTMLElement | undefined;
+
+function setItem(key: string, element: HTMLElement | null) {
+    if (element) items.set(key, element);
+    else items.delete(key);
+}
+
+function typeLabel(block: T) {
+    return (
+        props.blockTypes.find((type) => type.type === block.type)?.label ??
+        block.type
+    );
+}
+
+function title(block: T, index: number) {
+    return props.blockLabel?.(block, index) || typeLabel(block);
+}
+
+function bodyId(block: T) {
+    return `${id}-${encodeURIComponent(block.id)}`;
+}
+
+function focusBlock(key: string) {
+    void nextTick(() =>
+        items
+            .get(key)
+            ?.querySelector<HTMLButtonElement>('[data-block-toggle]')
+            ?.focus(),
+    );
+}
+
+function add(type: BlockType<T>) {
+    if (props.disabled) return;
+    const block = type.create();
+    if (
+        !block.id ||
+        block.type !== type.type ||
+        props.modelValue.some((item) => item.id === block.id)
+    ) {
+        throw new TypeError(
+            'Block factories must return the requested type and a unique, non-empty id.',
+        );
+    }
+    emit('update:modelValue', [...props.modelValue, { ...block }]);
+    focusBlock(block.id);
+    announce(`${type.label} added. ${props.modelValue.length + 1} blocks.`);
+}
+
+function update(key: string, patch: BlockPatch<T>) {
+    if (props.disabled) return;
+    emit(
+        'update:modelValue',
+        props.modelValue.map((block) =>
+            block.id === key
+                ? { ...block, ...patch, id: block.id, type: block.type }
+                : block,
+        ),
+    );
+}
+
+function remove(key: string) {
+    if (props.disabled) return;
+    const index = props.modelValue.findIndex((block) => block.id === key);
+    const block = props.modelValue[index];
+    if (!block) return;
+    const remaining = props.modelValue.filter((block) => block.id !== key);
+    emit('update:modelValue', remaining);
+    setCollapsed([...collapsed.value].filter((id) => id !== key));
+    const next = remaining[Math.min(index, remaining.length - 1)];
+    if (next) focusBlock(next.id);
+    else
+        void nextTick(() =>
+            document
+                .getElementById(`${id}-add`)
+                ?.querySelector<HTMLButtonElement>('button')
+                ?.focus(),
+        );
+    announce(`${title(block, index)} removed. ${remaining.length} blocks.`);
+}
+
+function move(key: string, target: number) {
+    if (props.disabled) return;
+    const source = props.modelValue.findIndex((block) => block.id === key);
+    if (
+        source < 0 ||
+        target < 0 ||
+        target >= props.modelValue.length ||
+        source === target
+    )
+        return;
+    const blocks = [...props.modelValue];
+    const block = blocks.splice(source, 1)[0]!;
+    blocks.splice(target, 0, block);
+    emit('update:modelValue', blocks);
+    focusBlock(key);
+    announce(
+        `${title(block, source)} moved to position ${target + 1} of ${blocks.length}.`,
+    );
+}
+
+function toggle(key: string) {
+    if (props.disabled) return;
+    const next = new Set(collapsed.value);
+    if (next.has(key)) next.delete(key);
+    else next.add(key);
+    setCollapsed([...next]);
+}
+
+function setCollapsed(ids: string[]) {
+    if (props.collapsed === undefined) localCollapsed.value = ids;
+    emit('update:collapsed', ids);
+}
+
+const otherBlocks = computed(() =>
+    props.modelValue.filter((block) => block.id !== dragging.value),
+);
+function indicator(key: string) {
+    if (!dragging.value) return undefined;
+    if (otherBlocks.value[dropIndex.value]?.id === key) return 'before';
+    if (
+        dropIndex.value === otherBlocks.value.length &&
+        otherBlocks.value.at(-1)?.id === key
+    )
+        return 'after';
+    return undefined;
+}
+
+function locateDrop(y: number) {
+    dropIndex.value = otherBlocks.value.filter((block) => {
+        const rect = items.get(block.id)?.getBoundingClientRect();
+        return rect && y > rect.top + rect.height / 2;
+    }).length;
+}
+
+function autoScroll() {
+    if (!gesture || !dragging.value) return;
+    const bounds = scrollParent?.getBoundingClientRect();
+    const top = bounds?.top ?? 0;
+    const bottom = bounds?.bottom ?? window.innerHeight;
+    const delta = gesture.y < top + 48 ? -14 : gesture.y > bottom - 48 ? 14 : 0;
+    if (delta) {
+        if (scrollParent) scrollParent.scrollTop += delta;
+        else window.scrollBy(0, delta);
+        locateDrop(gesture.y);
+    }
+    scrollFrame = requestAnimationFrame(autoScroll);
+}
+
+function stopDrag() {
+    pointerListeners?.abort();
+    pointerListeners = undefined;
+    cancelAnimationFrame(scrollFrame);
+    gesture = undefined;
+    dragging.value = undefined;
+}
+
+function startDrag(event: PointerEvent, key: string) {
+    if (props.disabled || event.button !== 0 || props.modelValue.length < 2)
+        return;
+    stopDrag();
+    const handle = event.currentTarget as HTMLButtonElement;
+    handle.focus({ preventScroll: true });
+    gesture = {
+        id: key,
+        pointerId: event.pointerId,
+        startX: event.clientX,
+        startY: event.clientY,
+        y: event.clientY,
+    };
+    scrollParent = undefined;
+    for (
+        let parent = handle.parentElement;
+        parent;
+        parent = parent.parentElement
+    ) {
+        if (
+            /(auto|scroll)/.test(getComputedStyle(parent).overflowY) &&
+            parent.scrollHeight > parent.clientHeight
+        ) {
+            scrollParent = parent;
+            break;
+        }
+    }
+    try {
+        handle.setPointerCapture(event.pointerId);
+    } catch {
+        /* Synthetic pointer events have no capturable pointer. */
+    }
+    pointerListeners = new AbortController();
+    const options = { signal: pointerListeners.signal };
+    window.addEventListener('pointermove', dragMove, options);
+    window.addEventListener('pointerup', finishDrag, options);
+    window.addEventListener('pointercancel', stopDrag, options);
+    window.addEventListener('blur', stopDrag, options);
+    window.addEventListener('keydown', cancelWithEscape, options);
+    event.preventDefault();
+}
+
+function dragMove(event: PointerEvent) {
+    if (!gesture || event.pointerId !== gesture.pointerId) return;
+    gesture.y = event.clientY;
+    if (!dragging.value) {
+        if (
+            Math.hypot(
+                event.clientX - gesture.startX,
+                event.clientY - gesture.startY,
+            ) < 5
+        )
+            return;
+        dragging.value = gesture.id;
+        scrollFrame = requestAnimationFrame(autoScroll);
+    }
+    locateDrop(event.clientY);
+    event.preventDefault();
+}
+
+function finishDrag(event: PointerEvent) {
+    if (!gesture || event.pointerId !== gesture.pointerId) return;
+    const key = dragging.value;
+    const target = dropIndex.value;
+    stopDrag();
+    if (key) move(key, target);
+}
+
+function cancelWithEscape(event: KeyboardEvent) {
+    if (event.key === 'Escape' && gesture) {
+        event.preventDefault();
+        stopDrag();
+        announce('Reordering cancelled.');
+    }
+}
+
+watch(
+    () => props.disabled,
+    (disabled) => {
+        if (disabled) stopDrag();
+    },
+);
+watch(() => props.modelValue.map((block) => block.id).join('\u0000'), stopDrag);
+onBeforeUnmount(stopDrag);
+</script>
+
+<template>
+    <div
+        class="pui-block-editor"
+        :data-disabled="disabled ? 'true' : undefined"
+    >
+        <p :id="`${id}-hint`" class="pui-block-editor__hint">
+            Drag to reorder, or use the move buttons.
+        </p>
+        <ol
+            v-if="modelValue.length"
+            class="pui-block-editor__list"
+            :aria-label="label"
+            :aria-describedby="`${id}-hint`"
+        >
+            <li
+                v-for="(block, index) in modelValue"
+                :key="block.id"
+                :ref="
+                    (element) =>
+                        setItem(block.id, element as HTMLElement | null)
+                "
+                class="pui-block-editor__item"
+                :data-block-id="block.id"
+                :data-dragging="dragging === block.id ? 'true' : undefined"
+                :data-drop="indicator(block.id)"
+            >
+                <div class="pui-block-editor__header">
+                    <button
+                        class="pui-block-editor__drag"
+                        type="button"
+                        :disabled="disabled || modelValue.length < 2"
+                        :aria-label="`Drag ${title(block, index)}`"
+                        :aria-describedby="`${id}-hint`"
+                        @pointerdown="startDrag($event, block.id)"
+                    >
+                        <Icon name="arrow-up-down" size="sm" />
+                    </button>
+                    <div class="pui-block-editor__heading">
+                        <button
+                            type="button"
+                            class="pui-block-editor__toggle"
+                            data-block-toggle
+                            :disabled="disabled"
+                            :aria-label="`${collapsed.has(block.id) ? 'Expand' : 'Collapse'} ${title(block, index)}`"
+                            :aria-expanded="
+                                collapsed.has(block.id) ? 'false' : 'true'
+                            "
+                            :aria-controls="bodyId(block)"
+                            @click="toggle(block.id)"
+                        >
+                            <Icon
+                                :name="
+                                    collapsed.has(block.id)
+                                        ? 'chevron-right'
+                                        : 'chevron-down'
+                                "
+                                size="sm"
+                            />
+                            <span class="pui-block-editor__title">{{
+                                title(block, index)
+                            }}</span>
+                            <span
+                                v-if="title(block, index) !== typeLabel(block)"
+                                class="pui-block-editor__type"
+                                >{{ typeLabel(block) }}</span
+                            >
+                        </button>
+                        <div
+                            v-if="$slots.summary"
+                            class="pui-block-editor__summary"
+                        >
+                            <slot
+                                name="summary"
+                                :block="block"
+                                :index="index"
+                            />
+                        </div>
+                    </div>
+                    <div class="pui-block-editor__actions">
+                        <IconButton
+                            name="arrow-up"
+                            variant="ghost"
+                            size="sm"
+                            :label="`Move ${title(block, index)} up`"
+                            :disabled="disabled || index === 0"
+                            @click="move(block.id, index - 1)"
+                        />
+                        <IconButton
+                            name="arrow-down"
+                            variant="ghost"
+                            size="sm"
+                            :label="`Move ${title(block, index)} down`"
+                            :disabled="
+                                disabled || index === modelValue.length - 1
+                            "
+                            @click="move(block.id, index + 1)"
+                        />
+                        <IconButton
+                            name="trash-2"
+                            variant="ghost"
+                            size="sm"
+                            :label="`Remove ${title(block, index)}`"
+                            :disabled="disabled"
+                            @click="remove(block.id)"
+                        />
+                    </div>
+                </div>
+                <div
+                    :id="bodyId(block)"
+                    :hidden="collapsed.has(block.id)"
+                    class="pui-block-editor__body"
+                    :inert="disabled ? true : undefined"
+                >
+                    <slot
+                        name="block"
+                        :block="block"
+                        :index="index"
+                        :update="
+                            (patch: BlockPatch<T>) => update(block.id, patch)
+                        "
+                        :disabled="disabled"
+                    />
+                </div>
+            </li>
+        </ol>
+        <div v-else class="pui-block-editor__empty">
+            <slot name="empty"
+                >No blocks yet. Add a block to start writing.</slot
+            >
+        </div>
+        <div :id="`${id}-add`" class="pui-block-editor__add">
+            <Button
+                v-for="type in blockTypes"
+                :key="type.type"
+                icon="plus"
+                size="sm"
+                :disabled="disabled"
+                @click="add(type)"
+                >Add {{ type.label }}</Button
+            >
+        </div>
+    </div>
+</template>
+
+<style>
+@import './block-editor.css';
+</style>