@magicborn/dialogue-forge 0.1.0

package/dist/esm/utils/layout/strategies/grid.js

@@ -0,0 +1,91 @@
+/**
+ * Grid Layout Strategy
+ *
+ * Simple grid-based layout that arranges nodes in rows and columns.
+ * Useful for getting a quick overview of all nodes.
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+const NODE_WIDTH = 220;
+const NODE_HEIGHT = 120;
+// ============================================================================
+// Strategy Implementation
+// ============================================================================
+export class GridLayoutStrategy {
+    constructor() {
+        this.id = 'grid';
+        this.name = 'Grid';
+        this.description = 'Arranges nodes in a simple grid pattern. Good for viewing all nodes at once.';
+        this.defaultOptions = {
+            nodeSpacingX: 50,
+            nodeSpacingY: 50,
+            margin: 50,
+        };
+    }
+    apply(dialogue, options) {
+        const startTime = performance.now();
+        const opts = { ...this.defaultOptions, ...options };
+        const margin = opts.margin || 50;
+        const spacingX = opts.nodeSpacingX || 50;
+        const spacingY = opts.nodeSpacingY || 50;
+        const nodeIds = Object.keys(dialogue.nodes);
+        if (nodeIds.length === 0) {
+            return this.emptyResult(dialogue, startTime);
+        }
+        // Calculate grid dimensions
+        const cols = Math.ceil(Math.sqrt(nodeIds.length));
+        const cellWidth = NODE_WIDTH + spacingX;
+        const cellHeight = NODE_HEIGHT + spacingY;
+        // Sort nodes: start node first, then by ID
+        const sortedIds = [...nodeIds].sort((a, b) => {
+            if (a === dialogue.startNodeId)
+                return -1;
+            if (b === dialogue.startNodeId)
+                return 1;
+            return a.localeCompare(b);
+        });
+        // Position nodes in grid
+        const updatedNodes = {};
+        let maxX = 0;
+        let maxY = 0;
+        sortedIds.forEach((id, index) => {
+            const col = index % cols;
+            const row = Math.floor(index / cols);
+            const x = margin + col * cellWidth;
+            const y = margin + row * cellHeight;
+            updatedNodes[id] = { ...dialogue.nodes[id], x, y };
+            maxX = Math.max(maxX, x + NODE_WIDTH);
+            maxY = Math.max(maxY, y + NODE_HEIGHT);
+        });
+        const computeTimeMs = performance.now() - startTime;
+        return {
+            dialogue: { ...dialogue, nodes: updatedNodes },
+            metadata: {
+                computeTimeMs,
+                nodeCount: nodeIds.length,
+                bounds: {
+                    minX: margin,
+                    minY: margin,
+                    maxX,
+                    maxY,
+                    width: maxX - margin,
+                    height: maxY - margin,
+                },
+            },
+        };
+    }
+    emptyResult(dialogue, startTime) {
+        return {
+            dialogue,
+            metadata: {
+                computeTimeMs: performance.now() - startTime,
+                nodeCount: 0,
+                bounds: { minX: 0, minY: 0, maxX: 0, maxY: 0, width: 0, height: 0 },
+            },
+        };
+    }
+    supports() {
+        return true; // Works with any graph
+    }
+}

package/dist/esm/utils/layout/strategies/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Layout Strategies Index
+ *
+ * Export all built-in layout strategies.
+ */
+export { DagreLayoutStrategy } from './dagre';
+export { ForceLayoutStrategy } from './force';
+export { GridLayoutStrategy } from './grid';

package/dist/esm/utils/layout/strategies/index.js

@@ -0,0 +1,8 @@
+/**
+ * Layout Strategies Index
+ *
+ * Export all built-in layout strategies.
+ */
+export { DagreLayoutStrategy } from './dagre';
+export { ForceLayoutStrategy } from './force';
+export { GridLayoutStrategy } from './grid';

package/dist/esm/utils/layout/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Layout Strategy Types
+ *
+ * Defines the interface and types for layout algorithms.
+ * Implements the Strategy pattern to allow swappable layout algorithms.
+ */
+import { DialogueTree } from '../../types';
+/**
+ * Layout direction for hierarchical layouts
+ * - TB: Top to Bottom (vertical flow)
+ * - LR: Left to Right (horizontal flow)
+ */
+export type LayoutDirection = 'TB' | 'LR';
+/**
+ * Configuration options for layout algorithms
+ */
+export interface LayoutOptions {
+    /** Direction of flow for hierarchical layouts */
+    direction?: LayoutDirection;
+    /** Horizontal spacing between nodes */
+    nodeSpacingX?: number;
+    /** Vertical spacing between nodes */
+    nodeSpacingY?: number;
+    /** Margin around the entire layout */
+    margin?: number;
+    /** Whether to animate the transition */
+    animate?: boolean;
+}
+/**
+ * Result of a layout operation
+ */
+export interface LayoutResult {
+    /** The dialogue tree with updated node positions */
+    dialogue: DialogueTree;
+    /** Metadata about the layout operation */
+    metadata: {
+        /** Time taken to compute layout in milliseconds */
+        computeTimeMs: number;
+        /** Number of nodes processed */
+        nodeCount: number;
+        /** Bounding box of the layout */
+        bounds: {
+            minX: number;
+            minY: number;
+            maxX: number;
+            maxY: number;
+            width: number;
+            height: number;
+        };
+    };
+}
+/**
+ * Layout Strategy Interface
+ *
+ * All layout algorithms must implement this interface.
+ * This enables the Strategy pattern - algorithms can be swapped at runtime.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomLayout implements LayoutStrategy {
+ *   readonly id = 'my-custom';
+ *   readonly name = 'My Custom Layout';
+ *   readonly description = 'A custom layout algorithm';
+ *
+ *   apply(dialogue: DialogueTree, options?: LayoutOptions): LayoutResult {
+ *     // Your layout logic here
+ *   }
+ * }
+ * ```
+ */
+export interface LayoutStrategy {
+    /** Unique identifier for the strategy */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Description of what this layout does */
+    readonly description: string;
+    /** Default options for this strategy */
+    readonly defaultOptions?: Partial<LayoutOptions>;
+    /**
+     * Apply the layout algorithm to a dialogue tree
+     * @param dialogue - The dialogue tree to layout
+     * @param options - Optional configuration
+     * @returns The layout result with updated positions
+     */
+    apply(dialogue: DialogueTree, options?: LayoutOptions): LayoutResult;
+    /**
+     * Check if this strategy supports the given dialogue
+     * Some strategies may not work well with certain graph structures
+     */
+    supports?(dialogue: DialogueTree): boolean;
+}
+/**
+ * Registry entry for a layout strategy
+ */
+export interface LayoutStrategyEntry {
+    strategy: LayoutStrategy;
+    /** Whether this is the default strategy */
+    isDefault?: boolean;
+}

package/dist/esm/utils/layout/types.js

@@ -0,0 +1,7 @@
+/**
+ * Layout Strategy Types
+ *
+ * Defines the interface and types for layout algorithms.
+ * Implements the Strategy pattern to allow swappable layout algorithms.
+ */
+export {};

package/dist/esm/utils/layout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Layout Utilities - Re-export from modular layout system
+ *
+ * This file provides backward compatibility.
+ * For new code, import directly from './layout/index.ts'
+ *
+ * @see LAYOUT_STRATEGIES.md for documentation
+ */
+export { applyLayout, listLayouts, applyDagreLayout, applyHierarchicalLayout, resolveNodeCollisions, type LayoutStrategy, type LayoutOptions, type LayoutResult, type LayoutDirection, layoutRegistry, DagreLayoutStrategy, ForceLayoutStrategy, GridLayoutStrategy, } from './layout/index';

package/dist/esm/utils/layout.js

@@ -0,0 +1,17 @@
+/**
+ * Layout Utilities - Re-export from modular layout system
+ *
+ * This file provides backward compatibility.
+ * For new code, import directly from './layout/index.ts'
+ *
+ * @see LAYOUT_STRATEGIES.md for documentation
+ */
+export { 
+// Main functions
+applyLayout, listLayouts, 
+// Backward compatibility
+applyDagreLayout, applyHierarchicalLayout, resolveNodeCollisions, 
+// Registry
+layoutRegistry, 
+// Strategies (for extension)
+DagreLayoutStrategy, ForceLayoutStrategy, GridLayoutStrategy, } from './layout/index';

package/dist/esm/utils/node-helpers.d.ts

@@ -0,0 +1,7 @@
+import { DialogueNode, DialogueTree, Choice } from '../types';
+import { NodeType } from '../types/constants';
+export declare function createNode(type: NodeType, id: string, x: number, y: number): DialogueNode;
+export declare function addChoiceToNode(node: DialogueNode): DialogueNode;
+export declare function removeChoiceFromNode(node: DialogueNode, choiceIdx: number): DialogueNode;
+export declare function updateChoiceInNode(node: DialogueNode, choiceIdx: number, updates: Partial<Choice>): DialogueNode;
+export declare function deleteNodeFromTree(tree: DialogueTree, nodeId: string): DialogueTree;

package/dist/esm/utils/node-helpers.js

@@ -0,0 +1,94 @@
+import { NODE_TYPE } from '../types/constants';
+export function createNode(type, id, x, y) {
+    if (type === NODE_TYPE.NPC) {
+        return {
+            id,
+            type,
+            content: 'New dialogue...',
+            speaker: 'Character',
+            x,
+            y
+        };
+    }
+    else if (type === NODE_TYPE.PLAYER) {
+        return {
+            id,
+            type,
+            content: '',
+            choices: [{ id: `c_${Date.now()}`, text: 'Choice 1', nextNodeId: '' }],
+            x,
+            y
+        };
+    }
+    else if (type === NODE_TYPE.CONDITIONAL) {
+        return {
+            id,
+            type,
+            content: '',
+            conditionalBlocks: [{
+                    id: `block_${Date.now()}`,
+                    type: 'if',
+                    condition: [],
+                    content: 'New dialogue...',
+                    speaker: undefined
+                }],
+            x,
+            y
+        };
+    }
+    // Fallback
+    return {
+        id,
+        type,
+        content: '',
+        x,
+        y
+    };
+}
+export function addChoiceToNode(node) {
+    if (node.type !== NODE_TYPE.PLAYER)
+        return node;
+    const newChoice = {
+        id: `c_${Date.now()}`,
+        text: 'New choice...',
+        nextNodeId: ''
+    };
+    return {
+        ...node,
+        choices: [...(node.choices || []), newChoice]
+    };
+}
+export function removeChoiceFromNode(node, choiceIdx) {
+    if (node.type !== NODE_TYPE.PLAYER || !node.choices)
+        return node;
+    return {
+        ...node,
+        choices: node.choices.filter((_, i) => i !== choiceIdx)
+    };
+}
+export function updateChoiceInNode(node, choiceIdx, updates) {
+    if (node.type !== NODE_TYPE.PLAYER || !node.choices)
+        return node;
+    const newChoices = [...node.choices];
+    newChoices[choiceIdx] = { ...newChoices[choiceIdx], ...updates };
+    return { ...node, choices: newChoices };
+}
+export function deleteNodeFromTree(tree, nodeId) {
+    if (nodeId === tree.startNodeId) {
+        throw new Error("Cannot delete the start node");
+    }
+    const { [nodeId]: _, ...rest } = tree.nodes;
+    // Remove references to deleted node
+    Object.keys(rest).forEach(id => {
+        if (rest[id].nextNodeId === nodeId) {
+            rest[id] = { ...rest[id], nextNodeId: undefined };
+        }
+        if (rest[id].choices) {
+            rest[id] = {
+                ...rest[id],
+                choices: rest[id].choices.map(c => c.nextNodeId === nodeId ? { ...c, nextNodeId: '' } : c)
+            };
+        }
+    });
+    return { ...tree, nodes: rest };
+}

package/dist/esm/utils/reactflow-converter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * React Flow Converter Utilities
+ *
+ * Converts between DialogueTree format and React Flow format.
+ *
+ * React Flow Format:
+ * - nodes: Array of { id, type, position: {x, y}, data }
+ * - edges: Array of { id, source, target, sourceHandle?, targetHandle?, type, data? }
+ */
+import { DialogueTree, DialogueNode } from '../types';
+import { Node, Edge, Position } from 'reactflow';
+import { LayoutDirection } from './layout';
+export declare const CHOICE_COLORS: string[];
+export interface ReactFlowNodeData {
+    node: DialogueNode;
+    flagSchema?: any;
+    layoutDirection?: LayoutDirection;
+}
+export type ReactFlowNode = Node<ReactFlowNodeData>;
+export type ReactFlowEdge = Edge;
+/**
+ * Get handle positions based on layout direction
+ * For horizontal (LR): source on right, target on left
+ * For vertical (TB): source on bottom, target on top
+ */
+export declare function getHandlePositions(direction: LayoutDirection): {
+    sourcePosition: Position;
+    targetPosition: Position;
+};
+/**
+ * Convert DialogueTree to React Flow format
+ */
+export declare function convertDialogueTreeToReactFlow(dialogue: DialogueTree, layoutDirection?: LayoutDirection): {
+    nodes: ReactFlowNode[];
+    edges: ReactFlowEdge[];
+};
+/**
+ * Convert React Flow format back to DialogueTree
+ *
+ * This updates node positions and edge connections in the DialogueTree.
+ */
+export declare function updateDialogueTreeFromReactFlow(dialogue: DialogueTree, nodes: Node[], edges: Edge[]): DialogueTree;

package/dist/esm/utils/reactflow-converter.js

@@ -0,0 +1,217 @@
+/**
+ * React Flow Converter Utilities
+ *
+ * Converts between DialogueTree format and React Flow format.
+ *
+ * React Flow Format:
+ * - nodes: Array of { id, type, position: {x, y}, data }
+ * - edges: Array of { id, source, target, sourceHandle?, targetHandle?, type, data? }
+ */
+import { NODE_TYPE } from '../types/constants';
+import { Position } from 'reactflow';
+// Color scheme for choice edges (same as current implementation)
+export const CHOICE_COLORS = ['#e94560', '#8b5cf6', '#06b6d4', '#22c55e', '#f59e0b'];
+/**
+ * Get handle positions based on layout direction
+ * For horizontal (LR): source on right, target on left
+ * For vertical (TB): source on bottom, target on top
+ */
+export function getHandlePositions(direction) {
+    if (direction === 'LR') {
+        return { sourcePosition: Position.Right, targetPosition: Position.Left };
+    }
+    return { sourcePosition: Position.Bottom, targetPosition: Position.Top };
+}
+/**
+ * Convert DialogueTree to React Flow format
+ */
+export function convertDialogueTreeToReactFlow(dialogue, layoutDirection = 'TB') {
+    const nodes = [];
+    const edges = [];
+    const { sourcePosition, targetPosition } = getHandlePositions(layoutDirection);
+    // Convert nodes - create new node objects to avoid sharing references
+    Object.values(dialogue.nodes).forEach(node => {
+        // Deep copy node to avoid sharing references, especially for arrays
+        const nodeCopy = {
+            ...node,
+            choices: node.choices ? node.choices.map(choice => ({ ...choice })) : undefined,
+            setFlags: node.setFlags ? [...node.setFlags] : undefined,
+            conditionalBlocks: node.conditionalBlocks ? node.conditionalBlocks.map(block => ({
+                ...block,
+                condition: block.condition ? [...block.condition] : undefined,
+            })) : undefined,
+        };
+        nodes.push({
+            id: node.id,
+            type: node.type,
+            position: { x: node.x, y: node.y },
+            data: {
+                node: nodeCopy,
+                layoutDirection,
+            },
+            sourcePosition,
+            targetPosition,
+            selected: false,
+        });
+    });
+    // Convert edges - using smoothstep type for cleaner angular look
+    Object.values(dialogue.nodes).forEach(node => {
+        if (node.type === NODE_TYPE.NPC && node.nextNodeId) {
+            // NPC -> next node (single connection)
+            edges.push({
+                id: `${node.id}-next`,
+                source: node.id,
+                target: node.nextNodeId,
+                sourceHandle: 'next',
+                type: 'default', // Uses NPCEdgeV2 component (smoothstep style)
+            });
+        }
+        if (node.type === NODE_TYPE.PLAYER && node.choices) {
+            // Player -> multiple choices (one edge per choice)
+            node.choices.forEach((choice, idx) => {
+                if (choice.nextNodeId) {
+                    const color = CHOICE_COLORS[idx % CHOICE_COLORS.length];
+                    edges.push({
+                        id: `${node.id}-choice-${idx}`,
+                        source: node.id,
+                        target: choice.nextNodeId,
+                        sourceHandle: `choice-${idx}`, // Connect to specific choice handle
+                        type: 'choice', // Use custom ChoiceEdge (smoothstep style)
+                        data: {
+                            choiceIndex: idx,
+                            choiceId: choice.id,
+                        },
+                        style: {
+                            stroke: color,
+                            strokeWidth: 2,
+                            opacity: 0.7,
+                        },
+                    });
+                }
+            });
+        }
+        if (node.type === NODE_TYPE.CONDITIONAL && node.conditionalBlocks) {
+            // Conditional -> multiple blocks (one edge per block)
+            node.conditionalBlocks.forEach((block, idx) => {
+                // Each block can have its own nextNodeId (though typically only one path is taken)
+                // For now, we'll treat it like choices - each block can connect to a node
+                if (block.nextNodeId) {
+                    const color = CHOICE_COLORS[idx % CHOICE_COLORS.length];
+                    edges.push({
+                        id: `${node.id}-block-${idx}`,
+                        source: node.id,
+                        target: block.nextNodeId,
+                        sourceHandle: `block-${idx}`, // Connect to specific block handle
+                        type: 'choice', // Use same edge type as choices (smoothstep style)
+                        data: {
+                            choiceIndex: idx,
+                            blockId: block.id,
+                        },
+                        style: {
+                            stroke: color,
+                            strokeWidth: 2,
+                            opacity: 0.7,
+                        },
+                    });
+                }
+            });
+        }
+    });
+    return { nodes, edges };
+}
+/**
+ * Convert React Flow format back to DialogueTree
+ *
+ * This updates node positions and edge connections in the DialogueTree.
+ */
+export function updateDialogueTreeFromReactFlow(dialogue, nodes, edges) {
+    // Create a deep copy of all nodes to avoid mutations
+    const updatedNodes = {};
+    // First, create copies of all nodes with cleared connections
+    Object.values(dialogue.nodes).forEach(node => {
+        if (node.type === NODE_TYPE.NPC) {
+            updatedNodes[node.id] = {
+                ...node,
+                nextNodeId: undefined,
+            };
+        }
+        else if (node.type === NODE_TYPE.PLAYER) {
+            updatedNodes[node.id] = {
+                ...node,
+                choices: node.choices ? node.choices.map(choice => ({
+                    ...choice,
+                    nextNodeId: '',
+                })) : [],
+            };
+        }
+        else if (node.type === NODE_TYPE.CONDITIONAL) {
+            updatedNodes[node.id] = {
+                ...node,
+                conditionalBlocks: node.conditionalBlocks ? node.conditionalBlocks.map(block => ({
+                    ...block,
+                    nextNodeId: undefined,
+                })) : [],
+            };
+        }
+        else {
+            updatedNodes[node.id] = { ...node };
+        }
+    });
+    // Update node positions
+    nodes.forEach(rfNode => {
+        if (updatedNodes[rfNode.id]) {
+            updatedNodes[rfNode.id] = {
+                ...updatedNodes[rfNode.id],
+                x: rfNode.position.x,
+                y: rfNode.position.y,
+            };
+        }
+    });
+    // Apply edge connections
+    edges.forEach(edge => {
+        const sourceNode = updatedNodes[edge.source];
+        if (!sourceNode)
+            return;
+        if (edge.sourceHandle === 'next' && sourceNode.type === NODE_TYPE.NPC) {
+            // NPC next connection - create new node object
+            updatedNodes[edge.source] = {
+                ...sourceNode,
+                nextNodeId: edge.target,
+            };
+        }
+        else if (edge.sourceHandle?.startsWith('choice-') && sourceNode.type === NODE_TYPE.PLAYER) {
+            // Player choice connection - create new node and choice objects
+            const choiceIdx = parseInt(edge.sourceHandle.replace('choice-', ''));
+            if (sourceNode.choices && sourceNode.choices[choiceIdx]) {
+                const updatedChoices = [...sourceNode.choices];
+                updatedChoices[choiceIdx] = {
+                    ...updatedChoices[choiceIdx],
+                    nextNodeId: edge.target,
+                };
+                updatedNodes[edge.source] = {
+                    ...sourceNode,
+                    choices: updatedChoices,
+                };
+            }
+        }
+        else if (edge.sourceHandle?.startsWith('block-') && sourceNode.type === NODE_TYPE.CONDITIONAL) {
+            // Conditional block connection
+            const blockIdx = parseInt(edge.sourceHandle.replace('block-', ''));
+            if (sourceNode.conditionalBlocks && sourceNode.conditionalBlocks[blockIdx]) {
+                const updatedBlocks = [...sourceNode.conditionalBlocks];
+                updatedBlocks[blockIdx] = {
+                    ...updatedBlocks[blockIdx],
+                    nextNodeId: edge.target,
+                };
+                updatedNodes[edge.source] = {
+                    ...sourceNode,
+                    conditionalBlocks: updatedBlocks,
+                };
+            }
+        }
+    });
+    return {
+        ...dialogue,
+        nodes: updatedNodes,
+    };
+}

package/dist/examples/example-loader.d.ts

@@ -0,0 +1,29 @@
+import { DialogueTree } from '../types';
+import { FlagSchema } from '../types/flags';
+/**
+ * Load an example dialogue from a Yarn file
+ * This is the unified way to load examples - all examples are Yarn files
+ */
+export declare function loadExampleDialogue(exampleId: string): Promise<DialogueTree | null>;
+/**
+ * Get flag schema for an example
+ */
+export declare function getFlagSchemaForExample(exampleId: string): FlagSchema | null;
+/**
+ * Get all examples with their metadata
+ */
+export declare function getAllExamples(): {
+    flagSchema: FlagSchema | null;
+    id: string;
+    title: string;
+    description: string;
+    filename: string;
+    flagSchemaId: string;
+    nodeCount?: number;
+    features: string[];
+}[];
+/**
+ * Synchronous version for use with pre-loaded examples
+ * This is used when examples are bundled/inlined
+ */
+export declare function loadExampleDialogueSync(exampleId: string, yarnContent: string): DialogueTree | null;