@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/config/InteractionConfig.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Interaction modes for node dragging and connection creation
+ */
+export declare enum InteractionMode {
+    /**
+     * Direct Mode: Click+drag body=move immediately, drag port=connect
+     * Fast workflow, industry standard
+     */
+    DIRECT = "direct",
+    /**
+     * Deliberate Mode: Must select node first, then drag to move
+     * Safer workflow, prevents accidental moves
+     */
+    DELIBERATE = "deliberate",
+    /**
+     * Smart Mode (Visio-style): Hover reveals ports, intelligent auto-connect
+     * Ports appear on hover, drop on body connects to nearest port
+     */
+    SMART = "smart"
+}
+/**
+ * Port visibility strategies
+ */
+export declare enum PortVisibilityStrategy {
+    /**
+     * Ports always visible
+     * Best for technical diagrams with few ports
+     */
+    ALWAYS = "always",
+    /**
+     * Ports visible only when hovering over node
+     * Industry standard, reduces visual clutter
+     */
+    ON_HOVER = "on-hover",
+    /**
+     * Ports hidden - drag-to-connect disabled
+     * For diagrams where connections are created programmatically
+     */
+    HIDDEN = "hidden"
+}
+/**
+ * Connection line style for preview
+ */
+export declare enum ConnectionLineStyle {
+    /**
+     * Straight line from port to mouse
+     */
+    STRAIGHT = "straight",
+    /**
+     * Smooth bezier curve
+     */
+    BEZIER = "bezier",
+    /**
+     * Step function (orthogonal)
+     */
+    STEP = "step"
+}
+/**
+ * Interaction configuration
+ */
+export interface InteractionConfig {
+    /**
+     * Interaction mode (direct, deliberate, smart)
+     */
+    mode: InteractionMode;
+    /**
+     * Movement threshold in screen pixels that separates a click from a drag.
+     * A pointer must travel farther than this from its down position before a
+     * gesture is treated as a drag (node move / marquee) rather than a click.
+     * This is what prevents a plain click from micro-jittering a node's position.
+     * Default: 4.
+     */
+    dragThreshold: number;
+    /**
+     * Port visibility strategy
+     */
+    portVisibility: PortVisibilityStrategy;
+    /**
+     * Port hover scale factor (e.g., 1.5 = 50% larger on hover)
+     */
+    portHoverScaleFactor: number;
+    /**
+     * Port default radius in pixels
+     */
+    portDefaultRadius: number;
+    /**
+     * Snap to port radius in pixels
+     * Connection will snap when mouse is within this distance
+     */
+    snapToPortRadius: number;
+    /**
+     * Show connection preview line while dragging
+     */
+    showConnectionPreview: boolean;
+    /**
+     * Connection line style for preview
+     */
+    connectionLineStyle: ConnectionLineStyle;
+    /**
+     * Enable link endpoint reconnection
+     */
+    enableLinkReconnection: boolean;
+    /**
+     * Show endpoint handles on selected links
+     */
+    showLinkEndpointHandles: boolean;
+    /**
+     * Enable smart mode nearest port auto-connect
+     * When enabled, dropping on node body connects to nearest port
+     */
+    enableSmartAutoConnect: boolean;
+    /**
+     * Highlight valid connection targets during drag
+     */
+    highlightValidTargets: boolean;
+    /**
+     * Show animated dots on connection preview
+     */
+    animateConnectionPreview: boolean;
+    /**
+     * Phase 2.3: Enable waypoint editing on links
+     * Allow users to add/move/remove waypoints by clicking/dragging link paths
+     */
+    enableWaypointEditing: boolean;
+    /**
+     * Phase 2.3: Show waypoint handles on selected links
+     */
+    showWaypointHandles: boolean;
+    /**
+     * Phase 2.3: Waypoint editor configuration
+     */
+    waypointEditor?: WaypointEditorConfig;
+    /**
+     * Phase 2.3: Enable control point editing on bezier curves
+     * Allow users to adjust bezier control points by dragging handles
+     */
+    enableControlPointEditing: boolean;
+    /**
+     * Phase 2.3: Show control point handles on selected bezier links
+     */
+    showControlPointHandles: boolean;
+    /**
+     * Phase 2.3: Control point editor configuration
+     */
+    controlPointEditor?: ControlPointEditorConfig;
+    /**
+     * wave12/connect-ergonomics (gap 1) — Drag a group's frame to move the whole
+     * subflow: the container and every member node (recursively through nested
+     * groups) translate by the same delta, committed as ONE undoable step.
+     *
+     * Opt-in (default false) so steady-state is untouched: with it off, a press on
+     * a group's empty frame area still falls through to clear-selection exactly as
+     * before. A press on a MEMBER NODE always drags that node (the node wins the
+     * priority ladder) regardless of this flag.
+     */
+    enableGroupDrag: boolean;
+    /**
+     * wave12/connect-ergonomics (gap 2) — React-Flow "Proximity Connect": after a
+     * node drag, if one of its ports comes within `proximityConnectRadius` of a
+     * compatible port on another node, auto-create the link on drop (one undoable
+     * command). Drives the shipped `SnapController.findProximityConnection` from
+     * the LIVE drag path, not from host glue. Default false (opt-in).
+     */
+    enableProximityConnect: boolean;
+    /**
+     * wave12/connect-ergonomics (gap 2) — Auto-link radius in world units for
+     * {@link enableProximityConnect}. Defaults to `DEFAULT_SNAP_CONFIG`'s value
+     * when unset/0.
+     */
+    proximityConnectRadius: number;
+    /**
+     * wave15/helper-lines — React-Flow "Helper Lines": while dragging a single
+     * top-level node, snap it to sibling edge/centre alignments and equal
+     * spacing, and draw the guides as dashed overlay lines. The SnapController
+     * always could compute this; nothing drove it from a live drag until now.
+     * Default false (opt-in) so the stock drag feel is unchanged.
+     */
+    enableHelperLines: boolean;
+    /**
+     * T8/visio — Visio-style containment: dropping a node inside a container's
+     * frame REPARENTS it (and dropping it outside every container unembeds it),
+     * so it then moves with its container. `GroupMembershipService` always had
+     * the full drop logic — hit-test, per-group `canAddMember` veto, coordinate
+     * translation, undoable Add/RemoveFromGroupCommand — and nothing ever called
+     * it, so a drag into a container only changed x/y. Default false (opt-in),
+     * like every other gesture in this block: turning it on globally changes what
+     * an existing drag MEANS for any host that draws frames decoratively.
+     */
+    enableGroupMembershipOnDrop: boolean;
+    /**
+     * T10/visio — double-click a node to edit its label in place. The editor
+     * (session + undoable commit) shipped in the renderer but was auto-wired ONLY
+     * in the Angular wrapper, so a vanilla / React / Vue embed got a
+     * `node:doubleclick` event and no caret. Default false (opt-in) so a host that
+     * already answers that event with its own editor keeps sole control.
+     */
+    enableInPlaceTextEdit: boolean;
+    /**
+     * visio-depth — arrow keys NUDGE the selected node(s): 1 world unit per
+     * press, ×10 with Shift, committed through MoveNodeCommand so every nudge is
+     * undoable (and successive presses inside the CommandManager's merge window
+     * collapse to one undo entry). The whole computation shipped years ago in
+     * `KeyboardNavigationController.nudgeCommand` — but it was auto-wired only in
+     * the Angular wrapper, so a vanilla/React/Vue embed pressing an arrow moved
+     * nothing (the same built-but-unwired hole `enableInPlaceTextEdit` closed for
+     * double-click rename). Default false (opt-in): arrows may already mean
+     * scroll-the-page to an embedding host.
+     */
+    enableKeyboardNudge: boolean;
+    /**
+     * wave12/connect-ergonomics (gap 3) — React-Flow "Easy Connect": make the
+     * whole node BODY a connection handle. A press on a node body (not over a
+     * specific port) starts a connection from the node's nearest/default port
+     * instead of a move. Default false (opt-in) so normal body-drag-to-move is
+     * preserved; when on, hold no modifier to connect and the configured
+     * {@link easyConnectModifier} (if any) still gates it.
+     */
+    enableEasyConnect: boolean;
+    /**
+     * wave12/connect-ergonomics (gap 3) — Optional modifier that must be held for
+     * an easy-connect body press to start a connection (e.g. 'shift'). When
+     * 'none' (the default) any plain body press connects while {@link
+     * enableEasyConnect} is on. Lets a host keep body-drag-to-move as the default
+     * gesture and gate connect behind a key.
+     */
+    easyConnectModifier: 'none' | 'shift' | 'alt' | 'ctrl' | 'meta';
+}
+/**
+ * Phase 2.3: Waypoint editor configuration
+ */
+export interface WaypointEditorConfig {
+    /**
+     * Snap waypoints to grid
+     */
+    snapToGrid: boolean;
+    /**
+     * Grid size for snapping (in pixels)
+     */
+    gridSize: number;
+    /**
+     * Remove waypoint on double-click
+     */
+    removeOnDoubleClick: boolean;
+    /**
+     * Waypoint handle radius (in pixels)
+     */
+    handleRadius: number;
+    /**
+     * Waypoint handle color
+     */
+    handleColor: string;
+    /**
+     * Waypoint handle stroke color
+     */
+    handleStrokeColor: string;
+    /**
+     * Minimum distance from endpoints to add waypoint (in pixels)
+     */
+    minDistanceFromEndpoints: number;
+    /**
+     * Maximum distance from path to detect click (in pixels)
+     */
+    clickDetectionRadius: number;
+}
+/**
+ * Phase 2.3: Control point editor configuration
+ */
+export interface ControlPointEditorConfig {
+    /**
+     * Snap control points to grid
+     */
+    snapToGrid: boolean;
+    /**
+     * Grid size for snapping (in pixels)
+     */
+    gridSize: number;
+    /**
+     * Control point handle radius (in pixels)
+     */
+    handleRadius: number;
+    /**
+     * Control point handle color
+     */
+    handleColor: string;
+    /**
+     * Control point handle stroke color
+     */
+    handleStrokeColor: string;
+    /**
+     * Control line color (line from anchor to control point)
+     */
+    controlLineColor: string;
+    /**
+     * Control line stroke width
+     */
+    controlLineWidth: number;
+    /**
+     * Control line dash pattern (e.g., [5, 5] for dashed)
+     */
+    controlLineDash: number[];
+    /**
+     * Maximum distance from control handle to detect click (in pixels)
+     */
+    clickDetectionRadius: number;
+    /**
+     * Show control lines connecting anchors to control points
+     */
+    showControlLines: boolean;
+    /**
+     * Auto-generate symmetric control points (mirror on both sides)
+     */
+    symmetricControls: boolean;
+}
+/**
+ * Default interaction configuration
+ * Optimized for modern diagramming workflows
+ */
+export declare const DEFAULT_INTERACTION_CONFIG: InteractionConfig;
+/**
+ * Direct mode preset (fast workflow)
+ */
+export declare const DIRECT_MODE_CONFIG: Partial<InteractionConfig>;
+/**
+ * Deliberate mode preset (safe workflow)
+ */
+export declare const DELIBERATE_MODE_CONFIG: Partial<InteractionConfig>;
+/**
+ * Smart mode preset (Visio-style)
+ */
+export declare const SMART_MODE_CONFIG: Partial<InteractionConfig>;

package/src/libs/engine/src/config/InteractionConfig.js

@@ -0,0 +1,154 @@
+"use strict";
+// InteractionConfig - Configuration for diagram interaction modes
+// This is part of Phase 1: Engine Foundation for interaction modes
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SMART_MODE_CONFIG = exports.DELIBERATE_MODE_CONFIG = exports.DIRECT_MODE_CONFIG = exports.DEFAULT_INTERACTION_CONFIG = exports.ConnectionLineStyle = exports.PortVisibilityStrategy = exports.InteractionMode = void 0;
+/**
+ * Interaction modes for node dragging and connection creation
+ */
+var InteractionMode;
+(function (InteractionMode) {
+    /**
+     * Direct Mode: Click+drag body=move immediately, drag port=connect
+     * Fast workflow, industry standard
+     */
+    InteractionMode["DIRECT"] = "direct";
+    /**
+     * Deliberate Mode: Must select node first, then drag to move
+     * Safer workflow, prevents accidental moves
+     */
+    InteractionMode["DELIBERATE"] = "deliberate";
+    /**
+     * Smart Mode (Visio-style): Hover reveals ports, intelligent auto-connect
+     * Ports appear on hover, drop on body connects to nearest port
+     */
+    InteractionMode["SMART"] = "smart";
+})(InteractionMode || (exports.InteractionMode = InteractionMode = {}));
+/**
+ * Port visibility strategies
+ */
+var PortVisibilityStrategy;
+(function (PortVisibilityStrategy) {
+    /**
+     * Ports always visible
+     * Best for technical diagrams with few ports
+     */
+    PortVisibilityStrategy["ALWAYS"] = "always";
+    /**
+     * Ports visible only when hovering over node
+     * Industry standard, reduces visual clutter
+     */
+    PortVisibilityStrategy["ON_HOVER"] = "on-hover";
+    /**
+     * Ports hidden - drag-to-connect disabled
+     * For diagrams where connections are created programmatically
+     */
+    PortVisibilityStrategy["HIDDEN"] = "hidden";
+})(PortVisibilityStrategy || (exports.PortVisibilityStrategy = PortVisibilityStrategy = {}));
+/**
+ * Connection line style for preview
+ */
+var ConnectionLineStyle;
+(function (ConnectionLineStyle) {
+    /**
+     * Straight line from port to mouse
+     */
+    ConnectionLineStyle["STRAIGHT"] = "straight";
+    /**
+     * Smooth bezier curve
+     */
+    ConnectionLineStyle["BEZIER"] = "bezier";
+    /**
+     * Step function (orthogonal)
+     */
+    ConnectionLineStyle["STEP"] = "step";
+})(ConnectionLineStyle || (exports.ConnectionLineStyle = ConnectionLineStyle = {}));
+/**
+ * Default interaction configuration
+ * Optimized for modern diagramming workflows
+ */
+exports.DEFAULT_INTERACTION_CONFIG = {
+    mode: InteractionMode.SMART,
+    dragThreshold: 4,
+    portVisibility: PortVisibilityStrategy.ON_HOVER,
+    portHoverScaleFactor: 1.5,
+    portDefaultRadius: 6,
+    snapToPortRadius: 30,
+    showConnectionPreview: true,
+    connectionLineStyle: ConnectionLineStyle.BEZIER,
+    enableLinkReconnection: true,
+    showLinkEndpointHandles: true,
+    enableSmartAutoConnect: true,
+    highlightValidTargets: true,
+    animateConnectionPreview: true,
+    // Phase 2.3: Waypoint editing defaults
+    enableWaypointEditing: false, // Disabled by default for backward compatibility
+    showWaypointHandles: true,
+    waypointEditor: {
+        snapToGrid: false,
+        gridSize: 20,
+        removeOnDoubleClick: true,
+        handleRadius: 5,
+        handleColor: '#3b82f6',
+        handleStrokeColor: '#ffffff',
+        minDistanceFromEndpoints: 30,
+        clickDetectionRadius: 10,
+    },
+    // Phase 2.3: Control point editing defaults
+    enableControlPointEditing: false, // Disabled by default for backward compatibility
+    showControlPointHandles: true,
+    controlPointEditor: {
+        snapToGrid: false,
+        gridSize: 20,
+        handleRadius: 6,
+        handleColor: '#10b981',
+        handleStrokeColor: '#ffffff',
+        controlLineColor: '#6b7280',
+        controlLineWidth: 1,
+        controlLineDash: [5, 5],
+        clickDetectionRadius: 10,
+        showControlLines: true,
+        symmetricControls: false,
+    },
+    // wave12/connect-ergonomics — all three opt-in so steady-state is untouched.
+    enableGroupDrag: false,
+    enableProximityConnect: false,
+    proximityConnectRadius: 0, // 0 → fall back to DEFAULT_SNAP_CONFIG.proximityConnectRadius
+    // Kept opt-in at the library level: a global default-on regresses the drag
+    // covenant (the interaction gate's 1:1-move assumption — verified: it fails
+    // DRAG-ATTACH on contextual-zoom + LINK-SELECT-SPAN on layout-portfolio), and
+    // changes the feel for every embedder. The Visio editor surface enables it.
+    enableHelperLines: false,
+    enableGroupMembershipOnDrop: false,
+    enableInPlaceTextEdit: false,
+    enableKeyboardNudge: false,
+    enableEasyConnect: false,
+    easyConnectModifier: 'none',
+};
+/**
+ * Direct mode preset (fast workflow)
+ */
+exports.DIRECT_MODE_CONFIG = {
+    mode: InteractionMode.DIRECT,
+    portVisibility: PortVisibilityStrategy.ALWAYS,
+    portHoverScaleFactor: 1.3,
+};
+/**
+ * Deliberate mode preset (safe workflow)
+ */
+exports.DELIBERATE_MODE_CONFIG = {
+    mode: InteractionMode.DELIBERATE,
+    portVisibility: PortVisibilityStrategy.ON_HOVER,
+    portHoverScaleFactor: 1.5,
+};
+/**
+ * Smart mode preset (Visio-style)
+ */
+exports.SMART_MODE_CONFIG = {
+    mode: InteractionMode.SMART,
+    portVisibility: PortVisibilityStrategy.ON_HOVER,
+    portHoverScaleFactor: 1.5,
+    enableSmartAutoConnect: true,
+    highlightValidTargets: true,
+};
+//# sourceMappingURL=InteractionConfig.js.map

package/src/libs/engine/src/config/index.d.ts

@@ -0,0 +1 @@
+export * from './InteractionConfig';

package/src/libs/engine/src/config/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// Config exports
+tslib_1.__exportStar(require("./InteractionConfig"), exports);
+//# sourceMappingURL=index.js.map

package/src/libs/engine/src/dsl/DSL.d.ts

@@ -0,0 +1,197 @@
+/**
+ * DSL - Main interface for Mermaid-compatible diagram text parsing
+ *
+ * High-level API that orchestrates Lexer, Parser, Transformer, and LayoutDetector
+ * to convert text-based diagram syntax into fully rendered DiagramModel instances.
+ *
+ * @example
+ * ```typescript
+ * const dsl = new DSL();
+ *
+ * const text = `
+ * flowchart TD
+ *   A[Start] --> B{Decision}
+ *   B -->|Yes| C[Process]
+ *   B -->|No| D[End]
+ *   C --> D
+ * `;
+ *
+ * const diagram = dsl.parse(text);
+ * console.log(`Created ${diagram.getNodes().length} nodes`);
+ * ```
+ */
+import { TransformOptions } from './transformer/ASTTransformer';
+import { LayoutSuggestion } from './detector/LayoutDetector';
+import { GeneratorOptions } from './generator/DSLGenerator';
+import { FormatterOptions } from './generator/DSLFormatter';
+import { DiagramModel } from '../models/DiagramModel';
+import { DiagramNode } from './types/ASTNode';
+import { Token } from './types/Token';
+export interface DSLOptions {
+    /**
+     * Auto-apply layout after parsing
+     */
+    autoLayout?: boolean;
+    /**
+     * Transformation options
+     */
+    transformOptions?: TransformOptions;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+export interface ParseResult {
+    /**
+     * Generated diagram model
+     */
+    diagram: DiagramModel;
+    /**
+     * Abstract syntax tree
+     */
+    ast: DiagramNode;
+    /**
+     * Tokens from lexical analysis
+     */
+    tokens: Token[];
+    /**
+     * Layout suggestion
+     */
+    layoutSuggestion?: LayoutSuggestion;
+    /**
+     * Parse statistics
+     */
+    stats: {
+        nodeCount: number;
+        linkCount: number;
+        parseTime: number;
+    };
+}
+export declare class DSL {
+    /** First-word (lowercased) → canonical Mermaid header. flowchart/graph/
+     *  erDiagram/classDiagram are handled directly in detectDiagramType and are
+     *  intentionally absent. `stateDiagram[-v2]` IS listed (the header spelling
+     *  needs canonicalising) but is now parsed, not refused — everything else
+     *  here is still a recognised-but-unparsed type that Phase 0 fails safe on. */
+    private static readonly KNOWN_DIAGRAM_TYPES;
+    private lexer;
+    private parser;
+    private transformer;
+    private layoutDetector;
+    private generator;
+    private formatter;
+    private options;
+    private styleParser;
+    private templateParser;
+    constructor(options?: DSLOptions);
+    /**
+     * Parse DSL text into a DiagramModel
+     */
+    parse(text: string): DiagramModel;
+    /**
+     * Parse DSL text with detailed results
+     */
+    parseDetailed(text: string): ParseResult;
+    /**
+     * Validate DSL text without creating a diagram
+     */
+    validate(text: string): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get layout suggestion for text without parsing fully
+     */
+    suggestLayout(text: string): LayoutSuggestion | null;
+    /**
+     * Get token stream for debugging
+     */
+    tokenize(text: string): Token[];
+    /**
+     * Get AST for debugging
+     */
+    parseToAST(text: string): DiagramNode;
+    /**
+     * Set options
+     */
+    setOptions(options: Partial<DSLOptions>): void;
+    /**
+     * Get current options
+     */
+    getOptions(): DSLOptions;
+    /**
+     * Generate DSL text from diagram
+     */
+    generate(diagram: DiagramModel, options?: GeneratorOptions): string;
+    /**
+     * Generate and format DSL text from diagram
+     */
+    generateFormatted(diagram: DiagramModel, generatorOptions?: GeneratorOptions, formatterOptions?: FormatterOptions): string;
+    /**
+     * Generate pretty-printed DSL text
+     */
+    generatePretty(diagram: DiagramModel, addHeaders?: boolean): string;
+    /**
+     * Format DSL text
+     */
+    format(text: string, options?: FormatterOptions): string;
+    /**
+     * Round-trip test: parse → generate → parse
+     * Returns true if the round-trip preserves structure
+     */
+    testRoundTrip(text: string): {
+        success: boolean;
+        originalNodes: number;
+        originalLinks: number;
+        regeneratedNodes: number;
+        regeneratedLinks: number;
+        generatedText: string;
+    };
+    /**
+     * Parse ERD (Entity Relationship Diagram).
+     *
+     * Delegates to the Phase-3 Mermaid parser — ONE implementation, so this
+     * long-standing public helper cannot drift back to the scaffolding's
+     * behaviour (a single node called `CUSTOMER ||--o`).
+     */
+    parseERD(text: string): DiagramModel;
+    /**
+     * Generate ERD DSL from diagram
+     */
+    generateERD(diagram: DiagramModel): string;
+    /**
+     * Parse BPMN (Business Process Model)
+     */
+    parseBPMN(text: string): DiagramModel;
+    /**
+     * Generate BPMN DSL from diagram
+     */
+    generateBPMN(diagram: DiagramModel): string;
+    /**
+     * Parse UML Class Diagram.
+     *
+     * Delegates to the Phase-3 Mermaid parser (see parseERD for the reasoning).
+     * The scaffolding this replaces returned an EMPTY diagram for canonical
+     * `classDiagram` input.
+     */
+    parseUML(text: string): DiagramModel;
+    /**
+     * Generate UML DSL from diagram
+     */
+    generateUML(diagram: DiagramModel): string;
+    /**
+     * Phase 4: Apply styles and templates to diagram nodes
+     */
+    private applyStylesAndTemplates;
+    /**
+     * Detect diagram type from text
+     */
+    private detectDiagramType;
+    /**
+     * Wrap an already-built graph-family DiagramModel in a ParseResult. These
+     * types do not go through the flowchart Lexer/Parser at all — their grammars
+     * are line-oriented and share nothing with the flowchart token stream — so
+     * the AST/token slots are empty by construction, not by omission.
+     */
+    private finishGraphType;
+}