@form-flow/core 1.0.0

package/README.md

@@ -0,0 +1,281 @@
+# @form-flow/core
+
+![npm](https://img.shields.io/npm/v/@form-flow/core) ![license](https://img.shields.io/npm/l/@form-flow/core) ![build](https://img.shields.io/github/actions/workflow/status/YOUR_USERNAME/form-flow-core/ci.yml)
+
+> **Framework-agnostic TypeScript engine for conditional form field behavior**  
+> Define when fields should be visible, required, disabled, or readonly based on other field values—no framework lock-in.
+
+---
+
+## ✨ Features
+
+- 🎯 **Conditional rendering logic** – Show/hide fields based on form state
+- ✅ **Dynamic validation** – Make fields required/optional conditionally
+- 🔒 **Smart field states** – Disable or set readonly based on rules
+- 🧩 **Framework agnostic** – Works with React, Vue, Angular, Svelte, or vanilla JS
+- 🗄️ **Easy w/r configuration** - Save and load field definitions from database or datasets
+- 🪶 **Zero dependencies** – Lightweight and tree-shakeable
+- 📘 **Full TypeScript support** – Type-safe rule definitions
+- 🧪 **Battle-tested** – Comprehensive test coverage with Jest
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install @form-flow/core
+# or
+yarn add @form-flow/core
+# or
+pnpm add @form-flow/core
+```
+
+---
+
+## 📖 Quick Start
+
+### Basic Example
+
+```ts
+import { FieldDefinition, RuleEvaluator } from "@form-flow/core";
+
+// Define your fields
+const ageField: FieldDefinition = {
+  id: "age",
+  type: "number",
+  label: "Your Age"
+};
+
+const consentField: FieldDefinition = {
+  id: "parentalConsent",
+  type: "checkbox",
+  label: "Parental Consent Required",
+  
+  // Show this field only when age < 18
+  visibleIf: {
+    groupId: "visibility-group",
+    operator: "and",
+    ruleType: "visibleIf",
+    rules: [
+      { ruleId: "1", conditionFieldId: "age", operator: "lt", value: 18 }
+    ]
+  },
+  
+  // Make it required when visible
+  requiredIf: {
+    groupId: "required-group",
+    operator: "and",
+    ruleType: "requiredIf",
+    rules: [
+      { ruleId: "2", conditionFieldId: "age", operator: "lt", value: 18 }
+    ]
+  }
+};
+
+// Evaluate rules against current form data
+const formData = { age: 16 };
+const fieldStates = RuleEvaluator.evaluateFields(
+  [ageField, consentField],
+  formData
+);
+
+console.log(fieldStates.parentalConsent.visible);   // true
+console.log(fieldStates.parentalConsent.required);  // true
+
+const formData2 = { age: 21 };
+const fieldStates2 = RuleEvaluator.evaluateFields(
+  [ageField, consentField],
+  formData2
+);
+
+console.log(fieldStates2.parentalConsent.visible);   // false
+console.log(fieldStates2.parentalConsent.required);  // false
+```
+
+### Advanced: Complex Rules
+
+```ts
+const emailField: FieldDefinition = {
+  id: "workEmail",
+  type: "email",
+  label: "Work Email",
+  
+  // Show if (employed AND age >= 18) OR freelancer
+  visibleIf: {
+    groupId: "email-visibility",
+    operator: "or",
+    ruleType: "visibleIf",
+    rules: [
+      {
+        groupId: "employed-adult",
+        operator: "and",
+        ruleType: "visibleIf",
+        rules: [
+          { ruleId: "1", conditionFieldId: "employmentStatus", operator: "eq", value: "employed" },
+          { ruleId: "2", conditionFieldId: "age", operator: "gte", value: 18 }
+        ]
+      },
+      { ruleId: "3", conditionFieldId: "employmentStatus", operator: "eq", value: "freelancer" }
+    ]
+  },
+  
+  // Readonly if verified
+  readonlyIf: {
+    groupId: "verified-check",
+    operator: "and",
+    ruleType: "readonlyIf",
+    rules: [
+      { ruleId: "4", conditionFieldId: "emailVerified", operator: "eq", value: true }
+    ]
+  }
+};
+```
+
+---
+
+## 🛠️ API Reference
+
+### `RuleEvaluator.evaluateFields()`
+
+Evaluates all conditional rules for your form fields.
+
+```ts
+const state: FormControlState = RuleEvaluator.evaluateFields(
+  fields: FieldDefinition[],
+  formData: Record<string, any>
+);
+```
+
+**Returns:** `FormControlState` – Map of field IDs to their computed states
+
+```ts
+{
+  [fieldId: string]: {
+    visible: boolean;
+    required: boolean;
+    disabled: boolean;
+    readonly: boolean;
+  }
+}
+```
+
+### `FieldHelper.getAvailableRuleTypes()`
+
+Get which rule types can still be added to a field.
+
+```ts
+import { FieldHelper } from "@form-flow/core";
+
+const availableRules = FieldHelper.getAvailableRuleTypes(consentField);
+console.log(availableRules); // ["disabledIf", "readonlyIf"]
+```
+
+---
+
+## 📚 Core Concepts
+
+### Rule Types
+
+| Rule Type | Purpose | Example |
+|-----------|---------|---------|
+| `visibleIf` | Control field visibility | Show "Company Name" if employment is "employed" |
+| `requiredIf` | Make field conditionally required | Require "Tax ID" if revenue > 50000 |
+| `disabledIf` | Disable field interaction | Disable "Submit" until terms are accepted |
+| `readonlyIf` | Make field read-only | Lock "Email" after verification |
+
+### Operators
+
+- **Comparison:** `eq`, `neq`, `lt`, `lte`, `gt`, `gte`
+- **String:** `contains`, `startsWith`, `endsWith`
+- **Logical:** `and`, `or` (for grouping rules)
+
+### Type Definitions
+
+```ts
+// Field with conditional rules
+type FieldDefinition<T = any> = {
+  id: string;
+  type: string;
+  label: string;
+  visibleIf?: FieldRuleGroupDefinition;
+  requiredIf?: FieldRuleGroupDefinition;
+  disabledIf?: FieldRuleGroupDefinition;
+  readonlyIf?: FieldRuleGroupDefinition;
+};
+
+// Atomic rule
+type FieldRuleDefinition = {
+  ruleId: string;
+  conditionFieldId: string;
+  operator: "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith";
+  value: any;
+};
+
+// Rule group (supports nesting)
+type FieldRuleGroupDefinition = {
+  groupId: string;
+  operator: "and" | "or";
+  ruleType: ConditionalFieldProperty;
+  rules: Array<FieldRuleDefinition | FieldRuleGroupDefinition>;
+};
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+npm run test
+# or
+yarn test
+```
+
+Tests are written with **Jest** and cover both `RuleEvaluator` and `FieldHelper` with comprehensive test coverage.
+
+---
+
+## 🗺️💡 Roadmap & Ideas
+
+- [ ] **Visual Rule Builder** – Drag-and-drop UI for creating rules (React version in development)
+- [ ] **Rule Templates** – Pre-built common patterns (age verification, address forms, etc.)
+- [ ] **Async Rules** – Support for API-based conditions
+- [ ] **Rule Debugging** – Dev tools for visualizing rule evaluation
+- [ ] **Performance Optimizations** – Memoization and selective re-evaluation
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please check out the [Contributing Guide](CONTRIBUTING.md).
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT © [Andrea Moretti]
+
+---
+
+## ☕ Support
+
+If this library saves you time, consider supporting its development:
+
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buy-me-a-coffee)](https://buymeacoffee.com/YOUR_USERNAME)
+
+---
+
+## 🔗 Links
+
+- [📦 npm Package](https://www.npmjs.com/package/@form-flow/core)
+- [🐛 Report Issues](https://github.com/YOUR_USERNAME/form-flow-core/issues)
+- [💬 Discussions](https://github.com/YOUR_USERNAME/form-flow-core/discussions)
+
+---
+
+**Made with ❤️ by the open-source community**

package/dist/dependency-graph.d.ts

@@ -0,0 +1,14 @@
+import { FieldDefinition } from './models/field-definition';
+export declare class DependencyGraph {
+    private dependentsMap;
+    constructor(fields: FieldDefinition[]);
+    /**
+     * Estrae le dipendenze ricorsivamente da una regola, che può essere un FieldRuleDefinition o un FieldRuleGroupDefinition.
+     */
+    private extractDependencies;
+    /**
+     * Restituisce tutti i campi che dipendono da un campo specifico.
+     */
+    getDependentFields(fieldId: string): Set<string>;
+}
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/dependency-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAI5D,qBAAa,eAAe;IACxB,OAAO,CAAC,aAAa,CAAuC;gBAEhD,MAAM,EAAE,eAAe,EAAE;IAwBrC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;CAiBnD"}

package/dist/dependency-graph.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyGraph = void 0;
+const rule_helper_1 = require("./utility/rule-helper");
+class DependencyGraph {
+    constructor(fields) {
+        this.dependentsMap = new Map();
+        fields.forEach(field => {
+            const dependencies = new Set();
+            // Estrazione delle dipendenze dalle regole
+            const fieldRules = ['visibleIf', 'requiredIf', 'disabledIf', 'readonlyIf'];
+            fieldRules.forEach(ruleName => {
+                const rule = field[ruleName];
+                if (rule) {
+                    this.extractDependencies(rule, dependencies);
+                }
+            });
+            // Registriamo le dipendenze
+            dependencies.forEach(dep => {
+                if (!this.dependentsMap.has(dep)) {
+                    this.dependentsMap.set(dep, new Set());
+                }
+                this.dependentsMap.get(dep).add(field.id);
+            });
+        });
+    }
+    /**
+     * Estrae le dipendenze ricorsivamente da una regola, che può essere un FieldRuleDefinition o un FieldRuleGroupDefinition.
+     */
+    extractDependencies(rule, dependencies) {
+        if ('conditionFieldId' in rule) {
+            // Se è una FieldRuleDefinition, aggiungi il conditionFieldId
+            dependencies.add(rule.conditionFieldId);
+        }
+        if ('rules' in rule) {
+            // Se è un FieldRuleGroupDefinition, esploriamo ricorsivamente le regole
+            const groups = rule_helper_1.RuleHelper.getGroups(rule);
+            const rules = rule_helper_1.RuleHelper.getRules(rule);
+            // Esplora i gruppi
+            groups.forEach(group => {
+                this.extractDependencies(group, dependencies);
+            });
+            // Esplora le regole singole
+            rules.forEach(r => {
+                this.extractDependencies(r, dependencies);
+            });
+        }
+    }
+    /**
+     * Restituisce tutti i campi che dipendono da un campo specifico.
+     */
+    getDependentFields(fieldId) {
+        const visited = new Set();
+        const stack = [fieldId];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const dependents = this.dependentsMap.get(current) ?? new Set();
+            for (const dep of dependents) {
+                if (!visited.has(dep)) {
+                    visited.add(dep);
+                    stack.push(dep);
+                }
+            }
+        }
+        return visited;
+    }
+}
+exports.DependencyGraph = DependencyGraph;
+//# sourceMappingURL=dependency-graph.js.map

package/dist/dependency-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.js","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":";;;AAEA,uDAAmD;AAEnD,MAAa,eAAe;IAGxB,YAAY,MAAyB;QAF7B,kBAAa,GAA6B,IAAI,GAAG,EAAE,CAAC;QAGxD,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;YACnB,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;YAEvC,2CAA2C;YAC3C,MAAM,UAAU,GAAG,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;YAC3E,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,QAAiC,CAAC,CAAC;gBAEtD,IAAI,IAAI,EAAE,CAAC;oBACP,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;gBACjD,CAAC;YACL,CAAC,CAAC,CAAC;YAEH,4BAA4B;YAC5B,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;gBACvB,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC/B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;gBAC3C,CAAC;gBACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;OAEG;IACK,mBAAmB,CAAC,IAAmB,EAAE,YAAyB;QACtE,IAAI,kBAAkB,IAAI,IAAI,EAAE,CAAC;YAC7B,6DAA6D;YAC7D,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;YAClB,wEAAwE;YACxE,MAAM,MAAM,GAAG,wBAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC1C,MAAM,KAAK,GAAG,wBAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAExC,mBAAmB;YACnB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;gBACnB,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;YAEH,4BAA4B;YAC5B,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;gBACd,IAAI,CAAC,mBAAmB,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YAC9C,CAAC,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED;;OAEG;IACH,kBAAkB,CAAC,OAAe;QAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAClC,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,CAAC;QAExB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;YAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;YAChE,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;gBAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACpB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;oBACjB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACpB,CAAC;YACL,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACnB,CAAC;CACJ;AAzED,0CAyEC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { type FieldControlType, type FieldDefinition, type ConditionalFieldProperty, type FieldListOption, type FieldControlState, type CustomFieldControlType, type FormControlState, } from './models/field-definition';
+export { type FormFlowDefinition, type FormFlowSchema, type FormFlowValues, } from './models/form-definition';
+export { type FieldRuleGroupDefinition, type FieldRuleNode, type LogicalOperator, } from './models/group';
+export { type FieldRuleDefinition } from './models/rule';
+export { RuleEvaluator as FormFlowRuleEvaluator } from './rule-evaluator';
+export { FORM_FLOW_OPERATORS_MAP, type RuleOperatorKey, type RuleOperatorMeta, type RuleOperatorValueType, } from './models/operators';
+export { OperatorRegistry as FormFlowOperatorRegistry } from './models/operator-registry';
+export { DependencyGraph as FormFlowDependencyGraph } from './dependency-graph';
+export { RuleBuilder as FormFlowRuleBuilder } from './rule-builder';
+export { RuleMapper as FormFlowRuleMapper } from './utility/rule-mapper';
+export { RuleHelper as FormFlowRuleHelper } from './utility/rule-helper';
+export { FieldHelper as FormFlowFieldHelper } from './utility/field-helper';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACH,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACH,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,eAAe,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAIzD,OAAO,EAAE,aAAa,IAAI,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EACH,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACH,gBAAgB,IAAI,wBAAwB,EAC/C,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EAAE,eAAe,IAAI,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,WAAW,IAAI,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,WAAW,IAAI,mBAAmB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+// packages/core/src/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormFlowFieldHelper = exports.FormFlowRuleHelper = exports.FormFlowRuleMapper = exports.FormFlowRuleBuilder = exports.FormFlowDependencyGraph = exports.FormFlowOperatorRegistry = exports.FORM_FLOW_OPERATORS_MAP = exports.FormFlowRuleEvaluator = void 0;
+// 3. Valutatore ufficiale del sistema
+var rule_evaluator_1 = require("./rule-evaluator");
+Object.defineProperty(exports, "FormFlowRuleEvaluator", { enumerable: true, get: function () { return rule_evaluator_1.RuleEvaluator; } });
+// 4. (Opzionale) operatori configurabili, se vuoi supportare override dal consumer
+var operators_1 = require("./models/operators");
+Object.defineProperty(exports, "FORM_FLOW_OPERATORS_MAP", { enumerable: true, get: function () { return operators_1.FORM_FLOW_OPERATORS_MAP; } });
+var operator_registry_1 = require("./models/operator-registry");
+Object.defineProperty(exports, "FormFlowOperatorRegistry", { enumerable: true, get: function () { return operator_registry_1.OperatorRegistry; } });
+var dependency_graph_1 = require("./dependency-graph");
+Object.defineProperty(exports, "FormFlowDependencyGraph", { enumerable: true, get: function () { return dependency_graph_1.DependencyGraph; } });
+var rule_builder_1 = require("./rule-builder");
+Object.defineProperty(exports, "FormFlowRuleBuilder", { enumerable: true, get: function () { return rule_builder_1.RuleBuilder; } });
+var rule_mapper_1 = require("./utility/rule-mapper");
+Object.defineProperty(exports, "FormFlowRuleMapper", { enumerable: true, get: function () { return rule_mapper_1.RuleMapper; } });
+var rule_helper_1 = require("./utility/rule-helper");
+Object.defineProperty(exports, "FormFlowRuleHelper", { enumerable: true, get: function () { return rule_helper_1.RuleHelper; } });
+var field_helper_1 = require("./utility/field-helper");
+Object.defineProperty(exports, "FormFlowFieldHelper", { enumerable: true, get: function () { return field_helper_1.FieldHelper; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,6BAA6B;;;AAyB7B,sCAAsC;AACtC,mDAA0E;AAAjE,uHAAA,aAAa,OAAyB;AAE/C,mFAAmF;AACnF,gDAK4B;AAJxB,oHAAA,uBAAuB,OAAA;AAM3B,gEAEmC;AAD/B,6HAAA,gBAAgB,OAA4B;AAGhD,uDAAgF;AAAvE,2HAAA,eAAe,OAA2B;AAEnD,+CAAoE;AAA3D,mHAAA,WAAW,OAAuB;AAC3C,qDAAyE;AAAhE,iHAAA,UAAU,OAAsB;AACzC,qDAAyE;AAAhE,iHAAA,UAAU,OAAsB;AACzC,uDAA4E;AAAnE,mHAAA,WAAW,OAAuB"}

package/dist/models/field-definition.d.ts

@@ -0,0 +1,49 @@
+import { FieldRuleGroupDefinition } from './group';
+export type FieldControlType = 'text' | 'number' | 'date' | 'singleSelect' | 'multipleSelect' | 'checkbox';
+export type CustomFieldControlType<T extends string = never> = FieldControlType | Exclude<T, FieldControlType>;
+export type ConditionalFieldProperty = "visibleIf" | "requiredIf" | "disabledIf" | "readonlyIf";
+export type FieldListOption = {
+    label: string;
+    value: any;
+} & Record<string, any>;
+export interface FieldDefinition<TControl extends FieldControlType = FieldControlType> {
+    id: string;
+    label: string;
+    type: TControl;
+    defaultValue?: any;
+    visibleIf?: FieldRuleGroupDefinition;
+    requiredIf?: FieldRuleGroupDefinition;
+    disabledIf?: FieldRuleGroupDefinition;
+    readonlyIf?: FieldRuleGroupDefinition;
+    /**
+   * List of available options for fields like select, checkbox, or radio buttons.
+   *
+   * The base shape is defined by `FieldOption`, which requires:
+   * - `label`: the text displayed to the user
+   * - `value`: the actual value stored/submitted
+   *
+   * The `FieldOption` type is **not exported**, but consumers can still conform
+   * to its shape using `satisfies` to ensure compatibility while extending it
+   * with additional UI-related metadata (e.g. icons, images, tooltips).
+   *
+   * Example:
+   *
+   * const options = [
+   *   { label: "Startup", value: "startup", icon: "🚀" },
+   *   { label: "Agency", value: "agency", icon: "🏢" },
+   *   { label: "Freelancer", value: "freelancer", icon: "🧑‍💻" }
+   * ] satisfies FieldOption[];
+   */
+    options?: FieldListOption[];
+}
+/**
+ * Rappresenta il campo target dopo la valutazione delle regole condizionali
+ */
+export interface FieldControlState {
+    visible: boolean;
+    required: boolean;
+    disabled: boolean;
+    readonly: boolean;
+}
+export type FormControlState = Record<string, FieldControlState>;
+//# sourceMappingURL=field-definition.d.ts.map

package/dist/models/field-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-definition.d.ts","sourceRoot":"","sources":["../../src/models/field-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAC3G,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,IACzD,gBAAgB,GAAG,OAAO,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;AAClD,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAQhG,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,GAAG,CAAC;CACZ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExB,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,gBAAgB,GAAG,gBAAgB;IACnF,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,CAAC,EAAE,GAAG,CAAC;IAGnB,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,UAAU,CAAC,EAAE,wBAAwB,CAAC;IAEtC;;;;;;;;;;;;;;;;;;KAkBC;IACD,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B;AAGD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AACD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC"}

package/dist/models/field-definition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=field-definition.js.map

package/dist/models/field-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-definition.js","sourceRoot":"","sources":["../../src/models/field-definition.ts"],"names":[],"mappings":""}

package/dist/models/form-definition.d.ts

@@ -0,0 +1,16 @@
+import { CustomFieldControlType, FieldDefinition } from "./field-definition";
+export type FormFlowValues = Record<string, any>;
+export interface FormFlowDefinition<TControl extends CustomFieldControlType = CustomFieldControlType> {
+    formId: string;
+    fields: FieldDefinition<TControl>[];
+    metadata?: Record<string, any>;
+}
+export interface FormFlowSchema<TControl extends CustomFieldControlType = CustomFieldControlType> {
+    definition: FormFlowDefinition<TControl>;
+    getValues: () => FormFlowValues;
+    getFieldValue: (fieldId: keyof FormFlowValues) => any;
+    setValues: (values: FormFlowValues, emit?: boolean) => void;
+    setFieldValue: (fieldId: keyof FormFlowValues, value: any, emit?: boolean) => void;
+    readonly values: FormFlowValues;
+}
+//# sourceMappingURL=form-definition.d.ts.map

package/dist/models/form-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-definition.d.ts","sourceRoot":"","sources":["../../src/models/form-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE7E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEjD,MAAM,WAAW,kBAAkB,CAC9B,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc,CAAC,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB;IAC5F,UAAU,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAA;IACxC,SAAS,EAAE,MAAM,cAAc,CAAC;IAChC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,cAAc,KAAK,GAAG,CAAC;IACtD,SAAS,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5D,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,cAAc,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACnF,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACnC"}

package/dist/models/form-definition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=form-definition.js.map

package/dist/models/form-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-definition.js","sourceRoot":"","sources":["../../src/models/form-definition.ts"],"names":[],"mappings":""}

package/dist/models/group.d.ts

@@ -0,0 +1,12 @@
+import { ConditionalFieldProperty } from "./field-definition";
+import { FieldRuleDefinition } from "./rule";
+export type LogicalOperator = "and" | "or";
+export type FieldRuleNode = FieldRuleDefinition | FieldRuleGroupDefinition;
+export interface FieldRuleGroupDefinition {
+    groupId: string;
+    ruleType: ConditionalFieldProperty;
+    operator: LogicalOperator;
+    not?: boolean;
+    rules: FieldRuleNode[];
+}
+//# sourceMappingURL=group.d.ts.map

package/dist/models/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/models/group.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAE7C,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,IAAI,CAAC;AAC3C,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,wBAAwB,CAAC;AAC3E,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,wBAAwB,CAAC;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,aAAa,EAAE,CAAC;CAC1B"}

package/dist/models/group.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=group.js.map

package/dist/models/group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.js","sourceRoot":"","sources":["../../src/models/group.ts"],"names":[],"mappings":""}

package/dist/models/operator-registry.d.ts

@@ -0,0 +1,21 @@
+import { RuleOperatorKey, RuleOperatorMeta } from "./operators";
+export declare const OperatorRegistry: {
+    /**
+     * Get the definition of a specific operator by key.
+     */
+    get: (key: RuleOperatorKey) => RuleOperatorMeta | undefined;
+    /**
+     * Get all operator definitions (e.g., for building UI pickers).
+     */
+    getAll: () => Partial<Record<RuleOperatorKey, RuleOperatorMeta>>;
+    /**
+     * Register one or more operator overrides or additions.
+     * Existing operators with the same key will be replaced.
+     */
+    register: (overrides: Partial<Record<RuleOperatorKey, RuleOperatorMeta>>) => void;
+    /**
+     * Reset the registry to the original default operator map.
+     */
+    reset: () => void;
+};
+//# sourceMappingURL=operator-registry.d.ts.map

package/dist/models/operator-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-registry.d.ts","sourceRoot":"","sources":["../../src/models/operator-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAA2B,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAKzF,eAAO,MAAM,gBAAgB;IACzB;;OAEG;eACQ,eAAe,KAAG,gBAAgB,GAAG,SAAS;IAEzD;;OAEG;kBACS,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;IAE9D;;;OAGG;0BACmB,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;IAIxE;;OAEG;;CAIN,CAAC"}

package/dist/models/operator-registry.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperatorRegistry = void 0;
+// operator-registry.ts
+const operators_1 = require("./operators");
+// Mutable copy of the original operator map
+let registry = { ...operators_1.FORM_FLOW_OPERATORS_MAP };
+exports.OperatorRegistry = {
+    /**
+     * Get the definition of a specific operator by key.
+     */
+    get: (key) => registry[key],
+    /**
+     * Get all operator definitions (e.g., for building UI pickers).
+     */
+    getAll: () => registry,
+    /**
+     * Register one or more operator overrides or additions.
+     * Existing operators with the same key will be replaced.
+     */
+    register: (overrides) => {
+        registry = { ...registry, ...overrides };
+    },
+    /**
+     * Reset the registry to the original default operator map.
+     */
+    reset: () => {
+        registry = { ...operators_1.FORM_FLOW_OPERATORS_MAP };
+    },
+};
+//# sourceMappingURL=operator-registry.js.map

package/dist/models/operator-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-registry.js","sourceRoot":"","sources":["../../src/models/operator-registry.ts"],"names":[],"mappings":";;;AAAA,uBAAuB;AACvB,2CAAyF;AAEzF,4CAA4C;AAC5C,IAAI,QAAQ,GAAuD,EAAE,GAAG,mCAAuB,EAAE,CAAC;AAErF,QAAA,gBAAgB,GAAG;IAC5B;;OAEG;IACH,GAAG,EAAE,CAAC,GAAoB,EAAgC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC;IAE1E;;OAEG;IACH,MAAM,EAAE,GAAuD,EAAE,CAAC,QAAQ;IAE1E;;;OAGG;IACH,QAAQ,EAAE,CAAC,SAA6D,EAAE,EAAE;QACxE,QAAQ,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,KAAK,EAAE,GAAG,EAAE;QACR,QAAQ,GAAG,EAAE,GAAG,mCAAuB,EAAE,CAAC;IAC9C,CAAC;CACJ,CAAC"}

package/dist/models/operators.d.ts

@@ -0,0 +1,43 @@
+import { RuleBuilder } from "../rule-builder";
+import { FieldControlType } from "./field-definition";
+/**
+ * Base operators defined inside RuleBuilder.
+ */
+type RuleOperatorBase = keyof typeof RuleBuilder.value;
+/**
+ * Special operator that represents a field reference.
+ */
+type RuleOperatorSpecial = "var";
+/**
+ * Union of all operator keys supported by the system.
+ */
+export type RuleOperatorKey = RuleOperatorBase | RuleOperatorSpecial;
+/**
+ * Defines the kind of value an operator expects:
+ * - "list": expects an array of values
+ * - "single": expects a single value
+ * - "none": no value required (boolean-like)
+ * - "field": expects a reference to another field
+ * - undefined: not specified
+ */
+export type RuleOperatorValueType = "list" | "single" | "none" | "field" | undefined;
+/**
+ * Metadata for describing how an operator behaves.
+ */
+export interface RuleOperatorMeta {
+    /** Label to display in the UI (can be customized by consumers). */
+    label: string;
+    /** Which field types this operator is allowed for. */
+    allowedTypes?: FieldControlType[] | "all";
+    /** The type of value this operator requires. */
+    valueType?: RuleOperatorValueType;
+    /** If true, the operator will be hidden from the UI picker. */
+    hideFromPicker?: boolean;
+}
+/**
+ * Default operator map shipped with `@form-flow/core`.
+ * Consumers may override or extend this map at runtime.
+ */
+export declare const FORM_FLOW_OPERATORS_MAP: Partial<Record<RuleOperatorKey, RuleOperatorMeta>>;
+export {};
+//# sourceMappingURL=operators.d.ts.map

package/dist/models/operators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operators.d.ts","sourceRoot":"","sources":["../../src/models/operators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD;;GAEG;AACH,KAAK,gBAAgB,GAAG,MAAM,OAAO,WAAW,CAAC,KAAK,CAAC;AAEvD;;GAEG;AACH,KAAK,mBAAmB,GAAG,KAAK,CAAC;AAEjC;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAC7B,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IAEd,sDAAsD;IACtD,YAAY,CAAC,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IAE1C,gDAAgD;IAChD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAElC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAClC,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAoBlD,CAAC"}