@prenta/admin 2.6.1 → 2.8.0

package/src/layout/use-nav-items.ts

@@ -0,0 +1,40 @@
+'use client'
+
+import { useEffect, useMemo, useState } from 'react'
+import { fetchFormsSidebarCounts, type FormsSidebarCount } from '../lib/forms-service.js'
+import { onFormsChanged } from '../lib/forms-events.js'
+import { applyFormsNav, buildNavItems, type NavItem } from './nav-config.js'
+
+/**
+ * The nav tree with live Forms counts. Counts refresh on mount and whenever a
+ * forms/entries mutation fires the shared event (mark read, archive, notify
+ * toggle, …). Best-effort: a failed fetch keeps the last known value rather
+ * than surfacing an error in nav. Pass `enabled: false` to skip the fetch when
+ * the caller already has the items.
+ */
+export function useNavItems(config: any, enabled = true): NavItem[] {
+  const [forms, setForms] = useState<FormsSidebarCount[]>([])
+
+  useEffect(() => {
+    if (!enabled) return
+    let active = true
+    const load = () => {
+      fetchFormsSidebarCounts()
+        .then((counts) => {
+          // A malformed response must not break the nav.
+          if (active && Array.isArray(counts)) setForms(counts)
+        })
+        .catch(() => {
+          /* keep the last known value; nav must never break on a fetch error */
+        })
+    }
+    load()
+    const off = onFormsChanged(load)
+    return () => {
+      active = false
+      off()
+    }
+  }, [enabled])
+
+  return useMemo(() => applyFormsNav(buildNavItems(config), forms), [config, forms])
+}

package/src/lib/api.ts

@@ -76,6 +76,14 @@ export interface CmsApiResult<T> {
    * `/seo/autopilot/applied/:id/revert`). Callers must narrow it themselves.
    */
   errorBody?: unknown
+  /**
+   * The parsed 2xx body, for the few endpoints that send fields beside `data`
+   * (e.g. a job review decision's `documentStatus` and `notice`). Callers must
+   * narrow it themselves.
+   */
+  body?: unknown
+  /** The response's `ETag`, for endpoints that take `If-Match` on the next write. */
+  etag?: string
   status: number
 }
 
@@ -112,6 +120,10 @@ export async function cmsApi<T = unknown>(
     const res = await fetch(url, { ...options, headers, credentials: 'include' })
     const json = await res.json().catch(() => ({}))
 
+    // Test doubles often stub `fetch` with a bare `{ ok, json }`.
+    const etag =
+      typeof res.headers?.get === 'function' ? (res.headers.get('ETag') ?? undefined) : undefined
+
     if (!res.ok) {
       return {
         error: json.error || `Request failed (${res.status})`,
@@ -121,7 +133,12 @@ export async function cmsApi<T = unknown>(
       }
     }
 
-    return { data: json.data ?? json, status: res.status }
+    return {
+      data: json.data ?? json,
+      body: json,
+      status: res.status,
+      ...(etag ? { etag } : {}),
+    }
   } catch (err) {
     return { error: err instanceof Error ? err.message : 'Network error', status: 0 }
   }

package/src/lib/appearance-api.ts

@@ -4,6 +4,7 @@ import {
   type BrandAssetLike,
   type BrandSettings,
   type ColorMode,
+  type LightBase,
   type LogoShape,
   type SidebarDensity,
 } from '@prenta/core/appearance'
@@ -14,6 +15,8 @@ import type { AdminBrandCache, AppearanceSnapshot } from '../components/ThemePro
 export interface AppearanceApiResponse {
   appearance: {
     adminColorModeDefault: ColorMode
+    /** Absent on servers that predate the Linen base; treat as Porcelain. */
+    adminLightBase?: LightBase
     adminAccentColor: string
     sidebarDensity: SidebarDensity
     contentFont: string
@@ -83,6 +86,7 @@ export function appearanceApiToSnapshot(data: AppearanceApiResponse): Appearance
   const assets = parseAppearanceAssets(data.assets)
   return {
     theme: data.appearance.adminColorModeDefault,
+    lightBase: data.appearance.adminLightBase === 'linen' ? 'linen' : 'porcelain',
     accent: data.appearance.adminAccentColor,
     density: data.appearance.sidebarDensity,
     font: data.appearance.contentFont,

package/src/lib/batch-wizard.ts

@@ -0,0 +1,188 @@
+/**
+ * The New batch AI job wizard (jobs-new.jsx, TRACKING P-20): its sources,
+ * validation and request, kept apart from the component so they can be
+ * tested on their own. The server's rules are in cms-core `jobs/batch-ai.ts`
+ * and CONFLICTS.md §4 (P-16).
+ */
+import type {
+  BatchAiEstimate,
+  BatchAiPayload,
+  BatchAiRequest,
+  BatchAiTextField,
+} from '@prenta/core'
+import { JOB_OPS } from './job-view.js'
+
+export type BatchOperation = BatchAiPayload['operation']
+export type BatchOp = (typeof JOB_OPS)[number]
+
+/** Where a batch runs: a page or post collection, or the media library. */
+export interface BatchSource {
+  /** The collection's key in the config, or `media`. */
+  id: string
+  /** The kit's Content select label ("Posts", "Media library"). */
+  label: string
+}
+
+export const MEDIA_SOURCE: BatchSource = { id: 'media', label: 'Media library' }
+
+/**
+ * Documents picked in a list (P-21's "Run with AI…"). They run as they are,
+ * without the operation's "Only where" preset.
+ */
+export interface BatchSelection {
+  /** A collection key, or `media` for images picked in the media library. */
+  source: string
+  documentIds: string[]
+}
+
+/** A custom instruction needs more than 8 characters, and at most 2,000. */
+const INSTRUCTION_MIN = 9
+export const INSTRUCTION_MAX = 2000
+/** The most documents one batch freezes. */
+const BATCH_MAX = 1000
+
+/**
+ * The fields a custom instruction can rewrite. `field` isn't in the kit's
+ * contract; it's the kit's "Field you choose" (CONFLICTS.md §4, P-16).
+ */
+export const CUSTOM_FIELDS: ReadonlyArray<{ id: BatchAiTextField; label: string }> = [
+  { id: 'metaDescription', label: 'Meta description' },
+  { id: 'seoTitle', label: 'SEO title' },
+  { id: 'excerpt', label: 'Excerpt' },
+]
+
+export function batchOp(id: BatchOperation): BatchOp {
+  return JOB_OPS.find((op) => op.id === id) ?? JOB_OPS[0]
+}
+
+interface ConfigCollection {
+  slug?: string
+  type?: string
+  labels?: { plural?: string }
+  admin?: { hidden?: boolean }
+}
+
+/**
+ * The Content select's options: the config's page and post collections, in
+ * config order, without hidden ones (as Settings → AI's brand voice lists
+ * them). The media library is added for alt text only.
+ */
+export function batchSources(config: unknown): BatchSource[] {
+  const raw = (config as { collections?: unknown } | null | undefined)?.collections
+  if (!raw || typeof raw !== 'object') return []
+  const entries: Array<[string, ConfigCollection]> = Array.isArray(raw)
+    ? (raw as ConfigCollection[]).map((c) => [c.slug ?? '', c])
+    : Object.entries(raw as Record<string, ConfigCollection>)
+  return entries
+    .filter(([key, c]) => key && (c.type === 'page' || c.type === 'post') && !c.admin?.hidden)
+    .map(([key, c]) => ({
+      id: key,
+      label: c.labels?.plural ?? key.charAt(0).toUpperCase() + key.slice(1),
+    }))
+}
+
+/** cms-core's `ADMIN_ROLES`: who may queue a batch that applies changes automatically. */
+export function isAdminRole(role: string | null | undefined): boolean {
+  return role === 'OWNER' || role === 'ADMIN'
+}
+
+/** Alt text runs on images; every other operation on a collection. */
+export function runsOnMedia(operation: BatchOperation): boolean {
+  return operation === 'alt'
+}
+
+/** Whether an operation can run on a picked selection's source. */
+export function operationFits(
+  operation: BatchOperation,
+  selection: BatchSelection | null,
+): boolean {
+  if (!selection) return true
+  return runsOnMedia(operation) === (selection.source === MEDIA_SOURCE.id)
+}
+
+/** Everything the wizard asks, before it becomes a request. */
+export interface BatchDraft {
+  operation: BatchOperation
+  instruction: string
+  field: BatchAiTextField
+  /** The collection picked in the Content select (ignored for alt text). */
+  collection: string
+  statusFilter: 'published' | 'all'
+  review: 'review' | 'auto'
+  onApprove: 'draft' | 'publish'
+  selection: BatchSelection | null
+}
+
+/** The source a draft runs on: the media library for alt text, else its collection. */
+function draftSource(draft: Pick<BatchDraft, 'operation' | 'collection'>): string {
+  return runsOnMedia(draft.operation) ? MEDIA_SOURCE.id : draft.collection
+}
+
+/** Step 1's check: a custom instruction needs more than 8 characters (the server's message). */
+export function instructionError(operation: BatchOperation, instruction: string): string | null {
+  if (operation !== 'custom') return null
+  return instruction.trim().length < INSTRUCTION_MIN
+    ? 'A custom instruction needs more than 8 characters.'
+    : null
+}
+
+/**
+ * The request for estimate, preview and create. "Apply automatically" never
+ * publishes (the server refuses it), so it always sends `draft`.
+ */
+export function batchRequest(draft: BatchDraft): BatchAiRequest {
+  const instruction = draft.instruction.trim()
+  return {
+    operation: draft.operation,
+    source: draft.selection?.source ?? draftSource(draft),
+    statusFilter: draft.statusFilter,
+    review: draft.review,
+    onApprove: draft.review === 'auto' ? 'draft' : draft.onApprove,
+    instruction: instruction || null,
+    ...(draft.operation === 'custom' ? { field: draft.field } : {}),
+    ...(draft.selection ? { filter: { documentIds: draft.selection.documentIds } } : {}),
+  }
+}
+
+/**
+ * The fields that change which documents match, or what the AI writes. An
+ * estimate or preview is stale once its key differs from the draft's.
+ */
+export function estimateKey(request: BatchAiRequest): string {
+  return JSON.stringify([
+    request.operation,
+    request.source,
+    request.statusFilter,
+    request.filter?.documentIds ?? null,
+  ])
+}
+
+export function previewKey(request: BatchAiRequest): string {
+  return JSON.stringify([estimateKey(request), request.instruction, request.field ?? null])
+}
+
+/** Why step 2 can't continue: nothing matches, or more than a batch holds. Null when it can. */
+export function matchProblem(estimate: BatchAiEstimate): string | null {
+  if (estimate.count === 0) return 'No documents match this filter.'
+  if (estimate.count > BATCH_MAX) {
+    return `This matches ${estimate.count.toLocaleString('en-US')} documents. Narrow it to ${BATCH_MAX.toLocaleString('en-US')} or fewer.`
+  }
+  return null
+}
+
+/** The estimate tiles: "~42 min" and "~38k tokens", as the kit rounds them. */
+export function estimateTiles(estimate: BatchAiEstimate): { minutes: string; tokens: string } {
+  return {
+    minutes: `~${estimate.minutes.toLocaleString('en-US')} min`,
+    tokens: `~${Math.round(estimate.tokens / 1000).toLocaleString('en-US')}k tokens`,
+  }
+}
+
+/** The line under the tiles. The limit sentence is left out when Settings → AI sets none. */
+export function estimateNote(estimate: BatchAiEstimate): string {
+  const pace = 'One document per slice, about one a minute.'
+  const pct = estimate.pctOfMonthlyLimit
+  if (pct === null) return pace
+  const share = pct === 0 && estimate.tokens > 0 ? 'under 1' : String(pct)
+  return `${pace} That’s ${share}% of this month’s AI limit.`
+}

package/src/lib/chrome-service.ts

@@ -0,0 +1,200 @@
+/**
+ * Site chrome API (DATA_CONTRACTS §2) for Appearance → Header & Footer.
+ * Region values and the announcement come with an `ETag`; a save sends it as
+ * `If-Match`, so a stale form gets 412 instead of overwriting a newer save.
+ */
+import type {
+  Announcement,
+  ChromeOverridesList,
+  ChromeRegionName,
+  ChromeSettings,
+  ChromeSyncStatus,
+  RegionSchema,
+  RegionValues,
+} from '@prenta/core'
+
+import { cmsApi } from './api.js'
+
+export interface ChromeSchemaView {
+  regions: RegionSchema[]
+  sync: ChromeSyncStatus
+}
+
+/** A result the screen can show: the value, or why there isn't one. */
+export type ChromeResult<T> =
+  | { ok: true; value: T; etag: string | null }
+  | { ok: false; status: number; error: string }
+
+function result<T>(res: {
+  data?: T
+  error?: string
+  status: number
+  etag?: string
+}): ChromeResult<T> {
+  if (res.error !== undefined || res.data === undefined) {
+    return { ok: false, status: res.status, error: res.error ?? 'Request failed' }
+  }
+  return { ok: true, value: res.data, etag: res.etag ?? null }
+}
+
+function ifMatch(etag: string | null): Record<string, string> {
+  return etag ? { 'If-Match': etag } : {}
+}
+
+export async function fetchChromeSchema(): Promise<ChromeResult<ChromeSchemaView>> {
+  return result(await cmsApi<ChromeSchemaView>('/chrome/schema'))
+}
+
+/** 404 until the site has pushed the region's schema. */
+export async function fetchRegion(region: ChromeRegionName): Promise<ChromeResult<RegionValues>> {
+  return result(await cmsApi<RegionValues>(`/chrome/${region}`))
+}
+
+/** What `PUT /chrome/:region` takes. `fields` replaces every saved value. */
+export interface RegionSaveBody {
+  variant: string
+  fields: Record<string, unknown>
+}
+
+export async function saveRegion(
+  region: ChromeRegionName,
+  body: RegionSaveBody,
+  etag: string | null,
+): Promise<ChromeResult<RegionValues>> {
+  return result(
+    await cmsApi<RegionValues>(`/chrome/${region}`, {
+      method: 'PUT',
+      headers: ifMatch(etag),
+      body: JSON.stringify(body),
+    }),
+  )
+}
+
+/** "Remove now" on the orphan row. */
+export async function removeOrphan(
+  region: ChromeRegionName,
+  key: string,
+): Promise<ChromeResult<RegionValues>> {
+  return result(
+    await cmsApi<RegionValues>(`/chrome/${region}/orphans/${encodeURIComponent(key)}`, {
+      method: 'DELETE',
+    }),
+  )
+}
+
+export async function fetchAnnouncement(): Promise<ChromeResult<Announcement>> {
+  return result(await cmsApi<Announcement>('/chrome/announcement'))
+}
+
+/** What `PUT /chrome/announcement` takes. The server mints `id`. */
+export type AnnouncementSaveBody = Omit<Announcement, 'id'>
+
+export async function saveAnnouncement(
+  body: AnnouncementSaveBody,
+  etag: string | null,
+): Promise<ChromeResult<Announcement>> {
+  return result(
+    await cmsApi<Announcement>('/chrome/announcement', {
+      method: 'PUT',
+      headers: ifMatch(etag),
+      body: JSON.stringify(body),
+    }),
+  )
+}
+
+export async function fetchChromeSettings(): Promise<ChromeResult<ChromeSettings>> {
+  return result(await cmsApi<ChromeSettings>('/chrome/settings'))
+}
+
+/**
+ * Saves the keys sent; one left out stays as it is. `secret` comes back once,
+ * when the save creates the revalidate webhook.
+ */
+export async function saveChromeSettings(
+  body: Partial<ChromeSettings>,
+): Promise<ChromeResult<ChromeSettings & { secret?: string }>> {
+  return result(
+    await cmsApi<ChromeSettings & { secret?: string }>('/chrome/settings', {
+      method: 'PUT',
+      body: JSON.stringify(body),
+    }),
+  )
+}
+
+/** The pages whose `_layout` overrides a region. A core before 8.11 answers 404. */
+export async function fetchChromeOverrides(): Promise<ChromeResult<ChromeOverridesList>> {
+  return result(await cmsApi<ChromeOverridesList>('/chrome/overrides'))
+}
+
+/** A menu item as the form and the preview mock read it. */
+export interface ChromeMenuItem {
+  id: string
+  label: string
+  url: string
+  target?: '_blank' | '_self'
+  /** Shown as a button (the kit's "Show as button"). */
+  button: boolean
+  children: ChromeMenuItem[]
+}
+
+/** A menu a menu field can pick, by its slug. */
+export interface ChromeMenuOption {
+  slug: string
+  name: string
+  items: ChromeMenuItem[]
+}
+
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function menuItems(value: unknown, depth = 0): ChromeMenuItem[] {
+  if (!Array.isArray(value) || depth > 6) return []
+  const out: ChromeMenuItem[] = []
+  value.forEach((raw, index) => {
+    if (!raw || typeof raw !== 'object') return
+    const item = raw as Record<string, unknown>
+    const label = asText(item.label).trim()
+    if (!label) return
+    out.push({
+      id: asText(item.id) || `${depth}-${index}`,
+      label,
+      url: asText(item.url),
+      ...(item.target === '_blank' || item.target === '_self' ? { target: item.target } : {}),
+      button: item.button === true,
+      children: menuItems(item.children, depth + 1),
+    })
+  })
+  return out
+}
+
+/**
+ * Menus from the navigation plugin's `navigations` collection. Without the
+ * plugin there are none, and menu fields offer only what's saved.
+ */
+export async function fetchChromeMenus(): Promise<ChromeMenuOption[]> {
+  const res = await cmsApi<{
+    docs?: Array<{ slug?: string | null; title?: string | null; data?: unknown }>
+  }>('/collections/navigations?pageSize=100&sort=title&order=asc&pick=name,slug,items')
+  const menus: ChromeMenuOption[] = []
+  for (const doc of res.data?.docs ?? []) {
+    const data = (doc.data && typeof doc.data === 'object' ? doc.data : {}) as Record<
+      string,
+      unknown
+    >
+    const slug = asText(data.slug) || asText(doc.slug)
+    if (!slug || menus.some((menu) => menu.slug === slug)) continue
+    menus.push({
+      slug,
+      name: asText(data.name) || asText(doc.title) || slug,
+      items: menuItems(data.items),
+    })
+  }
+  return menus
+}
+
+/** The site title, for brand fields and the preview's logo. */
+export async function fetchSiteTitle(): Promise<string | null> {
+  const res = await cmsApi<{ siteTitle?: string | null }>('/appearance')
+  return typeof res.data?.siteTitle === 'string' && res.data.siteTitle ? res.data.siteTitle : null
+}