@actuate-media/cms-admin 0.35.0 → 0.36.1

package/src/views/settings/SeoSettingsTab.tsx

@@ -17,6 +17,7 @@ import { MediaPickerModal } from '../../components/MediaPickerModal.js'
 import { SEOConfigPanel } from '../../components/SEOConfigPanel.js'
 import {
   ConfirmDangerousSettingDialog,
+  SettingsCard,
   SettingsSaveBar,
   SettingsSourceBadge,
   SettingsToggleRow,
@@ -82,7 +83,7 @@ export function SeoSettingsTab({ onNavigate, role }: SeoSettingsTabProps) {
       <div className="space-y-4" aria-busy="true" aria-live="polite">
         <span className="sr-only">Loading SEO settings…</span>
         {[0, 1, 2, 3].map((i) => (
-          <div key={i} className="border-border bg-card rounded-lg border p-4">
+          <div key={i} className="border-border bg-card rounded-lg border p-6">
             <div className="bg-muted mb-4 h-4 w-40 animate-pulse rounded" />
             <div className="space-y-3">
               <div className="bg-muted h-9 w-full animate-pulse rounded" />
@@ -208,7 +209,6 @@ function SeoWorkspaceCallout({ onNavigate }: { onNavigate?: (path: string) => vo
 // ---------------------------------------------------------------------------
 
 function MetaDefaultsCard({ seo, canEdit }: { seo: UseSeoSettings; canEdit: boolean }) {
-  const headingId = useId()
   const templateId = useId()
   const descId = useId()
   const [pickerOpen, setPickerOpen] = useState(false)
@@ -229,11 +229,10 @@ function MetaDefaultsCard({ seo, canEdit }: { seo: UseSeoSettings; canEdit: bool
   const imageEditable = sources.defaultOgImage?.editable !== false && canEdit
 
   return (
-    <section aria-labelledby={headingId} className="border-border bg-card rounded-lg border p-4">
-      <h3 id={headingId} className="text-foreground mb-4 text-base font-medium">
-        Meta Defaults
-      </h3>
-
+    <SettingsCard
+      title="Meta Defaults"
+      description="Fallback page title, description, and social image applied when a page defines none of its own."
+    >
       <div className="space-y-4">
         {/* Title template */}
         <div>
@@ -362,7 +361,7 @@ function MetaDefaultsCard({ seo, canEdit }: { seo: UseSeoSettings; canEdit: bool
         onSelect={(url) => setField('defaultOgImage', url)}
         onSelectItem={(item) => setField('defaultSocialImageAssetId', item.id)}
       />
-    </section>
+    </SettingsCard>
   )
 }
 
@@ -458,20 +457,14 @@ function VerificationField({
 }
 
 function SearchEngineVerificationCard({ seo, canEdit }: { seo: UseSeoSettings; canEdit: boolean }) {
-  const headingId = useId()
   const { form, setField } = seo
   const onChange = (key: keyof SeoSettingsForm, value: string) => setField(key, value as never)
 
   return (
-    <section aria-labelledby={headingId} className="border-border bg-card rounded-lg border p-4">
-      <h3 id={headingId} className="text-foreground mb-1 text-base font-medium">
-        Search Engine Verification
-      </h3>
-      <p className="text-muted-foreground mb-4 text-sm">
-        Paste the verification token from each provider. We render only safe meta tags into your
-        site&apos;s head — never arbitrary HTML.
-      </p>
-
+    <SettingsCard
+      title="Search Engine Verification"
+      description="Paste the verification token from each provider. We render only safe meta tags into your site's head — never arbitrary HTML."
+    >
       <div className="space-y-4">
         <VerificationField
           label="Google Search Console"
@@ -523,7 +516,7 @@ function SearchEngineVerificationCard({ seo, canEdit }: { seo: UseSeoSettings; c
           />
         </div>
       </details>
-    </section>
+    </SettingsCard>
   )
 }
 
@@ -540,7 +533,6 @@ function SitemapDefaultsCard({
   canEdit: boolean
   onNavigate?: (path: string) => void
 }) {
-  const headingId = useId()
   const [pendingDisable, setPendingDisable] = useState(false)
   const { form, setField, sitemap, siteUrl, isProduction, regenerateSitemap, regenerating } = seo
 
@@ -558,11 +550,10 @@ function SitemapDefaultsCard({
     : 'Never'
 
   return (
-    <section aria-labelledby={headingId} className="border-border bg-card rounded-lg border p-4">
-      <h3 id={headingId} className="text-foreground mb-4 text-base font-medium">
-        Sitemap
-      </h3>
-
+    <SettingsCard
+      title="Sitemap"
+      description="Control XML sitemap generation and whether search engines are pinged on publish."
+    >
       {!siteUrl && (
         <div className="border-warning/30 bg-warning/10 text-warning mb-4 flex items-start gap-2 rounded-md border p-3 text-sm">
           <AlertTriangle size={16} className="mt-0.5 shrink-0" aria-hidden="true" />
@@ -644,7 +635,7 @@ function SitemapDefaultsCard({
         }}
         onCancel={() => setPendingDisable(false)}
       />
-    </section>
+    </SettingsCard>
   )
 }
 

package/src/views/settings/SiteIndexStatusCard.tsx

@@ -5,11 +5,11 @@ import {
   XCircle,
   AlertTriangle,
   HelpCircle,
-  ShieldCheck,
   ExternalLink,
   Search,
 } from 'lucide-react'
 import type { ReactNode } from 'react'
+import { SettingsCard } from './components.js'
 import type { SiteIndexStatus } from './useGeneralSettings.js'
 
 interface SiteIndexStatusCardProps {
@@ -61,23 +61,11 @@ export function SiteIndexStatusCard({
   onRunAudit,
 }: SiteIndexStatusCardProps) {
   return (
-    <section
-      aria-labelledby="site-index-status-heading"
-      className="border-border bg-card rounded-lg border p-4"
-    >
-      <div className="mb-3 flex items-start justify-between gap-3">
-        <div className="flex items-start gap-2">
-          <ShieldCheck size={18} className="text-muted-foreground mt-0.5" aria-hidden="true" />
-          <div>
-            <h3 id="site-index-status-heading" className="text-foreground text-base font-medium">
-              Site Index Status
-            </h3>
-            <p className="text-muted-foreground text-sm">
-              Current effective crawl and indexing state
-            </p>
-          </div>
-        </div>
-        {status && (
+    <SettingsCard
+      title="Site Index Status"
+      description="Current effective crawl and indexing state."
+      actions={
+        status ? (
           <span
             className={`inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs font-medium ${SEVERITY_STYLES[status.severity].pill}`}
           >
@@ -85,9 +73,9 @@ export function SiteIndexStatusCard({
             <span className="sr-only">Status: </span>
             {status.label}
           </span>
-        )}
-      </div>
-
+        ) : undefined
+      }
+    >
       {loading && !status ? (
         <div className="space-y-2" aria-hidden="true">
           <div className="bg-muted h-4 w-2/3 animate-pulse rounded" />
@@ -128,7 +116,7 @@ export function SiteIndexStatusCard({
           )}
         </>
       )}
-    </section>
+    </SettingsCard>
   )
 }
 

package/src/views/settings/SiteInformationCard.tsx

@@ -2,7 +2,7 @@
 
 import { useId } from 'react'
 import { CheckCircle2 } from 'lucide-react'
-import { SettingsSourceBadge } from './components.js'
+import { SettingsCard, SettingsSourceBadge } from './components.js'
 import type {
   GeneralSettingsForm,
   SettingsSourceMetadata,
@@ -39,13 +39,7 @@ export function SiteInformationCard({
   const urlValid = !urlIssue && form.siteUrl.trim().length > 0
 
   return (
-    <section
-      aria-labelledby={`${titleId}-heading`}
-      className="border-border bg-card rounded-lg border p-4"
-    >
-      <h3 id={`${titleId}-heading`} className="text-foreground mb-4 text-base font-medium">
-        Site Information
-      </h3>
+    <SettingsCard title="Site Information" description="Your site's name, tagline, and public URL.">
       <div className="space-y-4">
         <div>
           <label htmlFor={titleId} className={LABEL_CLASS}>
@@ -117,6 +111,6 @@ export function SiteInformationCard({
           )}
         </div>
       </div>
-    </section>
+    </SettingsCard>
   )
 }

package/src/views/settings/components.tsx

@@ -2,9 +2,80 @@
 
 import * as Dialog from '@radix-ui/react-dialog'
 import { AlertTriangle, Check, Loader2, Lock } from 'lucide-react'
-import type { ReactNode } from 'react'
+import { useId, type ReactNode } from 'react'
 import type { SettingsSourceMetadata, ValidationIssue } from './useGeneralSettings.js'
 
+/**
+ * The canonical Settings section card: a bordered `bg-card` surface with a
+ * header (title + optional description) and an optional right-aligned actions
+ * slot. This is the single source of truth for the Settings design language —
+ * every tab's sections render through it so spacing, padding, typography, and
+ * the title/description rhythm stay identical across General, Appearance,
+ * Security, SEO, AI, and beyond. Match the Appearance tab exactly: `p-6`,
+ * `text-lg` medium title, `text-sm` muted description.
+ */
+export function SettingsCard({
+  title,
+  description,
+  actions,
+  children,
+  className,
+  headingLevel: Heading = 'h3',
+}: {
+  title: ReactNode
+  description?: ReactNode
+  /** Right-aligned controls in the header (e.g. a Refresh or Add button). */
+  actions?: ReactNode
+  children: ReactNode
+  className?: string
+  /** Override the heading element for correct document outline nesting. */
+  headingLevel?: 'h2' | 'h3'
+}) {
+  const headingId = useId()
+  return (
+    <section
+      aria-labelledby={headingId}
+      className={`border-border bg-card rounded-lg border p-6 ${className ?? ''}`}
+    >
+      <header className="mb-4 flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <Heading id={headingId} className="text-foreground text-lg font-medium">
+            {title}
+          </Heading>
+          {description && <p className="text-muted-foreground mt-0.5 text-sm">{description}</p>}
+        </div>
+        {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+      </header>
+      {children}
+    </section>
+  )
+}
+
+/**
+ * A sub-section inside a {@link SettingsCard}: a top divider plus a
+ * `text-base` medium label and optional description. Use for grouped controls
+ * within a single card (e.g. "Admin branding" under "Branding").
+ */
+export function SettingsSubsection({
+  title,
+  description,
+  children,
+  className,
+}: {
+  title: ReactNode
+  description?: ReactNode
+  children?: ReactNode
+  className?: string
+}) {
+  return (
+    <div className={`border-border border-t pt-4 ${className ?? ''}`}>
+      <div className="text-foreground text-base font-medium">{title}</div>
+      {description && <p className="text-muted-foreground mt-0.5 text-sm">{description}</p>}
+      {children}
+    </div>
+  )
+}
+
 const SOURCE_LABEL: Record<SettingsSourceMetadata['source'], string> = {
   config: 'Config-managed',
   environment: 'Environment-managed',

package/src/views/settings/securityPrimitives.tsx

@@ -3,6 +3,7 @@
 import { AlertTriangle, Check, CircleHelp, X } from 'lucide-react'
 import type { ReactNode } from 'react'
 import type { CheckStatus } from '@actuate-media/cms-core/security-center'
+import { SettingsCard } from './components.js'
 
 /** Small status icon used in check/summary rows. Text label always accompanies it. */
 export function CheckIcon({ status }: { status: CheckStatus }) {
@@ -51,25 +52,29 @@ export function StatusRow({
   )
 }
 
-/** Section wrapper matching the other settings cards. */
+/**
+ * Section wrapper for the Security tab. Delegates to the shared
+ * {@link SettingsCard} so Security matches the canonical Settings design
+ * language (p-6, text-lg title, muted description). `headingId` is accepted
+ * for backward compatibility but ignored — {@link SettingsCard} generates and
+ * wires its own accessible heading id.
+ */
 export function SecurityCard({
-  headingId,
   title,
   description,
+  actions,
   children,
 }: {
-  headingId: string
+  /** @deprecated No longer used; SettingsCard manages the heading id. */
+  headingId?: string
   title: string
   description: string
+  actions?: ReactNode
   children: ReactNode
 }) {
   return (
-    <section aria-labelledby={headingId} className="border-border bg-card rounded-lg border p-4">
-      <h3 id={headingId} className="text-foreground mb-1 text-base font-medium">
-        {title}
-      </h3>
-      <p className="text-muted-foreground mb-4 text-sm">{description}</p>
+    <SettingsCard title={title} description={description} actions={actions}>
       {children}
-    </section>
+    </SettingsCard>
   )
 }

package/src/views/settings/useAiSettings.ts

@@ -93,12 +93,32 @@ export interface AiUsageView {
   runCount: number
 }
 
+/** Editable brand voice fields (the buffered Save-bar portion). */
+export interface BrandVoiceForm {
+  enabled: boolean
+  name: string
+  tone: string
+  audience: string
+  guidelines: string
+  sampleText: string
+}
+
+const EMPTY_BRAND_VOICE: BrandVoiceForm = {
+  enabled: false,
+  name: '',
+  tone: '',
+  audience: '',
+  guidelines: '',
+  sampleText: '',
+}
+
 /** The buffered (Save-bar) portion of AI settings. */
 export interface AiSettingsForm {
   defaultProviderId: string
   defaultModelId: string
   features: AiFeatureView[]
   monthlyTokenLimit: string
+  brandVoice: BrandVoiceForm
 }
 
 interface AiSettingsResponse {
@@ -107,6 +127,14 @@ interface AiSettingsResponse {
     defaultModelId?: string
     features: AiFeatureView[]
     budget: { monthlyTokenLimit?: number }
+    brandVoice?: {
+      enabled?: boolean
+      name?: string
+      tone?: string
+      audience?: string
+      guidelines?: string
+      sampleText?: string
+    }
   }
   providers: AiProviderView[]
   defaultModel: AiModelView | null
@@ -127,6 +155,14 @@ function formFromResponse(res: AiSettingsResponse): AiSettingsForm {
       typeof res.settings.budget.monthlyTokenLimit === 'number'
         ? String(res.settings.budget.monthlyTokenLimit)
         : '',
+    brandVoice: {
+      enabled: res.settings.brandVoice?.enabled ?? false,
+      name: res.settings.brandVoice?.name ?? '',
+      tone: res.settings.brandVoice?.tone ?? '',
+      audience: res.settings.brandVoice?.audience ?? '',
+      guidelines: res.settings.brandVoice?.guidelines ?? '',
+      sampleText: res.settings.brandVoice?.sampleText ?? '',
+    },
   }
 }
 
@@ -135,6 +171,19 @@ const EMPTY_FORM: AiSettingsForm = {
   defaultModelId: '',
   features: [],
   monthlyTokenLimit: '',
+  brandVoice: { ...EMPTY_BRAND_VOICE },
+}
+
+/** A brand voice with no content and disabled clears the stored profile (send null). */
+function brandVoiceIsEmpty(bv: BrandVoiceForm): boolean {
+  return (
+    !bv.enabled &&
+    !bv.name.trim() &&
+    !bv.tone.trim() &&
+    !bv.audience.trim() &&
+    !bv.guidelines.trim() &&
+    !bv.sampleText.trim()
+  )
 }
 
 export interface ProviderInput {
@@ -162,6 +211,8 @@ export interface UseAiSettings {
   toggleFeature: (key: string, enabled: boolean) => void
   /** Set a per-feature model override. Empty string reverts to the default model. */
   setFeatureModel: (key: string, modelId: string) => void
+  /** Patch one or more brand voice fields. */
+  setBrandVoice: (patch: Partial<BrandVoiceForm>) => void
   dirty: boolean
   budgetError: string | null
   saveState: SaveState
@@ -273,6 +324,11 @@ export function useAiSettings(canEdit: boolean): UseAiSettings {
     setSaveState('idle')
   }, [])
 
+  const setBrandVoice = useCallback((patch: Partial<BrandVoiceForm>) => {
+    setForm((prev) => ({ ...prev, brandVoice: { ...prev.brandVoice, ...patch } }))
+    setSaveState('idle')
+  }, [])
+
   const budgetError = useMemo(() => {
     if (form.monthlyTokenLimit === '') return null
     const n = Number(form.monthlyTokenLimit)
@@ -285,6 +341,15 @@ export function useAiSettings(canEdit: boolean): UseAiSettings {
     if (form.defaultModelId !== baseline.defaultModelId) return true
     if (form.monthlyTokenLimit !== baseline.monthlyTokenLimit) return true
     if (form.features.length !== baseline.features.length) return true
+    const bvKeys: (keyof BrandVoiceForm)[] = [
+      'enabled',
+      'name',
+      'tone',
+      'audience',
+      'guidelines',
+      'sampleText',
+    ]
+    if (bvKeys.some((k) => form.brandVoice[k] !== baseline.brandVoice[k])) return true
     return form.features.some((f, i) => {
       const base = baseline.features[i]
       return f.enabled !== base?.enabled || (f.modelId ?? '') !== (base?.modelId ?? '')
@@ -310,6 +375,16 @@ export function useAiSettings(canEdit: boolean): UseAiSettings {
             monthlyTokenLimit:
               form.monthlyTokenLimit === '' ? null : Number(form.monthlyTokenLimit),
           },
+          brandVoice: brandVoiceIsEmpty(form.brandVoice)
+            ? null
+            : {
+                enabled: form.brandVoice.enabled,
+                name: form.brandVoice.name,
+                tone: form.brandVoice.tone,
+                audience: form.brandVoice.audience,
+                guidelines: form.brandVoice.guidelines,
+                sampleText: form.brandVoice.sampleText,
+              },
         }),
       })
       if (res.error) throw new Error(res.error)
@@ -459,6 +534,7 @@ export function useAiSettings(canEdit: boolean): UseAiSettings {
     setMonthlyTokenLimit,
     toggleFeature,
     setFeatureModel,
+    setBrandVoice,
     dirty,
     budgetError,
     saveState,