@nuforge/editor 0.1.3 → 0.3.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as t from '@nuforge/types';
-import { Nu } from '@nuforge/core';
+import { Nu, NuExternalsFactory } from '@nuforge/core';
 import { MutationEntry } from '@nuforge/reactivity';
 
+/** A control hint for auto-generating inspector fields from a block's props. */
 interface PropSchemaField {
     name: string;
     type: 'string' | 'number' | 'boolean' | 'expression' | 'enum';
@@ -9,6 +10,11 @@ interface PropSchemaField {
     default?: string | number | boolean;
     options?: string[];
 }
+/**
+ * A reusable element/block in the palette. `create()` returns a fresh template
+ * subtree to insert. `icon` is a name (not a component) so the registry stays
+ * framework-agnostic; the UI maps the name to its own icon set.
+ */
 interface Block {
     id: string;
     label: string;
@@ -26,58 +32,293 @@ declare class BlockRegistry {
     all(): Block[];
     byCategory(): Record<string, Block[]>;
 }
+/** The built-in palette — the common HTML primitives. */
 declare const DEFAULT_BLOCKS: Block[];
 
+/** A literal expression (`"x"`, `5`, `true`). */
 declare function lit(value: string | number | boolean): t.Literal;
+/** A text node: `<text text={value} />`, rendered as its string value. */
 declare function text(value: string): t.TagTemplate;
+/**
+ * Concise element builder — `el('div', { class: lit('box') }, [text('hi')])`
+ * instead of the verbose `t.tagTemplate({ tag, props, children })`.
+ */
 declare function el(tag: string, props?: Record<string, t.Expression>, children?: t.Template[]): t.TagTemplate;
 
+/** Where a dragged node is dropped relative to a target. */
 type DropPosition = 'before' | 'after' | 'inside';
+/**
+ * Compute a drop position from the pointer's Y against a target's bounding rect.
+ * When `allowInside` is set, the middle band is `inside` (drop as a child) and
+ * the outer bands are `before`/`after`; otherwise it's a simple before/after
+ * split at the midpoint. Pure — use it from an `onDragOver`/`onPointerMove`
+ * handler to drive a drop indicator and the eventual `moveNode`/`pasteNode`.
+ */
 declare function dropPositionFromPointer(clientY: number, rect: {
     top: number;
     height: number;
 }, opts?: {
     allowInside?: boolean;
 }): DropPosition;
+/** A human label for a template node (tag name, component name, slot, …). */
 declare function templateLabel(node: t.Template): string;
+/** Child templates of a node (empty for leaves / text nodes). */
 declare function templateChildren(node: t.Template): t.Template[];
+/** Is this a text node (`<text text=…>`), rendered as its string value? */
 declare function isTextTemplate(node: t.Template): boolean;
+/** Preview the content of a text node, e.g. for a layers tree. */
 declare function textPreview(node: t.Template): string | null;
+/** Can this node hold appended children? */
 declare function canHaveChildren(node: t.Template | null): boolean;
+/** Is `ancestor` somewhere above `node` in the tree? */
 declare function isAncestorOf(nu: Nu, ancestor: t.Template, node: t.Template): boolean;
 
+/**
+ * Wire protocol for `RemoteCanvasHost` <-> `createCanvasReceiver`: a genuinely
+ * navigated `/canvas/[id]`-style iframe has its own JS realm, so state and
+ * interaction can't cross as direct object references the way `IframeCanvas`'s
+ * portal allows — everything here is a structured-clone-safe plain message.
+ *
+ * Deliberately generic: only the shapes the editor primitive itself needs
+ * (state sync, ready handshake, the core interaction events) are typed. Host
+ * concerns like theme/preview-mode/overrides ride through `CanvasUiMessage`'s
+ * opaque `payload` — this package relays it, never interprets it.
+ */
+declare const CANVAS_CHANNEL = "nuforge-canvas";
+declare const CANVAS_PROTOCOL_VERSION = 1;
+/** Namespace the `BroadcastChannel` per canvas instance (derive from the
+ *  iframe's own `src`, so a host never has to invent/track a separate id). */
+declare function canvasChannelName(src: string): string;
+/** The `{ root, types }` shape from `@nuforge/types`' `flatten` — plain JSON,
+ *  safe across `postMessage`/`BroadcastChannel`'s structured clone. */
+interface FlattenedState {
+    root: {
+        $$typeId: string;
+    };
+    types: Record<string, {
+        type: string;
+        [key: string]: unknown;
+    }>;
+}
+interface CanvasInitMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'init';
+    /** Which component the canvas should render (matches `Nu.createFrame`'s
+     *  `component.name`) — lets the SAME canvas realm switch pages without a
+     *  full iframe reload; only the rendered Frame changes. */
+    activeComponent: string;
+    flat: FlattenedState;
+}
+interface CanvasPatchMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'patch';
+    activeComponent: string;
+    flat: FlattenedState;
+    rev: number;
+}
+/** Host-defined payload (theme CSS, preview-mode toggle, hide/lock overrides,
+ *  ...) — nucode doesn't interpret this, just relays it verbatim. */
+interface CanvasUiMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'ui';
+    payload: unknown;
+}
+type CanvasHostMessage = CanvasInitMessage | CanvasPatchMessage | CanvasUiMessage;
+interface CanvasReadyMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'ready';
+    /** Distinguishes a fresh mount from a stale one still catching up (e.g. a
+     *  rapid remount) — the host ignores a `ready` whose `mountGen` is not newer
+     *  than the last one it accepted. */
+    mountGen: number;
+}
+interface CanvasSelectMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'select';
+    nodeId: string | null;
+}
+interface CanvasHoverMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'hover';
+    nodeId: string | null;
+}
+interface CanvasDropMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'drop';
+    targetId: string;
+    position: DropPosition;
+}
+interface CanvasKeydownMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'keydown';
+    key: string;
+    code: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+}
+interface CanvasLinkClickMessage {
+    channel: typeof CANVAS_CHANNEL;
+    v: typeof CANVAS_PROTOCOL_VERSION;
+    type: 'link-click';
+    href: string;
+}
+type CanvasClientMessage = CanvasReadyMessage | CanvasSelectMessage | CanvasHoverMessage | CanvasDropMessage | CanvasKeydownMessage | CanvasLinkClickMessage;
+type CanvasMessage = CanvasHostMessage | CanvasClientMessage;
+/** Plain `Omit` collapses a union to only its shared keys (`keyof` over a
+ *  union intersects, not unions) — this distributes per member instead, so
+ *  e.g. `DistributiveOmit<CanvasClientMessage, 'channel' | 'v'>` still keeps
+ *  each variant's own fields (`nodeId`, `targetId`, `key`, ...). */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** Narrow an arbitrary `BroadcastChannel` payload to a message from this
+ *  protocol — guards against unrelated traffic on the same channel name and
+ *  against a version mismatch across a stale cached bundle. */
+declare function isCanvasMessage(data: unknown): data is CanvasMessage;
+
+interface CanvasReceiverOpts {
+    /** Must match the `src` `RemoteCanvasHost` was given — the channel name is
+     *  derived from it, so both sides agree without a separate id to track. */
+    src: string;
+    externals?: NuExternalsFactory;
+}
+interface CanvasReceiver {
+    /**
+     * A `Nu` instance mirroring the host's, kept in sync one-way (host -> here)
+     * via `init`/`patch` messages. It's a genuinely mutable, loaded `Nu` — DSL
+     * `onClick` handlers rendered from it run and mutate it locally exactly like
+     * any other `Nu` (e.g. a counter's `val inc = () => count = count + 1`, used
+     * by an in-editor "preview mode" toggle to stay truly interactive). That
+     * local mutation is intentionally NOT relayed back to the host: the next
+     * `init`/`patch` from the host simply overwrites/merges over it, so nothing
+     * here needs to enforce read-only-ness — only `RemoteCanvasHost`'s own
+     * resync-on-transition behavior needs to guarantee a clean return to the
+     * host's authoritative state (see its docs).
+     */
+    nu: Nu;
+    /** Which component `nu` should currently be rendered as (via
+     *  `nu.createFrame({ component: { name } })`) — reactive, so a component
+     *  wrapped in `@nuforge/react`'s `observer()` re-renders when it changes. */
+    volatile: {
+        activeComponent: string | null;
+        /**
+         * Bumped every time `nu` gets a full `nu.load()` — a bootstrap, a resync
+         * (previewMode/activeComponent change), OR a `patch` whose flattened
+         * node-id set differs from the current one (nodes added/removed, not
+         * just field edits — see `applyState`). Callers building a Frame (e.g.
+         * via `useNuFrame`) should key their memo/`key` on this, alongside
+         * `activeComponent`, so React remounts and gets a fresh Frame instead of
+         * reading a disposed one.
+         *
+         * Structural patches are folded into the SAME full-reload path as
+         * `init`, not merged in place, even though that means a `val`'s live
+         * runtime value (e.g. a preview-mode counter's `count` — lives in a
+         * Frame's `Environment` bindings, not `nu.state`'s AST) gets reset too.
+         * An earlier version tried to preserve that by merging state first and
+         * bumping this counter as a second, separate step — that let React
+         * render the OLD (soon-stale) Frame against the ALREADY-merged,
+         * structurally-different `nu.state` in between the two updates
+         * (`Frame`'s template/component caches are keyed by structural PATH, not
+         * object identity, and aren't evicted on removal), producing duplicate
+         * React keys or a briefly-missing node before the remount caught up.
+         * Doing both as one atomic `nu.load()` + bump — the same already-proven
+         * resync path — closes that window entirely.
+         */
+        loadGeneration: number;
+    };
+    /** Announce this receiver is mounted and ready for the host's first `init`.
+     *  Call once, after registering any `onUi`/message handling — the host may
+     *  reply synchronously-ish (same task queue) once it sees `ready`. */
+    postReady(): void;
+    /** Register a callback for host->iframe UI payloads (`ui` messages) —
+     *  interpretation (theme, preview mode, overrides, ...) is entirely up to
+     *  the caller; this SDK only relays the envelope. Returns an unsubscribe. */
+    onUi(cb: (payload: unknown) => void): () => void;
+    /** Send an interaction event up to the host (select/hover/drop/keydown/link-click). */
+    postEvent(message: DistributiveOmit<CanvasClientMessage, 'channel' | 'v'>): void;
+    dispose(): void;
+}
+/**
+ * Canvas-side receiver for a genuinely-navigated `/canvas/[id]`-style route:
+ * a `Nu` instance kept in sync with the host's one-way, via `BroadcastChannel`
+ * + `t.unflatten`/`t.merge` (the same primitives `@nuforge/collaboration`'s
+ * `LoroSyncProvider` uses for its state<->doc binding, without the CRDT layer
+ * — there's exactly one writer here, so convergence machinery is unneeded).
+ * No `createEditor()`: this instance is never meant to originate an edit the
+ * host doesn't already know about, so it only needs `Nu`, not the mutation SDK.
+ */
+declare function createCanvasReceiver(opts: CanvasReceiverOpts): CanvasReceiver;
+
 interface CreateEditorOptions {
+    /** Extra blocks to add to the palette. */
     blocks?: Block[];
+    /** Include the built-in DEFAULT_BLOCKS (default true). */
     defaultBlocks?: boolean;
 }
+/**
+ * A high-level facade over a {@link Nu} runtime for building visual page
+ * editors. Every mutation goes through `nu.change`, so it is transactional and
+ * undoable. Reach for these instead of hand-splicing the AST.
+ */
 declare class Editor {
     readonly nu: Nu;
     readonly blocks: BlockRegistry;
     readonly commands: CommandRegistry;
     constructor(nu: Nu, opts?: CreateEditorOptions);
+    /** Append (or insert at `index`) `child` into `parent`'s children. */
     insertNode(parent: t.Template, child: t.Template, index?: number): void;
+    /** Remove a node from its parent. Returns false if it has no parent. */
     removeNode(node: t.Template): boolean;
+    /** Move `dragged` before/after/inside `target`. Refuses to nest into self. */
     moveNode(dragged: t.Template, target: t.Template, position: DropPosition): boolean;
     private clipboardNode;
+    /** Put a node on the editor clipboard (a clone is made on paste). */
     copyNode(node: t.Template): void;
+    /** Copy a node, then remove it. */
     cutNode(node: t.Template): boolean;
+    /** Whether there is something on the clipboard to paste. */
     canPaste(): boolean;
+    /**
+     * Paste a fresh copy (new ids) of the clipboard node before/after/inside
+     * `target`. Returns the inserted node, or null if nothing was pasted.
+     */
     pasteNode(target: t.Template, position?: DropPosition): t.Template | null;
+    /** Duplicate a node in place (inserted right after it). Returns the copy. */
     duplicateNode(node: t.Template): t.Template | null;
+    /**
+     * Insert a detached node before/after/inside a target (undoable). The core of
+     * canvas drag-and-drop: a drop computes a target + position, then calls this.
+     * Returns the inserted node.
+     */
     insertNodeAt(node: t.Template, target: t.Template, position: DropPosition): t.Template | null;
+    /** Create a block and insert it before/after/inside a target. */
     insertBlockAt(blockId: string, target: t.Template, position: DropPosition): t.Template | null;
     private insertCloneRelativeTo;
+    /** Set several props at once. */
     updateProps(node: t.Template, props: Record<string, t.Expression>): void;
     setProp(node: t.Template, key: string, expr: t.Expression): void;
     removeProp(node: t.Template, key: string): void;
+    /** Parse `source` as a nuforge expression and assign it to `key`. */
     setExpression(node: t.Template, key: string, source: string): boolean;
+    /** Update a text node's literal value. */
     setText(node: t.Template, value: string): boolean;
     setTag(node: t.TagTemplate, tag: string): void;
     addClass(node: t.Template, name: string): void;
+    /** Parse `source` and set the condition under which class `name` applies. */
     setClassCondition(node: t.Template, name: string, source: string): boolean;
     removeClass(node: t.Template, name: string): void;
+    /** Set the `@if` condition from source. */
     setCondition(node: t.Template, source: string): boolean;
     clearCondition(node: t.Template): void;
+    /** Repeat a node over `iterator` (a list expression), binding each `alias`. */
     setEach(node: t.Template, iterator: string, alias?: string, indexName?: string): boolean;
     clearEach(node: t.Template): void;
     addState(component: t.NuComponent, name?: string, init?: string): t.Val;
@@ -86,9 +327,12 @@ declare class Editor {
     addComponentProp(component: t.NuComponent, name?: string, init?: string): t.ComponentProp;
     removeComponentProp(component: t.NuComponent, prop: t.ComponentProp): void;
     setComponentPropInit(prop: t.ComponentProp, source: string): boolean;
+    /** Create a block's template and insert it into `parent`. */
     insertBlock(blockId: string, parent: t.Template, index?: number): t.Template | null;
     private uniqueName;
+    /** Add a new component (a "page"). */
     addComponent(name?: string): t.NuComponent;
+    /** Rename a component, updating `<Name/>` references across the program. */
     renameComponent(component: t.NuComponent, name: string): boolean;
     removeComponent(component: t.NuComponent): boolean;
     duplicateComponent(component: t.NuComponent): t.NuComponent;
@@ -99,15 +343,20 @@ declare class Editor {
     getChildren(node: t.Template): t.Template[];
     getSiblings(node: t.Template): t.Template[];
     getNodeIndex(node: t.Template): number;
+    /** Full path from the State root to this node (for selections/serialization). */
     getNodePath(node: t.Type): Array<string | number>;
+    /** Fires with the raw field-level writes of every change (incl. undo/redo). */
     onChange(cb: (entries: MutationEntry[]) => void): () => void;
+    /** Fires only when the tree shape changes (a child array was mutated). */
     onStructureChange(cb: () => void): () => void;
     private spliceFromParent;
     private applyMove;
+    /** Insert an already-detached node relative to `target` (no removal). */
     private insertRelativeTo;
 }
 declare function createEditor(nu: Nu, opts?: CreateEditorOptions): Editor;
 
+/** A named action a UI can discover and bind to (toolbar buttons, shortcuts). */
 interface Command {
     id: string;
     label: string;
@@ -124,5 +373,5 @@ declare class CommandRegistry {
     run(id: string): void;
 }
 
-export { BlockRegistry, CommandRegistry, DEFAULT_BLOCKS, Editor, canHaveChildren, createEditor, defineBlock, dropPositionFromPointer, el, isAncestorOf, isTextTemplate, lit, templateChildren, templateLabel, text, textPreview };
-export type { Block, Command, CreateEditorOptions, DropPosition, PropSchemaField };
+export { BlockRegistry, CANVAS_CHANNEL, CANVAS_PROTOCOL_VERSION, CommandRegistry, DEFAULT_BLOCKS, Editor, canHaveChildren, canvasChannelName, createCanvasReceiver, createEditor, defineBlock, dropPositionFromPointer, el, isAncestorOf, isCanvasMessage, isTextTemplate, lit, templateChildren, templateLabel, text, textPreview };
+export type { Block, CanvasClientMessage, CanvasDropMessage, CanvasHostMessage, CanvasHoverMessage, CanvasInitMessage, CanvasKeydownMessage, CanvasLinkClickMessage, CanvasMessage, CanvasPatchMessage, CanvasReadyMessage, CanvasReceiver, CanvasReceiverOpts, CanvasSelectMessage, CanvasUiMessage, Command, CreateEditorOptions, DistributiveOmit, DropPosition, FlattenedState, PropSchemaField };