@constela/core 0.9.1 → 0.11.0

package/README.md

@@ -42,7 +42,7 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 
 ## Expression Types
 
-13 expression types for constrained computation:
+14 expression types for constrained computation:
 
 | Type | JSON Example | Description |
 |------|-------------|-------------|
@@ -59,9 +59,29 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 | `data` | `{ "expr": "data", "name": "posts" }` | Build-time data |
 | `ref` | `{ "expr": "ref", "name": "inputEl" }` | DOM element ref |
 | `style` | `{ "expr": "style", "name": "button", "variants": {...} }` | Style reference |
+| `concat` | `{ "expr": "concat", "items": [...] }` | String concatenation |
 
 **Binary Operators:** `+`, `-`, `*`, `/`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`
 
+**Concat Expression:**
+
+Concatenate multiple expressions into a single string:
+
+```json
+{
+  "expr": "concat",
+  "items": [
+    { "expr": "lit", "value": "Hello, " },
+    { "expr": "var", "name": "username" },
+    { "expr": "lit", "value": "!" }
+  ]
+}
+```
+
+- Evaluates each item and joins them as strings
+- `null`/`undefined` values become empty strings
+- Numbers and booleans are converted to strings
+
 ## View Node Types
 
 8 node types for building UI:
@@ -305,11 +325,11 @@ if (result.ok) {
 
 ### Type Guards
 
-47 type guard functions for runtime type checking:
+48 type guard functions for runtime type checking:
 
 ```typescript
 import {
-  isLitExpr, isStateExpr, isVarExpr, isBinExpr,
+  isLitExpr, isStateExpr, isVarExpr, isBinExpr, isConcatExpr,
   isElementNode, isTextNode, isIfNode, isEachNode,
   isSetStep, isUpdateStep, isFetchStep,
   isNumberField, isStringField, isListField,

package/dist/index.d.ts

@@ -16,6 +16,10 @@ declare const STORAGE_TYPES: readonly ["local", "session"];
 type StorageType = (typeof STORAGE_TYPES)[number];
 declare const CLIPBOARD_OPERATIONS: readonly ["write", "read"];
 type ClipboardOperation = (typeof CLIPBOARD_OPERATIONS)[number];
+declare const FOCUS_OPERATIONS: readonly ["focus", "blur", "select"];
+type FocusOperation = (typeof FOCUS_OPERATIONS)[number];
+declare const VALIDITY_PROPERTIES: readonly ["valid", "valueMissing", "typeMismatch", "patternMismatch", "tooLong", "tooShort", "rangeUnderflow", "rangeOverflow", "customError", "message"];
+type ValidityProperty = (typeof VALIDITY_PROPERTIES)[number];
 declare const NAVIGATE_TARGETS: readonly ["_self", "_blank"];
 type NavigateTarget = (typeof NAVIGATE_TARGETS)[number];
 declare const PARAM_TYPES: readonly ["string", "number", "boolean", "json"];
@@ -142,7 +146,15 @@ interface ConcatExpr {
     expr: 'concat';
     items: Expression[];
 }
-type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr | CondExpr | GetExpr | RouteExpr | ImportExpr | DataExpr | RefExpr | IndexExpr | StyleExpr | ConcatExpr;
+/**
+ * Validity expression - gets form element validation state
+ */
+interface ValidityExpr {
+    expr: 'validity';
+    ref: string;
+    property?: ValidityProperty;
+}
+type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr | CondExpr | GetExpr | RouteExpr | ImportExpr | DataExpr | RefExpr | IndexExpr | StyleExpr | ConcatExpr | ValidityExpr;
 /**
  * Number state field
  */
@@ -340,7 +352,51 @@ interface CloseStep {
     do: 'close';
     connection: string;
 }
-type ActionStep = SetStep | UpdateStep | SetPathStep | FetchStep | StorageStep | ClipboardStep | NavigateStep | ImportStep | CallStep | SubscribeStep | DisposeStep | DomStep | SendStep | CloseStep;
+/**
+ * Delay step - executes steps after a delay (setTimeout equivalent)
+ */
+interface DelayStep {
+    do: 'delay';
+    ms: Expression;
+    then: ActionStep[];
+    result?: string;
+}
+/**
+ * Interval step - executes an action repeatedly (setInterval equivalent)
+ */
+interface IntervalStep {
+    do: 'interval';
+    ms: Expression;
+    action: string;
+    result?: string;
+}
+/**
+ * ClearTimer step - clears a timer (clearTimeout/clearInterval equivalent)
+ */
+interface ClearTimerStep {
+    do: 'clearTimer';
+    target: Expression;
+}
+/**
+ * Focus step - manages form element focus
+ */
+interface FocusStep {
+    do: 'focus';
+    target: Expression;
+    operation: FocusOperation;
+    onSuccess?: ActionStep[];
+    onError?: ActionStep[];
+}
+type ActionStep = SetStep | UpdateStep | SetPathStep | FetchStep | StorageStep | ClipboardStep | NavigateStep | ImportStep | CallStep | SubscribeStep | DisposeStep | DomStep | SendStep | CloseStep | DelayStep | IntervalStep | ClearTimerStep | FocusStep;
+type LocalActionStep = SetStep | UpdateStep | SetPathStep;
+/**
+ * Event handler options for special events like intersect
+ */
+interface EventHandlerOptions {
+    threshold?: number;
+    rootMargin?: string;
+    once?: boolean;
+}
 /**
  * Event handler - binds an event to an action
  */
@@ -348,6 +404,9 @@ interface EventHandler {
     event: string;
     action: string;
     payload?: Expression;
+    debounce?: number;
+    throttle?: number;
+    options?: EventHandlerOptions;
 }
 /**
  * Action definition - a named sequence of steps
@@ -356,6 +415,14 @@ interface ActionDefinition {
     name: string;
     steps: ActionStep[];
 }
+/**
+ * Local action definition - a named sequence of local steps
+ * Only set, update, and setPath steps are allowed
+ */
+interface LocalActionDefinition {
+    name: string;
+    steps: LocalActionStep[];
+}
 /**
  * Element node - represents an HTML element
  */
@@ -425,9 +492,19 @@ interface CodeNode {
     language: Expression;
     content: Expression;
 }
-type ViewNode = ElementNode | TextNode | IfNode | EachNode | ComponentNode | SlotNode | MarkdownNode | CodeNode;
+/**
+ * Portal node - renders children to a different DOM location
+ */
+interface PortalNode {
+    kind: 'portal';
+    target: 'body' | 'head' | string;
+    children: ViewNode[];
+}
+type ViewNode = ElementNode | TextNode | IfNode | EachNode | ComponentNode | SlotNode | MarkdownNode | CodeNode | PortalNode;
 interface ComponentDef {
     params?: Record<string, ParamDef>;
+    localState?: Record<string, StateField>;
+    localActions?: LocalActionDefinition[];
     view: ViewNode;
 }
 /**
@@ -622,6 +699,10 @@ 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 validity expression
+ */
+declare function isValidityExpr(value: unknown): value is ValidityExpr;
 /**
  * Checks if value is a data source
  */
@@ -670,6 +751,10 @@ declare function isMarkdownNode(value: unknown): value is MarkdownNode;
  * Checks if value is a code node
  */
 declare function isCodeNode(value: unknown): value is CodeNode;
+/**
+ * Checks if value is a portal node
+ */
+declare function isPortalNode(value: unknown): value is PortalNode;
 /**
  * Checks if value is any valid view node
  */
@@ -682,6 +767,10 @@ declare function isSetStep(value: unknown): value is SetStep;
  * Checks if value is an update step
  */
 declare function isUpdateStep(value: unknown): value is UpdateStep;
+/**
+ * Checks if value is a setPath step
+ */
+declare function isSetPathStep(value: unknown): value is SetPathStep;
 /**
  * Checks if value is a fetch step
  */
@@ -714,10 +803,23 @@ declare function isSubscribeStep(value: unknown): value is SubscribeStep;
  * Checks if value is a dispose step
  */
 declare function isDisposeStep(value: unknown): value is DisposeStep;
+/**
+ * Checks if value is a focus step
+ */
+declare function isFocusStep(value: unknown): value is FocusStep;
 /**
  * Checks if value is any valid action step
  */
 declare function isActionStep(value: unknown): value is ActionStep;
+/**
+ * Checks if value is a valid local action step
+ * Local actions only allow set, update, and setPath steps
+ */
+declare function isLocalActionStep(value: unknown): value is LocalActionStep;
+/**
+ * Checks if value is a local action definition
+ */
+declare function isLocalActionDefinition(value: unknown): value is LocalActionDefinition;
 /**
  * Checks if value is a number field
  */
@@ -770,7 +872,7 @@ 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' | 'UNDEFINED_STYLE' | 'UNDEFINED_VARIANT';
+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' | 'UNDEFINED_LOCAL_STATE' | 'LOCAL_ACTION_INVALID_STEP';
 /**
  * Options for creating enhanced ConstelaError instances
  */
@@ -969,6 +1071,14 @@ declare function createUndefinedStyleError(styleName: string, path?: string, opt
  * Creates an undefined variant key error
  */
 declare function createUndefinedVariantError(variantKey: string, styleName: string, path?: string, options?: ErrorOptions): ConstelaError;
+/**
+ * Creates an undefined local state reference error
+ */
+declare function createUndefinedLocalStateError(stateName: string, path?: string, options?: ErrorOptions): ConstelaError;
+/**
+ * Creates a local action invalid step error
+ */
+declare function createLocalActionInvalidStepError(stepType: string, path?: string): ConstelaError;
 /**
  * Finds similar names from a set of candidates using Levenshtein distance
  * and prefix matching.
@@ -1077,6 +1187,8 @@ declare const astSchema: {
                 readonly $ref: "#/$defs/IndexExpr";
             }, {
                 readonly $ref: "#/$defs/StyleExpr";
+            }, {
+                readonly $ref: "#/$defs/ValidityExpr";
             }];
         };
         readonly LitExpr: {
@@ -1263,6 +1375,24 @@ declare const astSchema: {
                 };
             };
         };
+        readonly ValidityExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "ref"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "validity";
+                };
+                readonly ref: {
+                    readonly type: "string";
+                };
+                readonly property: {
+                    readonly type: "string";
+                    readonly enum: readonly ["valid", "valueMissing", "typeMismatch", "patternMismatch", "tooLong", "tooShort", "rangeUnderflow", "rangeOverflow", "customError", "message"];
+                };
+            };
+        };
         readonly StylePreset: {
             readonly type: "object";
             readonly required: readonly ["base"];
@@ -1396,6 +1526,14 @@ declare const astSchema: {
                 readonly $ref: "#/$defs/UpdateStep";
             }, {
                 readonly $ref: "#/$defs/FetchStep";
+            }, {
+                readonly $ref: "#/$defs/DelayStep";
+            }, {
+                readonly $ref: "#/$defs/IntervalStep";
+            }, {
+                readonly $ref: "#/$defs/ClearTimerStep";
+            }, {
+                readonly $ref: "#/$defs/FocusStep";
             }];
         };
         readonly SetStep: {
@@ -1478,6 +1616,93 @@ declare const astSchema: {
                 };
             };
         };
+        readonly DelayStep: {
+            readonly type: "object";
+            readonly required: readonly ["do", "ms", "then"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly do: {
+                    readonly type: "string";
+                    readonly const: "delay";
+                };
+                readonly ms: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly then: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ActionStep";
+                    };
+                };
+                readonly result: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly IntervalStep: {
+            readonly type: "object";
+            readonly required: readonly ["do", "ms", "action"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly do: {
+                    readonly type: "string";
+                    readonly const: "interval";
+                };
+                readonly ms: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly action: {
+                    readonly type: "string";
+                };
+                readonly result: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly ClearTimerStep: {
+            readonly type: "object";
+            readonly required: readonly ["do", "target"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly do: {
+                    readonly type: "string";
+                    readonly const: "clearTimer";
+                };
+                readonly target: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+            };
+        };
+        readonly FocusStep: {
+            readonly type: "object";
+            readonly required: readonly ["do", "target", "operation"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly do: {
+                    readonly type: "string";
+                    readonly const: "focus";
+                };
+                readonly target: {
+                    readonly $ref: "#/$defs/Expression";
+                };
+                readonly operation: {
+                    readonly type: "string";
+                    readonly enum: readonly ["focus", "blur", "select"];
+                };
+                readonly onSuccess: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ActionStep";
+                    };
+                };
+                readonly onError: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ActionStep";
+                    };
+                };
+            };
+        };
         readonly EventHandler: {
             readonly type: "object";
             readonly required: readonly ["event", "action"];
@@ -1492,6 +1717,30 @@ declare const astSchema: {
                 readonly payload: {
                     readonly $ref: "#/$defs/Expression";
                 };
+                readonly debounce: {
+                    readonly type: "number";
+                };
+                readonly throttle: {
+                    readonly type: "number";
+                };
+                readonly options: {
+                    readonly $ref: "#/$defs/EventHandlerOptions";
+                };
+            };
+        };
+        readonly EventHandlerOptions: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly threshold: {
+                    readonly type: "number";
+                };
+                readonly rootMargin: {
+                    readonly type: "string";
+                };
+                readonly once: {
+                    readonly type: "boolean";
+                };
             };
         };
         readonly ActionDefinition: {
@@ -1527,6 +1776,8 @@ declare const astSchema: {
                 readonly $ref: "#/$defs/MarkdownNode";
             }, {
                 readonly $ref: "#/$defs/CodeNode";
+            }, {
+                readonly $ref: "#/$defs/PortalNode";
             }];
         };
         readonly ElementNode: {
@@ -1687,6 +1938,26 @@ declare const astSchema: {
                 };
             };
         };
+        readonly PortalNode: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "target", "children"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly const: "portal";
+                };
+                readonly target: {
+                    readonly type: "string";
+                };
+                readonly children: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ViewNode";
+                    };
+                };
+            };
+        };
         readonly ParamDef: {
             readonly type: "object";
             readonly required: readonly ["type"];
@@ -1720,4 +1991,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 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 };
+export { type ActionDefinition, type ActionStep, BINARY_OPERATORS, type BinExpr, type BinaryOperator, type BooleanField, CLIPBOARD_OPERATIONS, type CallStep, type ClearTimerStep, 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 DelayStep, type DisposeStep, type DomStep, type EachNode, type ElementNode, type ErrorCode, type ErrorOptions, type EventHandler, type EventHandlerOptions, type Expression, FOCUS_OPERATIONS, type FetchStep, type FocusOperation, type FocusStep, type GetExpr, HTTP_METHODS, type HttpMethod, type IfNode, type ImportExpr, type ImportStep, type IntervalStep, type LayoutProgram, type LifecycleHooks, type ListField, type LitExpr, type LocalActionDefinition, type LocalActionStep, type MarkdownNode, NAVIGATE_TARGETS, type NavigateStep, type NavigateTarget, type NotExpr, type NumberField, type ObjectField, PARAM_TYPES, type ParamDef, type ParamExpr, type ParamType, type PortalNode, 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, VALIDITY_PROPERTIES, type ValidationFailure, type ValidationResult, type ValidationSuccess, type ValidityExpr, type ValidityProperty, type VarExpr, type ViewNode, astSchema, createClipboardWriteMissingValueError, createComponentCycleError, createComponentNotFoundError, createComponentPropMissingError, createComponentPropTypeError, createCondElseRequiredError, createDataNotDefinedError, createDuplicateActionError, createDuplicateDefaultSlotError, createDuplicateSlotNameError, createImportsNotDefinedError, createInvalidClipboardOperationError, createInvalidDataSourceError, createInvalidNavigateTargetError, createInvalidSlotNameError, createInvalidStorageOperationError, createInvalidStorageTypeError, createLayoutMissingSlotError, createLayoutNotFoundError, createLocalActionInvalidStepError, createOperationInvalidForTypeError, createOperationMissingFieldError, createOperationUnknownError, createRouteNotDefinedError, createSchemaError, createSlotInLoopError, createStorageSetMissingValueError, createUndefinedActionError, createUndefinedDataError, createUndefinedDataSourceError, createUndefinedImportError, createUndefinedLocalStateError, 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, isFocusStep, isGetExpr, isIfNode, isImportExpr, isImportStep, isLayoutProgram, isLifecycleHooks, isListField, isLitExpr, isLocalActionDefinition, isLocalActionStep, isMarkdownNode, isNamedSlotNode, isNavigateStep, isNotExpr, isNumberField, isObjectField, isParamExpr, isPortalNode, isRefExpr, isRouteDefinition, isRouteExpr, isSetPathStep, isSetStep, isSlotNode, isStateExpr, isStateField, isStaticPathsDefinition, isStorageStep, isStringField, isStyleExpr, isSubscribeStep, isTextNode, isUpdateStep, isValidityExpr, isVarExpr, isViewNode, validateAst };

package/dist/index.js

@@ -29,6 +29,19 @@ var HTTP_METHODS = ["GET", "POST", "PUT", "DELETE"];
 var STORAGE_OPERATIONS = ["get", "set", "remove"];
 var STORAGE_TYPES = ["local", "session"];
 var CLIPBOARD_OPERATIONS = ["write", "read"];
+var FOCUS_OPERATIONS = ["focus", "blur", "select"];
+var VALIDITY_PROPERTIES = [
+  "valid",
+  "valueMissing",
+  "typeMismatch",
+  "patternMismatch",
+  "tooLong",
+  "tooShort",
+  "rangeUnderflow",
+  "rangeOverflow",
+  "customError",
+  "message"
+];
 var NAVIGATE_TARGETS = ["_self", "_blank"];
 var PARAM_TYPES = ["string", "number", "boolean", "json"];
 var DATA_TRANSFORMS = ["mdx", "yaml", "csv"];
@@ -142,6 +155,17 @@ function isStyleExpr(value) {
 function isConcatExpr(value) {
   return typeof value === "object" && value !== null && value.expr === "concat" && Array.isArray(value.items);
 }
+function isValidityExpr(value) {
+  if (!isObject(value)) return false;
+  if (value["expr"] !== "validity") return false;
+  if (typeof value["ref"] !== "string") return false;
+  if ("property" in value && value["property"] !== void 0) {
+    if (!VALIDITY_PROPERTIES.includes(value["property"])) {
+      return false;
+    }
+  }
+  return true;
+}
 function isDataSource(value) {
   if (!isObject(value)) return false;
   const type = value["type"];
@@ -178,7 +202,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) || isConcatExpr(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) || isValidityExpr(value);
 }
 function isElementNode(value) {
   if (!isObject(value)) return false;
@@ -233,8 +257,15 @@ function isCodeNode(value) {
   if (!("content" in value) || !isObject(value["content"])) return false;
   return true;
 }
+function isPortalNode(value) {
+  if (!isObject(value)) return false;
+  if (value["kind"] !== "portal") return false;
+  if (typeof value["target"] !== "string") return false;
+  if (!Array.isArray(value["children"])) return false;
+  return true;
+}
 function isViewNode(value) {
-  return isElementNode(value) || isTextNode(value) || isIfNode(value) || isEachNode(value) || isComponentNode(value) || isSlotNode(value) || isMarkdownNode(value) || isCodeNode(value);
+  return isElementNode(value) || isTextNode(value) || isIfNode(value) || isEachNode(value) || isComponentNode(value) || isSlotNode(value) || isMarkdownNode(value) || isCodeNode(value) || isPortalNode(value);
 }
 function isSetStep(value) {
   if (!isObject(value)) return false;
@@ -252,6 +283,14 @@ function isUpdateStep(value) {
   }
   return true;
 }
+function isSetPathStep(value) {
+  if (!isObject(value)) return false;
+  if (value["do"] !== "setPath") return false;
+  if (typeof value["target"] !== "string") return false;
+  if (!isObject(value["path"])) return false;
+  if (!isObject(value["value"])) return false;
+  return true;
+}
 function isFetchStep(value) {
   if (!isObject(value)) return false;
   if (value["do"] !== "fetch") return false;
@@ -321,8 +360,49 @@ function isDisposeStep(value) {
   if (!isObject(value["target"])) return false;
   return true;
 }
+function isDelayStep(value) {
+  if (!isObject(value)) return false;
+  if (value["do"] !== "delay") return false;
+  if (!isObject(value["ms"])) return false;
+  if (!Array.isArray(value["then"])) return false;
+  return true;
+}
+function isIntervalStep(value) {
+  if (!isObject(value)) return false;
+  if (value["do"] !== "interval") return false;
+  if (!isObject(value["ms"])) return false;
+  if (typeof value["action"] !== "string") return false;
+  return true;
+}
+function isClearTimerStep(value) {
+  if (!isObject(value)) return false;
+  if (value["do"] !== "clearTimer") return false;
+  if (!isObject(value["target"])) return false;
+  return true;
+}
+function isFocusStep(value) {
+  if (!isObject(value)) return false;
+  if (value["do"] !== "focus") return false;
+  if (!isObject(value["target"])) return false;
+  if (!FOCUS_OPERATIONS.includes(value["operation"])) {
+    return false;
+  }
+  return true;
+}
 function isActionStep(value) {
-  return isSetStep(value) || isUpdateStep(value) || isFetchStep(value) || isStorageStep(value) || isClipboardStep(value) || isNavigateStep(value) || isImportStep(value) || isCallStep(value) || isSubscribeStep(value) || isDisposeStep(value);
+  return isSetStep(value) || isUpdateStep(value) || isSetPathStep(value) || isFetchStep(value) || isStorageStep(value) || isClipboardStep(value) || isNavigateStep(value) || isImportStep(value) || isCallStep(value) || isSubscribeStep(value) || isDisposeStep(value) || isDelayStep(value) || isIntervalStep(value) || isClearTimerStep(value) || isFocusStep(value);
+}
+function isLocalActionStep(value) {
+  return isSetStep(value) || isUpdateStep(value) || isSetPathStep(value);
+}
+function isLocalActionDefinition(value) {
+  if (!isObject(value)) return false;
+  if (typeof value["name"] !== "string") return false;
+  if (!Array.isArray(value["steps"])) return false;
+  for (const step of value["steps"]) {
+    if (!isLocalActionStep(step)) return false;
+  }
+  return true;
 }
 function isNumberField(value) {
   if (!isObject(value)) return false;
@@ -697,6 +777,21 @@ function createUndefinedVariantError(variantKey, styleName, path, options) {
     options
   );
 }
+function createUndefinedLocalStateError(stateName, path, options) {
+  return new ConstelaError(
+    "UNDEFINED_LOCAL_STATE",
+    `Undefined local state reference: '${stateName}' is not defined in localState`,
+    path,
+    options
+  );
+}
+function createLocalActionInvalidStepError(stepType, path) {
+  return new ConstelaError(
+    "LOCAL_ACTION_INVALID_STEP",
+    `Invalid step type '${stepType}' in local action. Only 'set', 'update', and 'setPath' are allowed`,
+    path
+  );
+}
 function levenshteinDistance(a, b) {
   const aLen = a.length;
   const bLen = b.length;
@@ -1424,7 +1519,8 @@ var astSchema = {
         { $ref: "#/$defs/CondExpr" },
         { $ref: "#/$defs/GetExpr" },
         { $ref: "#/$defs/IndexExpr" },
-        { $ref: "#/$defs/StyleExpr" }
+        { $ref: "#/$defs/StyleExpr" },
+        { $ref: "#/$defs/ValidityExpr" }
       ]
     },
     LitExpr: {
@@ -1541,6 +1637,19 @@ var astSchema = {
         }
       }
     },
+    ValidityExpr: {
+      type: "object",
+      required: ["expr", "ref"],
+      additionalProperties: false,
+      properties: {
+        expr: { type: "string", const: "validity" },
+        ref: { type: "string" },
+        property: {
+          type: "string",
+          enum: ["valid", "valueMissing", "typeMismatch", "patternMismatch", "tooLong", "tooShort", "rangeUnderflow", "rangeOverflow", "customError", "message"]
+        }
+      }
+    },
     // ==================== Style Presets ====================
     StylePreset: {
       type: "object",
@@ -1633,7 +1742,11 @@ var astSchema = {
       oneOf: [
         { $ref: "#/$defs/SetStep" },
         { $ref: "#/$defs/UpdateStep" },
-        { $ref: "#/$defs/FetchStep" }
+        { $ref: "#/$defs/FetchStep" },
+        { $ref: "#/$defs/DelayStep" },
+        { $ref: "#/$defs/IntervalStep" },
+        { $ref: "#/$defs/ClearTimerStep" },
+        { $ref: "#/$defs/FocusStep" }
       ]
     },
     SetStep: {
@@ -1685,6 +1798,61 @@ var astSchema = {
         }
       }
     },
+    DelayStep: {
+      type: "object",
+      required: ["do", "ms", "then"],
+      additionalProperties: false,
+      properties: {
+        do: { type: "string", const: "delay" },
+        ms: { $ref: "#/$defs/Expression" },
+        then: {
+          type: "array",
+          items: { $ref: "#/$defs/ActionStep" }
+        },
+        result: { type: "string" }
+      }
+    },
+    IntervalStep: {
+      type: "object",
+      required: ["do", "ms", "action"],
+      additionalProperties: false,
+      properties: {
+        do: { type: "string", const: "interval" },
+        ms: { $ref: "#/$defs/Expression" },
+        action: { type: "string" },
+        result: { type: "string" }
+      }
+    },
+    ClearTimerStep: {
+      type: "object",
+      required: ["do", "target"],
+      additionalProperties: false,
+      properties: {
+        do: { type: "string", const: "clearTimer" },
+        target: { $ref: "#/$defs/Expression" }
+      }
+    },
+    FocusStep: {
+      type: "object",
+      required: ["do", "target", "operation"],
+      additionalProperties: false,
+      properties: {
+        do: { type: "string", const: "focus" },
+        target: { $ref: "#/$defs/Expression" },
+        operation: {
+          type: "string",
+          enum: ["focus", "blur", "select"]
+        },
+        onSuccess: {
+          type: "array",
+          items: { $ref: "#/$defs/ActionStep" }
+        },
+        onError: {
+          type: "array",
+          items: { $ref: "#/$defs/ActionStep" }
+        }
+      }
+    },
     // ==================== Event Handler ====================
     EventHandler: {
       type: "object",
@@ -1693,7 +1861,19 @@ var astSchema = {
       properties: {
         event: { type: "string" },
         action: { type: "string" },
-        payload: { $ref: "#/$defs/Expression" }
+        payload: { $ref: "#/$defs/Expression" },
+        debounce: { type: "number" },
+        throttle: { type: "number" },
+        options: { $ref: "#/$defs/EventHandlerOptions" }
+      }
+    },
+    EventHandlerOptions: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        threshold: { type: "number" },
+        rootMargin: { type: "string" },
+        once: { type: "boolean" }
       }
     },
     // ==================== Action Definition ====================
@@ -1719,7 +1899,8 @@ var astSchema = {
         { $ref: "#/$defs/ComponentNode" },
         { $ref: "#/$defs/SlotNode" },
         { $ref: "#/$defs/MarkdownNode" },
-        { $ref: "#/$defs/CodeNode" }
+        { $ref: "#/$defs/CodeNode" },
+        { $ref: "#/$defs/PortalNode" }
       ]
     },
     ElementNode: {
@@ -1821,6 +2002,19 @@ var astSchema = {
         content: { $ref: "#/$defs/Expression" }
       }
     },
+    PortalNode: {
+      type: "object",
+      required: ["kind", "target", "children"],
+      additionalProperties: false,
+      properties: {
+        kind: { type: "string", const: "portal" },
+        target: { type: "string" },
+        children: {
+          type: "array",
+          items: { $ref: "#/$defs/ViewNode" }
+        }
+      }
+    },
     // ==================== Component Definition ====================
     ParamDef: {
       type: "object",
@@ -1854,12 +2048,14 @@ export {
   ConstelaError,
   DATA_SOURCE_TYPES,
   DATA_TRANSFORMS,
+  FOCUS_OPERATIONS,
   HTTP_METHODS,
   NAVIGATE_TARGETS,
   PARAM_TYPES,
   STORAGE_OPERATIONS,
   STORAGE_TYPES,
   UPDATE_OPERATIONS,
+  VALIDITY_PROPERTIES,
   astSchema,
   createClipboardWriteMissingValueError,
   createComponentCycleError,
@@ -1880,6 +2076,7 @@ export {
   createInvalidStorageTypeError,
   createLayoutMissingSlotError,
   createLayoutNotFoundError,
+  createLocalActionInvalidStepError,
   createOperationInvalidForTypeError,
   createOperationMissingFieldError,
   createOperationUnknownError,
@@ -1891,6 +2088,7 @@ export {
   createUndefinedDataError,
   createUndefinedDataSourceError,
   createUndefinedImportError,
+  createUndefinedLocalStateError,
   createUndefinedParamError,
   createUndefinedRefError,
   createUndefinedRouteParamError,
@@ -1918,6 +2116,7 @@ export {
   isEventHandler,
   isExpression,
   isFetchStep,
+  isFocusStep,
   isGetExpr,
   isIfNode,
   isImportExpr,
@@ -1926,6 +2125,8 @@ export {
   isLifecycleHooks,
   isListField,
   isLitExpr,
+  isLocalActionDefinition,
+  isLocalActionStep,
   isMarkdownNode,
   isNamedSlotNode,
   isNavigateStep,
@@ -1933,9 +2134,11 @@ export {
   isNumberField,
   isObjectField,
   isParamExpr,
+  isPortalNode,
   isRefExpr,
   isRouteDefinition,
   isRouteExpr,
+  isSetPathStep,
   isSetStep,
   isSlotNode,
   isStateExpr,
@@ -1947,6 +2150,7 @@ export {
   isSubscribeStep,
   isTextNode,
   isUpdateStep,
+  isValidityExpr,
   isVarExpr,
   isViewNode,
   validateAst

package/package.json

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