@constela/core 0.11.0 → 0.12.1

package/README.md

@@ -40,9 +40,27 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 }
 ```
 
+### Cookie Expression for Initial Value
+
+String state can use a cookie expression to read initial value from cookies (SSR/SSG-safe):
+
+```json
+{
+  "theme": {
+    "type": "string",
+    "initial": { "expr": "cookie", "key": "theme", "default": "dark" }
+  }
+}
+```
+
+- `key`: Cookie name to read
+- `default`: Fallback value when cookie is not set
+- Works in both SSR and client-side rendering
+- Useful for theme persistence, user preferences, etc.
+
 ## Expression Types
 
-14 expression types for constrained computation:
+15 expression types for constrained computation:
 
 | Type | JSON Example | Description |
 |------|-------------|-------------|
@@ -60,6 +78,7 @@ All fields except `version`, `state`, `actions`, and `view` are optional.
 | `ref` | `{ "expr": "ref", "name": "inputEl" }` | DOM element ref |
 | `style` | `{ "expr": "style", "name": "button", "variants": {...} }` | Style reference |
 | `concat` | `{ "expr": "concat", "items": [...] }` | String concatenation |
+| `cookie` | `{ "expr": "cookie", "key": "theme", "default": "dark" }` | Cookie value (SSR-safe) |
 
 **Binary Operators:** `+`, `-`, `*`, `/`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`
 

package/dist/index.d.ts

@@ -155,6 +155,14 @@ interface ValidityExpr {
     property?: ValidityProperty;
 }
 type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr | CondExpr | GetExpr | RouteExpr | ImportExpr | DataExpr | RefExpr | IndexExpr | StyleExpr | ConcatExpr | ValidityExpr;
+/**
+ * Cookie expression for state initial value
+ */
+interface CookieInitialExpr {
+    expr: 'cookie';
+    key: string;
+    default: string;
+}
 /**
  * Number state field
  */
@@ -167,7 +175,7 @@ interface NumberField {
  */
 interface StringField {
     type: 'string';
-    initial: string;
+    initial: string | CookieInitialExpr;
 }
 /**
  * List state field
@@ -824,6 +832,10 @@ declare function isLocalActionDefinition(value: unknown): value is LocalActionDe
  * Checks if value is a number field
  */
 declare function isNumberField(value: unknown): value is NumberField;
+/**
+ * Checks if value is a cookie initial expression
+ */
+declare function isCookieInitialExpr(value: unknown): value is CookieInitialExpr;
 /**
  * Checks if value is a string field
  */
@@ -1473,6 +1485,27 @@ declare const astSchema: {
                     readonly const: "string";
                 };
                 readonly initial: {
+                    readonly oneOf: readonly [{
+                        readonly type: "string";
+                    }, {
+                        readonly $ref: "#/$defs/CookieInitialExpr";
+                    }];
+                };
+            };
+        };
+        readonly CookieInitialExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "key", "default"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "cookie";
+                };
+                readonly key: {
+                    readonly type: "string";
+                };
+                readonly default: {
                     readonly type: "string";
                 };
             };
@@ -1991,4 +2024,4 @@ declare const astSchema: {
     };
 };
 
-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 };
+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, type CookieInitialExpr, 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, isCookieInitialExpr, 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

@@ -409,10 +409,13 @@ function isNumberField(value) {
   if (value["type"] !== "number") return false;
   return typeof value["initial"] === "number";
 }
+function isCookieInitialExpr(value) {
+  return typeof value === "object" && value !== null && "expr" in value && value.expr === "cookie" && "key" in value && typeof value.key === "string" && "default" in value && typeof value.default === "string";
+}
 function isStringField(value) {
   if (!isObject(value)) return false;
   if (value["type"] !== "string") return false;
-  return typeof value["initial"] === "string";
+  return typeof value["initial"] === "string" || isCookieInitialExpr(value["initial"]);
 }
 function isListField(value) {
   if (!isObject(value)) return false;
@@ -836,10 +839,10 @@ function findSimilarNames(target, candidates, maxDistance = 2) {
 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", "style"];
+var VALID_VIEW_KINDS = ["element", "text", "if", "each", "component", "slot", "markdown", "code", "portal"];
+var VALID_EXPR_TYPES = ["lit", "state", "var", "bin", "not", "param", "cond", "get", "style", "validity", "index"];
 var VALID_PARAM_TYPES = ["string", "number", "boolean", "json"];
-var VALID_ACTION_TYPES = ["set", "update", "fetch"];
+var VALID_ACTION_TYPES = ["set", "update", "fetch", "delay", "interval", "clearTimer", "focus"];
 var VALID_STATE_TYPES = ["number", "string", "list", "boolean", "object"];
 var VALID_BIN_OPS = BINARY_OPERATORS;
 var VALID_UPDATE_OPS = UPDATE_OPERATIONS;
@@ -853,7 +856,7 @@ function validateViewNode(node, path) {
     return { path: path + "/kind", message: "kind is required" };
   }
   if (!VALID_VIEW_KINDS.includes(kind)) {
-    return { path: path + "/kind", message: "must be one of: element, text, if, each, component, slot, markdown, code" };
+    return { path: path + "/kind", message: "must be one of: element, text, if, each, component, slot, markdown, code, portal" };
   }
   switch (kind) {
     case "element":
@@ -952,6 +955,17 @@ function validateViewNode(node, path) {
         if (langError) return langError;
         return validateExpression(node["content"], path + "/content");
       }
+    case "portal":
+      if (typeof node["target"] !== "string") {
+        return { path: path + "/target", message: "target is required" };
+      }
+      if (Array.isArray(node["children"])) {
+        for (let i = 0; i < node["children"].length; i++) {
+          const error = validateViewNode(node["children"][i], path + "/children/" + i);
+          if (error) return error;
+        }
+      }
+      break;
   }
   return null;
 }
@@ -964,7 +978,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, style" };
+    return { path: path + "/expr", message: "must be one of: lit, state, var, bin, not, param, cond, get, style, validity, index" };
   }
   switch (exprType) {
     case "lit":
@@ -1052,6 +1066,25 @@ function validateExpression(expr, path) {
         }
       }
       break;
+    case "validity":
+      if (typeof expr["ref"] !== "string") {
+        return { path: path + "/ref", message: "ref is required" };
+      }
+      break;
+    case "index":
+      if (!("base" in expr)) {
+        return { path: path + "/base", message: "base is required" };
+      }
+      if (!("key" in expr)) {
+        return { path: path + "/key", message: "key is required" };
+      }
+      {
+        const baseError = validateExpression(expr["base"], path + "/base");
+        if (baseError) return baseError;
+        const keyError = validateExpression(expr["key"], path + "/key");
+        if (keyError) return keyError;
+      }
+      break;
   }
   return null;
 }
@@ -1064,7 +1097,7 @@ function validateActionStep(step, path) {
     return { path: path + "/do", message: "do is required" };
   }
   if (!VALID_ACTION_TYPES.includes(doType)) {
-    return { path: path + "/do", message: "must be one of: set, update, fetch" };
+    return { path: path + "/do", message: "must be one of: set, update, fetch, delay, interval, clearTimer, focus" };
   }
   switch (doType) {
     case "set":
@@ -1107,6 +1140,50 @@ function validateActionStep(step, path) {
         if (bodyError) return bodyError;
       }
       break;
+    case "delay":
+      if (!("ms" in step)) {
+        return { path: path + "/ms", message: "ms is required" };
+      }
+      if (!("then" in step)) {
+        return { path: path + "/then", message: "then is required" };
+      }
+      {
+        const msError = validateExpression(step["ms"], path + "/ms");
+        if (msError) return msError;
+        if (!Array.isArray(step["then"])) {
+          return { path: path + "/then", message: "then must be an array" };
+        }
+        for (let i = 0; i < step["then"].length; i++) {
+          const thenError = validateActionStep(step["then"][i], path + "/then/" + i);
+          if (thenError) return thenError;
+        }
+      }
+      break;
+    case "interval":
+      if (!("ms" in step)) {
+        return { path: path + "/ms", message: "ms is required" };
+      }
+      if (typeof step["action"] !== "string") {
+        return { path: path + "/action", message: "action is required" };
+      }
+      {
+        const msError = validateExpression(step["ms"], path + "/ms");
+        if (msError) return msError;
+      }
+      break;
+    case "clearTimer":
+      if (!("target" in step)) {
+        return { path: path + "/target", message: "target is required" };
+      }
+      return validateExpression(step["target"], path + "/target");
+    case "focus":
+      if (!("target" in step)) {
+        return { path: path + "/target", message: "target is required" };
+      }
+      if (typeof step["operation"] !== "string") {
+        return { path: path + "/operation", message: "operation is required" };
+      }
+      return validateExpression(step["target"], path + "/target");
   }
   return null;
 }
@@ -1707,7 +1784,22 @@ var astSchema = {
       additionalProperties: false,
       properties: {
         type: { type: "string", const: "string" },
-        initial: { type: "string" }
+        initial: {
+          oneOf: [
+            { type: "string" },
+            { $ref: "#/$defs/CookieInitialExpr" }
+          ]
+        }
+      }
+    },
+    CookieInitialExpr: {
+      type: "object",
+      required: ["expr", "key", "default"],
+      additionalProperties: false,
+      properties: {
+        expr: { type: "string", const: "cookie" },
+        key: { type: "string" },
+        default: { type: "string" }
       }
     },
     ListField: {
@@ -2108,6 +2200,7 @@ export {
   isConcatExpr,
   isCondExpr,
   isConstelaError,
+  isCookieInitialExpr,
   isDataExpr,
   isDataSource,
   isDisposeStep,

package/package.json

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