@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/templates/NodeTemplate.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Node Template System - Type Definitions
+ *
+ * Provides declarative, JSON-driven node creation with support for:
+ * - Hierarchical node structures (parent/children)
+ * - Flexible port configuration
+ * - HTML and SVG rendering modes
+ * - Data binding and repeaters
+ * - Layout management (flexbox/grid)
+ */
+import type { ValidationResult } from '../types/model.types';
+import type { ConnectionValidator } from '../state/ConnectionStateManager';
+import type { PortGroupDefinition, PortLabelSpec, PortShapeSpec } from '../ports/port-types';
+import type { LayoutConfig } from '../types/layout.types';
+/**
+ * Port rendering mode
+ */
+export type PortRenderingMode = 'svg' | 'html' | 'auto';
+/**
+ * Port visibility strategy
+ */
+export type PortVisibility = 'always' | 'on-hover' | 'never';
+/**
+ * Flexbox direction
+ */
+export type FlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
+/**
+ * Node role in hierarchy
+ */
+export type NodeRole = 'container' | 'drag-handler' | 'content' | 'repeater';
+/**
+ * Shape type for SVG rendering.
+ *
+ * The five originals (rect/circle/ellipse/diamond/hexagon) plus the extended
+ * flowchart / BPMN / UML / ERD figure library. Every value here has a matching
+ * ShapeDefinition in the renderer's shape registry (libs/renderer/src/svg/
+ * shape-registry.ts); adding a shape means: register its geometry there and add
+ * its name here. A few widely-used aliases (database, stadium, data …) are
+ * included so callers can type the vocabulary they already know.
+ */
+export type ShapeType = 'rect' | 'circle' | 'ellipse' | 'diamond' | 'hexagon' | 'parallelogram' | 'parallelogram-top' | 'trapezoid' | 'trapezoid-bottom' | 'triangle' | 'triangle-down' | 'package' | 'cube' | 'document' | 'cylinder' | 'cloud' | 'predefined-process' | 'component' | 'note' | 'terminal' | 'actor' | 'delay' | 'display' | 'summing-junction' | 'or-junction' | 'sync-bar' | 'double-rect' | 'double-diamond' | 'double-ellipse' | 'gateway-xor' | 'gateway-or' | 'gateway-and' | 'event-intermediate' | 'final-node' | 'database' | 'stadium' | 'data' | 'subroutine' | 'folder';
+/**
+ * Shape configuration for SVG node rendering (Phase 3.1)
+ * Defines the geometric shape of the node in the SVG layer
+ */
+export interface ShapeConfig {
+    /**
+     * Shape type
+     */
+    type: ShapeType;
+    /**
+     * Fill color (CSS color)
+     */
+    fill?: string;
+    /**
+     * Stroke color (CSS color)
+     */
+    stroke?: string;
+    /**
+     * Stroke width in pixels
+     */
+    strokeWidth?: number;
+    /**
+     * Corner radius for rectangles (in pixels)
+     */
+    cornerRadius?: number;
+    /**
+     * Opacity (0-1)
+     */
+    opacity?: number;
+}
+/**
+ * Port configuration for a specific side
+ */
+export interface PortConfig {
+    enabled: boolean;
+    visibility?: PortVisibility;
+    type?: 'input' | 'output' | 'bi';
+    maxConnections?: number;
+}
+/**
+ * Port rendering configuration
+ */
+export interface PortRenderingConfig {
+    /**
+     * Rendering mode: 'svg', 'html', or 'auto'
+     */
+    mode: PortRenderingMode;
+    /**
+     * Port size
+     */
+    size?: {
+        width: number;
+        height: number;
+        hoverScale?: number;
+    };
+    /**
+     * HTML-specific configuration
+     */
+    html?: {
+        component?: string;
+        className?: string | string[];
+        style?: Record<string, any>;
+        zIndex?: number;
+    };
+    /**
+     * SVG-specific configuration
+     */
+    svg?: {
+        shape?: 'circle' | 'rect' | 'custom';
+        fill?: string;
+        stroke?: string;
+        strokeWidth?: number;
+    };
+    /**
+     * Visibility configuration
+     */
+    visibility?: {
+        default?: PortVisibility;
+        showOnNodeHover?: boolean;
+        showOnNodeSelected?: boolean;
+    };
+}
+/**
+ * Drag handler configuration
+ */
+export interface DragHandlerConfig {
+    isDragHandler: boolean;
+    dragChildren?: boolean;
+    snapToGrid?: boolean;
+    gridSize?: number;
+}
+/**
+ * Ports configuration
+ */
+/**
+ * Wave 6 (Card 3): one member of a named port group. It declares its id and
+ * ONLY the fields that differ from the group — side, shape, label config,
+ * gating and data type all inherit.
+ */
+export interface PortGroupMemberSpec {
+    id: string;
+    index?: number;
+    type?: 'input' | 'output' | 'bi';
+    side?: 'left' | 'right' | 'top' | 'bottom';
+    label?: PortLabelSpec;
+    shape?: PortShapeSpec;
+    dataType?: string;
+    style?: Record<string, unknown>;
+}
+/**
+ * A named port group on a template, plus its members.
+ *
+ * This is what replaces the four `top`/`right`/`bottom`/`left` slots below —
+ * those could say "there is a port on the left" and nothing more, so the shape
+ * every real node editor needs ("eight typed, labelled inputs down the left
+ * edge, each capped at one incoming link") was simply not expressible.
+ */
+export interface PortGroupSpec extends PortGroupDefinition {
+    ports?: PortGroupMemberSpec[];
+}
+export interface PortsConfig {
+    enabled?: boolean;
+    defaultVisibility?: PortVisibility;
+    rendering?: PortRenderingConfig;
+    /** Wave 6 (Card 3). When present, the four side slots below are not consulted. */
+    groups?: PortGroupSpec[];
+    top?: PortConfig;
+    right?: PortConfig;
+    bottom?: PortConfig;
+    left?: PortConfig;
+}
+/**
+ * HTML rendering configuration
+ * Phase 3.4: Enhanced to support LemonadeJS templates for framework-agnostic rendering
+ */
+export interface HtmlConfig {
+    /**
+     * Rendering mode
+     * - 'component': Reference to a framework-specific component (Angular, React, etc.)
+     * - 'template': LemonadeJS template string (framework-agnostic)
+     */
+    mode?: 'component' | 'template';
+    /**
+     * Component reference (for mode='component')
+     * Used when integrating with framework-specific components
+     */
+    component?: string;
+    /**
+     * LemonadeJS template string (for mode='template')
+     * HTML string with LemonadeJS binding syntax
+     * Example: '<div>{{data.name}}</div>'
+     *
+     * Phase 3.4: Framework-agnostic HTML templates
+     */
+    template?: string;
+    /**
+     * CSS classes to apply
+     */
+    className?: string | string[];
+    /**
+     * Inline styles
+     */
+    style?: Record<string, any>;
+    /**
+     * Data bindings (property mappings)
+     * Maps template variables to node data paths
+     * Example: { userName: 'data.user.name', count: 'data.items.length' }
+     */
+    bindings?: Record<string, string>;
+    /**
+     * Event handlers
+     * Maps DOM events to engine event names
+     * Example: { click: 'node:clicked', input: 'node:valueChanged' }
+     *
+     * Phase 3.4: Events are emitted through the engine's EventBus
+     * Handler signature: (nodeId: string, eventData: any) => void
+     */
+    events?: Record<string, string>;
+    /**
+     * Z-index for HTML layer positioning
+     */
+    zIndex?: number;
+    /**
+     * Whether to enable pointer events
+     * If false, the HTML layer won't capture mouse events (pass-through to SVG)
+     */
+    pointerEvents?: boolean;
+}
+/**
+ * Data binding configuration
+ */
+export interface DataBindConfig {
+    bindings?: Record<string, string>;
+    condition?: string;
+}
+/**
+ * Repeater configuration for dynamic children
+ */
+export interface RepeaterConfig {
+    dataSource: string;
+    itemTemplate: NodeStructureDefinition;
+    keyField?: string;
+}
+/**
+ * Node structure definition (recursive)
+ */
+export interface NodeStructureDefinition {
+    type: string;
+    role?: NodeRole;
+    size?: {
+        width?: number | string;
+        height?: number | string;
+        minWidth?: number;
+        maxWidth?: number;
+        minHeight?: number;
+        maxHeight?: number;
+    };
+    /**
+     * Shape configuration for SVG rendering (Phase 3.1)
+     * Defines the geometric shape of the node
+     * If not specified, defaults to rectangle
+     */
+    shape?: ShapeConfig;
+    /**
+     * Where the node's caption paints. `'inside'` (default) centres it in the
+     * shape's inner rect; `'below'` paints it centred UNDER the silhouette — the
+     * Visio/BPMN convention for glyph-sized masters (event circles, gateway
+     * diamonds, connectors, fork/join bars) whose caption cannot fit inside.
+     * Carried to the node as `metadata.labelPlacement`; the renderer consumes it.
+     */
+    labelPlacement?: 'inside' | 'below';
+    layout?: LayoutConfig;
+    ports?: PortsConfig;
+    behavior?: {
+        draggable?: boolean;
+        dragHandler?: DragHandlerConfig;
+        selectable?: boolean;
+        connectable?: boolean;
+        resizable?: boolean;
+        deletable?: boolean;
+    };
+    connectionGroup?: string;
+    connectionRestrictions?: {
+        allowedGroups?: string[];
+        disallowedGroups?: string[];
+        customValidatorId?: string;
+    };
+    html?: HtmlConfig;
+    dataBind?: DataBindConfig;
+    className?: string;
+    style?: Record<string, any>;
+    children?: NodeStructureDefinition[];
+    repeater?: RepeaterConfig;
+}
+/**
+ * Template metadata
+ */
+export interface TemplateMetadata {
+    name: string;
+    description?: string;
+    category: string;
+    icon?: string;
+    preview?: string;
+    tags?: string[];
+    author?: string;
+    license?: string;
+}
+/**
+ * Node template definition
+ */
+export interface NodeTemplate {
+    /**
+     * Unique template identifier
+     */
+    id: string;
+    /**
+     * Template version (semver)
+     */
+    version: string;
+    /**
+     * Template metadata
+     */
+    meta: TemplateMetadata;
+    /**
+     * Root node structure
+     */
+    structure: NodeStructureDefinition;
+    /**
+     * Data schema for validation (JSON Schema)
+     */
+    dataSchema?: Record<string, any>;
+    /**
+     * Default data values
+     */
+    defaultData?: Record<string, any>;
+    /**
+     * Style presets
+     */
+    styles?: Record<string, any>;
+}
+export type { ValidationResult, ConnectionValidator };

package/src/libs/engine/src/templates/NodeTemplate.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Node Template System - Type Definitions
+ *
+ * Provides declarative, JSON-driven node creation with support for:
+ * - Hierarchical node structures (parent/children)
+ * - Flexible port configuration
+ * - HTML and SVG rendering modes
+ * - Data binding and repeaters
+ * - Layout management (flexbox/grid)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=NodeTemplate.js.map

package/src/libs/engine/src/templates/TemplateLoader.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TemplateLoader - Utility for loading/exporting templates
+ *
+ * Handles:
+ * - JSON string parsing
+ * - Object validation
+ * - Array loading
+ * - Export to JSON
+ */
+import { NodeTemplate } from './NodeTemplate';
+export declare class TemplateLoader {
+    /**
+     * Load template from JSON string
+     * @throws Error if JSON is invalid or template is invalid
+     */
+    static fromJSON(json: string): NodeTemplate;
+    /**
+     * Load template from object
+     * @throws Error if template is invalid
+     */
+    static fromObject(obj: any): NodeTemplate;
+    /**
+     * Load multiple templates from JSON array
+     * @throws Error if JSON is invalid or not an array
+     */
+    static fromJSONArray(json: string): NodeTemplate[];
+    /**
+     * Export template to JSON string
+     * @param template Template to export
+     * @param pretty Pretty print with indentation (default: true)
+     * @returns JSON string
+     */
+    static toJSON(template: NodeTemplate, pretty?: boolean): string;
+    /**
+     * Export multiple templates to JSON array
+     * @param templates Templates to export
+     * @param pretty Pretty print with indentation (default: true)
+     * @returns JSON string
+     */
+    static toJSONArray(templates: NodeTemplate[], pretty?: boolean): string;
+    /**
+     * Validate template structure
+     * @throws Error if template is invalid
+     */
+    private static validateTemplate;
+}

package/src/libs/engine/src/templates/TemplateLoader.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * TemplateLoader - Utility for loading/exporting templates
+ *
+ * Handles:
+ * - JSON string parsing
+ * - Object validation
+ * - Array loading
+ * - Export to JSON
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateLoader = void 0;
+class TemplateLoader {
+    /**
+     * Load template from JSON string
+     * @throws Error if JSON is invalid or template is invalid
+     */
+    static fromJSON(json) {
+        try {
+            const template = JSON.parse(json);
+            this.validateTemplate(template);
+            return template;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to parse template JSON: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Load template from object
+     * @throws Error if template is invalid
+     */
+    static fromObject(obj) {
+        this.validateTemplate(obj);
+        return obj;
+    }
+    /**
+     * Load multiple templates from JSON array
+     * @throws Error if JSON is invalid or not an array
+     */
+    static fromJSONArray(json) {
+        try {
+            const data = JSON.parse(json);
+            if (!Array.isArray(data)) {
+                throw new Error('Expected array of templates');
+            }
+            return data.map(item => this.fromObject(item));
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to parse templates JSON: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Export template to JSON string
+     * @param template Template to export
+     * @param pretty Pretty print with indentation (default: true)
+     * @returns JSON string
+     */
+    static toJSON(template, pretty = true) {
+        return pretty
+            ? JSON.stringify(template, null, 2)
+            : JSON.stringify(template);
+    }
+    /**
+     * Export multiple templates to JSON array
+     * @param templates Templates to export
+     * @param pretty Pretty print with indentation (default: true)
+     * @returns JSON string
+     */
+    static toJSONArray(templates, pretty = true) {
+        return pretty
+            ? JSON.stringify(templates, null, 2)
+            : JSON.stringify(templates);
+    }
+    /**
+     * Validate template structure
+     * @throws Error if template is invalid
+     */
+    static validateTemplate(template) {
+        if (!template) {
+            throw new Error('Template is null or undefined');
+        }
+        if (!template.id) {
+            throw new Error('Template must have an id');
+        }
+        if (!template.version) {
+            throw new Error('Template must have a version');
+        }
+        if (!template.meta) {
+            throw new Error('Template must have meta information');
+        }
+        if (!template.structure) {
+            throw new Error('Template must have a structure definition');
+        }
+        // Validate meta fields
+        if (!template.meta.name) {
+            throw new Error('Template meta must have a name');
+        }
+        if (!template.meta.category) {
+            throw new Error('Template meta must have a category');
+        }
+        // Validate structure
+        if (!template.structure.type) {
+            throw new Error('Template structure must have a type');
+        }
+    }
+}
+exports.TemplateLoader = TemplateLoader;
+//# sourceMappingURL=TemplateLoader.js.map

package/src/libs/engine/src/templates/TemplateRegistry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * TemplateRegistry - Central registry for node templates
+ *
+ * Manages:
+ * - Template registration and lookup
+ * - Category and tag-based search
+ * - Connection validator registry
+ * - Event notifications
+ */
+import { NodeTemplate, ConnectionValidator } from './NodeTemplate';
+import { EventBus } from '../events/EventBus';
+export declare class TemplateRegistry {
+    private eventBus;
+    private templates;
+    private validators;
+    constructor(eventBus: EventBus);
+    /**
+     * Register a template
+     */
+    register(template: NodeTemplate): void;
+    /**
+     * Register multiple templates
+     */
+    registerMany(templates: NodeTemplate[]): void;
+    /**
+     * Unregister a template
+     * @returns true if template was removed, false if it didn't exist
+     */
+    unregister(templateId: string): boolean;
+    /**
+     * Get template by ID
+     */
+    get(id: string): NodeTemplate | undefined;
+    /**
+     * Get all registered templates
+     */
+    getAll(): NodeTemplate[];
+    /**
+     * Get templates by category
+     */
+    getByCategory(category: string): NodeTemplate[];
+    /**
+     * Search templates by name, description, or tags
+     */
+    search(query: string): NodeTemplate[];
+    /**
+     * Get all unique categories (sorted)
+     */
+    getCategories(): string[];
+    /**
+     * Check if template exists
+     */
+    has(templateId: string): boolean;
+    /**
+     * Get template count
+     */
+    count(): number;
+    /**
+     * Clear all templates
+     */
+    clear(): void;
+    /**
+     * Register custom connection validator
+     */
+    registerValidator(id: string, validator: ConnectionValidator): void;
+    /**
+     * Get connection validator
+     */
+    getValidator(id: string): ConnectionValidator | undefined;
+}