@pienter/ui 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## Unreleased
 
+## 0.22.0 - 2026-09-16
+### Added
+
+- `RecordForm` tracks whether the record has unsaved edits. `baseline` is
+  the last saved state; without one the first `modelValue` the form sees
+  stands in, so a create form is clean until the first edit. `dirty` is a
+  structural comparison of `modelValue` against that baseline
+  (`isEqualRecord` in `utils/cms`, so key order does not matter), always
+  `false` in `readonly` mode, emitted as `update:dirty` for `v-model:dirty`
+  and exposed on the component instance. Consumers set `baseline` to a clone
+  of the model after load and after a successful save, before navigating.
+- `useUnsavedChanges(dirty)` (`@pienter/ui/composables/useUnsavedChanges`)
+  turns that flag into a leave guard: while dirty, `beforeunload` has the
+  browser confirm a reload or tab close, and a vue-router `onBeforeRouteLeave`
+  guard asks through `confirmLeave()`, which resolves `true` at once when
+  clean and otherwise raises `pending` until `resolve(leave)` answers it. The
+  consumer binds `pending` to an `AlertDialog` and answers with
+  `resolve(true)` on confirm, `resolve(false)` on cancel; a second question
+  while one is pending shares its promise. Requires the optional `vue-router`
+  peer dependency, like `useUrlTab`.
+## 0.21.1 - 2026-09-16
+### Fixed
+
+- `Sidebar` marks one entry `aria-current="page"` instead of every entry on
+  the current path. On `/pages/create` the "All pages" link (`/pages`), its
+  group row and "New page" (`/pages/create`) all reported themselves as the
+  current page, so a screen reader heard three current pages and both links
+  wore the brand wash. The hierarchical match is unchanged — it still
+  drives a group's `data-active` and expand-on-mount — but `aria-current` now
+  goes only to the longest matching href, and when a group row and one of its
+  child links share that href the link wins.
+
+## 0.21.0 - 2026-09-16
+
+### Added
+
+- `BlockEditor`'s drag handle is keyboard-operable and back in the tab
+  order. Space or Enter grabs a block (`aria-pressed`, `data-state="grabbed"`),
+  ArrowUp and ArrowDown move it one step through the same reorder the move
+  buttons use, Space or Enter drops it and Escape returns it to where it was
+  grabbed; blur while grabbed cancels too. Every step emits
+  `update:modelValue`, so the page sees the block move as it does with the
+  move buttons, and each grab, step, drop and cancel is announced through the
+  shared live region. The default `hint` now describes the keyboard pattern.
+  Pointer dragging is unchanged.
+
 ## 0.20.1 - 2026-09-16
 
 ### Fixed

package/CONVENTIONS.md

@@ -503,6 +503,17 @@ isActive(activeHref, itemHref):
 descendant items (recursively) is active. Sidebar uses this to expand
 the matching group on mount and to highlight the group header.
 
+**Rendering rule** (2026-09-16, issue #54): the match algorithm above is
+unchanged and still answers "is this item on the current page's path?"
+for every item. What it does _not_ decide is which entry renders
+`aria-current="page"`: that goes to the single longest matching href
+across the whole tree (`resolveCurrentHref`), so on `/pages/create` only
+"New page" (`/pages/create`) is current, while "All pages" (`/pages`) and
+its group keep their hierarchical match for `data-active` and
+expand-on-mount. When a group's own `href` and one of its direct child
+links share that longest href, the link is current and the group toggle
+is not.
+
 **Edge cases — out of scope for v1**, documented for future:
 
 - Trailing slashes are NOT normalized (`/admin/members/` vs

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

@@ -39,7 +39,7 @@ const props = withDefaults(
         level: 3,
         blockLabel: undefined,
         addLabel: (typeLabel: string) => `Add ${typeLabel}`,
-        hint: 'Use the move buttons to reorder, or drag with a pointer.',
+        hint: 'Use the move buttons to reorder, or drag with a pointer. On a drag handle, Space grabs the block, the arrow keys move it, Space drops it and Escape cancels.',
         emptyText: 'No blocks yet. Add a block to start writing.',
     },
 );
@@ -68,6 +68,9 @@ const collapsed = computed(
 );
 const dragging = ref<string>();
 const dropIndex = ref(0);
+const grabbed = ref<string>();
+let grabbedFrom = 0;
+let stepping = false;
 const items = new Map<string, HTMLElement>();
 let gesture:
     | {
@@ -160,7 +163,7 @@ function remove(key: string) {
     announce(`${title(block, index)} removed. ${remaining.length} blocks.`);
 }
 
-function move(key: string, target: number) {
+function reorder(key: string, target: number) {
     if (locked.value) return;
     const source = props.modelValue.findIndex((block) => block.id === key);
     if (
@@ -174,12 +177,116 @@ function move(key: string, target: number) {
     const block = blocks.splice(source, 1)[0]!;
     blocks.splice(target, 0, block);
     emit('update:modelValue', blocks);
+    return { block, source, blocks };
+}
+
+function move(key: string, target: number) {
+    const moved = reorder(key, target);
+    if (!moved) return;
     focusBlock(key);
     announce(
-        `${title(block, source)} moved to position ${target + 1} of ${blocks.length}.`,
+        `${title(moved.block, moved.source)} moved to position ${target + 1} of ${moved.blocks.length}.`,
+    );
+}
+
+function focusHandle(key: string) {
+    items
+        .get(key)
+        ?.querySelector<HTMLButtonElement>('.pui-block-editor__drag')
+        ?.focus({ preventScroll: true });
+}
+
+function position(key: string) {
+    const index = props.modelValue.findIndex((block) => block.id === key);
+    const block = props.modelValue[index];
+    return block
+        ? {
+              index,
+              name: title(block, index),
+              place: `position ${index + 1} of ${props.modelValue.length}`,
+          }
+        : undefined;
+}
+
+function grab(key: string) {
+    const at = position(key);
+    if (!at || props.modelValue.length < 2) return;
+    grabbed.value = key;
+    grabbedFrom = at.index;
+    announce(
+        `Grabbed ${at.name}, ${at.place}. Use arrow keys to move, Space to drop, Escape to cancel.`,
     );
 }
 
+function step(key: string, delta: -1 | 1) {
+    const at = position(key);
+    if (!at) return;
+    const target = at.index + delta;
+    if (target < 0 || target >= props.modelValue.length) {
+        announce(
+            `${at.name} cannot move further ${delta < 0 ? 'up' : 'down'}.`,
+        );
+        return;
+    }
+    // Vue moves the `<li>` in the DOM, which blurs the handle; that blur is not a cancel.
+    stepping = true;
+    reorder(key, target);
+    void nextTick(() => {
+        focusHandle(key);
+        stepping = false;
+    });
+    announce(
+        `${at.name} moved to position ${target + 1} of ${props.modelValue.length}.`,
+    );
+}
+
+function drop(key: string) {
+    const at = position(key);
+    grabbed.value = undefined;
+    if (at) announce(`Dropped ${at.name}, ${at.place}.`);
+}
+
+function cancelGrab() {
+    const key = grabbed.value;
+    if (!key) return;
+    grabbed.value = undefined;
+    stepping = true;
+    reorder(key, grabbedFrom);
+    void nextTick(() => {
+        stepping = false;
+    });
+    announce('Reordering cancelled.');
+}
+
+function handleKey(event: KeyboardEvent, key: string) {
+    if (locked.value) return;
+    const held = grabbed.value === key;
+    switch (event.key) {
+        case ' ':
+        case 'Enter':
+            event.preventDefault();
+            if (held) drop(key);
+            else grab(key);
+            return;
+        case 'ArrowUp':
+        case 'ArrowDown':
+            if (!held) return;
+            event.preventDefault();
+            step(key, event.key === 'ArrowUp' ? -1 : 1);
+            return;
+        case 'Escape':
+            if (!held) return;
+            event.preventDefault();
+            event.stopPropagation();
+            cancelGrab();
+            return;
+    }
+}
+
+function handleBlur(key: string) {
+    if (!stepping && grabbed.value === key) cancelGrab();
+}
+
 function toggle(key: string) {
     if (props.disabled) return;
     const next = new Set(collapsed.value);
@@ -240,6 +347,7 @@ function startDrag(event: PointerEvent, key: string) {
     if (locked.value || event.button !== 0 || props.modelValue.length < 2)
         return;
     stopDrag();
+    grabbed.value = undefined;
     const handle = event.currentTarget as HTMLButtonElement;
     handle.focus({ preventScroll: true });
     gesture = {
@@ -313,9 +421,22 @@ function cancelWithEscape(event: KeyboardEvent) {
 }
 
 watch(locked, (value) => {
-    if (value) stopDrag();
+    if (value) {
+        stopDrag();
+        grabbed.value = undefined;
+    }
 });
-watch(() => props.modelValue.map((block) => block.id).join('\u0000'), stopDrag);
+watch(
+    () => props.modelValue.map((block) => block.id).join('\u0000'),
+    () => {
+        stopDrag();
+        if (
+            grabbed.value &&
+            !props.modelValue.some((block) => block.id === grabbed.value)
+        )
+            grabbed.value = undefined;
+    },
+);
 onBeforeUnmount(stopDrag);
 </script>
 
@@ -343,7 +464,11 @@ onBeforeUnmount(stopDrag);
                 "
                 class="pui-block-editor__item"
                 :data-block-id="block.id"
-                :data-dragging="dragging === block.id ? 'true' : undefined"
+                :data-dragging="
+                    dragging === block.id || grabbed === block.id
+                        ? 'true'
+                        : undefined
+                "
                 :data-drop="indicator(block.id)"
             >
                 <div class="pui-block-editor__header">
@@ -351,11 +476,16 @@ onBeforeUnmount(stopDrag);
                         v-if="!readonly"
                         class="pui-block-editor__drag"
                         type="button"
-                        tabindex="-1"
                         :disabled="disabled || modelValue.length < 2"
                         :aria-label="`Drag ${title(block, index)}`"
                         :aria-describedby="`${id}-hint`"
+                        :aria-pressed="grabbed === block.id ? 'true' : 'false'"
+                        :data-state="
+                            grabbed === block.id ? 'grabbed' : undefined
+                        "
                         @pointerdown="startDrag($event, block.id)"
+                        @keydown="handleKey($event, block.id)"
+                        @blur="handleBlur(block.id)"
                     >
                         <Icon name="arrow-up-down" size="sm" />
                     </button>

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

@@ -3,12 +3,13 @@ export type { RecordFormField } from './types.js';
 </script>
 
 <script setup lang="ts" generic="T extends object">
-import { computed } from 'vue';
+import { computed, watch } from 'vue';
 import Button from '../../action/button/Button.vue';
 import Form from '../form/Form.vue';
 import RecordFields from './RecordFields.vue';
 import {
     cloneRecord,
+    isEqualRecord,
     type ValidationIssue,
     type ValuePath,
 } from '../../../utils/cms/index.js';
@@ -19,6 +20,8 @@ const props = withDefaults(
     defineProps<{
         /** Caller-owned write payload; every supplied property is retained. */
         modelValue: T;
+        /** Last saved state `dirty` compares against; defaults to the first `modelValue` seen. */
+        baseline?: T;
         fields: readonly RecordFormField[];
         issues?: readonly ValidationIssue[];
         errors?: string[];
@@ -29,6 +32,7 @@ const props = withDefaults(
         statusMessage?: string;
     }>(),
     {
+        baseline: undefined,
         issues: () => [],
         errors: () => [],
         busy: false,
@@ -40,10 +44,20 @@ const props = withDefaults(
 
 const emit = defineEmits<{
     'update:modelValue': [value: T];
+    'update:dirty': [value: boolean];
     'field-change': [path: ValuePath];
     submit: [value: T];
 }>();
 
+const initial = cloneRecord(props.modelValue);
+const dirty = computed(
+    () =>
+        !props.readonly &&
+        !isEqualRecord(props.modelValue, props.baseline ?? initial),
+);
+watch(dirty, (value) => emit('update:dirty', value), { immediate: true });
+defineExpose({ dirty });
+
 const fieldErrors = computed(() =>
     Object.fromEntries(
         props.fields.map((field) => [

package/components/navigation/sidebar/Sidebar.vue

@@ -70,6 +70,7 @@ import {
     computeSubmenuPosition,
     deriveGroupKey,
     isSubmenuActive,
+    resolveCurrentHref,
     SUBMENU_CLOSE_DELAY,
     type SubmenuPosition,
 } from '../../../utils/navigation/sidebar.js';
@@ -266,8 +267,16 @@ function onEntryEnter(topLevelKey: string | null): void {
     if (!pinned.value) scheduleClose();
 }
 
+const currentHref = computed(() =>
+    resolveCurrentHref(
+        [...props.topItems, ...props.bottomItems],
+        props.activeHref,
+    ),
+);
+
 provide(SIDEBAR_CONTEXT, {
     activeHref: computed(() => props.activeHref),
+    currentHref,
     expandedKeys,
     openKey,
     submenuActive,

package/components/navigation/sidebar/SidebarMenuItem.vue

@@ -110,7 +110,6 @@ import { generateId } from '../../../utils/a11y/id.js';
 import {
     deriveGroupKey,
     groupContainsActive,
-    isHrefActive,
 } from '../../../utils/navigation/sidebar.js';
 import { SIDEBAR_CONTEXT } from './context.js';
 import type { SidebarItem } from './types.js';
@@ -144,13 +143,15 @@ const ownKey = computed(() =>
 );
 
 const isCurrent = computed(() => {
-    const href =
-        props.item.type === 'link'
-            ? props.item.href
-            : props.item.type === 'group'
-              ? props.item.href
-              : undefined;
-    return href !== undefined && isHrefActive(ctx.activeHref.value, href);
+    if (props.item.type === 'section') return false;
+    const href = props.item.href;
+    if (href === undefined || href !== ctx.currentHref.value) return false;
+    // A group whose own child link repeats its href: the link is the page.
+    if (props.item.type === 'group')
+        return !props.item.items.some(
+            (child) => child.type === 'link' && child.href === href,
+        );
+    return true;
 });
 
 const containsCurrent = computed(

package/components/navigation/sidebar/context.ts

@@ -4,6 +4,8 @@ import type { SubmenuPosition } from '../../../utils/navigation/sidebar.js';
 /** What `Sidebar.vue` hands down to the recursive `SidebarMenuItem`. */
 export interface SidebarContext {
     activeHref: ComputedRef<string | null>;
+    /** The one href that renders `aria-current`; see `resolveCurrentHref`. */
+    currentHref: ComputedRef<string | undefined>;
     expandedKeys: Ref<Set<string>>;
     /** Group key whose collapsed-rail flyout is open, or null. */
     openKey: Ref<string | null>;

package/composables/useUnsavedChanges.ts

@@ -0,0 +1,57 @@
+import { ref, toValue, type MaybeRefOrGetter, type Ref } from 'vue';
+import { onBeforeRouteLeave } from 'vue-router';
+import { useWindowListener } from './useEventListener.js';
+
+export interface UnsavedChanges {
+    /** `true` while a leave is waiting on an answer. Bind to `AlertDialog`'s `open`. */
+    pending: Ref<boolean>;
+    /** Resolves `true` at once when clean; otherwise asks and resolves with the answer. */
+    confirmLeave: () => Promise<boolean>;
+    /** Answers the pending question: `resolve(true)` on confirm, `resolve(false)` on cancel. */
+    resolve: (leave: boolean) => void;
+}
+
+/**
+ * Guards a dirty form against leaving unsaved. Bind `dirty` to `RecordForm`'s
+ * `v-model:dirty`. While dirty, a `beforeunload` listener has the browser confirm
+ * a reload or tab close, and a route-leave guard asks through `confirmLeave()`,
+ * which the consumer answers from an `AlertDialog` bound to `pending` and
+ * `resolve`. One question at a time: a second `confirmLeave()` while pending
+ * returns the same promise. Requires the optional `vue-router` peer dependency.
+ */
+export function useUnsavedChanges(
+    dirty: MaybeRefOrGetter<boolean>,
+): UnsavedChanges {
+    const pending = ref(false);
+    let question: {
+        promise: Promise<boolean>;
+        settle: (leave: boolean) => void;
+    } | null = null;
+
+    useWindowListener('beforeunload', (event) => {
+        if (toValue(dirty)) event.preventDefault();
+    });
+
+    function confirmLeave(): Promise<boolean> {
+        if (!toValue(dirty)) return Promise.resolve(true);
+        if (question) return question.promise;
+        let settle!: (leave: boolean) => void;
+        const promise = new Promise<boolean>((resolve) => {
+            settle = resolve;
+        });
+        question = { promise, settle };
+        pending.value = true;
+        return promise;
+    }
+
+    function resolve(leave: boolean): void {
+        const current = question;
+        question = null;
+        pending.value = false;
+        current?.settle(leave);
+    }
+
+    onBeforeRouteLeave(() => confirmLeave());
+
+    return { pending, confirmLeave, resolve };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pienter/ui",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "description": "Shared Pienter UI components, styles, icons, and browser utilities.",
   "type": "module",
   "license": "MIT",
@@ -92,6 +92,7 @@
     "./composables/usePopover": "./composables/usePopover.ts",
     "./composables/useUrlSort": "./composables/useUrlSort.ts",
     "./composables/useUrlTab": "./composables/useUrlTab.ts",
+    "./composables/useUnsavedChanges": "./composables/useUnsavedChanges.ts",
     "./icons": "./icons/index.ts",
     "./icons/*": "./icons/*",
     "./utils": "./utils/index.ts",

package/utils/cms/index.ts

@@ -222,6 +222,36 @@ export function cloneRecord<T>(record: T): T {
     return JSON.parse(JSON.stringify(record)) as T;
 }
 
+/** Structural equality of two JSON-shaped records; key order and `undefined` properties do not count. */
+export function isEqualRecord(a: unknown, b: unknown): boolean {
+    if (a === b) return true;
+    if (
+        a === null ||
+        b === null ||
+        typeof a !== 'object' ||
+        typeof b !== 'object' ||
+        Array.isArray(a) !== Array.isArray(b)
+    )
+        return false;
+    if (Array.isArray(a) && Array.isArray(b))
+        return (
+            a.length === b.length &&
+            a.every((item, index) => isEqualRecord(item, b[index]))
+        );
+    const left = a as Record<string, unknown>;
+    const right = b as Record<string, unknown>;
+    const keys = Object.keys(left).filter((key) => left[key] !== undefined);
+    const other = Object.keys(right).filter((key) => right[key] !== undefined);
+    return (
+        keys.length === other.length &&
+        keys.every(
+            (key) =>
+                Object.hasOwn(right, key) &&
+                isEqualRecord(left[key], right[key]),
+        )
+    );
+}
+
 export function readPath(record: unknown, path: ValuePath): unknown {
     let value = record;
     for (const key of path) {

package/utils/navigation/sidebar.ts

@@ -90,8 +90,35 @@ export function groupContainsActive(
     });
 }
 
+/**
+ * The single href that renders `aria-current="page"`: the longest one the
+ * current page matches, so `/pages/create` lights up "New page" and not
+ * "All pages" (`/pages`) as well. See CONVENTIONS.md § Rendering rule.
+ */
+export function resolveCurrentHref(
+    items: readonly SidebarItemLike[],
+    activeHref: string | null | undefined,
+): string | undefined {
+    let current: string | undefined;
+    const visit = (list: readonly SidebarItemLike[]): void => {
+        for (const item of list) {
+            if (item.type === 'section') continue;
+            const href = item.href;
+            if (
+                href !== undefined &&
+                isHrefActive(activeHref, href) &&
+                (current === undefined || href.length > current.length)
+            )
+                current = href;
+            if (item.type === 'group') visit(item.items);
+        }
+    };
+    visit(items);
+    return current;
+}
+
 /** The part of `SidebarItem` these primitives read; avoids a component import. */
 export type SidebarItemLike =
     | { type: 'link'; href: string }
-    | { type: 'group'; items: readonly SidebarItemLike[] }
+    | { type: 'group'; href?: string; items: readonly SidebarItemLike[] }
     | { type: 'section' };