@pienter/ui 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 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/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.9.0",
   "description": "Shared Pienter UI components, styles, icons, and browser utilities.",
   "type": "module",
   "license": "MIT",
@@ -87,6 +87,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],
+    };
+}