efficient-easel 0.99.1 → 0.99.2

package/dist/easel/index.d.ts

@@ -0,0 +1,385 @@
+import { E as EaselConfig, a as EaselView, b as EaselAction, P as Permissions, c as EaselCore, d as EaselUi } from '../types-BOSGNvil.js';
+export { A as AppState, e as EaselHistory, f as EditorAction, g as EditorConfig, h as EditorCore, i as EditorHistory, j as EditorUi, k as EditorView, H as HistoryEntry, S as SetDataPatch } from '../types-BOSGNvil.js';
+import { N as NodeSelection } from '../plan-DChbUXdS.js';
+export { I as ItemSelector } from '../plan-DChbUXdS.js';
+import { DataInput } from '../data/index.js';
+import { S as SlotAddress, D as Data, P as Place } from '../types-41704JE4.js';
+import { c as ResolveTrigger, a as ResolveCache, R as ResolvableItem } from '../resolve-D68pb3Bx.js';
+import * as react from 'react';
+import { ReactNode, CSSProperties, ComponentType, ReactElement } from 'react';
+import { b as NodeOpsHost, C as ClipboardEntry } from '../useNodeOps-BF0fQsif.js';
+import { I as InspectorFields } from '../types-C7HFvdtk.js';
+import '../buckets-CuLM47h9.js';
+
+interface EaselOptions<C extends EaselConfig = EaselConfig> {
+    config: C;
+    /** The document — Puck 0.20's shape, unchanged. */
+    data: DataInput | Data;
+    /** The host's own UI keys to start with (and an `itemSelector`, if any). */
+    ui?: Record<string, unknown>;
+    /** Called with the new document after every change that changed it — once
+     *  per `batch`, once per undo / redo. Not called for `load`. */
+    onChange?: (data: Data) => void;
+    /** Easel-wide permissions, under each block's own (Puck's `permissions`). */
+    permissions?: Partial<Permissions>;
+    /**
+     * Changes recorded closer together than this collapse into ONE undo step —
+     * Puck's 250 ms history debounce, so a word typed into a field is undone as
+     * a word and not as letters. A `batch` is never collapsed into its
+     * neighbours. 0 records every change on its own.
+     */
+    historyCoalesceMs?: number;
+    /** The clock, for tests. */
+    now?: () => number;
+}
+interface Easel<C extends EaselConfig = EaselConfig> {
+    /** What `useEasel` reads. The same object until the state changes. */
+    getState: () => EaselView<C>;
+    subscribe: (listener: () => void) => () => void;
+    /** One Puck action. Outside a `batch`, one undo step when it records. */
+    dispatch: (action: EaselAction) => void;
+    /**
+     * Run several changes as ONE: one undo step, one `onChange`, and one
+     * notification to subscribers. Each dispatch inside sees the ones before it.
+     * Throwing inside puts everything back. Batches nest; only the outer one
+     * records.
+     */
+    batch: (fn: () => void) => void;
+    /** Select a node by id, or nothing. Selection is not an undo step. */
+    select: (id: string | null) => void;
+    /** Select a slot — a column — or nothing. */
+    selectSlot: (address: SlotAddress | null) => void;
+    /** Apply a node-ops plan (`{ data, select }`) as one change. */
+    run: (plan: {
+        data: Data;
+        select?: NodeSelection | undefined;
+    }) => void;
+    /**
+     * Put a different document in WITHOUT remounting anything — Puck needed a
+     * new `key` on `<Puck>` for that, which threw away every subscriber's state.
+     * The history starts again at this document unless `keepHistory`.
+     */
+    load: (data: DataInput | Data, options?: {
+        keepHistory?: boolean;
+        selection?: NodeSelection;
+    }) => void;
+    undo: () => void;
+    redo: () => void;
+    setPermissions: (permissions: Partial<Permissions>) => void;
+    /**
+     * Run every block's `resolveData` over the document, as `<Puck>` did when it
+     * mounted (trigger `'load'`), and write what changed as ONE change folded
+     * into the step it happens in — a resolver bringing a stale document up to
+     * date is not an undo step (Puck made it one, which undid back to the stale
+     * document). `onChange` hears it, as Puck's did. `EaselProvider` runs this
+     * on mount; a node changed by hand while it ran is left as the hand left it.
+     */
+    resolveAll: (options?: {
+        trigger?: ResolveTrigger;
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+    /** This easel's memory of the last change each node was resolved for —
+     *  Puck kept one per editor, shared by every write that resolves. */
+    readonly resolveCache: ResolveCache;
+    /**
+     * Swap the config in place — `<Puck>` took a new `config` prop live. The
+     * website editor rebuilds a few blocks' fields when the site's gap moves; the
+     * document, the selection and the history are untouched.
+     */
+    setConfig: (config: C) => void;
+    /** The config in force now. */
+    readonly config: C;
+}
+/**
+ * Puck 0.20's UI at mount (`defaultAppState.ui`), less the selection, which
+ * the store holds by id. A host's chrome reads these — the website editor
+ * opens its side panels from `leftSideBarVisible` / `rightSideBarVisible` — so
+ * a host moving off `<Puck>` finds them where they were.
+ */
+declare const DEFAULT_UI: Record<string, unknown>;
+/**
+ * THE EASEL STORE (blueprint step 5.1): the document, the selection by id and
+ * the host's UI keys, with Puck's actions, Puck's history and a `batch` Puck
+ * never had. Framework-free — `useEasel` (./react) is the React binding.
+ */
+declare function createEasel<C extends EaselConfig>(options: EaselOptions<C>): Easel<C>;
+/** @deprecated The name before the Easel rename: `EaselOptions`. */
+type EditorOptions<C extends EaselConfig = EaselConfig> = EaselOptions<C>;
+/** @deprecated The name before the Easel rename: `Easel`. */
+type Editor<C extends EaselConfig = EaselConfig> = Easel<C>;
+/** @deprecated The name before the Easel rename: `createEasel`. */
+declare const createEditor: typeof createEasel;
+
+/**
+ * Puck 0.20's reducer, on `efficient-easel/data` — blueprint step 5.1.
+ *
+ * Each action means what it meant to Puck, so the apps' `dispatch` calls move
+ * over unchanged (`reorder`'s and `move`'s indexes, `replaceRoot` MERGING
+ * props, `duplicate` selecting the copy, `insert` leaving the selection where
+ * it was). Two things differ, on purpose:
+ *
+ *   - THE SELECTION IS BY ID. Puck held `itemSelector` — a place — so a node
+ *     inserted or removed above the selected one silently moved the selection
+ *     onto its neighbour, and both editors carried patches for exactly that.
+ *     Here `itemSelector` is derived from the id on every read, and a
+ *     selection whose node is gone becomes nothing rather than whatever now
+ *     sits in its place.
+ *   - A SLOT CAN BE SELECTED (a column): `ui.selectedSlot`, which Puck had no
+ *     way to say.
+ */
+/** Whether Puck records an action in history when the action does not say:
+ *  everything but the state-setters. */
+declare function recordsByDefault(action: EaselAction): boolean;
+/** The UI as Puck shows it: the host's keys, with the selection translated. */
+declare function uiView(core: EaselCore, config: EaselConfig): EaselUi;
+/** A selection that still points at something; otherwise nothing. */
+declare function validSelection(data: Data, config: EaselConfig, selection: NodeSelection): NodeSelection;
+/** One action, applied. Pure: the same core and action give the same core. */
+declare function reduce(core: EaselCore, action: EaselAction, config: EaselConfig): EaselCore;
+
+interface EaselProviderProps {
+    easel: Easel;
+    hotkeys?: boolean;
+    /** Run every block's `resolveData` once the easel mounts, as `<Puck>` did
+     *  (`easel.resolveAll`). On by default. */
+    resolveOnMount?: boolean;
+    children?: ReactNode;
+}
+/** Puts one easel in reach of everything under it — `<Puck>`'s provider
+ *  half — and, as `<Puck>` did, binds undo / redo to the page's keyboard
+ *  (`hotkeys={false}` for a host that binds its own) and runs every block's
+ *  `resolveData` once on mount (`resolveOnMount={false}` to skip). */
+declare function EaselProvider({ easel, hotkeys, resolveOnMount, children }: EaselProviderProps): react.JSX.Element;
+/** The easel itself, for handlers that read the state at the moment they run
+ *  (`useGetPuck`'s job) and for `dispatch` / `batch` / `select`. */
+declare function useEaselApi<C extends EaselConfig = EaselConfig>(): Easel<C>;
+/**
+ * Read a slice of the easel and re-render when it changes — `usePuck` /
+ * `createUsePuck()`'s selector form, over the same state shape, so the apps'
+ * selectors move over by renaming the hook.
+ *
+ * A selector may return a fresh object; the snapshot is cached per state and
+ * per selector, so React sees the same value for the same state and does not
+ * loop. A primitive or an unchanged reference does not re-render.
+ */
+declare function useEasel<T, C extends EaselConfig = EaselConfig>(selector: (view: EaselView<C>) => T): T;
+/**
+ * A typed `useEasel` for one config — `createUsePuck<Config>()`'s shape, so
+ * a file that made its own typed hook keeps the one line that made it.
+ */
+declare function createUseEasel<C extends EaselConfig = EaselConfig>(): <T>(selector: (view: EaselView<C>) => T) => T;
+/** @deprecated The name before the Easel rename: `EaselProvider`, whose prop
+ *  is `easel`. This one still takes the store as `editor`. */
+declare function EditorProvider({ editor, ...rest }: Omit<EaselProviderProps, 'easel'> & {
+    editor: Easel;
+}): react.JSX.Element;
+/** @deprecated The name before the Easel rename: `useEaselApi`. */
+declare const useEditorApi: typeof useEaselApi;
+/** @deprecated The name before the Easel rename: `useEasel`. */
+declare const useEditor: typeof useEasel;
+/** @deprecated The name before the Easel rename: `createUseEasel`. */
+declare const createUseEditor: typeof createUseEasel;
+
+/** What a slot component accepts — Puck's. */
+interface CanvasSlotProps {
+    className?: string;
+    style?: CSSProperties;
+    allow?: string[];
+    disallow?: string[];
+    minEmptyHeight?: number;
+    collisionAxis?: unknown;
+}
+interface CanvasFrameProps {
+    children?: ReactNode;
+    /** `preview-frame` by default — the id the apps' canvas watchers look for. */
+    id?: string;
+    /**
+     * The frame's accessible name. Default "Canvas", in the strings provider's
+     * language (`EaselStrings.canvas.frame`).
+     */
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Copy the host page's stylesheets into the frame, and keep them in step.
+     *  On by default: the blocks are styled by the app's own CSS. */
+    mirrorStyles?: boolean;
+    /** Called with the frame's document once it is ready, and null when it goes. */
+    onDocument?: (doc: Document | null) => void;
+    /**
+     * `'auto'` (the default, Puck's): the frame is as tall as its content, and
+     * the host's pane scrolls it — so the canvas reads like the page it is.
+     * `'fill'`: the frame fills its parent and scrolls itself.
+     */
+    height?: 'auto' | 'fill';
+    /**
+     * The page's CSP nonce, for a host whose policy allows styles by nonce
+     * (`style-src 'nonce-…'`). The frame is the host page's own document, so the
+     * same policy applies in it, and a stylesheet without the nonce is refused.
+     * Given, it is set on every stylesheet the canvas puts in the frame: each
+     * `<style>` and `<link rel="stylesheet">` copied in from the host
+     * (`mirrorStyles`), and each sheet `useCanvasStyle` / `upsertCanvasStyle`
+     * (`efficient-easel/canvas`) creates there. Left out, nothing changes.
+     *
+     * Read when the frame is built, like `mirrorStyles`: a nonce is the page's
+     * for as long as the page lives.
+     */
+    nonce?: string;
+}
+/**
+ * An iframe of the easel's own, with the content portalled in. No `src`: the
+ * frame's first document is used — there to write into at once, with no load
+ * to wait for and nothing fetched. The host's stylesheets are copied into its
+ * head and copied again whenever the host's head changes (a route's CSS
+ * arriving late, a dev reload).
+ *
+ * ⚠️ THAT FIRST DOCUMENT HAS NO DOCTYPE, SO IT RENDERS IN QUIRKS MODE, and it
+ * is rewritten with one before anything is drawn. Puck's frame was a
+ * `<!DOCTYPE html>` srcdoc, so every block was written against standards mode;
+ * in quirks mode a `height: 100%` resolves through auto-height ancestors (an
+ * empty slot grew to the frame's full height), tables stop inheriting the
+ * page's font, and an image's line box changes. (0.89.0–0.92.0 shipped the
+ * quirks-mode frame.)
+ */
+declare function CanvasFrame({ children, id, title, className, style, mirrorStyles, onDocument, height, nonce, }: CanvasFrameProps): react.JSX.Element;
+/**
+ * The whole document, for editing. Works in a `CanvasFrame` or on its own.
+ *
+ * `metadata` is the easel-wide metadata: the root's `puck.metadata`, and —
+ * under each block's own — every block's (see the header).
+ */
+declare function EditDocument({ metadata }: {
+    metadata?: Record<string, unknown>;
+}): react.JSX.Element;
+/** What a host may wrap an outline in — Puck's `componentOverlay`: render
+ *  `children` to draw it, or nothing to hide it (a text part open on the
+ *  block, say). */
+type CanvasOverlay = ComponentType<{
+    componentId: string;
+    kind: 'selected' | 'hover';
+    children: ReactNode;
+}>;
+interface EaselCanvasProps {
+    /** Draw in an iframe of the easel's own (default), or straight into the page. */
+    frame?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * The easel-wide metadata — what the published page passes `Render` as
+     * `metadata`. Every block reads it as `puck.metadata` (its own `metadata`
+     * laid over it) and the root as it is. Change it whenever the host's data
+     * changes: the blocks redraw in place, nothing remounts, and it never enters
+     * the document or the undo history.
+     */
+    metadata?: Record<string, unknown>;
+    /** Copy the host's stylesheets into the frame (default true). */
+    mirrorStyles?: boolean;
+    /** The frame's height: as tall as its content (default, Puck's), or filling its parent. */
+    height?: 'auto' | 'fill';
+    /**
+     * The frame's accessible name — an iframe with none is announced as "frame".
+     * Default "Canvas", in the strings provider's language. Unused with
+     * `frame={false}`, where there is no frame to name.
+     */
+    title?: string;
+    /** The page's CSP nonce for the frame's stylesheets — see `CanvasFrameProps.nonce`. Unused with `frame={false}`. */
+    nonce?: string;
+    onDocument?: (doc: Document | null) => void;
+    /**
+     * Wraps everything drawn in the frame, and is handed the frame's document —
+     * Puck's `overrides.iframe`: where a host syncs its theme onto the frame's
+     * `<html>` or adds frame-only CSS.
+     */
+    frameWrapper?: ComponentType<{
+        document?: Document;
+        children: ReactNode;
+    }>;
+    /** Wraps each outline — Puck's `componentOverlay`; see `CanvasOverlay`. */
+    overlay?: CanvasOverlay;
+    /** Drawn inside the frame, after the document — a host's canvas-only layer. */
+    children?: ReactNode;
+}
+/**
+ * `<Puck.Preview>`, ours: the document for editing, its outlines, and the
+ * clicks that select. Must sit under an `EaselProvider`.
+ */
+declare function EaselCanvas({ frame, className, style, metadata, mirrorStyles, onDocument, height, title, nonce, frameWrapper: FrameWrapper, overlay, children, }: EaselCanvasProps): ReactElement;
+/** @deprecated The name before the Easel rename: `EaselCanvasProps`. */
+type EditorCanvasProps = EaselCanvasProps;
+/** @deprecated The name before the Easel rename: `EaselCanvas`. */
+declare const EditorCanvas: typeof EaselCanvas;
+
+/**
+ * THE PARTS, ON THE STORE (blueprint step 5.2).
+ *
+ * Every part built in steps 2.1–4.9 takes a HOST — what to read, how to write
+ * — so it never knew Puck. Until now each app wrote that host twice, once per
+ * editor, against Puck's store: `EmailFields` and `SiteFields` for the settings
+ * panel, the node-ops host for the menus. These are the hosts, written ONCE,
+ * against the engine's store; the parts' own APIs do not change.
+ */
+/** `useNodeOps` with the store as its host: reads the document, and writes one
+ *  `run` — one undo step, the selection travelling with it. */
+declare function useEaselNodeOps(options?: Omit<NodeOpsHost, 'data' | 'config' | 'commit'>): {
+    held: ClipboardEntry | null;
+    remove: (id: string) => boolean;
+    duplicate: (id: string) => boolean;
+    move: (id: string, to: Place) => boolean;
+    step: (id: string, dir: -1 | 1) => boolean;
+    canStep: (id: string, dir: -1 | 1) => boolean;
+    setProps: (id: string, patch: Record<string, unknown>) => boolean;
+    copy: (id: string, label: string) => boolean;
+    cut: (id: string, label: string) => boolean;
+    paste: (at: Place) => boolean;
+    parentOf: (selection: NodeSelection) => NodeSelection;
+};
+interface SelectedFields {
+    /** The selected node's id, or `"root"` with nothing selected. */
+    id: string;
+    /** The node the fields are for — the selected one, or the root as `{ type: 'root', props }`. */
+    node: ResolvableItem;
+    /** Its fields, resolved as Puck resolved them (`resolveFields` with Puck's params, parent included). */
+    fields: InspectorFields;
+    /** What the fields show. */
+    values: Record<string, unknown>;
+    /** The block's (or the root's) `edit` permission is off. */
+    readOnly: boolean;
+    /** Write one field: `resolveData` as Puck ran it, then ONE replace — one undo step. */
+    onChange: (name: string, value: unknown) => void;
+}
+/**
+ * The settings panel's host: the selected node's fields and the write that
+ * changes one — what `EmailFields` and `SiteFields` each did against Puck,
+ * here once:
+ *   - fields resolve through `useResolvedFields` (Puck's
+ *     `useRegisterFieldsSlice`: `changed`, `lastFields`, `appState`, `parent`);
+ *   - a change runs the block's `resolveData` (`resolveNodeData`, Puck's
+ *     `resolveComponentData`, with this easel's own memory of the last
+ *     change) and then writes ONE `replace` of the node, or ONE `replaceRoot`.
+ *
+ * The write reads the node AT THE MOMENT IT RUNS, by id: a field changed while
+ * a resolver is still running writes onto what is current, never onto what was
+ * selected when the change began.
+ */
+declare function useSelectedFields(): SelectedFields;
+/** @deprecated The name before the Easel rename: `useEaselNodeOps`. */
+declare const useEditorNodeOps: typeof useEaselNodeOps;
+
+/**
+ * UNDO AND REDO ON THE KEYBOARD — Puck's own six bindings, which both editors
+ * relied on without writing any: ⌘Z / Ctrl+Z undo; ⇧⌘Z, ⌘Y, Ctrl+Shift+Z and
+ * Ctrl+Y redo.
+ *
+ * Exact combinations, read off the physical key (`code`, as Puck read it), so
+ * a layout that moves Z still undoes and ⌥⌘Z does nothing.
+ *
+ * ⚠️ PUCK FIRED THESE IN A TEXT FIELD TOO, and so does this: ⌘Z while typing
+ * in a setting undoes the easel's last step — which, since a field writes as
+ * it is typed, is the typing — and the browser's own text undo is prevented,
+ * so there are never two undo histories answering one key.
+ *
+ * Bound per DOCUMENT: the host page (`EaselProvider`) and the canvas frame
+ * (`EaselCanvas`), because a key pressed in the frame never reaches the page.
+ */
+declare function bindUndoKeys(doc: Document, easel: Pick<Easel, 'undo' | 'redo'>): () => void;
+
+export { CanvasFrame, type CanvasFrameProps, type CanvasOverlay, type CanvasSlotProps, DEFAULT_UI, type Easel, EaselAction, EaselCanvas, type EaselCanvasProps, EaselConfig, EaselCore, type EaselOptions, EaselProvider, type EaselProviderProps, EaselUi, EaselView, EditDocument, type Editor, EditorCanvas, type EditorCanvasProps, type EditorOptions, EditorProvider, NodeSelection, Permissions, type SelectedFields, bindUndoKeys, createEasel, createEditor, createUseEasel, createUseEditor, recordsByDefault, reduce, uiView, useEasel, useEaselApi, useEaselNodeOps, useEditor, useEditorApi, useEditorNodeOps, useSelectedFields, validSelection };

package/dist/easel/index.js

@@ -0,0 +1 @@
+export{CanvasFrame,DEFAULT_UI,EaselCanvas,EaselProvider,EditDocument,EditorCanvas,EditorProvider,bindUndoKeys,createEasel,createEditor,createUseEasel,createUseEditor,recordsByDefault,reduce,uiView,useEasel,useEaselApi,useEaselNodeOps,useEditor,useEditorApi,useEditorNodeOps,useSelectedFields,validSelection}from"../chunk-F2PIG3AA.js";import"../chunk-D2BCHTQR.js";import"../chunk-AELNNAFM.js";import"../chunk-YRLPFZW3.js";import"../chunk-MFIRYGHW.js";import"../chunk-ZNCEOSXO.js";import"../chunk-KRXQM65X.js";import"../chunk-NKB3KVAB.js";

package/dist/edit-lock/index.d.ts

@@ -177,7 +177,7 @@ declare const documentPermissions: (canEdit: boolean) => DocumentPermissions;
 /**
  * "just now" / "2 minutes ago" — one phrasing, shared by every notice.
  *
- * `words` is the host's language (`useEditorStrings().lock`, 0.95.0); left out,
+ * `words` is the host's language (`useEaselStrings().lock`, 0.95.0); left out,
  * it is the English it always was. The thresholds are not words and do not
  * move: under 45 seconds is "just now", then whole minutes, then whole hours.
  */
@@ -192,7 +192,9 @@ declare const nameOrSomeone: (name: string, words?: LockWords) => string;
  * a reload IS a new editor session, and a remembered id would let a closed tab's
  * claim look alive.
  */
-declare function newEditorClientId(): string;
+declare function newEaselClientId(): string;
+/** @deprecated The name before the Easel rename: `newEaselClientId`. */
+declare const newEditorClientId: typeof newEaselClientId;
 /**
  * The `code` of a document write refused because somebody else TOOK the
  * document from this tab (backend `efficient/editlock.py`,
@@ -351,4 +353,4 @@ type EditLock = {
 /** Bind the decisions to one editor's HTTP client and document type. */
 declare function createEditLock(adapter: EditLockAdapter): EditLock;
 
-export { type ClaimBeatDeps, type DocumentPermissions, EDIT_LOCK_TAKEN, type EditAccess, type EditLock, type EditLockAdapter, type EditLockBody, type EditLockFailure, type HeldWrite, type LockHolder, type LockWords, type SaveConflict, accessForNewDocument, canWriteDocument, createEditLock, describeAge, documentPermissions, documentVersionMoved, holderOf, nameOrSomeone, newEditorClientId, readLockHolder, reloadIfVersionMoved, shouldReleaseHeldWrite, shouldReloadAfterTakeover };
+export { type ClaimBeatDeps, type DocumentPermissions, EDIT_LOCK_TAKEN, type EditAccess, type EditLock, type EditLockAdapter, type EditLockBody, type EditLockFailure, type HeldWrite, type LockHolder, type LockWords, type SaveConflict, accessForNewDocument, canWriteDocument, createEditLock, describeAge, documentPermissions, documentVersionMoved, holderOf, nameOrSomeone, newEaselClientId, newEditorClientId, readLockHolder, reloadIfVersionMoved, shouldReleaseHeldWrite, shouldReloadAfterTakeover };

package/dist/edit-lock/index.js

@@ -1 +1 @@
-export{EDIT_LOCK_TAKEN,accessForNewDocument,canWriteDocument,createEditLock,describeAge,documentPermissions,documentVersionMoved,holderOf,nameOrSomeone,newEditorClientId,readLockHolder,reloadIfVersionMoved,shouldReleaseHeldWrite,shouldReloadAfterTakeover}from"../chunk-TDA4HH54.js";import"../chunk-RE4LP46F.js";
+export{EDIT_LOCK_TAKEN,accessForNewDocument,canWriteDocument,createEditLock,describeAge,documentPermissions,documentVersionMoved,holderOf,nameOrSomeone,newEaselClientId,newEditorClientId,readLockHolder,reloadIfVersionMoved,shouldReleaseHeldWrite,shouldReloadAfterTakeover}from"../chunk-672FAEKU.js";import"../chunk-RE4LP46F.js";