@nuforge/editor 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -2,7 +2,6 @@ import * as t from '@nuforge/types';
 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';
@@ -10,11 +9,6 @@ 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;
@@ -32,65 +26,29 @@ 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;
@@ -104,9 +62,6 @@ 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;
 }
@@ -118,8 +73,6 @@ interface CanvasPatchMessage {
     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;
@@ -131,9 +84,6 @@ 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 {
@@ -174,151 +124,58 @@ interface CanvasLinkClickMessage {
 }
 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;
@@ -327,12 +184,9 @@ 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;
@@ -343,20 +197,15 @@ 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;