@actuate-media/cms-admin 0.26.0 → 0.27.0

package/src/components/ThemeProvider.tsx

@@ -1,19 +1,101 @@
 'use client'
 
+import {
+  accentTokensToCssVars,
+  generateAdminThemeTokens,
+  type ColorMode,
+  type SidebarDensity,
+} from '@actuate-media/cms-core/appearance'
 import { createContext, useContext, useState, useEffect, useCallback, type ReactNode } from 'react'
 
-type Theme = 'light' | 'dark' | 'system'
+/**
+ * Admin appearance engine.
+ *
+ * Owns the live, DOM-applied admin theme: color mode (light/dark/system),
+ * accent color, sidebar density, content font, reduced motion, and the
+ * resolved admin brand logos used by the sidebar. State is mirrored to
+ * localStorage so a reload paints instantly without a render-blocking fetch;
+ * the Appearance tab pushes the DB-backed values in via `applyAppearance` on
+ * load and save, making the database the source of truth and localStorage the
+ * warm cache.
+ *
+ * Backward compatible: `useTheme()` still exposes `{ theme, resolvedTheme,
+ * setTheme }`; the extra fields are additive.
+ */
+
+/** Resolved admin logo URLs (cached for the sidebar to paint without a fetch). */
+export interface AdminBrandCache {
+  primaryUrl: string | null
+  markUrl: string | null
+  darkUrl: string | null
+  initials: string
+}
 
 interface ThemeContextValue {
-  theme: Theme
+  theme: ColorMode
   resolvedTheme: 'light' | 'dark'
-  setTheme: (theme: Theme) => void
+  setTheme: (theme: ColorMode) => void
+  accent: string
+  setAccent: (accent: string) => void
+  density: SidebarDensity
+  setDensity: (density: SidebarDensity) => void
+  font: string
+  setFont: (font: string) => void
+  reduceMotion: boolean
+  setReduceMotion: (value: boolean) => void
+  adminBrand: AdminBrandCache
+  setAdminBrand: (brand: AdminBrandCache) => void
+  /** Push a full settings snapshot live (used by the Appearance tab). */
+  applyAppearance: (snapshot: AppearanceSnapshot) => void
+}
+
+export interface AppearanceSnapshot {
+  theme?: ColorMode
+  accent?: string
+  density?: SidebarDensity
+  font?: string
+  reduceMotion?: boolean
+  adminBrand?: AdminBrandCache
+}
+
+/** Curated content-font options. Applied as family strings (no web-font load). */
+export const AVAILABLE_FONTS = ['DM Sans', 'Inter', 'Geist', 'System UI'] as const
+
+const SYSTEM_STACK = "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
+
+const FONT_STACKS: Record<string, string> = {
+  'DM Sans': `'DM Sans', ${SYSTEM_STACK}`,
+  Inter: `'Inter', ${SYSTEM_STACK}`,
+  Geist: `'Geist', ${SYSTEM_STACK}`,
+  'System UI': SYSTEM_STACK,
+}
+
+function fontStack(font: string): string {
+  return FONT_STACKS[font] ?? `'${font}', ${SYSTEM_STACK}`
+}
+
+const DEFAULT_BRAND: AdminBrandCache = {
+  primaryUrl: null,
+  markUrl: null,
+  darkUrl: null,
+  initials: 'A',
 }
 
 const ThemeContext = createContext<ThemeContextValue>({
   theme: 'system',
   resolvedTheme: 'light',
   setTheme: () => {},
+  accent: 'purple',
+  setAccent: () => {},
+  density: 'default',
+  setDensity: () => {},
+  font: 'DM Sans',
+  setFont: () => {},
+  reduceMotion: false,
+  setReduceMotion: () => {},
+  adminBrand: DEFAULT_BRAND,
+  setAdminBrand: () => {},
+  applyAppearance: () => {},
 })
 
 export function useTheme() {
@@ -25,74 +107,205 @@ function getSystemTheme(): 'light' | 'dark' {
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
 }
 
-function resolveTheme(theme: Theme): 'light' | 'dark' {
+function resolveTheme(theme: ColorMode): 'light' | 'dark' {
   return theme === 'system' ? getSystemTheme() : theme
 }
 
-const STORAGE_KEY = 'actuate-theme'
+const KEY_THEME = 'actuate-theme'
+const KEY_ACCENT = 'actuate-accent'
+const KEY_DENSITY = 'actuate-density'
+const KEY_FONT = 'actuate-font'
+const KEY_MOTION = 'actuate-reduce-motion'
+const KEY_BRAND = 'actuate-admin-brand'
+
+function adminRootEl(): HTMLElement | null {
+  return document.querySelector('.actuate-admin')
+}
+
+function applyColorMode(resolved: 'light' | 'dark') {
+  const el = adminRootEl()
+  if (!el) return
+  el.classList.toggle('dark', resolved === 'dark')
+}
+
+function applyAccent(accent: string, resolved: 'light' | 'dark') {
+  const el = adminRootEl()
+  if (!el) return
+  const vars = accentTokensToCssVars(
+    generateAdminThemeTokens({ adminAccentColor: accent }, resolved),
+  )
+  for (const [name, value] of Object.entries(vars)) el.style.setProperty(name, value)
+}
+
+function applyDensity(density: SidebarDensity) {
+  const el = adminRootEl()
+  if (!el) return
+  el.setAttribute('data-density', density)
+}
+
+function applyFont(font: string) {
+  const el = adminRootEl()
+  if (!el) return
+  el.style.setProperty('--actuate-admin-font', fontStack(font))
+}
+
+function applyReduceMotion(value: boolean) {
+  const el = adminRootEl()
+  if (!el) return
+  el.classList.toggle('reduce-motion', value)
+}
 
 interface ThemeProviderProps {
   children: ReactNode
-  /** When true, default to dark mode if the user hasn't explicitly chosen a theme. */
+  /** When true, default to dark mode if the user hasn't explicitly chosen one. */
   defaultDarkMode?: boolean
 }
 
 export function ThemeProvider({ children, defaultDarkMode }: ThemeProviderProps) {
-  const [theme, setThemeState] = useState<Theme>('system')
+  const [theme, setThemeState] = useState<ColorMode>('system')
   const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>('light')
+  const [accent, setAccentState] = useState('purple')
+  const [density, setDensityState] = useState<SidebarDensity>('default')
+  const [font, setFontState] = useState('DM Sans')
+  const [reduceMotion, setReduceMotionState] = useState(false)
+  const [adminBrand, setAdminBrandState] = useState<AdminBrandCache>(DEFAULT_BRAND)
 
+  // Hydrate from localStorage on mount and apply everything to the DOM.
   useEffect(() => {
-    const stored = localStorage.getItem(STORAGE_KEY) as Theme | null
-    let initial: Theme
-    if (stored && ['light', 'dark', 'system'].includes(stored)) {
-      initial = stored
+    const storedTheme = localStorage.getItem(KEY_THEME) as ColorMode | null
+    let initialTheme: ColorMode
+    if (storedTheme && ['light', 'dark', 'system'].includes(storedTheme)) {
+      initialTheme = storedTheme
     } else if (defaultDarkMode === true) {
-      initial = 'dark'
+      initialTheme = 'dark'
     } else if (defaultDarkMode === false) {
-      initial = 'light'
+      initialTheme = 'light'
     } else {
-      initial = 'system'
+      initialTheme = 'system'
     }
-    setThemeState(initial)
-    const resolved = resolveTheme(initial)
+    const resolved = resolveTheme(initialTheme)
+
+    const storedAccent = localStorage.getItem(KEY_ACCENT) || 'purple'
+    const storedDensity = (localStorage.getItem(KEY_DENSITY) as SidebarDensity | null) || 'default'
+    const storedFont = localStorage.getItem(KEY_FONT) || 'DM Sans'
+    const storedMotion = localStorage.getItem(KEY_MOTION) === 'true'
+    let storedBrand = DEFAULT_BRAND
+    try {
+      const raw = localStorage.getItem(KEY_BRAND)
+      if (raw) storedBrand = { ...DEFAULT_BRAND, ...JSON.parse(raw) }
+    } catch {
+      // Ignore malformed cache.
+    }
+
+    setThemeState(initialTheme)
     setResolvedTheme(resolved)
-    applyTheme(resolved)
+    setAccentState(storedAccent)
+    setDensityState(storedDensity)
+    setFontState(storedFont)
+    setReduceMotionState(storedMotion)
+    setAdminBrandState(storedBrand)
+
+    applyColorMode(resolved)
+    applyAccent(storedAccent, resolved)
+    applyDensity(storedDensity)
+    applyFont(storedFont)
+    applyReduceMotion(storedMotion)
   }, [defaultDarkMode])
 
+  // Follow the OS color scheme while in `system` mode (re-applies accent too,
+  // since presets differ between light and dark).
   useEffect(() => {
     const mq = window.matchMedia('(prefers-color-scheme: dark)')
     const handler = () => {
       if (theme === 'system') {
         const resolved = getSystemTheme()
         setResolvedTheme(resolved)
-        applyTheme(resolved)
+        applyColorMode(resolved)
+        applyAccent(accent, resolved)
       }
     }
     mq.addEventListener('change', handler)
     return () => mq.removeEventListener('change', handler)
-  }, [theme])
+  }, [theme, accent])
 
-  const setTheme = useCallback((next: Theme) => {
-    setThemeState(next)
-    localStorage.setItem(STORAGE_KEY, next)
-    const resolved = resolveTheme(next)
-    setResolvedTheme(resolved)
-    applyTheme(resolved)
+  const setTheme = useCallback(
+    (next: ColorMode) => {
+      setThemeState(next)
+      localStorage.setItem(KEY_THEME, next)
+      const resolved = resolveTheme(next)
+      setResolvedTheme(resolved)
+      applyColorMode(resolved)
+      applyAccent(accent, resolved)
+    },
+    [accent],
+  )
+
+  const setAccent = useCallback(
+    (next: string) => {
+      setAccentState(next)
+      localStorage.setItem(KEY_ACCENT, next)
+      applyAccent(next, resolvedTheme)
+    },
+    [resolvedTheme],
+  )
+
+  const setDensity = useCallback((next: SidebarDensity) => {
+    setDensityState(next)
+    localStorage.setItem(KEY_DENSITY, next)
+    applyDensity(next)
+  }, [])
+
+  const setFont = useCallback((next: string) => {
+    setFontState(next)
+    localStorage.setItem(KEY_FONT, next)
+    applyFont(next)
   }, [])
 
+  const setReduceMotion = useCallback((next: boolean) => {
+    setReduceMotionState(next)
+    localStorage.setItem(KEY_MOTION, String(next))
+    applyReduceMotion(next)
+  }, [])
+
+  const setAdminBrand = useCallback((next: AdminBrandCache) => {
+    setAdminBrandState(next)
+    localStorage.setItem(KEY_BRAND, JSON.stringify(next))
+  }, [])
+
+  // Apply a full snapshot live (Appearance tab on load/save). Persists to
+  // localStorage so the choice survives reloads even before the next fetch.
+  const applyAppearance = useCallback(
+    (snapshot: AppearanceSnapshot) => {
+      if (snapshot.theme !== undefined) setTheme(snapshot.theme)
+      if (snapshot.accent !== undefined) setAccent(snapshot.accent)
+      if (snapshot.density !== undefined) setDensity(snapshot.density)
+      if (snapshot.font !== undefined) setFont(snapshot.font)
+      if (snapshot.reduceMotion !== undefined) setReduceMotion(snapshot.reduceMotion)
+      if (snapshot.adminBrand !== undefined) setAdminBrand(snapshot.adminBrand)
+    },
+    [setTheme, setAccent, setDensity, setFont, setReduceMotion, setAdminBrand],
+  )
+
   return (
-    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+    <ThemeContext.Provider
+      value={{
+        theme,
+        resolvedTheme,
+        setTheme,
+        accent,
+        setAccent,
+        density,
+        setDensity,
+        font,
+        setFont,
+        reduceMotion,
+        setReduceMotion,
+        adminBrand,
+        setAdminBrand,
+        applyAppearance,
+      }}
+    >
       {children}
     </ThemeContext.Provider>
   )
 }
-
-function applyTheme(resolved: 'light' | 'dark') {
-  const adminRoot = document.querySelector('.actuate-admin')
-  if (!adminRoot) return
-  if (resolved === 'dark') {
-    adminRoot.classList.add('dark')
-  } else {
-    adminRoot.classList.remove('dark')
-  }
-}

package/src/layout/Sidebar.tsx

@@ -76,26 +76,55 @@ const ICON_MAP: Record<string, LucideIcon> = {
   Layers: Layers,
 }
 
+/** Square site-initials badge — the final fallback before the Actuate mark. */
+function InitialsBadge({ initials, size }: { initials: string; size: 'sm' | 'lg' }) {
+  return (
+    <span
+      className={`bg-sidebar-primary text-sidebar-primary-foreground inline-flex shrink-0 items-center justify-center rounded-md font-medium ${
+        size === 'lg' ? 'h-8 w-8 text-sm' : 'h-8 w-8 text-sm'
+      }`}
+      aria-hidden="true"
+    >
+      {initials}
+    </span>
+  )
+}
+
+/**
+ * Sidebar brand lockup.
+ *
+ * Resolution order follows the Appearance spec, sourcing from the live
+ * appearance context (DB-backed brand, cached in localStorage) and falling
+ * back to legacy `config.admin.branding`, then site initials, then the bundled
+ * Actuate mark/wordmark for un-branded installs. Dark-mode uses the dark logo
+ * when one is configured. Logos are never stretched/cropped (object-contain).
+ */
 function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean }) {
+  const { adminBrand, resolvedTheme } = useTheme()
   const branding = config?.admin?.branding
-  const customLogo = branding?.logo
+  const configLogo = branding?.logo
   const brandName = branding?.name
+  const initials = adminBrand.initials
+  const hasInitials = Boolean(initials) && initials !== 'A'
+
+  // Prefer the dark logo on dark backgrounds when supplied.
+  const primary =
+    resolvedTheme === 'dark' && adminBrand.darkUrl ? adminBrand.darkUrl : adminBrand.primaryUrl
+  const mark = adminBrand.markUrl
+  const alt = brandName ?? 'Admin'
 
   if (collapsed) {
-    if (customLogo) {
-      return <img src={customLogo} alt={brandName ?? 'Admin'} className="h-8 w-8 object-contain" />
-    }
+    if (mark) return <img src={mark} alt={alt} className="h-8 w-8 object-contain" />
+    if (primary) return <img src={primary} alt={alt} className="h-8 w-8 object-contain" />
+    if (configLogo) return <img src={configLogo} alt={alt} className="h-8 w-8 object-contain" />
+    if (hasInitials) return <InitialsBadge initials={initials} size="sm" />
     return <ActuateMark className="h-8 w-8" />
   }
 
-  if (customLogo) {
+  if (primary) {
     return (
       <div className="flex min-w-0 items-center gap-2.5">
-        <img
-          src={customLogo}
-          alt={brandName ?? 'Admin'}
-          className="h-8 w-auto shrink-0 object-contain"
-        />
+        <img src={primary} alt={alt} className="h-8 w-auto shrink-0 object-contain" />
         {brandName && (
           <span className="text-sidebar-foreground truncate text-sm font-medium">{brandName}</span>
         )}
@@ -103,6 +132,32 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
     )
   }
 
+  if (configLogo) {
+    return (
+      <div className="flex min-w-0 items-center gap-2.5">
+        <img src={configLogo} alt={alt} className="h-8 w-auto shrink-0 object-contain" />
+        {brandName && (
+          <span className="text-sidebar-foreground truncate text-sm font-medium">{brandName}</span>
+        )}
+      </div>
+    )
+  }
+
+  if (mark || hasInitials) {
+    return (
+      <div className="flex min-w-0 items-center gap-2.5">
+        {mark ? (
+          <img src={mark} alt={alt} className="h-8 w-8 shrink-0 object-contain" />
+        ) : (
+          <InitialsBadge initials={initials} size="lg" />
+        )}
+        <span className="text-sidebar-foreground truncate text-sm font-medium">
+          {brandName ?? alt}
+        </span>
+      </div>
+    )
+  }
+
   if (brandName) {
     return (
       <div className="flex min-w-0 items-center gap-2.5">
@@ -180,6 +235,8 @@ export function Sidebar({
 }: SidebarProps) {
   const formsSidebar = useFormsSidebar()
   const navItems = applyFormsNav(buildNavItems(config), formsSidebar)
+  const { density } = useTheme()
+  const compact = density === 'compact'
 
   return (
     <aside
@@ -196,8 +253,11 @@ export function Sidebar({
         <BrandLogo config={config} collapsed={collapsed} />
       </div>
 
-      <nav className="flex-1 space-y-1 overflow-y-auto p-3" aria-label="Primary">
-        {renderNavTree(navItems, { collapsed, currentPath, onNavigate })}
+      <nav
+        className={`flex-1 overflow-y-auto ${compact ? 'space-y-0.5 p-2' : 'space-y-1 p-3'}`}
+        aria-label="Primary"
+      >
+        {renderNavTree(navItems, { collapsed, currentPath, onNavigate, compact })}
       </nav>
 
       {/* Footer collapse control. Sits at the bottom of the sidebar so it
@@ -303,6 +363,8 @@ interface NavRenderContext {
   collapsed: boolean
   currentPath: string
   onNavigate: (path: string) => void
+  /** Compact density tightens nav row vertical padding. */
+  compact?: boolean
 }
 
 function isPathActive(currentPath: string, itemPath: string): boolean {
@@ -472,7 +534,13 @@ function NavLink({
     <button
       onClick={() => ctx.onNavigate(item.path)}
       className={`flex w-full items-center gap-3 rounded-lg text-left transition-colors ${
-        nested ? 'py-1.5 pr-3 pl-9' : 'px-3 py-2.5'
+        nested
+          ? ctx.compact
+            ? 'py-1 pr-3 pl-9'
+            : 'py-1.5 pr-3 pl-9'
+          : ctx.compact
+            ? 'px-3 py-1.5'
+            : 'px-3 py-2.5'
       } ${
         isActive
           ? 'bg-sidebar-accent text-sidebar-primary'

package/src/styles/theme.css

@@ -166,13 +166,23 @@
 
   .actuate-admin {
     @apply bg-background text-foreground;
-    font-family:
+    /*
+     * Content font is var-driven so the Appearance tab can switch it at
+     * runtime, but defaults to the system-ui stack. We do NOT load web fonts
+     * here (no Google Fonts / @font-face) — the chosen family is applied as a
+     * family string and falls back to system-ui when not installed, keeping
+     * the admin dependency-free per the design system. This is the single
+     * permitted `!important` (it must beat consumer global resets).
+     */
+    font-family: var(
+      --actuate-admin-font,
       system-ui,
       -apple-system,
       BlinkMacSystemFont,
       'Segoe UI',
       Roboto,
-      sans-serif !important;
+      sans-serif
+    ) !important;
     font-size: var(--font-size);
     line-height: 1.5;
     isolation: isolate;
@@ -241,3 +251,23 @@
     line-height: 1.5;
   }
 }
+
+/*
+ * Reduce-motion (admin-level Appearance toggle).
+ *
+ * Intentionally UNLAYERED: unlayered rules beat Tailwind's `@layer utilities`
+ * transition/animation classes without needing `!important`, so the toggle can
+ * neutralize utility-driven motion. We shorten (not delete) durations and never
+ * touch outlines/focus rings, so state changes and focus visibility remain
+ * intact. The OS `prefers-reduced-motion` is still respected app-wide via
+ * `motion-safe:`/`motion-reduce:`; this class lets users opt in regardless.
+ */
+.actuate-admin.reduce-motion,
+.actuate-admin.reduce-motion *,
+.actuate-admin.reduce-motion *::before,
+.actuate-admin.reduce-motion *::after {
+  animation-duration: 0.001ms;
+  animation-iteration-count: 1;
+  transition-duration: 0.001ms;
+  scroll-behavior: auto;
+}

package/src/views/Settings.tsx

@@ -26,10 +26,10 @@ import { useState, useEffect, useCallback, useMemo } from 'react'
 import { toast } from 'sonner'
 import { useApiData } from '../lib/useApiData.js'
 import { cmsApi } from '../lib/api.js'
-import { useTheme } from '../components/ThemeProvider.js'
 import { RelationshipField } from '../fields/RelationshipField.js'
 import { SEOConfigPanel } from '../components/SEOConfigPanel.js'
 import { GeneralSettingsTab } from './settings/GeneralSettingsTab.js'
+import { AppearanceTab } from './settings/AppearanceTab.js'
 import { Users as UsersView } from './Users.js'
 import { ApiKeys as ApiKeysView } from './ApiKeys.js'
 
@@ -44,7 +44,7 @@ export interface SettingsProps {
 }
 
 /** Tabs that drive their own persistence (no global "Save Changes" footer). */
-const SELF_MANAGED_TABS = new Set(['general', 'users', 'api-keys'])
+const SELF_MANAGED_TABS = new Set(['general', 'appearance', 'users', 'api-keys'])
 
 function readSettingsTabFromUrl(): string | null {
   if (typeof window === 'undefined') return null
@@ -275,25 +275,7 @@ export function Settings({
         </Tabs.Content>
 
         <Tabs.Content value="appearance" className="space-y-4">
-          <div className="rounded-lg border border-gray-200 bg-white p-4">
-            <h3 className="mb-4 text-sm font-semibold text-gray-900">Theme</h3>
-            <div className="space-y-4">
-              <div>
-                <label className="mb-1 block text-sm font-medium text-gray-700">Color Scheme</label>
-                <ThemeSelect />
-              </div>
-              <div>
-                <label className="mb-1 block text-sm font-medium text-gray-700">
-                  Primary Color
-                </label>
-                <input
-                  type="color"
-                  defaultValue="#3b82f6"
-                  className="h-10 w-full rounded-lg border border-gray-300 px-3 py-2"
-                />
-              </div>
-            </div>
-          </div>
+          <AppearanceTab role={session?.user?.role} config={config} />
         </Tabs.Content>
 
         {hasLayoutRegions && (
@@ -622,21 +604,6 @@ export function Settings({
   )
 }
 
-function ThemeSelect() {
-  const { theme, setTheme } = useTheme()
-  return (
-    <select
-      value={theme}
-      onChange={(e) => setTheme(e.target.value as 'light' | 'dark' | 'system')}
-      className="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:ring-2 focus:ring-blue-500 focus:outline-none"
-    >
-      <option value="light">Light</option>
-      <option value="dark">Dark</option>
-      <option value="system">Auto (System)</option>
-    </select>
-  )
-}
-
 function ToggleSetting({
   label,
   description,