@pienter/ui 0.5.0 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 ## Unreleased
 
+## 0.7.1 - 2026-09-15
+
+### Changed
+
+- RecordFields reuses field error arrays while draft values change, avoiding
+  repeated issue scans and unnecessary error-prop updates during typing.
+
+- Sidebar and Tabs skip navigation DOM scans for unrelated key presses; Sidebar
+  also handles Space activation before collecting visible entries.
+
+- Menus initialize roving focus with one enabled-item search and avoid repeating
+  full tabindex updates when keyboard navigation triggers a focus event.
+
+- NumberField stepper clicks emit one model update while preserving native input
+  and change events, so consumer validation and autosave handlers run once.
+
+## 0.7.0 - 2026-09-15
+
+### Changed
+
+- Index preserves structured backend errors and offers reset for rejected queries.
+  Refresh callbacks wait for navigation and loading to settle. Sortable columns
+  are checked against the endpoint's allowed fields before loading.
+
+- `Breadcrumb` is now a bar with an optional `actions` slot on the
+  inline-end side. The `pui-breadcrumb` block class moved from the `<ol>`
+  to the `<nav>`; the list is `pui-breadcrumb__trail`.
+- Index renders its pagination footer as a page-level band after the
+  results card instead of inside it, mirroring the header. Pages can pin
+  it to the viewport bottom; consumer styles targeting the footer's card
+  corner radii no longer apply.
+
+### Added
+
+- Index's sort select shares state with table headers and supports allowed fields
+  without visible columns. Sort labels can be customized independently of columns.
+- Individual filter updates and refresh/loading access in Index action and
+  selection slots reduce consumer wiring.
+- `normalizeListQuery` validates structured query state directly, without a URL
+  encoding round trip.
+
+## 0.6.0 - 2026-09-11
+
+### Changed
+
+- CMS surfaces use softer decorative borders and a lower-contrast canvas; the block editor no longer sits inside a second card. New `--bg-clr-canvas` and `--border-clr-subtle` semantic tokens leave control, text and focus contrast intact.
+- Form validation focuses a visible, enabled invalid control, including when other errors are in hidden tab panels.
+- Index separates page headings and actions from a bordered search, filter and results surface.
+- Compact CMS layouts use tighter table rows and inline pagination controls. Form fields no longer double label spacing or stretch controls beside hints.
+
+### Added
+
+- `RecordFields` and RecordForm’s `fields` slot for sidebar and tabbed layouts within one form; Tabs items can supply panel IDs and relationships.
+- `BlockEditor` for typed content blocks, with model updates, app-provided fields/factories, pointer drag-and-drop, keyboard movement, add/remove and controlled collapse.
+- `Breadcrumb` link slot for router links and `RecordForm` before-field slot for headings and other content between fields.
+- `Index`, `RecordForm`, and `RecordDetails` components for CMS pages composed with ordinary Vue routes, props, events, and slots. Index accepts an async loader and owns query state, debounced search, loading, retry, stale-request protection and optional Vue Router query synchronization.
+- Backend query and response types, JSON Schema, URL query codecs, and immutable record path helpers under `@pienter/ui/utils/cms`.
+
 ## 0.5.0 - 2026-08-30
 
 ### Breaking

package/CONVENTIONS.md

@@ -1409,3 +1409,48 @@ Pinned upstream SHAs used across the table:
 | toggle        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle/src                      | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
 | toggle-group  | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle-group.tsx    | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle-group/src                | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
 | tooltip       | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/tooltip.tsx         | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/tooltip/src                     | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+
+## CMS page composition
+
+`Index`, `RecordForm`, and `RecordDetails` compose existing primitives. Consumers
+register routes and supply endpoint-specific data functions, rendering and actions.
+
+Index accepts `load(query, { signal })`, `columns` and `queryOptions`. It owns
+query state, rows, metadata, loading, failures and retry. Search is debounced;
+search/filter/sort/page-size changes reset page to 1. New requests and unmount
+abort earlier work; stale responses are ignored even when loaders ignore the signal.
+`sync-query` opts into Vue Router query decoding and history synchronization.
+Without it, state stays local. Index imports the optional `vue-router` peer, but
+requires an installed router instance only for URL synchronization.
+
+Index applies the existing default sort cycle; Table/DataTable still emit a column
+key as intent, per ADR 0005. A toolbar select shares that sort state and includes
+all allowed fields, including those without visible columns. Sortable columns
+must belong to the allowed sort vocabulary; labels may be overridden with
+`sortLabels`. Filter slots can update one key without replacing siblings. Action
+and selection slots receive loading state and an awaitable refresh callback.
+Structured backend query errors offer reset; other load failures offer retry.
+Use DataTable when the consumer needs controlled data
+and request state. Index's compact row spacing uses
+`--pui-table-cell-padding-block`, which Table otherwise defaults to `--space-xs`.
+
+RecordForm emits detached JSON snapshots, preserving every supplied property.
+Consumers construct an explicit writable object from backend records. Typed path
+segments identify nested fields and array indices; fields display issues for
+their path and descendants. The form summary retains unmatched issues.
+`--pui-record-form-columns` customizes the field grid, defaulting to one column.
+
+RecordForm's `fields` slot replaces its default RecordFields rendering for
+custom sidebar/tab layouts. RecordFields takes the same draft and renders a
+subset, with `--pui-record-fields-columns` as its grid seam. It never renders a
+form element. Callers expose the relevant tab when backend issues arrive.
+
+BlockEditor owns an ordered array of stable `id`/`type` blocks and emits updates
+for edits, addition, removal and reordering. Creation factories and slot content
+stay caller-owned. Optional `v-model:collapsed` lets pages reveal invalid blocks.
+Its colocated audit records pointer, keyboard, focus and cancellation behavior.
+
+The backend contract lives in `docs/cms/backend-contract.md` with a distributable
+JSON Schema at `utils/cms/schema.json`. It defines request/response data only;
+endpoint URLs, authentication, permissions and domain operations belong to the
+application.

package/README.md

@@ -32,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;
+}