@grafloria/element 0.3.17 → 0.3.19

package/src/libs/renderer/src/ssr/render-to-static.d.ts

@@ -0,0 +1,91 @@
+import type { Theme } from '../types/theme.types';
+import type { EdgeSpec, NodeSpec } from '../instance/model-input';
+/**
+ * Card 6 — the deterministic SERVER path.
+ *
+ * `renderToStaticSVG()` runs the real `DiagramEngine` + the real `SVGRenderer`
+ * in Node, with no DOM anywhere, and returns:
+ *
+ *   - `html`     — the exact markup `createDiagram()` would have mounted,
+ *   - `svg`      — just the `<svg>` (for an `<img>`, an email, a README),
+ *   - `snapshot` — the four values the client must reuse to reproduce the same
+ *                  VNode tree byte-for-byte: instance scope, canvas size, camera
+ *                  origin and zoom.
+ *
+ * Hand the snapshot back to `createDiagram(el, { hydrate: snapshot })` and the
+ * client rebuilds the same model, renders the same VNodes, and ADOPTS the DOM
+ * that is already on the page — no re-creation, no flash, no re-layout. The
+ * competitors either punt on SSR entirely (React Flow is `'use client'`-only) or
+ * server-render something that can never become interactive (Mermaid).
+ *
+ * ## What makes it deterministic
+ *
+ * - ids: `node-<i>` / `edge-<i>` when the spec omits them (never a nanoid);
+ * - ports: rewritten to `<nodeId>__<side>` (the engine's auto-ports are nanoids
+ *   and the renderer emits them as VNode keys) — see `instance/model-input.ts`;
+ * - instance scope: `instanceId` is fixed here and echoed in the snapshot,
+ *   because the renderer's fallback counter restarts in every process;
+ * - camera: the snapshot carries width/height/zoom/origin, so the client's
+ *   `viewBox` is identical even before it has measured the container.
+ *
+ * ## Scope (stated plainly)
+ *
+ * Custom / HTML-layer nodes are NOT server-rendered: they are framework
+ * components, and the server has no framework. They mount on hydration, inside
+ * the (empty, correctly-transformed) HTML layer this emits. Everything the SVG
+ * renderer draws — nodes, ports, edges, labels, arrows, routing — IS in the
+ * snapshot, which is the part that would otherwise re-layout.
+ */
+export interface StaticRenderOptions {
+    nodes?: NodeSpec[];
+    edges?: EdgeSpec[];
+    theme?: Theme;
+    /** Canvas width in CSS px. Default 800. */
+    width?: number;
+    /** Canvas height in CSS px. Default 600. */
+    height?: number;
+    zoom?: number;
+    /** Camera origin in world coordinates. Default (0, 0). */
+    viewport?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * CSS scope for this diagram. Default `'grafloria-ssr'`. Give each diagram on a
+     * page its own id if you server-render more than one.
+     */
+    instanceId?: string;
+    /** Frame the content instead of using `viewport`/`zoom`. Default false. */
+    fitView?: boolean;
+    /** Padding (CSS px) for `fitView`. Default 40. */
+    fitPadding?: number;
+    /** Add `xmlns` to the `<svg>` so it stands alone as a file. Default false. */
+    standalone?: boolean;
+}
+/** Everything the client needs to reproduce this render exactly. */
+export interface HydrationSnapshot {
+    instanceId: string;
+    width: number;
+    height: number;
+    zoom: number;
+    viewport: {
+        x: number;
+        y: number;
+    };
+}
+export interface StaticRenderResult {
+    /** The full layer skeleton — drop this straight into your container. */
+    html: string;
+    /** Only the `<svg>` element. */
+    svg: string;
+    /**
+     * The stylesheet the diagram needs. In CSS mode the theme is expressed purely
+     * as `--grafloria-*` variables, so the SVG above is theme-INDEPENDENT (which is
+     * what makes hydration a no-op) — but it is also unstyled until this CSS is on
+     * the page. Ship it in a `<style>` tag; the client re-injects identical content
+     * under the same ids, so nothing repaints.
+     */
+    css: string;
+    snapshot: HydrationSnapshot;
+}
+export declare function renderToStaticSVG(options?: StaticRenderOptions): StaticRenderResult;

package/src/libs/renderer/src/ssr/render-to-static.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderToStaticSVG = renderToStaticSVG;
+const engine_1 = require("@grafloria/engine");
+const svg_renderer_1 = require("../svg/svg-renderer");
+const viewport_controller_1 = require("../viewport/viewport-controller");
+const model_input_1 = require("../instance/model-input");
+const layers_1 = require("../instance/layers");
+const vnode_serializer_1 = require("../export/vnode-serializer");
+function renderToStaticSVG(options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+    const width = (_a = options.width) !== null && _a !== void 0 ? _a : 800;
+    const height = (_b = options.height) !== null && _b !== void 0 ? _b : 600;
+    const instanceId = (_c = options.instanceId) !== null && _c !== void 0 ? _c : 'grafloria-ssr';
+    const engine = new engine_1.DiagramEngine();
+    const model = engine.createDiagram('grafloria-ssr');
+    (0, model_input_1.applyNodes)(model, (_d = options.nodes) !== null && _d !== void 0 ? _d : []);
+    (0, model_input_1.applyEdges)(model, (_e = options.edges) !== null && _e !== void 0 ? _e : []);
+    const viewport = new viewport_controller_1.ViewportController({
+        viewport: {
+            x: (_g = (_f = options.viewport) === null || _f === void 0 ? void 0 : _f.x) !== null && _g !== void 0 ? _g : 0,
+            y: (_j = (_h = options.viewport) === null || _h === void 0 ? void 0 : _h.y) !== null && _j !== void 0 ? _j : 0,
+            width,
+            height,
+        },
+        zoom: (_k = options.zoom) !== null && _k !== void 0 ? _k : 1,
+    });
+    if (options.fitView) {
+        const bounds = contentBoundsOf(model);
+        if (bounds)
+            viewport.fitToBounds(bounds, (_l = options.fitPadding) !== null && _l !== void 0 ? _l : 40);
+    }
+    // `useCSSMode` stays ON: the renderer's document access is now guarded
+    // (see SVGRenderer.injectThemeCSS), so the VNode tree the server produces is
+    // the SAME tree the browser produces — which is the whole point.
+    const renderer = new svg_renderer_1.SVGRenderer(engine, { instanceId }, options.theme);
+    const vnode = renderer.render(viewport.getRenderViewport(), viewport.getZoom());
+    // A static artifact must SIZE ITSELF: the live path leaves width/height to the
+    // host's CSS, but an email, a README or a bare <img> cannot add CSS — without
+    // these the svg renders 0×0 (the audit's "blank page with a stray dot").
+    vnode.props = Object.assign(Object.assign({}, vnode.props), { width: (_m = options.width) !== null && _m !== void 0 ? _m : 800, height: (_o = options.height) !== null && _o !== void 0 ? _o : 600 });
+    // ONE serializer, in DOM fidelity: the snapshot must describe exactly the DOM the
+    // client's VNodePatcher would build, or hydration rebuilds the tree and flashes.
+    // (The same function in 'file' fidelity is what `export/` uses for standalone SVG.)
+    const svg = (0, vnode_serializer_1.serializeVNode)(vnode, { fidelity: 'dom', standalone: options.standalone });
+    const css = renderer.getStyleSheet();
+    renderer.dispose();
+    engine.destroy();
+    const snapshot = {
+        instanceId,
+        width,
+        height,
+        zoom: viewport.getZoom(),
+        viewport: { x: viewport.getViewport().x, y: viewport.getViewport().y },
+    };
+    return { html: wrapInLayers(svg, instanceId), svg, css, snapshot };
+}
+/** The markup `createDiagram()`'s `ensureLayers()` builds — as a string. */
+function wrapInLayers(svg, instanceId) {
+    return (`<div class="${layers_1.ROOT_CLASS}" style="${layers_1.ROOT_STYLE}" data-grafloria-instance="${instanceId}">` +
+        `<div class="${layers_1.SVG_LAYER_CLASS}" style="${layers_1.SVG_LAYER_STYLE}">${svg}</div>` +
+        `<div class="${layers_1.HTML_LAYER_CLASS}" style="${(0, layers_1.htmlLayerStyle)('translate(0px, 0px) scale(1)')}"></div>` +
+        `</div>`);
+}
+function contentBoundsOf(model) {
+    const nodes = model.getNodes();
+    if (nodes.length === 0)
+        return null;
+    let left = Infinity;
+    let top = Infinity;
+    let right = -Infinity;
+    let bottom = -Infinity;
+    for (const node of nodes) {
+        left = Math.min(left, node.position.x);
+        top = Math.min(top, node.position.y);
+        right = Math.max(right, node.position.x + node.size.width);
+        bottom = Math.max(bottom, node.position.y + node.size.height);
+    }
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+//# sourceMappingURL=render-to-static.js.map

package/src/libs/renderer/src/ssr/render-to-static.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-to-static.js","sourceRoot":"","sources":["../../../../../../renderer/src/ssr/render-to-static.ts"],"names":[],"mappings":"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"}

package/src/libs/renderer/src/svg/ArrowRenderer.d.ts

@@ -0,0 +1,159 @@
+import type { ArrowStyle } from '@grafloria/engine';
+import type { VNode } from '../types/vnode.types';
+/**
+ * ArrowRenderer generates SVG VNodes for different arrow types.
+ *
+ * Supports:
+ * - Basic arrows (arrow, circle, square, diamond)
+ * - ERD arrows (crow-foot, one, zero-or-one, zero-or-many, one-or-many)
+ * - UML arrows (hollow-diamond, filled-diamond, generalization, open-arrow, double-arrow)
+ * - Additional arrows (cross, bar, dot, oval)
+ * - Half-arrowheads (Mermaid 11.13) — `half-arrow-left` / `half-arrow-right`
+ * - AUTHOR-DEFINED markers (Wave 4, Card 5): a raw SVG `path`, or anything
+ *   registered with `registerMarker` — the catalogue is no longer a closed enum.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new ArrowRenderer();
+ * const arrowVNode = renderer.renderArrow({
+ *   type: 'crow-foot',
+ *   size: 10,
+ *   filled: false,
+ *   color: '#000'
+ * }, 'translate(100, 50) rotate(45)');
+ * ```
+ *
+ * @example A custom marker
+ * ```typescript
+ * registerMarker('feather', {
+ *   tipOffset: style => style.size,
+ *   render: ctx => ({ type: 'path', props: { d: `M0,0 L${ctx.size},0`, stroke: ctx.color, transform: ctx.transform } }),
+ * });
+ * link.updateStyle({ arrowHead: { type: 'feather', size: 12, filled: true } });
+ * ```
+ */
+export declare class ArrowRenderer {
+    private readonly defaultColor;
+    private readonly defaultStrokeWidth;
+    /**
+     * Distance from the marker's local origin to its forward-most point (its
+     * visual tip), in the +x direction the marker is rotated toward.
+     *
+     * The renderer positions markers by pulling the transform origin back from
+     * the path endpoint by exactly this amount so every tip lands ON the port —
+     * a uniform offset only fits the triangle family and left circles/diamonds
+     * floating off the node.
+     *
+     * Wave 4 (Card 5): a custom marker declares its own. Precedence is
+     * `style.tipOffset` (explicit) > the registered marker's > 0 (a raw `path`
+     * marker is assumed to be drawn with its tip at the origin).
+     */
+    getTipOffset(style: ArrowStyle): number;
+    /**
+     * Render an arrow based on the provided style and transform
+     *
+     * @param style Arrow style configuration
+     * @param transform SVG transform string
+     * @param backgroundColor Fill for hollow (unfilled) markers — pass the theme
+     *   background so hollow arrows don't glare white on dark themes
+     * @returns VNode representing the arrow, or null if type is 'none'
+     */
+    renderArrow(style: ArrowStyle, transform: string, backgroundColor?: string, end?: 'source' | 'target'): VNode | null;
+    /**
+     * The registered marker this style refers to, if any.
+     *
+     * Two ways to name one, because both read naturally:
+     *   { type: 'custom', marker: 'feather' }   — explicit
+     *   { type: 'feather' }                     — the registered name AS the type
+     *
+     * A registered name never shadows a built-in accidentally: the built-in switch
+     * only runs when nothing is registered under that name.
+     */
+    private resolveMarker;
+    /**
+     * A marker from raw SVG path data (`{ type: 'custom', path: 'M0,0 …' }`).
+     * Drawn in the marker's local frame — origin at the anchor, +x forward.
+     */
+    private renderCustomPath;
+    /**
+     * Half-arrowhead (Mermaid 11.13): one barb of the triangle, on the given side
+     * of the direction of travel. `side` is +1 for the RIGHT barb (screen-down
+     * when travelling right) and -1 for the LEFT one.
+     *
+     * The shaft point (size, 0) is the tip, exactly as for the full triangle, so a
+     * half arrow anchors on the port identically.
+     */
+    private renderHalfArrow;
+    /**
+     * Basic triangle arrow (standard arrowhead)
+     */
+    private renderTriangleArrow;
+    /**
+     * Circle arrow
+     */
+    private renderCircleArrow;
+    /**
+     * Square arrow
+     */
+    private renderSquareArrow;
+    /**
+     * Diamond arrow
+     */
+    private renderDiamondArrow;
+    /**
+     * ERD crow-foot arrow (one-to-many relationship)
+     */
+    private renderCrowFootArrow;
+    /**
+     * ERD one arrow (exactly one - vertical bar)
+     */
+    private renderOneArrow;
+    /**
+     * ERD zero-or-one arrow (circle + bar)
+     */
+    private renderZeroOrOneArrow;
+    /**
+     * ERD zero-or-many arrow (circle + crow-foot)
+     */
+    private renderZeroOrManyArrow;
+    /**
+     * ERD one-or-many arrow (bar + crow-foot)
+     */
+    private renderOneOrManyArrow;
+    /**
+     * UML hollow diamond arrow (aggregation)
+     */
+    private renderHollowDiamondArrow;
+    /**
+     * UML filled diamond arrow (composition)
+     */
+    private renderFilledDiamondArrow;
+    /**
+     * UML generalization arrow (inheritance - hollow triangle)
+     */
+    private renderGeneralizationArrow;
+    /**
+     * UML open arrow (dependency - open triangle)
+     */
+    private renderOpenArrow;
+    /**
+     * UML double arrow (bidirectional)
+     */
+    private renderDoubleArrow;
+    /**
+     * Cross arrow (X mark)
+     */
+    private renderCrossArrow;
+    /**
+     * Bar arrow (perpendicular line)
+     */
+    private renderBarArrow;
+    /**
+     * Dot arrow (simple dot)
+     */
+    private renderDotArrow;
+    /**
+     * Oval arrow
+     */
+    private renderOvalArrow;
+}