@wire-dsl/engine 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -267,7 +267,7 @@ interface IRScreen {
         ref: string;
     };
 }
-type IRNode = IRContainerNode | IRComponentNode;
+type IRNode = IRContainerNode | IRComponentNode | IRInstanceNode;
 interface IRContainerNode {
     id: string;
     kind: 'container';
@@ -298,6 +298,28 @@ interface IRMeta {
     source?: string;
     nodeId?: string;
 }
+/**
+ * Wraps an expanded user-defined component or layout instance.
+ * Preserves the call-site identity (nodeId) in the SVG so the canvas
+ * can select and edit the instance independently from its definition.
+ */
+interface IRInstanceNode {
+    id: string;
+    kind: 'instance';
+    /** Name of the user-defined component or layout (e.g. "MyComp") */
+    definitionName: string;
+    /** Whether it originated from a `define Component` or `define Layout` */
+    definitionKind: 'component' | 'layout';
+    /** Props/params passed at the call site (e.g. { text: "Hello" }) */
+    invocationProps: Record<string, string | number>;
+    /** Reference to the root IR node produced by expanding the definition */
+    expandedRoot: {
+        ref: string;
+    };
+    style: IRNodeStyle;
+    /** meta.nodeId = SourceMap nodeId of the call-site AST node */
+    meta: IRMeta;
+}
 declare class IRGenerator {
     private idGen;
     private nodes;
@@ -441,6 +463,13 @@ declare class LayoutEngine {
     private calculateSplit;
     private calculatePanel;
     private calculateCard;
+    /**
+     * Calculate layout for an instance node.
+     * The instance is a transparent wrapper — its bounding box equals the
+     * expanded root's bounding box. We calculate the expanded root first and
+     * then copy its position to the instance nodeId so the renderer can use it.
+     */
+    private calculateInstance;
     private calculateComponent;
     private resolveSpacing;
     private getSeparateSize;
@@ -568,6 +597,12 @@ interface SVGRenderOptions {
     theme?: 'light' | 'dark';
     includeLabels?: boolean;
     screenName?: string;
+    /**
+     * When true, renders visual diagnostic overlays for invalid DSL states
+     * (e.g. empty containers). Enable in editor/canvas mode; leave false for
+     * clean exports (CLI, PDF, PNG).
+     */
+    showDiagnostics?: boolean;
 }
 interface SVGComponent {
     tag: string;
@@ -641,6 +676,16 @@ declare class SVGRenderer {
     protected renderTopbar(node: IRComponentNode, pos: any): string;
     protected renderPanelBorder(node: IRNode, pos: any, output: string[]): void;
     protected renderCardBorder(node: IRNode, pos: any, output: string[]): void;
+    /**
+     * Renders a yellow warning placeholder for containers with no children.
+     * Only shown when `showDiagnostics` is enabled (editor/canvas mode).
+     */
+    protected renderEmptyContainerDiagnostic(pos: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, containerType?: string): string;
     protected renderSplitDecoration(node: IRNode, pos: any, output: string[]): void;
     protected renderTable(node: IRComponentNode, pos: any): string;
     protected renderChartPlaceholder(node: IRComponentNode, pos: any): string;
@@ -750,7 +795,7 @@ declare class SVGRenderer {
      * Get data-node-id attribute string for SVG elements
      * Enables bidirectional selection between code and canvas
      */
-    protected getDataNodeId(node: IRComponentNode | IRContainerNode): string;
+    protected getDataNodeId(node: IRComponentNode | IRContainerNode | IRInstanceNode): string;
 }
 declare function renderToSVG(ir: IRContract, layout: LayoutResult, options?: SVGRenderOptions): string;
 declare function createSVGElement(tag: string, attrs: Record<string, string | number>, children?: string[]): string;
@@ -796,6 +841,12 @@ declare class SkeletonSVGRenderer extends SVGRenderer {
      * Render label as gray block
      */
     protected renderLabel(node: IRComponentNode, pos: any): string;
+    /**
+     * Render image as a plain skeleton rectangle — no icon, no placeholder label,
+     * just a filled block with the correct dimensions (aspect-ratio is preserved
+     * by the layout engine, so pos already has the right size).
+     */
+    protected renderImage(node: IRComponentNode, pos: any): string;
     /**
      * Render badge as shape only (no text)
      */
@@ -1342,4 +1393,4 @@ declare class SourceMapResolver {
 
 declare const version = "0.0.1";
 
-export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTDefinedLayout, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseDiagnosticsResult, type ParseError, type ParseResult, type ParseWireDSLWithSourceMapOptions, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };
+export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTDefinedLayout, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRInstanceNode, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseDiagnosticsResult, type ParseError, type ParseResult, type ParseWireDSLWithSourceMapOptions, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };

package/dist/index.d.ts

@@ -267,7 +267,7 @@ interface IRScreen {
         ref: string;
     };
 }
-type IRNode = IRContainerNode | IRComponentNode;
+type IRNode = IRContainerNode | IRComponentNode | IRInstanceNode;
 interface IRContainerNode {
     id: string;
     kind: 'container';
@@ -298,6 +298,28 @@ interface IRMeta {
     source?: string;
     nodeId?: string;
 }
+/**
+ * Wraps an expanded user-defined component or layout instance.
+ * Preserves the call-site identity (nodeId) in the SVG so the canvas
+ * can select and edit the instance independently from its definition.
+ */
+interface IRInstanceNode {
+    id: string;
+    kind: 'instance';
+    /** Name of the user-defined component or layout (e.g. "MyComp") */
+    definitionName: string;
+    /** Whether it originated from a `define Component` or `define Layout` */
+    definitionKind: 'component' | 'layout';
+    /** Props/params passed at the call site (e.g. { text: "Hello" }) */
+    invocationProps: Record<string, string | number>;
+    /** Reference to the root IR node produced by expanding the definition */
+    expandedRoot: {
+        ref: string;
+    };
+    style: IRNodeStyle;
+    /** meta.nodeId = SourceMap nodeId of the call-site AST node */
+    meta: IRMeta;
+}
 declare class IRGenerator {
     private idGen;
     private nodes;
@@ -441,6 +463,13 @@ declare class LayoutEngine {
     private calculateSplit;
     private calculatePanel;
     private calculateCard;
+    /**
+     * Calculate layout for an instance node.
+     * The instance is a transparent wrapper — its bounding box equals the
+     * expanded root's bounding box. We calculate the expanded root first and
+     * then copy its position to the instance nodeId so the renderer can use it.
+     */
+    private calculateInstance;
     private calculateComponent;
     private resolveSpacing;
     private getSeparateSize;
@@ -568,6 +597,12 @@ interface SVGRenderOptions {
     theme?: 'light' | 'dark';
     includeLabels?: boolean;
     screenName?: string;
+    /**
+     * When true, renders visual diagnostic overlays for invalid DSL states
+     * (e.g. empty containers). Enable in editor/canvas mode; leave false for
+     * clean exports (CLI, PDF, PNG).
+     */
+    showDiagnostics?: boolean;
 }
 interface SVGComponent {
     tag: string;
@@ -641,6 +676,16 @@ declare class SVGRenderer {
     protected renderTopbar(node: IRComponentNode, pos: any): string;
     protected renderPanelBorder(node: IRNode, pos: any, output: string[]): void;
     protected renderCardBorder(node: IRNode, pos: any, output: string[]): void;
+    /**
+     * Renders a yellow warning placeholder for containers with no children.
+     * Only shown when `showDiagnostics` is enabled (editor/canvas mode).
+     */
+    protected renderEmptyContainerDiagnostic(pos: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, containerType?: string): string;
     protected renderSplitDecoration(node: IRNode, pos: any, output: string[]): void;
     protected renderTable(node: IRComponentNode, pos: any): string;
     protected renderChartPlaceholder(node: IRComponentNode, pos: any): string;
@@ -750,7 +795,7 @@ declare class SVGRenderer {
      * Get data-node-id attribute string for SVG elements
      * Enables bidirectional selection between code and canvas
      */
-    protected getDataNodeId(node: IRComponentNode | IRContainerNode): string;
+    protected getDataNodeId(node: IRComponentNode | IRContainerNode | IRInstanceNode): string;
 }
 declare function renderToSVG(ir: IRContract, layout: LayoutResult, options?: SVGRenderOptions): string;
 declare function createSVGElement(tag: string, attrs: Record<string, string | number>, children?: string[]): string;
@@ -796,6 +841,12 @@ declare class SkeletonSVGRenderer extends SVGRenderer {
      * Render label as gray block
      */
     protected renderLabel(node: IRComponentNode, pos: any): string;
+    /**
+     * Render image as a plain skeleton rectangle — no icon, no placeholder label,
+     * just a filled block with the correct dimensions (aspect-ratio is preserved
+     * by the layout engine, so pos already has the right size).
+     */
+    protected renderImage(node: IRComponentNode, pos: any): string;
     /**
      * Render badge as shape only (no text)
      */
@@ -1342,4 +1393,4 @@ declare class SourceMapResolver {
 
 declare const version = "0.0.1";
 
-export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTDefinedLayout, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseDiagnosticsResult, type ParseError, type ParseResult, type ParseWireDSLWithSourceMapOptions, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };
+export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTDefinedLayout, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRInstanceNode, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseDiagnosticsResult, type ParseError, type ParseResult, type ParseWireDSLWithSourceMapOptions, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };