efficient-easel 0.0.0 → 0.97.0

package/dist/data/index.d.ts

@@ -0,0 +1,375 @@
+import { D as Data, a as DataConfig, N as Node, S as SlotAddress, F as Found, P as Place, b as SlotEntry, W as WalkInfo } from '../types-41704JE4.js';
+export { B as BlockShape, c as FieldShape, d as FieldsShape, e as NodeProps, R as RootData } from '../types-41704JE4.js';
+export { R as ResolvableItem, a as ResolveCache, b as ResolveOptions, c as ResolveTrigger, d as changedProps, e as createResolveCache, f as deepEqual, r as resolveNodeData } from '../resolve-D68pb3Bx.js';
+
+/**
+ * Finding a node's slots, and reading or writing a value at a prop path.
+ *
+ * A slot is found the way Puck finds one: by the FIELDS, not by the value. A
+ * prop is a slot when its field says `type: 'slot'`; a slot can also sit inside
+ * an `object` field or inside each item of an `array` field, and its name is
+ * then the prop path Puck gives it — `items[0].content`, `box.content`.
+ *
+ * One deliberate difference from Puck: Puck also walks an object whose field is
+ * NOT an `object` field using the PARENT's field map, so a key there that
+ * happens to share a slot's name is treated as a slot. No document relies on
+ * that (a non-array value there crashes Puck's own walk), and a rule that
+ * depends on a coincidence of names is not one to copy.
+ *
+ * Order is DECLARATION order — the order the fields are written in the config,
+ * which is the order a person reads the block in (`col1` before `col2`). Puck
+ * visits slots in reverse, as a side effect of how it fills empty ones; nothing
+ * in either app depends on that.
+ */
+
+/** One step of a prop path: a key, or an index into an array. */
+type Segment = string | number;
+declare function getIn(value: unknown, segments: readonly Segment[]): unknown;
+
+/** One translated value, and the fingerprint of the base value it was made from. */
+interface TranslatedValue {
+    v: unknown;
+    src: string;
+}
+/** One node's translated values, by prop path. */
+type TranslationEntries = Record<string, TranslatedValue>;
+/** One language's values, beside the document — never inside it. Keyed by node id, or `"root"`. */
+type TranslationOverlay = Record<string, TranslationEntries>;
+/** One translatable value in a document: whose it is, and where in its props. */
+interface TranslationRef {
+    id: string;
+    path: string;
+}
+interface TranslationStatus {
+    /** Values that want a translation (the base is not blank) or have one. */
+    total: number;
+    /** Values with words in the base and no translation: drawn in the base language. */
+    missing: TranslationRef[];
+    /** Values whose translation was made from a base value that has since changed. */
+    stale: TranslationRef[];
+}
+interface TranslatablePath {
+    path: string;
+    /** The value there now; `undefined` when the props hold none. */
+    value: unknown;
+}
+/** A node, or the root (`{ props }`, no type) — what `resolveNodeData` takes too. */
+interface TranslatableItem {
+    type?: string;
+    props: Record<string, unknown>;
+}
+/**
+ * A short, stable mark of a base value, kept beside its translation as `src`.
+ *
+ *   a string       `s<length>.<hash>`   the string itself is hashed
+ *   anything else  `j<length>.<hash>`   its JSON is hashed, keys sorted at
+ *                                       every level, because a document's key
+ *                                       order is not kept by the database
+ *   no value       `u`
+ *
+ * `<length>` is in UTF-16 code units and `<hash>` is FNV-1a (32 bits) over
+ * those units, both written in base 36. It is not a secret and not a proof:
+ * two values of the same length and the same 32-bit hash read as one, which is
+ * enough to notice that words were edited.
+ *
+ * The first letter names the scheme. These marks are STORED, so the function
+ * must go on giving the same answer for the same value; a better scheme takes
+ * a new letter rather than changing what `s` and `j` mean.
+ */
+declare function translationFingerprint(value: unknown): string;
+/**
+ * The props of a node (or of the root) that may be translated, in the order
+ * the fields declare them, each with the value it holds now.
+ *
+ * A top-level value, and one inside an `object` field, is listed whether or
+ * not the props hold it (`value: undefined`). One inside an `array` field is
+ * listed per item that is there.
+ */
+declare function translatablePaths(item: TranslatableItem, config: DataConfig): TranslatablePath[];
+/**
+ * The document in one language: every translated value laid over the base,
+ * every other value the base's.
+ *
+ * With no overlay, or an empty one, it is `data` ITSELF. Otherwise only the
+ * nodes that took a value are copied, along with what holds them; a block
+ * nothing was translated in is the same object before and after, and so is a
+ * document no entry lands in.
+ *
+ * An entry for a node that is not in the document (deleted, or not on this
+ * page), for a path the fields no longer declare, or for a block type the
+ * config does not know, is passed over — never an error.
+ */
+declare function applyTranslation(data: Data, config: DataConfig, overlay?: TranslationOverlay | null): Data;
+/**
+ * How far a language has got: how many values want a translation, which have
+ * none (`missing`) and which were translated from words that have since
+ * changed (`stale`). Both lists are in document order — the root, then the
+ * nodes as `walk` visits them — and name the place in the BASE document.
+ *
+ * A value the base leaves blank wants nothing and is not counted, unless the
+ * language has an entry for it. A stale entry under an array that was not
+ * found again is reported at the index it is stored under.
+ */
+declare function translationStatus(data: Data, config: DataConfig, overlay?: TranslationOverlay | null): TranslationStatus;
+/**
+ * The overlay a language's edit comes to. `edited` is the page as it was
+ * changed while it was shown in that language — `applyTranslation(base,
+ * previous)`, then words typed over it — and the answer holds an entry for
+ * every translatable value that differs from the base, with `src` the base
+ * value's fingerprint as it is now.
+ *
+ *   - A value equal to the base's makes NO entry: falling back is the absence
+ *     of one. So does a value that is not there (`undefined`).
+ *   - Only translatable values are read. A block added, removed or moved in
+ *     `edited`, an array of another length, a changed number or colour — the
+ *     structure is the base's alone while a language is being written, and a
+ *     difference there is passed over, never an error.
+ *   - `previous` is the overlay the edit started from. An entry the edit did
+ *     not touch is kept AS IT WAS, old `src` and all, so a save does not
+ *     quietly turn a stale translation into a current one; and what `previous`
+ *     holds for nodes that are not on the page is carried over (only
+ *     `pruneTranslation` drops). Where nothing changed, the answer is
+ *     `previous` itself.
+ */
+declare function extractTranslation(base: Data, edited: Data, config: DataConfig, previous?: TranslationOverlay | null): TranslationOverlay;
+/**
+ * Drop what no longer has a place: the entries of a node that is not in the
+ * document, and — in a node whose type the config knows — an entry at a path
+ * its fields no longer declare or its props no longer reach. An entry whose
+ * array item moved is written at the index it is drawn at.
+ *
+ * A node whose type the config does NOT know keeps its entries untouched for
+ * as long as the node is there, and so does any node found inside it: with no
+ * fields there is no telling which of its paths are gone, and a block's
+ * content is allowed to land before its code.
+ *
+ * Until a host calls this, the entries of a deleted node stay in the overlay —
+ * which is what lets undoing the delete bring its translations back. An
+ * overlay with nothing to drop comes back as itself.
+ */
+declare function pruneTranslation(data: Data, config: DataConfig, overlay: TranslationOverlay): TranslationOverlay;
+/**
+ * Carry an overlay across an edit of the BASE. `previousBase` is the document
+ * the overlay was in step with, `nextBase` the document after the edit.
+ *
+ * Only arrays need it. A node keeps its id wherever it goes, so moving one
+ * changes nothing here, and a node that was deleted keeps its entries (see
+ * `pruneTranslation`). An array item has no id, so its entries are stored
+ * under its INDEX, and this moves them to where the item went:
+ *
+ *   - an item that reads the same before and after keeps its entries, at its
+ *     new index (in place first; then the lowest unclaimed index before to the
+ *     lowest after, so identical items keep their order);
+ *   - an item that is at the same index on both sides but reads differently
+ *     was edited where it stands: its entries stay, and are stale wherever a
+ *     base value changed;
+ *   - an item that is new but reads the same as one that was there (a
+ *     duplicate) takes a COPY of that item's entries;
+ *   - an item that is gone takes its entries with it. An item cannot be
+ *     recognised again once it is out of the array, so a host that must bring
+ *     them back on undo keeps the overlay in the same history step as the base.
+ *
+ * Stale entries travel with their item, which reading the overlay later, with
+ * `nextBase` alone, could not do: it finds a moved item by its base
+ * fingerprint, and a stale entry no longer has one that matches.
+ *
+ * An overlay the edit does not disturb comes back as itself.
+ */
+declare function rebaseTranslation(previousBase: Data, nextBase: Data, config: DataConfig, overlay: TranslationOverlay): TranslationOverlay;
+/**
+ * Old id → new id, for a node and its copy: `duplicate` and `copyNode` give
+ * every copied node a fresh id, and an overlay is keyed by id. The two are
+ * walked side by side, slot by slot and child by child, for as far as they
+ * keep the same shape (a `strip` that drops a child ends the pairing there).
+ */
+declare function mapIds(source: Node, copy: Node, config: DataConfig): Record<string, string>;
+/**
+ * The entries a copied subtree starts with: for every old id in `ids` that the
+ * overlay has entries for, the same entries under the new id. ONLY those — lay
+ * them over the language's overlay (`{ ...overlay, ...copyTranslation(overlay,
+ * ids) }`), or carry them to another page with the clipboard. An entry whose
+ * base value the copy changed (`strip`) is stale there, as it should be.
+ */
+declare function copyTranslation(overlay: TranslationOverlay | null | undefined, ids: Record<string, string>): TranslationOverlay;
+
+/**
+ * efficient-easel/data — the document, as pure functions.
+ *
+ * The bottom layer of the engine that replaces Puck (the blueprint "Puck From
+ * The Ground Up For Efficient Editor", 2026-09-29, step 1.1). Every function
+ * takes a document and returns a new one; nothing here holds state, knows
+ * about React, or touches a browser global, so a server component, a Node
+ * script, a test and the editor's store all call the same code.
+ *
+ *   find · walk · slotsOf              read
+ *   insert · move · remove · duplicate change the tree
+ *   setProps · setRoot                 change one node's props, or the root's
+ *   normalizeData                      what the editor does to a document it opens
+ *   createNode · newId                 make a block the way the Add panel does
+ *   applyTranslation · …               a page's other languages, kept beside it (./translate)
+ *
+ * THE FORMAT DOES NOT CHANGE. A document goes in and comes out in exactly the
+ * shape Puck 0.20 saves (see ./types). Four rules keep it that way, and the
+ * round-trip spec pins each one:
+ *
+ *   1. An empty slot is written as `[]`, and `zones` is written as `{}`.
+ *   2. Default props follow Puck: a new block is created WITH its
+ *      `defaultProps`; the root's `defaultProps` are filled in on open; an
+ *      existing block is never back-filled.
+ *   3. A root prop that no field declares (a site's `theme`, `fonts`, `scales`)
+ *      is kept exactly as it is. Nothing here drops a key it doesn't know.
+ *   4. The two older formats are READ — root props written directly on `root`,
+ *      and children parked in `zones` — and converted on open, the way Puck's
+ *      `migrate()` converts them. They are never written back.
+ *
+ * KEY ORDER. The backend stores these documents in Postgres `jsonb`, which does
+ * not keep key order, so "the same document as Puck" means the same keys and
+ * values. What this layer does promise is stronger for its own round trip: a
+ * document that is already in shape comes back as THE SAME OBJECT (so
+ * `normalizeData(doc) === doc`), and every edit copies only the nodes on the
+ * path to the change — an untouched block is the same object before and after.
+ *
+ * ERRORS. An edit that names a node or slot that is not there, an index off the
+ * end of a list, a move into the node's own subtree, or an insert that would
+ * put a second copy of an id into the document throws a `DataError`. The
+ * editor's store decides what an operator sees; this layer never guesses.
+ *
+ * LEAF DISCIPLINE: no imports outside this folder, no dependency at all.
+ * `crypto` is read inside `newId`, never at module evaluation.
+ */
+
+/**
+ * What `normalizeData` accepts: any saved document, as loosely as Puck's own
+ * `Data` type describes one (`root.props` optional). Converting the older
+ * shapes is its job, so it must take them without a cast. Every OTHER function
+ * here takes the normalised `Data` it returns.
+ */
+interface DataInput {
+    root?: {
+        props?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    content?: unknown[];
+    zones?: Record<string, unknown[]>;
+}
+
+/** The root's id in a zone key, and the parent of the top-level list. */
+declare const ROOT_ID = "root";
+/** The top-level list's slot name. */
+declare const ROOT_SLOT = "default-zone";
+/** The top-level list, as an address. */
+declare const ROOT_LIST: SlotAddress;
+/** `{ parentId, slot }` → Puck's zone key `"<parentId>:<slot>"`. */
+declare const zoneKey: ({ parentId, slot }: SlotAddress) => string;
+/** Puck's zone key → `{ parentId, slot }`. Ids and prop paths hold no colon. */
+declare function parseZoneKey(key: string): SlotAddress;
+type DataErrorCode = 'not-found' | 'no-slot' | 'bad-index' | 'duplicate-id' | 'cycle' | 'id-change' | 'unknown-type';
+declare class DataError extends Error {
+    readonly code: DataErrorCode;
+    constructor(code: DataErrorCode, message: string);
+}
+/**
+ * `<Type>-<uuid>` — the id every saved block already carries, in both apps.
+ * Where `crypto.randomUUID` is unavailable (a non-secure origin, an old test
+ * runtime) it falls back to time plus randomness: ids are persisted, so they
+ * must stay unique across page loads, which a counter would not.
+ */
+declare function newId(type: string): string;
+/** A node's slots in declaration order. A missing top-level slot reads as `[]`. */
+declare function slotsOf(node: Node, config: DataConfig): SlotEntry[];
+/**
+ * Visit every node once, depth first, parent before children: the top-level
+ * list, then any slots on the root, then anything still parked in a legacy
+ * `zones` entry. Entries in a list that are not nodes are skipped, and indexes
+ * are always positions in the stored list.
+ *
+ * `visit` may return a node to put in this one's place (its id must not
+ * change); its children are then walked from the replacement. Returning
+ * nothing keeps the node. The result is `data` itself when nothing was
+ * replaced.
+ */
+declare function walk(data: Data, config: DataConfig, visit: (node: Node, info: WalkInfo) => Node | void): Data;
+/** Where the node with this id is, or `null`. The first match in walk order. */
+declare function find(data: Data, config: DataConfig, id: string): Found | null;
+/** The list at an address, or `null` when no such slot exists. */
+declare function getList(data: Data, config: DataConfig, address: SlotAddress): Node[] | null;
+/**
+ * What the editor does to a document when it opens it — the same result Puck
+ * reaches on load, with the older formats converted (rule 4):
+ *
+ *   - `root` holding its props directly becomes `{ props: { …those keys } }`;
+ *   - the root's `defaultProps` fill any root prop that is missing (rule 2);
+ *   - every declared top-level slot exists, `[]` when empty (rule 1);
+ *   - `content` is a list and `zones` exists, `{}` when there is nothing in it;
+ *   - children parked in `zones["<id>:<slot>"]` move into that slot when the
+ *     node declares it and the slot is empty. Anything else in `zones` stays
+ *     where it is — never dropped, never merged over content.
+ *
+ * A document already in shape is returned as the same object.
+ */
+declare function normalizeData(data: DataInput | Data, config: DataConfig): Data;
+/**
+ * A new block, the way the Add panel makes one — Puck's `insert` recipe:
+ * `{ ...defaultProps, id }`, plus any `props` the caller starts it with. The
+ * defaults are copied, so two blocks never share an array or object, and every
+ * child a default slot seeds gets its own id.
+ */
+declare function createNode(config: DataConfig, type: string, props?: Record<string, unknown>, options?: {
+    id?: string;
+}): Node;
+/**
+ * Put `node` into the list at `place`. The node is brought into shape (default
+ * slots, ids for children that have none) and must not bring an id the
+ * document already holds — that is the bug where two blocks select, hide and
+ * delete together.
+ */
+declare function insert(data: Data, config: DataConfig, place: Place, node: Node): Data;
+/** Take the node, and everything under it, out of the document. */
+declare function remove(data: Data, config: DataConfig, id: string): Data;
+/**
+ * Move a node to `to`. Within one list, `to.index` is the node's index AFTER
+ * the move (Puck's rule), so `0 … length-1`; into another list it is the index
+ * to insert at, `0 … length`. A move into the node's own subtree is refused.
+ */
+declare function move(data: Data, config: DataConfig, id: string, to: Place): Data;
+/**
+ * Copy a node, and everything under it, to the place just after it. Every
+ * copied node gets a fresh id. `strip` sees each copied node (with its new id)
+ * and returns what to keep — the hook for "a copy must not claim the
+ * original's baked image" (`bakedId`), which Puck's own duplicate copied
+ * verbatim.
+ */
+declare function duplicate(data: Data, config: DataConfig, id: string, options?: {
+    id?: string;
+    strip?: (node: Node) => Node;
+}): Data;
+/**
+ * A copy of `node` and everything under it, every copied node with a FRESH id —
+ * what a paste inserts, so a clipboard can be pasted twice without two blocks
+ * sharing an id. `strip` sees each copied node, as in `duplicate`. The input is
+ * not touched.
+ */
+declare function copyNode(node: Node, config: DataConfig, options?: {
+    id?: string;
+    strip?: (node: Node) => Node;
+}): Node;
+/**
+ * Merge `patch` into a node's props — Puck's `replace`, for the common case of
+ * changing some props. A key keeps its place; a new key goes on the end;
+ * `undefined` clears a key (JSON drops it on save). New children in a patched
+ * slot are brought into shape. Changing `id` is refused. A patch that changes
+ * nothing returns `data` itself.
+ */
+declare function setProps(data: Data, config: DataConfig, id: string, patch: Record<string, unknown>): Data;
+/**
+ * Replace a node wholesale — Puck's `replace` action: the node keeps its place
+ * and its id, and every prop is the new node's (a key it does not carry is
+ * gone, which `setProps` cannot do). Children in its slots that arrive without
+ * an id get one, and an id another node already holds is refused, as `insert`
+ * refuses it.
+ */
+declare function replaceNode(data: Data, config: DataConfig, id: string, node: Node): Data;
+/** Merge `patch` into the root's props, the same way `setProps` does. */
+declare function setRoot(data: Data, config: DataConfig, patch: Record<string, unknown>): Data;
+
+export { Data, DataConfig, DataError, type DataErrorCode, type DataInput, Found, Node, Place, ROOT_ID, ROOT_LIST, ROOT_SLOT, type Segment, SlotAddress, SlotEntry, type TranslatableItem, type TranslatablePath, type TranslatedValue, type TranslationEntries, type TranslationOverlay, type TranslationRef, type TranslationStatus, WalkInfo, applyTranslation, copyNode, copyTranslation, createNode, duplicate, extractTranslation, find, getIn, getList, insert, mapIds, move, newId, normalizeData, parseZoneKey, pruneTranslation, rebaseTranslation, remove, replaceNode, setProps, setRoot, slotsOf, translatablePaths, translationFingerprint, translationStatus, walk, zoneKey };

package/dist/data/index.js

@@ -0,0 +1 @@
+export{DataError,ROOT_ID,ROOT_LIST,ROOT_SLOT,applyTranslation,changedProps,copyNode,copyTranslation,createNode,createResolveCache,deepEqual,duplicate,extractTranslation,find,getList,insert,mapIds,move,newId,normalizeData,parseZoneKey,pruneTranslation,rebaseTranslation,remove,replaceNode,resolveNodeData,setProps,setRoot,slotsOf,translatablePaths,translationFingerprint,translationStatus,walk,zoneKey}from"../chunk-KRXQM65X.js";export{getIn}from"../chunk-NKB3KVAB.js";