@marktiderman/genesis-sites 0.2.0 → 0.3.1

package/README.md

@@ -15,12 +15,11 @@ hydration, and published as immutable releases you can roll back.
 - **Import** (`/import`, Node): `importAssets`, which re-hosts an old site's
   images and PDFs behind a guard against server-side request forgery, and
   `rewriteUrls`.
+- **Editor** (`/editor`): `<SiteEditor>`, the visual editor (on Puck).
 - **Block** (`/blocks`): `sitesBlock`, so `genesis add sites` installs the
   migration.
 
-Status: beta. The visual editor (Puck) is next; the editor-facing APIs
-(`sectionManifests`, `sectionJsonSchema`, labels, categories, variants and
-presets) are in place for it. The design and its reasoning are in
+Status: beta. The design and its reasoning are in
 [docs/SITES.md](../../docs/SITES.md).
 
 ## Install
@@ -32,8 +31,9 @@ pnpm add @marktiderman/genesis-sites zod@^4
 
 Peers: `react` and `react-dom` 19, `zod` 4, `@marktiderman/genesis-ui`,
 `@marktiderman/genesis-design-system`, `@marktiderman/genesis-forms` and
-`-forms-web` (the form embed), `lucide-react`, and `@supabase/supabase-js` for
-the Supabase store.
+`-forms-web` (the form embed), `lucide-react`, `@supabase/supabase-js` for
+the Supabase store, and `@puckeditor/core` 0.23 for the editor. The last two
+are optional: install them only if you use the Supabase store or `/editor`.
 
 Then:
 
@@ -445,6 +445,90 @@ A public bucket serves any file to whoever has its URL, so give uploads random
 names (`putAsset` does) and never put anything there that isn't meant for the
 published site.
 
+## The editor
+
+```bash
+pnpm add @puckeditor/core@^0.23   # only where the editor runs
+```
+
+```tsx
+import { SiteEditor } from "@marktiderman/genesis-sites/editor";
+
+<div style={{ height: "100dvh" }}>
+  <SiteEditor siteId={siteId} store={store} brand={brand} forms={forms} onPublish={(release) => purge(release)} />
+</div>;
+```
+
+`SiteEditor` fills its parent, so give the parent a height. Props:
+
+| Prop | |
+|---|---|
+| `siteId`, `store` | Any `SiteStore`: the Supabase store signed in as the editor, or the memory store. |
+| `brand` | The site's brand: the canvas theme, and what publishing checks contrast against. |
+| `forms?` | Your `FormsResolver`, so form embeds draw on the canvas and in preview. |
+| `assets?` | `{ list?, upload?, maxBytes? }`: the image library, and an upload of your own instead of the store's `putAsset`. |
+| `onPublish?` | Called with each new release. |
+| `onDirtyChange?` | Called with whether anything isn't saved yet. Block your app's own navigation while it's true; closing the tab is guarded already. |
+| `siteStylesheet?` | The site stylesheet's URL (`@marktiderman/genesis-sites/sites.css`, say through Vite's `?url`). Without it the canvas loads the renderer's bundled assets, a much larger download. |
+| `reserved?` | Paths pages can't use (default: the store's rule, `DEFAULT_RESERVED_PATHS`). |
+| `previewUrl?` | A link to your own preview route for a page path, shown in the Publish panel. |
+| `readOnly?` | View only: the canvas, fields and SEO can't be changed; there is no Add picker, no page actions, no Publish and no Roll back; no autosaver is made, so nothing is saved. A "View only" note says so. |
+| `autosaveDelay?`, `initialPageId?`, `className?` | |
+
+What it does:
+
+- **Generated from the registry.** Each section becomes one Add-picker entry
+  per preset, grouped by category, with fields made from its JSON Schema:
+  text and textareas, a select for its layout (variants) and for enums, the
+  image picker for images, the Genesis rich text editor, objects (links),
+  lists, one-per-line string lists, and Puck slots for props marked
+  `x-genesis-kind: "slot"`. A section at its `limit` can't be added again. A
+  prop the editor can't map shows as "can't be edited here" and warns in the
+  console; it is kept as it is. Register a section and it appears; nothing in
+  the editor changes.
+- **The canvas** is an iframe drawn by each section's own renderer, with the
+  site stylesheet and your brand's theme, and the site's header and footer
+  as editable slots above and below the page. **Preview** runs the real
+  `/web` handler on the drafts (and **View it live** on the live release)
+  in a sandboxed frame with no scripts.
+- **Autosave** saves a moment after each change by compare-and-swap. If
+  someone else saved first, it stops, keeps your edits, and asks: load their
+  version, or keep yours. Closing the tab with unsaved changes asks first;
+  for a route change in your app, use `onDirtyChange` to ask. When the editor
+  unmounts with changes still waiting it saves them on the way out, but it
+  can't wait for that save, so a host that must not lose them asks first.
+  Undo and redo are Puck's history (the toolbar, or Ctrl+Z and Ctrl+Shift+Z).
+- **Pages**: open, add (blank, the landing page from your brand, or a starter
+  site page), change an address (the old one redirects with a 301; reserved
+  paths are refused), delete, and edit the header menu. Reordering pages
+  needs a store with `reorderPages(siteId, pageIds)`; without it the list is
+  in the store's order.
+- **Publish**: the publish checks run on the saved drafts and errors block
+  the button. While a publish runs the canvas is read-only and autosave
+  waits, so no edit races the store's own re-saves; afterwards the editor
+  takes the new revisions and saves anything that waited; "Show" selects the section a check is about. Publish with a
+  note, see the release history, and roll back. Per-page SEO (search title,
+  description, share image, noindex) is in the same panel.
+- **Images** come from an upload, the library, or a link; every one needs alt
+  text unless it is marked decorative. SVG isn't accepted.
+- **Accessible**: every field has a label; nothing needs dragging (each
+  Add-picker entry has an Add button, and the selected section's Up, Down
+  and Remove buttons sit above its fields); actions are announced; and the
+  panels are Genesis UI tabs and dialogs. Puck's canvas and outline still
+  move sections only by dragging.
+
+Puck is an optional peer dependency (`@puckeditor/core`): an app that only
+serves sites never installs it, and the root, `/web` and `/sections` never
+import it. It stays inside `/editor`: import everything from here (it re-exports `usePuck`, `createUsePuck` and the
+`PuckConfig`, `PuckData` and `PuckOverrides` types for extensions), and
+never from `@puckeditor/core`. `/web` never imports the editor, so published
+pages carry no Puck code. The lower-level pieces are exported too:
+`createEditorConfig`, `sectionFields`, `toEditorData` and `fromEditorData`,
+`Autosaver`, and `checkSite`, `publishSite`, `renamePage` and
+`pageTemplates`.
+
+The sample app's `/sites-editor` route is a working demo on the memory store.
+
 ## Stores
 
 `createSupabaseSiteStore(client)` uses the `genesis_sites` functions: pass a