@michaelthielemann/kestrel 1.2.1

package/layers/admin/app/components/SingletonEditor.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+// A proper editor for a single-record (singleton) collection — the same header-driven chrome as the
+// record editor, minus list/new/delete. The header carries the title and a Save button that submits the
+// CollectionEditor's form by id; `saving`/`dirty` come from the editor's exposed state.
+import type { EditorExpose } from '../utils/editor-expose'
+
+const props = defineProps<{ collection: string; title: string; localeParam?: string }>()
+
+const { t } = useT()
+const toast = useToast()
+
+const EDITOR_FORM_ID = 'singleton-editor'
+const editorRef = ref<EditorExpose | null>(null)
+const saving = computed(() => editorRef.value?.saving ?? false)
+
+function onSaved() {
+  toast.success(t('toast.saved'))
+}
+
+function openPreview() {
+  const url = editorRef.value?.previewUrl
+  if (url) window.open(url, '_blank', 'noopener,noreferrer')
+}
+
+// Guard in-app navigation away from unsaved changes — both record-change AND same-record `?locale`
+// switches (the LocaleBar's singleton locale switch reuses this route record → onBeforeRouteUpdate).
+// The editor itself guards native unload.
+useUnsavedGuard(() => editorRef.value?.dirty ?? false, () => t('editor.discardConfirm'))
+</script>
+
+<template>
+  <section class="singleton">
+    <div class="singleton__head">
+      <h1 class="singleton__title">{{ title }}</h1>
+      <div class="singleton__actions">
+        <UiButton type="button" variant="ghost" size="sm" icon="undo" :disabled="saving || !editorRef?.canUndo" :title="t('history.undo')" :aria-label="t('history.undo')" @click="editorRef?.undo()" />
+        <UiButton type="button" variant="ghost" size="sm" icon="redo" :disabled="saving || !editorRef?.canRedo" :title="t('history.redo')" :aria-label="t('history.redo')" @click="editorRef?.redo()" />
+        <UiButton v-if="editorRef?.previewUrl" type="button" variant="ghost" size="sm" icon="external-link" :title="t('editor.openInNewTab')" :aria-label="t('editor.openInNewTab')" @click="openPreview" />
+        <UiButton type="submit" :form="EDITOR_FORM_ID" variant="primary" size="sm" icon="check" :loading="saving">{{ t('common.save') }}</UiButton>
+        <EditorStatus class="singleton__ampel" :dirty="editorRef?.dirty ?? false" :saving="saving" :has-status="editorRef?.hasStatus ?? false" :status="editorRef?.status" :saved-status="editorRef?.savedStatus" :page-like="editorRef?.pageLike ?? false" :live="editorRef?.live" />
+      </div>
+    </div>
+    <CollectionEditor
+      ref="editorRef"
+      :collection="collection"
+      id="single"
+      :form-id="EDITOR_FORM_ID"
+      :locale-param="localeParam"
+      :actions="false"
+      @saved="onSaved"
+    />
+  </section>
+</template>
+
+<style lang="scss">
+// The singleton shell stays fixed and fills the height handed down; the editor body (.editor__flat /
+// .editor3) owns the scroll — same model as the record editor (see the admin layout).
+.singleton {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: hidden;
+
+  // Fixed header; the fields scroll below it, so it needs no sticky positioning (matching .record__head).
+  &__head {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-4);
+    padding-bottom: var(--space-3);
+    border-bottom: 1px solid var(--color-border);
+  }
+  &__title {
+    font-size: var(--text-xl);
+    font-weight: var(--weight-bold);
+    text-transform: capitalize;
+  }
+  &__actions {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+  }
+  &__ampel {
+    margin-inline-start: var(--space-1);
+    padding-inline-start: var(--space-3);
+    border-inline-start: 1px solid var(--color-border);
+  }
+}
+</style>

package/layers/admin/app/composables/useAuth.ts

@@ -0,0 +1,68 @@
+interface AuthState {
+  authenticated: boolean
+  exp: number | null
+  checked: boolean
+}
+
+export function useAuth() {
+  const state = useState<AuthState>('kestrel-auth', () => ({
+    authenticated: false,
+    exp: null,
+    checked: false,
+  }))
+
+  const expired = () => state.value.exp !== null && state.value.exp <= Date.now()
+
+  async function checkSession() {
+    // Fail closed: a transient session-endpoint failure (5xx, offline) must read as
+    // "not authenticated" so the route guard redirects to login instead of throwing an error page.
+    try {
+      const r = await $fetch<{ authenticated: boolean; exp?: number }>('/api/auth/session')
+      state.value = { authenticated: r.authenticated, exp: r.exp ?? null, checked: true }
+    } catch {
+      state.value = { authenticated: false, exp: null, checked: true }
+    }
+    return state.value.authenticated
+  }
+
+  async function ensureSession() {
+    if (!state.value.checked || expired()) await checkSession()
+    return state.value.authenticated && !expired()
+  }
+
+  async function login(password: string) {
+    const r = await $fetch<{ ok: true; exp: number }>('/api/auth/login', {
+      method: 'POST',
+      body: { password },
+    })
+    state.value = { authenticated: true, exp: r.exp, checked: true }
+    return r
+  }
+
+  /** Drop the local session without a server round-trip — used by the re-auth interceptor on a 401. */
+  function reset() {
+    state.value = { authenticated: false, exp: null, checked: true }
+  }
+
+  async function logout() {
+    // The desired end state is "logged out" regardless of the response: an expired/rotated
+    // session makes the guarded logout endpoint 401, but the local session is still cleared.
+    try {
+      await $fetch('/api/auth/logout', { method: 'POST' })
+    } catch {
+      // already invalid server-side — nothing to clear there
+    }
+    state.value = { authenticated: false, exp: null, checked: true }
+    await navigateTo('/admin/login')
+  }
+
+  return {
+    authenticated: computed(() => state.value.authenticated && !expired()),
+    exp: computed(() => state.value.exp),
+    checkSession,
+    ensureSession,
+    login,
+    logout,
+    reset,
+  }
+}

package/layers/admin/app/composables/useBlockTree.ts

@@ -0,0 +1,95 @@
+import { ref, computed } from 'vue'
+import type { Ref } from 'vue'
+import { useEchoGuard } from '../../../ui/app/composables/useEchoGuard'
+import type { SerializedBlock } from '../../../core/server/utils/serialize-collection'
+import {
+  type BlockRow,
+  findInTree,
+  updatePropById,
+  removeById,
+  removalRetarget,
+  moveById,
+  duplicateById,
+  addBlock,
+} from '../utils/block-tree'
+
+/**
+ * Reactive state for the 3-pane block editor: one nested `content` tree plus a single shared selection
+ * (the stable `block.id`, or `null` for the page root). The tree pane and the fields pane both drive
+ * the same instance — the tree selects + does structural ops, the fields pane edits the selected
+ * block's props. Every mutation is id-addressed and immutable (see `block-tree.ts`) and re-emits the
+ * whole array (so `useEditForm`'s `setField('content', …)` reconciliation still runs). `genId` is
+ * injectable for deterministic tests; defaults to `crypto.randomUUID` (the server requires a non-empty id).
+ */
+export function useBlockTree(
+  model: Ref<unknown[] | null | undefined>,
+  schemas: Ref<Record<string, SerializedBlock>>,
+  genId: () => string = () => crypto.randomUUID(),
+  // Routes an emit through the caller's own undo-history capture point instead of a plain `model.value =`
+  // assignment, tagged with a per-op coalesce key (see `emit`) — so a structural op landing inside another
+  // edit's coalesce window (e.g. a delete right after typing) still gets its own undo step.
+  setContent?: (value: unknown[], coalesceAs: string) => void,
+) {
+  // JSON round-trip (not structuredClone — which throws on Vue reactive proxies): reads through the
+  // proxy into detached plain objects. Block content is JSON by definition, so this is lossless here.
+  const clone = (v: unknown): BlockRow[] => (Array.isArray(v) ? (JSON.parse(JSON.stringify(v)) as BlockRow[]) : [])
+
+  const blocks = ref<BlockRow[]>(clone(model.value))
+  const selectedId = ref<string | null>(null)
+
+  function emit(coalesceAs: string): void {
+    if (setContent) setContent(blocks.value, coalesceAs)
+    else model.value = blocks.value
+  }
+
+  // Echo-guard against the tree's OWN emit (shared primitive): an external change (load / locale copy /
+  // undo / redo) differs from the current tree, so it reseeds and drops a now-missing selection to root.
+  useEchoGuard(model, () => blocks.value, (v) => {
+    blocks.value = clone(v)
+    if (selectedId.value !== null && !findInTree(blocks.value, selectedId.value)) selectedId.value = null
+  }, [])
+
+  const selectedBlock = computed<BlockRow | null>(() =>
+    selectedId.value === null ? null : (findInTree(blocks.value, selectedId.value)?.block ?? null),
+  )
+
+  function select(id: string | null): void {
+    selectedId.value = id
+  }
+
+  function setProp(id: string, key: string, value: unknown): void {
+    blocks.value = updatePropById(blocks.value, id, key, value)
+    // Coalesces a typing burst into that one field, same as an ordinary text field would.
+    emit(`content:prop:${id}:${key}`)
+  }
+
+  function remove(id: string): void {
+    const retarget = removalRetarget(blocks.value, id)
+    blocks.value = removeById(blocks.value, id)
+    // Heal the selection whenever it no longer exists — covers removing the selected block itself AND
+    // removing an ANCESTOR of it (the whole subtree goes); land on the removed block's sibling/parent.
+    if (selectedId.value !== null && !findInTree(blocks.value, selectedId.value)) selectedId.value = retarget
+    emit(`content:remove:${id}`)
+  }
+
+  function move(id: string, dir: -1 | 1): void {
+    blocks.value = moveById(blocks.value, id, dir)
+    emit(`content:move:${id}`)
+  }
+
+  function duplicate(id: string): void {
+    const { tree, newId } = duplicateById(blocks.value, id, genId)
+    blocks.value = tree
+    selectedId.value = newId
+    emit(`content:duplicate:${id}`)
+  }
+
+  function add(parentId: string | null, slotName: string | null, type: string): void {
+    const { tree, newId } = addBlock(blocks.value, parentId, slotName, type, schemas.value, genId)
+    blocks.value = tree
+    selectedId.value = newId
+    emit(`content:add:${parentId}:${slotName}:${type}`)
+  }
+
+  return { blocks, selectedId, selectedBlock, select, setProp, remove, move, duplicate, add }
+}

package/layers/admin/app/composables/useBlocks.ts

@@ -0,0 +1,7 @@
+import type { SerializedBlock } from '../../../core/server/utils/serialize-collection'
+
+// Thin wrapper over the shared cached-resource loader; keeps the named `blocks` return.
+export function useBlocks() {
+  const { state: blocks, load } = useCachedResource<SerializedBlock>('kestrel-blocks', '/api/blocks')
+  return { blocks, load }
+}

package/layers/admin/app/composables/useCachedResource.ts

@@ -0,0 +1,35 @@
+// Generic cached-resource loader: a `useState`-backed list that fetches once and is shared by every
+// caller. Backs `useBlocks` / `useCollections` (structurally identical loaders).
+//
+// SSR isolation: the in-flight (dedup) promise is keyed first by the per-request Nuxt app (a WeakMap,
+// so it can't leak across SSR requests) AND then by `stateKey` — otherwise two different resources
+// loading concurrently in ONE request would share a single promise and cross-contaminate (one
+// resolves with the other's data).
+const inflight = new WeakMap<object, Map<string, Promise<unknown>>>()
+
+export function useCachedResource<T>(stateKey: string, url: string) {
+  const state = useState<T[] | null>(stateKey, () => null)
+  const nuxtApp = useNuxtApp()
+
+  async function load(): Promise<T[]> {
+    if (state.value) return state.value
+    let perApp = inflight.get(nuxtApp)
+    if (!perApp) {
+      perApp = new Map()
+      inflight.set(nuxtApp, perApp)
+    }
+    let pending = perApp.get(stateKey) as Promise<T[]> | undefined
+    if (!pending) {
+      pending = $fetch<{ data: T[] }>(url)
+        .then(({ data }) => {
+          state.value = data
+          return data
+        })
+        .finally(() => perApp!.delete(stateKey))
+      perApp.set(stateKey, pending)
+    }
+    return pending
+  }
+
+  return { state, load }
+}

package/layers/admin/app/composables/useCollectionOps.ts

@@ -0,0 +1,53 @@
+import { ref, toValue, type MaybeRefOrGetter } from 'vue'
+import { buildDeleteReport, type BatchAction, type BatchDeleteReport, type BulkResult, type ReferrerCounts } from '../utils/collection-ops'
+
+/**
+ * Client orchestration for the collection batch operations — ONE module, two entry points: a row action
+ * passes a single id, the bulk bar passes many. Every mutating call hits the one command endpoint
+ * (`POST /api/{collection}/bulk`); the server does the batching, the client never loops N requests.
+ * Mirrors media/useMediaOps (busy/error + an onChanged refetch hook).
+ */
+export function useCollectionOps(collection: MaybeRefOrGetter<string>, onChanged?: () => void | Promise<void>) {
+  const { t } = useT()
+  const busy = ref(false)
+  const error = ref<string | null>(null)
+  const name = () => toValue(collection)
+
+  async function bulk(action: BatchAction, ids: number[]): Promise<BulkResult> {
+    busy.value = true
+    error.value = null
+    try {
+      const res = await $fetch<BulkResult>(`/api/${name()}/bulk`, { method: 'POST', body: { action, ids } })
+      await onChanged?.()
+      return res
+    } catch (e) {
+      error.value = (e as { statusMessage?: string })?.statusMessage ?? t('list.opFailed')
+      throw e
+    } finally {
+      busy.value = false
+    }
+  }
+
+  /** Read-only pre-delete summary (referrer aggregate). Best-effort: sets `error` and rethrows on failure
+   *  so the caller can decide whether to still proceed (deletion is not blocked on the warning lookup). */
+  async function previewDelete(ids: number[]): Promise<BatchDeleteReport> {
+    error.value = null
+    try {
+      const res = await $fetch<ReferrerCounts>('/api/references/referrers', { query: { collection: name(), ids: ids.join(',') } })
+      // The endpoint flags whether the index lookup ran; carry that through rather than inferring safety from
+      // an empty `counts`. A missing body is indeterminate too — it is no evidence that nothing links here.
+      return buildDeleteReport(ids, res?.counts ?? {}, res != null && res.checked !== false)
+    } catch (e) {
+      error.value = (e as { statusMessage?: string })?.statusMessage ?? t('list.refCheckFailed')
+      throw e
+    }
+  }
+
+  const confirmDelete = (ids: number[]) => bulk('delete', ids)
+  const duplicate = (ids: number[]) => bulk('duplicate', ids)
+  /** Persist a new status; the server's write pipeline (emitWrite) turns that into a publish/unpublish. */
+  const setStatus = (ids: number[], status: 'published' | 'draft') =>
+    bulk(status === 'published' ? 'publish' : 'unpublish', ids)
+
+  return { busy, error, previewDelete, confirmDelete, duplicate, setStatus }
+}

package/layers/admin/app/composables/useCollections.ts

@@ -0,0 +1,7 @@
+import type { SerializedCollection } from '../../../core/server/utils/serialize-collection'
+
+// Thin wrapper over the shared cached-resource loader; keeps the named `collections` return.
+export function useCollections() {
+  const { state: collections, load } = useCachedResource<SerializedCollection>('kestrel-collections', '/api/collections')
+  return { collections, load }
+}

package/layers/admin/app/composables/useContentLocales.ts

@@ -0,0 +1,23 @@
+export interface ContentLocales {
+  /** Website/content locales (NOT the admin-UI language) — what the editor LocaleBar offers. */
+  locales: string[]
+  primary: string
+  /** Whether the primary locale is prefixed in public URLs too (`/en/about`); the `localePath` flag. */
+  prefixPrimary: boolean
+}
+
+/** Resolve the configured content locales from a `runtimeConfig.public`-shaped object. Pure, so the
+ *  fallback/primary logic is unit-testable without a Nuxt context. The `['en']` fallback is a safe
+ *  last resort for an absent/empty config (nuxt.config always sets `public.locales`): primary-only is
+ *  a safer guess than assuming a second locale exists, so it intentionally differs from the server's
+ *  `['en','de']` *default* (which applies only when KESTREL_LOCALES itself is unset). */
+export function pickContentLocales(pub: { locales?: unknown; primaryLocale?: unknown; prefixPrimary?: unknown }): ContentLocales {
+  const locales = Array.isArray(pub.locales) && pub.locales.length ? pub.locales.map(String) : ['en']
+  const primary =
+    typeof pub.primaryLocale === 'string' && locales.includes(pub.primaryLocale) ? pub.primaryLocale : locales[0]!
+  return { locales, primary, prefixPrimary: pub.prefixPrimary === true }
+}
+
+export function useContentLocales(): ContentLocales {
+  return pickContentLocales(useRuntimeConfig().public as { locales?: unknown; primaryLocale?: unknown; prefixPrimary?: unknown })
+}