berrypod/docs/plans/live-site-editor.md

# Live site editor

Status: Design exploration

A live, on-site editing experience where admins browse their real shop with an editing overlay. Change theme settings, edit page content, and adjust block settings — all while seeing the result immediately on the actual site.

## Inspiration

Squarespace, Webflow, Shopify's theme customiser. The common pattern: you're looking at your real site, with an editing panel alongside it. Changes apply live. No separate "admin preview" — what you see is what your customers get.

## Core concept

### Edit mode

Logged-in admins see a small floating "Edit" button (or pencil icon) on their shop. Clicking it enters edit mode. This is invisible to regular visitors.

### Layout by screen size

**Mobile / small screens (< 768px):**
- Full-width site view
- Tap a block or element to select it
- Bottom sheet or full-screen overlay slides up with settings for the selected item
- Swipe down or tap outside to dismiss
- A small floating toolbar stays visible (edit toggle, undo, save)

**Tablet / medium screens (768px–1024px):**
- Site view takes most of the width
- Sidebar slides in from the left or right, narrower (250–300px)
- Site content reflows to fit

**Desktop / large screens (> 1024px):**
- Split view: sidebar (350–400px) on the left, live site preview on the right
- Sidebar has full settings panels
- Site renders at remaining width, giving a realistic preview

### What's editable

**Theme settings (global):**
- Preset picker (the 8 existing presets)
- Colour tokens (primary, surface, text, accent)
- Typography (font family, sizes, weights)
- Layout settings (max-width, spacing)
- Logo, header image, favicon

These already work via CSS custom properties — changes can apply instantly client-side before saving, exactly like the current theme editor.

**Page content (per-page):**
- Block list: reorder, add, remove blocks
- Block settings: layout, styling, images — shown in sidebar when a block is selected
- **Inline text editing**: `contenteditable` for text content within blocks (headings, paragraphs, button labels). Edit directly on the page, changes sync back to block data via LiveView events.

**Page settings:**
- Title, slug, SEO metadata, publish status
- Accessible from the sidebar when no block is selected

### Interaction model

1. **Click a block on the page** → block highlights (outline/overlay), sidebar shows that block's settings
2. **Click text within a block** → enters inline editing mode (`contenteditable`). Sidebar shows block settings alongside.
3. **Edit in sidebar** → changes apply live to the page (theme via CSS vars, blocks via LiveView re-render)
4. **Sidebar tabs/sections:** "Theme" (global settings) and "Page" (current page's blocks and settings)
5. **Save** → persists all changes. Unsaved changes indicator in toolbar.
6. **Exit edit mode** → removes sidebar/overlay, back to normal browsing

### How it relates to existing features

The current admin already has:
- **Theme editor** (`/admin/theme`): full theme customisation with preset picker, colour/font/layout controls
- **Page editor** (`/admin/pages/:id/edit`): block list with drag-and-drop reorder, block settings panels, live preview

The live site editor doesn't replace these — it re-surfaces the same components in a new context. The admin pages remain as the full-featured editing environment. The live editor is the quick, visual, "I just want to tweak this" experience.

**Shared components:**
- Theme setting controls (colour pickers, font selectors, preset cards)
- Block settings panels (per block type)
- Block list with reorder controls

These need to be extracted into standalone components that work in both contexts (admin page and live editor sidebar).

## Technical approach

### LiveView architecture

The live site editor would be a LiveView that:
1. Renders the actual shop page content (blocks, theme) as the main view
2. Has a sidebar component (LiveComponent or function component) for editing controls
3. Manages edit state (selected block, unsaved changes, edit mode on/off)

**Option A: Wrapper LiveView**
A dedicated LiveView at e.g. `/edit/:path` that wraps the shop page rendering with the editor UI. The shop page content is rendered server-side just like normal, but wrapped in edit-mode markup.

**Option B: Editor overlay on existing shop LiveViews**
Inject the editor UI into the existing shop LiveViews when the user is an admin in edit mode. Cleaner URL story (you're editing at the same URL) but more coupling.

Option A is probably cleaner for a first pass — less risk of breaking the shop experience.

### Inline text editing

`contenteditable` integration with LiveView:

1. Block text content renders inside a `contenteditable` element with `phx-hook="InlineEdit"`
2. The JS hook captures changes (on blur or on a debounce) and sends them back as LiveView events
3. The LiveView updates the block data
4. Need `phx-update="ignore"` on the contenteditable element to prevent LiveView from overwriting mid-edit

This is achievable but needs careful handling of the LiveView ↔ JS boundary.

### CSS custom property injection

Theme changes already work by injecting CSS custom properties into `<style>` tags. The live editor can use the same mechanism:

1. User changes a theme setting in the sidebar
2. LiveView updates the CSS custom property value
3. Browser applies it instantly (no page reload, no re-render needed for most changes)
4. On save, persist to the database

### Responsive sidebar

CSS-based responsive layout:
- `@container` queries or media queries to switch between split view and overlay
- Sidebar as a fixed/absolute positioned element on small screens, part of the grid on large screens
- Transition animations for sidebar open/close

## Open questions

- **URL routing:** `/edit/*` prefix? Or a query param like `?edit=true`? Or detect from session state?
- **Permissions:** just the admin user, or could there be collaborator roles later?
- **Conflict resolution:** what if someone edits in the admin panel while someone else uses the live editor? (Probably fine for single-user MVP, but worth noting.)
- **Block types that aren't text:** image blocks, product grids, etc. — sidebar-only editing, no inline editing for these?
- **Performance:** rendering the full shop page inside a LiveView with extra edit UI — any concerns?

## Task breakdown (rough)

This is a bigger feature. Rough phases:

| Phase | Description | Est | Status |
|---|---|---|---|
| 1 | Design: sketch 2-3 approaches, pick one | 2h | planned |
| 2 | Extract shared components from theme editor and page editor | 4h | planned |
| 3 | Build the editor wrapper LiveView with sidebar shell | 3h | planned |
| 4 | Theme editing in sidebar (re-use theme controls, live CSS vars) | 3h | planned |
| 5 | Block list and block settings in sidebar | 3h | planned |
| 6 | Block selection: click-to-select with highlight on page | 2h | planned |
| 7 | Inline text editing with contenteditable + phx-hook | 4h | planned |
| 8 | Responsive layout (split view ↔ overlay) | 2h | planned |
| 9 | Save/discard/undo flow | 2h | planned |
| 10 | Edit mode toggle (floating button for admins on shop pages) | 1h | planned |
| 11 | Polish and testing | 4h | planned |

Total estimate: ~30h

This should be broken down further when we get to implementation. Each phase is roughly a session.