@wire-dsl/engine 0.0.3 → 0.1.0

package/dist/index.d.cts

@@ -1,3 +1,99 @@
+/**
+ * SourceMap Types for Wire DSL
+ *
+ * Provides bidirectional mapping between code positions and AST nodes
+ * for features like code-canvas selection, visual editing, and error reporting.
+ */
+
+/**
+ * Position in source code (1-based line, 0-based column)
+ */
+interface Position {
+    line: number;
+    column: number;
+    offset?: number;
+}
+/**
+ * Range in source code
+ */
+interface CodeRange {
+    start: Position;
+    end: Position;
+}
+/**
+ * SourceMap for a single property
+ * Captures ranges for precise property editing
+ */
+interface PropertySourceMap {
+    name: string;
+    value: any;
+    range: CodeRange;
+    nameRange: CodeRange;
+    valueRange: CodeRange;
+}
+/**
+ * Types of nodes in Wire DSL
+ */
+type SourceMapNodeType = 'project' | 'screen' | 'layout' | 'component' | 'component-definition' | 'cell' | 'theme' | 'mocks' | 'colors';
+/**
+ * Main SourceMap entry - represents one node in the AST
+ */
+interface SourceMapEntry {
+    nodeId: string;
+    type: SourceMapNodeType;
+    range: CodeRange;
+    filePath: string;
+    parentId: string | null;
+    name?: string;
+    layoutType?: string;
+    componentType?: string;
+    indexInParent?: number;
+    isUserDefined?: boolean;
+    keywordRange?: CodeRange;
+    nameRange?: CodeRange;
+    bodyRange?: CodeRange;
+    properties?: Record<string, PropertySourceMap>;
+    insertionPoint?: InsertionPoint;
+}
+/**
+ * Insertion point for new children (FASE 3)
+ */
+interface InsertionPoint {
+    line: number;
+    column: number;
+    indentation: string;
+    after?: string;
+}
+/**
+ * Parse result with SourceMap
+ */
+interface ParseResult {
+    ast: AST;
+    sourceMap: SourceMapEntry[];
+    errors: ParseError[];
+}
+/**
+ * Parse error with optional nodeId reference
+ */
+interface ParseError {
+    message: string;
+    range: CodeRange;
+    severity: 'error' | 'warning';
+    nodeId?: string;
+}
+/**
+ * Captured tokens from Chevrotain parser (internal use)
+ * These are NOT stored in AST, only used temporarily during SourceMap building
+ */
+interface CapturedTokens {
+    keyword?: any;
+    name?: any;
+    paramList?: any;
+    properties?: any[];
+    body?: any;
+    children?: any[];
+}
+
 interface AST {
     type: 'project';
     name: string;
@@ -6,35 +102,81 @@ interface AST {
     colors: Record<string, string>;
     definedComponents: ASTDefinedComponent[];
     screens: ASTScreen[];
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTDefinedComponent {
     type: 'definedComponent';
     name: string;
     body: ASTLayout | ASTComponent;
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTScreen {
     type: 'screen';
     name: string;
     params: Record<string, string | number>;
     layout: ASTLayout;
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTLayout {
     type: 'layout';
     layoutType: string;
     params: Record<string, string | number>;
     children: (ASTComponent | ASTLayout | ASTCell)[];
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTCell {
     type: 'cell';
     props: Record<string, string | number>;
     children: (ASTComponent | ASTLayout)[];
+    _meta?: {
+        nodeId: string;
+    };
 }
 interface ASTComponent {
     type: 'component';
     componentType: string;
     props: Record<string, string | number>;
+    _meta?: {
+        nodeId: string;
+    };
 }
 declare function parseWireDSL(input: string): AST;
+/**
+ * Parse Wire DSL with SourceMap generation
+ *
+ * Returns both AST and SourceMap for bidirectional code-canvas mapping
+ * Useful for:
+ * - Visual editors (Wire Studio)
+ * - Code navigation (click canvas → jump to code)
+ * - Error reporting with precise locations
+ * - Component inspection and manipulation
+ *
+ * @param input - Wire DSL source code
+ * @param filePath - Optional file path (default: "<input>") - used for stable nodeIds
+ * @returns ParseResult with AST, SourceMap, and errors
+ *
+ * @example
+ * ```typescript
+ * const { ast, sourceMap } = parseWireDSLWithSourceMap(code, 'screens/Main.wire');
+ *
+ * // Find node by position
+ * const node = sourceMap.find(e =>
+ *   e.range.start.line === 5 && e.range.start.column === 4
+ * );
+ *
+ * // Access AST node
+ * console.log(node.astNode.type);  // 'component'
+ * ```
+ */
+declare function parseWireDSLWithSourceMap(input: string, filePath?: string): ParseResult;
 interface ParsedWireframe {
     name: string;
     components: ParsedComponent[];
@@ -116,6 +258,7 @@ interface IRStyle {
 }
 interface IRMeta {
     source?: string;
+    nodeId?: string;
 }
 declare class IRGenerator {
     private idGen;
@@ -302,11 +445,342 @@ declare class SVGRenderer {
     private extractSvgContent;
     private resolveSpacing;
     private escapeXml;
+    /**
+     * Get data-node-id attribute string for SVG elements
+     * Enables bidirectional selection between code and canvas
+     */
+    private getDataNodeId;
 }
 declare function renderToSVG(ir: IRContract, layout: LayoutResult, options?: SVGRenderOptions): string;
 declare function createSVGElement(tag: string, attrs: Record<string, string | number>, children?: string[]): string;
 declare function buildSVG(component: SVGComponent): string;
 
+/**
+ * Content-based hash generation for stable NodeIds
+ *
+ * Browser-safe implementation (no crypto/node dependencies)
+ * Generates stable IDs that persist across parses if code hasn't changed
+ *
+ * **Uniqueness Strategy:**
+ * Includes `indexInParent` in the hash to ensure identical components
+ * in the same parent get unique IDs. This prevents nodeId collisions for:
+ *
+ * ```wire
+ * layout stack {
+ *   component Button text: "Click"  // index 0
+ *   component Button text: "Click"  // index 1
+ *   component Button text: "Click"  // index 2
+ * }
+ * ```
+ *
+ * Each button will have a different nodeId despite being identical.
+ */
+
+/**
+ * Generate a stable, content-based node ID
+ *
+ * The ID is based on:
+ * - File path (distinguishes nodes across files)
+ * - Line and column (unique position in file)
+ * - Node type (component, layout, screen, etc.)
+ * - Index in parent array (distinguishes identical siblings)
+ * - Optional name (for named nodes like screens, defined components)
+ *
+ * Examples:
+ * - "node-k7m2p9-component" (Icon component at Main.wire:5:4, index 0)
+ * - "node-abc123-screen"    (Main screen at Main.wire:2:0, index 0)
+ * - "node-xyz789-layout"    (stack layout at Main.wire:3:2, index 0)
+ *
+ * @param type - Type of AST node
+ * @param filePath - Source file path
+ * @param line - Line number (1-based)
+ * @param column - Column number (0-based)
+ * @param indexInParent - Index in parent's child array (0-based)
+ * @param name - Optional name (for screens, defined components)
+ * @returns Stable node ID
+ */
+declare function generateStableNodeId(type: SourceMapNodeType, filePath: string, line: number, column: number, indexInParent: number, name?: string): string;
+/**
+ * Validate if a string looks like a valid node ID
+ *
+ * @param id - String to validate
+ * @returns true if it matches the node ID pattern
+ */
+declare function isValidNodeId(id: string): boolean;
+/**
+ * Extract node type from a node ID
+ *
+ * @param nodeId - Node ID to parse
+ * @returns The node type, or null if invalid
+ */
+declare function getTypeFromNodeId(nodeId: string): SourceMapNodeType | null;
+
+/**
+ * SourceMapBuilder
+ *
+ * Constructs SourceMap during AST traversal using semantic node IDs.
+ *
+ * **ID Strategy:**
+ * - Uses human-readable, semantic IDs: `{type}-{subtype}-{counter}`
+ * - Counter is per type-subtype to keep indices small
+ * - Examples: `component-button-0`, `layout-stack-1`, `screen-0`
+ *
+ * **Stability:**
+ * - IDs remain stable when editing properties ✅
+ * - IDs change when reordering nodes ⚠️
+ * - Ideal for editor UX where property editing is frequent
+ *
+ * **Generated IDs:**
+ * - `project` - Single project (no counter)
+ * - `screen-{n}` - Screens by index (0-based)
+ * - `component-{type}-{n}` - Components by subtype (button-0, input-0, etc.)
+ * - `layout-{type}-{n}` - Layouts by subtype (stack-0, grid-1, etc.)
+ * - `cell-{n}` - Grid cells by index
+ * - `define-{name}` - Component definitions by name
+ */
+
+/**
+ * Builder for constructing SourceMap entries during parsing
+ * Uses semantic IDs based on type-subtype-counter (e.g., component-button-0)
+ */
+declare class SourceMapBuilder {
+    private entries;
+    private filePath;
+    private sourceCode;
+    private parentStack;
+    private counters;
+    constructor(filePath?: string, sourceCode?: string);
+    /**
+     * Add a node to the SourceMap
+     * Generates semantic IDs like: project, screen-0, component-button-1, layout-stack-0
+     *
+     * @param type - Type of AST node
+     * @param tokens - Captured tokens from parser
+     * @param metadata - Optional metadata (name, layoutType, componentType)
+     * @returns Generated nodeId
+     */
+    addNode(type: SourceMapNodeType, tokens: CapturedTokens, metadata?: {
+        name?: string;
+        layoutType?: string;
+        componentType?: string;
+        isUserDefined?: boolean;
+    }): string;
+    /**
+     * Generate semantic node ID based on type and subtype
+     * Format: {type}-{subtype}-{counter} or {type}-{counter}
+     *
+     * Examples:
+     * - project → "project"
+     * - theme → "theme"
+     * - mocks → "mocks"
+     * - colors → "colors"
+     * - screen → "screen-0", "screen-1"
+     * - component Button → "component-button-0", "component-button-1"
+     * - layout stack → "layout-stack-0", "layout-stack-1"
+     * - cell → "cell-0", "cell-1"
+     * - component-definition → "define-MyButton"
+     */
+    private generateNodeId;
+    /**
+     * Add a property to an existing node in the SourceMap
+     * Captures precise ranges for property name and value for surgical editing
+     *
+     * @param nodeId - ID of the node that owns this property
+     * @param propertyName - Name of the property (e.g., "text", "direction")
+     * @param propertyValue - Parsed value of the property
+     * @param tokens - Captured tokens for the property
+     * @returns The PropertySourceMap entry created
+     */
+    addProperty(nodeId: string, propertyName: string, propertyValue: any, tokens: {
+        name?: any;
+        value?: any;
+        separator?: any;
+        full?: any;
+    }): PropertySourceMap;
+    /**
+     * Push a parent onto the stack (when entering a container node)
+     */
+    pushParent(nodeId: string): void;
+    /**
+     * Pop a parent from the stack (when exiting a container node)
+     */
+    popParent(): void;
+    /**
+     * Get the current parent nodeId (or null if at root)
+     */
+    getCurrentParent(): string | null;
+    /**
+     * Build and return the final SourceMap
+     */
+    build(): SourceMapEntry[];
+    /**
+     * Calculate insertionPoints for all container nodes
+     * Container nodes: project, screen, layout, cell, component-definition
+     */
+    private calculateAllInsertionPoints;
+    /**
+     * Calculate CodeRange from captured tokens
+     * Finds the earliest start and latest end among all tokens
+     */
+    private calculateRange;
+    /**
+     * Convert a single token to CodeRange
+     */
+    private tokenToRange;
+    /**
+     * Calculate body range from closing brace token
+     * Body range typically spans from opening brace to closing brace
+     */
+    private calculateBodyRange;
+    /**
+     * Extract the first real token from a CST node (earliest by offset)
+     * Recursively searches through children to find the token with smallest offset
+     */
+    private getFirstToken;
+    /**
+     * Extract the last real token from a CST node (latest by offset)
+     * Recursively searches through children to find the token with largest offset
+     */
+    private getLastToken;
+    /**
+     * Extract start position from a Chevrotain token or CST node
+     */
+    private getTokenStart;
+    /**
+     * Extract end position from a Chevrotain token or CST node
+     */
+    private getTokenEnd;
+    /**
+     * Reset the builder (for reuse)
+     */
+    reset(filePath?: string, sourceCode?: string): void;
+    /**
+     * Calculate insertion point for adding new children to a container node
+     *
+     * Strategy:
+     * - If node has children: insert after last child, preserve indentation
+     * - If node is empty: insert inside body, use parent indentation + 2 spaces
+     *
+     * @param nodeId - ID of the container node
+     * @returns InsertionPoint with line, column, indentation, and optional after
+     */
+    calculateInsertionPoint(nodeId: string): {
+        line: number;
+        column: number;
+        indentation: string;
+        after?: string;
+    } | undefined;
+    /**
+     * Extract indentation (leading whitespace) from a line
+     */
+    private extractIndentation;
+}
+
+/**
+ * SourceMapResolver
+ *
+ * Provides query APIs for bidirectional code↔canvas selection
+ *
+ * **Use Cases:**
+ * 1. Canvas → Code: Click SVG element with data-node-id → find code location
+ * 2. Code → Canvas: Click code position → find corresponding node
+ *
+ * **Performance:**
+ * - getNodeById: O(1) with Map index
+ * - getNodeByPosition: O(n) linear search (could be optimized with interval tree)
+ * - getChildren/getParent: O(1) with indexes
+ */
+
+/**
+ * Query result for position-based lookups
+ */
+interface PositionQueryResult extends SourceMapEntry {
+    depth: number;
+}
+/**
+ * SourceMap query and navigation API
+ */
+declare class SourceMapResolver {
+    private nodeMap;
+    private childrenMap;
+    private positionIndex;
+    constructor(sourceMap: SourceMapEntry[]);
+    /**
+     * Find node by ID (Canvas → Code)
+     *
+     * @example
+     * // User clicks SVG element with data-node-id="component-button-0"
+     * const node = resolver.getNodeById("component-button-0");
+     * editor.revealRange(node.range); // Jump to code
+     */
+    getNodeById(nodeId: string): SourceMapEntry | null;
+    /**
+     * Find node at position (Code → Canvas)
+     * Returns the most specific (deepest) node containing the position
+     *
+     * @example
+     * // User clicks code at line 5, column 10
+     * const node = resolver.getNodeByPosition(5, 10);
+     * canvas.highlightElement(node.nodeId); // Highlight in canvas
+     */
+    getNodeByPosition(line: number, column: number): SourceMapEntry | null;
+    /**
+     * Get all child nodes of a parent
+     *
+     * @example
+     * const children = resolver.getChildren("layout-stack-0");
+     * // Returns: [component-button-0, component-input-0, ...]
+     */
+    getChildren(nodeId: string): SourceMapEntry[];
+    /**
+     * Get parent node
+     *
+     * @example
+     * const parent = resolver.getParent("component-button-0");
+     * // Returns: layout-stack-0
+     */
+    getParent(nodeId: string): SourceMapEntry | null;
+    /**
+     * Get all nodes in the SourceMap
+     */
+    getAllNodes(): SourceMapEntry[];
+    /**
+     * Get all nodes of a specific type
+     *
+     * @example
+     * const buttons = resolver.getNodesByType("component", "Button");
+     */
+    getNodesByType(type: SourceMapEntry['type'], subtype?: string): SourceMapEntry[];
+    /**
+     * Get siblings of a node (nodes with same parent)
+     */
+    getSiblings(nodeId: string): SourceMapEntry[];
+    /**
+     * Get path from root to node (breadcrumb)
+     *
+     * @example
+     * const path = resolver.getPath("component-button-0");
+     * // Returns: [project, screen-0, layout-stack-0, component-button-0]
+     */
+    getPath(nodeId: string): SourceMapEntry[];
+    /**
+     * Check if a position is within a node's range
+     */
+    private containsPosition;
+    /**
+     * Calculate depth of a node in the tree (0 = root)
+     */
+    private calculateDepth;
+    /**
+     * Get statistics about the SourceMap
+     */
+    getStats(): {
+        totalNodes: number;
+        byType: Record<string, number>;
+        maxDepth: number;
+    };
+}
+
 declare const version = "0.0.1";
 
-export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRProject, type IRScreen, type IRStyle, type IRTheme, type IRWireframe, LayoutEngine, type LayoutPosition, type LayoutResult, type ParsedComponent, type ParsedWireframe, type SVGComponent, type SVGRenderOptions, SVGRenderer, buildSVG, calculateLayout, createSVGElement, generateIR, parseWireDSL, renderToSVG, resolveGridPosition, version };
+export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRProject, type IRScreen, type IRStyle, type IRTheme, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseError, type ParseResult, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveGridPosition, version };