@marktiderman/genesis-sites 0.2.0 → 0.3.0

package/dist/editor.d.ts

@@ -0,0 +1,526 @@
+import * as React from 'react';
+import { P as PageKind, a as PageDoc, b as PageMeta, R as Release, F as FormsResolver, c as RenderContext, d as ResolvedForm, S as SectionCategory, A as AnySectionDefinition, e as Seo, f as SectionNode, g as SiteDoc } from './registry-HBn1X60x.js';
+import { A as Asset, a as AssetMeta, S as SiteStore, B as BrandInput, b as SiteIssue, P as PublishOptions, R as ReservedPaths, c as SaveResult } from './store-BXiZeZzH.js';
+import { Config, Fields, Overrides } from '@puckeditor/core';
+export { Config as PuckConfig, Data as PuckData, Overrides as PuckOverrides, createUsePuck, usePuck } from '@puckeditor/core';
+import 'zod';
+import '@marktiderman/genesis-design-system';
+
+/** The host's asset library, beside the store's `putAsset` uploads. */
+interface EditorAssets {
+    /** The images and files a site already has (shown in the picker's Library). */
+    list?: (siteId: string) => Promise<Asset[]>;
+    /** Upload, instead of the store's `putAsset` (for a host that stores files elsewhere). */
+    upload?: (siteId: string, file: File, meta: AssetMeta) => Promise<Asset>;
+    /** The largest upload, in bytes. Default 10 MB. */
+    maxBytes?: number;
+}
+interface PickedImage {
+    src: string;
+    alt: string;
+    decorative?: boolean;
+    width?: number;
+    height?: number;
+}
+
+/**
+ * What the editor's panels do to a site, as plain functions over a
+ * `SiteStore`: check and publish, add, move, delete and reorder pages, and
+ * the page templates. No React, so each is tested against the memory store.
+ */
+
+/** A store the editor can drive. `reorderPages` is optional: without it, page order is the store's. */
+type EditorSiteStore = SiteStore & {
+    reorderPages?(siteId: string, pageIds: string[]): Promise<void>;
+};
+interface SiteCheck {
+    issues: SiteIssue[];
+    /** No errors: the site can be published. */
+    publishable: boolean;
+}
+/**
+ * Run the publish checks on the drafts as they are now (accessibility,
+ * contrast, placeholders, paths), without publishing: what the Publish
+ * panel lists, errors first.
+ *
+ * @stability Beta
+ */
+declare function checkSite(store: SiteStore, siteId: string, options?: Pick<PublishOptions, "brand" | "reserved">): Promise<SiteCheck>;
+/** Publish after checking: a site with errors is refused before the store is asked. */
+declare function publishSite(store: SiteStore, siteId: string, options: {
+    brand: BrandInput;
+    note?: string;
+    reserved?: ReservedPaths;
+}): Promise<{
+    release: Release;
+} | {
+    blocked: SiteIssue[];
+}>;
+/** Why a path can't be a page's here (empty when it can): the pattern, reserved paths, and pages already there. */
+declare function pathProblems(path: string, pages: readonly Pick<PageMeta, "id" | "path">[], options?: {
+    reserved?: ReservedPaths;
+    except?: string;
+}): string[];
+/** A page's title as a path segment: "Our classes" → "/our-classes". */
+declare function slugify(title: string): string;
+/**
+ * Move a page to a new address. The store writes a 301 from the old path
+ * (and rewrites older redirects, so there are no chains). Refuses the home
+ * page, reserved paths and a path another page has, before asking the store.
+ */
+declare function renamePage(store: SiteStore, pageId: string, path: string, options?: {
+    reserved?: ReservedPaths;
+}): Promise<PageMeta>;
+/** A page a person can start from. */
+interface PageTemplate {
+    id: string;
+    label: string;
+    description: string;
+    kind: PageKind;
+    doc(input: {
+        title: string;
+        brand: BrandInput;
+    }): PageDoc;
+}
+/**
+ * The templates the Add page dialog offers: a blank page, the one-click
+ * landing page from the brand, and each page of the starter site (about,
+ * contact) after its home page.
+ *
+ * @stability Beta
+ */
+declare function pageTemplates(): PageTemplate[];
+/** Move one page up or down the list (through `reorderPages`, when the store has it). */
+declare function movePageInList(store: EditorSiteStore, siteId: string, pageId: string, by: -1 | 1): Promise<PageMeta[]>;
+
+/**
+ * `<SiteEditor>`: the visual editor for a genesis-sites site.
+ *
+ *   <SiteEditor siteId="riverside" store={store} brand={brand} />
+ *
+ * Puck runs the canvas, drag and drop, the fields and the history; every
+ * panel around it is Genesis UI. The canvas is an iframe drawn by each
+ * section's own renderer with the site's stylesheet and the brand's theme;
+ * "Preview" runs the real `/web` request handler. Drafts autosave by
+ * compare-and-swap; publishing runs the checks first, and holds the canvas
+ * and the autosaves while it runs. `readOnly` opens a site to look at only.
+ */
+
+interface SiteEditorProps {
+    siteId: string;
+    /** Any `SiteStore`: the Supabase one signed in as the editor, or the memory store. */
+    store: EditorSiteStore;
+    /** The site's brand: the canvas theme, and what a publish checks contrast against. */
+    brand: BrandInput;
+    /** Resolves form embeds' slugs, for the canvas and preview. */
+    forms?: FormsResolver;
+    /** The asset library and upload, beside the store's `putAsset`. */
+    assets?: EditorAssets;
+    /** After each publish. */
+    onPublish?: (release: Release) => void;
+    /**
+     * Whether anything isn't saved yet (waiting, saving, a conflict, a failed save, or a change that
+     * can't be saved until it's fixed). Block your app's own navigation while it's true: closing the
+     * tab is already guarded, and unmounting the editor saves what it can but can't ask.
+     */
+    onDirtyChange?: (dirty: boolean) => void;
+    /** Paths the site can't use (default: the store's own rule). */
+    reserved?: ReservedPaths;
+    /** A link to the host's preview route for a page path (opens in a new tab). */
+    previewUrl?: (path: string) => string;
+    /** Milliseconds after the last change before a save (default 800). */
+    autosaveDelay?: number;
+    /** The page to open first (default: the home page). */
+    initialPageId?: string;
+    /**
+     * The URL of the package's site stylesheet (`@marktiderman/genesis-sites/sites.css`, for example
+     * Vite's `?url` import, or `/_gs/sites.<hash>.css` where `handleSiteRequest` is mounted). Without it
+     * the canvas loads the stylesheet from the renderer's bundled assets, a larger download.
+     */
+    siteStylesheet?: string;
+    /**
+     * View only: the canvas, fields and SEO can't be changed, there is no Add, no
+     * page actions, no Publish and no Roll back, and nothing is ever saved. For
+     * someone who may see the drafts but not edit them.
+     */
+    readOnly?: boolean;
+    className?: string;
+}
+/**
+ * The visual editor.
+ *
+ * @stability Beta
+ */
+declare function SiteEditor({ siteId, store, brand, forms, assets, onPublish, reserved, previewUrl, autosaveDelay, initialPageId, siteStylesheet, readOnly, onDirtyChange, className }: SiteEditorProps): React.JSX.Element;
+
+/** What the Add picker and its limits know about one Puck component. */
+interface ComponentInfo {
+    type: string;
+    /** The preset's name (the Add picker's label). */
+    label: string;
+    /** The section's own label. */
+    sectionLabel: string;
+    category: SectionCategory;
+    placement: "header" | "body" | "footer";
+    limit?: number;
+}
+/** What every section on the canvas is told about the page (Puck metadata). */
+interface CanvasMetadata {
+    site: RenderContext["site"];
+    pagePath: string;
+    /** Plain objects, not Maps: Puck copies its metadata. */
+    forms: Readonly<Record<string, ResolvedForm | null>>;
+    /** The section that gets the page's h1. */
+    h1Id: string | null;
+    /** Template placeholders' original props, by section id. */
+    placeholders: Readonly<Record<string, string>>;
+}
+interface EditorConfigOptions {
+    /** The page kind: sections not `enabledOn` it are left out of the picker. */
+    kind?: PageKind;
+    /** Sections to offer (default: every registered section). */
+    sections?: readonly AnySectionDefinition[];
+    /** How many of each type the page holds now; read when Puck asks whether one more may be added. */
+    counts?: () => ReadonlyMap<string, number>;
+    /**
+     * Whether the page can't be changed now (a view-only editor, or a publish
+     * running). Read with `counts`: a component's own `insert` overrides the
+     * global permissions Puck is given, so it has to say no itself.
+     */
+    readOnly?: () => boolean;
+}
+interface EditorConfig {
+    config: Config;
+    /** Puck component name → what it is. */
+    components: ReadonlyMap<string, ComponentInfo>;
+    /** The props of a section type that hold nested sections. */
+    slotKeys: (type: string) => readonly string[];
+}
+/**
+ * The Puck config for one page kind, from the registry.
+ *
+ * @stability Beta
+ */
+declare function createEditorConfig(options?: EditorConfigOptions): EditorConfig;
+
+/**
+ * Editor fields from a section's JSON Schema (`sectionJsonSchema`, the zod
+ * schema's input side), so a new section gets its fields with no editor
+ * change:
+ *
+ * - `x-genesis-kind: "image"` (or any object with `src` and `alt`) → the
+ *   image picker, which asks for alt text;
+ * - `x-genesis-kind: "rich-text"` → the Genesis rich text editor;
+ * - `x-genesis-kind: "slot"` → a Puck slot (nested sections);
+ * - an enum, or a union of constants → a select;
+ * - a boolean → a yes/no radio; a number → a number input;
+ * - a string → text, or a textarea when it may run past 160 characters;
+ * - an object → its fields (a record keyed by an enum, such as
+ *   `z.partialRecord(Day, …)`, gets one optional field per key); an array of
+ *   objects → a list of them; an array of strings → one per line.
+ *
+ * Anything else gets a field that says it can't be edited here, and a
+ * warning in the console, so a gap is visible rather than silent.
+ */
+
+/** `primaryCta` → "Primary CTA"; `hideOn` → "Hide on". */
+declare function humanize(key: string): string;
+interface SectionFields {
+    fields: Fields;
+    /** Props that hold nested sections (Puck slots). */
+    slotKeys: string[];
+    /** Props no field could be made for (shown as "can't be edited here"). */
+    unsupported: string[];
+}
+/**
+ * Every field of a section: its layout (variant) first, then its props from
+ * the JSON Schema, then where it shows.
+ *
+ * @stability Beta
+ */
+declare function sectionFields(def: AnySectionDefinition, options?: {
+    slotAllow?: string[];
+}): SectionFields;
+
+/**
+ * Between Genesis documents and Puck's data.
+ *
+ * A Genesis section node is `{ id, type, v, variant, hidden, hideOn,
+ * placeholder, props }`; a Puck item is `{ type, props: { id, ...props } }`.
+ * The node's own fields travel in the Puck props under `_` keys (`_variant`,
+ * `_hidden`, `_hideOn`, `_v`, `_placeholder`) that no section schema may use,
+ * and come back out on save. A page's header and footer (site parts) are
+ * slots on Puck's root, so the canvas shows and edits the whole page.
+ *
+ * The editor's Add picker offers each section's presets: a preset after the
+ * first is its own Puck component, `type__n`, and turns back into `type` on
+ * save, so stored documents only ever name registered types.
+ */
+
+/** Puck's item shape, as far as the editor needs it. */
+interface PuckItem {
+    type: string;
+    props: Record<string, unknown> & {
+        id: string;
+    };
+}
+/** Puck's page data as the editor builds it. */
+interface EditorData {
+    root: {
+        props: EditorRootProps;
+    };
+    content: PuckItem[];
+}
+interface EditorRootProps {
+    title: string;
+    hideSiteChrome?: boolean;
+    seo?: Seo;
+    /** The site header's sections (slot). */
+    header: PuckItem[];
+    /** The site footer's sections (slot). */
+    footer: PuckItem[];
+    [key: string]: unknown;
+}
+/** Keys a section schema may not use: they carry the node's own fields. */
+declare const NODE_KEYS: readonly ["_variant", "_hidden", "_hideOn", "_v", "_placeholder"];
+/** The Puck component name of a section's preset: `hero` for the first, `hero__1` for the second (`_` never appears in a section type, and Puck builds ids from the name, so it must be id-safe). */
+declare const presetComponentName: (type: string, index: number) => string;
+/** The section type a Puck component name stands for. */
+declare const sectionTypeOf: (componentName: string) => string;
+type Lookup = (type: string) => AnySectionDefinition | undefined;
+type SlotKeys = (type: string) => readonly string[];
+/** A node as a Puck item. Unknown types keep their props, so nothing is lost. */
+declare function nodeToItem(node: SectionNode, slotKeys?: SlotKeys): PuckItem;
+/**
+ * Empty optional values out: `""`, and objects left with nothing in them
+ * (an optional button whose fields were cleared). A required field that
+ * empties is then reported by the section's schema, never saved as `""`.
+ * Strings inside arrays stay as they are (an empty one is the schema's to
+ * report, not ours to drop).
+ */
+declare function pruneEmpty(value: unknown): unknown;
+/**
+ * A section id the schema accepts (1–64 letters, digits, `-`, `_`). Puck makes
+ * ids for dragged-in and duplicated sections from the component name and a
+ * UUID; the same id always maps to the same safe one, so saves stay stable.
+ */
+declare function safeSectionId(id: string): string;
+interface FromItemOptions {
+    lookup?: Lookup;
+    slotKeys?: SlotKeys;
+    /**
+     * A hash of the props each template placeholder had when the editor
+     * opened it (`placeholderSnapshot`), by section id. A placeholder stays one only while its props are unchanged:
+     * editing it clears the flag.
+     */
+    placeholders?: ReadonlyMap<string, string>;
+}
+/** A Puck item as a node. */
+declare function itemToNode(item: PuckItem, options?: FromItemOptions): SectionNode;
+/** A hash of every placeholder node's props, to tell later whether it was edited. */
+declare function placeholderSnapshot(nodes: readonly SectionNode[], into?: Map<string, string>): Map<string, string>;
+/** A page (and its site's header and footer) as the editor's Puck data. */
+declare function toEditorData(page: PageDoc, site: Pick<SiteDoc, "header" | "footer">, slotKeys?: SlotKeys): EditorData;
+interface FromEditorResult {
+    page: PageDoc;
+    header: SectionNode[];
+    footer: SectionNode[];
+}
+/** The editor's Puck data back as a page and the site's header and footer. */
+declare function fromEditorData(data: {
+    root?: {
+        props?: Record<string, unknown>;
+    };
+    content?: unknown[];
+}, options?: FromItemOptions): FromEditorResult;
+/** The id of the section that gets the page's `h1`: the first visible one that provides it. */
+declare function h1SectionId(content: readonly PuckItem[], lookup?: Lookup): string | null;
+/** How many sections of each type the page holds, in every zone (for the Add picker's limits). */
+declare function countTypes(data: Pick<EditorData, "content"> & {
+    root?: {
+        props?: Partial<EditorRootProps>;
+    };
+}): Map<string, number>;
+
+/**
+ * Autosave with compare-and-swap: a document is saved a moment after the
+ * last change, naming the revision it started from. When someone else saved
+ * first the store answers with their document, and the autosaver stops and
+ * waits: the person chooses to load theirs (`reload`) or keep their own
+ * (`overwrite`). Nothing is dropped on the way:
+ *
+ * - a change made while a save is in flight is saved right after it, on the
+ *   new revision;
+ * - during a conflict, edits keep collecting and are what `overwrite` saves;
+ * - a failed save (offline, a server error) keeps the change and retries
+ *   with backoff, and on the next change;
+ * - `flush()` saves now and resolves once nothing is waiting (page switch,
+ *   publish), or rejects when it can't;
+ * - `pause()` holds every save (while a publish runs) and `resume()` saves
+ *   what collected meanwhile, after `rebase` has adopted the new revision.
+ *
+ * Pure TypeScript with injectable timers, so it is tested without a DOM.
+ */
+
+type AutosaveStatus = "saved" | "pending" | "saving" | "conflict" | "error";
+interface AutosaveState<T> {
+    status: AutosaveStatus;
+    /** The revision the next save names. */
+    rev: number;
+    /** When status is `conflict`: the store's document and revision. */
+    conflict: {
+        doc: T;
+        rev: number;
+    } | null;
+    error: Error | null;
+    /** When the last save landed. */
+    savedAt: Date | null;
+}
+interface AutosaverOptions<T> {
+    rev: number;
+    save: (rev: number, doc: T) => Promise<SaveResult<T>>;
+    /** Wait this long after the last change (default 800 ms). */
+    delay?: number;
+    /** Retry a failed save after this long, doubling up to a minute (default 2 s). */
+    retryDelay?: number;
+    onState?: (state: AutosaveState<T>) => void;
+    /** Two documents are the same save (default: the same content, in any key order). */
+    equals?: (a: T, b: T) => boolean;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    now?: () => Date;
+}
+/** Thrown by `flush` when the document can't be saved yet (a conflict, or a failed save). */
+declare class AutosaveBlockedError extends Error {
+    readonly status: AutosaveStatus;
+    constructor(status: AutosaveStatus, message: string);
+}
+/**
+ * One document's autosave.
+ *
+ * @stability Beta
+ */
+declare class Autosaver<T> {
+    private state;
+    /** The newest document not yet saved, or null. */
+    private pending;
+    /** The last document the store accepted (or loaded). */
+    private saved;
+    private timer;
+    private inFlight;
+    private retries;
+    private waiters;
+    private disposed;
+    private paused;
+    private readonly opts;
+    constructor(options: AutosaverOptions<T>, initial?: T);
+    get current(): AutosaveState<T>;
+    /** Is anything not yet in the store (pending, saving, a conflict or a failed save)? */
+    get dirty(): boolean;
+    /** The document as the person has it: unsaved changes, or the last save. */
+    get latest(): T | null;
+    private set;
+    /** A change: saved after the delay, unless another change comes first. */
+    update(doc: T): void;
+    private schedule;
+    private run;
+    private settle;
+    /** Save now; resolves when nothing is waiting, rejects on a conflict or a failed save. */
+    flush(): Promise<void>;
+    /** Conflict: take the store's document. Returns it; unsaved changes are discarded. */
+    reload(): T | null;
+    /** Conflict: save this person's document over the store's. */
+    overwrite(): Promise<void>;
+    /**
+     * The store moved on without a conflict (a page move bumped its revision,
+     * a publish migrated it): adopt its revision. `doc` replaces the saved
+     * copy when given; unsaved changes are kept and saved on the new revision.
+     */
+    rebase(rev: number, doc?: T): void;
+    /** Is saving held (`pause`)? */
+    get isPaused(): boolean;
+    /**
+     * Hold every save, for as long as the store must not change under the
+     * caller (a publish). A save already in flight lands; changes keep
+     * collecting and are saved on `resume`.
+     */
+    pause(): void;
+    /** Save again: what collected while paused is saved now, on the current revision. */
+    resume(): void;
+    dispose(): void;
+}
+
+/**
+ * The editor's view of the real output: the `/web` request handler, run in
+ * the browser, renders a page of the drafts (`preview`) or of the live
+ * release (`live`) exactly as a visitor gets it. Its stylesheet is inlined
+ * so the HTML works as an iframe's `srcdoc`, and its script is left out:
+ * the frame is sandboxed with no script and no same-origin access, so
+ * nothing an editor typed can run with the editor's privileges.
+ *
+ * The renderer and its assets load on demand (a separate chunk), so opening
+ * the editor doesn't download them until a preview or the canvas needs them.
+ */
+
+interface PreviewInput {
+    store: Pick<SiteStore, "getLive" | "getDraft" | "listPages" | "getPageDraft">;
+    siteId: string;
+    brand: BrandInput;
+    path: string;
+    mode: "preview" | "live";
+    forms?: FormsResolver;
+}
+interface PreviewResult {
+    status: number;
+    /** The page as a self-contained document, or null when the address redirects or isn't the site's. */
+    html: string | null;
+    /** Where a redirect goes. */
+    location?: string;
+}
+/**
+ * One page through `handleSiteRequest`, as an iframe-ready document.
+ *
+ * @stability Beta
+ */
+declare function renderPreview(input: PreviewInput): Promise<PreviewResult>;
+
+/**
+ * The image picker: upload (through the store's `putAsset`, or the host's
+ * own upload), choose from the site's library, or link an https image.
+ * Every choice needs alt text, or to be marked decorative, before it can be
+ * used: the publish check would refuse it anyway, so the picker asks first.
+ */
+
+/** Raster images only: the database refuses SVG (it can carry script). */
+declare const IMAGE_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/avif", "image/gif"];
+interface AssetPickerProps {
+    open: boolean;
+    siteId: string;
+    store: Pick<SiteStore, "putAsset">;
+    assets?: EditorAssets | undefined;
+    current?: PickedImage | undefined;
+    /** The field takes only the address; its alt text is a field of its own (a gallery photo). */
+    altElsewhere?: boolean | undefined;
+    onDone: (image: PickedImage | null) => void;
+}
+/** Why an upload can't be used (or null). */
+declare function uploadProblem(file: {
+    type: string;
+    size: number;
+} | null, maxBytes?: number): string | null;
+declare function AssetPicker({ open, siteId, store, assets, current, altElsewhere, onDone }: AssetPickerProps): React.JSX.Element;
+
+/**
+ * Puck's chrome, drawn with Genesis UI: every field type, field labels, and
+ * the Add picker's items (which also enforce each section's limit). So the
+ * editor reads as part of the host app, not as stock Puck, and every
+ * control has a real label.
+ */
+
+interface GenesisOverrideOptions {
+    /** Say what an action did (a section added, moved or removed), for a live region. */
+    announce?: (message: string) => void;
+}
+declare function genesisOverrides(info: ReadonlyMap<string, ComponentInfo>, extra?: Partial<Overrides>, options?: GenesisOverrideOptions): Partial<Overrides>;
+
+export { AssetPicker, type AssetPickerProps, AutosaveBlockedError, type AutosaveState, type AutosaveStatus, Autosaver, type AutosaverOptions, type CanvasMetadata, type ComponentInfo, type EditorAssets, type EditorConfig, type EditorConfigOptions, type EditorData, type EditorRootProps, type EditorSiteStore, type FromEditorResult, IMAGE_TYPES, NODE_KEYS, type PageTemplate, type PickedImage, type PreviewInput, type PreviewResult, type PuckItem, type SectionFields, type SiteCheck, SiteEditor, type SiteEditorProps, checkSite, countTypes, createEditorConfig, fromEditorData, genesisOverrides, h1SectionId, humanize, itemToNode, movePageInList, nodeToItem, pageTemplates, pathProblems, placeholderSnapshot, presetComponentName, pruneEmpty, publishSite, renamePage, renderPreview, safeSectionId, sectionFields, sectionTypeOf, slugify, toEditorData, uploadProblem };