efficient-web-builder 0.0.0 → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,541 @@
+/**
+ * The public types of `efficient-web-builder` (published as dist/index.d.ts).
+ *
+ * Written out rather than generated: the entry reaches ~700 shop modules and a
+ * declaration bundle of them would publish the shop's internals as API. Kept
+ * honest by `types.check.ts` beside it, which the shop's own `tsc` compiles —
+ * each type here must be mutually assignable with the one the code defines.
+ */
+import type { ComponentType, ReactElement } from "react";
+// The engine's own block type: a host's blocks are written exactly as the
+// editor's are. `efficient-easel` is a peer of this package.
+import type { ComponentConfig } from "efficient-easel/blocks";
+
+/** What the page editor is pointed at: a website page (site + slug) or a page
+ *  of a website template. */
+export type EditorTarget =
+  | { kind: "page"; slug: string; siteId?: string; originSlug?: string }
+  | { kind: "template"; id: string; pageSlug?: string };
+
+/** The standalone one-section editor's target (a section template). */
+export type SectionEditorTarget = { kind: "section"; id: string; type?: string; name?: string };
+
+/** A media item the host's picker returns. */
+export interface HostPickedMedia {
+  id: string;
+  url: string;
+  kind: "image" | "video";
+}
+
+/** What a field asked the media panel for. `file` is a file dropped straight on
+ *  the field: the host uploads it and picks it without waiting for a click. */
+export interface MediaPickRequest {
+  requestId: string;
+  /** `image/*`, `video/*` or `image/svg+xml` — what the field can hold. */
+  accept: string;
+  /** The field's label, e.g. "Background image". */
+  title: string;
+  file?: File | null;
+}
+
+/** The props the host's media panel is drawn with. */
+export interface MediaPanelProps {
+  /** The field choosing right now, or null while the merchant is browsing. */
+  pick: MediaPickRequest | null;
+  /** Answer the field. Ignored while browsing. */
+  onPick: (media: HostPickedMedia) => void;
+}
+
+/** The host's media library, as a component the editor draws in its left
+ *  panel (the rail's Media view, and every image field's pick mode). */
+export type MediaPanelComponent = ComponentType<MediaPanelProps>;
+
+/** Every message the editor sends its host. */
+export type EditorToHostMessage =
+  | { type: "storefront-editor:ready" }
+  | { type: "storefront-editor:auth-expired" }
+  | { type: "storefront-editor:dirty" }
+  | { type: "storefront-editor:saved" }
+  | { type: "storefront-editor:published" }
+  | { type: "storefront-editor:save-failed" }
+  | { type: "storefront-editor:navigated"; target: EditorTarget }
+  | {
+      type: "storefront-editor:open-media-picker";
+      requestId: string;
+      accept: string;
+      title: string;
+      file?: File;
+    }
+  /** `mode: "create"` asks for a new form and carries a `requestId` to answer
+   *  with `form-saved` / `form-closed`. `mode: "edit"` opens the form builder on
+   *  `formId` and carries none: nothing waits on it. */
+  | { type: "storefront-editor:open-form"; requestId?: string; mode: "create" | "edit"; formId?: string }
+  | { type: "storefront-editor:open-category"; categoryId: string; name?: string }
+  | { type: "storefront-editor:open-product"; slug: string; name?: string }
+  | { type: "storefront-editor:open-post"; slug: string; title?: string }
+  | { type: "storefront-editor:open-menus"; menuId?: string | null }
+  | { type: "storefront-editor:open-page"; slug: string }
+  | { type: "storefront-editor:new-page" }
+  | { type: "storefront-editor:save-as-template"; siteId: string; slug: string };
+
+/** Every message a host sends the editor. */
+export type HostToEditorMessage =
+  | {
+      type: "storefront-editor:auth";
+      token: string;
+      siteId?: string;
+      brandId?: string;
+      theme?: string;
+      can?: { canCreatePlatformTemplate?: boolean };
+    }
+  | { type: "storefront-editor:navigate"; target: EditorTarget | SectionEditorTarget }
+  | { type: "storefront-editor:category-updated"; categoryId?: string }
+  | { type: "storefront-editor:menus-updated" }
+  | { type: "storefront-editor:form-saved"; requestId?: string; form?: { id: string; slug: string } }
+  | { type: "storefront-editor:form-closed"; requestId?: string }
+  | { type: "storefront-editor:media-picked"; requestId: string; media: HostPickedMedia }
+  | { type: "storefront-editor:media-pick-cancelled"; requestId: string };
+
+export type EditorMessageType = EditorToHostMessage["type"];
+type PayloadOf<T extends EditorMessageType> = Omit<Extract<EditorToHostMessage, { type: T }>, "type">;
+
+export type SendToHost = <T extends EditorMessageType>(
+  type: T,
+  ...payload: Record<string, never> extends PayloadOf<T> ? [PayloadOf<T>?] : [PayloadOf<T>]
+) => void;
+
+export type InboundHostMessage = { type: string } & Record<string, unknown>;
+
+/** The editor's address — for an embedder, retargets of its own window. */
+export interface EditorHostAddress {
+  /** The query the editor was opened with. An embedder that opens templates to
+   *  edit their layout answers `"?editTemplate=1"`. */
+  search(): string;
+  /** Keep the embedder's notion of "where" in step (no load). */
+  show(target: EditorTarget | SectionEditorTarget): void;
+  /** Leave for another document by LOADING it — re-mount the editor there. */
+  load(target: EditorTarget): void;
+  /** Reload the editor from scratch — re-mount it on the same target. */
+  reload(): void;
+}
+
+export interface EditorHost {
+  readonly connected: boolean;
+  readonly ownsDocument: boolean;
+  send: SendToHost;
+  subscribe(listener: (message: InboundHostMessage) => void): () => void;
+  readonly address: EditorHostAddress;
+}
+
+/** A host for an editor mounted in the embedder's own page. One per editor. */
+export function createEditorHost(options: {
+  onMessage: (message: EditorToHostMessage) => void;
+  address: EditorHostAddress;
+}): { host: EditorHost; deliver: (message: HostToEditorMessage) => void };
+
+// ── The backend (0.4.0) ──────────────────────────────────────────────────────
+//
+// Everything the editor asks a server for, as one contract an embedder may
+// implement. Leave `backend` out of the editor's props and it is EFFICIENT's
+// (`createEfficientBackend`), authorised by the token the host delivers with
+// `storefront-editor:auth` — exactly as before 0.4.0. Supply one and the editor
+// waits for no token, draws no control the backend has no group for, and makes
+// no request of its own.
+//
+//   • `pages`, `site.get` and `media.resolve` are required; every other group
+//     and method is optional, and ABSENCE IS THE ANSWER — never implement a
+//     method to say "not supported".
+//   • A failed call rejects with `WebsiteBackendError`; the editor reads its
+//     `kind`, never a status code or a response body.
+//   • No credential crosses the interface: how a call is authorised is the
+//     backend's own business.
+
+/** The page document the editor edits: the engine's `Data` (`content`, `root`,
+ *  `zones`), stored and returned exactly as it was saved. Opaque to a backend. */
+export type PageLayout = Record<string, unknown>;
+
+/** One row of the editor's page list. Rows arrive in display order. */
+export type EditorPageRow = {
+  id: string;
+  slug: string;
+  /** What the list calls the page. */
+  label: string;
+  /** Header text of the row's group (null / absent = top level). */
+  group?: string | null;
+  /** Stable key of that group — two groups may share a header text. */
+  groupKey?: string;
+  /** Not published yet (drives the "draft" tag). False where pages never publish. */
+  draft: boolean;
+  /** Page kind, where the backend has kinds (`dynamic`, `lightbox`, …). */
+  kind?: string | null;
+};
+
+/**
+ * A page's content, as it is stored and saved.
+ *
+ * `translations` and `seo` are RESERVED for per-language content: a backend
+ * that stores a page as this bundle from the start does not migrate its storage
+ * when the multilingual overlay ships. 0.4.0 edits `layout` only — it sends
+ * neither of the other two on a save, and a backend treats an absent member as
+ * "leave what is stored".
+ */
+export type PageBundle = {
+  layout: PageLayout;
+  /** Per-language overrides of the layout's text, keyed by language tag. */
+  translations?: Record<string, unknown>;
+  /** Per-language title and description, keyed by language tag. */
+  seo?: Record<string, { title?: string; description?: string }>;
+};
+
+/** A page as the editor opens it. */
+export type PageDocument = PageBundle & {
+  id: string;
+  /**
+   * The VERSION of the stored document this copy is based on — what the next
+   * save says it replaces. Any string the backend can compare for equality; the
+   * editor passes it back untouched. `null` means the backend keeps no versions
+   * for this document: every save is accepted and nothing is ever refused as
+   * `changed-elsewhere`.
+   */
+  version: string | null;
+  /** Page kind, where the backend has kinds. */
+  kind?: string | null;
+};
+
+/** The website a call is about, when the editor's target names one
+ *  (`EditorTarget.siteId`). A backend that serves one website ignores it. */
+export type SiteScope = { siteId?: string };
+
+/** A page by its slug or its id. */
+export type PageRef = ({ slug: string } | { id: string }) & SiteScope;
+
+/** What the page list's inline "Add page" hands the backend. */
+export type NewPageInput = { slug: string; title: string; layout: PageLayout } & SiteScope;
+
+/** What a save says it expects, and who is writing. */
+export type SaveExpectation = {
+  /** The version being replaced (`PageDocument.version`, then each save's own). */
+  version: string | null;
+  /** This editor tab — the id its lock claim sends. */
+  clientId: string;
+};
+
+/** A set of pages: a website's, or one template's. */
+export interface WebsitePages {
+  /** The rows the page list navigates between. */
+  list(scope?: SiteScope): Promise<EditorPageRow[]>;
+  /** The page, or null when there is none. */
+  load(ref: PageRef): Promise<PageDocument | null>;
+  /**
+   * Store the page's working copy and answer with the version it now has.
+   * Reject `changed-elsewhere` when `expect.version` is no longer the stored
+   * one, and `lock-taken` when somebody took the page from `expect.clientId`.
+   */
+  save(id: string, doc: PageBundle, expect: SaveExpectation): Promise<{ version: string | null }>;
+  /** The stored version alone, without the layout. Lets the editor re-base a
+   *  save its own other tab refused, and reload after a take-over only when the
+   *  page really moved. */
+  version?(id: string): Promise<string | null>;
+  /** Make the stored working copy the public one. Without it the editor's main
+   *  button reads "Save" and nothing is ever a draft. */
+  publish?(id: string, expect?: { version: string }): Promise<{ version: string | null }>;
+  /** Add a page from the page list. Without it the editor asks its HOST for a
+   *  new page (`storefront-editor:new-page`). */
+  create?(input: NewPageInput): Promise<EditorPageRow>;
+  /** Delete a page from the page list. */
+  remove?(id: string): Promise<void>;
+}
+
+/** The other operator, as the editor's notices describe them. */
+export type LockHolder = {
+  name: string;
+  /** Seconds since their last heartbeat, as the SERVER measured it. */
+  secondsSinceSeen: number;
+  /** Seconds since they TOOK the page, as the SERVER measured it. */
+  secondsSinceHeld: number;
+};
+
+/** A refused save: the stored page moved on since this editor loaded it. */
+export type SaveConflict = {
+  /** Who saved. Empty when the backend cannot attribute the write. */
+  savedBy: string;
+  /** True when it was this same person, in another tab. */
+  savedByYou: boolean;
+  secondsAgo: number;
+};
+
+/** The advisory "somebody is editing this page" lock. */
+export interface WebsiteEditLock {
+  /**
+   * Claim the page, refresh the claim (the heartbeat) or — `takeover` — take it
+   * from whoever holds it. Resolves once this tab holds the page; rejects
+   * `lock-taken` (with `holder`) while somebody else does.
+   */
+  claim(id: string, clientId: string, takeover: boolean): Promise<{ heartbeatSeconds: number }>;
+  /** Hand the page back. Best-effort: a lock expires by itself. */
+  release(id: string, clientId: string): Promise<void>;
+}
+
+/** What the editor reads of the website itself. */
+export interface SiteRecord {
+  /** The website's display name. */
+  name: string;
+  /** Its public slug, where it has one. */
+  slug?: string | null;
+  /** The site-wide Google Maps browser key the canvas's map blocks draw with. */
+  mapsApiKey?: string | null;
+  /** The site-wide Google Maps cloud style. */
+  mapsMapId?: string | null;
+}
+
+/** The part of the site record the editor writes. */
+export type SiteRecordPatch = { mapsApiKey?: string };
+
+export interface WebsiteSite {
+  get(scope?: SiteScope): Promise<SiteRecord>;
+  /** Save the site-wide Maps key. Without it that field is read-only. */
+  update?(patch: SiteRecordPatch, scope?: SiteScope): Promise<SiteRecord>;
+  /** RESERVED for the multilingual overlay: the languages the website is
+   *  written in. 0.4.0 does not call it. */
+  languages?(): Promise<{ base: string; others: string[] }>;
+}
+
+export interface WebsiteMedia {
+  /**
+   * Turn a stored media reference into a URL the browser can load, or answer
+   * null to leave the reference as it is. Synchronous — it runs while a section
+   * renders. `width` is the size a thumbnail is drawn at, when the caller has one.
+   */
+  resolve(ref: string, options?: { width?: number }): string | null;
+  /** RESERVED: upload a file dropped on a media field. 0.4.0 hands a dropped
+   *  file to the host's media panel or picker and does not call it. */
+  upload?(file: File): Promise<HostPickedMedia>;
+}
+
+/** One node of a page document: a section or a block, with its own props. */
+export type SectionNode = { type: string; props: { id: string; [key: string]: unknown } };
+
+/** A stored section template. `node` is null for a card nobody has designed. */
+export interface SectionTemplateRecord {
+  id: string;
+  name: string;
+  component_type: string;
+  node: SectionNode | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** A section template with a design. */
+export interface SectionTemplate extends SectionTemplateRecord {
+  node: SectionNode;
+}
+
+/** Reusable single sections, edited on their own and dropped into any page. */
+export interface WebsiteSectionTemplates {
+  /** The designed templates, newest first. */
+  list(): Promise<SectionTemplate[]>;
+  /** The record at `id`, designed or not; null when there is none. */
+  get(id: string): Promise<SectionTemplateRecord | null>;
+  /** The template at `id` with its design, seeding `name` + `node` when it has none. */
+  ensure(id: string, name: string, node: SectionNode): Promise<SectionTemplate>;
+  save(name: string, node: SectionNode): Promise<SectionTemplate>;
+  update(id: string, node: SectionNode): Promise<SectionTemplate>;
+  rename(id: string, name: string): Promise<SectionTemplateRecord>;
+  remove(id: string): Promise<void>;
+}
+
+/** Website templates: blueprints whose pages the same editor edits. */
+export interface WebsiteTemplates {
+  /** The template's name (the canvas header's wordmark while it is edited). */
+  get(id: string): Promise<{ id: string; name: string }>;
+  /** The template's pages. They never publish and carry no lock. */
+  pages(templateId: string): WebsitePages;
+}
+
+/** Where the top bar's Preview link goes. */
+export interface WebsitePreview {
+  /** The public address of the page with this slug. */
+  href(slug: string): string;
+}
+
+/**
+ * Everything the editor asks a server for.
+ *
+ * Other groups the editor still reads from the EFFICIENT client directly — the
+ * site's theme, header, social links and live chat, menus, blog, forms and the
+ * catalog — join this interface as optional members when their call sites move.
+ * Until then a backend other than EFFICIENT's gets the page editor without them.
+ */
+export interface WebsiteBackend {
+  pages: WebsitePages;
+  lock?: WebsiteEditLock;
+  site: WebsiteSite;
+  media: WebsiteMedia;
+  sectionTemplates?: WebsiteSectionTemplates;
+  templates?: WebsiteTemplates;
+  preview?: WebsitePreview;
+}
+
+/** Why a backend call failed, in the editor's own terms. */
+export type WebsiteBackendErrorKind =
+  /** The session is not (or no longer) authorised. The editor tells its host
+   *  (`storefront-editor:auth-expired`) and treats the call as failed. */
+  | "unauthorized"
+  /** A save was refused: the stored page moved on since this copy was loaded.
+   *  Carries `conflict`. */
+  | "changed-elsewhere"
+  /** Somebody else holds the page (a claim), or took it from this tab (a save).
+   *  Carries `holder`. */
+  | "lock-taken"
+  /** There is no such page, site or template. */
+  | "not-found"
+  /** The backend understood the request and refused it as wrong. */
+  | "invalid"
+  /** No answer: offline, timed out, the backend itself failing. */
+  | "unavailable";
+
+/**
+ * The one error a backend rejects with. `message` is shown to the operator
+ * where the editor has nowhere better to read from (a document that would not
+ * load), so write it for a person.
+ */
+export class WebsiteBackendError extends Error {
+  readonly kind: WebsiteBackendErrorKind;
+  /** `changed-elsewhere`: who saved, and whether it was this person's own tab. */
+  readonly conflict?: SaveConflict;
+  /** `lock-taken`: who holds the page. */
+  readonly holder?: LockHolder;
+  constructor(
+    kind: WebsiteBackendErrorKind,
+    message?: string,
+    detail?: { conflict?: SaveConflict; holder?: LockHolder; cause?: unknown },
+  );
+}
+
+export interface EfficientBackendOptions {
+  /** Pin every site-scoped call to one website. Without it the client follows
+   *  the editor's open document, as the built-in default does. */
+  siteId?: string;
+}
+
+/**
+ * The EFFICIENT backend, for an embedder that wants to pass it explicitly — to
+ * hand over one group of its own: `{ ...createEfficientBackend(), preview }`.
+ * Leaving `backend` out of the editor's props is the same thing.
+ */
+export function createEfficientBackend(options?: EfficientBackendOptions): WebsiteBackend;
+
+/** The website the editor is showing. */
+export interface WebsiteEditorSite {
+  /** `StorefrontSite.slug` — named on every public read. */
+  slug: string;
+  /** The website's public origin, no trailing slash. */
+  origin: string;
+}
+
+// ── Which blocks the editor offers (0.7.0) ───────────────────────────────────
+//
+// Leave `blocks` out of the editor's props and it offers every block it has —
+// exactly as before 0.7.0. Supply it to choose which SETS are offered, to allow
+// or deny single blocks, and to add blocks of your own.
+//
+//   • OFFERED, NOT REGISTERED. A block you leave out is in no group of the Add
+//     panel, no slot's menu and no drop target. A page that already holds one
+//     still draws it, and it can be selected and deleted.
+//   • NOT A SECURITY BOUNDARY. Check a saved page on your server with
+//     `blockTypesIn` from `efficient-web-builder/contract`.
+//   • `sets`, `allow`, `deny`, `host` and `categories` are read once, when the
+//     editor mounts — re-mount (a `key`) to change them. `metadata` is live.
+
+/**
+ * The set a block travels in.
+ *
+ *   general   draws from its own props and what the host hands it; any host
+ *             may offer it
+ *   commerce  the shop: products, the catalogue, the cart, the checkout
+ *   service   needs one of the EFFICIENT backend's site services (forms,
+ *             bookings, reviews, the newsletter, the blog, menus)
+ */
+export type WebsiteBlockSet = "general" | "commerce" | "service";
+
+/** A group of the Add panel a host places its blocks in. */
+export interface WebsiteBlockCategory {
+  /** The group's key. An existing group's key (`content`, `structure`, …) adds
+   *  the blocks to the end of that group; a new key makes a new group. */
+  key: string;
+  /** A new group's heading. Not read for an existing group. */
+  title: string;
+  /** The types in the group, in order. */
+  components: string[];
+  /** Put a NEW group before the group with this key. Without it — or when no
+   *  such group is offered — the group is added last. */
+  before?: string;
+}
+
+/** The host's choice of blocks. Every member is optional. */
+export interface WebsiteEditorBlocks {
+  /** The sets offered. Default: all three. */
+  sets?: readonly WebsiteBlockSet[];
+  /** After `sets`: only these block types. A section that is built from other
+   *  blocks (a Hero from its slides) is offered only when those are too. */
+  allow?: readonly string[];
+  /** After both: never these. */
+  deny?: readonly string[];
+  /**
+   * The host's own blocks, by type, each written as the engine's
+   * `ComponentConfig`. A type the editor already registers is refused (the
+   * editor throws when it mounts): name yours so they cannot collide.
+   *
+   * A host's block is a SECTION: it is added to the page from the Add panel, in
+   * the group `categories` names, and it is given what the editor's own
+   * sections are given — the Padding, Corners, Width, Height, Anchor, Theme and
+   * Motion rows, the settings tabs (its own fields under Content),
+   * click-to-edit text and the Layers tree's eye. So untouched it is on the
+   * site's first theme, as any section is; and a field of its own under a name
+   * the editor adds a row with (`anchor`, `widthMode`, `sectionAccent`,
+   * `sectionPaddingTop`, …) is refused when the editor mounts. It is not
+   * offered inside a Box.
+   */
+  host?: Record<string, ComponentConfig>;
+  /** Where the host's blocks stand in the Add panel. A block named in no group
+   *  is registered and drawn, and offered nowhere. */
+  categories?: WebsiteBlockCategory[];
+  /**
+   * The host's live data. Every block in the canvas receives it as
+   * `puck.metadata`. Change the object and the blocks redraw in place; it is
+   * never written to the page or to the undo history.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/** The page / website-template editor. Re-mount (a `key`) to change website. */
+export function WebsiteEditor(props: {
+  host: EditorHost;
+  target: EditorTarget;
+  site: WebsiteEditorSite | null;
+  /** The host's media library, drawn in the editor's left panel. Without one,
+   *  fields ask the host to open its picker window (`open-media-picker`). */
+  mediaPanel?: MediaPanelComponent | null;
+  /** The server the editor talks to. Without one it is EFFICIENT's
+   *  (`createEfficientBackend`). Read once, when the editor mounts. */
+  backend?: WebsiteBackend | null;
+  /** Which blocks the editor offers, and the host's own. Without one: every
+   *  block, as before 0.7.0. */
+  blocks?: WebsiteEditorBlocks | null;
+}): ReactElement;
+
+/** The standalone one-section editor (a section template). */
+export function WebsiteSectionEditor(props: {
+  host: EditorHost;
+  id: string;
+  initialType?: string;
+  initialName?: string;
+  site: WebsiteEditorSite | null;
+  /** The host's media library — see `WebsiteEditor`. */
+  mediaPanel?: MediaPanelComponent | null;
+  /** The server the editor talks to — see `WebsiteEditor`. Needs
+   *  `sectionTemplates`. */
+  backend?: WebsiteBackend | null;
+  /** Which blocks the editor offers — see `WebsiteEditor`. */
+  blocks?: WebsiteEditorBlocks | null;
+}): ReactElement;