@prenta/admin 2.7.0 → 2.8.0

package/src/views/header-footer/chrome-form.ts

@@ -0,0 +1,603 @@
+/**
+ * Pure helpers for Appearance → Header & Footer: form values built from the
+ * region schema (never from a fixed field list), save bodies, the page
+ * override chips, and the draft chrome the preview renders.
+ */
+import type {
+  Announcement,
+  AnnouncementTone,
+  ChromePageOverrides,
+  ChromeRegionName,
+  FieldDef,
+  RegionSchema,
+  RegionSchemaSource,
+  RegionValues,
+} from '@prenta/core'
+
+import type {
+  AnnouncementSaveBody,
+  ChromeMenuItem,
+  ChromeMenuOption,
+  RegionSaveBody,
+} from '../../lib/chrome-service.js'
+
+/** The announcement message limit (DATA_CONTRACTS §2). */
+export const ANNOUNCEMENT_MAX = 110
+/** The link text limit `PUT /chrome/announcement` enforces. */
+export const ANNOUNCEMENT_LINK_MAX = 40
+/** How many menus a list field holds when the schema sets no `max` (core's `MAX_MENU_LIST`). */
+const MENU_LIST_MAX = 20
+
+/**
+ * The menu pickers a list field shows: three to start (the kit's footer
+ * columns), one more than the list holds as it fills, up to `max`, and never
+ * fewer than are saved, so every saved menu can be cleared.
+ */
+export function menuListSlots(def: { max?: number }, length: number): number {
+  const max = def.max ?? MENU_LIST_MAX
+  return Math.max(length, Math.min(max, Math.max(3, length + 1)))
+}
+
+export const ANNOUNCEMENT_TONES: ReadonlyArray<{ id: AnnouncementTone; label: string }> = [
+  { id: 'brand', label: 'Brand' },
+  { id: 'dark', label: 'Dark' },
+  { id: 'alert', label: 'Alert' },
+]
+
+export const SOCIAL_PLATFORMS = ['LinkedIn', 'Facebook', 'Instagram', 'X', 'YouTube', 'TikTok']
+
+export interface RegionForm {
+  variant: string
+  fields: Record<string, unknown>
+}
+
+type Rec = Record<string, unknown>
+
+function isRec(value: unknown): value is Rec {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function str(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+/** A schema's fields in the order the site wrote them, own properties only. */
+export function fieldEntries(schema: Pick<RegionSchema, 'fields'>): Array<[string, FieldDef]> {
+  return Object.keys(schema.fields)
+    .filter((key) => Object.hasOwn(schema.fields, key))
+    .map((key) => [key, schema.fields[key]!])
+}
+
+/** Optional fields store `{ on, ...value }` and show a switch. */
+export function isToggled(def: FieldDef): boolean {
+  if (def.type === 'menu') return Boolean(def.optional) && !def.list
+  return (def.type === 'link' || def.type === 'text') && Boolean(def.optional)
+}
+
+/** The field types this admin can edit. A newer schema may send others. */
+const KNOWN_TYPES = new Set([
+  'brand',
+  'menu',
+  'link',
+  'text',
+  'textarea',
+  'select',
+  'boolean',
+  'social',
+])
+
+export function isKnownField(def: FieldDef): boolean {
+  return KNOWN_TYPES.has((def as { type: string }).type)
+}
+
+/** `topMenu` → "Top menu", for fields without a `label`. */
+export function humanizeKey(key: string): string {
+  const words = key
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .trim()
+    .toLowerCase()
+  return words ? words[0]!.toUpperCase() + words.slice(1) : key
+}
+
+export function fieldLabel(key: string, def: FieldDef): string {
+  return def.label?.trim() || humanizeKey(key)
+}
+
+/** The help line under a field's label: the schema's, or what the CMS fills in. */
+export function fieldHelp(def: FieldDef): string | null {
+  if (def.help?.trim()) return def.help.trim()
+  if (def.type === 'text' && def.tokens?.includes('{year}')) return '{year} updates automatically.'
+  if (def.type === 'menu' && def.list) {
+    return `Up to ${def.max ?? MENU_LIST_MAX} menus. Column headings use the menu name.`
+  }
+  return null
+}
+
+/** What a field shows when nothing is saved, in the stored shape. */
+function defaultValue(def: FieldDef): unknown {
+  switch (def.type) {
+    case 'menu':
+      if (def.list) return def.default ? [def.default] : []
+      return def.optional ? { on: false, value: def.default ?? '' } : (def.default ?? '')
+    case 'link':
+      return def.optional ? { on: false, label: '', url: '' } : { label: '', url: '' }
+    case 'text':
+      return def.optional ? { on: false, value: '' } : ''
+    case 'textarea':
+      return ''
+    case 'select':
+      return def.default ?? def.options[0] ?? ''
+    case 'boolean':
+      return def.default ?? false
+    case 'social':
+      return []
+    default:
+      return undefined
+  }
+}
+
+/** A saved value in the shape the field edits, or its default when it doesn't fit. */
+function formValue(def: FieldDef, saved: unknown): unknown {
+  if (saved === undefined) return defaultValue(def)
+  switch (def.type) {
+    case 'menu':
+      if (def.list) {
+        return Array.isArray(saved) ? saved.filter((slug) => typeof slug === 'string') : []
+      }
+      if (def.optional) {
+        return isRec(saved) && typeof saved.on === 'boolean'
+          ? { on: saved.on, value: str(saved.value) }
+          : defaultValue(def)
+      }
+      return typeof saved === 'string' ? saved : defaultValue(def)
+    case 'link': {
+      const link = isRec(saved) ? { label: str(saved.label), url: str(saved.url) } : null
+      if (!link) return defaultValue(def)
+      return def.optional ? { on: isRec(saved) && saved.on === true, ...link } : link
+    }
+    case 'text':
+      if (def.optional) {
+        return isRec(saved) && typeof saved.on === 'boolean'
+          ? { on: saved.on, value: str(saved.value) }
+          : defaultValue(def)
+      }
+      return typeof saved === 'string' ? saved : ''
+    case 'textarea':
+      return typeof saved === 'string' ? saved : ''
+    case 'select':
+      return typeof saved === 'string' && def.options.includes(saved) ? saved : defaultValue(def)
+    case 'boolean':
+      return typeof saved === 'boolean' ? saved : defaultValue(def)
+    case 'social':
+      return Array.isArray(saved)
+        ? saved.filter(isRec).map((item) => ({ platform: str(item.platform), url: str(item.url) }))
+        : []
+    default:
+      // A type this admin doesn't know: keep what's saved and send it back.
+      return saved
+  }
+}
+
+/** The form for a region: the saved variant and every field, defaults filled in. */
+export function regionForm(schema: RegionSchema, values: RegionValues | null): RegionForm {
+  const variants = Object.keys(schema.variants)
+  const variant =
+    values && Object.hasOwn(schema.variants, values.variant) ? values.variant : (variants[0] ?? '')
+  const fields: Rec = {}
+  for (const [key, def] of fieldEntries(schema)) {
+    if (def.type === 'brand') continue
+    const saved = values && Object.hasOwn(values.fields, key) ? values.fields[key] : undefined
+    const value = formValue(def, saved)
+    if (value !== undefined) fields[key] = value
+  }
+  return { variant, fields }
+}
+
+/**
+ * The value `PUT /chrome/:region` stores for one field. A required menu or
+ * link left empty is left out (the site then gets its default or null), and
+ * empty rows are dropped from lists.
+ */
+function saveValue(def: FieldDef, value: unknown): unknown {
+  switch (def.type) {
+    case 'menu':
+      if (def.list) {
+        return Array.isArray(value)
+          ? [...new Set(value.filter((slug): slug is string => typeof slug === 'string' && !!slug))]
+          : []
+      }
+      if (def.optional) return value
+      return typeof value === 'string' && value ? value : null
+    case 'link':
+      if (def.optional) return value
+      return isRec(value) && (str(value.url).trim() || str(value.label).trim()) ? value : null
+    case 'social':
+      return Array.isArray(value)
+        ? value.filter((row) => isRec(row) && (str(row.url).trim() || str(row.platform).trim()))
+        : []
+    default:
+      return value
+  }
+}
+
+/**
+ * The `PUT /chrome/:region` body. A field with nothing saved whose value is
+ * still its default is left out, so the site keeps following the default in
+ * its code if the developer changes it later.
+ */
+export function regionSaveBody(
+  schema: RegionSchema,
+  form: RegionForm,
+  saved: Record<string, unknown> = {},
+): RegionSaveBody {
+  const fields: Rec = {}
+  for (const [key, def] of fieldEntries(schema)) {
+    if (def.type === 'brand' || !Object.hasOwn(form.fields, key)) continue
+    if (!Object.hasOwn(saved, key) && sameValue(form.fields[key], defaultValue(def))) continue
+    const value = saveValue(def, form.fields[key])
+    if (value !== null && value !== undefined) fields[key] = value
+  }
+  return { variant: form.variant, fields }
+}
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+const PHONE = /^[+()0-9.\-\s]{3,40}$/
+const LINK_PROBLEM = 'Links can be a site path or an http(s), mailto or tel link.'
+
+function linkProblem(value: unknown, required: boolean): string | null {
+  if (!isRec(value)) return null
+  const url = str(value.url).trim()
+  if (str(value.label).length > 80) return 'Keep the button text to 80 characters.'
+  if (!url) return required ? 'Add the link URL.' : null
+  return isSafeLinkUrl(url) ? null : LINK_PROBLEM
+}
+
+/**
+ * Why a field's value can't be saved, or null. Mirrors the checks
+ * `PUT /chrome/:region` makes, so the form says what's wrong before a 400.
+ */
+export function fieldProblem(def: FieldDef, value: unknown): string | null {
+  switch (def.type) {
+    case 'menu':
+      if (def.list) {
+        const max = def.max ?? MENU_LIST_MAX
+        return Array.isArray(value) && value.filter(Boolean).length > max
+          ? `Pick at most ${max} menus.`
+          : null
+      }
+      if (def.optional && isRec(value) && value.on && !str(value.value)) {
+        return 'Pick a menu, or turn this off.'
+      }
+      return null
+    case 'link':
+      if (def.optional) return isRec(value) ? linkProblem(value, value.on === true) : null
+      return isRec(value) && (str(value.label).trim() || str(value.url).trim())
+        ? linkProblem(value, true)
+        : null
+    case 'text': {
+      const text = def.optional ? (isRec(value) ? str(value.value) : '') : str(value)
+      const max = def.max ?? 500
+      if (text.length > max) return `Keep it to ${max} characters.`
+      const trimmed = text.trim()
+      if (trimmed && def.format === 'email' && !EMAIL.test(trimmed))
+        return 'Enter an email address.'
+      if (trimmed && def.format === 'tel' && !PHONE.test(trimmed)) return 'Enter a phone number.'
+      return null
+    }
+    case 'textarea': {
+      const max = def.max ?? 2000
+      return str(value).length > max ? `Keep it to ${max} characters.` : null
+    }
+    case 'social':
+      if (!Array.isArray(value)) return null
+      for (const row of value) {
+        if (!isRec(row) || !(str(row.url).trim() || str(row.platform).trim())) continue
+        if (!str(row.platform).trim()) return 'Pick a platform for each link.'
+        const problem = linkProblem({ label: '', url: row.url }, true)
+        if (problem) return problem
+      }
+      return null
+    default:
+      return null
+  }
+}
+
+/** Every field that can't be saved yet, by key. */
+export function regionProblems(schema: RegionSchema, form: RegionForm): Record<string, string> {
+  const problems: Record<string, string> = {}
+  for (const [key, def] of fieldEntries(schema)) {
+    const problem = fieldProblem(def, form.fields[key])
+    if (problem) problems[key] = problem
+  }
+  return problems
+}
+
+/** Forms are built in schema order, so JSON compares them faithfully. */
+export function sameValue(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+// ─── Announcement ───────────────────────────────────────────────────────
+
+export interface AnnouncementForm {
+  on: boolean
+  text: string
+  linkLabel: string
+  linkUrl: string
+  tone: AnnouncementTone
+  dismissible: boolean
+  scheduled: boolean
+  /** `datetime-local` values, in the editor's time zone. */
+  startsAt: string
+  endsAt: string
+  /**
+   * The saved times. A `datetime-local` value can't tell the two 1:30s of a
+   * clock-change night apart, so an untouched field sends these back as they were.
+   */
+  savedStartsAt: string | null
+  savedEndsAt: string | null
+}
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0')
+}
+
+/** An ISO time as a `datetime-local` value in the browser's zone. */
+export function toLocalInput(iso: string | null): string {
+  if (!iso) return ''
+  const at = new Date(iso)
+  if (Number.isNaN(at.getTime())) return ''
+  return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}T${pad(at.getHours())}:${pad(at.getMinutes())}`
+}
+
+/**
+ * A `datetime-local` value (local time, no zone) as the ISO time with a zone
+ * the API needs, or null when it's empty or not a time.
+ */
+export function fromLocalInput(value: string, saved: string | null = null): string | null {
+  if (!value) return null
+  if (saved && toLocalInput(saved) === value) return saved
+  const at = new Date(value)
+  return Number.isNaN(at.getTime()) ? null : at.toISOString()
+}
+
+export function announcementForm(announcement: Announcement): AnnouncementForm {
+  return {
+    on: announcement.on,
+    text: announcement.text,
+    linkLabel: announcement.link?.label ?? '',
+    linkUrl: announcement.link?.url ?? '',
+    tone: announcement.tone,
+    dismissible: announcement.dismissible,
+    scheduled: announcement.schedule !== null,
+    startsAt: toLocalInput(announcement.schedule?.startsAt ?? null),
+    endsAt: toLocalInput(announcement.schedule?.endsAt ?? null),
+    savedStartsAt: announcement.schedule?.startsAt ?? null,
+    savedEndsAt: announcement.schedule?.endsAt ?? null,
+  }
+}
+
+export function announcementSaveBody(form: AnnouncementForm): AnnouncementSaveBody {
+  const url = form.linkUrl.trim()
+  const startsAt = form.scheduled ? fromLocalInput(form.startsAt, form.savedStartsAt) : null
+  const endsAt = form.scheduled ? fromLocalInput(form.endsAt, form.savedEndsAt) : null
+  return {
+    on: form.on,
+    text: form.text,
+    link: url || form.linkLabel.trim() ? { label: form.linkLabel, url } : null,
+    tone: form.tone,
+    dismissible: form.dismissible,
+    schedule: startsAt || endsAt ? { startsAt, endsAt } : null,
+  }
+}
+
+/** Why the announcement can't be saved yet, or null. Mirrors the API's checks. */
+export function announcementProblem(form: AnnouncementForm): string | null {
+  if (form.text.length > ANNOUNCEMENT_MAX) {
+    return `Keep the message to ${ANNOUNCEMENT_MAX} characters.`
+  }
+  if (form.on && !form.text.trim()) return 'Add a message before turning the bar on.'
+  if (form.linkLabel.length > ANNOUNCEMENT_LINK_MAX) {
+    return `Keep the link text to ${ANNOUNCEMENT_LINK_MAX} characters.`
+  }
+  if (form.linkLabel.trim() && !form.linkUrl.trim())
+    return 'Add the link URL, or clear the link text.'
+  if (form.linkUrl.trim() && !isSafeLinkUrl(form.linkUrl.trim())) {
+    return 'Links can be a site path or an http(s), mailto or tel link.'
+  }
+  if (form.scheduled) {
+    const starts = fromLocalInput(form.startsAt, form.savedStartsAt)
+    const ends = fromLocalInput(form.endsAt, form.savedEndsAt)
+    if (!starts && !ends) return 'Pick when the bar starts or ends, or turn the schedule off.'
+    if (starts && ends && Date.parse(ends) <= Date.parse(starts)) {
+      return 'The end has to be after the start.'
+    }
+  }
+  return null
+}
+
+/** Links an editor may set (the API's `isSafeLinkUrl`). */
+function isSafeLinkUrl(url: string): boolean {
+  if (url.length > 2048) return false
+  if (url.startsWith('/') || url.startsWith('#') || url.startsWith('?')) return true
+  return /^(https?:\/\/|mailto:|tel:)/i.test(url)
+}
+
+// ─── Page overrides ─────────────────────────────────────────────────────
+
+/**
+ * The mono chips for one page's override of one region, as the kit writes
+ * them: `header:minimal`, `header.cta: off`, `footer: none`.
+ */
+export function overrideChips(page: ChromePageOverrides, region: ChromeRegionName): string[] {
+  const override = page[region]
+  if (override === undefined) return []
+  if (override === null) return [`${region}: none`]
+  const chips: string[] = []
+  if (override.variant) chips.push(`${region}:${override.variant}`)
+  for (const [key, value] of Object.entries(override.fields ?? {})) {
+    chips.push(isRec(value) && value.on === false ? `${region}.${key}: off` : `${region}.${key}`)
+  }
+  return chips.length > 0 ? chips : [`${region}: inherits`]
+}
+
+// ─── Source card ────────────────────────────────────────────────────────
+
+/** `./src/components/site/Header.astro` → `src/components/site/Header.astro`. */
+export function componentPath(component: string): string {
+  return component.replace(/^\.\//, '')
+}
+
+export function shortCommit(commit: string): string {
+  return /^[0-9a-f]{8,}$/i.test(commit) ? commit.slice(0, 7) : commit
+}
+
+/**
+ * "View in repo ↗". `prenta push chrome` stores the repo as `owner/name`
+ * without its host, so this assumes GitHub; a full http(s) URL passed with
+ * `--repo` is used as it is.
+ */
+export function repoFileUrl(source: RegionSchemaSource, component: string): string | null {
+  const repo = source.repo.trim()
+  const path = componentPath(component).split('/').filter(Boolean).map(encodeURIComponent).join('/')
+  const ref = encodeURIComponent(source.commit || source.branch || 'HEAD')
+  if (/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+    return `https://github.com/${repo}/blob/${ref}/${path}`
+  }
+  if (/^https?:\/\//i.test(repo)) {
+    try {
+      const url = new URL(repo.replace(/\.git$/, ''))
+      url.pathname = `${url.pathname.replace(/\/+$/, '')}/blob/${ref}/${path}`
+      return url.toString()
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/** "just now", "5 minutes ago", "2 hours ago", "3 days ago", then the date. */
+export function timeAgo(iso: string | null | undefined, now: number): string {
+  if (!iso) return 'never'
+  const at = Date.parse(iso)
+  if (!Number.isFinite(at)) return 'never'
+  const seconds = Math.max(0, Math.round((now - at) / 1000))
+  const plural = (n: number, unit: string) => `${n} ${unit}${n === 1 ? '' : 's'} ago`
+  if (seconds < 60) return 'just now'
+  if (seconds < 3600) return plural(Math.floor(seconds / 60), 'minute')
+  if (seconds < 86_400) return plural(Math.floor(seconds / 3600), 'hour')
+  if (seconds < 30 * 86_400) return plural(Math.floor(seconds / 86_400), 'day')
+  return new Date(at).toLocaleDateString(undefined, {
+    day: 'numeric',
+    month: 'short',
+    year: 'numeric',
+  })
+}
+
+// ─── Draft chrome for the preview ───────────────────────────────────────
+
+/** A menu as the site's components receive it (`ChromeMenu`). */
+interface PreviewMenu {
+  id: string
+  name: string
+  items: Array<{ label: string; url: string; target?: '_blank' | '_self'; children?: unknown[] }>
+}
+
+function publicItems(items: ChromeMenuItem[]): PreviewMenu['items'] {
+  return items.map((item) => ({
+    label: item.label,
+    url: item.url,
+    ...(item.target ? { target: item.target } : {}),
+    ...(item.children.length > 0 ? { children: publicItems(item.children) } : {}),
+  }))
+}
+
+function publicMenu(menus: ChromeMenuOption[], slug: unknown): PreviewMenu | null {
+  const menu = typeof slug === 'string' && slug ? menus.find((m) => m.slug === slug) : undefined
+  return menu ? { id: menu.slug, name: menu.name, items: publicItems(menu.items) } : null
+}
+
+export interface PreviewContext {
+  menus: ChromeMenuOption[]
+  siteTitle: string
+  now: Date
+}
+
+/**
+ * One field as `/public/chrome` would send it, so a Preview URL page can
+ * render the site's real components with the draft. Brand logos aren't
+ * resolved here (null); the site name is.
+ */
+function publicField(def: FieldDef, value: unknown, ctx: PreviewContext): unknown {
+  switch (def.type) {
+    case 'brand':
+      return def.key === 'logo' ? null : ctx.siteTitle
+    case 'menu':
+      if (def.list) {
+        return (Array.isArray(value) ? value : [])
+          .map((slug) => publicMenu(ctx.menus, slug))
+          .filter(Boolean)
+      }
+      if (def.optional) return isRec(value) && value.on ? publicMenu(ctx.menus, value.value) : null
+      return publicMenu(ctx.menus, value || def.default)
+    case 'link': {
+      if (def.optional && !(isRec(value) && value.on)) return null
+      return isRec(value) && str(value.url)
+        ? { label: str(value.label), url: str(value.url) }
+        : null
+    }
+    case 'text': {
+      const year = String(ctx.now.getFullYear())
+      const fill = (text: string) =>
+        def.tokens?.includes('{year}') ? text.split('{year}').join(year) : text
+      if (def.optional) return isRec(value) && value.on ? fill(str(value.value)) : null
+      return fill(str(value))
+    }
+    default:
+      return value
+  }
+}
+
+export interface PreviewChrome {
+  header?: { variant: string; fields: Rec } | null
+  footer?: { variant: string; fields: Rec } | null
+  announcement: {
+    id: string
+    text: string
+    link: { label: string; url: string } | null
+    tone: AnnouncementTone
+    dismissible: boolean
+    endsAt: string | null
+  } | null
+}
+
+/** The draft as the `/public/chrome` shape, for `postMessage` to a Preview URL page. */
+export function previewChrome(
+  regions: Partial<Record<ChromeRegionName, { schema: RegionSchema; form: RegionForm }>>,
+  announcement: { id: string; form: AnnouncementForm } | null,
+  ctx: PreviewContext,
+): PreviewChrome {
+  const out: PreviewChrome = { announcement: null }
+  for (const [region, entry] of Object.entries(regions) as Array<
+    [ChromeRegionName, { schema: RegionSchema; form: RegionForm }]
+  >) {
+    const fields: Rec = {}
+    for (const [key, def] of fieldEntries(entry.schema)) {
+      fields[key] = publicField(def, entry.form.fields[key] ?? defaultValue(def), ctx)
+    }
+    out[region] = { variant: entry.form.variant, fields }
+  }
+  if (announcement && announcement.form.on && announcement.form.text.trim()) {
+    const body = announcementSaveBody(announcement.form)
+    out.announcement = {
+      id: announcement.id,
+      text: body.text,
+      link: body.link?.url ? body.link : null,
+      tone: body.tone,
+      dismissible: body.dismissible,
+      endsAt: body.schedule?.endsAt ?? null,
+    }
+  }
+  return out
+}