efficient-easel 0.101.1 → 0.103.0

package/dist/screen/lib/screen-parts.js

@@ -0,0 +1 @@
+export{SELECTION_MODE,ScreenPartsProvider,sameInspectorMode,useScreenBlockLook,useScreenBlockRules,useScreenBridges,useScreenCanvasFrame,useScreenDevices,useScreenDocumentPass,useScreenInspectorPanel,useScreenLeftView,useScreenOwnerName,useScreenParts,useScreenPinned,useScreenSaveSwitch,useStandaloneScreenBridges}from"../../chunk-NBJ2YY6Y.js";import"../../chunk-P67FP7PG.js";import"../../chunk-AELNNAFM.js";import"../../chunk-BXZ6WLHC.js";import"../../chunk-EOJNJCMJ.js";import"../../chunk-ZFDCDJNZ.js";import"../../chunk-ZNS7727Y.js";import"../../chunk-3EDSDPIP.js";import"../../chunk-QTLAVDJE.js";import"../../chunk-YRLPFZW3.js";import"../../chunk-KTVH2ZRL.js";import"../../chunk-D2BCHTQR.js";import"../../chunk-EWVJSRRY.js";import"../../chunk-P6O363EE.js";import"../../chunk-FPOKPNO4.js";import"../../chunk-MFIRYGHW.js";import"../../chunk-BZ5ASXOL.js";import"../../chunk-67GNT6PF.js";import"../../chunk-ZNCEOSXO.js";import"../../chunk-L5KW4HG5.js";import"../../chunk-KRXQM65X.js";import"../../chunk-NKB3KVAB.js";

package/dist/screen/lib/section-template-types.d.ts

@@ -0,0 +1,49 @@
+import { TreeItem } from './puck/content-tree.js';
+
+/**
+ * A SAVED SECTION, AND THE STORE THE EDITOR KEEPS THEM IN — the types alone.
+ *
+ * Declared with the website builder (doc/adr/0002): the editor's "Saved
+ * sections" and the backend contract's `sectionTemplates` group
+ * (lib/web-backend) are written against these, and a backend implements them.
+ * EFFICIENT's implementation is `lib/api/section-templates`, which re-exports
+ * them — so there is one declaration, and the builder imports no API client to
+ * name a type.
+ */
+
+interface SectionTemplateRecord {
+    id: string;
+    name: string;
+    component_type: string;
+    node: TreeItem | null;
+    created_at: string;
+    updated_at: string;
+}
+/** A template with a design — what the port hands its callers to render or
+ *  insert. */
+interface SectionTemplate extends SectionTemplateRecord {
+    node: TreeItem;
+}
+interface SectionTemplateStore {
+    /** The designed templates, newest first. A card with no design yet is left
+     *  out: there is nothing to insert. */
+    list(): Promise<SectionTemplate[]>;
+    /** The record at `id`, designed or not; null when there is none. */
+    get(id: string): Promise<SectionTemplateRecord | null>;
+    /**
+     * Get the template at `id` with its design, seeding `name` + the starter
+     * `node` when it has none. The admin generates the id when it adds a card
+     * (which may already exist, with no design yet) or opens a built-in block
+     * (`section-block-<type>`, which may not exist at all), and the shop seeds the
+     * design the first time the standalone editor opens it (create-on-first-open).
+     */
+    ensure(id: string, name: string, node: TreeItem): Promise<SectionTemplate>;
+    /** Create a template from a section node; returns the stored record. */
+    save(name: string, node: TreeItem): Promise<SectionTemplate>;
+    /** Persist an edited section node (the standalone editor's autosave path). */
+    update(id: string, node: TreeItem): Promise<SectionTemplate>;
+    rename(id: string, name: string): Promise<SectionTemplateRecord>;
+    remove(id: string): Promise<void>;
+}
+
+export type { SectionTemplate, SectionTemplateRecord, SectionTemplateStore };

package/dist/screen/lib/section-templates.d.ts

@@ -0,0 +1,23 @@
+import { SectionTemplateStore } from './section-template-types.js';
+import './puck/content-tree.js';
+
+/**
+ * The section templates of the editor on this page — whichever store its
+ * backend offers (`WebsiteBackend.sectionTemplates`).
+ *
+ * Under the EFFICIENT backend that is the store it always was
+ * (lib/api/section-templates, `/api/storefront/section-templates/`). Under an
+ * embedder's own backend it is the embedder's — and when that backend has none,
+ * it is an EMPTY store: nothing to list, so the Add panel draws no "Your
+ * templates" group, and nothing to open, so the standalone section editor says
+ * it could not open the section. No caller asks "is there a store?"; an empty
+ * one answers every question they have.
+ *
+ * Read per call, never captured: the editor is remounted for another website
+ * with another backend, and a store kept from the first mount would write one
+ * website's sections into the other's.
+ */
+
+declare const sectionTemplates: SectionTemplateStore;
+
+export { sectionTemplates };

package/dist/screen/lib/section-templates.js

@@ -0,0 +1 @@
+export{sectionTemplates}from"../../chunk-4MXFKJUY.js";import"../../chunk-KDYIMJTZ.js";import"../../chunk-AJBJ74ME.js";

package/dist/screen/lib/session-context.d.ts

@@ -0,0 +1,30 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { EaselSession } from './session.js';
+import '../../blocks/index.js';
+import '../../types-E3HrTPg2.js';
+import '../../data/index.js';
+import '../../types-41704JE4.js';
+import '../../resolve-D68pb3Bx.js';
+import '../../plan-DChbUXdS.js';
+import './host-chrome.js';
+import './links/link-filters.js';
+import '../../LinkPicker-W2Rtxetz.js';
+import './document-contract.js';
+import './document-hooks.js';
+import './section-template-types.js';
+import './puck/content-tree.js';
+
+/**
+ * Hand `session` to the editor below, and make it the page's current one for
+ * as long as this is mounted (see `activateEaselSession` for why it happens in
+ * render AND in an effect).
+ */
+declare function EaselSessionProvider({ session, children }: {
+    session: EaselSession;
+    children: ReactNode;
+}): react.JSX.Element;
+/** The session of the editor this component renders in. */
+declare function useEaselSession(): EaselSession;
+
+export { EaselSessionProvider, useEaselSession };

package/dist/screen/lib/session-context.js

@@ -0,0 +1 @@
+export{EaselSessionProvider,useEaselSession}from"../../chunk-6TZTKAB5.js";import"../../chunk-AJBJ74ME.js";

package/dist/screen/lib/session.d.ts

@@ -0,0 +1,255 @@
+import { Config } from '../../blocks/index.js';
+import { EaselChrome } from './host-chrome.js';
+import { WebsiteEditLock } from './document-contract.js';
+import { EaselDocumentHooks } from './document-hooks.js';
+import { SectionTemplateStore } from './section-template-types.js';
+import 'react';
+import '../../types-E3HrTPg2.js';
+import '../../data/index.js';
+import '../../types-41704JE4.js';
+import '../../resolve-D68pb3Bx.js';
+import '../../plan-DChbUXdS.js';
+import './links/link-filters.js';
+import '../../LinkPicker-W2Rtxetz.js';
+import './puck/content-tree.js';
+
+/**
+ * The editor SESSION — everything one mounted editor knows that no prop reaches:
+ * the backend it talks to, the console's sign-in, the website being edited, and
+ * the caches that belong to this editor and no other.
+ *
+ * Until efficient-web 0.4.0 each of those was a module singleton of its own
+ * (lib/editor-auth, lib/editor-site, lib/editor-site-slug, …), written by one
+ * part of the editor and read by another with nothing saying they belonged
+ * together. That holds while one editor is mounted for the life of the page. It
+ * stops holding the moment an embedder REMOUNTS the editor for a different
+ * website: the previous website's token, site id and cached answers were all
+ * still there, and nothing was the one place to clear them.
+ *
+ * So there is one object per mounted editor. The embedder's `EditorFrame`
+ * (packages/website/src/index.tsx) creates it when the editor mounts and lets it
+ * go when the editor unmounts; a new mount starts from an empty one.
+ *
+ * ONE EDITOR AT A TIME IS STILL THE RULE. Puck custom fields and the loaders
+ * they call render where no React context reaches, so they read the session of
+ * "the editor on this page" — {@link currentEaselSession}. Code that DOES sit
+ * under the editor's React tree reads its own session through
+ * `useEaselSession()` (lib/session-context), which is what keeps an
+ * editor's last writes — the autosave's flush on unmount, the lock's release —
+ * on its own backend and token while the next editor is already mounting.
+ *
+ * WHERE NO EDITOR IS MOUNTED — the shop's own pages, a dev harness, a guard —
+ * there is the AMBIENT session: the EFFICIENT client, no token until somebody
+ * sets one. That is exactly what the old singletons were.
+ *
+ * LEAF DISCIPLINE: no React, no HTTP client, no other module of this repo at
+ * runtime. lib/api reads the site id from here (through lib/editor-site), and
+ * the published site imports lib/api on the server.
+ */
+
+/**
+ * THE BACKEND, AS THE SESSION HOLDS IT: what the editor's own machinery reads
+ * of it, and nothing more. The rest is the layer's, read by the layer under
+ * its own type — the website's is `WebsiteBackend` (lib/web-backend), and it
+ * reads its sessions' backend as one through lib/website-session.
+ *
+ * The session is the screen's and moves into efficient-easel with it
+ * (doc/adr/0004), where a second editor hands it a backend of its own; so it
+ * names no website's backend. It keeps the object it was handed and hands that
+ * same object back, so a layer's backend loses nothing by passing through.
+ */
+interface SessionBackend {
+    /** Present when the documents it stores carry an advisory edit lock: the
+     *  document's provider asks, of a page it is about to open, whether it has
+     *  one to claim. */
+    lock?: WebsiteEditLock;
+    /** Where the editor's saved sections are kept (lib/section-templates).
+     *  Without it there are none to list and none to open. */
+    sectionTemplates?: SectionTemplateStore;
+}
+/**
+ * The mark `createEfficientBackend` puts on what it returns, so a session can
+ * tell the EFFICIENT client from an embedder's own backend without importing it
+ * (lib/efficient-backend imports lib/api, which imports this module's readers).
+ * `Symbol.for`, so two copies of this module in one page agree; enumerable on
+ * the object, so `{ ...createEfficientBackend(), pages }` keeps it.
+ */
+declare const EFFICIENT_BACKEND: unique symbol;
+/** Whether `backend` is (or is spread from) the EFFICIENT client. */
+declare function isEfficientBackend(backend: SessionBackend | null | undefined): boolean;
+/**
+ * A host's choice of blocks, as the session carries it: the shape of the
+ * website's `EditorBlocks` (lib/editor-blocks, where the module comment says
+ * what each member does) with its set names as plain strings, so the screen's
+ * session names none of a layer's block sets (doc/adr/0004). The website's
+ * type is assignable to it; the website layer reads the sets back in its own
+ * terms (lib/editor-blocks `offeredSets`).
+ */
+interface SessionBlocks {
+    readonly sets?: readonly string[];
+    readonly allow?: readonly string[];
+    readonly deny?: readonly string[];
+    readonly host?: Readonly<Record<string, unknown>>;
+    readonly categories?: readonly {
+        key: string;
+        title: string;
+        components: string[];
+        before?: string;
+    }[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface EaselSession {
+    /**
+     * The backend the EMBEDDER supplied, or null when it supplied none — the
+     * host's default then (EFFICIENT's client, `provideDefaultBackend`). Read the
+     * backend in force through `backendOf(session)`, never from here.
+     */
+    readonly hostBackend: SessionBackend | null;
+    /**
+     * Whether the backend is authorised by the console's bridged token (the
+     * `storefront-editor:auth` message). True for the EFFICIENT client; false for
+     * an embedder's own backend, which authorises its calls itself — the editor
+     * then waits for no token and may call it from its first render.
+     */
+    readonly usesBridgedToken: boolean;
+    /**
+     * Which blocks the EMBEDDER chose to offer, and its own (lib/editor-blocks),
+     * or null when it chose nothing — every block then, as before the option
+     * existed. Read once, with the backend. `metadata` is the one member that is
+     * NOT read from here: it is followed live (lib/editor-block-metadata).
+     */
+    readonly blocks: SessionBlocks | null;
+    /**
+     * The block registry this editor works from — the page root, the palette's
+     * groups and every block (lib/puck/registry). Whoever mounts the editor hands
+     * it over: the storefront's is `lib/puck/config`, with its commerce and
+     * service blocks registered among the general ones. The editor imports no
+     * registry of its own, so it never imports a block it does not own
+     * (doc/adr/0002). Read once, with the backend — through
+     * {@link sessionRegistry}, which refuses an editor that was handed none.
+     */
+    readonly registry: Config | null;
+    /**
+     * What the host stands round the editor — its own providers, primers and
+     * panels, handed over as components (lib/host-chrome, doc/adr/0004) — or
+     * null when it brings none. Read once, with the backend.
+     */
+    readonly chrome: EaselChrome | null;
+    /**
+     * What the host does to a document as it opens and as an edit is stored
+     * (lib/document-hooks) — the storefront seeds and feeds its catalogue
+     * blocks — or null when it does nothing. Read once, with the backend.
+     */
+    readonly documentHooks: EaselDocumentHooks | null;
+    /** The console's sign-in: the admin JWT and the legacy brand scope. */
+    readonly auth: {
+        token: string | null;
+        brandId: string | null;
+    };
+    /** The website being edited — see lib/editor-site for why there are two. */
+    readonly site: {
+        documentId: string | null;
+        bridgedId: string | null;
+    };
+    /** `site.documentId ?? site.bridgedId`: the website a call is scoped to. */
+    siteId(): string | null;
+    /**
+     * One value per key for the life of this editor — a list fetched once, a
+     * lookup in flight. Dropped with the session, so the next editor (another
+     * website, another person) never reads this one's answers.
+     */
+    cache<T>(key: string, make: () => T): T;
+    /** Forget one cached value, or all of them. */
+    forget(key?: string): void;
+}
+/** What makes the backend of a session whose embedder supplied none. */
+type DefaultBackend = (session: EaselSession) => SessionBackend;
+/**
+ * Name the backend an editor talks to when its embedder passes none. Called
+ * ONCE, by the host's own backend module as it loads: EFFICIENT's is
+ * `lib/efficient-backend`, which the storefront's registry imports.
+ *
+ * A registration rather than an import, because the direction matters: the
+ * editor is the builder's and a host's client is the host's (doc/adr/0002).
+ * It is one default for the app, not a choice per editor — an embedder that
+ * wants another backend for one editor passes `backend`, as before.
+ */
+declare function provideDefaultBackend(make: DefaultBackend): void;
+/**
+ * The backend one editor session talks to: the embedder's own when it supplied
+ * one, else the host's default — one client per session, built the first time
+ * it is asked for and bound to THAT session's token and website.
+ *
+ * Throws when there is neither: an editor with no backend can load and save
+ * nothing, and falling back to "no pages" would look like an empty website.
+ *
+ * Typed as the session holds it ({@link SessionBackend}); the website's code
+ * reads the same object as its own through lib/website-session `backendOf`.
+ */
+declare function backendOf(session?: EaselSession): SessionBackend;
+/**
+ * The registry an editor's session was created with. Throws on a session that
+ * was handed none: an editor with no registry has no blocks and no page root,
+ * and one that quietly fell back to SOME registry would draw a host's pages
+ * with holes where its own blocks belong.
+ */
+declare function sessionRegistry(session: EaselSession): Config;
+declare function createEaselSession(options?: {
+    backend?: SessionBackend | null;
+    blocks?: SessionBlocks | null;
+    registry?: Config | null;
+    chrome?: EaselChrome | null;
+    documentHooks?: EaselDocumentHooks | null;
+}): EaselSession;
+/** Record the website a session's open document belongs to. */
+declare function setSessionDocumentSite(session: EaselSession, siteId: string | null | undefined): void;
+/** Record the website the host bridged in with an auth grant. */
+declare function setSessionBridgedSite(session: EaselSession, siteId: string | null | undefined): void;
+/** The session of the editor mounted on this page — the ambient one when none is. */
+declare function currentEaselSession(): EaselSession;
+/**
+ * Make `session` the page's current one. IDEMPOTENT, and called from two places
+ * on purpose: while the editor RENDERS (so a child's effect — which runs before
+ * its parent's — already reads the right session) and from the editor's own
+ * effect (which is what survives React StrictMode's mount, unmount, mount).
+ */
+declare function activateEaselSession(session: EaselSession): void;
+/**
+ * The editor that owned `session` unmounted.
+ *
+ * Deferred by a microtask rather than done at once: StrictMode unmounts and
+ * re-mounts every effect in one synchronous pass, children first, so clearing
+ * the session in the cleanup would leave the children's re-run effects reading
+ * the ambient session — the EFFICIENT client — in an editor that was given its
+ * own backend. A session that was activated again in the meantime, or that a
+ * newer editor has already replaced, is left alone.
+ *
+ * The session OBJECT is not emptied: the unmounting editor's own last calls (a
+ * final autosave, the lock's release) hold it by reference and still need its
+ * backend and token. It is simply no longer the page's current one, and is
+ * collected with the closures that hold it.
+ */
+declare function deactivateEaselSession(session: EaselSession): void;
+/**
+ * Whether this repo's own HTTP client has a server to talk to on this page.
+ *
+ * It always has — except while the mounted editor runs over an EMBEDDER'S OWN
+ * backend (doc/adr/0002). The sections and settings that still call the
+ * EFFICIENT API by themselves (the catalog a product grid lists, the cart's
+ * bundles, a link picker's blog posts) would then be asking a server that is
+ * not there: the embedder's origin, which serves none of those routes and
+ * whose users hold no EFFICIENT session. So the client is CLOSED for that
+ * editor — `apiFetch` and the two shop-origin fetchers refuse before they touch
+ * the network, exactly as they fail when the server is unreachable, and every
+ * caller degrades the way it already does for an outage.
+ *
+ * This is what makes "the package itself makes no request" true by construction
+ * under an embedder's backend, rather than true of the call sites somebody
+ * remembered to gate. On the published site, the shop's own pages and under the
+ * EFFICIENT backend it is always open.
+ */
+declare function efficientClientOpen(): boolean;
+/** Start the ambient session again from nothing (tests; a guard between cases). */
+declare function resetAmbientEaselSession(): void;
+
+export { EFFICIENT_BACKEND, type EaselSession, type SessionBackend, type SessionBlocks, activateEaselSession, backendOf, createEaselSession, currentEaselSession, deactivateEaselSession, efficientClientOpen, isEfficientBackend, provideDefaultBackend, resetAmbientEaselSession, sessionRegistry, setSessionBridgedSite, setSessionDocumentSite };

package/dist/screen/lib/session.js

@@ -0,0 +1 @@
+export{EFFICIENT_BACKEND,activateEaselSession,backendOf,createEaselSession,currentEaselSession,deactivateEaselSession,efficientClientOpen,isEfficientBackend,provideDefaultBackend,resetAmbientEaselSession,sessionRegistry,setSessionBridgedSite,setSessionDocumentSite}from"../../chunk-AJBJ74ME.js";