@constela/compiler 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Program, ConstelaError } from '@constela/core';
+import { Program, ConstelaError, LayoutProgram, ComponentDef, ViewNode } from '@constela/core';
 export { createUndefinedVarError } from '@constela/core';
 
 /**
@@ -16,6 +16,10 @@ interface AnalysisContext {
     stateNames: Set<string>;
     actionNames: Set<string>;
     componentNames: Set<string>;
+    routeParams: Set<string>;
+    importNames: Set<string>;
+    dataNames: Set<string>;
+    refNames: Set<string>;
 }
 interface AnalyzePassSuccess {
     ok: true;
@@ -40,6 +44,7 @@ type AnalyzePassResult = AnalyzePassSuccess | AnalyzePassFailure;
  * - Validates component references and props
  * - Detects component cycles
  * - Validates param references in component definitions
+ * - Validates data sources and getStaticPaths
  *
  * @param programAst - Validated AST from validate pass
  * @returns AnalyzePassResult
@@ -53,20 +58,36 @@ declare function analyzePass(programAst: Program): AnalyzePassResult;
  * that is optimized for runtime execution.
  */
 
+interface CompiledRouteDefinition {
+    path: string;
+    params: string[];
+    title?: CompiledExpression;
+    layout?: string;
+    meta?: Record<string, CompiledExpression>;
+}
+interface CompiledLifecycleHooks {
+    onMount?: string;
+    onUnmount?: string;
+    onRouteEnter?: string;
+    onRouteLeave?: string;
+}
 interface CompiledProgram {
     version: '1.0';
+    route?: CompiledRouteDefinition;
+    lifecycle?: CompiledLifecycleHooks;
     state: Record<string, {
         type: string;
         initial: unknown;
     }>;
     actions: Record<string, CompiledAction>;
     view: CompiledNode;
+    importData?: Record<string, unknown>;
 }
 interface CompiledAction {
     name: string;
     steps: CompiledActionStep[];
 }
-type CompiledActionStep = CompiledSetStep | CompiledUpdateStep | CompiledFetchStep;
+type CompiledActionStep = CompiledSetStep | CompiledUpdateStep | CompiledFetchStep | CompiledStorageStep | CompiledClipboardStep | CompiledNavigateStep | CompiledImportStep | CompiledCallStep | CompiledSubscribeStep | CompiledDisposeStep;
 interface CompiledSetStep {
     do: 'set';
     target: string;
@@ -89,10 +110,79 @@ interface CompiledFetchStep {
     onSuccess?: CompiledActionStep[];
     onError?: CompiledActionStep[];
 }
+interface CompiledStorageStep {
+    do: 'storage';
+    operation: 'get' | 'set' | 'remove';
+    key: CompiledExpression;
+    value?: CompiledExpression;
+    storage: 'local' | 'session';
+    result?: string;
+    onSuccess?: CompiledActionStep[];
+    onError?: CompiledActionStep[];
+}
+interface CompiledClipboardStep {
+    do: 'clipboard';
+    operation: 'write' | 'read';
+    value?: CompiledExpression;
+    result?: string;
+    onSuccess?: CompiledActionStep[];
+    onError?: CompiledActionStep[];
+}
+interface CompiledNavigateStep {
+    do: 'navigate';
+    url: CompiledExpression;
+    target?: '_self' | '_blank';
+    replace?: boolean;
+}
+/**
+ * Compiled ref expression
+ */
+interface CompiledRefExpr {
+    expr: 'ref';
+    name: string;
+}
+/**
+ * Compiled import step
+ */
+interface CompiledImportStep {
+    do: 'import';
+    module: string;
+    result: string;
+    onSuccess?: CompiledActionStep[];
+    onError?: CompiledActionStep[];
+}
+/**
+ * Compiled call step
+ */
+interface CompiledCallStep {
+    do: 'call';
+    target: CompiledExpression;
+    args?: CompiledExpression[];
+    result?: string;
+    onSuccess?: CompiledActionStep[];
+    onError?: CompiledActionStep[];
+}
+/**
+ * Compiled subscribe step
+ */
+interface CompiledSubscribeStep {
+    do: 'subscribe';
+    target: CompiledExpression;
+    event: string;
+    action: string;
+}
+/**
+ * Compiled dispose step
+ */
+interface CompiledDisposeStep {
+    do: 'dispose';
+    target: CompiledExpression;
+}
 type CompiledNode = CompiledElementNode | CompiledTextNode | CompiledIfNode | CompiledEachNode | CompiledMarkdownNode | CompiledCodeNode;
 interface CompiledElementNode {
     kind: 'element';
     tag: string;
+    ref?: string;
     props?: Record<string, CompiledExpression | CompiledEventHandler>;
     children?: CompiledNode[];
 }
@@ -123,7 +213,7 @@ interface CompiledCodeNode {
     language: CompiledExpression;
     content: CompiledExpression;
 }
-type CompiledExpression = CompiledLitExpr | CompiledStateExpr | CompiledVarExpr | CompiledBinExpr | CompiledNotExpr | CompiledCondExpr | CompiledGetExpr;
+type CompiledExpression = CompiledLitExpr | CompiledStateExpr | CompiledVarExpr | CompiledBinExpr | CompiledNotExpr | CompiledCondExpr | CompiledGetExpr | CompiledRouteExpr | CompiledImportExpr | CompiledRefExpr;
 interface CompiledLitExpr {
     expr: 'lit';
     value: string | number | boolean | null | unknown[];
@@ -158,6 +248,16 @@ interface CompiledGetExpr {
     base: CompiledExpression;
     path: string;
 }
+interface CompiledRouteExpr {
+    expr: 'route';
+    name: string;
+    source: 'param' | 'query' | 'path';
+}
+interface CompiledImportExpr {
+    expr: 'import';
+    name: string;
+    path?: string;
+}
 interface CompiledEventHandler {
     event: string;
     action: string;
@@ -168,9 +268,10 @@ interface CompiledEventHandler {
  *
  * @param ast - Validated AST from validate pass
  * @param _context - Analysis context from analyze pass (unused in current implementation)
+ * @param importData - Optional resolved import data to include in the compiled program
  * @returns CompiledProgram
  */
-declare function transformPass(ast: Program, _context: AnalysisContext): CompiledProgram;
+declare function transformPass(ast: Program, _context: AnalysisContext, importData?: Record<string, unknown>): CompiledProgram;
 
 /**
  * Main compile function for @constela/compiler
@@ -222,4 +323,71 @@ type ValidatePassResult = ValidatePassSuccess | ValidatePassFailure;
  */
 declare function validatePass(input: unknown): ValidatePassResult;
 
-export { type AnalysisContext, type AnalyzePassFailure, type AnalyzePassResult, type AnalyzePassSuccess, type CompileFailure, type CompileResult, type CompileSuccess, type CompiledAction, type CompiledActionStep, type CompiledCodeNode, type CompiledEachNode, type CompiledElementNode, type CompiledEventHandler, type CompiledExpression, type CompiledFetchStep, type CompiledIfNode, type CompiledMarkdownNode, type CompiledNode, type CompiledProgram, type CompiledSetStep, type CompiledTextNode, type CompiledUpdateStep, type ValidatePassFailure, type ValidatePassResult, type ValidatePassSuccess, analyzePass, compile, transformPass, validatePass };
+/**
+ * Layout Analysis Pass - Semantic validation for layout programs
+ *
+ * This pass performs semantic analysis on layout programs:
+ * - Validates that at least one slot node exists
+ * - Detects duplicate named slots
+ * - Validates state and action references within layouts
+ * - Warns/errors for slots inside loops
+ */
+
+interface LayoutAnalysisContext {
+    stateNames: Set<string>;
+    actionNames: Set<string>;
+    componentNames: Set<string>;
+    routeParams: Set<string>;
+    importNames: Set<string>;
+    slotNames: Set<string>;
+    hasDefaultSlot: boolean;
+}
+interface LayoutAnalysisSuccess {
+    ok: true;
+    context: LayoutAnalysisContext;
+}
+interface LayoutAnalysisFailure {
+    ok: false;
+    errors: ConstelaError[];
+}
+type LayoutAnalysisResult = LayoutAnalysisSuccess | LayoutAnalysisFailure;
+/**
+ * Performs static analysis on a layout program
+ *
+ * - Validates at least one slot exists
+ * - Detects duplicate slot names
+ * - Validates state references
+ * - Validates action references
+ *
+ * @param layout - Layout program to analyze
+ * @returns LayoutAnalysisResult
+ */
+declare function analyzeLayoutPass(layout: LayoutProgram): LayoutAnalysisResult;
+
+/**
+ * Layout Transform Pass - Layout to CompiledProgram transformation and composition
+ *
+ * This pass transforms layout programs and composes them with page programs.
+ */
+
+interface CompiledLayoutProgram {
+    version: '1.0';
+    type: 'layout';
+    state: Record<string, {
+        type: string;
+        initial: unknown;
+    }>;
+    actions: CompiledAction[];
+    view: CompiledNode;
+    components?: Record<string, ComponentDef> | undefined;
+}
+/**
+ * Transforms a layout program into a compiled layout
+ */
+declare function transformLayoutPass(layout: LayoutProgram, _context: LayoutAnalysisContext): CompiledLayoutProgram;
+/**
+ * Composes a layout with a page, inserting page content into slots
+ */
+declare function composeLayoutWithPage(layout: CompiledProgram, page: CompiledProgram, 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 CompiledCallStep, type CompiledClipboardStep, type CompiledCodeNode, type CompiledDisposeStep, type CompiledEachNode, type CompiledElementNode, type CompiledEventHandler, type CompiledExpression, type CompiledFetchStep, type CompiledIfNode, type CompiledImportExpr, type CompiledImportStep, type CompiledLayoutProgram, type CompiledLifecycleHooks, type CompiledMarkdownNode, type CompiledNavigateStep, type CompiledNode, type CompiledProgram, type CompiledRefExpr, type CompiledRouteDefinition, type CompiledRouteExpr, type CompiledSetStep, type CompiledStorageStep, type CompiledSubscribeStep, type CompiledTextNode, type CompiledUpdateStep, type LayoutAnalysisContext, type LayoutAnalysisFailure, type LayoutAnalysisResult, type LayoutAnalysisSuccess, type ValidatePassFailure, type ValidatePassResult, type ValidatePassSuccess, analyzeLayoutPass, analyzePass, compile, composeLayoutWithPage, transformLayoutPass, transformPass, validatePass };