berrypod/docs/plans/admin-ux-polish.md

# Admin & page editor UX polish

Status: Complete

## Context

Full UX audit of the admin panel and page editing experience, evaluating intuitiveness, completeness, and newbie-friendliness. The admin is solid and well-built — good accessibility, clear status indicators, logical flow. The gaps are around preventing data loss, helping newbies understand block types, and tidying up navigation.

## What works well

- Dashboard launch checklist with direct links to each setup step
- Split-screen page editor with live preview, undo/redo, keyboard shortcuts
- ARIA labels on all block controls, live region announcements
- Clear dirty state tracking (badge + disabled save button)
- Legal page auto-population with "auto-generated" vs "customised" badges
- Live editing on shop pages via sidebar with same block card UI
- Custom page creation with templates (blank/content/landing)
- Shop header shows "Edit page" and "Admin" icons for logged-in admins
- Settings page with status pills and helpful setup guidance

## Tasks

### High priority

#### 1. Unsaved changes warning
**Problem:** No `beforeunload` handler or LiveView navigation guard. Clicking "Pages" breadcrumb or any sidebar link silently discards all unsaved changes.
**Fix:** Add a `beforeunload` event listener in the `EditorKeyboard` JS hook that checks `data-dirty`. Also handle LiveView `phx-remove` / navigation events to warn before leaving.
**Files:** `assets/js/hooks/editor_keyboard.js`, possibly `lib/berrypod_web/live/admin/pages/editor.ex`
**Est:** 30m

#### 2. Block descriptions in picker
**Problem:** Block picker shows icon + name only. "Info card" vs "Trust badges" vs "Image + text" — a newbie doesn't know what these do or look like.
**Fix:** Add a `description` field to each block type in `BlockTypes`. Show it as a subtitle in the picker modal.
**Files:** `lib/berrypod/pages/block_types.ex`, `lib/berrypod_web/components/block_editor_components.ex`
**Est:** 45m

### Medium priority

#### 3. Sidebar nav grouping
**Problem:** 12 top-level items in the admin sidebar is too flat. Dashboard, Analytics, Orders, Products, Providers, Pages, Navigation, Media, Theme, Settings, Email, Redirects — a wall of links with no visual hierarchy.
**Fix:** Add subtle section headers to group related items:
- **Shop** — Dashboard, Analytics, Orders, Products, Providers
- **Content** — Pages, Navigation, Media
- **Appearance** — Theme
- **Settings** — Settings, Email, Redirects

Alternatively, nest Email under Settings (it's email *settings*) and move Redirects into a Settings sub-page. That drops to 10 items with clearer grouping.
**Files:** `lib/berrypod_web/components/layouts/admin.html.heex`, `assets/css/admin/components.css`
**Est:** 45m

#### 4. Nav editor input labels
**Problem:** Navigation editor shows pairs of text inputs with placeholder text ("Label", "/path") but no visible labels. Accessibility issue and confusing for new users.
**Fix:** Add visible `<label>` elements above each input pair, or at minimum a row header like "Link 1", "Link 2". Consider showing a small preview of each link.
**Files:** `lib/berrypod_web/live/admin/navigation.ex`
**Est:** 30m

#### 5. Custom page settings inline
**Problem:** Clicking "Settings" on a custom page editor navigates away to `/admin/pages/:slug/settings`, losing editing context. Round-tripping between editor and settings is jarring.
**Fix:** Show page settings (title, slug, meta description, published, show in nav) in a collapsible panel at the top of the editor, or in a slide-over panel. Keep the separate settings page as a fallback but make inline editing the default.
**Files:** `lib/berrypod_web/live/admin/pages/editor.ex`
**Est:** 1h

#### 6. Preview with real data
**Problem:** Admin editor preview uses `PreviewData` (fake products, fake cart). The user's actual products don't appear. This means the preview doesn't accurately represent the live shop. The live editor on shop pages uses real data and doesn't have this problem.
**Fix:** Load real products/categories/cart from the database for preview, falling back to `PreviewData` if no products exist yet (fresh install). This makes the admin preview match what the shop actually looks like.
**Files:** `lib/berrypod_web/live/admin/pages/editor.ex` (mount, preview_pane)
**Est:** 45m

### Low priority

#### 7. Block content preview in list
**Problem:** Block settings are hidden behind a gear icon toggle. The block list is just type names with position numbers — no indication of content. You can't scan and see "this hero says 'Welcome to my shop'" without expanding each block.
**Fix:** Show a one-line content preview below the block name (e.g. first text field value, truncated). Only for blocks that have text settings.
**Files:** `lib/berrypod_web/components/block_editor_components.ex` (block_card)
**Est:** 45m

#### 8. "Providers" label clarity
**Problem:** "Providers" is jargon. A newbie selling mugs doesn't know what a "provider" is in this context.
**Fix:** Rename to "Print providers" in the sidebar. Consider "Suppliers" as an alternative. Update the nav label only — the route and module names can stay as-is.
**Files:** `lib/berrypod_web/components/layouts/admin.html.heex`
**Est:** 5m

#### 9. Newsletter block backend
**Problem:** The newsletter signup form renders on the shop but has no backend handler. A user adds it to their page thinking it works, then discovers email signups go nowhere.
**Fix:** Either: (a) wire up a simple email collection table + controller so signups are stored, or (b) add a note in the block settings saying "Coming soon — this block is currently decorative" and mark it visually in the editor.
**Files:** TBD depending on approach
**Est:** 1-3h depending on approach

#### 10. Block preview thumbnails in picker
**Problem:** Block picker shows names and descriptions (after task 2) but no visual preview. Users still have to guess what blocks look like.
**Fix:** Add a small screenshot or SVG illustration for each block type in the picker. Could be static images stored in `priv/static/images/blocks/`.
**Files:** `lib/berrypod_web/components/block_editor_components.ex`, static assets
**Est:** 2h (mostly creating the images)

## Summary table

| # | Task | Priority | Est |
|---|------|----------|-----|
| 1 | Unsaved changes warning | High | 30m |
| 2 | Block descriptions in picker | High | 45m |
| 3 | Sidebar nav grouping | Medium | 45m |
| 4 | Nav editor input labels | Medium | 30m |
| 5 | Custom page settings inline | Medium | 1h |
| 6 | Preview with real data | Medium | 45m |
| 7 | Block content preview in list | Low | 45m |
| 8 | "Providers" label clarity | Low | 5m |
| 9 | Newsletter block backend | Low | 1-3h |
| 10 | Block preview thumbnails | Low | 2h |

Total: ~8-10h across all tasks