@prenta/admin 0.92.0

package/src/lib/comments-client.ts

@@ -0,0 +1,208 @@
+/**
+ * Comments REST client — thin, typed wrapper around the
+ * `/documents/:id/comments` + `/comments/:id` endpoints shipped in slice 4
+ * of Phase 3 (see `packages/cms-core/src/realtime/comments.ts`).
+ *
+ * The client lives in `cms-admin` so the side panel, the bubble-menu
+ * "comment on selection" action, and any future MCP/AI hooks all share one
+ * request path, error model, and DTO shape.
+ *
+ * Mirrors the server contract:
+ *   POST   /documents/:documentId/comments     -> { body, anchor?, parentId? }
+ *   GET    /documents/:documentId/comments?…   -> { data: CommentDTO[] }
+ *   PATCH  /comments/:id                       -> { body }
+ *   POST   /comments/:id/resolve               -> 200 with updated DTO
+ *   POST   /comments/:id/reopen                -> 200 with updated DTO
+ *   DELETE /comments/:id                       -> 200 with soft-deleted DTO
+ */
+
+import { cmsApi } from './api.js'
+
+/**
+ * Yjs relative-position anchor returned by the server. The encoding is
+ * intentionally opaque on the wire (Base64 of `Y.encodeRelativePosition`);
+ * `lib/comment-anchor.ts` handles the round-trip when slice 5 paints a
+ * highlight in the editor.
+ */
+export interface CommentAnchor {
+  from: string
+  to: string
+}
+
+/**
+ * Public DTO returned by every comments endpoint. Mirrors `CommentDTO` in
+ * `@prenta/core/realtime`; we duplicate the shape here so
+ * `cms-admin` doesn't take a hard dependency on the server-side service
+ * layer (which carries Prisma types we don't want pulled into the bundle).
+ */
+export interface Comment {
+  id: string
+  documentId: string
+  parentId: string | null
+  userId: string | null
+  body: string
+  anchor: CommentAnchor | null
+  resolvedAt: string | null
+  resolvedById: string | null
+  deletedAt: string | null
+  createdAt: string
+  updatedAt: string
+  isResolved: boolean
+}
+
+export type CommentOutcome<T> =
+  | { ok: true; result: T }
+  | { ok: false; error: string; status: number }
+
+export interface CreateCommentInput {
+  documentId: string
+  body: string
+  anchor?: CommentAnchor | null
+  parentId?: string | null
+}
+
+export interface ListCommentsOptions {
+  /** Default: false. Resolved threads are filtered out unless requested. */
+  includeResolved?: boolean
+  /** Default: false. Admin-only; the server rejects non-admin callers. */
+  includeDeleted?: boolean
+  /** Default: server-side cap (100). Hard upper bound is 200. */
+  pageSize?: number
+}
+
+function encodeOptions(opts: ListCommentsOptions = {}): string {
+  const params = new URLSearchParams()
+  if (opts.includeResolved) params.set('includeResolved', 'true')
+  if (opts.includeDeleted) params.set('includeDeleted', 'true')
+  if (opts.pageSize !== undefined) params.set('pageSize', String(opts.pageSize))
+  const qs = params.toString()
+  return qs ? `?${qs}` : ''
+}
+
+function failure(error: string, status: number): { ok: false; error: string; status: number } {
+  return { ok: false, error, status }
+}
+
+function envelope<T>(res: { data?: unknown; error?: string; status: number }): CommentOutcome<T> {
+  if (res.error || res.data === undefined) {
+    return failure(res.error ?? `Request failed (${res.status})`, res.status)
+  }
+  return { ok: true, result: res.data as T }
+}
+
+/**
+ * Create a top-level comment or a reply. Pass `parentId` to thread the
+ * comment under an existing one — the server enforces single-level
+ * threading (replies cannot themselves be parents).
+ */
+export async function createComment(input: CreateCommentInput): Promise<CommentOutcome<Comment>> {
+  if (typeof input.documentId !== 'string' || input.documentId.length === 0) {
+    return failure('documentId is required', 0)
+  }
+  if (typeof input.body !== 'string' || input.body.trim().length === 0) {
+    return failure('Comment cannot be empty', 0)
+  }
+
+  const body: Record<string, unknown> = { body: input.body.trim() }
+  if (input.anchor) body.anchor = input.anchor
+  if (input.parentId) body.parentId = input.parentId
+
+  const res = await cmsApi<Comment>(`/documents/${encodeURIComponent(input.documentId)}/comments`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * List comments for a document. Active comments (not resolved, not deleted)
+ * are returned by default; pass `includeResolved` to keep resolved threads
+ * in the response. The server rejects `includeDeleted` for non-admins.
+ */
+export async function listComments(
+  documentId: string,
+  opts: ListCommentsOptions = {},
+): Promise<CommentOutcome<Comment[]>> {
+  if (typeof documentId !== 'string' || documentId.length === 0) {
+    return failure('documentId is required', 0)
+  }
+  const path = `/documents/${encodeURIComponent(documentId)}/comments${encodeOptions(opts)}`
+  const res = await cmsApi<Comment[]>(path, { method: 'GET' })
+  return envelope<Comment[]>(res)
+}
+
+/** Edit a comment body. Only the author or an admin is permitted. */
+export async function updateComment(id: string, body: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  if (typeof body !== 'string' || body.trim().length === 0) {
+    return failure('Comment cannot be empty', 0)
+  }
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ body: body.trim() }),
+  })
+  return envelope<Comment>(res)
+}
+
+/** Resolve a thread. Write-role or the author may resolve. */
+export async function resolveComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}/resolve`, {
+    method: 'POST',
+    body: '{}',
+  })
+  return envelope<Comment>(res)
+}
+
+/** Re-open a resolved thread. Same permission as resolve. */
+export async function reopenComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}/reopen`, {
+    method: 'POST',
+    body: '{}',
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * Soft-delete a comment. The row is preserved so its replies don't lose
+ * their thread root — the server simply stops returning it from the list
+ * endpoint unless an admin asks for `includeDeleted`.
+ */
+export async function deleteComment(id: string): Promise<CommentOutcome<Comment>> {
+  if (!id) return failure('comment id is required', 0)
+  const res = await cmsApi<Comment>(`/comments/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  })
+  return envelope<Comment>(res)
+}
+
+/**
+ * Sort comments into thread groups suitable for rendering. Roots are
+ * returned in chronological order; replies are ordered the same way and
+ * attached to their root. Replies whose root is missing (e.g. the root was
+ * filtered out by `includeResolved=false`) are dropped — the UI can fetch
+ * them explicitly if it needs to render orphaned replies.
+ */
+export interface CommentThread {
+  root: Comment
+  replies: Comment[]
+}
+
+export function groupCommentsIntoThreads(comments: readonly Comment[]): CommentThread[] {
+  const roots = new Map<string, CommentThread>()
+  const sorted = [...comments].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+
+  for (const c of sorted) {
+    if (c.parentId === null) {
+      roots.set(c.id, { root: c, replies: [] })
+    }
+  }
+  for (const c of sorted) {
+    if (c.parentId !== null) {
+      const root = roots.get(c.parentId)
+      if (root) root.replies.push(c)
+    }
+  }
+  return Array.from(roots.values())
+}

package/src/lib/cv.ts

@@ -0,0 +1,103 @@
+import clsx from 'clsx'
+
+/**
+ * Tiny in-house implementation of the `class-variance-authority` pattern
+ * (a.k.a. `cva` / `tailwind-variants`). We roll our own to avoid a runtime
+ * dependency while keeping the API surface compatible with the shadcn /
+ * cva ecosystem — anyone familiar with cva can read these calls.
+ *
+ * @example
+ *   const button = cv('inline-flex items-center', {
+ *     variants: {
+ *       intent: {
+ *         primary: 'bg-primary text-white',
+ *         secondary: 'bg-secondary text-foreground',
+ *       },
+ *       size: {
+ *         sm: 'px-2 py-1 text-xs',
+ *         md: 'px-4 py-2 text-sm',
+ *       },
+ *     },
+ *     defaultVariants: { intent: 'primary', size: 'md' },
+ *   })
+ *
+ *   button({ intent: 'secondary' })           // -> "inline-flex … bg-secondary …"
+ *   button({ intent: 'secondary', class: 'shadow' })  // append extras
+ */
+
+type ClassValue = string | undefined | false | null
+
+export type VariantsConfig = Record<string, Record<string, ClassValue>>
+
+type VariantSelection<V extends VariantsConfig> = {
+  [K in keyof V]?: keyof V[K]
+}
+
+interface CompoundVariant<V extends VariantsConfig> {
+  // Subset of variants that must match for the compound classes to apply.
+  // Use string values from each variant key (or arrays for "match any").
+  [key: string]: keyof V[keyof V] | Array<keyof V[keyof V]> | ClassValue
+  class?: ClassValue
+}
+
+export interface CvConfig<V extends VariantsConfig> {
+  variants: V
+  defaultVariants?: VariantSelection<V>
+  compoundVariants?: Array<CompoundVariant<V>>
+}
+
+export type VariantProps<F extends (...args: any) => any> = Omit<
+  NonNullable<Parameters<F>[0]>,
+  'class' | 'className'
+>
+
+/**
+ * Build a variant-aware class generator.
+ *
+ * The returned function accepts the variant selection plus an optional
+ * `class` / `className` escape hatch and returns the combined Tailwind
+ * class string. Compound variants run after the base + per-variant
+ * classes, so they take precedence when the Tailwind ordering matters.
+ */
+export function cv<V extends VariantsConfig>(base: ClassValue, config: CvConfig<V>) {
+  return function variantClass(
+    props?: VariantSelection<V> & { class?: ClassValue; className?: ClassValue },
+  ): string {
+    // Per the cva contract, an explicit `undefined` for a variant key must
+    // fall back to the default — spreading props naively would clobber the
+    // default and drop the variant's classes entirely (e.g. a Button without
+    // a `size` prop losing all height/padding).
+    const selected = { ...config.defaultVariants } as Record<string, unknown>
+    for (const [key, value] of Object.entries(props ?? {})) {
+      if (value !== undefined) selected[key] = value
+    }
+
+    const variantClasses: ClassValue[] = []
+    for (const [key, valuesMap] of Object.entries(config.variants)) {
+      const value = selected[key]
+      if (value === undefined || value === null) continue
+      const cls = valuesMap[value as string]
+      if (cls) variantClasses.push(cls)
+    }
+
+    const compoundClasses: ClassValue[] = []
+    if (config.compoundVariants) {
+      for (const compound of config.compoundVariants) {
+        const { class: cClass, className: _cn, ...match } = compound as any
+        const matches = Object.entries(match).every(([k, v]) => {
+          const current = selected[k]
+          if (Array.isArray(v)) return (v as unknown[]).includes(current)
+          return current === v
+        })
+        if (matches && cClass) compoundClasses.push(cClass as ClassValue)
+      }
+    }
+
+    return clsx(
+      base,
+      ...variantClasses,
+      ...compoundClasses,
+      (props?.class ?? props?.className) as ClassValue,
+    )
+  }
+}

package/src/lib/editor-preview.ts

@@ -0,0 +1,12 @@
+import type { AdminEditorConfig } from '@prenta/core'
+
+/** Resolve whether a section editor should open with Site preview active. */
+export function resolveDefaultSitePreview(
+  editor: AdminEditorConfig | undefined,
+  kind: 'pages' | 'posts',
+): boolean {
+  const setting = editor?.defaultSitePreview
+  if (setting === true) return true
+  if (setting == null || setting === false) return false
+  return kind === 'pages' ? setting.pages === true : setting.posts === true
+}

package/src/lib/editor-seo-content.ts

@@ -0,0 +1,144 @@
+import { getSectionType, type PageSection } from '@prenta/core/page-sections'
+import { analyzeContent } from '@prenta/core/seo/analysis'
+
+const HTML_LIKE = /<\/?[a-z][\s\S]*>/i
+
+/** Build an HTML-ish string from editor sections (+ optional post body) for SEO analysis. */
+export function buildEditorContentHtml(sections: PageSection[], body = ''): string {
+  const parts: string[] = []
+  if (body.trim()) parts.push(body)
+  for (const section of sections) {
+    if (section.visible === false) continue
+    const chunk = extractSectionContentHtml(section)
+    if (chunk) parts.push(chunk)
+  }
+  return parts.join('\n')
+}
+
+/** Live 0–100 SEO score from the current in-editor document state. */
+export function computeLiveSeoScore(input: {
+  title: string
+  slug: string
+  seoTitle: string
+  seoDescription: string
+  focusKeyword?: string
+  sections: PageSection[]
+  bodyHtml?: string
+}): number {
+  const content = buildEditorContentHtml(input.sections, input.bodyHtml ?? '')
+  return analyzeContent({
+    title: input.title,
+    slug: input.slug,
+    content,
+    metaTitle: input.seoTitle,
+    metaDescription: input.seoDescription,
+    focusKeyphrase: input.focusKeyword,
+  }).score
+}
+
+function extractSectionContentHtml(section: PageSection): string {
+  const content = section.content
+  if (!content || typeof content !== 'object') return ''
+  const def = getSectionType(section.sectionType)
+  const chunks: string[] = []
+
+  if (def) {
+    for (const field of def.fields) {
+      const val = content[field.key]
+      if (typeof val !== 'string' || !val.trim()) continue
+      if (field.type === 'richText' || HTML_LIKE.test(val)) {
+        chunks.push(val)
+      } else if (/heading|title|subtitle|eyebrow/i.test(field.key)) {
+        chunks.push(`<h2>${escapeHtml(val.trim())}</h2>`)
+      } else if (/body|content|text|copy|description|excerpt|quote|answer/i.test(field.key)) {
+        chunks.push(`<p>${escapeHtml(val.trim())}</p>`)
+      }
+    }
+  } else {
+    collectStringValues(content, chunks, 0)
+  }
+
+  return chunks.join('\n')
+}
+
+function collectStringValues(obj: Record<string, unknown>, chunks: string[], depth: number): void {
+  if (depth > 6) return
+  for (const value of Object.values(obj)) {
+    if (typeof value === 'string' && value.trim()) {
+      chunks.push(HTML_LIKE.test(value) ? value : `<p>${escapeHtml(value.trim())}</p>`)
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === 'object') {
+          collectStringValues(item as Record<string, unknown>, chunks, depth + 1)
+        }
+      }
+    } else if (value && typeof value === 'object') {
+      collectStringValues(value as Record<string, unknown>, chunks, depth + 1)
+    }
+  }
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+const STOP_WORDS = new Set([
+  'about',
+  'after',
+  'also',
+  'been',
+  'before',
+  'being',
+  'between',
+  'both',
+  'could',
+  'each',
+  'from',
+  'have',
+  'into',
+  'more',
+  'most',
+  'other',
+  'over',
+  'some',
+  'such',
+  'than',
+  'that',
+  'their',
+  'them',
+  'then',
+  'there',
+  'these',
+  'they',
+  'this',
+  'through',
+  'under',
+  'very',
+  'were',
+  'what',
+  'when',
+  'where',
+  'which',
+  'while',
+  'with',
+  'would',
+  'your',
+])
+
+/** Top content words for the Insights accordion (excluding common stop words). */
+export function prominentWordsFromText(plainText: string, limit = 8): string[] {
+  const counts = new Map<string, number>()
+  for (const raw of plainText.toLowerCase().split(/\s+/)) {
+    const word = raw.replace(/[^a-z0-9'-]/g, '')
+    if (word.length < 4 || STOP_WORDS.has(word)) continue
+    counts.set(word, (counts.get(word) ?? 0) + 1)
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([word]) => word)
+}

package/src/lib/favicon.ts

@@ -0,0 +1,46 @@
+/**
+ * Browser-tab favicon helpers for the admin SPA.
+ *
+ * The admin runs as a client app, so the favicon shown in the browser tab is
+ * whatever `<link rel="icon">` the document currently has. The Settings →
+ * Appearance favicon (stored in the CMS) is the source of truth, so the admin
+ * applies it at runtime instead of relying on the host app's `<head>` wiring.
+ */
+
+/**
+ * Window event the admin dispatches after the brand (logo/favicon) is saved so
+ * live surfaces — the browser tab favicon — refresh without a full reload.
+ */
+export const BRAND_UPDATED_EVENT = 'prenta:brand-updated'
+
+export interface FaviconUpdate {
+  /** The `<link rel="icon">` element that is now active. */
+  link: HTMLLinkElement
+  /** True when we created the link (so callers can remove it on cleanup). */
+  created: boolean
+  /** The href the link had before this update — for restore on cleanup. */
+  previousHref: string | null
+}
+
+/**
+ * Point the browser tab favicon at `href`, creating the `<link rel="icon">` when
+ * the document doesn't already have one. Returns enough state for the caller to
+ * restore/remove it on cleanup. Client-only — call inside an effect.
+ */
+export function setDocumentFavicon(href: string, type?: string | null): FaviconUpdate {
+  const existing = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
+  if (existing) {
+    const previousHref = existing.href || null
+    existing.href = href
+    existing.sizes = '32x32'
+    if (type) existing.type = type
+    return { link: existing, created: false, previousHref }
+  }
+  const link = document.createElement('link')
+  link.rel = 'icon'
+  link.href = href
+  link.sizes = '32x32'
+  if (type) link.type = type
+  document.head.appendChild(link)
+  return { link, created: true, previousHref: null }
+}

package/src/lib/forms-events.ts

@@ -0,0 +1,32 @@
+/**
+ * Forms event bus — a minimal pub/sub so views that mutate submission state
+ * (mark read/unread, star, archive) or form state (create, notify toggle,
+ * archive) can tell the sidebar to refresh its unread badges immediately,
+ * without threading a refresh callback through the whole component tree.
+ *
+ * Deliberately tiny and dependency-free: one event, synchronous fan-out,
+ * SSR-safe. Subscribers must unsubscribe on unmount via the returned
+ * disposer to avoid leaks.
+ */
+type Listener = () => void
+
+const listeners = new Set<Listener>()
+
+/** Subscribe to "forms data changed" notifications. Returns an unsubscribe fn. */
+export function onFormsChanged(listener: Listener): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+/** Notify all subscribers that forms/submission counts may have changed. */
+export function emitFormsChanged(): void {
+  for (const listener of listeners) {
+    try {
+      listener()
+    } catch {
+      // A misbehaving subscriber must not break sibling subscribers.
+    }
+  }
+}