@constela/compiler 0.7.1 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @constela/compiler
 
-Compiler for the Constela UI framework - transforms AST to optimized runtime programs.
+Transforms Constela JSON programs into optimized runtime code.
 
 ## Installation
 
@@ -8,96 +8,88 @@ Compiler for the Constela UI framework - transforms AST to optimized runtime pro
 npm install @constela/compiler
 ```
 
-## Overview
+## Usage
 
-This package transforms validated Constela AST into optimized `CompiledProgram` structures for runtime execution. It implements a three-pass compiler pipeline:
-
-1. **Validate Pass** - Schema and syntax validation
-2. **Analyze Pass** - Semantic analysis and context collection
-3. **Transform Pass** - AST-to-Program transformation
-
-## API Reference
-
-### compile
-
-Main compilation function that orchestrates the entire pipeline.
-
-```typescript
-import { compile } from '@constela/compiler';
-
-const result = compile(input);
-
-if (result.ok) {
-  // Success
-  console.log(result.program);
-} else {
-  // Failure - array of errors
-  console.error(result.errors);
-}
+```bash
+constela compile app.json --out dist/app.compiled.json
 ```
 
-**Parameters:**
-- `input: unknown` - Raw program input (typically parsed JSON)
-
-**Returns:** `CompileResult`
-- Success: `{ ok: true, program: CompiledProgram }`
-- Failure: `{ ok: false, errors: ConstelaError[] }`
-
-### Individual Passes
-
-#### validatePass
-
-```typescript
-import { validatePass } from '@constela/compiler';
+## JSON Input
 
-const result = validatePass(input);
-if (result.ok) {
-  // result.program is a validated Program
+```json
+{
+  "version": "1.0",
+  "state": {
+    "count": { "type": "number", "initial": 0 }
+  },
+  "actions": [
+    {
+      "name": "increment",
+      "steps": [{ "do": "update", "target": "count", "operation": "increment" }]
+    }
+  ],
+  "view": {
+    "kind": "element",
+    "tag": "button",
+    "props": { "onClick": { "event": "click", "action": "increment" } },
+    "children": [{ "kind": "text", "value": { "expr": "state", "name": "count" } }]
+  }
 }
 ```
 
-#### analyzePass
-
-```typescript
-import { analyzePass } from '@constela/compiler';
-
-const result = analyzePass(validatedProgram);
-if (result.ok) {
-  // result.context contains analysis results
-  console.log(result.context.stateNames);
-  console.log(result.context.actionNames);
-}
-```
+## Compiler Pipeline
 
-**AnalysisContext:**
-- `stateNames: Set<string>` - State field identifiers
-- `actionNames: Set<string>` - Action names
-- `componentNames: Set<string>` - Component identifiers
-- `routeParams: Set<string>` - Route parameter names
-- `importNames: Set<string>` - External import names
-- `dataNames: Set<string>` - Data source names
-- `refNames: Set<string>` - DOM element reference names
+The compiler transforms JSON programs through three passes:
 
-#### transformPass
+1. **Validate** - JSON Schema validation
+2. **Analyze** - Semantic analysis (state, actions, components, routes)
+3. **Transform** - AST to optimized runtime program
 
-```typescript
-import { transformPass } from '@constela/compiler';
+## CompiledProgram Structure
 
-const compiledProgram = transformPass(program, analysisContext);
+```json
+{
+  "version": "1.0",
+  "route": {
+    "path": "/users/:id",
+    "params": ["id"],
+    "title": { ... },
+    "layout": "MainLayout"
+  },
+  "lifecycle": {
+    "onMount": "loadData",
+    "onUnmount": "cleanup"
+  },
+  "state": {
+    "count": { "type": "number", "initial": 0 }
+  },
+  "actions": {
+    "increment": {
+      "name": "increment",
+      "steps": [{ "do": "update", "target": "count", "operation": "increment" }]
+    }
+  },
+  "view": { ... }
+}
 ```
 
 ## Layout Compilation
 
-Layouts have a separate compilation path with additional validation.
-
-### analyzeLayoutPass
-
-```typescript
-import { analyzeLayoutPass } from '@constela/compiler';
-
-const result = analyzeLayoutPass(layoutProgram);
-if (result.ok) {
-  // result.context contains layout-specific analysis
+Layouts are compiled separately with slot validation:
+
+```json
+{
+  "version": "1.0",
+  "type": "layout",
+  "view": {
+    "kind": "element",
+    "tag": "div",
+    "children": [
+      { "kind": "component", "name": "Header" },
+      { "kind": "slot" },
+      { "kind": "component", "name": "Footer" }
+    ]
+  }
 }
 ```
 
@@ -107,170 +99,72 @@ if (result.ok) {
 - No duplicate default slots
 - Slots not inside loops
 
-### transformLayoutPass
-
-```typescript
-import { transformLayoutPass } from '@constela/compiler';
-
-const compiledLayout = transformLayoutPass(layoutProgram, layoutContext);
-```
-
-### composeLayoutWithPage
-
-Composes a compiled layout with a page program.
-
-```typescript
-import { composeLayoutWithPage } from '@constela/compiler';
-
-const composedProgram = composeLayoutWithPage(compiledLayout, compiledPage);
-```
-
-**Composition Process:**
-- Merges state from both layout and page
-- Merges actions from both
-- Replaces slot nodes with page content
-- Named slots match by name
+## Error Handling
 
-## CompiledProgram Structure
+Structured errors with JSON Pointer paths:
 
-```typescript
-interface CompiledProgram {
-  version: '1.0';
-  route?: {
-    path: string;
-    params: string[];
-    title?: CompiledExpression;
-    layout?: string;
-    layoutParams?: Record<string, CompiledExpression>;
-    meta?: Record<string, CompiledExpression>;
-  };
-  lifecycle?: {
-    onMount?: string;
-    onUnmount?: string;
-    onRouteEnter?: string;
-    onRouteLeave?: string;
-  };
-  state: Record<string, {
-    type: 'number' | 'string' | 'list' | 'boolean' | 'object';
-    initial: unknown;
-  }>;
-  actions: Record<string, CompiledAction>;
-  view: CompiledNode;
-  importData?: Record<string, unknown>;
+```json
+{
+  "code": "UNDEFINED_STATE",
+  "message": "State \"count\" is not defined",
+  "path": "/view/children/0/props/onClick"
 }
 ```
 
-## Compiled Types
+**Error Codes:**
+- `SCHEMA_INVALID` - JSON Schema validation error
+- `UNDEFINED_STATE` - Reference to undefined state
+- `UNDEFINED_ACTION` - Reference to undefined action
+- `DUPLICATE_ACTION` - Duplicate action name
+- `VAR_UNDEFINED` - Undefined variable reference
+- `COMPONENT_NOT_FOUND` - Undefined component
+- `COMPONENT_PROP_MISSING` - Missing required prop
+- `COMPONENT_CYCLE` - Circular component reference
+- `OPERATION_INVALID_FOR_TYPE` - Invalid operation for state type
+- `LAYOUT_MISSING_SLOT` - Layout missing slot node
+- `LAYOUT_NOT_FOUND` - Referenced layout not found
 
-### CompiledExpression (13 types)
+## Internal API
 
-All expression types are preserved with optimizations:
+> For framework developers only. End users should use the CLI.
 
-```typescript
-type CompiledExpression =
-  | CompiledLitExpr
-  | CompiledStateExpr
-  | CompiledVarExpr
-  | CompiledBinExpr
-  | CompiledNotExpr
-  | CompiledCondExpr
-  | CompiledGetExpr
-  | CompiledRouteExpr
-  | CompiledImportExpr
-  | CompiledDataExpr
-  | CompiledRefExpr
-  | CompiledIndexExpr
-  | CompiledParamExpr;
-```
-
-### CompiledNode (7 types)
+### compile
 
 ```typescript
-type CompiledNode =
-  | CompiledElementNode
-  | CompiledTextNode
-  | CompiledIfNode
-  | CompiledEachNode
-  | CompiledMarkdownNode
-  | CompiledCodeNode
-  | CompiledSlotNode;
-```
+import { compile } from '@constela/compiler';
 
-### CompiledAction
+const result = compile(jsonInput);
 
-```typescript
-interface CompiledAction {
-  name: string;
-  params?: Record<string, { type: string }>;
-  steps: CompiledStep[];
+if (result.ok) {
+  console.log(result.program);
+} else {
+  console.error(result.errors);
 }
 ```
 
-### CompiledStep (12 types)
+### Individual Passes
 
 ```typescript
-type CompiledStep =
-  | CompiledSetStep
-  | CompiledUpdateStep
-  | CompiledFetchStep
-  | CompiledStorageStep
-  | CompiledClipboardStep
-  | CompiledNavigateStep
-  | CompiledImportStep
-  | CompiledCallStep
-  | CompiledSubscribeStep
-  | CompiledDisposeStep
-  | CompiledDomStep
-  | CompiledIfStep;
-```
+import { validatePass, analyzePass, transformPass } from '@constela/compiler';
 
-## Error Handling
-
-The compiler collects multiple errors during the analyze pass:
+// Step 1: Validate
+const validated = validatePass(input);
 
-```typescript
-const result = compile(input);
+// Step 2: Analyze
+const analyzed = analyzePass(validated.program);
 
-if (!result.ok) {
-  for (const error of result.errors) {
-    console.log(`[${error.code}] ${error.message}`);
-    console.log(`  at ${error.path}`);
-  }
-}
+// Step 3: Transform
+const compiled = transformPass(analyzed.program, analyzed.context);
 ```
 
-Errors include JSON Pointer paths for precise location reporting.
-
-## Example
+### Layout Compilation
 
 ```typescript
-import { compile } from '@constela/compiler';
+import { analyzeLayoutPass, transformLayoutPass, composeLayoutWithPage } from '@constela/compiler';
 
-const program = {
-  version: '1.0',
-  state: {
-    count: { type: 'number', initial: 0 }
-  },
-  actions: [
-    {
-      name: 'increment',
-      steps: [{ do: 'update', target: 'count', operation: 'increment' }]
-    }
-  ],
-  view: {
-    kind: 'element',
-    tag: 'button',
-    props: { onClick: { event: 'click', action: 'increment' } },
-    children: [{ kind: 'text', value: { expr: 'state', name: 'count' } }]
-  }
-};
-
-const result = compile(program);
-
-if (result.ok) {
-  // result.program is ready for runtime
-  console.log(result.program.actions.increment);
-}
+const layoutResult = analyzeLayoutPass(layoutProgram);
+const compiledLayout = transformLayoutPass(layoutProgram, layoutResult.context);
+const composedProgram = composeLayoutWithPage(compiledLayout, compiledPage);
 ```
 
 ## License

package/dist/index.d.ts

@@ -20,6 +20,7 @@ interface AnalysisContext {
     importNames: Set<string>;
     dataNames: Set<string>;
     refNames: Set<string>;
+    styleNames: Set<string>;
 }
 interface AnalyzePassSuccess {
     ok: true;
@@ -234,7 +235,7 @@ interface CompiledSlotNode {
     kind: 'slot';
     name?: string;
 }
-type CompiledExpression = CompiledLitExpr | CompiledStateExpr | CompiledVarExpr | CompiledBinExpr | CompiledNotExpr | CompiledCondExpr | CompiledGetExpr | CompiledRouteExpr | CompiledImportExpr | CompiledDataExpr | CompiledRefExpr | CompiledIndexExpr | CompiledParamExpr;
+type CompiledExpression = CompiledLitExpr | CompiledStateExpr | CompiledVarExpr | CompiledBinExpr | CompiledNotExpr | CompiledCondExpr | CompiledGetExpr | CompiledRouteExpr | CompiledImportExpr | CompiledDataExpr | CompiledRefExpr | CompiledIndexExpr | CompiledParamExpr | CompiledStyleExpr;
 interface CompiledLitExpr {
     expr: 'lit';
     value: string | number | boolean | null | unknown[];
@@ -295,6 +296,11 @@ interface CompiledParamExpr {
     name: string;
     path?: string;
 }
+interface CompiledStyleExpr {
+    expr: 'style';
+    name: string;
+    variants?: Record<string, CompiledExpression>;
+}
 interface CompiledEventHandler {
     event: string;
     action: string;

package/dist/index.js

@@ -42,6 +42,9 @@ import {
   createClipboardWriteMissingValueError,
   createInvalidNavigateTargetError,
   createUndefinedRefError,
+  createUndefinedStyleError,
+  createUndefinedVariantError,
+  findSimilarNames,
   isEventHandler,
   DATA_SOURCE_TYPES,
   DATA_TRANSFORMS,
@@ -53,6 +56,15 @@ import {
 function buildPath(base, ...segments) {
   return segments.reduce((p, s) => `${p}/${s}`, base);
 }
+function createErrorOptionsWithSuggestion(name, availableNames) {
+  const availableNamesArray = Array.from(availableNames);
+  const similarNames = findSimilarNames(name, availableNames);
+  const suggestion = similarNames.length > 0 ? `Did you mean '${similarNames[0]}'?` : void 0;
+  return {
+    suggestion,
+    context: { availableNames: availableNamesArray }
+  };
+}
 function extractRouteParams(path) {
   const params = [];
   const segments = path.split("/");
@@ -124,7 +136,10 @@ function collectContext(programAst) {
     programAst.data ? Object.keys(programAst.data) : []
   );
   const refNames = collectRefs(programAst.view);
-  return { stateNames, actionNames, componentNames, routeParams, importNames, dataNames, refNames };
+  const styleNames = new Set(
+    programAst.styles ? Object.keys(programAst.styles) : []
+  );
+  return { stateNames, actionNames, componentNames, routeParams, importNames, dataNames, refNames, styleNames };
 }
 function checkDuplicateActions(ast2) {
   const errors = [];
@@ -144,7 +159,8 @@ function validateExpression(expr, path, context, scope, paramScope) {
   switch (expr.expr) {
     case "state":
       if (!context.stateNames.has(expr.name)) {
-        errors.push(createUndefinedStateError(expr.name, path));
+        const errorOptions = createErrorOptionsWithSuggestion(expr.name, context.stateNames);
+        errors.push(createUndefinedStateError(expr.name, path, errorOptions));
       }
       break;
     case "var":
@@ -207,6 +223,32 @@ function validateExpression(expr, path, context, scope, paramScope) {
     case "get":
       errors.push(...validateExpression(expr.base, buildPath(path, "base"), context, scope, paramScope));
       break;
+    case "style":
+      errors.push(...validateStyleExpression(expr, path, context, scope, paramScope));
+      break;
+  }
+  return errors;
+}
+function validateStyleExpression(expr, path, context, scope, paramScope) {
+  const errors = [];
+  if (!context.styleNames.has(expr.name)) {
+    const errorOptions = createErrorOptionsWithSuggestion(expr.name, context.styleNames);
+    errors.push(createUndefinedStyleError(expr.name, path, errorOptions));
+    return errors;
+  }
+  if (expr.variants) {
+    const stylePreset = ast.styles?.[expr.name];
+    const availableVariants = new Set(
+      stylePreset?.variants ? Object.keys(stylePreset.variants) : []
+    );
+    for (const [variantKey, variantValue] of Object.entries(expr.variants)) {
+      const variantPath = buildPath(path, "variants", variantKey);
+      if (!availableVariants.has(variantKey)) {
+        const errorOptions = createErrorOptionsWithSuggestion(variantKey, availableVariants);
+        errors.push(createUndefinedVariantError(variantKey, expr.name, variantPath, errorOptions));
+      }
+      errors.push(...validateExpression(variantValue, variantPath, context, scope, paramScope));
+    }
   }
   return errors;
 }
@@ -215,7 +257,8 @@ function validateActionStep(step, path, context) {
   switch (step.do) {
     case "set":
       if (!context.stateNames.has(step.target)) {
-        errors.push(createUndefinedStateError(step.target, buildPath(path, "target")));
+        const errorOptions = createErrorOptionsWithSuggestion(step.target, context.stateNames);
+        errors.push(createUndefinedStateError(step.target, buildPath(path, "target"), errorOptions));
       }
       errors.push(
         ...validateExpressionStateOnly(step.value, buildPath(path, "value"), context)
@@ -223,7 +266,8 @@ function validateActionStep(step, path, context) {
       break;
     case "update": {
       if (!context.stateNames.has(step.target)) {
-        errors.push(createUndefinedStateError(step.target, buildPath(path, "target")));
+        const errorOptions = createErrorOptionsWithSuggestion(step.target, context.stateNames);
+        errors.push(createUndefinedStateError(step.target, buildPath(path, "target"), errorOptions));
       } else {
         const stateField = ast.state[step.target];
         if (stateField) {
@@ -437,7 +481,8 @@ function validateActionStep(step, path, context) {
         ...validateExpressionStateOnly(subscribeStep.target, buildPath(path, "target"), context)
       );
       if (!context.actionNames.has(subscribeStep.action)) {
-        errors.push(createUndefinedActionError(subscribeStep.action, buildPath(path, "action")));
+        const errorOptions = createErrorOptionsWithSuggestion(subscribeStep.action, context.actionNames);
+        errors.push(createUndefinedActionError(subscribeStep.action, buildPath(path, "action"), errorOptions));
       }
       break;
     }
@@ -456,7 +501,8 @@ function validateExpressionStateOnly(expr, path, context) {
   switch (expr.expr) {
     case "state":
       if (!context.stateNames.has(expr.name)) {
-        errors.push(createUndefinedStateError(expr.name, path));
+        const errorOptions = createErrorOptionsWithSuggestion(expr.name, context.stateNames);
+        errors.push(createUndefinedStateError(expr.name, path, errorOptions));
       }
       break;
     case "var":
@@ -513,6 +559,32 @@ function validateExpressionStateOnly(expr, path, context) {
     case "get":
       errors.push(...validateExpressionStateOnly(expr.base, buildPath(path, "base"), context));
       break;
+    case "style":
+      errors.push(...validateStyleExpressionStateOnly(expr, path, context));
+      break;
+  }
+  return errors;
+}
+function validateStyleExpressionStateOnly(expr, path, context) {
+  const errors = [];
+  if (!context.styleNames.has(expr.name)) {
+    const errorOptions = createErrorOptionsWithSuggestion(expr.name, context.styleNames);
+    errors.push(createUndefinedStyleError(expr.name, path, errorOptions));
+    return errors;
+  }
+  if (expr.variants) {
+    const stylePreset = ast.styles?.[expr.name];
+    const availableVariants = new Set(
+      stylePreset?.variants ? Object.keys(stylePreset.variants) : []
+    );
+    for (const [variantKey, variantValue] of Object.entries(expr.variants)) {
+      const variantPath = buildPath(path, "variants", variantKey);
+      if (!availableVariants.has(variantKey)) {
+        const errorOptions = createErrorOptionsWithSuggestion(variantKey, availableVariants);
+        errors.push(createUndefinedVariantError(variantKey, expr.name, variantPath, errorOptions));
+      }
+      errors.push(...validateExpressionStateOnly(variantValue, variantPath, context));
+    }
   }
   return errors;
 }
@@ -521,7 +593,8 @@ function validateExpressionInEventPayload(expr, path, context, scope) {
   switch (expr.expr) {
     case "state":
       if (!context.stateNames.has(expr.name)) {
-        errors.push(createUndefinedStateError(expr.name, path));
+        const errorOptions = createErrorOptionsWithSuggestion(expr.name, context.stateNames);
+        errors.push(createUndefinedStateError(expr.name, path, errorOptions));
       }
       break;
     case "var":
@@ -595,6 +668,32 @@ function validateExpressionInEventPayload(expr, path, context, scope) {
         ...validateExpressionInEventPayload(expr.base, buildPath(path, "base"), context, scope)
       );
       break;
+    case "style":
+      errors.push(...validateStyleExpressionInEventPayload(expr, path, context, scope));
+      break;
+  }
+  return errors;
+}
+function validateStyleExpressionInEventPayload(expr, path, context, scope) {
+  const errors = [];
+  if (!context.styleNames.has(expr.name)) {
+    const errorOptions = createErrorOptionsWithSuggestion(expr.name, context.styleNames);
+    errors.push(createUndefinedStyleError(expr.name, path, errorOptions));
+    return errors;
+  }
+  if (expr.variants) {
+    const stylePreset = ast.styles?.[expr.name];
+    const availableVariants = new Set(
+      stylePreset?.variants ? Object.keys(stylePreset.variants) : []
+    );
+    for (const [variantKey, variantValue] of Object.entries(expr.variants)) {
+      const variantPath = buildPath(path, "variants", variantKey);
+      if (!availableVariants.has(variantKey)) {
+        const errorOptions = createErrorOptionsWithSuggestion(variantKey, availableVariants);
+        errors.push(createUndefinedVariantError(variantKey, expr.name, variantPath, errorOptions));
+      }
+      errors.push(...validateExpressionInEventPayload(variantValue, variantPath, context, scope));
+    }
   }
   return errors;
 }
@@ -608,7 +707,8 @@ function validateViewNode(node, path, context, scope, options = { insideComponen
           const propPath = buildPath(path, "props", propName);
           if (isEventHandler(propValue)) {
             if (!context.actionNames.has(propValue.action)) {
-              errors.push(createUndefinedActionError(propValue.action, propPath));
+              const errorOptions = createErrorOptionsWithSuggestion(propValue.action, context.actionNames);
+              errors.push(createUndefinedActionError(propValue.action, propPath, errorOptions));
             }
             if (propValue.payload) {
               errors.push(
@@ -662,7 +762,8 @@ function validateViewNode(node, path, context, scope, options = { insideComponen
     }
     case "component": {
       if (!context.componentNames.has(node.name)) {
-        errors.push(createComponentNotFoundError(node.name, path));
+        const errorOptions = createErrorOptionsWithSuggestion(node.name, context.componentNames);
+        errors.push(createComponentNotFoundError(node.name, path, errorOptions));
       } else {
         const componentDef = ast.components?.[node.name];
         if (componentDef) {
@@ -839,7 +940,8 @@ function validateLifecycleHooks(lifecycle, context) {
   for (const hook of hooks) {
     const actionName = lifecycle[hook];
     if (actionName && !context.actionNames.has(actionName)) {
-      errors.push(createUndefinedActionError(actionName, `/lifecycle/${hook}`));
+      const errorOptions = createErrorOptionsWithSuggestion(actionName, context.actionNames);
+      errors.push(createUndefinedActionError(actionName, `/lifecycle/${hook}`, errorOptions));
     }
   }
   return errors;
@@ -1063,6 +1165,19 @@ function transformExpression(expr, ctx) {
         base: transformExpression(expr.base, ctx),
         key: transformExpression(expr.key, ctx)
       };
+    case "style": {
+      const styleExpr = {
+        expr: "style",
+        name: expr.name
+      };
+      if (expr.variants) {
+        styleExpr.variants = {};
+        for (const [key, value] of Object.entries(expr.variants)) {
+          styleExpr.variants[key] = transformExpression(value, ctx);
+        }
+      }
+      return styleExpr;
+    }
   }
 }
 function transformEventHandler(handler, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/compiler",
-  "version": "0.7.1",
+  "version": "0.8.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.7.0"
+    "@constela/core": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",