@prenta/admin 2.6.1 → 2.8.0

package/src/__tests__/views/appearance-menus-route.render.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import { navigationCollections } from '@prenta/plugin-navigation'
+
+vi.mock('../../lib/api.js', () => ({
+  cmsApi: vi.fn(async () => ({ data: { docs: [] }, status: 200 })),
+  ensureCsrfToken: vi.fn(async () => undefined),
+  setApiBase: vi.fn(),
+  getApiBase: () => '',
+}))
+
+const storage = new Map<string, string>()
+vi.stubGlobal('localStorage', {
+  getItem: (key: string) => storage.get(key) ?? null,
+  setItem: (key: string, value: string) => void storage.set(key, String(value)),
+  removeItem: (key: string) => void storage.delete(key),
+  clear: () => storage.clear(),
+})
+
+const { AdminRoot } = await import('../../AdminRoot.js')
+
+afterEach(() => {
+  cleanup()
+  window.history.replaceState({}, '', '/')
+})
+
+const session = { user: { id: 'u1', email: 'admin@example.com', role: 'ADMIN' } }
+const pages = { slug: 'pages', labels: { singular: 'Page', plural: 'Pages' }, type: 'page' }
+
+function renderAt(config: object) {
+  window.history.replaceState({}, '', '/admin/appearance/menus')
+  render(<AdminRoot config={config} session={session} initialPath="/appearance/menus" />)
+}
+
+/**
+ * `/appearance/menus` used to render a placeholder with hard-coded `main` and
+ * `legal` menus that loaded and saved nothing. It now forwards to the working
+ * navigations editor, or 404s when there are no menus to edit.
+ */
+describe('/appearance/menus', () => {
+  it('opens the navigations collection when plugin-navigation is installed', async () => {
+    renderAt({ collections: { pages, ...navigationCollections } })
+
+    expect(await screen.findByRole('heading', { name: 'Navigations' })).toBeTruthy()
+    await waitFor(() => expect(window.location.pathname).toBe('/admin/navigations'))
+    expect(screen.queryByText('legal')).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Show in header' })).toBeNull()
+  })
+
+  it('does not render demo menus when plugin-navigation is not installed', async () => {
+    renderAt({ collections: { pages } })
+
+    expect(await screen.findByText('The page you are looking for does not exist.')).toBeTruthy()
+    expect(screen.queryByText('legal')).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Show in header' })).toBeNull()
+  })
+})

package/src/__tests__/views/appearance-settings.render.test.tsx

@@ -73,17 +73,15 @@ describe('AppearanceTab', () => {
     expect(screen.getByText('Admin theme')).toBeTruthy()
     expect(screen.getByText('Typography & motion')).toBeTruthy()
     expect(screen.getByText('Brand preview')).toBeTruthy()
-    expect(
-      (screen.getByRole('button', { name: 'Save Changes' }) as HTMLButtonElement).disabled,
-    ).toBe(true)
+    expect(screen.queryByRole('button', { name: 'Save changes' })).toBeNull()
   })
 
   it('enables Save when the accent changes and persists appearance to the settings global', async () => {
     render(<AppearanceTab role="ADMIN" />)
     await screen.findByText('Branding')
 
-    fireEvent.click(screen.getByRole('radio', { name: 'Blue' }))
-    const save = screen.getByRole('button', { name: 'Save Changes' }) as HTMLButtonElement
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    const save = screen.getByRole('button', { name: 'Save changes' }) as HTMLButtonElement
     expect(save.disabled).toBe(false)
 
     fireEvent.click(save)
@@ -93,7 +91,7 @@ describe('AppearanceTab', () => {
         '/globals/settings',
         expect.objectContaining({
           method: 'PUT',
-          body: expect.stringContaining('"adminAccentColor":"blue"'),
+          body: expect.stringContaining('"adminAccentColor":"teal"'),
         }),
       ),
     )
@@ -105,6 +103,10 @@ describe('AppearanceTab', () => {
     expect(String((saveCall?.[1] as { body?: string } | undefined)?.body)).toContain(
       '"publicTheme"',
     )
+    // Saved means clean: the dirty-only bar goes away.
+    await waitFor(() =>
+      expect(screen.queryByRole('region', { name: 'Unsaved changes' })).toBeNull(),
+    )
   })
 
   it('warns when dark mode is the default but no dark-mode logo is set', async () => {
@@ -142,7 +144,7 @@ describe('AppearanceTab', () => {
     )
     await waitFor(() =>
       expect(
-        (screen.getByRole('button', { name: 'Save Changes' }) as HTMLButtonElement).disabled,
+        (screen.getByRole('button', { name: 'Save changes' }) as HTMLButtonElement).disabled,
       ).toBe(false),
     )
   })
@@ -159,7 +161,7 @@ describe('AppearanceTab', () => {
     // No upload should be issued — we reference the existing asset by id.
     expect(cmsApi.mock.calls.some(([endpoint]) => endpoint === '/media/upload')).toBe(false)
 
-    const save = await screen.findByRole('button', { name: 'Save Changes' })
+    const save = await screen.findByRole('button', { name: 'Save changes' })
     await waitFor(() => expect((save as HTMLButtonElement).disabled).toBe(false))
     fireEvent.click(save)
 

package/src/__tests__/views/appearance-theme-provider.render.test.tsx

@@ -0,0 +1,347 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+
+import { ADMIN_ROOT_ATTR } from '../../lib/admin-root-element.js'
+
+/**
+ * Settings → Admin appearance mounted inside the REAL ThemeProvider. Picking
+ * an accent or a base applies it live; it must stay picked (and the tab dirty)
+ * until Save. A provider whose setters change identity on every pick makes
+ * the tab refetch /appearance and silently put the saved values back — which
+ * the provider-less render test can't see.
+ */
+
+type ApiResult = { data?: unknown; error?: string; status: number }
+
+let appearanceData: Record<string, unknown>
+let appearanceGets = 0
+/** The settings PUT; a test swaps it to hold the save in flight or fail it. */
+let putSettings: () => Promise<ApiResult>
+
+const cmsApi = vi.fn(async (endpoint: string, options?: { method?: string; body?: unknown }) => {
+  const method = options?.method ?? 'GET'
+  if (endpoint === '/appearance' && method === 'GET') {
+    appearanceGets++
+    return { data: appearanceData, status: 200 }
+  }
+  if (endpoint === '/globals/settings' && method === 'GET')
+    return { data: { siteTitle: 'Actuate Media' }, status: 200 }
+  if (endpoint === '/globals/settings' && method === 'PUT') return putSettings()
+  return { data: {}, status: 200 }
+})
+
+vi.mock('../../lib/api.js', () => ({
+  cmsApi: (e: string, o?: { method?: string; body?: unknown }) => cmsApi(e, o),
+}))
+
+const { AppearanceTab } = await import('../../views/settings/AppearanceTab.js')
+const { ThemeProvider } = await import('../../components/ThemeProvider.js')
+const { toast } = await import('sonner')
+
+/** A settings PUT that stays in flight until the test settles it. */
+function holdPut() {
+  let settle!: (result: ApiResult) => void
+  putSettings = () =>
+    new Promise<ApiResult>((resolve) => {
+      settle = resolve
+    })
+  return (result: ApiResult) => act(async () => settle(result))
+}
+
+const storage = new Map<string, string>()
+
+beforeEach(() => {
+  cmsApi.mockClear()
+  appearanceGets = 0
+  putSettings = async () => ({ data: {}, status: 200 })
+  storage.clear()
+  vi.stubGlobal('localStorage', {
+    getItem: (key: string) => storage.get(key) ?? null,
+    setItem: (key: string, value: string) => storage.set(key, value),
+    removeItem: (key: string) => storage.delete(key),
+    clear: () => storage.clear(),
+  })
+  appearanceData = {
+    appearance: {
+      adminColorModeDefault: 'light',
+      adminLightBase: 'porcelain',
+      adminAccentColor: 'cobalt',
+      sidebarDensity: 'default',
+      contentFont: 'DM Sans',
+      reduceMotion: false,
+    },
+    brand: { mode: 'inheritPublicBrand' },
+    resolved: { admin: { initials: 'AM' } },
+    assets: [],
+    siteTitle: 'Actuate Media',
+  }
+})
+
+afterEach(() => {
+  cleanup()
+  document.body.innerHTML = ''
+  vi.unstubAllGlobals()
+})
+
+/** The tab inside the provider; `show={false}` is leaving the tab. */
+function Harness({ show = true, primaryColor }: { show?: boolean; primaryColor?: string }) {
+  const config = primaryColor ? { admin: { branding: { primaryColor } } } : undefined
+  return (
+    <ThemeProvider accentOverride={primaryColor}>
+      {show ? <AppearanceTab role="ADMIN" config={config} /> : <span>elsewhere</span>}
+    </ThemeProvider>
+  )
+}
+
+function mount(props: { primaryColor?: string } = {}) {
+  const root = document.createElement('div')
+  root.className = 'prenta-admin'
+  root.setAttribute(ADMIN_ROOT_ATTR, '')
+  document.body.appendChild(root)
+  const view = render(<Harness {...props} />, { container: root })
+  return Object.assign(root, { leave: () => view.rerender(<Harness {...props} show={false} />) })
+}
+
+/** Let effects that a changed callback identity would trigger run. */
+const settle = () => act(() => new Promise((r) => setTimeout(r, 30)))
+
+const saveButton = () => screen.queryByRole('button', { name: 'Save changes' }) as HTMLButtonElement
+
+describe('Admin appearance inside ThemeProvider', () => {
+  it('keeps accent, custom hex and base picks until Save, then persists them', async () => {
+    const root = mount()
+    await screen.findByText('Base theme')
+    await settle()
+    expect(appearanceGets).toBe(1)
+
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    await settle()
+    expect(screen.getByRole('radio', { name: 'Teal' }).getAttribute('aria-checked')).toBe('true')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    expect(saveButton().disabled).toBe(false)
+
+    fireEvent.change(screen.getByLabelText('Accent hex value'), { target: { value: '#FFD400' } })
+    await settle()
+    expect(screen.getByText('Custom')).toBeTruthy()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#ffd400')
+
+    fireEvent.click(screen.getByRole('radio', { name: /Graphite/ }))
+    await settle()
+    expect(screen.getByRole('radio', { name: /Graphite/ }).getAttribute('aria-checked')).toBe(
+      'true',
+    )
+    expect(root.getAttribute('data-theme')).toBe('dark')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#ffd400')
+
+    // Nothing refetched and overwrote the edits.
+    expect(appearanceGets).toBe(1)
+    expect(saveButton().disabled).toBe(false)
+
+    fireEvent.click(saveButton())
+    await waitFor(() =>
+      expect(cmsApi).toHaveBeenCalledWith(
+        '/globals/settings',
+        expect.objectContaining({ method: 'PUT' }),
+      ),
+    )
+    const put = cmsApi.mock.calls.find(
+      (c) => c[0] === '/globals/settings' && (c[1] as { method?: string })?.method === 'PUT',
+    )!
+    const body = JSON.parse(String((put[1] as { body: string }).body))
+    expect(body.appearance).toMatchObject({
+      adminAccentColor: '#ffd400',
+      adminColorModeDefault: 'dark',
+      adminLightBase: 'porcelain',
+    })
+    await settle()
+    expect(root.getAttribute('data-theme')).toBe('dark')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#ffd400')
+  })
+
+  it('keeps Linen and Match operating system picks', async () => {
+    const root = mount()
+    await screen.findByText('Base theme')
+
+    fireEvent.click(screen.getByRole('radio', { name: /Linen/ }))
+    await settle()
+    expect(root.getAttribute('data-light')).toBe('linen')
+    fireEvent.click(screen.getByRole('switch', { name: 'Match operating system' }))
+    await settle()
+    expect(
+      screen.getByRole('switch', { name: 'Match operating system' }).getAttribute('aria-checked'),
+    ).toBe('true')
+    expect(screen.getByText(/Uses Linen by day/)).toBeTruthy()
+    expect(appearanceGets).toBe(1)
+    expect(saveButton().disabled).toBe(false)
+  })
+
+  it('puts the saved look back when you leave with unsaved picks', async () => {
+    const root = mount()
+    await screen.findByText('Base theme')
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    fireEvent.click(screen.getByRole('radio', { name: /Graphite/ }))
+    fireEvent.click(screen.getByRole('radio', { name: /Linen/ }))
+    fireEvent.click(screen.getByRole('radio', { name: /Graphite/ }))
+    await settle()
+    expect(root.getAttribute('data-theme')).toBe('dark')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+
+    root.leave()
+    await settle()
+    expect(root.getAttribute('data-theme')).toBe('light')
+    expect(root.getAttribute('data-light')).toBe('porcelain')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#2f5bea')
+    expect(storage.get('prenta-accent')).toBe('cobalt')
+    expect(storage.get('prenta-theme')).toBe('light')
+    expect(storage.get('prenta-light')).toBe('porcelain')
+  })
+
+  it('keeps saved picks when you leave after saving', async () => {
+    const root = mount()
+    await screen.findByText('Base theme')
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    await settle()
+    fireEvent.click(saveButton())
+    await waitFor(() => expect(saveButton()).toBeNull())
+
+    root.leave()
+    await settle()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    expect(storage.get('prenta-accent')).toBe('teal')
+  })
+
+  it('Reset puts back the saved snapshot, live preview included', async () => {
+    const root = mount()
+    await screen.findByText('Base theme')
+    await settle()
+    expect(screen.queryByRole('region', { name: 'Unsaved changes' })).toBeNull()
+
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    fireEvent.click(screen.getByRole('radio', { name: /Graphite/ }))
+    fireEvent.click(screen.getByRole('radio', { name: 'Compact' }))
+    fireEvent.change(screen.getByLabelText('Content font'), { target: { value: 'Inter' } })
+    await settle()
+    expect(root.getAttribute('data-theme')).toBe('dark')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    expect(root.getAttribute('data-density')).toBe('compact')
+    expect(root.style.getPropertyValue('--prenta-admin-font')).toContain("'Inter'")
+
+    fireEvent.click(screen.getByRole('button', { name: 'Reset' }))
+    await settle()
+    expect(screen.queryByRole('region', { name: 'Unsaved changes' })).toBeNull()
+    expect(root.getAttribute('data-theme')).toBe('light')
+    expect(root.getAttribute('data-light')).toBe('porcelain')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#2f5bea')
+    expect(root.getAttribute('data-density')).toBe('default')
+    expect(root.style.getPropertyValue('--prenta-admin-font')).toContain("'DM Sans'")
+    expect(screen.getByRole('radio', { name: 'Cobalt' }).getAttribute('aria-checked')).toBe('true')
+    expect(screen.getByRole('radio', { name: 'Default' }).getAttribute('aria-checked')).toBe('true')
+    expect((screen.getByLabelText('Content font') as HTMLSelectElement).value).toBe('DM Sans')
+    expect(storage.get('prenta-accent')).toBe('cobalt')
+    expect(storage.get('prenta-density')).toBe('default')
+    expect(storage.get('prenta-font')).toBe('DM Sans')
+  })
+
+  it('Reset goes back to the last save, not to what was first loaded', async () => {
+    const root = mount()
+    await screen.findByText('Base theme')
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    await settle()
+    fireEvent.click(saveButton())
+    await waitFor(() => expect(saveButton()).toBeNull())
+
+    fireEvent.click(screen.getByRole('radio', { name: /Graphite/ }))
+    fireEvent.click(screen.getByRole('radio', { name: 'Compact' }))
+    await settle()
+    fireEvent.click(screen.getByRole('button', { name: 'Reset' }))
+    await settle()
+    expect(saveButton()).toBeNull()
+    expect(root.getAttribute('data-theme')).toBe('light')
+    expect(root.getAttribute('data-density')).toBe('default')
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    expect(screen.getByRole('radio', { name: 'Teal' }).getAttribute('aria-checked')).toBe('true')
+  })
+
+  it('keeps the look being saved when you leave while the save is in flight', async () => {
+    const toastSuccess = vi.spyOn(toast, 'success')
+    const finishPut = holdPut()
+    const root = mount()
+    await screen.findByText('Base theme')
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    await settle()
+    fireEvent.click(saveButton())
+    await waitFor(() => expect(screen.getByRole('button', { name: 'Saving…' })).toBeTruthy())
+
+    root.leave()
+    await settle()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    expect(storage.get('prenta-accent')).toBe('teal')
+
+    await finishPut({ data: {}, status: 200 })
+    await settle()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    expect(storage.get('prenta-accent')).toBe('teal')
+    // The tab's own "Saved" toast left with it, so the hook confirms instead.
+    expect(toastSuccess).toHaveBeenCalledWith('Saved')
+    toastSuccess.mockRestore()
+  })
+
+  it('puts the saved look back, and says so, when a save fails after you leave', async () => {
+    const toastError = vi.spyOn(toast, 'error')
+    const finishPut = holdPut()
+    const root = mount()
+    await screen.findByText('Base theme')
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    await settle()
+    fireEvent.click(saveButton())
+    await waitFor(() => expect(screen.getByRole('button', { name: 'Saving…' })).toBeTruthy())
+    root.leave()
+    await settle()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+
+    await finishPut({ error: 'Server unavailable', status: 503 })
+    await settle()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#2f5bea')
+    expect(storage.get('prenta-accent')).toBe('cobalt')
+    expect(toastError).toHaveBeenCalledWith(expect.stringContaining('Server unavailable'))
+    toastError.mockRestore()
+  })
+
+  it('keeps the unsaved picks on screen when a save fails while you stay', async () => {
+    const toastError = vi.spyOn(toast, 'error')
+    putSettings = async () => ({ error: 'Server unavailable', status: 503 })
+    const root = mount()
+    await screen.findByText('Base theme')
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    await settle()
+    fireEvent.click(saveButton())
+    expect(await screen.findByText('Server unavailable')).toBeTruthy()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    expect(saveButton().disabled).toBe(false)
+    // The tab shows the error itself; no toast on top.
+    expect(toastError).not.toHaveBeenCalled()
+    toastError.mockRestore()
+  })
+
+  it('locks the accent to a usable config color, in any CSS form tuneAccent reads', async () => {
+    const root = mount({ primaryColor: 'rgb(79 70 229)' })
+    await screen.findByText('Base theme')
+    await settle()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#4f46e5')
+    expect((screen.getByRole('radio', { name: 'Teal' }) as HTMLButtonElement).disabled).toBe(true)
+  })
+
+  it('keeps the accent editable, and warns, when the config color is unusable', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const root = mount({ primaryColor: 'blurple' })
+    await screen.findByText('Base theme')
+    await settle()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('"blurple"'))
+    expect((screen.getByRole('radio', { name: 'Teal' }) as HTMLButtonElement).disabled).toBe(false)
+    fireEvent.click(screen.getByRole('radio', { name: 'Teal' }))
+    await settle()
+    expect(root.style.getPropertyValue('--acc-base')).toBe('#0f8a7e')
+    warn.mockRestore()
+  })
+})

package/src/__tests__/views/dashboard.test.tsx

@@ -208,3 +208,51 @@ describe('Dashboard', () => {
     expect(onNavigate).toHaveBeenCalledWith('/posts/blog/p9/edit')
   })
 })
+
+/**
+ * TRACKING P-06: the KPI grid (SHELL.md §8, Dashboard.html `.kpis`). Five
+ * cards are 5-up from 1400px, 2+3 on six tracks below, two columns on phones
+ * with the last card spanning both; four cards never leave an empty slot.
+ */
+describe('Dashboard KPI grid', () => {
+  const kpiCards = (grid: Element) => Array.from(grid.children) as HTMLElement[]
+
+  it('lays five cards out 5-up, 2+3, and 2+2+1 on phones', () => {
+    responses['/stats'] = statsResult()
+    const { container } = render(
+      <Dashboard
+        config={{
+          collections: [
+            { slug: 'posts', type: 'post', labels: { plural: 'Posts' } },
+            { slug: 'pages', type: 'page', labels: { plural: 'Pages' } },
+          ],
+        }}
+        session={{}}
+        onNavigate={() => {}}
+      />,
+    )
+    const grid = container.querySelector('[data-kpi-grid]')!
+    const cards = kpiCards(grid)
+    expect(cards).toHaveLength(5)
+    expect(grid.className).toContain('grid-cols-6')
+    expect(grid.className).toContain('min-[1400px]:grid-cols-5')
+    expect(grid.className).toContain('mobile:grid-cols-2')
+    expect(cards.slice(0, 2).every((c) => c.className.includes('col-span-3'))).toBe(true)
+    expect(cards.slice(2).every((c) => / col-span-2 /.test(` ${c.className} `))).toBe(true)
+    expect(cards.every((c) => c.className.includes('min-[1400px]:col-span-1'))).toBe(true)
+    expect(cards.slice(0, 4).every((c) => c.className.includes('mobile:col-span-1'))).toBe(true)
+    expect(cards[4]!.className).toContain('mobile:col-span-2')
+  })
+
+  it('lays four cards out 4-up and 2+2, with no empty slot', () => {
+    responses['/stats'] = statsResult()
+    const { container } = render(
+      <Dashboard config={{ collections: [] }} session={{}} onNavigate={() => {}} />,
+    )
+    const grid = container.querySelector('[data-kpi-grid]')!
+    expect(kpiCards(grid)).toHaveLength(4)
+    expect(grid.className).toContain('min-[1400px]:grid-cols-4')
+    expect(grid.className).not.toContain('grid-cols-6')
+    expect(kpiCards(grid).every((c) => !c.className.includes('col-span'))).toBe(true)
+  })
+})

package/src/__tests__/views/document-edit-navigation.render.test.tsx

@@ -0,0 +1,130 @@
+// @vitest-environment happy-dom
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const cmsApi = vi.fn(async (endpoint: string, options?: { method?: string }) => {
+  if (options?.method === 'POST') return { data: { id: 'doc-42' }, status: 201 }
+  if (endpoint.startsWith('/collections/faqs/doc-1')) {
+    return { data: { id: 'doc-1', title: 'Shipping', status: 'DRAFT' }, status: 200 }
+  }
+  return { data: {}, status: 200 }
+})
+vi.mock('../../lib/api.js', () => ({ cmsApi: (e: string, o?: unknown) => cmsApi(e, o as never) }))
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }))
+
+// PresenceIndicator opens a live stream for saved documents; happy-dom has none.
+vi.stubGlobal(
+  'EventSource',
+  class {
+    onmessage: unknown = null
+    onerror: unknown = null
+    addEventListener() {}
+    close() {}
+  },
+)
+
+const { DocumentEdit } = await import('../../views/DocumentEdit.js')
+
+const defaultAnswer = cmsApi.getMockImplementation()!
+
+afterEach(() => {
+  cleanup()
+  cmsApi.mockClear()
+  cmsApi.mockImplementation(defaultAnswer)
+})
+
+const config = {
+  collections: {
+    faqs: {
+      slug: 'faqs',
+      labels: { singular: 'FAQ', plural: 'FAQs' },
+      fields: [{ name: 'title', type: 'text', label: 'Title' }],
+    },
+  },
+}
+
+/**
+ * With the shell breadcrumb gone (P-03), the document screen's own breadcrumb,
+ * Cancel and post-create redirect are the way back; AdminRoot must pass
+ * `onNavigate` for them to work.
+ */
+describe('DocumentEdit navigation', () => {
+  it('links back to the list it came from and cancels to it', async () => {
+    const onNavigate = vi.fn()
+    render(
+      <DocumentEdit
+        collectionSlug="faqs"
+        documentId="doc-1"
+        config={config}
+        onNavigate={onNavigate}
+        listPath="/collections/faqs"
+      />,
+    )
+    const crumbs = await screen.findByRole('navigation', { name: 'Breadcrumb' })
+    expect(crumbs.textContent).toContain('FAQs')
+    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }))
+    expect(onNavigate).toHaveBeenCalledWith('/collections/faqs')
+  })
+
+  it('opens the new document under its list after create', async () => {
+    const onNavigate = vi.fn()
+    render(<DocumentEdit collectionSlug="faqs" config={config} onNavigate={onNavigate} />)
+    fireEvent.click(await screen.findByRole('button', { name: 'Create' }))
+    await waitFor(() => expect(onNavigate).toHaveBeenCalledWith('/faqs/doc-42'))
+    expect(cmsApi).toHaveBeenCalledWith(
+      '/collections/faqs',
+      expect.objectContaining({ method: 'POST' }),
+    )
+  })
+
+  it('keeps the fields read-only while the document is being created', async () => {
+    let finish: (value: unknown) => void = () => {}
+    const answer = cmsApi.getMockImplementation()!
+    cmsApi.mockImplementation((endpoint, options) =>
+      options?.method === 'POST'
+        ? (new Promise<unknown>((resolve) => {
+            finish = resolve
+          }) as never)
+        : answer(endpoint, options),
+    )
+    const onNavigate = vi.fn()
+    const { container } = render(
+      <DocumentEdit collectionSlug="faqs" config={config} onNavigate={onNavigate} />,
+    )
+    const create = await screen.findByRole('button', { name: 'Create' })
+    const input = container.querySelector('input') as HTMLInputElement
+    const fields = input.closest('.grid') as HTMLElement & { inert?: boolean }
+    expect(fields.inert).toBeFalsy()
+    fireEvent.click(create)
+    await waitFor(() => expect(fields.inert).toBe(true))
+    expect(fields.getAttribute('aria-busy')).toBe('true')
+    finish({ data: { id: 'doc-42' }, status: 201 })
+    await waitFor(() => expect(onNavigate).toHaveBeenCalledWith('/faqs/doc-42'))
+  })
+
+  it('gives the fields and focus back when the create fails', async () => {
+    let finish: (value: unknown) => void = () => {}
+    const answer = cmsApi.getMockImplementation()!
+    cmsApi.mockImplementation((endpoint, options) =>
+      options?.method === 'POST'
+        ? (new Promise<unknown>((resolve) => {
+            finish = resolve
+          }) as never)
+        : answer(endpoint, options),
+    )
+    const onNavigate = vi.fn()
+    const { container } = render(
+      <DocumentEdit collectionSlug="faqs" config={config} onNavigate={onNavigate} />,
+    )
+    const create = await screen.findByRole('button', { name: 'Create' })
+    const input = container.querySelector('input') as HTMLInputElement
+    const fields = input.closest('.grid') as HTMLElement & { inert?: boolean }
+    input.focus()
+    fireEvent.click(create)
+    await waitFor(() => expect(fields.inert).toBe(true))
+    finish({ error: 'Slug taken', status: 409 })
+    await waitFor(() => expect(fields.inert).toBe(false))
+    expect(document.activeElement).toBe(input)
+    expect(onNavigate).not.toHaveBeenCalled()
+  })
+})