@kubuild/core 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,122 @@
+# @kubuild/core
+
+[![npm version](https://img.shields.io/npm/v/@kubuild/core.svg)](https://www.npmjs.com/package/@kubuild/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+
+Framework-agnostic engine for **KUBUILD**: document tree utilities, command engine, history stack (undo/redo), Action Pipeline Executor, Runtime State Store, Validation Engine, template interpolation, migration, and export/import.
+
+Core contains **zero UI/DOM dependencies** and runs seamlessly in Node.js, Cloudflare Workers, Electron, and the browser.
+
+---
+
+## 📦 Installation
+
+```bash
+# Using pnpm (recommended)
+pnpm add @kubuild/core @kubuild/schema
+
+# Using npm
+npm install @kubuild/core @kubuild/schema
+
+# Using yarn
+yarn add @kubuild/core @kubuild/schema
+```
+
+---
+
+## ✨ Features
+
+- **Document Tree Manipulation**: Safe operations for finding, inserting, moving, cloning, and removing nodes (`findNodeById`, `insertNode`, `removeNode`, `moveNode`).
+- **Command Engine & History**: Transactional command pattern with an undo/redo stack (`CommandEngine`, `InsertNodeCommand`, `UpdateNodePropsCommand`, `UpdateNodeStylesCommand`).
+- **Action Pipeline Executor**: Comprehensive runner for executing multi-step action flows (`ActionPipelineExecutor`), evaluating success/error branches and conditional expressions.
+- **Runtime State Store**: Lightweight reactive store (`RuntimeStateStore`) for managing form values, execution logs, response data, and runtime variables.
+- **Validation Engine**: Built-in validators for form fields and models (required, email, regex, min/max length, custom rules).
+- **Template Interpolation**: Powerful variable interpolation supporting syntax like `{{form.name}}`, `{{user.id}}`, or `{{response.data}}`.
+- **Portable Export & Import**: Pack page documents and assets into portable `.stora` archives (compressed zip via `fflate`) and unpack them back into memory.
+- **Security Defense**: Strict XSS prevention, safe URL sanitization, and style value validation.
+
+---
+
+## 🚀 Quick Usage
+
+### Command Engine & Undo/Redo
+
+```typescript
+import { CommandEngine, InsertNodeCommand } from '@kubuild/core';
+import type { PageDocument, Node } from '@kubuild/schema';
+
+const engine = new CommandEngine(initialPageDocument);
+
+// Execute a command to insert a new node
+const buttonNode: Node = {
+  id: 'btn-1',
+  type: 'button',
+  props: { label: 'Click Me' },
+  styles: { backgroundColor: '#3b82f6', color: '#ffffff' }
+};
+
+engine.execute(new InsertNodeCommand(engine.getDocument(), 'root-1', buttonNode));
+
+// Undo the insertion
+engine.undo();
+
+// Redo the insertion
+engine.redo();
+
+const currentDoc: PageDocument = engine.getDocument();
+```
+
+### Action Pipeline Execution & Interpolation
+
+```typescript
+import {
+  ActionPipelineExecutor,
+  RuntimeStateStore,
+  interpolateTemplate
+} from '@kubuild/core';
+import type { ActionPipeline } from '@kubuild/schema';
+
+// 1. Initialize State Store
+const stateStore = new RuntimeStateStore({
+  form: { email: 'user@example.com', name: 'Alex' },
+  user: { role: 'admin' }
+});
+
+// 2. Interpolate template string
+const greeting = interpolateTemplate('Hello {{form.name}}! Role: {{user.role}}', stateStore.getState());
+console.log(greeting); // "Hello Alex! Role: admin"
+
+// 3. Execute Pipeline
+const executor = new ActionPipelineExecutor({
+  stateStore,
+  runners: {
+    async apiRequest(step, context) {
+      const response = await fetch(step.config.url, { method: step.config.method });
+      return await response.json();
+    }
+  }
+});
+
+const result = await executor.execute(pipelineDefinition);
+```
+
+### Exporting & Importing `.stora` Files
+
+```typescript
+import { exportStoraArchive, importStoraArchive } from '@kubuild/core';
+
+// Export document to binary .stora buffer (zip)
+const storaBuffer: Uint8Array = await exportStoraArchive(pageDocument, {
+  includeAssets: true
+});
+
+// Import .stora buffer back into validated PageDocument
+const importedDocument = await importStoraArchive(storaBuffer);
+```
+
+---
+
+## 📄 License
+
+MIT © [KUBUILD](https://github.com/kustora/kubuild)

package/dist/commands.d.ts

@@ -1,5 +1,5 @@
-import { PageDocument, Node, ResponsiveStyles, StyleDefinition, AnimationConfig } from '@kubuild/schema';
-export type DocumentChangeType = 'NODE_INSERTED' | 'NODE_MOVED' | 'PROPS_UPDATED' | 'STYLE_UPDATED' | 'ANIMATION_UPDATED' | 'NODE_REMOVED' | 'NODE_DUPLICATED';
+import { PageDocument, Node, ResponsiveStyles, StyleDefinition, AnimationConfig, ActionPipeline, FormConfig } from '@kubuild/schema';
+export type DocumentChangeType = 'NODE_INSERTED' | 'NODE_MOVED' | 'PROPS_UPDATED' | 'STYLE_UPDATED' | 'ANIMATION_UPDATED' | 'ACTIONS_UPDATED' | 'FORM_CONFIG_UPDATED' | 'NODE_REMOVED' | 'NODE_DUPLICATED';
 export interface DocumentChangeEvent {
     type: DocumentChangeType;
     timestamp: string;
@@ -111,4 +111,28 @@ export interface UpdateAnimationParams {
  * Returns a new PageDocument and an ANIMATION_UPDATED event.
  */
 export declare function updateAnimation(document: PageDocument, params: UpdateAnimationParams): CommandResult;
+export interface UpdateActionsParams {
+    nodeId: string;
+    actions: ActionPipeline[] | null;
+}
+/**
+ * 8. Update the action pipelines of an existing node.
+ * Returns a new PageDocument and an ACTIONS_UPDATED event.
+ */
+export declare function updateActions(document: PageDocument, params: UpdateActionsParams): CommandResult;
+export interface UpdateFormConfigParams {
+    nodeId: string;
+    formConfig: Partial<FormConfig> | null;
+    /**
+     * If true (default), shallow merges new formConfig properties with existing config.
+     * If false, replaces the formConfig with the provided object.
+     * If formConfig is null, removes the form configuration from the node.
+     */
+    merge?: boolean;
+}
+/**
+ * 9. Update the form configuration of an existing node.
+ * Returns a new PageDocument and a FORM_CONFIG_UPDATED event.
+ */
+export declare function updateFormConfig(document: PageDocument, params: UpdateFormConfigParams): CommandResult;
 //# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}

package/dist/conditional-resolver.d.ts

@@ -0,0 +1,45 @@
+import type { ActionStepCondition, ConditionOperator } from '@kubuild/schema';
+/**
+ * Extended condition operators supported by the evaluator.
+ */
+export type ExtendedConditionOperator = ConditionOperator | 'starts_with' | 'ends_with' | 'is_empty' | 'is_not_empty' | 'in' | 'not_in';
+/**
+ * Options for fine-tuning condition evaluation.
+ */
+export interface ConditionEvaluationOptions {
+    caseInsensitive?: boolean;
+    trimStrings?: boolean;
+}
+/**
+ * Represents a group of conditions evaluated together using AND / OR combinators.
+ */
+export interface ConditionGroup {
+    combinator: 'and' | 'or';
+    conditions: (ActionStepCondition | ConditionGroup)[];
+}
+/**
+ * Type guard to check if a condition item is a ConditionGroup.
+ */
+export declare function isConditionGroup(item: ActionStepCondition | ConditionGroup): item is ConditionGroup;
+/**
+ * Checks whether a given value is considered empty.
+ * Returns true for undefined, null, empty string, empty array, or empty object.
+ */
+export declare function isValueEmpty(value: unknown): boolean;
+/**
+ * Evaluates an operator against an actual value and an optional expected value.
+ */
+export declare function evaluateOperator(operator: ExtendedConditionOperator | string, actual: unknown, expected?: unknown, options?: ConditionEvaluationOptions): boolean;
+/**
+ * Resolves a field value from context and evaluates a single ActionStepCondition.
+ */
+export declare function evaluateCondition(condition: ActionStepCondition | undefined, context: Record<string, unknown>, options?: ConditionEvaluationOptions): boolean;
+/**
+ * Evaluates a ConditionGroup (AND / OR group with nested conditions).
+ */
+export declare function evaluateConditionGroup(group: ConditionGroup, context: Record<string, unknown>, options?: ConditionEvaluationOptions): boolean;
+/**
+ * Evaluates a list of conditions and/or condition groups using a given combinator ('and' | 'or').
+ */
+export declare function evaluateConditions(conditions: (ActionStepCondition | ConditionGroup)[], context: Record<string, unknown>, combinator?: 'and' | 'or', options?: ConditionEvaluationOptions): boolean;
+//# sourceMappingURL=conditional-resolver.d.ts.map

package/dist/conditional-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditional-resolver.d.ts","sourceRoot":"","sources":["../src/conditional-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAG9E;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,aAAa,GACb,WAAW,GACX,UAAU,GACV,cAAc,GACd,IAAI,GACJ,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,CAAC,mBAAmB,GAAG,cAAc,CAAC,EAAE,CAAC;CACtD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,mBAAmB,GAAG,cAAc,GACzC,IAAI,IAAI,cAAc,CAExB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,yBAAyB,GAAG,MAAM,EAC5C,MAAM,EAAE,OAAO,EACf,QAAQ,CAAC,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CA+IT;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,mBAAmB,GAAG,SAAS,EAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAWT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAsBT;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,CAAC,mBAAmB,GAAG,cAAc,CAAC,EAAE,EACpD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,UAAU,GAAE,KAAK,GAAG,IAAY,EAChC,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAET"}