@nuforge/editor 0.2.0 → 0.3.0

package/dist/react.d.ts

@@ -3,6 +3,7 @@ import { ReactNode } from 'react';
 import * as t from '@nuforge/types';
 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,6 +11,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;
@@ -27,6 +33,35 @@ declare class BlockRegistry {
     byCategory(): Record<string, Block[]>;
 }
 
+/** Where a dragged node is dropped relative to a target. */
+type DropPosition = 'before' | 'after' | 'inside';
+
+/**
+ * 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;
+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;
+}
+
+/** A named action a UI can discover and bind to (toolbar buttons, shortcuts). */
 interface Command {
     id: string;
     label: string;
@@ -43,40 +78,68 @@ declare class CommandRegistry {
     run(id: string): void;
 }
 
-type DropPosition = 'before' | 'after' | 'inside';
-
 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;
@@ -85,9 +148,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;
@@ -98,11 +164,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;
 }
 
@@ -113,31 +183,76 @@ interface Rect {
     height: number;
 }
 interface CanvasWindow {
+    /** The canvas's own document — the iframe's, inside `IframeCanvas`. */
     doc: Document | null;
+    /** The canvas's own window — the iframe's, inside `IframeCanvas`. */
     window: Window | null;
 }
+/**
+ * The real `window`/`document` a canvas-rendered element visually lives in.
+ * `IframeCanvas` portals its content into an `<iframe>`, but a portal only
+ * relocates DOM nodes — the JS building them still runs in the host page's
+ * realm. Any library that reads a bare `window`/`document` global (scroll
+ * listeners, `matchMedia`, `ResizeObserver`/`IntersectionObserver` defaults)
+ * silently ends up watching the HOST page, not the iframe the user actually
+ * sees and scrolls. Build refs/options from `useCanvasWindow()` instead of the
+ * ambient global so they resolve to the right realm — this works identically
+ * outside `IframeCanvas` too (e.g. `NuFrame`'s direct, non-iframe render),
+ * where it's just the ambient `window`/`document`.
+ */
 declare function useCanvasWindow(): CanvasWindow;
+/** Reactive renderer for a frame, decorating each element with `data-nu-id`. */
 declare const EditorFrame: (props: {
     frame: Frame;
 }) => ReactNode;
+/** Map a DOM node (or event target) back to its template id. */
 declare function templateIdFromElement(target: EventTarget | null): string | null;
+/** Sensible default styling for the isolated canvas document. */
 declare const DEFAULT_CANVAS_CSS = "\n  *, *::before, *::after { box-sizing: border-box; }\n  html, body { margin: 0; }\n  body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; color: #111; line-height: 1.5; padding: 28px; }\n  h1 { font-size: 2rem; font-weight: 700; margin: .5em 0; }\n  h2 { font-size: 1.5rem; font-weight: 600; margin: .6em 0; }\n  h3 { font-size: 1.2rem; font-weight: 600; margin: .7em 0; }\n  p { margin: .8em 0; }\n  ul { list-style: disc; padding-left: 1.5em; margin: .8em 0; }\n  ol { list-style: decimal; padding-left: 1.5em; margin: .8em 0; }\n  a { color: #2563eb; text-decoration: underline; }\n  button { border: 1px solid #d4d4d8; border-radius: 6px; padding: 4px 12px; background: #fafafa; cursor: pointer; font: inherit; }\n  button:hover { background: #f4f4f5; }\n  input, textarea, select { border: 1px solid #d4d4d8; border-radius: 6px; padding: 4px 8px; font: inherit; }\n  section { display: flex; align-items: center; gap: .75rem; margin: .8em 0; }\n  img { max-width: 100%; }\n  [data-nu-id] { cursor: default; }\n";
 interface IframeCanvasProps {
     frame: Frame;
     selectedId?: string | null;
     hoveredId?: string | null;
+    /** Bump to force the overlay to recompute (e.g. on every committed change). */
     revision?: number;
+    /**
+     * Turn the canvas into a live, interactive preview. When `true`, the editing
+     * affordances are switched off: clicks and hovers pass through to the real
+     * elements (buttons fire, links work, inputs focus), drag-and-drop editing is
+     * disabled, and no overlay is drawn. When `false` (the default) the canvas is
+     * in edit mode — clicks select instead of activating, hover highlights, and
+     * `onDropOnNode` / `renderBox` are live. The same reactive `frame` is shown in
+     * both modes, so toggling is instant and state is preserved.
+     */
     previewMode?: boolean;
     onSelect?: (id: string | null) => void;
     onHover?: (id: string | null) => void;
+    /**
+     * Enable drop-on-canvas: fired when something is dropped onto a node. Compute
+     * a block to insert and call `editor.insertBlockAt(blockId, target, position)`.
+     */
     onDropOnNode?: (targetId: string, position: DropPosition, event: DragEvent) => void;
+    /** CSS injected into the isolated document (defaults to DEFAULT_CANVAS_CSS). */
     baseCss?: string;
+    /**
+     * Initial HTML for the iframe document — put anything in the `<head>` (CDN
+     * stylesheets, web fonts, `<script>` tags, a `<base>`, meta). The frame is
+     * portaled into its `<body>`. `baseCss` is still appended on top; pass
+     * `baseCss=""` to fully control styling from here.
+     */
     srcDoc?: string;
     className?: string;
     containerClassName?: string;
+    /**
+     * Build the overlay from the computed selection / hover / drop rects and the
+     * selected element's tag. Omit it for no overlay. The overlay container is
+     * pointer-events:none — set `pointerEvents: 'auto'` on interactive bits (e.g.
+     * an action toolbar) so they receive clicks.
+     */
     renderBox?: (rects: {
         selected: Rect | null;
         hovered: Rect | null;
+        /** Tag name of the selected element, e.g. `"div"`. */
         selectedLabel: string | null;
         drop: {
             rect: Rect;
@@ -145,17 +260,103 @@ interface IframeCanvasProps {
         } | null;
     }) => ReactNode;
 }
+/**
+ * A style-isolated editor canvas: the frame is portaled into an `<iframe>` so
+ * the host's CSS can't leak into the preview (and vice-versa). Selection/hover
+ * use native capture listeners on the iframe document, so element handlers stay
+ * inert while editing. Selection/hover rects are computed (in a layout effect,
+ * after the iframe commits) and handed to `renderBox` for the overlay.
+ */
 declare function IframeCanvas({ frame, selectedId, hoveredId, revision, previewMode, onSelect, onHover, onDropOnNode, baseCss, srcDoc, className, containerClassName, renderBox, }: IframeCanvasProps): ReactNode;
+interface RemoteCanvasHostProps {
+    /** The host's `Nu` instance — flattened and pushed to the canvas realm on
+     *  every committed change. Never referenced directly by the canvas realm: a
+     *  real `src` navigation puts it in a separate JS realm with no shared
+     *  object identity, unlike `IframeCanvas`'s portal. */
+    nu: Nu;
+    /** Which component the canvas should render (`Nu.createFrame`'s `component.name`). */
+    activeComponent: string;
+    /** The canvas route's URL, e.g. `/canvas/my-project`. The `BroadcastChannel`
+     *  name is derived from it, so `createCanvasReceiver` on the other end just
+     *  needs the SAME `src` — no separate id to keep in sync. */
+    src: string;
+    selectedId?: string | null;
+    hoveredId?: string | null;
+    /** Bump to force the overlay to recompute (e.g. on every committed change). */
+    revision?: number;
+    /**
+     * Mirrors `IframeCanvas`'s `previewMode`: when `true`, the canvas is a live,
+     * interactive preview (its own DSL `onClick` handlers run against the
+     * canvas's local `Nu`, since that instance is genuinely loaded and mutable —
+     * see `createCanvasReceiver`'s docs). Toggling this (either direction) forces
+     * a fresh `init` instead of an incremental `patch`, so any preview-only
+     * local mutation never lingers once you're back in edit mode.
+     */
+    previewMode?: boolean;
+    /** Opaque host-defined payload (theme CSS, hide/lock overrides, ...) pushed
+     *  to the canvas via a `ui` message whenever this reference changes. */
+    uiPayload?: unknown;
+    onSelect?: (id: string | null) => void;
+    onHover?: (id: string | null) => void;
+    onDropOnNode?: (targetId: string, position: DropPosition) => void;
+    onKeydownRelay?: (e: Omit<CanvasKeydownMessage, 'channel' | 'v' | 'type'>) => void;
+    onLinkClick?: (href: string) => void;
+    className?: string;
+    containerClassName?: string;
+    /**
+     * Build the overlay from the computed selection / hover rects and the
+     * selected element's tag — same contract as `IframeCanvas`'s `renderBox`
+     * (no `drop` rect: the canvas realm renders its own drop indicator locally,
+     * since it already has the DOM geometry and relaying it every `dragover`
+     * tick would add a message-per-frame the local realm doesn't need). Reading
+     * these rects is a same-origin DOM read (`iframe.contentDocument`), which a
+     * real `src` navigation doesn't block — only shared JS object identity is
+     * blocked, not DOM geometry reads.
+     */
+    renderBox?: (rects: {
+        selected: Rect | null;
+        hovered: Rect | null;
+        selectedLabel: string | null;
+    }) => ReactNode;
+}
+/**
+ * The `IframeCanvas` alternative for when a canvas needs its OWN genuine JS
+ * realm — e.g. so a third-party library reading bare `window`/`document` at
+ * module scope (an animation library's scroll-linked internals, a gesture
+ * library, ...) resolves against the canvas's real globals instead of
+ * silently binding to the host page's. A portal can't fix this (see
+ * `useCanvasWindow`'s docs for that half of the problem) because it only
+ * relocates DOM nodes, not the JS module graph building them.
+ *
+ * Renders a genuinely-`src`-navigated `<iframe>` — no `createPortal`, so
+ * nothing here shares object identity with the canvas's own React tree. State
+ * flows one-way, host -> canvas, over a `BroadcastChannel` as `t.flatten`'d
+ * JSON (see `./canvas-protocol`); interaction (select/hover/drop/keydown/
+ * link-click) relays back the other way as small typed messages. Pair with
+ * `createCanvasReceiver` (`./canvas-client`) on the canvas route's own end.
+ */
+declare function RemoteCanvasHost({ nu, activeComponent, src, selectedId, hoveredId, revision, previewMode, uiPayload, onSelect, onHover, onDropOnNode, onKeydownRelay, onLinkClick, className, containerClassName, renderBox, }: RemoteCanvasHostProps): ReactNode;
+/** Re-render only when the tree shape changes (add/remove/move). */
 declare function useStructureRevision(editor: Pick<Editor, 'onStructureChange'>): number;
+/** Re-render on every committed change (for undo state, inspectors, …). */
 declare function useEditorRevision(editor: Pick<Editor, 'onChange'>): number;
 type PropFieldValue = string | number | boolean | undefined;
 interface PropFieldsProps {
+    /** The control schema (e.g. a block's `props`). */
     fields: PropSchemaField[];
+    /** Current value per field name. */
     values: Record<string, PropFieldValue>;
+    /** Called when a control changes. Wire to `editor.setProp`/`setExpression`. */
     onChange: (name: string, value: string | number | boolean) => void;
     className?: string;
 }
+/**
+ * A headless inspector renderer: builds a control per {@link PropSchemaField}
+ * (text / number / checkbox / select / expression) so you don't hand-write a
+ * form per block. Style via `className` and your own CSS; wire `onChange` to the
+ * editor's mutation methods.
+ */
 declare function PropFields({ fields, values, onChange, className, }: PropFieldsProps): ReactNode;
 
-export { DEFAULT_CANVAS_CSS, EditorFrame, IframeCanvas, PropFields, templateIdFromElement, useCanvasWindow, useEditorRevision, useStructureRevision };
-export type { CanvasWindow, IframeCanvasProps, PropFieldValue, PropFieldsProps, Rect };
+export { DEFAULT_CANVAS_CSS, EditorFrame, IframeCanvas, PropFields, RemoteCanvasHost, templateIdFromElement, useCanvasWindow, useEditorRevision, useStructureRevision };
+export type { CanvasWindow, IframeCanvasProps, PropFieldValue, PropFieldsProps, Rect, RemoteCanvasHostProps };