@constela/compiler 0.9.1 → 0.11.0

package/README.md

@@ -50,6 +50,8 @@ The compiler transforms JSON programs through three passes:
 - **setPath** - Compiles to efficient path-based state updates
 - **Key-based each** - Compiles key expressions for list diffing
 - **WebSocket connections** - Compiles connection definitions and send/close actions
+- **concat expression** - Compiles string concatenation expressions
+- **Object payloads** - Supports object-shaped event handler payloads with expression fields
 
 ## CompiledProgram Structure
 

package/dist/index.d.ts

@@ -89,7 +89,7 @@ interface CompiledAction {
     name: string;
     steps: CompiledActionStep[];
 }
-type CompiledActionStep = CompiledSetStep | CompiledUpdateStep | CompiledSetPathStep | CompiledFetchStep | CompiledStorageStep | CompiledClipboardStep | CompiledNavigateStep | CompiledImportStep | CompiledCallStep | CompiledSubscribeStep | CompiledDisposeStep | CompiledDomStep | CompiledIfStep | CompiledSendStep | CompiledCloseStep;
+type CompiledActionStep = CompiledSetStep | CompiledUpdateStep | CompiledSetPathStep | CompiledFetchStep | CompiledStorageStep | CompiledClipboardStep | CompiledNavigateStep | CompiledImportStep | CompiledCallStep | CompiledSubscribeStep | CompiledDisposeStep | CompiledDomStep | CompiledIfStep | CompiledSendStep | CompiledCloseStep | CompiledDelayStep | CompiledIntervalStep | CompiledClearTimerStep | CompiledFocusStep;
 interface CompiledSetStep {
     do: 'set';
     target: string;
@@ -217,7 +217,61 @@ interface CompiledCloseStep {
     do: 'close';
     connection: string;
 }
-type CompiledNode = CompiledElementNode | CompiledTextNode | CompiledIfNode | CompiledEachNode | CompiledMarkdownNode | CompiledCodeNode | CompiledSlotNode;
+/**
+ * Compiled delay step - executes steps after a delay (setTimeout equivalent)
+ */
+interface CompiledDelayStep {
+    do: 'delay';
+    ms: CompiledExpression;
+    then: CompiledActionStep[];
+    result?: string;
+}
+/**
+ * Compiled interval step - executes an action repeatedly (setInterval equivalent)
+ */
+interface CompiledIntervalStep {
+    do: 'interval';
+    ms: CompiledExpression;
+    action: string;
+    result?: string;
+}
+/**
+ * Compiled clearTimer step - clears a timer (clearTimeout/clearInterval equivalent)
+ */
+interface CompiledClearTimerStep {
+    do: 'clearTimer';
+    target: CompiledExpression;
+}
+/**
+ * Compiled focus step - manages form element focus
+ */
+interface CompiledFocusStep {
+    do: 'focus';
+    target: CompiledExpression;
+    operation: 'focus' | 'blur' | 'select';
+    onSuccess?: CompiledActionStep[];
+    onError?: CompiledActionStep[];
+}
+/**
+ * Compiled local action
+ */
+interface CompiledLocalAction {
+    name: string;
+    steps: CompiledActionStep[];
+}
+/**
+ * Compiled local state node - wraps component with local state
+ */
+interface CompiledLocalStateNode {
+    kind: 'localState';
+    state: Record<string, {
+        type: string;
+        initial: unknown;
+    }>;
+    actions: Record<string, CompiledLocalAction>;
+    child: CompiledNode;
+}
+type CompiledNode = CompiledElementNode | CompiledTextNode | CompiledIfNode | CompiledEachNode | CompiledMarkdownNode | CompiledCodeNode | CompiledSlotNode | CompiledPortalNode | CompiledLocalStateNode;
 interface CompiledElementNode {
     kind: 'element';
     tag: string;
@@ -256,7 +310,12 @@ interface CompiledSlotNode {
     kind: 'slot';
     name?: string;
 }
-type CompiledExpression = CompiledLitExpr | CompiledStateExpr | CompiledVarExpr | CompiledBinExpr | CompiledNotExpr | CompiledCondExpr | CompiledGetExpr | CompiledRouteExpr | CompiledImportExpr | CompiledDataExpr | CompiledRefExpr | CompiledIndexExpr | CompiledParamExpr | CompiledStyleExpr | CompiledConcatExpr;
+interface CompiledPortalNode {
+    kind: 'portal';
+    target: 'body' | 'head' | string;
+    children: CompiledNode[];
+}
+type CompiledExpression = CompiledLitExpr | CompiledStateExpr | CompiledVarExpr | CompiledBinExpr | CompiledNotExpr | CompiledCondExpr | CompiledGetExpr | CompiledRouteExpr | CompiledImportExpr | CompiledDataExpr | CompiledRefExpr | CompiledIndexExpr | CompiledParamExpr | CompiledStyleExpr | CompiledConcatExpr | CompiledValidityExpr;
 interface CompiledLitExpr {
     expr: 'lit';
     value: string | number | boolean | null | unknown[];
@@ -326,10 +385,26 @@ interface CompiledConcatExpr {
     expr: 'concat';
     items: CompiledExpression[];
 }
+interface CompiledValidityExpr {
+    expr: 'validity';
+    ref: string;
+    property?: string;
+}
+/**
+ * Compiled event handler options for special events like intersect
+ */
+interface CompiledEventHandlerOptions {
+    threshold?: number;
+    rootMargin?: string;
+    once?: boolean;
+}
 interface CompiledEventHandler {
     event: string;
     action: string;
     payload?: CompiledExpression | Record<string, CompiledExpression>;
+    debounce?: number;
+    throttle?: number;
+    options?: CompiledEventHandlerOptions;
 }
 /**
  * Transforms the validated and analyzed AST into a CompiledProgram
@@ -459,4 +534,4 @@ declare function transformLayoutPass(layout: LayoutProgram, _context: LayoutAnal
  */
 declare function composeLayoutWithPage(layout: CompiledProgram, page: CompiledProgram, layoutParams?: Record<string, Expression>, slots?: Record<string, ViewNode>): CompiledProgram;
 
-export { type AnalysisContext, type AnalyzePassFailure, type AnalyzePassResult, type AnalyzePassSuccess, type CompileFailure, type CompileResult, type CompileSuccess, type CompiledAction, type CompiledActionStep, type CompiledBinExpr, type CompiledCallStep, type CompiledClipboardStep, type CompiledCloseStep, type CompiledCodeNode, type CompiledConcatExpr, type CompiledCondExpr, type CompiledDataExpr, type CompiledDisposeStep, type CompiledDomStep, type CompiledEachNode, type CompiledElementNode, type CompiledEventHandler, type CompiledExpression, type CompiledFetchStep, type CompiledGetExpr, type CompiledIfNode, type CompiledIfStep, type CompiledImportExpr, type CompiledImportStep, type CompiledIndexExpr, type CompiledLayoutProgram, type CompiledLifecycleHooks, type CompiledLitExpr, type CompiledMarkdownNode, type CompiledNavigateStep, type CompiledNode, type CompiledNotExpr, type CompiledParamExpr, type CompiledProgram, type CompiledRefExpr, type CompiledRouteDefinition, type CompiledRouteExpr, type CompiledSendStep, type CompiledSetPathStep, type CompiledSetStep, type CompiledSlotNode, type CompiledStateExpr, type CompiledStorageStep, type CompiledStyleExpr, type CompiledSubscribeStep, type CompiledTextNode, type CompiledUpdateStep, type CompiledVarExpr, type LayoutAnalysisContext, type LayoutAnalysisFailure, type LayoutAnalysisResult, type LayoutAnalysisSuccess, type ValidatePassFailure, type ValidatePassResult, type ValidatePassSuccess, analyzeLayoutPass, analyzePass, compile, composeLayoutWithPage, transformLayoutPass, transformPass, validatePass };
+export { type AnalysisContext, type AnalyzePassFailure, type AnalyzePassResult, type AnalyzePassSuccess, type CompileFailure, type CompileResult, type CompileSuccess, type CompiledAction, type CompiledActionStep, type CompiledBinExpr, type CompiledCallStep, type CompiledClearTimerStep, type CompiledClipboardStep, type CompiledCloseStep, type CompiledCodeNode, type CompiledConcatExpr, type CompiledCondExpr, type CompiledDataExpr, type CompiledDelayStep, type CompiledDisposeStep, type CompiledDomStep, type CompiledEachNode, type CompiledElementNode, type CompiledEventHandler, type CompiledEventHandlerOptions, type CompiledExpression, type CompiledFetchStep, type CompiledFocusStep, type CompiledGetExpr, type CompiledIfNode, type CompiledIfStep, type CompiledImportExpr, type CompiledImportStep, type CompiledIndexExpr, type CompiledIntervalStep, type CompiledLayoutProgram, type CompiledLifecycleHooks, type CompiledLitExpr, type CompiledLocalAction, type CompiledLocalStateNode, type CompiledMarkdownNode, type CompiledNavigateStep, type CompiledNode, type CompiledNotExpr, type CompiledParamExpr, type CompiledPortalNode, type CompiledProgram, type CompiledRefExpr, type CompiledRouteDefinition, type CompiledRouteExpr, type CompiledSendStep, type CompiledSetPathStep, type CompiledSetStep, type CompiledSlotNode, type CompiledStateExpr, type CompiledStorageStep, type CompiledStyleExpr, type CompiledSubscribeStep, type CompiledTextNode, type CompiledUpdateStep, type CompiledValidityExpr, type CompiledVarExpr, type LayoutAnalysisContext, type LayoutAnalysisFailure, type LayoutAnalysisResult, type LayoutAnalysisSuccess, type ValidatePassFailure, type ValidatePassResult, type ValidatePassSuccess, analyzeLayoutPass, analyzePass, compile, composeLayoutWithPage, transformLayoutPass, transformPass, validatePass };

package/dist/index.js

@@ -44,6 +44,8 @@ import {
   createUndefinedRefError,
   createUndefinedStyleError,
   createUndefinedVariantError,
+  createUndefinedLocalStateError,
+  createLocalActionInvalidStepError,
   findSimilarNames,
   isEventHandler,
   DATA_SOURCE_TYPES,
@@ -157,12 +159,19 @@ function checkDuplicateActions(ast2) {
 function validateExpression(expr, path, context, scope, paramScope) {
   const errors = [];
   switch (expr.expr) {
-    case "state":
-      if (!context.stateNames.has(expr.name)) {
-        const errorOptions = createErrorOptionsWithSuggestion(expr.name, context.stateNames);
+    case "state": {
+      const isGlobalState = context.stateNames.has(expr.name);
+      const isLocalState = paramScope?.localStateNames?.has(expr.name) ?? false;
+      if (!isGlobalState && !isLocalState) {
+        const availableNames = /* @__PURE__ */ new Set([
+          ...context.stateNames,
+          ...paramScope?.localStateNames ?? []
+        ]);
+        const errorOptions = createErrorOptionsWithSuggestion(expr.name, availableNames);
         errors.push(createUndefinedStateError(expr.name, path, errorOptions));
       }
       break;
+    }
     case "var":
       if (!scope.has(expr.name)) {
         errors.push(createUndefinedVarError(expr.name, path));
@@ -706,8 +715,14 @@ function validateViewNode(node, path, context, scope, options = { insideComponen
         for (const [propName, propValue] of Object.entries(node.props)) {
           const propPath = buildPath(path, "props", propName);
           if (isEventHandler(propValue)) {
-            if (!context.actionNames.has(propValue.action)) {
-              const errorOptions = createErrorOptionsWithSuggestion(propValue.action, context.actionNames);
+            const isGlobalAction = context.actionNames.has(propValue.action);
+            const isLocalAction = paramScope?.localActionNames?.has(propValue.action) ?? false;
+            if (!isGlobalAction && !isLocalAction) {
+              const availableNames = /* @__PURE__ */ new Set([
+                ...context.actionNames,
+                ...paramScope?.localActionNames ?? []
+              ]);
+              const errorOptions = createErrorOptionsWithSuggestion(propValue.action, availableNames);
               errors.push(createUndefinedActionError(propValue.action, propPath, errorOptions));
             }
             if (propValue.payload) {
@@ -910,21 +925,58 @@ function detectComponentCycles(programAst, context) {
   }
   return errors;
 }
+function validateLocalActions(localActions, localStateNames, componentPath) {
+  const errors = [];
+  for (let i = 0; i < localActions.length; i++) {
+    const action = localActions[i];
+    if (!action) continue;
+    const actionPath = buildPath(componentPath, "localActions", i);
+    for (let j = 0; j < action.steps.length; j++) {
+      const step = action.steps[j];
+      if (!step) continue;
+      const stepPath = buildPath(actionPath, "steps", j);
+      const stepDo = step.do;
+      if (stepDo !== "set" && stepDo !== "update" && stepDo !== "setPath") {
+        errors.push(createLocalActionInvalidStepError(stepDo, stepPath));
+        continue;
+      }
+      if (!localStateNames.has(step.target)) {
+        const errorOptions = createErrorOptionsWithSuggestion(step.target, localStateNames);
+        errors.push(createUndefinedLocalStateError(step.target, buildPath(stepPath, "target"), errorOptions));
+      }
+    }
+  }
+  return errors;
+}
 function validateComponents(programAst, context) {
   const errors = [];
   if (!programAst.components) return errors;
   for (const [name, def] of Object.entries(programAst.components)) {
+    const componentPath = buildPath("", "components", name);
+    const localStateNames = new Set(
+      def.localState ? Object.keys(def.localState) : []
+    );
+    const localActionNames = new Set(
+      def.localActions ? def.localActions.map((a) => a.name) : []
+    );
     const paramNames = new Set(
       def.params ? Object.keys(def.params) : []
     );
     const paramScope = {
       params: paramNames,
-      componentName: name
+      componentName: name,
+      localStateNames,
+      localActionNames
     };
+    if (def.localActions && def.localActions.length > 0) {
+      errors.push(
+        ...validateLocalActions(def.localActions, localStateNames, componentPath)
+      );
+    }
     errors.push(
       ...validateViewNode(
         def.view,
-        buildPath("", "components", name, "view"),
+        buildPath(componentPath, "view"),
         context,
         /* @__PURE__ */ new Set(),
         { insideComponent: true, paramScope }
@@ -1183,6 +1235,16 @@ function transformExpression(expr, ctx) {
         expr: "concat",
         items: expr.items.map((item) => transformExpression(item, ctx))
       };
+    case "validity": {
+      const validityExpr = {
+        expr: "validity",
+        ref: expr.ref
+      };
+      if (expr.property) {
+        validityExpr.property = expr.property;
+      }
+      return validityExpr;
+    }
   }
 }
 function transformEventHandler(handler, ctx) {
@@ -1193,6 +1255,24 @@ function transformEventHandler(handler, ctx) {
   if (handler.payload) {
     result.payload = transformExpression(handler.payload, ctx);
   }
+  if (handler.debounce !== void 0) {
+    result.debounce = handler.debounce;
+  }
+  if (handler.throttle !== void 0) {
+    result.throttle = handler.throttle;
+  }
+  if (handler.options) {
+    result.options = {};
+    if (handler.options.threshold !== void 0) {
+      result.options.threshold = handler.options.threshold;
+    }
+    if (handler.options.rootMargin !== void 0) {
+      result.options.rootMargin = handler.options.rootMargin;
+    }
+    if (handler.options.once !== void 0) {
+      result.options.once = handler.options.once;
+    }
+  }
   return result;
 }
 var emptyContext = { components: {} };
@@ -1384,6 +1464,52 @@ function transformActionStep(step) {
         connection: closeStep.connection
       };
     }
+    case "delay": {
+      const delayStep = step;
+      const compiledDelayStep = {
+        do: "delay",
+        ms: transformExpression(delayStep.ms, emptyContext),
+        then: delayStep.then.map(transformActionStep)
+      };
+      if (delayStep.result) {
+        compiledDelayStep.result = delayStep.result;
+      }
+      return compiledDelayStep;
+    }
+    case "interval": {
+      const intervalStep = step;
+      const compiledIntervalStep = {
+        do: "interval",
+        ms: transformExpression(intervalStep.ms, emptyContext),
+        action: intervalStep.action
+      };
+      if (intervalStep.result) {
+        compiledIntervalStep.result = intervalStep.result;
+      }
+      return compiledIntervalStep;
+    }
+    case "clearTimer": {
+      const clearTimerStep = step;
+      return {
+        do: "clearTimer",
+        target: transformExpression(clearTimerStep.target, emptyContext)
+      };
+    }
+    case "focus": {
+      const focusStep = step;
+      const compiledFocusStep = {
+        do: "focus",
+        target: transformExpression(focusStep.target, emptyContext),
+        operation: focusStep.operation
+      };
+      if (focusStep.onSuccess) {
+        compiledFocusStep.onSuccess = focusStep.onSuccess.map(transformActionStep);
+      }
+      if (focusStep.onError) {
+        compiledFocusStep.onError = focusStep.onError.map(transformActionStep);
+      }
+      return compiledFocusStep;
+    }
   }
 }
 function flattenSlotChildren(children, ctx) {
@@ -1480,7 +1606,16 @@ function transformViewNode(node, ctx) {
         currentParams: params,
         currentChildren: children
       };
-      return transformViewNode(def.view, newCtx);
+      const expandedView = transformViewNode(def.view, newCtx);
+      if (def.localState && Object.keys(def.localState).length > 0) {
+        return {
+          kind: "localState",
+          state: transformLocalState(def.localState),
+          actions: transformLocalActions(def.localActions ?? []),
+          child: expandedView
+        };
+      }
+      return expandedView;
     }
     case "markdown":
       return {
@@ -1507,6 +1642,18 @@ function transformViewNode(node, ctx) {
       }
       return { kind: "text", value: { expr: "lit", value: "" } };
     }
+    case "portal": {
+      const portalNode = node;
+      const compiledChildren = [];
+      for (const child of portalNode.children) {
+        compiledChildren.push(transformViewNode(child, ctx));
+      }
+      return {
+        kind: "portal",
+        target: portalNode.target,
+        children: compiledChildren
+      };
+    }
   }
 }
 function transformState(state) {
@@ -1519,6 +1666,23 @@ function transformState(state) {
   }
   return compiledState;
 }
+function transformLocalState(localState) {
+  const result = {};
+  for (const [name, field] of Object.entries(localState)) {
+    result[name] = { type: field.type, initial: field.initial };
+  }
+  return result;
+}
+function transformLocalActions(localActions) {
+  const result = {};
+  for (const action of localActions) {
+    result[action.name] = {
+      name: action.name,
+      steps: action.steps.map(transformActionStep)
+    };
+  }
+  return result;
+}
 function transformActions(actions) {
   const compiledActions = {};
   for (const action of actions) {
@@ -2176,6 +2340,14 @@ function transformViewNode2(node, ctx) {
         language: node.language,
         content: node.content
       };
+    case "portal":
+      return {
+        kind: "portal",
+        target: node.target,
+        children: (node.children ?? []).map(
+          (child) => transformViewNode2(child, ctx)
+        )
+      };
   }
 }
 function transformLayoutPass(layout, _context) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/compiler",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Compiler for Constela UI framework - AST to Program transformation",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,7 @@
     "dist"
   ],
   "dependencies": {
-    "@constela/core": "0.9.1"
+    "@constela/core": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",