@actuate-media/cms-admin 0.20.0 → 0.21.1

package/src/layout/Sidebar.tsx

@@ -1,6 +1,8 @@
 'use client'
 
-import type { ReactNode } from 'react'
+import { useRef, useState, type ReactNode } from 'react'
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
+import { useTheme } from '../components/ThemeProvider.js'
 import {
   LayoutDashboard,
   FileText,
@@ -8,8 +10,8 @@ import {
   Image,
   Settings,
   ChevronLeft,
+  ChevronDown,
   ClipboardList,
-  Users,
   Search as SearchIcon,
   Briefcase,
   FolderOpen,
@@ -22,7 +24,6 @@ import {
   LayoutGrid,
   Code2,
   Library,
-  KeyRound,
   ListTree,
   Menu as MenuIcon,
   PanelLeftClose,
@@ -156,8 +157,6 @@ const defaultNavItems: NavItem[] = [
   { path: '/forms', label: 'Forms', icon: ClipboardList, group: 'Content' },
   { path: '/seo', label: 'SEO', icon: SearchIcon, group: 'Content' },
   { path: '/script-tags', label: 'Script Tags', icon: Code2, group: 'Content' },
-  { path: '/users', label: 'Users', icon: Users, group: 'Settings' },
-  { path: '/api-keys', label: 'API Keys', icon: KeyRound, group: 'Settings' },
   { path: '/settings', label: 'Settings', icon: Settings, group: 'Settings' },
 ]
 
@@ -275,36 +274,117 @@ function renderNavTree(items: NavItem[], ctx: NavRenderContext): ReactNode {
       lastGroup = undefined
     }
 
+    const hasChildren = !!item.children && item.children.length > 0
+
+    // Collapsed parents reveal their children in a hover/focus flyout instead
+    // of inline (there's no room for indented rows in the 80px rail).
+    if (hasChildren && ctx.collapsed) {
+      nodes.push(<CollapsedFlyout key={`flyout:${item.path}`} item={item} ctx={ctx} />)
+      continue
+    }
+
+    // Expanded parents with children render as a collapsible section
+    // (chevron toggle to contract/expand the submenu).
+    if (hasChildren) {
+      nodes.push(<NavSection key={`section:${item.path}`} item={item} ctx={ctx} />)
+      continue
+    }
+
     // Keys are namespaced because a parent and its first child can share
     // the same path (e.g. the Posts parent and its "All Posts" child are
     // both `/posts`). Using the raw path as the key collided and made
     // React warn about — and risk dropping — duplicate siblings.
     nodes.push(<NavLink key={`item:${item.path}`} item={item} ctx={ctx} />)
-    if (item.children && item.children.length > 0 && !ctx.collapsed) {
-      for (const child of item.children) {
-        nodes.push(
-          <NavLink key={`child:${item.path}:${child.path}`} item={child} ctx={ctx} nested />,
-        )
-      }
-    }
   }
 
   return nodes
 }
 
+/**
+ * Expanded parent with a collapsible submenu. The label/icon navigates to the
+ * parent destination; a trailing chevron toggles the child list open/closed.
+ * Defaults to open, and auto-opens when the parent or one of its children is
+ * the active route so the current page is never hidden behind a collapsed
+ * section.
+ */
+function NavSection({ item, ctx }: { item: NavItem; ctx: NavRenderContext }) {
+  const Icon = item.icon
+  const isActive = isPathActive(ctx.currentPath, item.path)
+  const childActive = item.children!.some((c) => isPathActive(ctx.currentPath, c.path))
+  const [open, setOpen] = useState(true)
+  const childListId = `nav-section-${item.path.replace(/[^a-z0-9]+/gi, '-')}`
+
+  // Keep the active section visible: if the user is on this section's route
+  // (parent or child) it stays expanded regardless of the manual toggle.
+  const expanded = open || isActive || childActive
+
+  return (
+    <div>
+      <div
+        className={`flex items-center rounded-lg transition-colors ${
+          isActive
+            ? 'bg-sidebar-accent text-sidebar-primary'
+            : 'text-sidebar-foreground hover:bg-sidebar-accent'
+        }`}
+      >
+        <button
+          onClick={() => ctx.onNavigate(item.path)}
+          className="flex min-w-0 flex-1 items-center gap-3 rounded-lg py-2.5 pr-1 pl-3 text-left"
+          aria-current={isActive ? 'page' : undefined}
+        >
+          <Icon className="h-5 w-5 shrink-0" aria-hidden />
+          <span className="truncate text-sm font-medium">{item.label}</span>
+        </button>
+        <button
+          onClick={() => setOpen((v) => !v)}
+          className="text-sidebar-foreground/55 hover:text-sidebar-foreground mr-1 flex shrink-0 items-center rounded-md p-1.5 transition-colors"
+          aria-label={`${expanded ? 'Collapse' : 'Expand'} ${item.label}`}
+          aria-expanded={expanded}
+          aria-controls={childListId}
+        >
+          <ChevronDown
+            className={`h-4 w-4 transition-transform duration-200 ${expanded ? '' : '-rotate-90'}`}
+            aria-hidden
+          />
+        </button>
+      </div>
+
+      {/* Tight (gap-less) connector container so the vertical tree guides of
+          adjacent rows touch and read as one continuous line with curved
+          elbows into each child. */}
+      {expanded && (
+        <div id={childListId} className="relative">
+          {item.children!.map((child, i) => (
+            <NavLink
+              key={`child:${item.path}:${child.path}`}
+              item={child}
+              ctx={ctx}
+              nested
+              isLast={i === item.children!.length - 1}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
 function NavLink({
   item,
   ctx,
   nested = false,
+  isLast = false,
 }: {
   item: NavItem
   ctx: NavRenderContext
   nested?: boolean
+  /** Last child in its group — the elbow stops here (no continuation line). */
+  isLast?: boolean
 }) {
   const Icon = item.icon
   const isActive = isPathActive(ctx.currentPath, item.path)
 
-  return (
+  const button = (
     <button
       onClick={() => ctx.onNavigate(item.path)}
       className={`flex w-full items-center gap-3 rounded-lg text-left transition-colors ${
@@ -328,6 +408,137 @@ function NavLink({
       )}
     </button>
   )
+
+  if (!nested || ctx.collapsed) return button
+
+  // Curved-elbow tree connector (expanded only). The elbow draws the vertical
+  // run from the row top to its vertical center, curves at the bottom-left
+  // corner, then runs horizontally into the row. Non-last rows continue the
+  // vertical line to the row bottom so it meets the next sibling's elbow.
+  // The guide is centered (~21px) under the parent item's 20px icon.
+  return (
+    <div className="relative">
+      <span
+        aria-hidden
+        className="border-sidebar-border absolute top-0 left-[21px] h-1/2 w-[15px] rounded-bl-lg border-b border-l"
+      />
+      {!isLast && (
+        <span
+          aria-hidden
+          className="border-sidebar-border absolute top-1/2 bottom-0 left-[21px] border-l"
+        />
+      )}
+      {button}
+    </div>
+  )
+}
+
+/**
+ * Collapsed-rail parent: shows the icon button and, on hover or keyboard
+ * focus, a flyout listing the parent's children. Built on Radix
+ * DropdownMenu so the panel is portaled (escaping the nav's `overflow`
+ * clip), positioned, dismissable, and keyboard-navigable. Hover-opening is
+ * controlled manually; we suppress Radix's auto-focus when opened by pointer
+ * so hovering doesn't steal focus, while keyboard opening still moves focus
+ * into the menu.
+ */
+function CollapsedFlyout({ item, ctx }: { item: NavItem; ctx: NavRenderContext }) {
+  const Icon = item.icon
+  const isActive = isPathActive(ctx.currentPath, item.path)
+  const { resolvedTheme } = useTheme()
+  const [open, setOpen] = useState(false)
+  const openedByPointer = useRef(false)
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const cancelClose = () => {
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current)
+      closeTimer.current = null
+    }
+  }
+  const scheduleClose = () => {
+    cancelClose()
+    closeTimer.current = setTimeout(() => setOpen(false), 120)
+  }
+
+  return (
+    <DropdownMenu.Root
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) openedByPointer.current = false
+        setOpen(next)
+      }}
+      modal={false}
+    >
+      <div
+        onMouseEnter={() => {
+          openedByPointer.current = true
+          cancelClose()
+          setOpen(true)
+        }}
+        onMouseLeave={scheduleClose}
+      >
+        <DropdownMenu.Trigger asChild>
+          <button
+            onClick={() => ctx.onNavigate(item.path)}
+            className={`flex w-full items-center justify-center rounded-lg px-3 py-2.5 transition-colors ${
+              isActive
+                ? 'bg-sidebar-accent text-sidebar-primary'
+                : 'text-sidebar-foreground hover:bg-sidebar-accent'
+            }`}
+            aria-label={item.label}
+            title={item.label}
+            aria-current={isActive ? 'page' : undefined}
+          >
+            <Icon className="h-5 w-5 shrink-0" aria-hidden />
+          </button>
+        </DropdownMenu.Trigger>
+      </div>
+
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content
+          side="right"
+          align="start"
+          sideOffset={10}
+          onMouseEnter={cancelClose}
+          onMouseLeave={scheduleClose}
+          onCloseAutoFocus={(e) => {
+            // After a pointer-driven open, don't yank focus back to the rail
+            // trigger (it would leave a stray focus ring once the cursor moves
+            // away). Keyboard-driven opens keep the default focus-return.
+            if (openedByPointer.current) e.preventDefault()
+          }}
+          // Radix portals to <body>, outside the `.actuate-admin` scope where
+          // the theme tokens (`--popover`, `--radius`, …) live — without the
+          // scope class the panel renders transparent with square corners.
+          // Re-assert the scope (and current dark state) on the panel itself so
+          // it inherits the tokens regardless of portal position.
+          className={`actuate-admin ${resolvedTheme === 'dark' ? 'dark' : ''} bg-popover text-popover-foreground border-border motion-safe:animate-in motion-safe:fade-in z-50 min-w-44 overflow-hidden rounded-lg border p-1 shadow-lg`}
+        >
+          <div className="text-muted-foreground border-border mb-1 border-b px-3 py-2 text-xs font-medium">
+            {item.label}
+          </div>
+          {item.children!.map((child) => {
+            const ChildIcon = child.icon
+            const childActive = isPathActive(ctx.currentPath, child.path)
+            return (
+              <DropdownMenu.Item
+                key={`flyout-item:${item.path}:${child.path}`}
+                onSelect={() => ctx.onNavigate(child.path)}
+                className={`data-highlighted:bg-accent hover:bg-accent flex cursor-pointer items-center gap-2.5 rounded-md px-3 py-2 text-sm font-medium outline-none select-none ${
+                  childActive ? 'text-primary' : 'text-foreground'
+                }`}
+                aria-current={childActive ? 'page' : undefined}
+              >
+                <ChildIcon className="text-muted-foreground h-4 w-4 shrink-0" aria-hidden />
+                <span className="truncate">{child.label}</span>
+              </DropdownMenu.Item>
+            )
+          })}
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  )
 }
 
 // ─── Config-driven nav builder ──────────────────────────────────────────────
@@ -460,12 +671,10 @@ export function buildNavItems(config: any): NavItem[] {
   }
   for (const bucket of groupBuckets.values()) items.push(...bucket)
 
-  // Settings destinations — always last.
-  items.push(
-    { path: '/users', label: 'Users', icon: Users, group: 'Settings' },
-    { path: '/api-keys', label: 'API Keys', icon: KeyRound, group: 'Settings' },
-    { path: '/settings', label: 'Settings', icon: Settings, group: 'Settings' },
-  )
+  // Settings destinations — always last. Users + API Keys now live inside
+  // the Settings view as tabs (see Settings.tsx), so only Settings is anchored
+  // here.
+  items.push({ path: '/settings', label: 'Settings', icon: Settings, group: 'Settings' })
 
   return items
 }

package/src/lib/seo-service.ts

@@ -10,6 +10,19 @@
  */
 import { cmsApi } from './api.js'
 
+/**
+ * `cmsApi` never throws — it returns `{ error, status }` on a network/HTTP
+ * failure. Read (GET) fetchers below must re-surface that as a thrown error so
+ * `useSeoResource` can distinguish "request failed" from "empty result".
+ * Without this, a failed `/seo/overview` would fall through to the empty
+ * fallback (a fake score of 0 / grade "Critical") and the error/retry UI would
+ * be permanently unreachable. Mutations intentionally return `{ error }` and do
+ * not use this.
+ */
+function throwIfError(res: { error?: string }): void {
+  if (res.error) throw new Error(res.error)
+}
+
 // ─── Shared enums ────────────────────────────────────────────────────
 
 export type SeoGrade = 'good' | 'fair' | 'poor' | 'critical'
@@ -110,6 +123,7 @@ const EMPTY_OVERVIEW: SeoOverview = {
 
 export async function fetchSeoOverview(): Promise<SeoOverview> {
   const res = await cmsApi<SeoOverview>('/seo/overview')
+  throwIfError(res)
   return res.data ?? EMPTY_OVERVIEW
 }
 
@@ -120,6 +134,7 @@ export async function fetchSearchPerformance(
 ): Promise<SearchPerformanceRow[]> {
   const qs = params.limit ? `?limit=${params.limit}` : ''
   const res = await cmsApi<{ rows: SearchPerformanceRow[] }>(`/seo/search-performance${qs}`)
+  throwIfError(res)
   return res.data?.rows ?? []
 }
 
@@ -155,6 +170,7 @@ export type ContentSeoFilter = 'all' | 'pages' | 'posts'
 
 export async function fetchSeoContentRecords(): Promise<SeoContentRecord[]> {
   const res = await cmsApi<{ records: SeoContentRecord[] }>('/seo/content')
+  throwIfError(res)
   return res.data?.records ?? []
 }
 
@@ -165,6 +181,7 @@ export async function fetchSeoContentRecord(
   const res = await cmsApi<SeoContentRecord>(
     `/seo/content/${entityType}/${encodeURIComponent(entityId)}`,
   )
+  throwIfError(res)
   return res.data ?? null
 }
 
@@ -257,11 +274,13 @@ export async function runSeoAudit(
 
 export async function fetchSeoAuditRuns(): Promise<SeoAuditRun[]> {
   const res = await cmsApi<{ runs: SeoAuditRun[] }>('/seo/audits')
+  throwIfError(res)
   return res.data?.runs ?? []
 }
 
 export async function fetchSeoAuditRun(auditRunId: string): Promise<SeoAuditRun | null> {
   const res = await cmsApi<SeoAuditRun>(`/seo/audits/${encodeURIComponent(auditRunId)}`)
+  throwIfError(res)
   return res.data ?? null
 }
 
@@ -280,11 +299,13 @@ export async function fetchSeoIssues(query: SeoIssueQuery = {}): Promise<SeoIssu
   if (query.auditRunId) params.set('auditRunId', query.auditRunId)
   const qs = params.toString()
   const res = await cmsApi<{ issues: SeoIssue[] }>(`/seo/issues${qs ? `?${qs}` : ''}`)
+  throwIfError(res)
   return res.data?.issues ?? []
 }
 
 export async function fetchSeoIssue(issueId: string): Promise<SeoIssue | null> {
   const res = await cmsApi<SeoIssue>(`/seo/issues/${encodeURIComponent(issueId)}`)
+  throwIfError(res)
   return res.data ?? null
 }
 
@@ -325,6 +346,7 @@ export interface CrawlSettings {
 
 export async function fetchSitemapStatus(): Promise<SitemapStatus | null> {
   const res = await cmsApi<SitemapStatus>('/seo/sitemap/status')
+  throwIfError(res)
   return res.data ?? null
 }
 
@@ -336,6 +358,7 @@ export async function regenerateSitemap(): Promise<{ status?: SitemapStatus; err
 
 export async function fetchCrawlSettings(): Promise<CrawlSettings | null> {
   const res = await cmsApi<CrawlSettings>('/seo/crawl-settings')
+  throwIfError(res)
   return res.data ?? null
 }
 
@@ -363,6 +386,7 @@ export interface RobotsValidation {
 
 export async function fetchRobotsTxt(): Promise<RobotsConfig | null> {
   const res = await cmsApi<RobotsConfig>('/seo/robots')
+  throwIfError(res)
   return res.data ?? null
 }
 
@@ -463,6 +487,7 @@ export interface RedirectChain {
 
 export async function fetchRedirectOverview(): Promise<RedirectOverview> {
   const res = await cmsApi<RedirectOverview>('/seo/redirects/overview')
+  throwIfError(res)
   return (
     res.data ?? {
       activeRedirects: 0,
@@ -477,6 +502,7 @@ export async function fetchRedirectOverview(): Promise<RedirectOverview> {
 
 export async function fetchRedirectRules(): Promise<RedirectRule[]> {
   const res = await cmsApi<{ rules: RedirectRule[] }>('/seo/redirects')
+  throwIfError(res)
   return res.data?.rules ?? []
 }
 
@@ -516,6 +542,7 @@ export async function deleteRedirectRule(redirectId: string): Promise<{ error?:
 
 export async function fetchRedirectChains(): Promise<RedirectChain[]> {
   const res = await cmsApi<{ chains: RedirectChain[] }>('/seo/redirects/chains')
+  throwIfError(res)
   return res.data?.chains ?? []
 }
 
@@ -529,6 +556,7 @@ export async function flattenRedirectChain(chainId: string): Promise<{ error?: s
 
 export async function fetchRedirectSuggestions(): Promise<RedirectSuggestion[]> {
   const res = await cmsApi<{ suggestions: RedirectSuggestion[] }>('/seo/redirects/suggestions')
+  throwIfError(res)
   return res.data?.suggestions ?? []
 }
 
@@ -582,6 +610,15 @@ export interface SeoAiResult {
   unavailable?: boolean
 }
 
+/**
+ * AI SEO endpoints report unavailability with two statuses: 501 (plugin-ai not
+ * installed) and 503 (installed but the provider isn't configured). Both map to
+ * the same graceful "AI unavailable" UX.
+ */
+function isAiUnavailable(status?: number): boolean {
+  return status === 501 || status === 503
+}
+
 export async function generateSeoField(
   field: 'metaTitle' | 'metaDescription' | 'ogTitle' | 'ogDescription' | 'focusKeyword',
   context: { entityType: string; entityId: string },
@@ -590,7 +627,7 @@ export async function generateSeoField(
     method: 'POST',
     body: JSON.stringify({ field, ...context }),
   })
-  if (res.status === 501) return { unavailable: true }
+  if (isAiUnavailable(res.status)) return { unavailable: true }
   return res.data ?? {}
 }
 
@@ -599,7 +636,7 @@ export async function explainSeoIssue(issueId: string): Promise<SeoAiResult> {
     method: 'POST',
     body: JSON.stringify({ issueId }),
   })
-  if (res.status === 501) return { unavailable: true }
+  if (isAiUnavailable(res.status)) return { unavailable: true }
   return res.data ?? {}
 }
 
@@ -612,12 +649,12 @@ export async function generateStructuredData(context: {
     method: 'POST',
     body: JSON.stringify(context),
   })
-  if (res.status === 501) return { unavailable: true }
+  if (isAiUnavailable(res.status)) return { unavailable: true }
   return res.data ?? {}
 }
 
 export async function summarizeSeoAudit(): Promise<SeoAiResult> {
   const res = await cmsApi<SeoAiResult>('/ai/seo/summarize', { method: 'POST' })
-  if (res.status === 501) return { unavailable: true }
+  if (isAiUnavailable(res.status)) return { unavailable: true }
   return res.data ?? {}
 }

package/src/views/ApiKeys.tsx

@@ -19,6 +19,9 @@ import { cmsApi } from '../lib/api.js'
 
 export interface ApiKeysProps {
   onNavigate?: (path: string) => void
+  /** When rendered inside the Settings tab shell, drop the page padding and
+   * demote the heading so it reads as a section rather than a second page. */
+  embedded?: boolean
 }
 
 interface ApiKeyRecord {
@@ -68,12 +71,14 @@ function formatDate(value: string | null): string {
   }
 }
 
-export function ApiKeys(_props: ApiKeysProps) {
+export function ApiKeys({ embedded = false }: ApiKeysProps = {}) {
   const { data, loading, error, refetch } = useApiData<ApiKeyRecord[]>('/api-keys')
   const [showCreate, setShowCreate] = useState(false)
   const [createdKey, setCreatedKey] = useState<{ key: string; record: ApiKeyRecord } | null>(null)
 
   const keys = data ?? []
+  const rootPadding = embedded ? '' : 'p-4 sm:p-6'
+  const Heading = embedded ? 'h2' : 'h1'
 
   const handleRevoke = async (id: string, name: string) => {
     if (!confirm(`Revoke API key "${name}"? This cannot be undone.`)) return
@@ -93,20 +98,20 @@ export function ApiKeys(_props: ApiKeysProps) {
 
   if (loading) {
     return (
-      <div className="flex h-64 items-center justify-center p-4 sm:p-6">
+      <div className={`flex h-64 items-center justify-center ${embedded ? '' : 'p-4 sm:p-6'}`}>
         <Loader2 className="h-6 w-6 animate-spin text-blue-600" />
       </div>
     )
   }
 
   return (
-    <div className="p-4 sm:p-6">
+    <div className={rootPadding}>
       <div className="mb-6 flex flex-col justify-between gap-3 sm:flex-row sm:items-center">
         <div>
-          <h1 className="flex items-center gap-2 text-xl font-semibold text-gray-900 sm:text-2xl">
+          <Heading className="flex items-center gap-2 text-xl font-semibold text-gray-900 sm:text-2xl">
             <KeyRound className="h-5 w-5 text-gray-500" />
             API Keys
-          </h1>
+          </Heading>
           <p className="mt-1 text-sm text-gray-500">
             Long-lived credentials for programmatic access. Use the{' '}
             <code className="rounded bg-gray-100 px-1 py-0.5 text-xs">Authorization: Bearer</code>{' '}

package/src/views/Dashboard.tsx

@@ -425,7 +425,7 @@ export function Dashboard({ config, session, onNavigate }: DashboardProps) {
       { label: 'New Page', icon: Plus, onClick: () => nav(`/${pagesSlug}/new`) },
       { label: 'Upload Media', icon: Upload, onClick: () => nav('/media') },
       { label: 'New Form', icon: Plus, onClick: () => nav('/forms') },
-      { label: 'View API', icon: Globe, onClick: () => nav('/api-keys') },
+      { label: 'View API', icon: Globe, onClick: () => nav('/settings?tab=api-keys') },
     ]
     return items
   }, [collections, onNavigate]) // eslint-disable-line react-hooks/exhaustive-deps
@@ -899,7 +899,7 @@ export function Dashboard({ config, session, onNavigate }: DashboardProps) {
           </div>
           <button
             className="text-brand inline-flex items-center gap-1 text-xs font-medium hover:underline"
-            onClick={() => nav('/api-keys')}
+            onClick={() => nav('/settings?tab=api-keys')}
           >
             API docs <ExternalLink className="h-3 w-3" />
           </button>

package/src/views/Forms.tsx

@@ -106,7 +106,9 @@ export function Forms({ onNavigate }: FormsProps) {
               <div className="mb-3 flex items-center gap-4 text-sm text-gray-600">
                 <span className="flex items-center gap-1">
                   <FileText className="h-4 w-4" />
-                  {form.fields} fields
+                  {form.fieldCount ??
+                    (Array.isArray(form.fields) ? form.fields.length : form.fields)}{' '}
+                  fields
                 </span>
                 <span className="flex items-center gap-1">
                   <Send className="h-4 w-4" />