@pienter/ui 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-09-15
+
+### Changed
+
+- Index renders its title, description and actions through the new
+  `PageHeader`, so the `pui-index__header`, `pui-index__heading`,
+  `pui-index__title`, `pui-index__description` and `pui-index__actions`
+  classes are gone. They were never documented as public API; a consumer
+  style that targeted them moves to `pui-page-header` and its
+  `__heading`, `__title`, `__description` and `__actions` elements. Markup,
+  spacing and type are unchanged in both placements.
+
+### Added
+
+- `PageHeader` at `@pienter/ui/components/PageHeader.vue`: the title,
+  description and actions band above a module index or a record page,
+  extracted from Index so detail and form pages no longer hand-roll the same
+  header. `title` and `description` are plain strings, `level` (`1` | `2` |
+  `3`, default `1`) picks the heading element and sizes levels 2 and 3 as
+  section headings, `title-id` sets the title's `id` for `aria-labelledby`,
+  and `#actions` fills the trailing row. It renders nothing when it has no
+  title, description or actions. Index uses it at level 1 in module placement
+  and level 2 in related placement.
+
+## 0.9.0 - 2026-09-15
+
+### Added
+
+- `useUrlTab(keys, defaultKey, param = 'tab')` at
+  `@pienter/ui/composables/useUrlTab` keeps the active `Tabs` key in the URL
+  query, the single source of truth, so a shared link or a reload opens the
+  same tab. It returns a writable computed for `v-model`: the default key
+  drops the parameter, an unknown value falls back to it, and writes go
+  through `router.replace` so tab switches stay out of the back stack and
+  other query parameters survive. Requires the optional `vue-router` peer,
+  like `useUrlSort`.
+- `formFailure(cause, fallback)` in `@pienter/ui/utils/cms` turns a caught
+  save error into RecordForm's `{ issues, errors }`: a value carrying the
+  `ErrorResponse` envelope contributes its field issues and leaves `errors`
+  empty; otherwise `errors` holds the caught `Error` message or `fallback`.
+
 ## 0.8.0 - 2026-09-15
 
 ### Breaking

package/README.md

@@ -92,6 +92,10 @@ declarations, endpoint functions and saving. Use RecordForm’s `fields` slot an
 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.
+`useUrlTab` from `@pienter/ui/composables/useUrlTab` keeps the active tab key in
+the query string for `v-model` on Tabs, and `formFailure(cause, fallback)` from
+`@pienter/ui/utils/cms` turns a caught save error into RecordForm's `issues` and
+`errors`.
 
 The [CMS guide](../../docs/cms/README.md) contains working examples. The
 [backend contract](../../docs/cms/backend-contract.md) defines query parameters,

package/components/layout/index/Index.vue

@@ -4,26 +4,16 @@
         :data-placement="placement"
         :data-state="loading ? 'loading' : undefined"
     >
-        <header
-            v-if="title || description || $slots.actions"
-            class="pui-index__header"
+        <PageHeader
+            :title="title"
+            :description="description"
+            :level="placement === 'related' ? 2 : 1"
+            :title-id="titleId"
         >
-            <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">
+            <template v-if="$slots.actions" #actions>
                 <slot name="actions" :reload="reload" :loading="loading" />
-            </div>
-        </header>
+            </template>
+        </PageHeader>
 
         <div class="pui-index__body">
             <div
@@ -172,6 +162,7 @@
 <script setup lang="ts" generic="T extends object">
 import { computed, watch } from 'vue';
 import DataTable from '../table/DataTable.vue';
+import PageHeader from '../page-header/PageHeader.vue';
 import type { Column } from '../table/types.js';
 import TextInput from '../../form/text-input/TextInput.vue';
 import Select from '../../form/select/Select.vue';

package/components/layout/index/index.css

@@ -6,37 +6,6 @@
         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;
@@ -123,16 +92,10 @@
         border: var(--stroke-sm) solid var(--border-clr-subtle);
         border-radius: var(--radius-md);
 
-        & > .pui-index__header {
+        & > .pui-page-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);

package/components/layout/page-header/PageHeader.vue

@@ -0,0 +1,49 @@
+<template>
+    <header
+        v-if="title || description || $slots.actions"
+        class="pui-page-header"
+    >
+        <div v-if="title || description" class="pui-page-header__heading">
+            <component
+                :is="`h${level}`"
+                v-if="title"
+                :id="titleId"
+                class="pui-page-header__title"
+                >{{ title }}</component
+            >
+            <p v-if="description" class="pui-page-header__description">
+                {{ description }}
+            </p>
+        </div>
+        <div v-if="$slots.actions" class="pui-page-header__actions">
+            <slot name="actions" />
+        </div>
+    </header>
+</template>
+
+<script setup lang="ts">
+withDefaults(
+    defineProps<{
+        title?: string;
+        description?: string;
+        /** Heading level of the title: `1` for a page, `2` or `3` for a band inside one. */
+        level?: 1 | 2 | 3;
+        /** `id` for the title element, so a region can reference it through `aria-labelledby`. */
+        titleId?: string;
+    }>(),
+    {
+        title: undefined,
+        description: undefined,
+        level: 1,
+        titleId: undefined,
+    },
+);
+
+defineSlots<{
+    actions?: () => unknown;
+}>();
+</script>
+
+<style>
+@import './page-header.css';
+</style>

package/components/layout/page-header/page-header.css

@@ -0,0 +1,44 @@
+@layer components {
+    .pui-page-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-page-header__heading {
+        display: grid;
+        gap: var(--space-3xs);
+        min-inline-size: 0;
+    }
+
+    .pui-page-header__title {
+        margin: 0;
+        font-family: var(--ff-display);
+        font-size: var(--step-2);
+        font-weight: var(--fw-display);
+        letter-spacing: var(--ls-display);
+
+        &:is(h2, h3) {
+            font-size: var(--step-1);
+            font-weight: var(--fw-semibold);
+            letter-spacing: normal;
+        }
+    }
+
+    .pui-page-header__description {
+        margin: 0;
+        font-size: var(--step--1);
+        color: var(--text-clr-muted);
+    }
+
+    .pui-page-header__actions {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--space-xs);
+    }
+}

package/composables/useUrlTab.ts

@@ -0,0 +1,38 @@
+import { computed, type WritableComputedRef } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+
+/**
+ * Keeps the active `Tabs` key in the URL query, the single source of truth, so a shared
+ * link or a reload opens the same tab. Bind with `v-model`. The default key drops the
+ * parameter and an unknown value falls back to it; writes go through `router.replace`,
+ * so tab switches stay out of the back stack and other query parameters survive.
+ * Requires the optional `vue-router` peer dependency.
+ *
+ * @param keys - the tab keys the view renders.
+ * @param defaultKey - key used when the parameter is absent or unknown.
+ * @param param - query parameter name; defaults to `'tab'`.
+ */
+export function useUrlTab(
+    keys: readonly string[],
+    defaultKey: string,
+    param = 'tab',
+): WritableComputedRef<string> {
+    const route = useRoute();
+    const router = useRouter();
+
+    return computed<string>({
+        get: () => {
+            const raw = route.query[param];
+            const value = Array.isArray(raw) ? raw[0] : raw;
+            return typeof value === 'string' && keys.includes(value)
+                ? value
+                : defaultKey;
+        },
+        set: (key) => {
+            const query = { ...route.query };
+            if (key === defaultKey) delete query[param];
+            else query[param] = key;
+            void router.replace({ query });
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pienter/ui",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Shared Pienter UI components, styles, icons, and browser utilities.",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,7 @@
     "./components/Card.vue": "./components/layout/card/Card.vue",
     "./components/Collapsible.vue": "./components/layout/collapsible/Collapsible.vue",
     "./components/AppLayout.vue": "./components/layout/app-layout/AppLayout.vue",
+    "./components/PageHeader.vue": "./components/layout/page-header/PageHeader.vue",
     "./components/Separator.vue": "./components/layout/separator/Separator.vue",
     "./components/Table.vue": "./components/layout/table/Table.vue",
     "./components/TableRow.vue": "./components/layout/table/TableRow.vue",
@@ -87,6 +88,7 @@
     "./composables/useMenu": "./composables/useMenu.ts",
     "./composables/usePopover": "./composables/usePopover.ts",
     "./composables/useUrlSort": "./composables/useUrlSort.ts",
+    "./composables/useUrlTab": "./composables/useUrlTab.ts",
     "./icons": "./icons/index.ts",
     "./icons/*": "./icons/*",
     "./utils": "./utils/index.ts",

package/utils/cms/index.ts

@@ -281,3 +281,24 @@ export function errorsFor(
         )
         .flatMap((issue) => issue.messages);
 }
+
+export interface FormFailure {
+    issues: ValidationIssue[];
+    errors: string[];
+}
+
+/**
+ * Turns a failed save into RecordForm's `issues` and `errors` props. A caught value
+ * carrying the `ErrorResponse` envelope (`{ error: ApiError }`) contributes its field
+ * issues; without issues, `errors` holds the caught `Error` message, falling back to
+ * `fallback`.
+ */
+export function formFailure(cause: unknown, fallback: string): FormFailure {
+    const error = (cause as Partial<ErrorResponse> | null | undefined)?.error;
+    const issues = Array.isArray(error?.issues) ? error.issues : [];
+    if (issues.length) return { issues, errors: [] };
+    return {
+        issues: [],
+        errors: [cause instanceof Error ? cause.message : fallback],
+    };
+}