@constela/core 0.7.0 → 0.9.0

package/README.md

@@ -0,0 +1,302 @@
+# @constela/core
+
+Core types and validation for Constela JSON programs.
+
+## Installation
+
+```bash
+npm install @constela/core
+```
+
+## JSON Program Structure
+
+```json
+{
+  "version": "1.0",
+  "route": { "path": "/", "layout": "MainLayout" },
+  "imports": { "config": "./data/config.json" },
+  "data": { "posts": { "type": "glob", "pattern": "content/*.mdx" } },
+  "lifecycle": { "onMount": "loadData" },
+  "state": { ... },
+  "actions": [ ... ],
+  "view": { ... },
+  "components": { ... }
+}
+```
+
+All fields except `version`, `state`, `actions`, and `view` are optional.
+
+## State Types
+
+5 supported state types:
+
+```json
+{
+  "count": { "type": "number", "initial": 0 },
+  "query": { "type": "string", "initial": "" },
+  "items": { "type": "list", "initial": [] },
+  "isVisible": { "type": "boolean", "initial": true },
+  "form": { "type": "object", "initial": { "name": "", "email": "" } }
+}
+```
+
+## Expression Types
+
+13 expression types for constrained computation:
+
+| Type | JSON Example | Description |
+|------|-------------|-------------|
+| `lit` | `{ "expr": "lit", "value": "Hello" }` | Literal value |
+| `state` | `{ "expr": "state", "name": "count" }` | State reference |
+| `var` | `{ "expr": "var", "name": "item" }` | Loop/event variable |
+| `bin` | `{ "expr": "bin", "op": "+", "left": ..., "right": ... }` | Binary operation |
+| `not` | `{ "expr": "not", "operand": ... }` | Logical negation |
+| `param` | `{ "expr": "param", "name": "title" }` | Component parameter |
+| `cond` | `{ "expr": "cond", "if": ..., "then": ..., "else": ... }` | Conditional |
+| `get` | `{ "expr": "get", "base": ..., "path": "user.name" }` | Property access |
+| `route` | `{ "expr": "route", "name": "id", "source": "param" }` | Route parameter |
+| `import` | `{ "expr": "import", "name": "config" }` | External data |
+| `data` | `{ "expr": "data", "name": "posts" }` | Build-time data |
+| `ref` | `{ "expr": "ref", "name": "inputEl" }` | DOM element ref |
+| `style` | `{ "expr": "style", "name": "button", "variants": {...} }` | Style reference |
+
+**Binary Operators:** `+`, `-`, `*`, `/`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`
+
+## View Node Types
+
+8 node types for building UI:
+
+```json
+// Element node
+{ "kind": "element", "tag": "div", "props": { ... }, "children": [ ... ] }
+
+// Text node
+{ "kind": "text", "value": { "expr": "state", "name": "count" } }
+
+// Conditional node
+{ "kind": "if", "condition": { ... }, "then": { ... }, "else": { ... } }
+
+// Loop node
+{ "kind": "each", "items": { "expr": "state", "name": "todos" }, "as": "item", "body": { ... } }
+
+// Component node
+{ "kind": "component", "name": "Button", "props": { "label": { ... } } }
+
+// Slot node (for layouts)
+{ "kind": "slot" }
+{ "kind": "slot", "name": "sidebar" }
+
+// Markdown node
+{ "kind": "markdown", "content": { "expr": "state", "name": "content" } }
+
+// Code block node
+{ "kind": "code", "code": { ... }, "language": { ... } }
+```
+
+## Action Step Types
+
+11 step types for declarative actions:
+
+```json
+// Set state value
+{ "do": "set", "target": "query", "value": { "expr": "lit", "value": "" } }
+
+// Update with operation
+{ "do": "update", "target": "count", "operation": "increment" }
+{ "do": "update", "target": "todos", "operation": "push", "value": { ... } }
+
+// HTTP request
+{ "do": "fetch", "url": { ... }, "method": "GET", "onSuccess": [ ... ], "onError": [ ... ] }
+
+// Storage operation
+{ "do": "storage", "operation": "get", "key": { ... }, "storage": "local" }
+
+// Clipboard operation
+{ "do": "clipboard", "operation": "write", "value": { ... } }
+
+// Navigation
+{ "do": "navigate", "url": { ... } }
+
+// Dynamic import
+{ "do": "import", "module": "chart.js", "result": "Chart" }
+
+// External function call
+{ "do": "call", "ref": "Chart", "method": "create", "args": [ ... ] }
+
+// Event subscription
+{ "do": "subscribe", "ref": "eventSource", "event": "message", "action": "handleMessage" }
+
+// Resource disposal
+{ "do": "dispose", "ref": "chartInstance" }
+
+// DOM manipulation
+{ "do": "dom", "operation": "addClass", "ref": "myElement", "value": { ... } }
+```
+
+**Update Operations:**
+
+| Operation | State Type | Description |
+|-----------|------------|-------------|
+| `increment` | number | Add to number |
+| `decrement` | number | Subtract from number |
+| `push` | list | Add item to end |
+| `pop` | list | Remove last item |
+| `remove` | list | Remove by value/index |
+| `toggle` | boolean | Flip boolean |
+| `merge` | object | Shallow merge |
+| `replaceAt` | list | Replace at index |
+| `insertAt` | list | Insert at index |
+| `splice` | list | Delete/insert items |
+
+## Lifecycle Hooks
+
+```json
+{
+  "lifecycle": {
+    "onMount": "loadData",
+    "onUnmount": "cleanup",
+    "onRouteEnter": "fetchData",
+    "onRouteLeave": "saveState"
+  }
+}
+```
+
+## Style System
+
+Define reusable style presets with variants (similar to CVA/Tailwind Variants):
+
+```json
+{
+  "styles": {
+    "button": {
+      "base": "px-4 py-2 rounded font-medium",
+      "variants": {
+        "variant": {
+          "primary": "bg-blue-500 text-white",
+          "secondary": "bg-gray-200 text-gray-800"
+        },
+        "size": {
+          "sm": "text-sm",
+          "md": "text-base",
+          "lg": "text-lg"
+        }
+      },
+      "defaultVariants": {
+        "variant": "primary",
+        "size": "md"
+      }
+    }
+  }
+}
+```
+
+Use styles with `StyleExpr`:
+
+```json
+{
+  "kind": "element",
+  "tag": "button",
+  "props": {
+    "className": {
+      "expr": "style",
+      "name": "button",
+      "variants": {
+        "variant": { "expr": "lit", "value": "primary" },
+        "size": { "expr": "state", "name": "buttonSize" }
+      }
+    }
+  }
+}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| `SCHEMA_INVALID` | JSON Schema validation error |
+| `UNSUPPORTED_VERSION` | Unsupported version string |
+| `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 |
+| `COMPONENT_PROP_TYPE` | Prop type mismatch |
+| `PARAM_UNDEFINED` | Undefined parameter |
+| `OPERATION_INVALID_FOR_TYPE` | Invalid operation for state type |
+| `OPERATION_MISSING_FIELD` | Missing required field for operation |
+| `ROUTE_NOT_DEFINED` | Route not defined |
+| `UNDEFINED_ROUTE_PARAM` | Undefined route parameter |
+| `LAYOUT_MISSING_SLOT` | Layout missing slot node |
+| `LAYOUT_NOT_FOUND` | Referenced layout not found |
+| `INVALID_SLOT_NAME` | Invalid slot name |
+| `DUPLICATE_SLOT_NAME` | Duplicate slot name |
+| `DUPLICATE_DEFAULT_SLOT` | Multiple default slots |
+| `SLOT_IN_LOOP` | Slot inside loop |
+| `UNDEFINED_DATA_SOURCE` | Undefined data source |
+| `UNDEFINED_IMPORT` | Undefined import reference |
+| `UNDEFINED_REF` | Undefined element ref |
+| `INVALID_STORAGE_OPERATION` | Invalid storage operation |
+| `INVALID_CLIPBOARD_OPERATION` | Invalid clipboard operation |
+| `INVALID_NAVIGATE_TARGET` | Invalid navigate target |
+| `UNDEFINED_STYLE` | Reference to undefined style preset |
+| `UNDEFINED_VARIANT` | Reference to undefined style variant |
+
+### Error Suggestions
+
+Errors for undefined references include "Did you mean?" suggestions using Levenshtein distance:
+
+```typescript
+import { findSimilarNames } from '@constela/core';
+
+const candidates = new Set(['counter', 'items', 'query']);
+const similar = findSimilarNames('count', candidates);
+// Returns: ['counter'] - similar names within distance 2
+```
+
+## Internal API
+
+> For framework developers only.
+
+### validateAst
+
+```typescript
+import { validateAst } from '@constela/core';
+
+const result = validateAst(input);
+if (result.ok) {
+  console.log('Valid program:', result.program);
+} else {
+  console.error('Validation failed:', result.error);
+}
+```
+
+### Type Guards
+
+47 type guard functions for runtime type checking:
+
+```typescript
+import {
+  isLitExpr, isStateExpr, isVarExpr, isBinExpr,
+  isElementNode, isTextNode, isIfNode, isEachNode,
+  isSetStep, isUpdateStep, isFetchStep,
+  isNumberField, isStringField, isListField,
+} from '@constela/core';
+```
+
+### ConstelaError
+
+```typescript
+import { ConstelaError } from '@constela/core';
+
+const error = new ConstelaError(
+  'UNDEFINED_STATE',
+  'State "count" is not defined',
+  '/view/children/0/props/onClick'
+);
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -37,6 +37,7 @@ interface LitExpr {
 interface StateExpr {
     expr: 'state';
     name: string;
+    path?: string;
 }
 /**
  * Variable expression - references a loop variable or event data
@@ -118,7 +119,23 @@ interface RefExpr {
     expr: 'ref';
     name: string;
 }
-type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr | CondExpr | GetExpr | RouteExpr | ImportExpr | DataExpr | RefExpr;
+/**
+ * Index expression - dynamic property/array access
+ */
+interface IndexExpr {
+    expr: 'index';
+    base: Expression;
+    key: Expression;
+}
+/**
+ * Style expression - references a style preset with optional variant values
+ */
+interface StyleExpr {
+    expr: 'style';
+    name: string;
+    variants?: Record<string, Expression>;
+}
+type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr | CondExpr | GetExpr | RouteExpr | ImportExpr | DataExpr | RefExpr | IndexExpr | StyleExpr;
 /**
  * Number state field
  */
@@ -191,6 +208,22 @@ interface UpdateStep {
     index?: Expression;
     deleteCount?: Expression;
 }
+/**
+ * SetPath step - sets a value at a specific path within a state field
+ *
+ * This enables fine-grained state updates like `posts[5].liked = true`
+ * without re-creating the entire state.
+ *
+ * @property target - The state field name (e.g., "posts")
+ * @property path - The path within the state field (Expression that evaluates to string or array)
+ * @property value - The value to set at the path
+ */
+interface SetPathStep {
+    do: 'setPath';
+    target: string;
+    path: Expression;
+    value: Expression;
+}
 /**
  * Fetch step - makes an HTTP request
  */
@@ -275,7 +308,32 @@ interface DisposeStep {
     do: 'dispose';
     target: Expression;
 }
-type ActionStep = SetStep | UpdateStep | FetchStep | StorageStep | ClipboardStep | NavigateStep | ImportStep | CallStep | SubscribeStep | DisposeStep;
+/**
+ * DOM step - manipulate DOM elements (add/remove classes, attributes)
+ */
+interface DomStep {
+    do: 'dom';
+    operation: 'addClass' | 'removeClass' | 'toggleClass' | 'setAttribute' | 'removeAttribute';
+    selector: Expression;
+    value?: Expression;
+    attribute?: string;
+}
+/**
+ * Send step - sends data through a named WebSocket connection
+ */
+interface SendStep {
+    do: 'send';
+    connection: string;
+    data: Expression;
+}
+/**
+ * Close step - closes a named WebSocket connection
+ */
+interface CloseStep {
+    do: 'close';
+    connection: string;
+}
+type ActionStep = SetStep | UpdateStep | SetPathStep | FetchStep | StorageStep | ClipboardStep | NavigateStep | ImportStep | CallStep | SubscribeStep | DisposeStep | DomStep | SendStep | CloseStep;
 /**
  * Event handler - binds an event to an action
  */
@@ -365,6 +423,22 @@ interface ComponentDef {
     params?: Record<string, ParamDef>;
     view: ViewNode;
 }
+/**
+ * Compound variant - applies additional classes when multiple variants match
+ */
+interface CompoundVariant {
+    [key: string]: string;
+    class: string;
+}
+/**
+ * Style preset - defines a reusable style with variants (CVA-like pattern)
+ */
+interface StylePreset {
+    base: string;
+    variants?: Record<string, Record<string, string>>;
+    defaultVariants?: Record<string, string>;
+    compoundVariants?: CompoundVariant[];
+}
 /**
  * Data transform types for build-time content loading
  */
@@ -407,6 +481,7 @@ interface RouteDefinition {
     path: string;
     title?: Expression;
     layout?: string;
+    layoutParams?: Record<string, Expression>;
     meta?: Record<string, Expression>;
     getStaticPaths?: StaticPathsDefinition;
 }
@@ -427,6 +502,7 @@ interface Program {
     route?: RouteDefinition;
     imports?: Record<string, string>;
     data?: Record<string, DataSource>;
+    styles?: Record<string, StylePreset>;
     lifecycle?: LifecycleHooks;
     state: Record<string, StateField>;
     actions: ActionDefinition[];
@@ -441,6 +517,8 @@ type ConstelaAst = Program;
 interface LayoutProgram {
     version: '1.0';
     type: 'layout';
+    imports?: Record<string, string>;
+    importData?: Record<string, unknown>;
     state?: Record<string, StateField>;
     actions?: ActionDefinition[];
     view: ViewNode;
@@ -529,6 +607,10 @@ declare function isDataExpr(value: unknown): value is DataExpr;
  * Checks if value is a ref expression
  */
 declare function isRefExpr(value: unknown): value is RefExpr;
+/**
+ * Checks if value is a style expression
+ */
+declare function isStyleExpr(value: unknown): value is StyleExpr;
 /**
  * Checks if value is a data source
  */
@@ -677,14 +759,33 @@ declare function isLifecycleHooks(value: unknown): value is LifecycleHooks;
  * This module defines error types, the ConstelaError class,
  * and factory functions for creating specific errors.
  */
-type ErrorCode = 'SCHEMA_INVALID' | 'UNDEFINED_STATE' | 'UNDEFINED_ACTION' | 'VAR_UNDEFINED' | 'DUPLICATE_ACTION' | 'UNSUPPORTED_VERSION' | 'COMPONENT_NOT_FOUND' | 'COMPONENT_PROP_MISSING' | 'COMPONENT_CYCLE' | 'COMPONENT_PROP_TYPE' | 'PARAM_UNDEFINED' | 'OPERATION_INVALID_FOR_TYPE' | 'OPERATION_MISSING_FIELD' | 'OPERATION_UNKNOWN' | 'EXPR_INVALID_BASE' | 'EXPR_INVALID_CONDITION' | 'EXPR_COND_ELSE_REQUIRED' | 'UNDEFINED_ROUTE_PARAM' | 'ROUTE_NOT_DEFINED' | 'UNDEFINED_IMPORT' | 'IMPORTS_NOT_DEFINED' | 'LAYOUT_MISSING_SLOT' | 'LAYOUT_NOT_FOUND' | 'INVALID_SLOT_NAME' | 'DUPLICATE_SLOT_NAME' | 'DUPLICATE_DEFAULT_SLOT' | 'SLOT_IN_LOOP' | 'INVALID_DATA_SOURCE' | 'UNDEFINED_DATA_SOURCE' | 'DATA_NOT_DEFINED' | 'UNDEFINED_DATA' | 'UNDEFINED_REF' | 'INVALID_STORAGE_OPERATION' | 'INVALID_STORAGE_TYPE' | 'STORAGE_SET_MISSING_VALUE' | 'INVALID_CLIPBOARD_OPERATION' | 'CLIPBOARD_WRITE_MISSING_VALUE' | 'INVALID_NAVIGATE_TARGET';
+type ErrorCode = 'SCHEMA_INVALID' | 'UNDEFINED_STATE' | 'UNDEFINED_ACTION' | 'VAR_UNDEFINED' | 'DUPLICATE_ACTION' | 'UNSUPPORTED_VERSION' | 'COMPONENT_NOT_FOUND' | 'COMPONENT_PROP_MISSING' | 'COMPONENT_CYCLE' | 'COMPONENT_PROP_TYPE' | 'PARAM_UNDEFINED' | 'OPERATION_INVALID_FOR_TYPE' | 'OPERATION_MISSING_FIELD' | 'OPERATION_UNKNOWN' | 'EXPR_INVALID_BASE' | 'EXPR_INVALID_CONDITION' | 'EXPR_COND_ELSE_REQUIRED' | 'UNDEFINED_ROUTE_PARAM' | 'ROUTE_NOT_DEFINED' | 'UNDEFINED_IMPORT' | 'IMPORTS_NOT_DEFINED' | 'LAYOUT_MISSING_SLOT' | 'LAYOUT_NOT_FOUND' | 'INVALID_SLOT_NAME' | 'DUPLICATE_SLOT_NAME' | 'DUPLICATE_DEFAULT_SLOT' | 'SLOT_IN_LOOP' | 'INVALID_DATA_SOURCE' | 'UNDEFINED_DATA_SOURCE' | 'DATA_NOT_DEFINED' | 'UNDEFINED_DATA' | 'UNDEFINED_REF' | 'INVALID_STORAGE_OPERATION' | 'INVALID_STORAGE_TYPE' | 'STORAGE_SET_MISSING_VALUE' | 'INVALID_CLIPBOARD_OPERATION' | 'CLIPBOARD_WRITE_MISSING_VALUE' | 'INVALID_NAVIGATE_TARGET' | 'UNDEFINED_STYLE' | 'UNDEFINED_VARIANT';
+/**
+ * Options for creating enhanced ConstelaError instances
+ */
+interface ErrorOptions {
+    severity?: 'error' | 'warning' | 'info' | undefined;
+    suggestion?: string | undefined;
+    expected?: string | undefined;
+    actual?: string | undefined;
+    context?: {
+        availableNames?: string[] | undefined;
+    } | undefined;
+}
 /**
  * Custom error class for Constela validation errors
  */
 declare class ConstelaError extends Error {
     readonly code: ErrorCode;
     readonly path: string | undefined;
-    constructor(code: ErrorCode, message: string, path?: string | undefined);
+    readonly severity: 'error' | 'warning' | 'info';
+    readonly suggestion: string | undefined;
+    readonly expected: string | undefined;
+    readonly actual: string | undefined;
+    readonly context: {
+        availableNames?: string[] | undefined;
+    } | undefined;
+    constructor(code: ErrorCode, message: string, path?: string | undefined, options?: ErrorOptions);
     /**
      * Converts the error to a JSON-serializable object
      */
@@ -692,6 +793,13 @@ declare class ConstelaError extends Error {
         code: ErrorCode;
         message: string;
         path: string | undefined;
+        severity: 'error' | 'warning' | 'info';
+        suggestion: string | undefined;
+        expected: string | undefined;
+        actual: string | undefined;
+        context: {
+            availableNames?: string[] | undefined;
+        } | undefined;
     };
 }
 /**
@@ -705,11 +813,11 @@ declare function createSchemaError(message: string, path?: string): ConstelaErro
 /**
  * Creates an undefined state reference error
  */
-declare function createUndefinedStateError(stateName: string, path?: string): ConstelaError;
+declare function createUndefinedStateError(stateName: string, path?: string, options?: ErrorOptions): ConstelaError;
 /**
  * Creates an undefined action reference error
  */
-declare function createUndefinedActionError(actionName: string, path?: string): ConstelaError;
+declare function createUndefinedActionError(actionName: string, path?: string, options?: ErrorOptions): ConstelaError;
 /**
  * Creates a duplicate action name error
  */
@@ -725,7 +833,7 @@ declare function createUnsupportedVersionError(version: string): ConstelaError;
 /**
  * Creates a component not found error
  */
-declare function createComponentNotFoundError(name: string, path?: string): ConstelaError;
+declare function createComponentNotFoundError(name: string, path?: string, options?: ErrorOptions): ConstelaError;
 /**
  * Creates a missing required prop error
  */
@@ -842,6 +950,28 @@ declare function createClipboardWriteMissingValueError(path?: string): ConstelaE
  * Creates an invalid navigate target error
  */
 declare function createInvalidNavigateTargetError(target: string, path?: string): ConstelaError;
+/**
+ * Creates an undefined style reference error
+ */
+declare function createUndefinedStyleError(styleName: string, path?: string, options?: ErrorOptions): ConstelaError;
+/**
+ * Creates an undefined variant key error
+ */
+declare function createUndefinedVariantError(variantKey: string, styleName: string, path?: string, options?: ErrorOptions): ConstelaError;
+/**
+ * Finds similar names from a set of candidates using Levenshtein distance
+ * and prefix matching.
+ *
+ * Matching strategies:
+ * 1. Levenshtein distance <= maxDistance (default: 2)
+ * 2. Target is a prefix of candidate with minimum 3 characters
+ *
+ * @param target - The target string to find similar names for
+ * @param candidates - A set of candidate names to search through
+ * @param maxDistance - Maximum Levenshtein distance to consider (default: 2)
+ * @returns Array of similar names sorted by distance (closest first)
+ */
+declare function findSimilarNames(target: string, candidates: Set<string>, maxDistance?: number): string[];
 
 /**
  * AST Validator for Constela
@@ -901,6 +1031,12 @@ declare const astSchema: {
         readonly view: {
             readonly $ref: "#/$defs/ViewNode";
         };
+        readonly styles: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly $ref: "#/$defs/StylePreset";
+            };
+        };
         readonly components: {
             readonly type: "object";
             readonly additionalProperties: {
@@ -926,6 +1062,10 @@ declare const astSchema: {
                 readonly $ref: "#/$defs/CondExpr";
             }, {
                 readonly $ref: "#/$defs/GetExpr";
+            }, {
+                readonly $ref: "#/$defs/IndexExpr";
+            }, {
+                readonly $ref: "#/$defs/StyleExpr";
             }];
         };
         readonly LitExpr: {
@@ -964,6 +1104,9 @@ declare const astSchema: {
                 readonly name: {
                     readonly type: "string";
                 };
+                readonly path: {
+                    readonly type: "string";
+                };
             };
         };
         readonly VarExpr: {
@@ -1072,6 +1215,86 @@ declare const astSchema: {
                 };
             };
         };
+        readonly IndexExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "base", "key"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "index";
+                };
+                readonly base: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly key: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly StyleExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "name"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "style";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly variants: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly $ref: "#/$defs/Expression";
+                    };
+                };
+            };
+        };
+        readonly StylePreset: {
+            readonly type: "object";
+            readonly required: readonly ["base"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly base: {
+                    readonly type: "string";
+                };
+                readonly variants: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly type: "object";
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly defaultVariants: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                    };
+                };
+                readonly compoundVariants: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/CompoundVariant";
+                    };
+                };
+            };
+        };
+        readonly CompoundVariant: {
+            readonly type: "object";
+            readonly required: readonly ["class"];
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+            readonly properties: {
+                readonly class: {
+                    readonly type: "string";
+                };
+            };
+        };
         readonly StateField: {
             readonly oneOf: readonly [{
                 readonly $ref: "#/$defs/NumberField";
@@ -1486,4 +1709,4 @@ declare const astSchema: {
     };
 };
 
-export { type ActionDefinition, type ActionStep, BINARY_OPERATORS, type BinExpr, type BinaryOperator, type BooleanField, CLIPBOARD_OPERATIONS, type CallStep, type ClipboardOperation, type ClipboardStep, type CodeNode, type ComponentDef, type ComponentNode, type ComponentsRef, type CondExpr, type ConstelaAst, ConstelaError, type ConstelaProgram, DATA_SOURCE_TYPES, DATA_TRANSFORMS, type DataExpr, type DataSource, type DataSourceType, type DataTransform, type DisposeStep, type EachNode, type ElementNode, type ErrorCode, type EventHandler, type Expression, type FetchStep, type GetExpr, HTTP_METHODS, type HttpMethod, type IfNode, type ImportExpr, type ImportStep, type LayoutProgram, type LifecycleHooks, type ListField, type LitExpr, type MarkdownNode, NAVIGATE_TARGETS, type NavigateStep, type NavigateTarget, type NotExpr, type NumberField, type ObjectField, PARAM_TYPES, type ParamDef, type ParamExpr, type ParamType, type Program, type RefExpr, type RouteDefinition, type RouteExpr, STORAGE_OPERATIONS, STORAGE_TYPES, type SetStep, type SlotNode, type StateExpr, type StateField, type StaticPathsDefinition, type StorageOperation, type StorageStep, type StorageType, type StringField, type SubscribeStep, type TextNode, UPDATE_OPERATIONS, type UpdateOperation, type UpdateStep, type ValidationFailure, type ValidationResult, type ValidationSuccess, type VarExpr, type ViewNode, astSchema, createClipboardWriteMissingValueError, createComponentCycleError, createComponentNotFoundError, createComponentPropMissingError, createComponentPropTypeError, createCondElseRequiredError, createDataNotDefinedError, createDuplicateActionError, createDuplicateDefaultSlotError, createDuplicateSlotNameError, createImportsNotDefinedError, createInvalidClipboardOperationError, createInvalidDataSourceError, createInvalidNavigateTargetError, createInvalidSlotNameError, createInvalidStorageOperationError, createInvalidStorageTypeError, createLayoutMissingSlotError, createLayoutNotFoundError, createOperationInvalidForTypeError, createOperationMissingFieldError, createOperationUnknownError, createRouteNotDefinedError, createSchemaError, createSlotInLoopError, createStorageSetMissingValueError, createUndefinedActionError, createUndefinedDataError, createUndefinedDataSourceError, createUndefinedImportError, createUndefinedParamError, createUndefinedRefError, createUndefinedRouteParamError, createUndefinedStateError, createUndefinedVarError, createUnsupportedVersionError, isActionStep, isBinExpr, isBooleanField, isCallStep, isClipboardStep, isCodeNode, isComponentNode, isCondExpr, isConstelaError, isDataExpr, isDataSource, isDisposeStep, isEachNode, isElementNode, isEventHandler, isExpression, isFetchStep, isGetExpr, isIfNode, isImportExpr, isImportStep, isLayoutProgram, isLifecycleHooks, isListField, isLitExpr, isMarkdownNode, isNamedSlotNode, isNavigateStep, isNotExpr, isNumberField, isObjectField, isParamExpr, isRefExpr, isRouteDefinition, isRouteExpr, isSetStep, isSlotNode, isStateExpr, isStateField, isStaticPathsDefinition, isStorageStep, isStringField, isSubscribeStep, isTextNode, isUpdateStep, isVarExpr, isViewNode, validateAst };
+export { type ActionDefinition, type ActionStep, BINARY_OPERATORS, type BinExpr, type BinaryOperator, type BooleanField, CLIPBOARD_OPERATIONS, type CallStep, type ClipboardOperation, type ClipboardStep, type CloseStep, type CodeNode, type ComponentDef, type ComponentNode, type ComponentsRef, type CompoundVariant, type CondExpr, type ConstelaAst, ConstelaError, type ConstelaProgram, DATA_SOURCE_TYPES, DATA_TRANSFORMS, type DataExpr, type DataSource, type DataSourceType, type DataTransform, type DisposeStep, type DomStep, type EachNode, type ElementNode, type ErrorCode, type ErrorOptions, type EventHandler, type Expression, type FetchStep, type GetExpr, HTTP_METHODS, type HttpMethod, type IfNode, type ImportExpr, type ImportStep, type LayoutProgram, type LifecycleHooks, type ListField, type LitExpr, type MarkdownNode, NAVIGATE_TARGETS, type NavigateStep, type NavigateTarget, type NotExpr, type NumberField, type ObjectField, PARAM_TYPES, type ParamDef, type ParamExpr, type ParamType, type Program, type RefExpr, type RouteDefinition, type RouteExpr, STORAGE_OPERATIONS, STORAGE_TYPES, type SendStep, type SetPathStep, type SetStep, type SlotNode, type StateExpr, type StateField, type StaticPathsDefinition, type StorageOperation, type StorageStep, type StorageType, type StringField, type StyleExpr, type StylePreset, type SubscribeStep, type TextNode, UPDATE_OPERATIONS, type UpdateOperation, type UpdateStep, type ValidationFailure, type ValidationResult, type ValidationSuccess, type VarExpr, type ViewNode, astSchema, createClipboardWriteMissingValueError, createComponentCycleError, createComponentNotFoundError, createComponentPropMissingError, createComponentPropTypeError, createCondElseRequiredError, createDataNotDefinedError, createDuplicateActionError, createDuplicateDefaultSlotError, createDuplicateSlotNameError, createImportsNotDefinedError, createInvalidClipboardOperationError, createInvalidDataSourceError, createInvalidNavigateTargetError, createInvalidSlotNameError, createInvalidStorageOperationError, createInvalidStorageTypeError, createLayoutMissingSlotError, createLayoutNotFoundError, createOperationInvalidForTypeError, createOperationMissingFieldError, createOperationUnknownError, createRouteNotDefinedError, createSchemaError, createSlotInLoopError, createStorageSetMissingValueError, createUndefinedActionError, createUndefinedDataError, createUndefinedDataSourceError, createUndefinedImportError, createUndefinedParamError, createUndefinedRefError, createUndefinedRouteParamError, createUndefinedStateError, createUndefinedStyleError, createUndefinedVarError, createUndefinedVariantError, createUnsupportedVersionError, findSimilarNames, isActionStep, isBinExpr, isBooleanField, isCallStep, isClipboardStep, isCodeNode, isComponentNode, isCondExpr, isConstelaError, isDataExpr, isDataSource, isDisposeStep, isEachNode, isElementNode, isEventHandler, isExpression, isFetchStep, isGetExpr, isIfNode, isImportExpr, isImportStep, isLayoutProgram, isLifecycleHooks, isListField, isLitExpr, isMarkdownNode, isNamedSlotNode, isNavigateStep, isNotExpr, isNumberField, isObjectField, isParamExpr, isRefExpr, isRouteDefinition, isRouteExpr, isSetStep, isSlotNode, isStateExpr, isStateField, isStaticPathsDefinition, isStorageStep, isStringField, isStyleExpr, isSubscribeStep, isTextNode, isUpdateStep, isVarExpr, isViewNode, validateAst };

package/dist/index.js

@@ -123,6 +123,22 @@ function isRefExpr(value) {
   if (value["expr"] !== "ref") return false;
   return typeof value["name"] === "string";
 }
+function isIndexExpr(value) {
+  if (!isObject(value)) return false;
+  if (value["expr"] !== "index") return false;
+  if (!("base" in value)) return false;
+  if (!("key" in value)) return false;
+  return true;
+}
+function isStyleExpr(value) {
+  if (!isObject(value)) return false;
+  if (value["expr"] !== "style") return false;
+  if (typeof value["name"] !== "string") return false;
+  if ("variants" in value && value["variants"] !== void 0) {
+    if (!isObject(value["variants"])) return false;
+  }
+  return true;
+}
 function isDataSource(value) {
   if (!isObject(value)) return false;
   const type = value["type"];
@@ -159,7 +175,7 @@ function isRouteDefinition(value) {
   return true;
 }
 function isExpression(value) {
-  return isLitExpr(value) || isStateExpr(value) || isVarExpr(value) || isBinExpr(value) || isNotExpr(value) || isParamExpr(value) || isCondExpr(value) || isGetExpr(value) || isRouteExpr(value) || isImportExpr(value) || isDataExpr(value) || isRefExpr(value);
+  return isLitExpr(value) || isStateExpr(value) || isVarExpr(value) || isBinExpr(value) || isNotExpr(value) || isParamExpr(value) || isCondExpr(value) || isGetExpr(value) || isRouteExpr(value) || isImportExpr(value) || isDataExpr(value) || isRefExpr(value) || isIndexExpr(value) || isStyleExpr(value);
 }
 function isElementNode(value) {
   if (!isObject(value)) return false;
@@ -375,11 +391,21 @@ function isLifecycleHooks(value) {
 var ConstelaError = class _ConstelaError extends Error {
   code;
   path;
-  constructor(code, message, path) {
+  severity;
+  suggestion;
+  expected;
+  actual;
+  context;
+  constructor(code, message, path, options) {
     super(message);
     this.name = "ConstelaError";
     this.code = code;
     this.path = path;
+    this.severity = options?.severity ?? "error";
+    this.suggestion = options?.suggestion;
+    this.expected = options?.expected;
+    this.actual = options?.actual;
+    this.context = options?.context;
     Object.setPrototypeOf(this, _ConstelaError.prototype);
   }
   /**
@@ -389,7 +415,12 @@ var ConstelaError = class _ConstelaError extends Error {
     return {
       code: this.code,
       message: this.message,
-      path: this.path
+      path: this.path,
+      severity: this.severity,
+      suggestion: this.suggestion,
+      expected: this.expected,
+      actual: this.actual,
+      context: this.context
     };
   }
 };
@@ -399,18 +430,20 @@ function isConstelaError(value) {
 function createSchemaError(message, path) {
   return new ConstelaError("SCHEMA_INVALID", message, path);
 }
-function createUndefinedStateError(stateName, path) {
+function createUndefinedStateError(stateName, path, options) {
   return new ConstelaError(
     "UNDEFINED_STATE",
     `Undefined state reference: '${stateName}' is not defined in state`,
-    path
+    path,
+    options
   );
 }
-function createUndefinedActionError(actionName, path) {
+function createUndefinedActionError(actionName, path, options) {
   return new ConstelaError(
     "UNDEFINED_ACTION",
     `Undefined action reference: '${actionName}' is not defined in actions`,
-    path
+    path,
+    options
   );
 }
 function createDuplicateActionError(actionName, path) {
@@ -434,11 +467,12 @@ function createUnsupportedVersionError(version) {
     "/version"
   );
 }
-function createComponentNotFoundError(name, path) {
+function createComponentNotFoundError(name, path, options) {
   return new ConstelaError(
     "COMPONENT_NOT_FOUND",
     `Component '${name}' is not defined in components`,
-    path
+    path,
+    options
   );
 }
 function createComponentPropMissingError(componentName, propName, path) {
@@ -644,13 +678,68 @@ function createInvalidNavigateTargetError(target, path) {
     path
   );
 }
+function createUndefinedStyleError(styleName, path, options) {
+  return new ConstelaError(
+    "UNDEFINED_STYLE",
+    `Undefined style reference: '${styleName}' is not defined in styles`,
+    path,
+    options
+  );
+}
+function createUndefinedVariantError(variantKey, styleName, path, options) {
+  return new ConstelaError(
+    "UNDEFINED_VARIANT",
+    `Undefined variant key: '${variantKey}' is not defined in style '${styleName}'`,
+    path,
+    options
+  );
+}
+function levenshteinDistance(a, b) {
+  const aLen = a.length;
+  const bLen = b.length;
+  let prev = Array.from({ length: bLen + 1 }, (_, j) => j);
+  let curr = new Array(bLen + 1).fill(0);
+  for (let i = 1; i <= aLen; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= bLen; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const deletion = (prev[j] ?? 0) + 1;
+      const insertion = (curr[j - 1] ?? 0) + 1;
+      const substitution = (prev[j - 1] ?? 0) + cost;
+      curr[j] = Math.min(deletion, insertion, substitution);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[bLen] ?? 0;
+}
+function findSimilarNames(target, candidates, maxDistance = 2) {
+  const results = [];
+  for (const candidate of candidates) {
+    const distance = levenshteinDistance(target, candidate);
+    if (distance <= maxDistance) {
+      results.push({ name: candidate, distance });
+      continue;
+    }
+    if (target.length >= 3 && candidate.toLowerCase().startsWith(target.toLowerCase())) {
+      const prefixDistance = candidate.length - target.length;
+      results.push({ name: candidate, distance: prefixDistance });
+    }
+  }
+  results.sort((a, b) => {
+    if (a.distance !== b.distance) {
+      return a.distance - b.distance;
+    }
+    return a.name.localeCompare(b.name);
+  });
+  return results.map((r) => r.name);
+}
 
 // src/schema/validator.ts
 function isObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var VALID_VIEW_KINDS = ["element", "text", "if", "each", "component", "slot", "markdown", "code"];
-var VALID_EXPR_TYPES = ["lit", "state", "var", "bin", "not", "param", "cond", "get"];
+var VALID_EXPR_TYPES = ["lit", "state", "var", "bin", "not", "param", "cond", "get", "style"];
 var VALID_PARAM_TYPES = ["string", "number", "boolean", "json"];
 var VALID_ACTION_TYPES = ["set", "update", "fetch"];
 var VALID_STATE_TYPES = ["number", "string", "list", "boolean", "object"];
@@ -777,7 +866,7 @@ function validateExpression(expr, path) {
     return { path: path + "/expr", message: "expr is required" };
   }
   if (!VALID_EXPR_TYPES.includes(exprType)) {
-    return { path: path + "/expr", message: "must be one of: lit, state, var, bin, not, param, cond, get" };
+    return { path: path + "/expr", message: "must be one of: lit, state, var, bin, not, param, cond, get, style" };
   }
   switch (exprType) {
     case "lit":
@@ -851,6 +940,20 @@ function validateExpression(expr, path) {
         return { path: path + "/path", message: "path is required" };
       }
       return validateExpression(expr["base"], path + "/base");
+    case "style":
+      if (typeof expr["name"] !== "string") {
+        return { path: path + "/name", message: "name is required" };
+      }
+      if ("variants" in expr && expr["variants"] !== void 0) {
+        if (!isObject2(expr["variants"])) {
+          return { path: path + "/variants", message: "variants must be an object" };
+        }
+        for (const [variantKey, variantValue] of Object.entries(expr["variants"])) {
+          const error = validateExpression(variantValue, path + "/variants/" + variantKey);
+          if (error) return error;
+        }
+      }
+      break;
   }
   return null;
 }
@@ -985,6 +1088,61 @@ function validateComponentDef(def, path) {
   if (viewError) return viewError;
   return null;
 }
+function validateStylePreset(preset, path) {
+  if (!isObject2(preset)) {
+    return { path, message: "must be an object" };
+  }
+  if (!("base" in preset)) {
+    return { path: path + "/base", message: "base is required" };
+  }
+  if (typeof preset["base"] !== "string") {
+    return { path: path + "/base", message: "base must be a string" };
+  }
+  if ("variants" in preset && preset["variants"] !== void 0) {
+    if (!isObject2(preset["variants"])) {
+      return { path: path + "/variants", message: "variants must be an object" };
+    }
+    for (const [variantKey, variantOptions] of Object.entries(preset["variants"])) {
+      if (!isObject2(variantOptions)) {
+        return { path: path + "/variants/" + variantKey, message: "variant options must be an object" };
+      }
+      for (const [optionKey, optionValue] of Object.entries(variantOptions)) {
+        if (typeof optionValue !== "string") {
+          return { path: path + "/variants/" + variantKey + "/" + optionKey, message: "variant value must be a string" };
+        }
+      }
+    }
+  }
+  if ("defaultVariants" in preset && preset["defaultVariants"] !== void 0) {
+    if (!isObject2(preset["defaultVariants"])) {
+      return { path: path + "/defaultVariants", message: "defaultVariants must be an object" };
+    }
+    const variantKeys = isObject2(preset["variants"]) ? Object.keys(preset["variants"]) : [];
+    for (const [key, value] of Object.entries(preset["defaultVariants"])) {
+      if (typeof value !== "string") {
+        return { path: path + "/defaultVariants/" + key, message: "default variant value must be a string" };
+      }
+      if (!variantKeys.includes(key)) {
+        return { path: path + "/defaultVariants/" + key, message: `'${key}' is not a defined variant` };
+      }
+    }
+  }
+  if ("compoundVariants" in preset && preset["compoundVariants"] !== void 0) {
+    if (!Array.isArray(preset["compoundVariants"])) {
+      return { path: path + "/compoundVariants", message: "compoundVariants must be an array" };
+    }
+    for (let i = 0; i < preset["compoundVariants"].length; i++) {
+      const compound = preset["compoundVariants"][i];
+      if (!isObject2(compound)) {
+        return { path: path + "/compoundVariants/" + i, message: "compound variant must be an object" };
+      }
+      if (typeof compound["class"] !== "string") {
+        return { path: path + "/compoundVariants/" + i + "/class", message: "class is required" };
+      }
+    }
+  }
+  return null;
+}
 function customValidateAst(input) {
   if (isObject2(input["state"])) {
     for (const [name, field] of Object.entries(input["state"])) {
@@ -992,6 +1150,12 @@ function customValidateAst(input) {
       if (error) return error;
     }
   }
+  if ("styles" in input && isObject2(input["styles"])) {
+    for (const [name, preset] of Object.entries(input["styles"])) {
+      const error = validateStylePreset(preset, "/styles/" + name);
+      if (error) return error;
+    }
+  }
   if (Array.isArray(input["actions"])) {
     for (let i = 0; i < input["actions"].length; i++) {
       const action = input["actions"][i];
@@ -1015,6 +1179,15 @@ function customValidateAst(input) {
   }
   return null;
 }
+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 collectSemanticContext(ast) {
   const stateNames = /* @__PURE__ */ new Set();
   const actionNames = /* @__PURE__ */ new Set();
@@ -1036,7 +1209,8 @@ function validateStateReferences(node, path, stateNames) {
   if (!isObject2(node)) return null;
   if (node["expr"] === "state" && typeof node["name"] === "string") {
     if (!stateNames.has(node["name"])) {
-      return createUndefinedStateError(node["name"], path + "/" + node["name"]);
+      const errorOptions = createErrorOptionsWithSuggestion(node["name"], stateNames);
+      return createUndefinedStateError(node["name"], path + "/" + node["name"], errorOptions);
     }
   }
   for (const [key, value] of Object.entries(node)) {
@@ -1062,7 +1236,8 @@ function validateActionTargets(ast, stateNames) {
       if (!isObject2(step)) continue;
       if ((step["do"] === "set" || step["do"] === "update") && typeof step["target"] === "string") {
         if (!stateNames.has(step["target"])) {
-          return createUndefinedStateError(step["target"], "/actions/" + i + "/steps/" + j + "/target");
+          const errorOptions = createErrorOptionsWithSuggestion(step["target"], stateNames);
+          return createUndefinedStateError(step["target"], "/actions/" + i + "/steps/" + j + "/target", errorOptions);
         }
       }
     }
@@ -1076,7 +1251,8 @@ function validateActionReferences(node, path, actionNames) {
       if (isObject2(propValue) && "event" in propValue && "action" in propValue) {
         const actionName = propValue["action"];
         if (typeof actionName === "string" && !actionNames.has(actionName)) {
-          return createUndefinedActionError(actionName, path + "/props/" + propName);
+          const errorOptions = createErrorOptionsWithSuggestion(actionName, actionNames);
+          return createUndefinedActionError(actionName, path + "/props/" + propName, errorOptions);
         }
       }
     }
@@ -1223,6 +1399,10 @@ var astSchema = {
     view: {
       $ref: "#/$defs/ViewNode"
     },
+    styles: {
+      type: "object",
+      additionalProperties: { $ref: "#/$defs/StylePreset" }
+    },
     components: {
       type: "object",
       additionalProperties: { $ref: "#/$defs/ComponentDef" }
@@ -1239,7 +1419,9 @@ var astSchema = {
         { $ref: "#/$defs/NotExpr" },
         { $ref: "#/$defs/ParamExpr" },
         { $ref: "#/$defs/CondExpr" },
-        { $ref: "#/$defs/GetExpr" }
+        { $ref: "#/$defs/GetExpr" },
+        { $ref: "#/$defs/IndexExpr" },
+        { $ref: "#/$defs/StyleExpr" }
       ]
     },
     LitExpr: {
@@ -1265,7 +1447,8 @@ var astSchema = {
       additionalProperties: false,
       properties: {
         expr: { type: "string", const: "state" },
-        name: { type: "string" }
+        name: { type: "string" },
+        path: { type: "string" }
       }
     },
     VarExpr: {
@@ -1332,6 +1515,61 @@ var astSchema = {
         path: { type: "string" }
       }
     },
+    IndexExpr: {
+      type: "object",
+      required: ["expr", "base", "key"],
+      additionalProperties: false,
+      properties: {
+        expr: { type: "string", const: "index" },
+        base: { $ref: "#/$defs/Expression" },
+        key: { $ref: "#/$defs/Expression" }
+      }
+    },
+    StyleExpr: {
+      type: "object",
+      required: ["expr", "name"],
+      additionalProperties: false,
+      properties: {
+        expr: { type: "string", const: "style" },
+        name: { type: "string" },
+        variants: {
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/Expression" }
+        }
+      }
+    },
+    // ==================== Style Presets ====================
+    StylePreset: {
+      type: "object",
+      required: ["base"],
+      additionalProperties: false,
+      properties: {
+        base: { type: "string" },
+        variants: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            additionalProperties: { type: "string" }
+          }
+        },
+        defaultVariants: {
+          type: "object",
+          additionalProperties: { type: "string" }
+        },
+        compoundVariants: {
+          type: "array",
+          items: { $ref: "#/$defs/CompoundVariant" }
+        }
+      }
+    },
+    CompoundVariant: {
+      type: "object",
+      required: ["class"],
+      additionalProperties: { type: "string" },
+      properties: {
+        class: { type: "string" }
+      }
+    },
     // ==================== State Fields ====================
     StateField: {
       oneOf: [
@@ -1654,8 +1892,11 @@ export {
   createUndefinedRefError,
   createUndefinedRouteParamError,
   createUndefinedStateError,
+  createUndefinedStyleError,
   createUndefinedVarError,
+  createUndefinedVariantError,
   createUnsupportedVersionError,
+  findSimilarNames,
   isActionStep,
   isBinExpr,
   isBooleanField,
@@ -1698,6 +1939,7 @@ export {
   isStaticPathsDefinition,
   isStorageStep,
   isStringField,
+  isStyleExpr,
   isSubscribeStep,
   isTextNode,
   isUpdateStep,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Core types, schema, and validator for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",