@michaelthielemann/kestrel 2.0.0 → 3.0.0

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

@@ -3,7 +3,7 @@ import type { FieldDef } from '../../../core/server/utils/defineCollection'
 import type { LayoutNode } from '../../../core/server/utils/field-layout'
 import type { SeoMeta } from '../../../core/server/utils/seo'
 
-// The collection (page) field list — delegates to the shared <FieldLayout> renderer (rows / groups /
+// The collection (page) field list — delegates to the shared <KestrelFieldLayout> renderer (rows / groups /
 // widths, or one field per row when the collection declares no layout), shared by the flat-collection
 // form and the 3-pane editor's root-selected pane so the wiring lives in exactly one place. pageLike
 // collections also get their routable `path` (slug); seo-enabled ones get the SEO section — both as
@@ -30,6 +30,10 @@ const { t } = useT()
 const layoutOptions = computed(() => layoutSelectOptions(useOfferableLayouts(), t('pageSettings.layoutDefault')))
 const showLayout = computed(() => !!props.pageLike && layoutOptions.value.length > 1)
 
+// Article metadata is an installation-wide policy (`kestrel.seo.articleMeta`), not a per-collection one,
+// so it comes from runtimeConfig rather than the serialized collection schema.
+const articleMeta = computed(() => (useRuntimeConfig().public as { seoArticleMeta?: boolean }).seoArticleMeta === true)
+
 // Live preview of the slug the server will auto-generate from the title while the field is left blank
 // (the server slugifies the title on save). Falls back to '/' when there is no title yet.
 const slugPlaceholder = computed(() => {
@@ -41,14 +45,14 @@ const slugPlaceholder = computed(() => {
 <template>
   <!-- Publish gate (the `status` system column). The primary page-level control, so it leads the pane:
        Draft keeps the page out of the generated site; Published renders + auto-publishes it. -->
-  <UiField
+  <KestrelUiField
     v-if="status"
     class="page-settings__status"
     :label="t('pageSettings.statusLabel')"
     :hint="t('pageSettings.statusHint')"
   >
     <template #default="f">
-      <UiSelect
+      <KestrelUiSelect
         :model-value="(values.status as string) ?? 'draft'"
         :options="[
           { label: t('pageSettings.statusDraft'), value: 'draft' },
@@ -59,11 +63,11 @@ const slugPlaceholder = computed(() => {
         @update:model-value="(v) => emit('update', 'status', v)"
       />
     </template>
-  </UiField>
+  </KestrelUiField>
 
   <!-- The collection (page) fields, laid out by the shared renderer (rows / groups / widths, or one field
        per row when the collection declares no `fieldLayout`). The condition gate + dead-ref note live inside. -->
-  <FieldLayout
+  <KestrelFieldLayout
     :layout="fieldLayout"
     :fields="fields"
     :values="values"
@@ -75,7 +79,7 @@ const slugPlaceholder = computed(() => {
   />
 
   <!-- Page slug (the routable path). A system column on pageLike collections, edited like a field. -->
-  <UiField
+  <KestrelUiField
     v-if="pageLike"
     class="page-settings__slug"
     :label="t('pageSettings.slugLabel')"
@@ -83,7 +87,7 @@ const slugPlaceholder = computed(() => {
     :error="errors.path || null"
   >
     <template #default="f">
-      <UiTextInput
+      <KestrelUiTextInput
         :model-value="(values.path as string) ?? ''"
         :disabled="disabled"
         :placeholder="slugPlaceholder"
@@ -91,11 +95,11 @@ const slugPlaceholder = computed(() => {
         @update:model-value="(v) => emit('update', 'path', v)"
       />
     </template>
-  </UiField>
+  </KestrelUiField>
 
   <!-- Which layout renders this page (the `layout` system column). Empty = the `default` layout, so an
        unset value keeps rendering exactly as a project without the column. -->
-  <UiField
+  <KestrelUiField
     v-if="showLayout"
     class="page-settings__layout"
     :label="t('pageSettings.layoutLabel')"
@@ -103,7 +107,7 @@ const slugPlaceholder = computed(() => {
     :error="errors.layout || null"
   >
     <template #default="f">
-      <UiSelect
+      <KestrelUiSelect
         :model-value="(values.layout as string) ?? ''"
         :options="layoutOptions"
         :disabled="disabled"
@@ -111,16 +115,17 @@ const slugPlaceholder = computed(() => {
         @update:model-value="(v) => emit('update', 'layout', v)"
       />
     </template>
-  </UiField>
+  </KestrelUiField>
 
   <!-- Page SEO (meta title/description/noindex + Google preview). The `seo` JSON system column. -->
-  <SeoFields
+  <KestrelSeoFields
     v-if="seo"
     :value="(values.seo as SeoMeta) ?? {}"
     :page-title="(values.title as string) ?? ''"
     :path="(values.path as string) ?? ''"
     :locale="locale"
     :disabled="disabled"
+    :article-meta="articleMeta"
     @update="(v) => emit('update', 'seo', v)"
   />
 </template>

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

@@ -13,7 +13,7 @@ const { t } = useT()
 <template>
   <div v-if="translatable" class="ui-field">
     <span class="ui-field__label">{{ t('localeBar.fieldLabel') }}</span>
-    <LocaleBar
+    <KestrelLocaleBar
       :collection="collection"
       :id="id"
       :mode="mode"
@@ -23,7 +23,7 @@ const { t } = useT()
       @copy-from="(loc) => emit('copyFrom', loc)"
     />
   </div>
-  <PageFields
+  <KestrelPageFields
     :fields="fields"
     :field-layout="fieldLayout"
     :values="values"

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

@@ -12,6 +12,10 @@ const props = defineProps<{
   path?: string
   locale: string
   disabled?: boolean
+  /** `kestrel.seo.articleMeta`. Off (the default) hides author/date/keywords entirely: an installation
+   *  that must not attribute content should never be offered the fields, not merely stop publishing
+   *  them. Stored values are hidden, never cleared — turning the flag back on restores them. */
+  articleMeta?: boolean
 }>()
 const emit = defineEmits<{ update: [seo: SeoMeta] }>()
 const { t } = useT()
@@ -52,9 +56,9 @@ const socialImageField = { type: 'media', options: { accept: 'image' } } as Fiel
       <div class="seo-preview__desc">{{ previewDesc }}</div>
     </div>
 
-    <UiField class="seo-fields__title" :label="t('seo.metaTitle')" :hint="`${titleLen}/${TITLE_MAX}`">
+    <KestrelUiField class="seo-fields__title" :label="t('seo.metaTitle')" :hint="`${titleLen}/${TITLE_MAX}`">
       <template #default="f">
-        <UiTextInput
+        <KestrelUiTextInput
           :model-value="value.title ?? ''"
           :placeholder="pageTitle"
           :disabled="disabled"
@@ -62,11 +66,11 @@ const socialImageField = { type: 'media', options: { accept: 'image' } } as Fiel
           @update:model-value="(v) => patch({ title: v ?? '' })"
         />
       </template>
-    </UiField>
+    </KestrelUiField>
 
-    <UiField class="seo-fields__desc" :label="t('seo.metaDescription')" :hint="`${descLen}/${DESC_MAX}`">
+    <KestrelUiField class="seo-fields__desc" :label="t('seo.metaDescription')" :hint="`${descLen}/${DESC_MAX}`">
       <template #default="f">
-        <UiTextarea
+        <KestrelUiTextarea
           :model-value="value.description ?? ''"
           :rows="3"
           :disabled="disabled"
@@ -74,11 +78,11 @@ const socialImageField = { type: 'media', options: { accept: 'image' } } as Fiel
           @update:model-value="(v) => patch({ description: v ?? '' })"
         />
       </template>
-    </UiField>
+    </KestrelUiField>
 
-    <UiField class="seo-fields__image" :label="t('seo.socialImage')" :hint="t('seo.socialImageHint')">
+    <KestrelUiField class="seo-fields__image" :label="t('seo.socialImage')" :hint="t('seo.socialImageHint')">
       <template #default="f">
-        <FieldMedia
+        <KestrelFieldMedia
           :field="socialImageField"
           name="seoImage"
           :locale="locale"
@@ -88,11 +92,49 @@ const socialImageField = { type: 'media', options: { accept: 'image' } } as Fiel
           @update:model-value="(v) => patch({ image: typeof v === 'number' ? v : null })"
         />
       </template>
-    </UiField>
+    </KestrelUiField>
+
+    <!-- Article metadata (schema.org author / datePublished / keywords). Opt-in per installation. -->
+    <template v-if="articleMeta">
+      <KestrelUiField class="seo-fields__author" :label="t('seo.author')" :hint="t('seo.authorHint')">
+        <template #default="f">
+          <KestrelUiTextInput
+            :model-value="value.author ?? ''"
+            :disabled="disabled"
+            v-bind="f"
+            @update:model-value="(v) => patch({ author: v ?? '' })"
+          />
+        </template>
+      </KestrelUiField>
+
+      <KestrelUiField class="seo-fields__published" :label="t('seo.publishedDate')" :hint="t('seo.publishedDateHint')">
+        <template #default="f">
+          <KestrelUiDatePicker
+            :model-value="value.publishedDate || null"
+            precision="date"
+            :disabled="disabled"
+            :aria-label="t('seo.publishedDate')"
+            :describedby="f['aria-describedby']"
+            @update:model-value="(v) => patch({ publishedDate: v ?? '' })"
+          />
+        </template>
+      </KestrelUiField>
+
+      <KestrelUiField class="seo-fields__keywords" :label="t('seo.keywords')" :hint="t('seo.keywordsHint')">
+        <template #default="f">
+          <KestrelUiTextInput
+            :model-value="value.keywords ?? ''"
+            :disabled="disabled"
+            v-bind="f"
+            @update:model-value="(v) => patch({ keywords: v ?? '' })"
+          />
+        </template>
+      </KestrelUiField>
+    </template>
 
     <!-- eslint-disable-next-line vuejs-accessibility/label-has-for -- native wrapping label around a custom UiCheckbox; no `for`/`id` pair needed, invisible to static analysis -->
     <label class="seo-fields__noindex">
-      <UiCheckbox
+      <KestrelUiCheckbox
         :model-value="!!value.noindex"
         :disabled="disabled"
         @update:model-value="(v) => patch({ noindex: v })"

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

@@ -31,16 +31,16 @@ useUnsavedGuard(() => editorRef.value?.dirty ?? false, () => t('editor.discardCo
     <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 type="button" variant="ghost" size="sm" icon="external-link" :title="previewTitle" :aria-label="previewTitle" :loading="editorRef?.previewOpening" @click="editorRef?.openPreview()" />
-        <UiButton type="submit" :form="EDITOR_FORM_ID" variant="primary" size="sm" icon="check" :loading="saving">{{ t('common.save') }}</UiButton>
+        <KestrelUiButton type="button" variant="ghost" size="sm" icon="undo" :disabled="saving || !editorRef?.canUndo" :title="t('history.undo')" :aria-label="t('history.undo')" @click="editorRef?.undo()" />
+        <KestrelUiButton type="button" variant="ghost" size="sm" icon="redo" :disabled="saving || !editorRef?.canRedo" :title="t('history.redo')" :aria-label="t('history.redo')" @click="editorRef?.redo()" />
+        <KestrelUiButton type="button" variant="ghost" size="sm" icon="external-link" :title="previewTitle" :aria-label="previewTitle" :loading="editorRef?.previewOpening" @click="editorRef?.openPreview()" />
+        <KestrelUiButton type="submit" :form="EDITOR_FORM_ID" variant="primary" size="sm" icon="check" :loading="saving">{{ t('common.save') }}</KestrelUiButton>
         <!-- Publishing is its own decision: Save persists, Publish writes the static page (ADR-0008). -->
-        <UiButton v-if="editorRef?.canPublish !== false" type="button" variant="secondary" size="sm" icon="upload" :loading="editorRef?.publishing" :disabled="saving" @click="editorRef?.publish()">{{ t('common.publish') }}</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" />
+        <KestrelUiButton v-if="editorRef?.canPublish !== false" type="button" variant="secondary" size="sm" icon="upload" :loading="editorRef?.publishing" :disabled="saving" @click="editorRef?.publish()">{{ t('common.publish') }}</KestrelUiButton>
+        <KestrelEditorStatus 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
+    <KestrelCollectionEditor
       ref="editorRef"
       :collection="collection"
       id="single"

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

@@ -278,7 +278,11 @@ export function useEditForm(opts: UseEditFormOptions) {
   }
 
   function handleError(e: unknown) {
-    const { statusCode, statusMessage, issues } = readFetchError(e)
+    const { statusCode, statusMessage, issues, data } = readFetchError(e)
+    // The row WAS written and a follow-up step failed (a write effect — see write-effects.ts), so the
+    // server hands back the new `updatedAt`. Take it as the baseline: the client only rebaselines on
+    // success, and without this the "save again" those errors ask for would 409 on a stale precondition.
+    if (typeof data?.savedUpdatedAt === 'number') baseUpdatedAt.value = data.savedUpdatedAt
     if (statusCode === 400) {
       const mapped = mapServerErrors(issues)
       for (const [k, msg] of Object.entries(mapped.fields)) errors[k] = msg
@@ -292,9 +296,11 @@ export function useEditForm(opts: UseEditFormOptions) {
           ? t('editor.fixBlockContent')
           : Object.keys(mapped.fields).length ? t('editor.fixPageFields') : '')
     } else if (statusCode === 409) {
-      formError.value = statusMessage ?? t('editor.saveConflict')
+      // `||`, not `??`: an absent reason phrase arrives as '' rather than undefined, and an empty banner
+      // is a silent failure — the Save button simply stops spinning.
+      formError.value = statusMessage || t('editor.saveConflict')
     } else {
-      formError.value = statusMessage ?? t('editor.saveFailed')
+      formError.value = statusMessage || t('editor.saveFailed')
     }
   }
 

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

@@ -0,0 +1,61 @@
+// Row and bulk actions for the collection list: a row action is one id, the bulk bar is N — the server
+// does the batching, so both go through the same calls.
+//
+// Destructive → confirm dialog. Reversible → run, toast, refetch (the ops composable's onChanged).
+import { ref, type ComputedRef } from 'vue'
+import type { BatchDeleteReport } from '../utils/collection-ops'
+
+export function useListBatchActions(collection: ComputedRef<string>, refetch: () => void | Promise<void>) {
+  const { t } = useT()
+  const toast = useToast()
+  const { busy, error, previewDelete, confirmDelete: runDelete, duplicate: runDuplicate, setStatus: runSetStatus } =
+    useCollectionOps(collection, () => refetch())
+
+  const deleteOpen = ref(false)
+  const deleteReport = ref<BatchDeleteReport | null>(null)
+  const deleteIds = ref<number[]>([])
+
+  // The referrer preview is best-effort: if it fails we still open the dialog with a bare summary (never
+  // block a delete on the warning lookup).
+  async function askDelete(ids: number[]) {
+    if (!ids.length) return
+    deleteIds.value = ids
+    deleteReport.value = null
+    deleteOpen.value = true
+    try {
+      deleteReport.value = await previewDelete(ids)
+    } catch {
+      // The referrer lookup FAILED — do not fabricate a "no inbound links" report (that would look exactly
+      // like a verified-safe delete). Flag `checked: false` so the dialog cautions the check couldn't run.
+      deleteReport.value = { count: ids.length, referencedCount: 0, referenced: [], checked: false }
+      error.value = null
+    }
+  }
+  async function confirmDelete() {
+    try {
+      await runDelete(deleteIds.value)
+      toast.success(t('toast.deleted'))
+      deleteOpen.value = false
+    } catch {
+      // error stays surfaced in the dialog via `error`
+    }
+  }
+  async function duplicate(id: number) {
+    try {
+      await runDuplicate([id])
+      toast.success(t('toast.duplicated'))
+    } catch {
+      toast.error(error.value ?? t('list.opFailed'))
+    }
+  }
+  async function setStatus(ids: number[], status: 'published' | 'draft') {
+    try {
+      await runSetStatus(ids, status)
+      toast.success(status === 'published' ? t('toast.published') : t('toast.unpublished'))
+    } catch {
+      toast.error(error.value ?? t('list.opFailed'))
+    }
+  }
+
+  return { busy, error, deleteOpen, deleteReport, askDelete, confirmDelete, duplicate, setStatus }
+}

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

@@ -0,0 +1,128 @@
+// The Filter panel's pending edits, and how they become committed clauses in the URL.
+//
+// `filter` (from the URL) is the committed state that drives the query; `draft` is what the panel shows
+// while the user is still typing. A value change debounces, an operator change commits at once.
+import { computed, onBeforeUnmount, reactive, watch, type ComputedRef } from 'vue'
+import { DEFAULT_OP, OPS_BY_KIND, type FilterKind, type FilterOp } from '../../../core/app/utils/filter-ops'
+import { resolveLocalized } from '../../../ui/app/utils/localized'
+import { columnLabel } from '../utils/list-cell'
+import type { Localized } from '../../../core/server/utils/defineCollection'
+import type { ListColumn } from '../utils/list-columns'
+import type { FilterCell } from '../utils/list-query'
+
+const COMMIT_DEBOUNCE_MS = 250
+
+/** One active clause as the chip row renders it. */
+export interface ActiveFilter {
+  key: string
+  op: FilterOp
+  opLabel: string
+  label: string
+  display: string
+}
+
+/** The panel's whole controller — passed to the filter panel as one prop rather than a dozen. */
+export interface ListFilterDraft {
+  draft: Record<string, FilterCell>
+  activeFilters: ComputedRef<ActiveFilter[]>
+  opsFor: (c: ListColumn) => readonly FilterOp[]
+  opLabel: (kind: FilterKind, op: FilterOp) => string
+  enumOptions: (c: ListColumn) => { label: string; value: string }[]
+  setValue: (field: string, value: string) => void
+  setOp: (field: string, op: FilterOp) => void
+  clearFilter: (field: string) => void
+  clearAll: () => void
+}
+
+interface FilterDraftOptions {
+  available: ComputedRef<ListColumn[]>
+  filterableColumns: ComputedRef<ListColumn[]>
+  filter: ComputedRef<Record<string, FilterCell>>
+  setFilter: (next: Record<string, FilterCell>) => void
+}
+
+export function useListFilterDraft(opts: FilterDraftOptions): ListFilterDraft {
+  const { t, lang } = useT()
+  const draft = reactive<Record<string, FilterCell>>({})
+
+  // Overwrite each draft cell FROM the committed `filter` so deep-link / Back-Forward / chip-removal reflect
+  // back into the open panel; drop drafts for columns this collection no longer has. We key the watch on the
+  // committed filter's CONTENT (its JSON), not its object identity: `filter` recomputes to a fresh-but-EQUAL
+  // object on every `route.query` change (page/sort/perPage navigations too), and resyncing on those identity
+  // flips would wipe an in-progress panel edit. Clobber-safe on a real filter commit: a commit sends ALL
+  // drafts at once, so post-commit `filter` equals `draft` (a no-op overwrite) — the content only actually
+  // changes on external navigation (deep-link/Back-Forward/chip-removal), which is when the panel should resync.
+  watch([opts.filterableColumns, () => JSON.stringify(opts.filter.value)], () => {
+    const cols = opts.filterableColumns.value
+    for (const c of cols) {
+      const cm = opts.filter.value[c.key]
+      draft[c.key] = { op: cm?.op ?? DEFAULT_OP[c.filterKind ?? 'text'], value: cm?.value ?? '' }
+    }
+    for (const key of Object.keys(draft)) if (!cols.some((c) => c.key === key)) Reflect.deleteProperty(draft, key)
+  }, { immediate: true })
+
+  function opsFor(c: ListColumn): readonly FilterOp[] {
+    return OPS_BY_KIND[c.filterKind ?? 'text']
+  }
+  // Operator labels are kind-aware: a datetime comparison reads "before / on or before / …" instead of the
+  // generic "less than / less or equal / …".
+  function opLabel(kind: FilterKind, op: FilterOp): string {
+    if (kind === 'datetime' && (op === 'lt' || op === 'lte' || op === 'gt' || op === 'gte')) return t(`filter.opDate.${op}`)
+    return t(`filter.op.${op}`)
+  }
+  // Choices for an `enum` / `stringSet` value control: a fixed draft/published set for `status`, else the
+  // choice field's own (single- and multi-choice fields both carry `options.choices`).
+  function enumOptions(c: ListColumn): { label: string; value: string }[] {
+    if (c.key === 'status') return [
+      { value: 'draft', label: t('pageSettings.statusDraft') },
+      { value: 'published', label: t('pageSettings.statusPublished') },
+    ]
+    // A choice label is `Localized`, so resolve it here as the editor widget does — `{{ o.label }}` would
+    // stringify a `{ en, de }` map into the filter dropdown.
+    return ((c.field?.options?.choices ?? []) as { label: Localized; value: string }[])
+      .map((o) => ({ value: o.value, label: resolveLocalized(o.label, lang.value) ?? o.value }))
+  }
+  function displayValue(kind: FilterKind, value: string): string {
+    if (kind === 'boolean') return value === 'true' ? t('filter.bool.true') : value === 'false' ? t('filter.bool.false') : value
+    return value
+  }
+
+  // Builds a fresh clause map from the non-empty draft cells and navigates via `setFilter` (which also
+  // resets page → 1).
+  let timer: ReturnType<typeof setTimeout> | undefined
+  function commitDrafts() {
+    const next: Record<string, FilterCell> = {}
+    for (const [field, cell] of Object.entries(draft)) {
+      if (cell.value !== '' && cell.value != null) next[field] = { op: cell.op, value: cell.value }
+    }
+    opts.setFilter(next)
+  }
+  function setValue(field: string, value: string) {
+    if (draft[field]) draft[field].value = value
+    clearTimeout(timer)
+    timer = setTimeout(commitDrafts, COMMIT_DEBOUNCE_MS)
+  }
+  function setOp(field: string, op: FilterOp) {
+    if (draft[field]) draft[field].op = op
+    // An operator change is deliberate — re-query immediately (no debounce) if the field has a value.
+    clearTimeout(timer)
+    commitDrafts()
+  }
+  function clearFilter(field: string) {
+    if (draft[field]) draft[field].value = ''
+    commitDrafts() // re-commits the drafts with this one now empty → the clause is dropped (and page → 1)
+  }
+  function clearAll() {
+    for (const cell of Object.values(draft)) cell.value = ''
+    opts.setFilter({}) // clear the committed clauses (and page → 1); the draft-resync watch clears the panel
+  }
+  onBeforeUnmount(() => clearTimeout(timer))
+
+  const activeFilters = computed(() => Object.entries(opts.filter.value).map(([key, cell]) => {
+    const col = opts.available.value.find((c) => c.key === key)
+    const kind = col?.filterKind ?? 'text'
+    return { key, op: cell.op, opLabel: opLabel(kind, cell.op), label: col ? columnLabel(col, t) : key, display: displayValue(kind, cell.value) }
+  }))
+
+  return { draft, activeFilters, opsFor, opLabel, enumOptions, setValue, setOp, clearFilter, clearAll }
+}

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

@@ -0,0 +1,70 @@
+// The collection list's row fetch: request, out-of-range clamp, and the inline error state.
+import { computed, ref, type ComputedRef, type Ref } from 'vue'
+
+interface ListRowsOptions {
+  collection: ComputedRef<string>
+  /** The sanitized query derived from the URL (sort / page / perPage / filter). */
+  effectiveQuery: ComputedRef<Record<string, unknown>>
+  locale: () => string | undefined
+  page: ComputedRef<number>
+  perPage: ComputedRef<number>
+  /** Navigate back into range when the current page emptied out; REPLACE, never push. */
+  clampPage: (page: number) => void
+  /** Runs after a SUCCESSFUL fetch — the caller drops its page-scoped state here. A failed fetch keeps
+   *  the previously rendered rows, so anything scoped to them stays valid. */
+  onLoaded?: () => void
+}
+
+interface ListResponse {
+  data: Record<string, unknown>[]
+  total: number
+  page: number
+  perPage: number
+}
+
+export function useListRows(opts: ListRowsOptions) {
+  const { t } = useT()
+  const rows = ref<Record<string, unknown>[]>([])
+  const total = ref(0)
+  // Surfaced when a (re)fetch fails — an inline error + Retry, never a silent stale list or a thrown
+  // error boundary. Distinct from the empty state (which only shows when the fetch SUCCEEDED with no rows).
+  const error = ref<string | null>(null)
+  const totalPages = computed(() => Math.max(1, Math.ceil(total.value / opts.perPage.value)))
+
+  // Monotonic request id: a slow earlier response must not overwrite a newer one.
+  let seq = 0
+  async function fetchRows() {
+    const mine = ++seq
+    const locale = opts.locale()
+    try {
+      const res = await $fetch<ListResponse>(`/api/${opts.collection.value}`, {
+        query: { ...opts.effectiveQuery.value, ...(locale ? { locale } : {}) },
+      })
+      if (mine !== seq) return
+      rows.value = res.data
+      total.value = res.total
+      error.value = null
+      // A page that emptied out from under us — e.g. bulk-deleting the last rows of the trailing page —
+      // would otherwise strand the user on an out-of-range page showing the "create your first" empty
+      // state. Clamp back to the last page that still has rows (REPLACE, so the dead page isn't left as a
+      // history entry that Back would bounce off; the query watch refetches).
+      if (res.data.length === 0 && res.total > 0 && opts.page.value > 1) {
+        opts.clampPage(Math.max(1, Math.ceil(res.total / opts.perPage.value)))
+      }
+      opts.onLoaded?.()
+    } catch (e) {
+      if (mine !== seq) return
+      // Keep any previously-rendered rows, but surface that this fetch failed (and don't show the
+      // "create your first" empty state — that would imply the collection is empty when it isn't).
+      error.value = (e as { statusMessage?: string })?.statusMessage ?? t('list.loadError')
+    }
+  }
+
+  return { rows, total, error, totalPages, fetchRows } as {
+    rows: Ref<Record<string, unknown>[]>
+    total: Ref<number>
+    error: Ref<string | null>
+    totalPages: ComputedRef<number>
+    fetchRows: () => Promise<void>
+  }
+}

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

@@ -0,0 +1,28 @@
+// Page-scoped row selection for the collection list.
+//
+// The Set is valid only for the rows currently on screen — every (re)fetch replaces them, so the caller
+// clears it from its fetch handler. A reactive Set (Vue tracks add/delete/has/size) keeps a single-row
+// toggle O(1): no full-Set copy and no whole-table re-diff per click, which mattered at the 500-row cap.
+import { computed, reactive, type Ref } from 'vue'
+
+export function useListSelection(rows: Ref<Record<string, unknown>[]>) {
+  const selected = reactive(new Set<number>())
+  const pageIds = computed(() => rows.value.map((r) => Number(r.id)))
+  const allSelected = computed(() => pageIds.value.length > 0 && pageIds.value.every((id) => selected.has(id)))
+  // Tri-state header checkbox: some rows selected, but not all of them.
+  const headerIndeterminate = computed(() => pageIds.value.some((id) => selected.has(id)) && !allSelected.value)
+
+  function toggleRow(id: number, on: boolean) {
+    if (on) selected.add(id)
+    else selected.delete(id)
+  }
+  function toggleAll(on: boolean) {
+    selected.clear()
+    if (on) for (const id of pageIds.value) selected.add(id)
+  }
+  function clear() {
+    selected.clear()
+  }
+
+  return { selected, allSelected, headerIndeterminate, toggleRow, toggleAll, clear }
+}

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

@@ -0,0 +1,38 @@
+// Toolbar disclosure panels (filter / columns). Plain inline panels, not teleported, so they stay
+// testable and keep their scoped styles; a document listener closes them on an outside click.
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+
+export function useToolbarPanel<T extends string>() {
+  const container = ref<HTMLElement | null>(null)
+  const open = ref<T | null>(null)
+  // The element that opened the current panel — Escape restores focus to it (otherwise closing the panel
+  // from inside drops keyboard focus onto <body>, stranding the keyboard user at the top of the document).
+  let trigger: HTMLElement | null = null
+
+  function toggle(which: T, e: MouseEvent) {
+    if (open.value === which) { open.value = null; return }
+    trigger = e.currentTarget as HTMLElement
+    open.value = which
+  }
+  function onDocPointer(e: PointerEvent) {
+    // Outside click: close but do NOT steal focus — it belongs wherever the user just clicked.
+    if (container.value && !container.value.contains(e.target as Node)) open.value = null
+  }
+  function onDocKeydown(e: KeyboardEvent) {
+    if (e.key === 'Escape' && open.value) {
+      open.value = null
+      trigger?.focus() // return focus to the trigger, per the disclosure/APG pattern
+    }
+  }
+
+  onMounted(() => {
+    document.addEventListener('pointerdown', onDocPointer)
+    document.addEventListener('keydown', onDocKeydown)
+  })
+  onBeforeUnmount(() => {
+    document.removeEventListener('pointerdown', onDocPointer)
+    document.removeEventListener('keydown', onDocKeydown)
+  })
+
+  return { container, open, toggle }
+}