@constela/core 0.8.0 → 0.9.1

package/README.md

@@ -42,7 +42,7 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 
 ## Expression Types
 
-12 expression types for constrained computation:
+13 expression types for constrained computation:
 
 | Type | JSON Example | Description |
 |------|-------------|-------------|
@@ -58,6 +58,7 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 | `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:** `+`, `-`, `*`, `/`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`
 
@@ -78,6 +79,9 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 // Loop node
 { "kind": "each", "items": { "expr": "state", "name": "todos" }, "as": "item", "body": { ... } }
 
+// Loop node with key (efficient diffing)
+{ "kind": "each", "items": { ... }, "as": "item", "key": { "expr": "var", "name": "item", "path": "id" }, "body": { ... } }
+
 // Component node
 { "kind": "component", "name": "Button", "props": { "label": { ... } } }
 
@@ -94,7 +98,7 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 
 ## Action Step Types
 
-11 step types for declarative actions:
+14 step types for declarative actions:
 
 ```json
 // Set state value
@@ -104,6 +108,10 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 { "do": "update", "target": "count", "operation": "increment" }
 { "do": "update", "target": "todos", "operation": "push", "value": { ... } }
 
+// Set nested path (fine-grained update)
+{ "do": "setPath", "target": "posts", "path": [5, "liked"], "value": { "expr": "lit", "value": true } }
+{ "do": "setPath", "target": "posts", "path": { "expr": "var", "name": "payload", "path": "index" }, "field": "liked", "value": { ... } }
+
 // HTTP request
 { "do": "fetch", "url": { ... }, "method": "GET", "onSuccess": [ ... ], "onError": [ ... ] }
 
@@ -130,6 +138,30 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 
 // DOM manipulation
 { "do": "dom", "operation": "addClass", "ref": "myElement", "value": { ... } }
+
+// WebSocket send
+{ "do": "send", "connection": "chat", "data": { "expr": "state", "name": "inputText" } }
+
+// WebSocket close
+{ "do": "close", "connection": "chat" }
+```
+
+## Connections
+
+WebSocket connections for real-time data:
+
+```json
+{
+  "connections": {
+    "chat": {
+      "type": "websocket",
+      "url": "wss://api.example.com/ws",
+      "onMessage": { "action": "handleMessage" },
+      "onOpen": { "action": "connectionOpened" },
+      "onClose": { "action": "connectionClosed" }
+    }
+  }
+}
 ```
 
 **Update Operations:**
@@ -160,6 +192,54 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 }
 ```
 
+## 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 |
@@ -191,6 +271,20 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 | `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
 

package/dist/index.d.ts

@@ -135,7 +135,14 @@ interface StyleExpr {
     name: string;
     variants?: Record<string, Expression>;
 }
-type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr | CondExpr | GetExpr | RouteExpr | ImportExpr | DataExpr | RefExpr | IndexExpr | StyleExpr;
+/**
+ * Concat expression - concatenates multiple expressions into a string
+ */
+interface ConcatExpr {
+    expr: 'concat';
+    items: Expression[];
+}
+type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr | CondExpr | GetExpr | RouteExpr | ImportExpr | DataExpr | RefExpr | IndexExpr | StyleExpr | ConcatExpr;
 /**
  * Number state field
  */
@@ -208,6 +215,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
  */
@@ -302,7 +325,22 @@ interface DomStep {
     value?: Expression;
     attribute?: string;
 }
-type ActionStep = SetStep | UpdateStep | FetchStep | StorageStep | ClipboardStep | NavigateStep | ImportStep | CallStep | SubscribeStep | DisposeStep | DomStep;
+/**
+ * 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
  */
@@ -580,6 +618,10 @@ 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 concat expression
+ */
+declare function isConcatExpr(value: unknown): value is ConcatExpr;
 /**
  * Checks if value is a data source
  */
@@ -1678,4 +1720,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 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 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 };
+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 ConcatExpr, 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, isConcatExpr, 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

@@ -139,6 +139,9 @@ function isStyleExpr(value) {
   }
   return true;
 }
+function isConcatExpr(value) {
+  return typeof value === "object" && value !== null && value.expr === "concat" && Array.isArray(value.items);
+}
 function isDataSource(value) {
   if (!isObject(value)) return false;
   const type = value["type"];
@@ -175,7 +178,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) || isIndexExpr(value) || isStyleExpr(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) || isConcatExpr(value);
 }
 function isElementNode(value) {
   if (!isObject(value)) return false;
@@ -1904,6 +1907,7 @@ export {
   isClipboardStep,
   isCodeNode,
   isComponentNode,
+  isConcatExpr,
   isCondExpr,
   isConstelaError,
   isDataExpr,

package/package.json

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