@grafloria/element 0.3.20 → 0.3.21

package/src/libs/renderer/src/vnode/foreign-object.js

@@ -1,167 +0,0 @@
-"use strict";
-/**
- * foreignObject VNode Helpers
- *
- * Provides utility functions for creating and working with SVG foreignObject elements.
- * foreignObject allows embedding HTML content inside SVG, enabling rich components
- * like tables, charts, and forms within diagram nodes.
- *
- * @remarks
- * - foreignObject VNodes have type='foreignObject'
- * - Each foreignObject must have a unique containerId for Angular to target
- * - Default children include an XHTML div wrapper for proper rendering
- *
- * @example
- * ```typescript
- * // Create a foreignObject VNode
- * const vnode = createForeignObject({
- *   nodeId: 'node-1',
- *   x: 10,
- *   y: 20,
- *   width: 200,
- *   height: 150
- * });
- *
- * // Check if a VNode is a foreignObject
- * if (isForeignObject(vnode)) {
- *   const containerId = getContainerId(vnode);
- *   // Render Angular component to containerId...
- * }
- * ```
- *
- * @packageDocumentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createForeignObject = createForeignObject;
-exports.isForeignObject = isForeignObject;
-exports.getContainerId = getContainerId;
-const container_id_generator_1 = require("./container-id-generator");
-/**
- * Create a foreignObject VNode
- *
- * Creates a VNode representing an SVG foreignObject element, which allows
- * embedding HTML content inside SVG. Automatically generates a container ID
- * if not provided, and includes a default XHTML div wrapper.
- *
- * @param options - Configuration options for the foreignObject
- * @returns A VNode of type 'foreignObject'
- *
- * @example
- * ```typescript
- * const vnode = createForeignObject({
- *   nodeId: 'node-1',
- *   x: 10,
- *   y: 20,
- *   width: 200,
- *   height: 150
- * });
- * // Returns: { type: 'foreignObject', props: { x: 10, y: 20, ... }, children: [...] }
- * ```
- *
- * @example With custom container ID and children
- * ```typescript
- * const vnode = createForeignObject({
- *   nodeId: 'node-1',
- *   x: 10,
- *   y: 20,
- *   width: 200,
- *   height: 150,
- *   containerId: 'my-custom-id',
- *   children: [
- *     { type: 'div', props: { className: 'custom-content' } }
- *   ]
- * });
- * ```
- */
-function createForeignObject(options) {
-    const { nodeId, x, y, width, height, containerId, children, key } = options;
-    // Auto-generate container ID if not provided
-    const finalContainerId = containerId || container_id_generator_1.ContainerIdGenerator.generate(nodeId);
-    // Create default XHTML wrapper if no children provided
-    const defaultChildren = [
-        {
-            type: 'div',
-            props: {
-                xmlns: 'http://www.w3.org/1999/xhtml',
-                style: {
-                    width: '100%',
-                    height: '100%',
-                    overflow: 'hidden'
-                }
-            },
-            children: []
-        }
-    ];
-    const vnode = {
-        type: 'foreignObject',
-        props: {
-            x,
-            y,
-            width,
-            height,
-            containerId: finalContainerId
-        },
-        children: children || defaultChildren
-    };
-    // Only add key if provided
-    if (key !== undefined) {
-        vnode.key = key;
-    }
-    return vnode;
-}
-/**
- * Check if a VNode is a foreignObject element
- *
- * Type guard function that checks if the given VNode represents
- * a foreignObject element.
- *
- * @param vnode - The VNode to check
- * @returns True if the VNode is a foreignObject, false otherwise
- *
- * @example
- * ```typescript
- * const foNode = createForeignObject({ ... });
- * const rectNode = { type: 'rect', props: { ... } };
- *
- * isForeignObject(foNode);   // true
- * isForeignObject(rectNode); // false
- * ```
- */
-function isForeignObject(vnode) {
-    return vnode.type === 'foreignObject';
-}
-/**
- * Get the container ID from a foreignObject VNode
- *
- * Extracts the container ID from a foreignObject VNode's props.
- * Returns undefined if the VNode is not a foreignObject or doesn't have a container ID.
- *
- * @param vnode - The VNode to extract the container ID from
- * @returns The container ID if the VNode is a foreignObject, undefined otherwise
- *
- * @example
- * ```typescript
- * const vnode = createForeignObject({
- *   nodeId: 'node-1',
- *   x: 0, y: 0, width: 100, height: 100
- * });
- *
- * const containerId = getContainerId(vnode);
- * // Returns: 'fo-node-1-1'
- * ```
- *
- * @example Non-foreignObject returns undefined
- * ```typescript
- * const rectNode = { type: 'rect', props: { ... } };
- * const containerId = getContainerId(rectNode);
- * // Returns: undefined
- * ```
- */
-function getContainerId(vnode) {
-    var _a;
-    if (!isForeignObject(vnode)) {
-        return undefined;
-    }
-    return (_a = vnode.props) === null || _a === void 0 ? void 0 : _a.containerId;
-}
-//# sourceMappingURL=foreign-object.js.map

package/src/libs/renderer/src/vnode/index.d.ts

@@ -1,56 +0,0 @@
-/**
- * @packageDocumentation
- * VNode foreignObject Support Module
- *
- * This module provides utilities for working with SVG foreignObject elements
- * in the VNode system, enabling rich HTML content within diagram nodes.
- *
- * @example Basic Usage
- * ```typescript
- * import { createForeignObject, isForeignObject, getContainerId } from '@grafloria/renderer';
- *
- * // Create a foreignObject VNode
- * const vnode = createForeignObject({
- *   nodeId: 'node-1',
- *   x: 10,
- *   y: 20,
- *   width: 200,
- *   height: 150
- * });
- *
- * // Check if VNode is foreignObject and get container ID
- * if (isForeignObject(vnode)) {
- *   const containerId = getContainerId(vnode);
- *   console.log(containerId); // 'fo-node-1-1'
- * }
- * ```
- *
- * @example Advanced Usage with Custom Container ID
- * ```typescript
- * import { createForeignObject, ContainerIdGenerator } from '@grafloria/renderer';
- *
- * // Generate a custom container ID
- * const customId = ContainerIdGenerator.generate('my-node');
- *
- * const vnode = createForeignObject({
- *   nodeId: 'my-node',
- *   x: 0,
- *   y: 0,
- *   width: 300,
- *   height: 200,
- *   containerId: customId,
- *   children: [
- *     {
- *       type: 'div',
- *       props: {
- *         xmlns: 'http://www.w3.org/1999/xhtml',
- *         className: 'custom-content'
- *       }
- *     }
- *   ]
- * });
- * ```
- */
-export { ContainerIdGenerator } from './container-id-generator';
-export { createForeignObject, isForeignObject, getContainerId, type ForeignObjectOptions } from './foreign-object';
-export { VNodePatcher, defaultPatcher, reconcile, createDomElement, isOpaqueVNode, serializeStyle, camelToKebab, SVG_NS, XHTML_NS, type VNodePatcherOptions, type VNodeChild, type PatchStats, } from './patch';

package/src/libs/renderer/src/vnode/index.js

@@ -1,78 +0,0 @@
-"use strict";
-/**
- * @packageDocumentation
- * VNode foreignObject Support Module
- *
- * This module provides utilities for working with SVG foreignObject elements
- * in the VNode system, enabling rich HTML content within diagram nodes.
- *
- * @example Basic Usage
- * ```typescript
- * import { createForeignObject, isForeignObject, getContainerId } from '@grafloria/renderer';
- *
- * // Create a foreignObject VNode
- * const vnode = createForeignObject({
- *   nodeId: 'node-1',
- *   x: 10,
- *   y: 20,
- *   width: 200,
- *   height: 150
- * });
- *
- * // Check if VNode is foreignObject and get container ID
- * if (isForeignObject(vnode)) {
- *   const containerId = getContainerId(vnode);
- *   console.log(containerId); // 'fo-node-1-1'
- * }
- * ```
- *
- * @example Advanced Usage with Custom Container ID
- * ```typescript
- * import { createForeignObject, ContainerIdGenerator } from '@grafloria/renderer';
- *
- * // Generate a custom container ID
- * const customId = ContainerIdGenerator.generate('my-node');
- *
- * const vnode = createForeignObject({
- *   nodeId: 'my-node',
- *   x: 0,
- *   y: 0,
- *   width: 300,
- *   height: 200,
- *   containerId: customId,
- *   children: [
- *     {
- *       type: 'div',
- *       props: {
- *         xmlns: 'http://www.w3.org/1999/xhtml',
- *         className: 'custom-content'
- *       }
- *     }
- *   ]
- * });
- * ```
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.XHTML_NS = exports.SVG_NS = exports.camelToKebab = exports.serializeStyle = exports.isOpaqueVNode = exports.createDomElement = exports.reconcile = exports.defaultPatcher = exports.VNodePatcher = exports.getContainerId = exports.isForeignObject = exports.createForeignObject = exports.ContainerIdGenerator = void 0;
-// Export ContainerIdGenerator
-var container_id_generator_1 = require("./container-id-generator");
-Object.defineProperty(exports, "ContainerIdGenerator", { enumerable: true, get: function () { return container_id_generator_1.ContainerIdGenerator; } });
-// Export foreignObject helper functions and types
-var foreign_object_1 = require("./foreign-object");
-Object.defineProperty(exports, "createForeignObject", { enumerable: true, get: function () { return foreign_object_1.createForeignObject; } });
-Object.defineProperty(exports, "isForeignObject", { enumerable: true, get: function () { return foreign_object_1.isForeignObject; } });
-Object.defineProperty(exports, "getContainerId", { enumerable: true, get: function () { return foreign_object_1.getContainerId; } });
-// VNode → DOM patcher: the framework-agnostic keyed reconciler that every DOM
-// consumer (Angular VNodeRendererService, e2e harness, headless instances)
-// materializes VNode trees through.
-var patch_1 = require("./patch");
-Object.defineProperty(exports, "VNodePatcher", { enumerable: true, get: function () { return patch_1.VNodePatcher; } });
-Object.defineProperty(exports, "defaultPatcher", { enumerable: true, get: function () { return patch_1.defaultPatcher; } });
-Object.defineProperty(exports, "reconcile", { enumerable: true, get: function () { return patch_1.reconcile; } });
-Object.defineProperty(exports, "createDomElement", { enumerable: true, get: function () { return patch_1.createDomElement; } });
-Object.defineProperty(exports, "isOpaqueVNode", { enumerable: true, get: function () { return patch_1.isOpaqueVNode; } });
-Object.defineProperty(exports, "serializeStyle", { enumerable: true, get: function () { return patch_1.serializeStyle; } });
-Object.defineProperty(exports, "camelToKebab", { enumerable: true, get: function () { return patch_1.camelToKebab; } });
-Object.defineProperty(exports, "SVG_NS", { enumerable: true, get: function () { return patch_1.SVG_NS; } });
-Object.defineProperty(exports, "XHTML_NS", { enumerable: true, get: function () { return patch_1.XHTML_NS; } });
-//# sourceMappingURL=index.js.map

package/src/libs/renderer/src/vnode/patch.d.ts

@@ -1,189 +0,0 @@
-/**
- * VNode → DOM patcher (keyed reconciler)
- *
- * Framework-agnostic. NO Angular / framework imports — this module is the one
- * place that turns a VNode tree into real DOM and keeps it there across frames.
- * `VNodeRendererService` (Angular) and the e2e harness both delegate to it, and
- * a headless instance API can be built on top of it.
- *
- * Why this exists
- * ---------------
- * The previous Angular implementation did `container.innerHTML = ''` and rebuilt
- * the entire DOM every frame. That is not just slow — it *destroys live state*:
- * focus, text selection, in-flight CSS transitions/animations, and any HTML or
- * component content mounted inside a `<foreignObject>` all die on every render.
- *
- * The reconciler below REUSES existing DOM nodes:
- *   - stable identity: same `key` + same `type` → the same DOM element object
- *     survives across renders (assert with `toBe` on the element),
- *   - reorders are moves (`insertBefore`), not re-creations,
- *   - `<foreignObject>` subtrees are treated as OPAQUE: their props are patched
- *     but their children are never touched, so whatever a framework mounted
- *     inside them stays alive.
- *
- * Invariants
- * ----------
- * 1. The patcher owns the children of every element it creates, EXCEPT inside a
- *    `<foreignObject>` (opaque). It therefore relies on `parent.childNodes[i]`
- *    corresponding to `oldChildren[i]` — which holds because every render places
- *    children at their exact index.
- * 2. VNodes are never mutated. The SVG renderer caches and re-serves the *same*
- *    VNode object for clean entities, so a VNode may be shared between frames and
- *    even between containers; per-node DOM refs are held here, not on the VNode.
- * 3. `oldVNode === newVNode` (identity) ⇒ nothing changed ⇒ the whole subtree is
- *    skipped. This is what makes the renderer's VNode cache pay off.
- */
-import type { VNode } from '../types/vnode.types';
-/** SVG namespace — everything outside a foreignObject is created here. */
-export declare const SVG_NS = "http://www.w3.org/2000/svg";
-/** XHTML namespace — foreignObject children are HTML, not SVG. */
-export declare const XHTML_NS = "http://www.w3.org/1999/xhtml";
-/**
- * SVG attributes whose genuinely-camelCase names must be preserved verbatim.
- * camelCase→kebab-case would corrupt them (`gradientUnits` → `gradient-units`),
- * silently breaking the paint-server defs (gradients / patterns / drop shadows).
- *
- * Exported because the headless SVG SERIALIZER (`export/vnode-serializer.ts`) is
- * this patcher's DOM-less sibling and must map a VNode prop to an attribute name
- * exactly the same way — a second copy of this list is a divergence waiting to
- * happen (the two would disagree about `gradientUnits` and only one of the two
- * outputs would break).
- */
-export declare const VERBATIM_ATTRS: Set<string>;
-/** A child slot in a VNode tree. Strings/numbers materialise as text nodes. */
-export type VNodeChild = VNode | string | number | null | undefined;
-/** Options for a patcher instance. */
-export interface VNodePatcherOptions {
-    /**
-     * Document used to create nodes. Defaults to the ambient `globalThis.document`.
-     * Pass one explicitly for headless / SSR / multi-document use.
-     */
-    document?: Document;
-}
-/**
- * Per-reconcile work counters. Reset at the top of every `reconcile()` call.
- * Useful as a cheap regression guard: a steady-state frame should create ~0
- * elements ("no teardown-and-rebuild").
- */
-export interface PatchStats {
-    /** DOM nodes created from scratch. */
-    created: number;
-    /** DOM nodes reused in place (patched, not recreated). */
-    reused: number;
-    /** Reused DOM nodes that had to move to a new sibling index. */
-    moved: number;
-    /** DOM nodes removed because their VNode disappeared. */
-    removed: number;
-    /** Subtrees skipped entirely because the VNode object was identical. */
-    skipped: number;
-}
-/** camelCase → kebab-case (`strokeWidth` → `stroke-width`). */
-export declare function camelToKebab(str: string): string;
-/**
- * The attribute name a VNode prop is written to: `className` → `class`,
- * `gradientUnits` → `gradientUnits` (verbatim), everything else kebab-cased.
- *
- * THE single mapping, shared by the DOM patcher and the headless serializer.
- */
-export declare function attrNameForProp(key: string): string;
-/**
- * Serialize a style prop. Accepts the object form the renderer emits
- * (`{ cursor: 'move' }`) as well as a plain string.
- * Returns '' for empty/absent styles.
- */
-export declare function serializeStyle(style: unknown): string;
-/**
- * foreignObject subtrees embed live HTML (framework components, form controls,
- * media). They are OPAQUE to the diff: props are patched, children are left
- * exactly as they are. Diffing into them would wipe whatever was mounted there.
- */
-export declare function isOpaqueVNode(vnode: VNode): boolean;
-/**
- * Keyed VNode → DOM reconciler.
- *
- * ```ts
- * const patcher = new VNodePatcher();
- * patcher.reconcile(container, vnodeTree);   // first call: mount
- * patcher.reconcile(container, nextTree);    // later calls: diff + patch in place
- * ```
- */
-export declare class VNodePatcher {
-    /** container → {last vnode tree, root DOM element} */
-    private readonly mounts;
-    private readonly options;
-    private doc?;
-    private _stats;
-    constructor(options?: VNodePatcherOptions);
-    /** Work done during the most recent `reconcile()` call. */
-    get stats(): Readonly<PatchStats>;
-    /**
-     * Diff `vnode` against whatever this patcher last rendered into `container`
-     * and patch the existing DOM in place. First call (or a lost root) mounts a
-     * fresh tree.
-     *
-     * @returns the root DOM element representing `vnode`
-     */
-    reconcile(container: Element, vnode: VNode): Element;
-    /**
-     * ADOPT the DOM already inside `container` as the materialization of `vnode`,
-     * without creating, moving or removing a single node.
-     *
-     * This is the client half of SSR hydration (Card 6). The server emitted the
-     * serialization of this exact VNode tree into the HTML; re-mounting it would
-     * mean tearing that DOM down and rebuilding it — the "hydration flash" every
-     * flow library ships with. Instead we simply register the existing root as our
-     * mount, so the NEXT `reconcile()` diffs against `vnode` and touches only what
-     * genuinely changed.
-     *
-     * The adopt is only taken when the existing root plausibly IS this tree (same
-     * tag name); otherwise we fall back to a normal mount, which is always correct
-     * (just not flash-free). Assert with `stats`: a real hydration reports
-     * `created: 0, removed: 0`.
-     *
-     * @returns the adopted (or freshly mounted) root element.
-     */
-    hydrate(container: Element, vnode: VNode): Element;
-    /** The root element currently mounted in `container`, if any. */
-    getMountedElement(container: Element): Element | undefined;
-    /** Remove the mounted tree and forget the container. */
-    unmount(container: Element): void;
-    /** Build a fresh detached DOM element (deep) for a VNode. */
-    createElement(vnode: VNode, namespace?: string): Element;
-    /**
-     * Diff two VNodes onto an existing element.
-     *
-     * @returns the element representing `newVNode` — the SAME object when it could
-     * be reused, a fresh one when type/key changed (in which case it has already
-     * replaced `el` in the DOM, if `el` was attached).
-     */
-    patchElement(el: Element, oldVNode: VNode, newVNode: VNode): Element;
-    /** Apply a prop delta to an element (no children touched). */
-    patchProps(el: Element, oldProps: Record<string, any>, newProps: Record<string, any>): void;
-    private get document();
-    private createChild;
-    /**
-     * Keyed child reconciliation with an index-based fallback.
-     *
-     * Structural VNodes (nodes, links, ports, layers, foreignObjects, labels,
-     * handles) carry stable keys; leaf primitives inside a node group (shape,
-     * shadow, selection highlight, text) usually do not — so a child list is
-     * routinely a MIX of keyed and keyless children. Keyed children are matched by
-     * key (and moved with insertBefore when their order changes); keyless children
-     * are matched positionally against the remaining unclaimed keyless children.
-     */
-    private patchChildren;
-    /** Patch one child slot (element or text). */
-    private patchChild;
-    private applyProps;
-    private setProp;
-    private removeProp;
-}
-/**
- * Process-wide default patcher — convenient for the common "one DOM, one tree"
- * case. Instantiate `VNodePatcher` directly for isolated instances.
- */
-export declare const defaultPatcher: VNodePatcher;
-/** Reconcile `vnode` into `container` using the default patcher. */
-export declare function reconcile(container: Element, vnode: VNode): Element;
-/** Build a fresh detached DOM tree for `vnode` using the default patcher. */
-export declare function createDomElement(vnode: VNode, namespace?: string): Element;