kilo-cms 0.1.0

package/src/admin/ScheduledEditor.tsx

@@ -0,0 +1,155 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { CmsSidebar } from './CmsSidebar'
+import { EditorHeader } from './EditorHeader'
+import { CloseButton } from './CloseButton'
+import { Portal } from './Portal'
+import { useToast } from './Toast'
+import { useLocalStorageState } from '../useLocalStorageState'
+import { CardListSkeleton } from './EditorSkeleton'
+import { Button } from './Button'
+import { monthGrid, parseISODate, toISODate, weekdayLabels } from '../calendar-grid'
+import type { CollectionSlug } from '../collections/types'
+
+type ScheduledPost = { id: string; title: string; slug: string; type: CollectionSlug; scheduledAt: string }
+type ViewPrefs = { view: 'list' | 'calendar' }
+// `labelSingular`/`titleField` per scheduling-enabled collection — resolved server-side (the
+// registry is never populated on the client, `defineKiloConfig()` is server-only) and passed
+// down as a prop, same pattern as `CollectionRecordEditor`'s `config` prop.
+export type ScheduledCollectionMeta = Record<CollectionSlug, { labelSingular: string; titleField: string }>
+
+function formatTime(value: string) { return new Date(value).toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' }) }
+function formatDayHeading(iso: string) { const date = parseISODate(iso); return date ? date.toLocaleDateString('en-US', { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' }) : iso }
+
+function groupByDay(posts: ScheduledPost[]) {
+  const map = new Map<string, ScheduledPost[]>()
+  for (const post of posts) {
+    const key = toISODate(new Date(post.scheduledAt))
+    const list = map.get(key)
+    if (list) list.push(post)
+    else map.set(key, [post])
+  }
+  return map
+}
+
+function ScheduledRow({ post, meta, onPublishNow, onUnschedule }: { post: ScheduledPost; meta: ScheduledCollectionMeta; onPublishNow: (post: ScheduledPost) => void; onUnschedule: (post: ScheduledPost) => void }) {
+  const overdue = new Date(post.scheduledAt) < new Date()
+  return <div className="cms-schedule-row">
+    <span className="cms-schedule-time">{formatTime(post.scheduledAt)}{overdue && <span className="cms-schedule-overdue" title="Past its scheduled time — waiting for the scheduler to run">Overdue</span>}</span>
+    <a className="cms-schedule-title" href={`/admin/collections/${post.type}/${post.id}`}>{post.title || 'Untitled'}</a>
+    <span className="cms-schedule-category">{meta[post.type]?.labelSingular ?? post.type}</span>
+    <div className="cms-schedule-actions">
+      <Button variant="positive" compact onClick={() => onPublishNow(post)}>Publish now</Button>
+      <Button variant="negative" compact onClick={() => onUnschedule(post)}>Unschedule</Button>
+    </div>
+  </div>
+}
+
+function CalendarMonth({ grouped, meta, onPublishNow, onUnschedule }: { grouped: Map<string, ScheduledPost[]>; meta: ScheduledCollectionMeta; onPublishNow: (post: ScheduledPost) => void; onUnschedule: (post: ScheduledPost) => void }) {
+  const [viewMonth, setViewMonth] = useState(() => new Date())
+  const [dayPopover, setDayPopover] = useState<{ dateKey: string; top: number; left: number } | null>(null)
+  const popoverRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!dayPopover) return
+    function handleOutside(event: MouseEvent) { if (!popoverRef.current?.contains(event.target as Node)) setDayPopover(null) }
+    function handleKey(event: globalThis.KeyboardEvent) { if (event.key === 'Escape') setDayPopover(null) }
+    document.addEventListener('mousedown', handleOutside)
+    document.addEventListener('keydown', handleKey)
+    return () => { document.removeEventListener('mousedown', handleOutside); document.removeEventListener('keydown', handleKey) }
+  }, [dayPopover])
+
+  function openDay(dateKey: string, element: HTMLElement) {
+    const rect = element.getBoundingClientRect()
+    setDayPopover({ dateKey, top: rect.bottom + 6, left: Math.max(8, Math.min(rect.left, window.innerWidth - 300)) })
+  }
+
+  const cells = monthGrid(viewMonth)
+  const todayIso = toISODate(new Date())
+
+  return <div className="cms-schedule-calendar">
+    <div className="cms-schedule-cal-header">
+      <Button variant="secondary" iconOnly compact onClick={() => setViewMonth((current) => new Date(current.getFullYear(), current.getMonth() - 1, 1))} aria-label="Previous month" icon="‹" />
+      <strong>{viewMonth.toLocaleDateString('en-US', { month: 'long', year: 'numeric' })}</strong>
+      <Button variant="secondary" iconOnly compact onClick={() => setViewMonth((current) => new Date(current.getFullYear(), current.getMonth() + 1, 1))} aria-label="Next month" icon="›" />
+      <Button variant="secondary" compact className="cms-schedule-today" onClick={() => setViewMonth(new Date())}>Today</Button>
+    </div>
+    <div className="cms-schedule-cal-weekdays">{weekdayLabels.map((day) => <span key={day}>{day}</span>)}</div>
+    <div className="cms-schedule-cal-grid">{cells.map((date, index) => {
+      if (!date) return <div className="cms-schedule-cal-cell is-empty" key={index} />
+      const iso = toISODate(date)
+      const dayPosts = grouped.get(iso) ?? []
+      const visible = dayPosts.slice(0, 3)
+      const extra = dayPosts.length - visible.length
+      return <div className={`cms-schedule-cal-cell ${iso === todayIso ? 'is-today' : ''}`} key={index}>
+        <span className="cms-schedule-cal-date">{date.getDate()}</span>
+        {visible.map((post) => <button type="button" key={post.id} className={`cms-schedule-chip ${new Date(post.scheduledAt) < new Date() ? 'is-overdue' : ''}`} onClick={(event) => openDay(iso, event.currentTarget)}>{formatTime(post.scheduledAt)} {post.title || 'Untitled'}</button>)}
+        {extra > 0 && <button type="button" className="cms-schedule-more" onClick={(event) => openDay(iso, event.currentTarget)}>+{extra} more</button>}
+      </div>
+    })}</div>
+    {dayPopover && <Portal><div ref={popoverRef} className="cms-schedule-day-popover" style={{ position: 'fixed', top: dayPopover.top, left: dayPopover.left }}>
+      <div className="cms-schedule-day-popover-header"><strong>{formatDayHeading(dayPopover.dateKey)}</strong><CloseButton onClick={() => setDayPopover(null)} label="Close" /></div>
+      {(grouped.get(dayPopover.dateKey) ?? []).map((post) => <ScheduledRow key={post.id} post={post} meta={meta} onPublishNow={onPublishNow} onUnschedule={onUnschedule} />)}
+    </div></Portal>}
+  </div>
+}
+
+export function ScheduledEditor({ userName, scheduledSlugs, meta }: { userName: string; scheduledSlugs: CollectionSlug[]; meta: ScheduledCollectionMeta }) {
+  const toast = useToast()
+  const [posts, setPosts] = useState<ScheduledPost[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState('')
+  const [reloadKey, setReloadKey] = useState(0)
+  const [prefs, setPrefs] = useLocalStorageState<ViewPrefs>('cms-scheduled-view', { view: 'list' })
+
+  useEffect(() => {
+    setLoading(true)
+    const params = new URLSearchParams({
+      filters: JSON.stringify([{ field: 'published', operator: 'is', value: 'scheduled' }]),
+      pageSize: 'all', sortBy: 'scheduledAt', sortDir: 'asc',
+    })
+    Promise.all(scheduledSlugs.map((slug) =>
+      fetch(`/api/admin/collections/${slug}?${params}`)
+        .then((response) => (response.ok ? response.json() : { items: [] }))
+        .then((data: { items: Array<Record<string, unknown>> }) => data.items.map((item) => ({
+          id: String(item.id),
+          title: String(item[meta[slug]?.titleField ?? 'id'] ?? ''),
+          slug: String(item.slug ?? ''),
+          type: slug,
+          scheduledAt: String(item.scheduledAt),
+        }))),
+    ))
+      .then((groups) => { setPosts(groups.flat().sort((a, b) => a.scheduledAt.localeCompare(b.scheduledAt))); setError('') })
+      .catch(() => setError('Could not load scheduled content'))
+      .finally(() => setLoading(false))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reloadKey])
+
+  async function publishNow(post: ScheduledPost) {
+    const response = await fetch(`/api/admin/collections/${post.type}/${post.id}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ published: true }) })
+    if (response.ok) { toast.success(`${meta[post.type]?.labelSingular ?? post.type} published live.`); setReloadKey((key) => key + 1) } else toast.error('Could not publish.')
+  }
+  async function unschedule(post: ScheduledPost) {
+    const response = await fetch(`/api/admin/collections/${post.type}/${post.id}/unschedule`, { method: 'PATCH' })
+    if (response.ok) { toast.success('Schedule removed.'); setReloadKey((key) => key + 1) } else toast.error('Could not remove schedule.')
+  }
+
+  const grouped = groupByDay(posts)
+  const dayKeys = [...grouped.keys()].sort()
+
+  return <main className="cms-dashboard"><CmsSidebar active="scheduled" userName={userName} /><section className="cms-content">
+    <EditorHeader compact title="Scheduled Publishing" meta={error || `${posts.length} upcoming`} actions={
+      <div className="cms-tabs cms-tabs-inline"><button className={prefs.view === 'list' ? 'active' : ''} onClick={() => setPrefs({ view: 'list' })}>List</button><button className={prefs.view === 'calendar' ? 'active' : ''} onClick={() => setPrefs({ view: 'calendar' })}>Calendar</button></div>
+    } />
+    {loading ? <CardListSkeleton /> : prefs.view === 'list'
+      ? <div className="cms-schedule-list">
+          {dayKeys.map((dayKey) => <section className="cms-schedule-day" key={dayKey}>
+            <h3>{formatDayHeading(dayKey)}</h3>
+            {grouped.get(dayKey)!.map((post) => <ScheduledRow key={post.id} post={post} meta={meta} onPublishNow={publishNow} onUnschedule={unschedule} />)}
+          </section>)}
+          {!dayKeys.length && <p className="cms-empty-state">Nothing scheduled yet.</p>}
+        </div>
+      : <CalendarMonth grouped={grouped} meta={meta} onPublishNow={publishNow} onUnschedule={unschedule} />}
+  </section></main>
+}

package/src/admin/SeoSettingsEditor.tsx

@@ -0,0 +1,53 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { EditorHeader } from './EditorHeader'
+import { EditorSkeleton } from './EditorSkeleton'
+import { Field, TextAreaField, TextField } from './Field'
+import { CmsSidebar } from './CmsSidebar'
+import { ImageUploader } from './ImageUploader'
+import { useToast } from './Toast'
+import { useCmsSiteSettings } from './CmsSiteSettingsProvider'
+import { Button } from './Button'
+import { normalizeCmsAppearance, type CmsAppearance } from '../cms-appearance'
+import { defaultPublishingWorkflow, normalizePublishingWorkflow, type PublishingWorkflow } from '../publishing-workflow'
+
+type Settings = { siteName: string; logoLight: string | null; logoDark: string | null; metaTitle: string; metaDescription: string; metaImage: string | null; cmsAppearance: CmsAppearance; publishingWorkflow: PublishingWorkflow }
+const empty = (): Settings => ({ siteName: 'Kilo CMS', logoLight: null, logoDark: null, metaTitle: '', metaDescription: '', metaImage: null, cmsAppearance: normalizeCmsAppearance(null), publishingWorkflow: defaultPublishingWorkflow })
+
+export function SeoSettingsEditor({ userName }: { userName: string }) {
+  const toast = useToast()
+  const { setSettings: setCmsSiteSettings } = useCmsSiteSettings()
+  const [settings, setSettings] = useState<Settings>(empty)
+  const [status, setStatus] = useState('Loading settings…')
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => { fetch('/api/admin/settings').then(async (response) => { if (!response.ok) throw new Error(); return response.json() }).then((data) => { setSettings({ siteName: data.siteName ?? 'Kilo CMS', logoLight: data.logoLight ?? null, logoDark: data.logoDark ?? null, metaTitle: data.metaTitle ?? '', metaDescription: data.metaDescription ?? '', metaImage: data.metaImage ?? null, cmsAppearance: normalizeCmsAppearance(data.cmsAppearance), publishingWorkflow: normalizePublishingWorkflow(data.publishingWorkflow) }); setStatus('Loaded') }).catch(() => setStatus('Could not load settings')).finally(() => setLoading(false)) }, [])
+
+  function update<K extends keyof Settings>(key: K, value: Settings[K]) { setSettings((current) => ({ ...current, [key]: value })) }
+  async function save() {
+    setStatus('Saving…')
+    try {
+      const response = await fetch('/api/admin/settings', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(settings) })
+      const data = await response.json()
+      if (!response.ok) throw new Error(data.error)
+      setSettings(data)
+      setCmsSiteSettings({ siteName: data.siteName, logoLight: data.logoLight ?? null, logoDark: data.logoDark ?? null, publishingWorkflow: normalizePublishingWorkflow(data.publishingWorkflow) })
+      setStatus('Saved')
+      toast.success('Settings saved.')
+    } catch (error) { const message = error instanceof Error ? error.message : 'Could not save settings'; setStatus(message); toast.error(message) }
+  }
+
+  return <main className="cms-dashboard"><CmsSidebar active="settings" userName={userName} /><section className="cms-content">
+    <EditorHeader compact title="SEO settings" backHref="/admin/dashboard" backLabel="Dashboard" />
+    {loading ? <EditorSkeleton sections={1} /> : <div className="cms-editor-layout"><div className="cms-editor-form">
+      <section className="cms-section">
+        <div className="cms-section-heading"><p className="section-label">SEO defaults</p><p>Used for any page, service, or project that doesn’t set its own SEO fields.</p></div>
+        <TextField label="Default meta title" value={settings.metaTitle} onChange={(event) => update('metaTitle', event.target.value)} hint="Falls back to the site name when empty." placeholder="The Usual — Ideas with a pulse" />
+        <TextAreaField label="Default meta description" rows={4} value={settings.metaDescription} onChange={(event) => update('metaDescription', event.target.value)} hint="Shown in search results and social previews when a page has none of its own." />
+        <TextField label="Default social image URL" hint="Optional when uploading" type="url" value={settings.metaImage ?? ''} onChange={(event) => update('metaImage', event.target.value || null)} placeholder="https://…" />
+        <Field label="Upload default social image" hint="JPEG, PNG, or WebP — used for link previews (Open Graph)"><ImageUploader value={settings.metaImage ?? ''} onChange={(url) => update('metaImage', url)} /></Field>
+      </section>
+    </div><aside className="cms-editor-sidebar"><p>{status}</p><Button variant="primary" type="button" onClick={save} icon="↗">Save settings</Button></aside></div>}
+  </section></main>
+}

package/src/admin/SingleRecordEditor.tsx

@@ -0,0 +1,215 @@
+'use client'
+
+import { useEffect, useState, type ReactNode } from 'react'
+import { CmsSidebar } from './CmsSidebar'
+import { EditorHeader } from './EditorHeader'
+import { EditorSkeleton } from './EditorSkeleton'
+import { ContentEditorForm } from './ContentEditorForm'
+import { ContentViewSettings as ContentViewSettingsModal } from './ContentViewSettings'
+import { DynamicField } from './DynamicField'
+import { Button } from './Button'
+import { PublishingPanel, type ReviewStatus } from './PublishingPanel'
+import { RecordMeta } from './RecordMeta'
+import { useToast } from './Toast'
+import { useCmsLocales } from './CmsLocalesProvider'
+import { formatDateTime } from '../format'
+import { contentViewField, defaultContentViewFor, type ContentViewSettings as ContentViewConfig } from '../collections/content-view'
+import { relationFields } from '../collections/registry'
+import { emptyRecord, isFieldVisible } from '../collections/values'
+import { workflowColumnKeys, type SelectOption, type SingleConfig } from '../collections/types'
+
+type Row = Record<string, unknown>
+type UserOption = { id: string; name: string }
+type SavingState = 'draft' | 'publish' | 'unpublish' | 'workflow' | null
+const recordSignature = (row: Row) => JSON.stringify(Object.fromEntries(Object.entries(row).filter(([key]) => key !== 'id' && key !== 'createdAt' && key !== 'updatedAt' && !(workflowColumnKeys as readonly string[]).includes(key))))
+
+export function SingleRecordEditor({ config, userName, currentUserId, canUpdate, canPublish, allowedFields, canConfigureViews }: {
+  config: SingleConfig
+  userName: string
+  currentUserId: string
+  canUpdate: boolean
+  canPublish: boolean
+  allowedFields: string[]
+  canConfigureViews: boolean
+}) {
+  // The server page already resolved `config` (registry lookups only work server-side —
+  // `defineKiloConfig()` never runs on the client) and passes it down as a prop; `type` is
+  // just a local alias so every existing `type`-referencing line below keeps working unchanged.
+  const type = config.slug
+  const toast = useToast()
+  const localeConfig = useCmsLocales()
+  const [record, setRecord] = useState<Row>(() => emptyRecord(config, localeConfig))
+  const [view, setView] = useState<ContentViewConfig>(() => defaultContentViewFor(config))
+  const [relationOptions, setRelationOptions] = useState<Record<string, SelectOption[]>>({})
+  const [errors, setErrors] = useState<Record<string, string>>({})
+  const [saving, setSaving] = useState<SavingState>(null)
+  const [loading, setLoading] = useState(true)
+  const [status, setStatus] = useState('Loading…')
+  const [savedSignature, setSavedSignature] = useState<string | null>(null)
+  const [savedPublished, setSavedPublished] = useState(false)
+  const [viewSettingsOpen, setViewSettingsOpen] = useState(false)
+  const [users, setUsers] = useState<UserOption[]>([])
+  const [backTarget, setBackTarget] = useState<{ href: string; label: string } | null>(null)
+
+  useEffect(() => {
+    // Single types have no list page of their own to "go back" to — link back to the first
+    // collection the user can see (or another single type) so the back button always lands
+    // somewhere with the full Content nav, instead of pointing at this same page.
+    Promise.all([
+      fetch('/api/admin/collections').then((response) => response.ok ? response.json() : []).catch(() => []),
+      fetch('/api/admin/singles').then((response) => response.ok ? response.json() : []).catch(() => []),
+    ]).then(([collections, singles]: [Array<{ slug: string; label: string }>, Array<{ slug: string; label: string }>]) => {
+      const firstCollection = collections[0]
+      const firstOtherSingle = singles.find((single) => single.slug !== type)
+      if (firstCollection) setBackTarget({ href: `/admin/collections/${firstCollection.slug}`, label: 'All content' })
+      else if (firstOtherSingle) setBackTarget({ href: `/admin/single/${firstOtherSingle.slug}`, label: 'All content' })
+      else setBackTarget({ href: '/admin/dashboard', label: 'Dashboard' })
+    })
+    fetch(`/api/admin/content-views/${type}`).then((response) => response.ok ? response.json() : null).then((data) => { if (data) setView(data) }).catch(() => {})
+    if (config.workflow?.audit) fetch('/api/admin/users').then((response) => response.ok ? response.json() : []).then(setUsers).catch(() => {})
+    Promise.all(relationFields(config).map((field) =>
+      fetch(`/api/admin/collections/${field.relationTo}/options`).then((response) => response.ok ? response.json() : []).then((options: SelectOption[]) => [field.key, options] as const),
+    )).then((entries) => setRelationOptions(Object.fromEntries(entries))).catch(() => {})
+    setLoading(true)
+    fetch(`/api/admin/single/${type}`)
+      .then(async (response) => { if (!response.ok) throw new Error(); return response.json() })
+      .then((data: Row) => { applyServer(data); setStatus(Boolean(data.published) ? 'Published' : 'Draft') })
+      .catch(() => setStatus(`Could not load ${config.label.toLowerCase()}`))
+      .finally(() => setLoading(false))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [type])
+
+  function update(key: string, value: unknown) {
+    setRecord((current) => ({ ...current, [key]: value }))
+    setErrors((current) => {
+      if (!(key in current)) return current
+      const next = { ...current }
+      delete next[key]
+      return next
+    })
+  }
+
+  function validate(): Record<string, string> {
+    const next: Record<string, string> = {}
+    for (const field of config.fields) {
+      if (field.readOnly || !field.required) continue
+      const value = record[field.key]
+      if (value === null || value === undefined || value === '') next[field.key] = 'This field is required.'
+    }
+    setErrors(next)
+    return next
+  }
+
+  function applyServer(data: Row) {
+    setRecord(data)
+    setSavedSignature(recordSignature(data))
+    setSavedPublished(Boolean(data.published))
+  }
+
+  async function save(publish = false, kind: SavingState = publish ? 'publish' : 'draft') {
+    const validationErrors = !config.workflow?.publish || publish ? validate() : {}
+    if (Object.keys(validationErrors).length) {
+      const names = Object.keys(validationErrors).map((key) => contentViewField(view, key)?.label || config.fields.find((field) => field.key === key)?.label || key)
+      toast.error(`Cannot ${publish ? 'publish' : 'save'}. Check: ${names.join(', ')}.`)
+      return
+    }
+    setSaving(kind)
+    setStatus(publish ? 'Publishing…' : kind === 'unpublish' ? 'Unpublishing…' : 'Saving draft…')
+    try {
+      const response = await fetch(`/api/admin/single/${type}`, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(config.workflow?.publish ? { ...record, published: publish } : record) })
+      const body = await response.text()
+      const data = body ? JSON.parse(body) : null
+      if (!response.ok) throw new Error(data?.error || `Save failed (status ${response.status})`)
+      applyServer(data)
+      setStatus(publish ? 'Published live' : kind === 'unpublish' ? 'Unpublished — saved as draft' : 'Saved as draft')
+      toast.success(publish ? `${config.label} published live.` : kind === 'unpublish' ? `${config.label} unpublished and moved to draft.` : `${config.label} saved.`)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : `Could not save ${config.label.toLowerCase()}`
+      setStatus(message)
+      toast.error(message)
+    } finally {
+      setSaving(null)
+    }
+  }
+
+  async function saveView(next: ContentViewConfig) {
+    const response = await fetch(`/api/admin/content-views/${type}`, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(next) })
+    const data = await response.json()
+    if (!response.ok) throw new Error(data.error || 'Could not save view settings.')
+    setView(data)
+    toast.success(`${config.label} view settings saved.`)
+  }
+
+  const dirty = savedSignature !== null && savedSignature !== recordSignature(record)
+  const createdByName = users.find((item) => item.id === record.createdBy)?.name ?? null
+  const updatedByName = users.find((item) => item.id === record.updatedBy)?.name ?? null
+
+  const fields: Record<string, ReactNode> = Object.fromEntries(
+    config.fields
+      .filter((field) => !field.hidden && isFieldVisible(field, record) && (field.readOnly || allowedFields.includes(field.key)))
+      .map((field) => [field.key, (
+        <DynamicField
+          key={field.key}
+          field={field}
+          value={record[field.key]}
+          onChange={(value) => update(field.key, value)}
+          label={contentViewField(view, field.key)?.label || field.label}
+          hint={contentViewField(view, field.key)?.description || field.hint}
+          error={errors[field.key]}
+          disabled={!canUpdate}
+          relationOptions={field.type === 'relation' ? relationOptions[field.key] : undefined}
+        />
+      )]),
+  )
+
+  const sidePanel = config.workflow?.publish ? (
+    <PublishingPanel
+      published={savedPublished}
+      dirty={dirty}
+      saving={saving}
+      message={status}
+      publishedAt={record.publishedAt as string | null | undefined}
+      onSaveDraft={() => void save(false)}
+      onPublish={() => void save(true)}
+      onUnpublish={canPublish ? () => void save(false, 'unpublish') : undefined}
+      reviewStatus="draft"
+      requiresApproval={false}
+    />
+  ) : (
+    <div className="cms-editor-sidebar-stack">
+      <aside className="cms-editor-sidebar">
+        <div className="cms-publishing-heading"><span>{config.label}</span></div>
+        <div className="cms-publishing-summary">{dirty && <span className="cms-unsaved-status">Unsaved changes</span>}</div>
+        <div className="cms-publishing-actions">
+          <Button variant="positive" disabled={saving !== null || !canUpdate} onClick={() => void save(false)}>{saving ? 'Saving…' : 'Save'}</Button>
+        </div>
+        <p className="cms-ai-status">{status}</p>
+      </aside>
+      <aside className="cms-content-records">
+        <div className="cms-records-heading"><strong>Record</strong></div>
+        <section className="cms-record-section">
+          <div className="cms-meta-list">
+            <div><span>ID</span><strong>{String(record.id ?? '—')}</strong></div>
+            <div><span>Created</span><strong>{formatDateTime(record.createdAt as string)}</strong></div>
+            {config.touchUpdatedAt && <div><span>Last updated</span><strong>{formatDateTime(record.updatedAt as string)}</strong></div>}
+          </div>
+        </section>
+      </aside>
+    </div>
+  )
+
+  return <main className="cms-dashboard">
+    <CmsSidebar active="singles" userName={userName} contentContext={{ title: config.label, backHref: backTarget?.href ?? '/admin/dashboard', backLabel: backTarget?.label ?? 'Dashboard', settings: view }} />
+    <section className="cms-content">
+      <EditorHeader
+        compact
+        title={config.label}
+        backHref={backTarget?.href ?? '/admin/dashboard'}
+        backLabel={backTarget?.label ?? 'Dashboard'}
+        actions={canConfigureViews ? <Button type="button" variant="secondary" className="cms-view-settings-button" icon="⚙" iconPosition="before" onClick={() => setViewSettingsOpen(true)}>View settings</Button> : undefined}
+      />
+      {loading ? <EditorSkeleton /> : <div className="cms-editor-layout"><ContentEditorForm settings={view} fields={fields} groupExtras={{ record: <RecordMeta createdByName={createdByName} updatedByName={updatedByName} /> }} />{sidePanel}</div>}
+    </section>
+    {viewSettingsOpen && <ContentViewSettingsModal title={config.label} value={view} onClose={() => setViewSettingsOpen(false)} onSave={saveView} />}
+  </main>
+}

package/src/admin/SiteSettingsEditor.tsx

@@ -0,0 +1,96 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { EditorHeader } from './EditorHeader'
+import { EditorSkeleton } from './EditorSkeleton'
+import { CheckboxGroupField, Field, TextField } from './Field'
+import { CmsSidebar } from './CmsSidebar'
+import { ImageUploader } from './ImageUploader'
+import { useToast } from './Toast'
+import { formatDateTime } from '../format'
+import { useCmsSiteSettings } from './CmsSiteSettingsProvider'
+import { useCmsTheme } from './CmsThemeProvider'
+import { Button } from './Button'
+import { cmsAppearancePresets, cmsColorKeys, cmsSizeKeys, normalizeCmsAppearance, resolvedAppearanceTokens, type CmsAppearance, type CmsColorKey, type CmsSizeKey } from '../cms-appearance'
+import { allApprovalContentTypes, defaultPublishingWorkflow, normalizePublishingWorkflow, type ApprovalContentType, type PublishingWorkflow } from '../publishing-workflow'
+import { contentTypeDefs } from '../content-types'
+
+type Settings = { siteName: string; logoLight: string | null; logoDark: string | null; metaTitle: string; metaDescription: string; metaImage: string | null; cmsAppearance: CmsAppearance; publishingWorkflow: PublishingWorkflow; createdAt?: string; updatedAt?: string }
+type Errors = Partial<Record<'siteName', string>>
+const empty = (): Settings => ({ siteName: 'Kilo CMS', logoLight: null, logoDark: null, metaTitle: '', metaDescription: '', metaImage: null, cmsAppearance: normalizeCmsAppearance(null), publishingWorkflow: defaultPublishingWorkflow })
+
+const colorLabels: Record<CmsColorKey, string> = { ink: 'Foreground', paper: 'Page background', acid: 'Accent', acidHover: 'Accent hover', acidInk: 'Accent text', muted: 'Muted text', line: 'Borders', danger: 'Danger', dangerSoft: 'Danger soft', canvas: 'Canvas', surface: 'Surface', surfaceSoft: 'Soft surface' }
+const sizeLabels: Record<CmsSizeKey, string> = { radius: 'Radius', radiusSm: 'Small radius', space1: 'Space 1', space2: 'Space 2', space3: 'Space 3', space4: 'Space 4', space5: 'Space 5' }
+const approvalOptions = allApprovalContentTypes.map((value) => ({ value, label: contentTypeDefs[value]?.label ?? value }))
+
+function CmsAppearanceEditor({ value, onChange }: { value: CmsAppearance; onChange: (value: CmsAppearance) => void }) {
+  const [mode, setMode] = useState<'light' | 'dark'>('light')
+  const tokens = resolvedAppearanceTokens(value, mode)
+  function choosePreset(preset: string) { onChange({ preset, light: {}, dark: {} }) }
+  function updateColor(key: CmsColorKey, next: string) { if (!/^#[0-9a-fA-F]{6}$/.test(next)) return; onChange({ ...value, [mode]: { ...value[mode], [key]: next } }) }
+  function updateSize(key: CmsSizeKey, next: string) { const amount = Number(next); if (!Number.isFinite(amount)) return; onChange({ ...value, [mode]: { ...value[mode], [key]: Math.max(0, Math.min(64, Math.round(amount))) } }) }
+  return <section className="cms-section cms-appearance-section">
+    <div className="cms-section-heading"><p className="section-label">CMS theme</p><p>Choose a starting palette, then override every colour, radius, and spacing token. This changes the CMS only.</p></div>
+    <div className="cms-theme-presets">{cmsAppearancePresets.map((preset) => <button type="button" key={preset.id} className={`cms-theme-preset ${value.preset === preset.id ? 'is-selected' : ''}`} onClick={() => choosePreset(preset.id)}><span className="cms-theme-swatch" style={{ background: preset.light.acid }} /><strong>{preset.name}</strong><small>{preset.description}</small></button>)}</div>
+    <div className="cms-theme-token-head"><div className="cms-tabs cms-tabs-inline"><Button variant="secondary" compact className={mode === 'light' ? 'active' : ''} onClick={() => setMode('light')}>Light tokens</Button><Button variant="secondary" compact className={mode === 'dark' ? 'active' : ''} onClick={() => setMode('dark')}>Dark tokens</Button></div><Button variant="ghost" compact onClick={() => onChange({ ...value, [mode]: {} })}>Reset {mode} overrides</Button></div>
+    <div className="cms-theme-token-grid">{cmsColorKeys.map((key) => <label className="cms-theme-token" key={key}><span>{colorLabels[key]}</span><input type="color" aria-label={`${colorLabels[key]} colour`} value={tokens[key]} onChange={(event) => updateColor(key, event.target.value)} /><input value={tokens[key]} onChange={(event) => updateColor(key, event.target.value)} spellCheck={false} /></label>)}</div>
+    <div className="cms-theme-size-grid">{cmsSizeKeys.map((key) => <TextField key={key} label={sizeLabels[key]} type="number" min="0" max="64" value={tokens[key]} onChange={(event) => updateSize(key, event.target.value)} hint="px" />)}</div>
+  </section>
+}
+
+export function SiteSettingsEditor({ userName }: { userName: string }) {
+  const toast = useToast()
+  const { setSettings: setCmsSiteSettings } = useCmsSiteSettings()
+  const { theme, preference, setPreference, setAppearance } = useCmsTheme()
+  const [settings, setSettings] = useState<Settings>(empty)
+  const [status, setStatus] = useState('Loading settings…')
+  const [errors, setErrors] = useState<Errors>({})
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => { fetch('/api/admin/settings').then(async (response) => { if (!response.ok) throw new Error(); return response.json() }).then((data) => { setSettings({ siteName: data.siteName ?? 'Kilo CMS', logoLight: data.logoLight ?? null, logoDark: data.logoDark ?? null, metaTitle: data.metaTitle ?? '', metaDescription: data.metaDescription ?? '', metaImage: data.metaImage ?? null, cmsAppearance: normalizeCmsAppearance(data.cmsAppearance), publishingWorkflow: normalizePublishingWorkflow(data.publishingWorkflow), createdAt: data.createdAt, updatedAt: data.updatedAt }); setStatus('Loaded') }).catch(() => setStatus('Could not load settings')).finally(() => setLoading(false)) }, [])
+
+  function update<K extends keyof Settings>(key: K, value: Settings[K]) { setSettings((current) => ({ ...current, [key]: value })); if (key === 'siteName') setErrors((current) => ({ ...current, siteName: undefined })) }
+  function validate() { const next: Errors = {}; if (!settings.siteName.trim()) next.siteName = 'Site name is required.'; setErrors(next); return !Object.keys(next).length }
+  async function save() {
+    if (!validate()) { setStatus('Fix the highlighted fields'); toast.error('Complete the required fields before saving settings.'); return }
+    setStatus('Saving…')
+    try {
+      const response = await fetch('/api/admin/settings', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(settings) })
+      const data = await response.json()
+      if (!response.ok) throw new Error(data.error)
+      setSettings(data)
+      setCmsSiteSettings({ siteName: data.siteName, logoLight: data.logoLight ?? null, logoDark: data.logoDark ?? null, publishingWorkflow: normalizePublishingWorkflow(data.publishingWorkflow) })
+      setStatus('Saved')
+      toast.success('Settings saved.')
+    } catch (error) { const message = error instanceof Error ? error.message : 'Could not save settings'; setStatus(message); toast.error(message) }
+  }
+
+  return <main className="cms-dashboard"><CmsSidebar active="settings" userName={userName} /><section className="cms-content">
+    <EditorHeader compact title="Site settings" backHref="/admin/dashboard" backLabel="Dashboard" />
+    {loading ? <EditorSkeleton sections={1} /> : <div className="cms-editor-layout"><div className="cms-editor-form">
+      <section className="cms-section">
+        <div className="cms-section-heading"><p className="section-label">Site</p><p>Name and logo used across the CMS and the public site.</p></div>
+        <TextField label="Site name" required value={settings.siteName} onChange={(event) => update('siteName', event.target.value)} error={errors.siteName} hint="Shown in the browser tab title, e.g. “Page title — Site name”." />
+        <div className="cms-two-columns">
+          <Field label="Logo (light mode)" hint="Square image recommended (PNG or WebP)"><ImageUploader value={settings.logoLight ?? ''} onChange={(url) => update('logoLight', url || null)} aspect={1} label="Choose logo" /></Field>
+          <Field label="Logo (dark mode)" hint="Optional — falls back to the light mode logo when left blank"><ImageUploader value={settings.logoDark ?? ''} onChange={(url) => update('logoDark', url || null)} aspect={1} label="Choose logo" /></Field>
+        </div>
+      </section>
+      <section className="cms-section">
+        <div className="cms-section-heading"><p className="section-label">Appearance</p><p>Personal preference for this CMS browser session. It does not change the public website theme.</p></div>
+        <Field label="Theme" hint={preference === 'system' ? `Following your device — currently ${theme} mode` : `Currently using ${theme} mode`}>
+          <div className="cms-tabs cms-tabs-inline">
+            <Button type="button" variant="secondary" compact className={preference === 'light' ? 'active' : ''} onClick={() => setPreference('light')}>Light</Button>
+            <Button type="button" variant="secondary" compact className={preference === 'dark' ? 'active' : ''} onClick={() => setPreference('dark')}>Dark</Button>
+            <Button type="button" variant="secondary" compact className={preference === 'system' ? 'active' : ''} onClick={() => setPreference('system')}>System</Button>
+          </div>
+        </Field>
+      </section>
+      <section className="cms-section">
+        <div className="cms-section-heading"><p className="section-label">Publishing workflow</p><p>Choose which content types must pass review and approval before they can go live. Unticked types can publish directly.</p></div>
+        <CheckboxGroupField label="Require approval before publish" hint="This rule is enforced by the CMS API, including direct publish requests." value={settings.publishingWorkflow.approvalRequired} onChange={(approvalRequired) => update('publishingWorkflow', { approvalRequired: approvalRequired.filter((item): item is ApprovalContentType => (allApprovalContentTypes as string[]).includes(item)) })} options={approvalOptions} />
+      </section>
+      <CmsAppearanceEditor value={settings.cmsAppearance} onChange={(cmsAppearance) => { update('cmsAppearance', cmsAppearance); setAppearance(cmsAppearance) }} />
+    </div><aside className="cms-editor-sidebar"><p>{status}</p><Button variant="primary" type="button" onClick={save} icon="↗">Save settings</Button><div className="cms-meta-list"><div><span>Created</span><span>{formatDateTime(settings.createdAt)}</span></div><div><span>Updated</span><span>{formatDateTime(settings.updatedAt)}</span></div></div></aside></div>}
+  </section></main>
+}

package/src/admin/Toast.tsx

@@ -0,0 +1,45 @@
+'use client'
+
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+
+export type ToastType = 'success' | 'error' | 'warning' | 'info'
+type ToastInput = { message: string; type?: ToastType; duration?: number }
+type ToastItem = ToastInput & { id: string; type: ToastType }
+type ToastContextValue = { show: (input: ToastInput) => void; success: (message: string) => void; error: (message: string) => void; warning: (message: string) => void; info: (message: string) => void }
+
+const ToastContext = createContext<ToastContextValue | null>(null)
+
+function ToastIcon({ type }: { type: ToastType }) {
+  if (type === 'success') return <span aria-hidden="true">✓</span>
+  if (type === 'error') return <span aria-hidden="true">!</span>
+  if (type === 'warning') return <span aria-hidden="true">!</span>
+  return <span aria-hidden="true">i</span>
+}
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<ToastItem[]>([])
+  const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>())
+  const dismiss = useCallback((id: string) => {
+    const timer = timers.current.get(id)
+    if (timer) clearTimeout(timer)
+    timers.current.delete(id)
+    setToasts((items) => items.filter((item) => item.id !== id))
+  }, [])
+  const show = useCallback((input: ToastInput) => {
+    const id = crypto.randomUUID()
+    const toast: ToastItem = { ...input, id, type: input.type ?? 'info' }
+    setToasts((items) => [...items, toast].slice(-4))
+    const duration = input.duration ?? (toast.type === 'error' ? 6500 : 4000)
+    timers.current.set(id, setTimeout(() => dismiss(id), duration))
+  }, [dismiss])
+  useEffect(() => () => { timers.current.forEach((timer) => clearTimeout(timer)) }, [])
+  const value = useMemo<ToastContextValue>(() => ({ show, success: (message) => show({ message, type: 'success' }), error: (message) => show({ message, type: 'error' }), warning: (message) => show({ message, type: 'warning' }), info: (message) => show({ message, type: 'info' }) }), [show])
+
+  return <ToastContext.Provider value={value}>{children}<div className="cms-toast-region" aria-live="polite" aria-atomic="true">{toasts.map((toast) => <div className={`cms-toast is-${toast.type}`} key={toast.id} role={toast.type === 'error' ? 'alert' : 'status'}><span className="cms-toast-icon"><ToastIcon type={toast.type} /></span><p>{toast.message}</p><button type="button" onClick={() => dismiss(toast.id)} aria-label="Dismiss notification">×</button></div>)}</div></ToastContext.Provider>
+}
+
+export function useToast() {
+  const context = useContext(ToastContext)
+  if (!context) throw new Error('useToast must be used inside ToastProvider.')
+  return context
+}