@prenta/admin 2.6.1 → 2.8.0

package/src/lib/jobs-service.ts

@@ -0,0 +1,345 @@
+/**
+ * Jobs service: a typed client over the cms-core Jobs endpoints
+ * (DATA_CONTRACTS.md §1, envelopes in CONFLICTS.md §4). The Jobs screen calls
+ * these, never `cmsApi` directly.
+ *
+ * Every call returns an outcome rather than throwing, so a screen can tell a
+ * failed request from an empty list and show the server's message (a
+ * viewer's 403, a 409 for a job that can't be retried).
+ */
+import type {
+  BatchAiEstimate,
+  BatchAiPreviewItem,
+  BatchAiRequest,
+  Job,
+  JobEvent,
+  JobReviewItem,
+  JobWorkerStatus,
+} from '@prenta/core'
+import { cmsApi, getApiBase } from './api.js'
+
+export type JobsOutcome<T> = { ok: true; value: T } | { ok: false; error: string; status: number }
+
+/**
+ * A polled read. It also carries the server's clock (the `Date` header) and,
+ * on a 429, how long the server asked the client to wait (`Retry-After`).
+ */
+export type PollOutcome<T> =
+  | { ok: true; value: T; serverTime: number | null }
+  | {
+      ok: false
+      error: string
+      status: number
+      serverTime: number | null
+      retryAfterMs: number | null
+    }
+
+/** The screen lists the newest 50 jobs (JOBS.md). */
+export const JOBS_LIST_LIMIT = 50
+
+/** The job types "Run now" can start. Batch AI starts from a set of documents instead. */
+export type RunnableJobType = 'seo-scan' | 'content-health'
+
+async function call<T>(endpoint: string, init?: RequestInit): Promise<JobsOutcome<T>> {
+  const res = await cmsApi<T>(endpoint, init)
+  if (res.error !== undefined || res.data === undefined) {
+    return {
+      ok: false,
+      error: res.error ?? 'The server sent an empty response',
+      status: res.status,
+    }
+  }
+  return { ok: true, value: res.data }
+}
+
+function headerTime(value: string | null): number | null {
+  if (!value) return null
+  const at = Date.parse(value)
+  return Number.isNaN(at) ? null : at
+}
+
+/** `Retry-After` is either seconds or an HTTP date. */
+function retryAfterMs(value: string | null, serverTime: number | null): number | null {
+  if (!value) return null
+  const seconds = Number(value)
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000)
+  const at = headerTime(value)
+  return at === null ? null : Math.max(0, at - (serverTime ?? Date.now()))
+}
+
+/**
+ * A GET for the 5-second refresh. It calls `fetch` itself, as
+ * `downloadEntriesExport` does, because the refresh needs two response
+ * headers `cmsApi` doesn't pass on: `Date`, to correct for a wrong browser
+ * clock, and `Retry-After`, to back off when rate-limited. A GET needs no
+ * CSRF token. `signal` lets the caller time the request out.
+ */
+async function pollGet<T>(endpoint: string, signal?: AbortSignal): Promise<PollOutcome<T>> {
+  let res: Response
+  try {
+    res = await fetch(`${getApiBase()}${endpoint}`, {
+      credentials: 'include',
+      headers: { Accept: 'application/json' },
+      signal,
+    })
+  } catch (err) {
+    const error = err instanceof Error ? err.message : 'Network error'
+    return { ok: false, error, status: 0, serverTime: null, retryAfterMs: null }
+  }
+  const serverTime = headerTime(res.headers.get('date'))
+  const json = (await res.json().catch(() => ({}))) as { data?: T; error?: string }
+  if (!res.ok) {
+    return {
+      ok: false,
+      error: json.error || `Request failed (${res.status})`,
+      status: res.status,
+      serverTime,
+      retryAfterMs:
+        res.status === 429 ? retryAfterMs(res.headers.get('retry-after'), serverTime) : null,
+    }
+  }
+  if (json.data === undefined) {
+    return {
+      ok: false,
+      error: 'The server sent an empty response',
+      status: res.status,
+      serverTime,
+      retryAfterMs: null,
+    }
+  }
+  return { ok: true, value: json.data, serverTime }
+}
+
+/** `GET /jobs`: newest first. */
+export async function listJobs(
+  limit = JOBS_LIST_LIMIT,
+  signal?: AbortSignal,
+): Promise<PollOutcome<Job[]>> {
+  const res = await pollGet<{ jobs?: Job[] }>(`/jobs?limit=${limit}`, signal)
+  return res.ok ? { ...res, value: res.value.jobs ?? [] } : res
+}
+
+/** `GET /jobs/worker`: the last tick and the scan schedules, for the worker strip. */
+export function getJobWorker(signal?: AbortSignal): Promise<PollOutcome<JobWorkerStatus>> {
+  return pollGet<JobWorkerStatus>('/jobs/worker', signal)
+}
+
+/**
+ * `POST /jobs/run`. When a job of that type is already queued or running the
+ * server returns it with `reused: true` instead of adding one.
+ */
+export function runJobNow(
+  type: RunnableJobType,
+): Promise<JobsOutcome<{ job: Job; reused: boolean }>> {
+  return call('/jobs/run', { method: 'POST', body: JSON.stringify({ type }) })
+}
+
+/** `POST /jobs/:id/retry`: a failed job, or one waiting to retry. Anything else is a 409. */
+export function retryJob(id: string): Promise<JobsOutcome<Job>> {
+  return call(`/jobs/${encodeURIComponent(id)}/retry`, { method: 'POST' })
+}
+
+/**
+ * `POST /jobs/:id/cancel`. A queued job comes back cancelled; a running one
+ * comes back with `cancelRequestedAt` set and stops after its slice. A job
+ * that already finished comes back unchanged.
+ */
+export function cancelJob(id: string): Promise<JobsOutcome<Job>> {
+  return call(`/jobs/${encodeURIComponent(id)}/cancel`, { method: 'POST' })
+}
+
+/**
+ * `GET /jobs/batch-ai/estimate`: how many documents a batch would change,
+ * 3 of them as a sample, and its tokens, minutes and share of the monthly AI
+ * limit. The query carries the request's fields, `documentIds` comma-separated.
+ */
+export function estimateBatchAi(
+  request: BatchAiRequest,
+  signal?: AbortSignal,
+): Promise<JobsOutcome<BatchAiEstimate>> {
+  const params = new URLSearchParams({
+    operation: request.operation,
+    source: request.source,
+    statusFilter: request.statusFilter,
+  })
+  if (request.field) params.set('field', request.field)
+  if (request.instruction) params.set('instruction', request.instruction)
+  const ids = request.filter?.documentIds
+  if (ids?.length) params.set('documentIds', ids.join(','))
+  return call(`/jobs/batch-ai/estimate?${params}`, { signal })
+}
+
+/**
+ * `POST /jobs/batch-ai/preview`: what the AI would write for the first 3
+ * matching documents. Nothing is written. A document it would leave as it is
+ * isn't listed, and a spent AI cap is a 429.
+ */
+export async function previewBatchAi(
+  request: BatchAiRequest,
+  signal?: AbortSignal,
+): Promise<JobsOutcome<BatchAiPreviewItem[]>> {
+  const res = await call<{ items?: BatchAiPreviewItem[] }>('/jobs/batch-ai/preview', {
+    method: 'POST',
+    body: JSON.stringify(request),
+    signal,
+  })
+  return res.ok ? { ok: true, value: res.value.items ?? [] } : res
+}
+
+/**
+ * `POST /jobs/batch-ai`: resolve the documents once, freeze them in a new
+ * queued job, and return it. "Apply automatically" is admin-only (403), and
+ * a filter matching no documents, or more than 1,000, is a 400.
+ */
+export function createBatchAiJob(request: BatchAiRequest): Promise<JobsOutcome<Job>> {
+  return call('/jobs/batch-ai', { method: 'POST', body: JSON.stringify(request) })
+}
+
+function jobPath(id: string): string {
+  return `/jobs/${encodeURIComponent(id)}`
+}
+
+/**
+ * `GET /jobs/:id`: the job with its scan `results`. A caller who could retry
+ * or cancel it also gets the full `lastError` with its stack; others get the
+ * one line the list shows.
+ */
+export function getJob(id: string, signal?: AbortSignal): Promise<JobsOutcome<Job>> {
+  return call(jobPath(id), { signal })
+}
+
+/** `GET /jobs/:id/events`: the job's newest 50 events. */
+export async function listJobEvents(
+  id: string,
+  signal?: AbortSignal,
+): Promise<JobsOutcome<JobEvent[]>> {
+  const res = await call<{ events?: JobEvent[] }>(`${jobPath(id)}/events`, { signal })
+  return res.ok ? { ok: true, value: res.value.events ?? [] } : res
+}
+
+/** The drawer loads a job's suggested changes 20 at a time (TRACKING P-18). */
+export const REVIEW_PAGE_SIZE = 20
+/** The most `GET /jobs/:id/review` returns in one page. */
+export const REVIEW_PAGE_MAX = 100
+
+export interface ReviewPage {
+  items: JobReviewItem[]
+  /** Pass back as `cursor` for the next page; null on the last one. */
+  nextCursor: string | null
+}
+
+/**
+ * `GET /jobs/:id/review`: the job's changes, pending and decided, in the
+ * order they were suggested. A caller who can't edit content, or can't read
+ * one of the collections the job writes, gets a 403.
+ */
+export async function listReviewItems(
+  id: string,
+  page: { cursor?: string | null; limit?: number } = {},
+  signal?: AbortSignal,
+): Promise<JobsOutcome<ReviewPage>> {
+  const params = new URLSearchParams({ limit: String(page.limit ?? REVIEW_PAGE_SIZE) })
+  if (page.cursor) params.set('cursor', page.cursor)
+  const res = await call<{ items?: JobReviewItem[]; nextCursor?: string | null }>(
+    `${jobPath(id)}/review?${params}`,
+    { signal },
+  )
+  return res.ok
+    ? {
+        ok: true,
+        value: { items: res.value.items ?? [], nextCursor: res.value.nextCursor ?? null },
+      }
+    : res
+}
+
+/**
+ * "Save as draft" (which keeps a published document's status, so its change
+ * stays in review) or "Publish" (CONFLICTS.md §4).
+ */
+export type OnApprove = 'draft' | 'publish'
+
+export type ReviewAction =
+  | { action: 'approve'; onApprove?: OnApprove; after?: string }
+  | { action: 'reject' }
+  | { action: 'undo' }
+
+export interface ReviewDecision {
+  item: JobReviewItem
+  /** The document's status after the decision, such as `PUBLISHED`. Null for an image. */
+  documentStatus: string | null
+  /** Set when an undo left the document published, now showing the previous text. */
+  notice: string | null
+}
+
+/** `POST /jobs/:id/review/:itemId`: approve, reject or undo one change. */
+export async function decideReviewItem(
+  jobId: string,
+  itemId: string,
+  decision: ReviewAction,
+): Promise<JobsOutcome<ReviewDecision>> {
+  const res = await cmsApi<JobReviewItem>(
+    `${jobPath(jobId)}/review/${encodeURIComponent(itemId)}`,
+    { method: 'POST', body: JSON.stringify(decision) },
+  )
+  if (res.error !== undefined || res.data === undefined) {
+    return {
+      ok: false,
+      error: res.error ?? 'The server sent an empty response',
+      status: res.status,
+    }
+  }
+  // `documentStatus` and `notice` sit beside `data` in the envelope.
+  const envelope = (res.body ?? {}) as { documentStatus?: unknown; notice?: unknown }
+  return {
+    ok: true,
+    value: {
+      item: res.data,
+      documentStatus: typeof envelope.documentStatus === 'string' ? envelope.documentStatus : null,
+      notice: typeof envelope.notice === 'string' ? envelope.notice : null,
+    },
+  }
+}
+
+export interface ApproveAllOutcome {
+  approved: number
+  /** Changes this call couldn't apply. They stay pending. */
+  skipped: number
+  /** Pending changes left, skipped ones included. */
+  remaining: number
+}
+
+/**
+ * `POST /jobs/:id/review/approve-all`, with the job's own "When a change is
+ * approved". The server stops starting changes after 20 seconds, so a caller
+ * asks again while `remaining` is more than `skipped`.
+ */
+export function approveAllReviewItems(jobId: string): Promise<JobsOutcome<ApproveAllOutcome>> {
+  return call(`${jobPath(jobId)}/review/approve-all`, { method: 'POST', body: '{}' })
+}
+
+/**
+ * Why a review decision was refused with a 409, read from the server's
+ * message (cms-core `jobs/review.ts`), which the drawer shows as it is:
+ * - `published`: approved without Publish on a published document, so the
+ *   change stays in review;
+ * - `changed`: the document changed while the change was being saved, or its
+ *   publish state moved since it was read, and nothing was written;
+ * - `link-gone`: the page a link points to isn't published at that address;
+ * - `decided`: someone else decided the change first;
+ * - `gone`: the change or its document no longer exists.
+ * Null for any other refusal.
+ */
+export type ReviewConflict = 'published' | 'changed' | 'link-gone' | 'decided' | 'gone'
+
+const REVIEW_CONFLICTS: ReadonlyArray<[ReviewConflict, RegExp]> = [
+  ['published', /\bis published, so the change stays in review\b/i],
+  ['changed', /\bchanged while this was being saved\b/i],
+  ['link-gone', /\bisn[’']t published at that address any more\b/i],
+  ['decided', /\bwas already decided\b/i],
+  ['gone', /\bno longer exists\b/i],
+]
+
+export function reviewConflict(status: number, error: string): ReviewConflict | null {
+  if (status !== 409) return null
+  return REVIEW_CONFLICTS.find(([, pattern]) => pattern.test(error))?.[0] ?? null
+}

package/src/lib/sheet-focus.ts

@@ -0,0 +1,71 @@
+import { useEffect, useRef, type RefObject } from 'react'
+import { TIER_MEDIA } from './tiers.js'
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/**
+ * Where focus goes back to when a sheet closes. Usually the element that had
+ * focus when it opened. A tap on a row's plain text (a table cell) leaves focus
+ * on `<body>`, so the tapped row's own control stands in: the control that was
+ * tapped, else the row's title control, else its first control.
+ */
+export function returnTarget(
+  active: Element | null,
+  tapped: EventTarget | null,
+): HTMLElement | null {
+  if (active instanceof HTMLElement && active !== active.ownerDocument.body) return active
+  if (!(tapped instanceof Element)) return null
+  const own = tapped.closest<HTMLElement>(FOCUSABLE)
+  if (own) return own
+  const row = tapped.closest('tr, [role="row"]')
+  return (
+    row?.querySelector<HTMLElement>(`[data-role="title"] :is(${FOCUSABLE})`) ??
+    row?.querySelector<HTMLElement>(FOCUSABLE) ??
+    null
+  )
+}
+
+/**
+ * Below 769px an open side pane is a sheet that hides the list it was opened
+ * from (`[data-inspector-open]` in responsive.css), so the row that opened it
+ * leaves the screen. Focus moves into the sheet when it opens and back to that
+ * row when it closes. Wider screens keep the list beside the pane and leave
+ * focus alone.
+ *
+ * `restore` runs first on close, for a list that must put itself back (Media's
+ * virtualised grid returns at the top once shown again); `fallback` is focused
+ * when the opener can't take focus (Media's grid cards aren't focusable).
+ */
+export function useSheetFocus(
+  open: boolean,
+  sheetRef: RefObject<HTMLElement | null>,
+  options: { restore?: () => void; fallback?: () => HTMLElement | null } = {},
+): void {
+  const tapped = useRef<EventTarget | null>(null)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  useEffect(() => {
+    const onPointerDown = (event: PointerEvent) => {
+      tapped.current = event.target
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => document.removeEventListener('pointerdown', onPointerDown, true)
+  }, [])
+
+  useEffect(() => {
+    if (!open || typeof window.matchMedia !== 'function') return
+    if (!window.matchMedia(TIER_MEDIA.mobile).matches) return
+    const opener = returnTarget(document.activeElement, tapped.current)
+    sheetRef.current?.focus()
+    return () => {
+      optionsRef.current.restore?.()
+      const target =
+        opener?.isConnected && opener.getClientRects().length > 0
+          ? opener
+          : (optionsRef.current.fallback?.() ?? null)
+      target?.focus()
+    }
+  }, [open, sheetRef])
+}

package/src/lib/tiers.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * Layout tiers (SHELL.md §8) as media queries, for `matchMedia`. The CSS side
+ * is the `@custom-variant` block at the top of `styles/theme.css`
+ * (`mobile:`, `tablet:` …); `tiers.test.ts` checks the two say the same thing.
+ *
+ * Half-open ranges: every width, fractional ones included (768.5px at a zoom
+ * level), falls in exactly one of mobile, tablet, laptop, wide and 4k.
+ */
+export const TIER_MEDIA = {
+  /** Tablet and mobile together: ≤1024px. */
+  narrow: '(width < 1025px)',
+  /** ≤768px: bottom tab bar, FAB, cards, sheets. */
+  mobile: '(width < 769px)',
+  /** 769–1024px: icon rail, header actions as icons. */
+  tablet: '(769px <= width < 1025px)',
+  /** 1025–1440px: the baseline. */
+  laptop: '(1025px <= width < 1441px)',
+  /** 1441–2199px. */
+  wide: '(1441px <= width < 2200px)',
+  /** ≥2200px. */
+  '4k': '(width >= 2200px)',
+} as const
+
+/**
+ * Whether a media query matches, following changes. Starts `false` and
+ * corrects after mount, so a server render and the first client render agree.
+ * Prefer the CSS variants; use this only where behaviour (not style) differs
+ * by tier.
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(false)
+  useEffect(() => {
+    if (typeof window.matchMedia !== 'function') return
+    const mq = window.matchMedia(query)
+    const apply = () => setMatches(mq.matches)
+    apply()
+    mq.addEventListener?.('change', apply)
+    return () => mq.removeEventListener?.('change', apply)
+  }, [query])
+  return matches
+}

package/src/router/admin-routes.ts

@@ -27,12 +27,17 @@ export const ADMIN_STATIC_ROUTE_PATTERNS: readonly string[] = [
   '/collections/:slug/:id',
   '/collections/:slug/new',
   '/forgot-password',
+  '/appearance/header',
+  '/appearance/menus',
+  '/appearance/widgets',
   '/forms',
   '/forms/:id/edit',
   '/forms/:id/submissions',
   '/forms/entries',
   '/forms/deliveries',
   '/forms/new',
+  '/forms/settings',
+  '/forms/spam',
   '/jobs',
   '/media',
   '/mcp/consent',
@@ -43,6 +48,7 @@ export const ADMIN_STATIC_ROUTE_PATTERNS: readonly string[] = [
   '/pages/:id',
   '/pages/:id/edit',
   '/pages/new',
+  '/pages/trash',
   '/pages/tags',
   '/pages/tags/:id/edit',
   '/pages/tags/new',
@@ -50,6 +56,7 @@ export const ADMIN_STATIC_ROUTE_PATTERNS: readonly string[] = [
   '/posts/:type/:id/edit',
   '/posts/:type/new',
   '/posts/new',
+  '/posts/trash',
   '/posts/types',
   '/posts/types/:slug/edit',
   '/posts/types/:slug/template',
@@ -80,6 +87,7 @@ export const RESERVED_COLLECTION_SLUGS: ReadonlySet<string> = new Set([
   'page-templates',
   'widgets',
   'jobs',
+  'appearance',
   'trash',
   'users',
   'settings',

package/src/router/index.ts

@@ -59,8 +59,12 @@ export function hasBlockingNavigation(): boolean {
  * in-app navigation prompts for confirmation (via navigate()) and a browser
  * unload/refresh shows the native "leave site?" prompt. The registration and
  * the beforeunload listener are torn down on unmount.
+ *
+ * Returns `release()`: call it right before a navigation the editor itself
+ * makes after saving (e.g. opening a just-created document). The dirty flag
+ * only clears on the next render, so without it that navigation would prompt.
  */
-export function useNavigationBlocker(isDirty: boolean): void {
+export function useNavigationBlocker(isDirty: boolean): () => void {
   const dirtyRef = useRef(isDirty)
   dirtyRef.current = isDirty
 
@@ -76,6 +80,10 @@ export function useNavigationBlocker(isDirty: boolean): void {
     window.addEventListener('beforeunload', onBeforeUnload)
     return () => window.removeEventListener('beforeunload', onBeforeUnload)
   }, [isDirty])
+
+  return useCallback(() => {
+    dirtyRef.current = false
+  }, [])
 }
 
 export function useAdminRouter(basePath = '/admin', serverPath = '/') {