@constela/core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -10,6 +10,12 @@ declare const UPDATE_OPERATIONS: readonly ["increment", "decrement", "push", "po
 type UpdateOperation = (typeof UPDATE_OPERATIONS)[number];
 declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "DELETE"];
 type HttpMethod = (typeof HTTP_METHODS)[number];
+declare const PARAM_TYPES: readonly ["string", "number", "boolean", "json"];
+type ParamType = (typeof PARAM_TYPES)[number];
+interface ParamDef {
+    type: ParamType;
+    required?: boolean;
+}
 /**
  * Literal expression - represents a constant value
  */
@@ -48,7 +54,15 @@ interface NotExpr {
     expr: 'not';
     operand: Expression;
 }
-type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr;
+/**
+ * Param expression - references a component parameter
+ */
+interface ParamExpr {
+    expr: 'param';
+    name: string;
+    path?: string;
+}
+type Expression = LitExpr | StateExpr | VarExpr | BinExpr | NotExpr | ParamExpr;
 /**
  * Number state field
  */
@@ -152,7 +166,26 @@ interface EachNode {
     key?: Expression;
     body: ViewNode;
 }
-type ViewNode = ElementNode | TextNode | IfNode | EachNode;
+/**
+ * Component node - invokes a defined component
+ */
+interface ComponentNode {
+    kind: 'component';
+    name: string;
+    props?: Record<string, Expression>;
+    children?: ViewNode[];
+}
+/**
+ * Slot node - placeholder for children in component definition
+ */
+interface SlotNode {
+    kind: 'slot';
+}
+type ViewNode = ElementNode | TextNode | IfNode | EachNode | ComponentNode | SlotNode;
+interface ComponentDef {
+    params?: Record<string, ParamDef>;
+    view: ViewNode;
+}
 /**
  * Program - the root of a Constela AST
  */
@@ -161,6 +194,7 @@ interface Program {
     state: Record<string, StateField>;
     actions: ActionDefinition[];
     view: ViewNode;
+    components?: Record<string, ComponentDef>;
 }
 type ConstelaAst = Program;
 
@@ -202,6 +236,10 @@ declare function isBinExpr(value: unknown): value is BinExpr;
  * Use the AST validator for full recursive validation instead.
  */
 declare function isNotExpr(value: unknown): value is NotExpr;
+/**
+ * Checks if value is a param expression
+ */
+declare function isParamExpr(value: unknown): value is ParamExpr;
 /**
  * Checks if value is any valid expression
  */
@@ -222,6 +260,14 @@ declare function isIfNode(value: unknown): value is IfNode;
  * Checks if value is an each node
  */
 declare function isEachNode(value: unknown): value is EachNode;
+/**
+ * Checks if value is a component node
+ */
+declare function isComponentNode(value: unknown): value is ComponentNode;
+/**
+ * Checks if value is a slot node
+ */
+declare function isSlotNode(value: unknown): value is SlotNode;
 /**
  * Checks if value is any valid view node
  */
@@ -269,7 +315,7 @@ declare function isEventHandler(value: unknown): value is EventHandler;
  * 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';
+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';
 /**
  * Custom error class for Constela validation errors
  */
@@ -314,6 +360,26 @@ declare function createUndefinedVarError(varName: string, path?: string): Conste
  * Creates an unsupported version error
  */
 declare function createUnsupportedVersionError(version: string): ConstelaError;
+/**
+ * Creates a component not found error
+ */
+declare function createComponentNotFoundError(name: string, path?: string): ConstelaError;
+/**
+ * Creates a missing required prop error
+ */
+declare function createComponentPropMissingError(componentName: string, propName: string, path?: string): ConstelaError;
+/**
+ * Creates a component cycle error
+ */
+declare function createComponentCycleError(cycle: string[], path?: string): ConstelaError;
+/**
+ * Creates a prop type mismatch error
+ */
+declare function createComponentPropTypeError(componentName: string, propName: string, expected: string, actual: string, path?: string): ConstelaError;
+/**
+ * Creates an undefined param reference error
+ */
+declare function createUndefinedParamError(paramName: string, path?: string): ConstelaError;
 
 /**
  * AST Validator for Constela
@@ -372,6 +438,12 @@ declare const astSchema: {
         readonly view: {
             readonly $ref: "#/$defs/ViewNode";
         };
+        readonly components: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly $ref: "#/$defs/ComponentDef";
+            };
+        };
     };
     readonly $defs: {
         readonly Expression: {
@@ -385,6 +457,8 @@ declare const astSchema: {
                 readonly $ref: "#/$defs/BinExpr";
             }, {
                 readonly $ref: "#/$defs/NotExpr";
+            }, {
+                readonly $ref: "#/$defs/ParamExpr";
             }];
         };
         readonly LitExpr: {
@@ -477,6 +551,23 @@ declare const astSchema: {
                 };
             };
         };
+        readonly ParamExpr: {
+            readonly type: "object";
+            readonly required: readonly ["expr", "name"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly expr: {
+                    readonly type: "string";
+                    readonly const: "param";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly path: {
+                    readonly type: "string";
+                };
+            };
+        };
         readonly StateField: {
             readonly oneOf: readonly [{
                 readonly $ref: "#/$defs/NumberField";
@@ -652,6 +743,10 @@ declare const astSchema: {
                 readonly $ref: "#/$defs/IfNode";
             }, {
                 readonly $ref: "#/$defs/EachNode";
+            }, {
+                readonly $ref: "#/$defs/ComponentNode";
+            }, {
+                readonly $ref: "#/$defs/SlotNode";
             }];
         };
         readonly ElementNode: {
@@ -744,7 +839,74 @@ declare const astSchema: {
                 };
             };
         };
+        readonly ComponentNode: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "name"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly const: "component";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly props: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly $ref: "#/$defs/Expression";
+                    };
+                };
+                readonly children: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/ViewNode";
+                    };
+                };
+            };
+        };
+        readonly SlotNode: {
+            readonly type: "object";
+            readonly required: readonly ["kind"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly type: "string";
+                    readonly const: "slot";
+                };
+            };
+        };
+        readonly ParamDef: {
+            readonly type: "object";
+            readonly required: readonly ["type"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["string", "number", "boolean", "json"];
+                };
+                readonly required: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly ComponentDef: {
+            readonly type: "object";
+            readonly required: readonly ["view"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly params: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly $ref: "#/$defs/ParamDef";
+                    };
+                };
+                readonly view: {
+                    readonly $ref: "#/$defs/ViewNode";
+                };
+            };
+        };
     };
 };
 
-export { type ActionDefinition, type ActionStep, BINARY_OPERATORS, type BinExpr, type BinaryOperator, type ConstelaAst, ConstelaError, type EachNode, type ElementNode, type ErrorCode, type EventHandler, type Expression, type FetchStep, HTTP_METHODS, type HttpMethod, type IfNode, type ListField, type LitExpr, type NotExpr, type NumberField, type Program, type SetStep, type StateExpr, type StateField, type StringField, type TextNode, UPDATE_OPERATIONS, type UpdateOperation, type UpdateStep, type ValidationFailure, type ValidationResult, type ValidationSuccess, type VarExpr, type ViewNode, astSchema, createDuplicateActionError, createSchemaError, createUndefinedActionError, createUndefinedStateError, createUndefinedVarError, createUnsupportedVersionError, isActionStep, isBinExpr, isConstelaError, isEachNode, isElementNode, isEventHandler, isExpression, isFetchStep, isIfNode, isListField, isLitExpr, isNotExpr, isNumberField, isSetStep, isStateExpr, isStateField, isStringField, isTextNode, isUpdateStep, isVarExpr, isViewNode, validateAst };
+export { type ActionDefinition, type ActionStep, BINARY_OPERATORS, type BinExpr, type BinaryOperator, type ComponentDef, type ComponentNode, type ConstelaAst, ConstelaError, type EachNode, type ElementNode, type ErrorCode, type EventHandler, type Expression, type FetchStep, HTTP_METHODS, type HttpMethod, type IfNode, type ListField, type LitExpr, type NotExpr, type NumberField, PARAM_TYPES, type ParamDef, type ParamExpr, type ParamType, type Program, type SetStep, type SlotNode, type StateExpr, type StateField, type StringField, type TextNode, UPDATE_OPERATIONS, type UpdateOperation, type UpdateStep, type ValidationFailure, type ValidationResult, type ValidationSuccess, type VarExpr, type ViewNode, astSchema, createComponentCycleError, createComponentNotFoundError, createComponentPropMissingError, createComponentPropTypeError, createDuplicateActionError, createSchemaError, createUndefinedActionError, createUndefinedParamError, createUndefinedStateError, createUndefinedVarError, createUnsupportedVersionError, isActionStep, isBinExpr, isComponentNode, isConstelaError, isEachNode, isElementNode, isEventHandler, isExpression, isFetchStep, isIfNode, isListField, isLitExpr, isNotExpr, isNumberField, isParamExpr, isSetStep, isSlotNode, isStateExpr, isStateField, isStringField, isTextNode, isUpdateStep, isVarExpr, isViewNode, validateAst };

package/dist/index.js

@@ -21,6 +21,7 @@ var UPDATE_OPERATIONS = [
   "remove"
 ];
 var HTTP_METHODS = ["GET", "POST", "PUT", "DELETE"];
+var PARAM_TYPES = ["string", "number", "boolean", "json"];
 
 // src/types/guards.ts
 function isObject(value) {
@@ -56,8 +57,17 @@ function isNotExpr(value) {
   if (!isObject(value["operand"])) return false;
   return true;
 }
+function isParamExpr(value) {
+  if (!isObject(value)) return false;
+  if (value["expr"] !== "param") return false;
+  if (typeof value["name"] !== "string") return false;
+  if ("path" in value && value["path"] !== void 0) {
+    if (typeof value["path"] !== "string") return false;
+  }
+  return true;
+}
 function isExpression(value) {
-  return isLitExpr(value) || isStateExpr(value) || isVarExpr(value) || isBinExpr(value) || isNotExpr(value);
+  return isLitExpr(value) || isStateExpr(value) || isVarExpr(value) || isBinExpr(value) || isNotExpr(value) || isParamExpr(value);
 }
 function isElementNode(value) {
   if (!isObject(value)) return false;
@@ -84,8 +94,24 @@ function isEachNode(value) {
   if (!isObject(value["body"])) return false;
   return true;
 }
+function isComponentNode(value) {
+  if (!isObject(value)) return false;
+  if (value["kind"] !== "component") return false;
+  if (typeof value["name"] !== "string") return false;
+  if ("props" in value && value["props"] !== void 0) {
+    if (!isObject(value["props"])) return false;
+  }
+  if ("children" in value && value["children"] !== void 0) {
+    if (!Array.isArray(value["children"])) return false;
+  }
+  return true;
+}
+function isSlotNode(value) {
+  if (!isObject(value)) return false;
+  return value["kind"] === "slot";
+}
 function isViewNode(value) {
-  return isElementNode(value) || isTextNode(value) || isIfNode(value) || isEachNode(value);
+  return isElementNode(value) || isTextNode(value) || isIfNode(value) || isEachNode(value) || isComponentNode(value) || isSlotNode(value);
 }
 function isSetStep(value) {
   if (!isObject(value)) return false;
@@ -205,6 +231,41 @@ function createUnsupportedVersionError(version) {
     "/version"
   );
 }
+function createComponentNotFoundError(name, path) {
+  return new ConstelaError(
+    "COMPONENT_NOT_FOUND",
+    `Component '${name}' is not defined in components`,
+    path
+  );
+}
+function createComponentPropMissingError(componentName, propName, path) {
+  return new ConstelaError(
+    "COMPONENT_PROP_MISSING",
+    `Component '${componentName}' requires prop '${propName}'`,
+    path
+  );
+}
+function createComponentCycleError(cycle, path) {
+  return new ConstelaError(
+    "COMPONENT_CYCLE",
+    `Circular component reference detected: ${cycle.join(" -> ")}`,
+    path
+  );
+}
+function createComponentPropTypeError(componentName, propName, expected, actual, path) {
+  return new ConstelaError(
+    "COMPONENT_PROP_TYPE",
+    `Component '${componentName}' prop '${propName}' expects ${expected}, got ${actual}`,
+    path
+  );
+}
+function createUndefinedParamError(paramName, path) {
+  return new ConstelaError(
+    "PARAM_UNDEFINED",
+    `Undefined param reference: '${paramName}' is not defined in component params`,
+    path
+  );
+}
 
 // src/schema/validator.ts
 import Ajv from "ajv";
@@ -237,6 +298,10 @@ var astSchema = {
     },
     view: {
       $ref: "#/$defs/ViewNode"
+    },
+    components: {
+      type: "object",
+      additionalProperties: { $ref: "#/$defs/ComponentDef" }
     }
   },
   $defs: {
@@ -247,7 +312,8 @@ var astSchema = {
         { $ref: "#/$defs/StateExpr" },
         { $ref: "#/$defs/VarExpr" },
         { $ref: "#/$defs/BinExpr" },
-        { $ref: "#/$defs/NotExpr" }
+        { $ref: "#/$defs/NotExpr" },
+        { $ref: "#/$defs/ParamExpr" }
       ]
     },
     LitExpr: {
@@ -309,6 +375,16 @@ var astSchema = {
         operand: { $ref: "#/$defs/Expression" }
       }
     },
+    ParamExpr: {
+      type: "object",
+      required: ["expr", "name"],
+      additionalProperties: false,
+      properties: {
+        expr: { type: "string", const: "param" },
+        name: { type: "string" },
+        path: { type: "string" }
+      }
+    },
     // ==================== State Fields ====================
     StateField: {
       oneOf: [
@@ -429,7 +505,9 @@ var astSchema = {
         { $ref: "#/$defs/ElementNode" },
         { $ref: "#/$defs/TextNode" },
         { $ref: "#/$defs/IfNode" },
-        { $ref: "#/$defs/EachNode" }
+        { $ref: "#/$defs/EachNode" },
+        { $ref: "#/$defs/ComponentNode" },
+        { $ref: "#/$defs/SlotNode" }
       ]
     },
     ElementNode: {
@@ -486,6 +564,56 @@ var astSchema = {
         key: { $ref: "#/$defs/Expression" },
         body: { $ref: "#/$defs/ViewNode" }
       }
+    },
+    ComponentNode: {
+      type: "object",
+      required: ["kind", "name"],
+      additionalProperties: false,
+      properties: {
+        kind: { type: "string", const: "component" },
+        name: { type: "string" },
+        props: {
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/Expression" }
+        },
+        children: {
+          type: "array",
+          items: { $ref: "#/$defs/ViewNode" }
+        }
+      }
+    },
+    SlotNode: {
+      type: "object",
+      required: ["kind"],
+      additionalProperties: false,
+      properties: {
+        kind: { type: "string", const: "slot" }
+      }
+    },
+    // ==================== Component Definition ====================
+    ParamDef: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: false,
+      properties: {
+        type: {
+          type: "string",
+          enum: ["string", "number", "boolean", "json"]
+        },
+        required: { type: "boolean" }
+      }
+    },
+    ComponentDef: {
+      type: "object",
+      required: ["view"],
+      additionalProperties: false,
+      properties: {
+        params: {
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/ParamDef" }
+        },
+        view: { $ref: "#/$defs/ViewNode" }
+      }
     }
   }
 };
@@ -500,8 +628,9 @@ var validate = ajv.compile(astSchema);
 function isObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-var VALID_VIEW_KINDS = ["element", "text", "if", "each"];
-var VALID_EXPR_TYPES = ["lit", "state", "var", "bin", "not"];
+var VALID_VIEW_KINDS = ["element", "text", "if", "each", "component", "slot"];
+var VALID_EXPR_TYPES = ["lit", "state", "var", "bin", "not", "param"];
+var VALID_PARAM_TYPES = ["string", "number", "boolean", "json"];
 var VALID_ACTION_TYPES = ["set", "update", "fetch"];
 var VALID_STATE_TYPES = ["number", "string", "list"];
 var VALID_BIN_OPS = BINARY_OPERATORS;
@@ -516,7 +645,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" };
+    return { path: path + "/kind", message: "must be one of: element, text, if, each, component, slot" };
   }
   switch (kind) {
     case "element":
@@ -579,6 +708,25 @@ function validateViewNode(node, path) {
         if (bodyError) return bodyError;
       }
       break;
+    case "component":
+      if (typeof node["name"] !== "string") {
+        return { path: path + "/name", message: "name is required" };
+      }
+      if (node["props"] !== void 0 && isObject2(node["props"])) {
+        for (const [propName, propValue] of Object.entries(node["props"])) {
+          const error = validateExpression(propValue, path + "/props/" + propName);
+          if (error) return error;
+        }
+      }
+      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;
+    case "slot":
+      break;
   }
   return null;
 }
@@ -591,7 +739,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" };
+    return { path: path + "/expr", message: "must be one of: lit, state, var, bin, not, param" };
   }
   switch (exprType) {
     case "lit":
@@ -630,6 +778,14 @@ function validateExpression(expr, path) {
         return { path: path + "/operand", message: "operand is required" };
       }
       return validateExpression(expr["operand"], path + "/operand");
+    case "param":
+      if (typeof expr["name"] !== "string") {
+        return { path: path + "/name", message: "name is required" };
+      }
+      if ("path" in expr && typeof expr["path"] !== "string") {
+        return { path: path + "/path", message: "path must be a string" };
+      }
+      break;
   }
   return null;
 }
@@ -721,6 +877,39 @@ function validateStateField(field, path) {
   }
   return null;
 }
+function validateParamDef(param, path) {
+  if (!isObject2(param)) {
+    return { path, message: "must be an object" };
+  }
+  const paramType = param["type"];
+  if (typeof paramType !== "string") {
+    return { path: path + "/type", message: "type is required" };
+  }
+  if (!VALID_PARAM_TYPES.includes(paramType)) {
+    return { path: path + "/type", message: "must be one of: string, number, boolean, json" };
+  }
+  if ("required" in param && typeof param["required"] !== "boolean") {
+    return { path: path + "/required", message: "required must be a boolean" };
+  }
+  return null;
+}
+function validateComponentDef(def, path) {
+  if (!isObject2(def)) {
+    return { path, message: "must be an object" };
+  }
+  if (!("view" in def)) {
+    return { path: path + "/view", message: "view is required" };
+  }
+  if ("params" in def && isObject2(def["params"])) {
+    for (const [paramName, paramDef] of Object.entries(def["params"])) {
+      const error = validateParamDef(paramDef, path + "/params/" + paramName);
+      if (error) return error;
+    }
+  }
+  const viewError = validateViewNode(def["view"], path + "/view");
+  if (viewError) return viewError;
+  return null;
+}
 function customValidateAst(input) {
   if (isObject2(input["state"])) {
     for (const [name, field] of Object.entries(input["state"])) {
@@ -743,6 +932,12 @@ function customValidateAst(input) {
     const error = validateViewNode(input["view"], "/view");
     if (error) return error;
   }
+  if ("components" in input && isObject2(input["components"])) {
+    for (const [name, def] of Object.entries(input["components"])) {
+      const error = validateComponentDef(def, "/components/" + name);
+      if (error) return error;
+    }
+  }
   return null;
 }
 function findTopLevelRequiredError(errors) {
@@ -943,16 +1138,23 @@ export {
   BINARY_OPERATORS,
   ConstelaError,
   HTTP_METHODS,
+  PARAM_TYPES,
   UPDATE_OPERATIONS,
   astSchema,
+  createComponentCycleError,
+  createComponentNotFoundError,
+  createComponentPropMissingError,
+  createComponentPropTypeError,
   createDuplicateActionError,
   createSchemaError,
   createUndefinedActionError,
+  createUndefinedParamError,
   createUndefinedStateError,
   createUndefinedVarError,
   createUnsupportedVersionError,
   isActionStep,
   isBinExpr,
+  isComponentNode,
   isConstelaError,
   isEachNode,
   isElementNode,
@@ -964,7 +1166,9 @@ export {
   isLitExpr,
   isNotExpr,
   isNumberField,
+  isParamExpr,
   isSetStep,
+  isSlotNode,
   isStateExpr,
   isStateField,
   isStringField,

package/package.json

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