@wire-dsl/engine 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -31,10 +31,21 @@ interface PropertySourceMap {
     nameRange: CodeRange;
     valueRange: CodeRange;
 }
+/**
+ * SourceMap for a single event handler
+ * Captures ranges for event name and the full action expression
+ */
+interface EventSourceMap {
+    name: string;
+    value: string;
+    range: CodeRange;
+    nameRange: CodeRange;
+    valueRange: CodeRange;
+}
 /**
  * Types of nodes in Wire DSL
  */
-type SourceMapNodeType = 'project' | 'screen' | 'layout' | 'component' | 'component-definition' | 'layout-definition' | 'cell' | 'style' | 'mocks' | 'colors';
+type SourceMapNodeType = 'project' | 'screen' | 'layout' | 'component' | 'component-definition' | 'layout-definition' | 'cell' | 'tab' | 'modal-body' | 'modal-footer' | 'style' | 'mocks' | 'colors';
 /**
  * Main SourceMap entry - represents one node in the AST
  */
@@ -53,6 +64,7 @@ interface SourceMapEntry {
     nameRange?: CodeRange;
     bodyRange?: CodeRange;
     properties?: Record<string, PropertySourceMap>;
+    events?: Record<string, EventSourceMap>;
     insertionPoint?: InsertionPoint;
 }
 /**
@@ -138,24 +150,58 @@ interface ASTDefinedComponent {
 interface ASTScreen {
     type: 'screen';
     name: string;
-    params: Record<string, string | number>;
+    params: Record<string, string | number | string[]>;
     layout: ASTLayout;
     _meta?: {
         nodeId: string;
     };
 }
+type ASTEventActionType = 'navigate' | 'show' | 'hide' | 'toggle' | 'enable' | 'disable' | 'setTab';
+interface ASTEventAction {
+    type: ASTEventActionType;
+    screen?: string;
+    targetId?: string;
+    tabsId?: string;
+    index?: number;
+}
+interface ASTEventHandler {
+    event: string;
+    actions: ASTEventAction[];
+}
+interface ASTTab {
+    type: 'tab';
+    children: (ASTComponent | ASTLayout)[];
+    _meta?: {
+        nodeId: string;
+    };
+}
+interface ASTModalBody {
+    type: 'modal-body';
+    children: (ASTComponent | ASTLayout)[];
+    _meta?: {
+        nodeId: string;
+    };
+}
+interface ASTModalFooter {
+    type: 'modal-footer';
+    children: (ASTComponent | ASTLayout)[];
+    _meta?: {
+        nodeId: string;
+    };
+}
 interface ASTLayout {
     type: 'layout';
     layoutType: string;
-    params: Record<string, string | number>;
-    children: (ASTComponent | ASTLayout | ASTCell)[];
+    params: Record<string, string | number | string[]>;
+    events: ASTEventHandler[];
+    children: (ASTComponent | ASTLayout | ASTCell | ASTTab | ASTModalBody | ASTModalFooter)[];
     _meta?: {
         nodeId: string;
     };
 }
 interface ASTCell {
     type: 'cell';
-    props: Record<string, string | number>;
+    props: Record<string, string | number | string[]>;
     children: (ASTComponent | ASTLayout)[];
     _meta?: {
         nodeId: string;
@@ -164,7 +210,8 @@ interface ASTCell {
 interface ASTComponent {
     type: 'component';
     componentType: string;
-    props: Record<string, string | number>;
+    props: Record<string, string | number | string[]>;
+    events: ASTEventHandler[];
     _meta?: {
         nodeId: string;
     };
@@ -267,15 +314,49 @@ interface IRScreen {
         ref: string;
     };
 }
+type IREventAction = {
+    type: 'navigate';
+    screen: string;
+} | {
+    type: 'show';
+    targetId: string;
+} | {
+    type: 'hide';
+    targetId: string;
+} | {
+    type: 'toggle';
+    targetId: string;
+} | {
+    type: 'enable';
+    targetId: string;
+} | {
+    type: 'disable';
+    targetId: string;
+} | {
+    type: 'setTab';
+    tabsId: string;
+    index: number;
+} | {
+    type: 'navigateItems';
+    screens: string[];
+};
+type IREventName = 'onClick' | 'onChange' | 'onActive' | 'onInactive' | 'onItemsClick' | 'onItemClick' | 'onRowClick' | 'onClose';
+interface IREventHandler {
+    event: IREventName;
+    actions: IREventAction[];
+}
+/** Special target id used when event target is self (hide(self), show(self), toggle(self)) */
+declare const SELF_TARGET = "_self";
 type IRNode = IRContainerNode | IRComponentNode | IRInstanceNode;
 interface IRContainerNode {
     id: string;
     kind: 'container';
-    containerType: 'stack' | 'grid' | 'split' | 'panel' | 'card';
-    params: Record<string, string | number>;
+    containerType: 'stack' | 'grid' | 'split' | 'panel' | 'card' | 'tabs' | 'tab' | 'modal' | 'modal-body' | 'modal-footer';
+    params: Record<string, string | number | string[]>;
     children: Array<{
         ref: string;
     }>;
+    events?: IREventHandler[];
     style: IRNodeStyle;
     meta: IRMeta;
 }
@@ -283,7 +364,9 @@ interface IRComponentNode {
     id: string;
     kind: 'component';
     componentType: string;
-    props: Record<string, string | number>;
+    props: Record<string, string | number | string[]>;
+    userDefinedId?: string;
+    events?: IREventHandler[];
     style: IRNodeStyle;
     meta: IRMeta;
 }
@@ -311,7 +394,7 @@ interface IRInstanceNode {
     /** 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>;
+    invocationProps: Record<string, string | number | string[]>;
     /** Reference to the root IR node produced by expanding the definition */
     expandedRoot: {
         ref: string;
@@ -350,8 +433,14 @@ declare class IRGenerator {
         type: string;
     }>;
     private convertLayout;
+    private convertTab;
+    private convertModalBody;
+    private convertModalFooter;
     private convertCell;
     private convertComponent;
+    private convertASTEventAction;
+    private convertASTEvents;
+    private extractOnItemsClickEvent;
     private expandDefinedComponent;
     private expandDefinedLayout;
     private resolveChildrenSlot;
@@ -431,6 +520,86 @@ declare function resolveDevicePreset(device: string): {
  */
 declare function isValidDevice(device: string): boolean;
 
+/**
+ * Wire DSL Play Test State Management
+ *
+ * Provides the `applyStateChange` function for mutating a copy of the IR
+ * during play test sessions. The engine stays 100% static — this module
+ * produces a NEW IR (immutable pattern) from a change descriptor.
+ *
+ * The Wire source is never touched during play test. The canvas keeps a
+ * mutable copy of the IR per session and discards it when play test ends.
+ *
+ * Usage (Wire Studio / Canvas):
+ *   const newIR = applyStateChange(currentIR, { type: 'setVisible', targetId: 'confirmModal', visible: true });
+ *   const newSVG = render(newIR, screenName);
+ */
+
+type IRStateChange = 
+/** Show or hide a node by its userDefinedId (or '_self' resolved from originNodeId) */
+{
+    type: 'setVisible';
+    targetId: string;
+    visible: boolean;
+}
+/** Toggle visibility of a node by its userDefinedId (or '_self') */
+ | {
+    type: 'toggleVisible';
+    targetId: string;
+}
+/** Change the active tab index in a layout tabs container */
+ | {
+    type: 'setActiveTab';
+    tabsId: string;
+    index: number;
+}
+/** Set checked state on Checkbox / Radio controls */
+ | {
+    type: 'setChecked';
+    targetId: string;
+    checked: boolean;
+}
+/** Toggle checked state on Checkbox / Radio controls */
+ | {
+    type: 'toggleChecked';
+    targetId: string;
+}
+/** Set enabled state on Toggle controls */
+ | {
+    type: 'setEnabled';
+    targetId: string;
+    enabled: boolean;
+}
+/** Toggle enabled state on Toggle controls */
+ | {
+    type: 'toggleEnabled';
+    targetId: string;
+}
+/** Set disabled state on any component (enable = disabled false, disable = disabled true) */
+ | {
+    type: 'setDisabled';
+    targetId: string;
+    disabled: boolean;
+}
+/** Navigate to a different screen (changes the active screen id in the IR) */
+ | {
+    type: 'navigateTo';
+    screen: string;
+};
+/**
+ * Apply a state change to a copy of the IR, returning a new IR object.
+ *
+ * - Does NOT mutate the input IR
+ * - Returns a new IR with the minimal change applied
+ * - `originNodeId` is required when `targetId === '_self'` to resolve the self reference
+ *
+ * @param ir           The current IR (from the canvas's mutable session copy)
+ * @param change       The state change to apply
+ * @param originNodeId The nodeId of the element that triggered the event (required for self-target)
+ * @returns A new IR with the change applied
+ */
+declare function applyStateChange(ir: IRContract, change: IRStateChange, originNodeId?: string): IRContract;
+
 /**
  * Layout Engine
  *
@@ -463,6 +632,8 @@ declare class LayoutEngine {
     private calculateSplit;
     private calculatePanel;
     private calculateCard;
+    private calculateTabs;
+    private calculateModal;
     /**
      * Calculate layout for an instance node.
      * The instance is a transparent wrapper — its bounding box equals the
@@ -497,6 +668,11 @@ declare class LayoutEngine {
     private calculateChildHeight;
     private calculateChildWidth;
     private estimateTextWidth;
+    /**
+     * Returns false only when the node has an explicit `visible: 'false'` param/prop.
+     * Missing or any other value is treated as visible.
+     */
+    private isNodeVisible;
     private parseBooleanProp;
     private adjustNodeYPositions;
 }
@@ -717,7 +893,8 @@ declare class SVGRenderer {
     protected renderSeparate(node: IRComponentNode, _pos: any): string;
     protected renderAlert(node: IRComponentNode, pos: any): string;
     protected renderBadge(node: IRComponentNode, pos: any): string;
-    protected renderModal(node: IRComponentNode, pos: any): string;
+    protected renderModalDecoration(node: IRNode, pos: any, output: string[]): void;
+    protected renderModalFooterDecoration(pos: any, output: string[]): void;
     protected renderList(node: IRComponentNode, pos: any): string;
     protected renderGenericComponent(node: IRComponentNode, pos: any): string;
     protected renderStat(node: IRComponentNode, pos: any): string;
@@ -806,10 +983,17 @@ declare class SVGRenderer {
     private buildParentContainerIndex;
     protected escapeXml(text: string): string;
     /**
-     * Get data-node-id attribute string for SVG elements
-     * Enables bidirectional selection between code and canvas
+     * Get data-node-id and event data attributes for SVG elements.
+     * Enables bidirectional selection between code and canvas (data-node-id)
+     * and play test interactivity (data-event-*, data-user-id, data-tabs-id).
      */
     protected getDataNodeId(node: IRComponentNode | IRContainerNode | IRInstanceNode): string;
+    private isScopedEvent;
+    private getScopedEventAttrs;
+    private getTabsTriggerAttrs;
+    private serializeEventHandler;
+    private eventNameToDataAttr;
+    private serializeEventAction;
 }
 declare function renderToSVG(ir: IRContract, layout: LayoutResult, options?: SVGRenderOptions): string;
 declare function createSVGElement(tag: string, attrs: Record<string, string | number>, children?: string[]): string;
@@ -1218,6 +1402,19 @@ declare class SourceMapBuilder {
         separator?: any;
         full?: any;
     }): PropertySourceMap;
+    /**
+     * Add an event handler to an existing node in the SourceMap
+     * Events have action expressions as values (e.g., "show(modal) & navigate(Home)")
+     *
+     * @param nodeId - ID of the node that owns this event
+     * @param eventName - Name of the event (e.g., "onClick", "onClose")
+     * @param tokens - Captured tokens: name token for event key, CST node for actionChain
+     * @returns The EventSourceMap entry created
+     */
+    addEvent(nodeId: string, eventName: string, tokens: {
+        name: any;
+        value: any;
+    }): EventSourceMap;
     /**
      * Push a parent onto the stack (when entering a container node)
      */
@@ -1404,4 +1601,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 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 };
+export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTDefinedLayout, type ASTEventAction, type ASTEventActionType, type ASTEventHandler, type ASTLayout, type ASTModalBody, type ASTModalFooter, type ASTScreen, type ASTTab, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type EventSourceMap, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, type IREventAction, type IREventHandler, type IREventName, IRGenerator, type IRInstanceNode, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStateChange, 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, SELF_TARGET, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, applyStateChange, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };