@formos/kernel 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,372 @@
+import { ValidationTrigger, NormalizedSchemaV1, Conditional } from '@formos/schema';
+
+/**
+ * Type definitions for kernel adapters and execution context
+ */
+/**
+ * Validator executor function signature.
+ *
+ * Adapters implement this interface to execute actual validation logic.
+ * The kernel calls validators with field values and expects either:
+ * - `null` if the value is valid
+ * - Error message string if invalid
+ *
+ * **IMPORTANT**: Return `null` for valid values, NOT `undefined`.
+ *
+ * Validators can be synchronous or async (returning a Promise).
+ *
+ * @param value - The field value to validate
+ * @param params - Validation parameters from the schema's `rule` property
+ * @param context - Execution context with access to other field values
+ * @returns Error message if invalid, `null` if valid
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * const required: ValidatorExecutor = (value, params, context) => {
+ *   return value ? null : 'This field is required';
+ * };
+ *
+ * const matchesField: ValidatorExecutor = (value, params, context) => {
+ *   const { targetField } = params as { targetField: string };
+ *   const targetValue = context.getValue(targetField);
+ *   return value === targetValue ? null : 'Fields must match';
+ * };
+ * ```
+ */
+type ValidatorExecutor = (value: unknown, params: unknown, context: ValidationContext) => Promise<string | null> | string | null;
+/**
+ * Validation execution context.
+ *
+ * Provides validators with read-only access to form state.
+ * Validators can check other field values for cross-field validation.
+ *
+ * @public
+ * @stable
+ */
+interface ValidationContext {
+    /** Current field name being validated */
+    fieldName: string;
+    /** All form values */
+    values: ReadonlyMap<string, unknown>;
+    /** Get value of another field */
+    getValue: (fieldName: string) => unknown;
+}
+/**
+ * Effect executor function signature.
+ *
+ * Adapters implement this interface to execute side effects triggered
+ * by field changes. Common use cases:
+ * - Sync fields (e.g., calculate fullName from firstName + lastName)
+ * - Trigger API calls (e.g., fetch cities when country changes)
+ * - Custom business logic
+ *
+ * Effects have write access via `context.setValue()`.
+ *
+ * @param params - Effect configuration from the schema's `config` property
+ * @param context - Execution context with form values and setValue
+ * @returns Optional result value (typically unused)
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * const syncFullName: EffectExecutor = (params, context) => {
+ *   const firstName = context.getValue('firstName') as string;
+ *   const lastName = context.getValue('lastName') as string;
+ *   context.setValue('fullName', `${firstName} ${lastName}`);\n * };
+ *
+ * const fetchCities: EffectExecutor = async (params, context) => {
+ *   const country = context.sourceValue as string;
+ *   const response = await fetch(`/api/cities?country=${country}`);
+ *   const cities = await response.json();
+ *   context.setValue('cities', cities);\n * };
+ * ```
+ */
+type EffectExecutor = (params: unknown, context: EffectContext) => Promise<unknown> | unknown;
+/**
+ * Effect execution context.
+ *
+ * Provides effects with read-write access to form state.
+ * Effects can read any field value and update the target field.
+ *
+ * @public
+ * @stable
+ */
+interface EffectContext {
+    /** Source field that triggered the effect */
+    sourceField: string;
+    /** Source field's new value */
+    sourceValue: unknown;
+    /** Target field (if applicable) */
+    targetField?: string;
+    /** All form values */
+    values: ReadonlyMap<string, unknown>;
+    /** Get value of a field */
+    getValue: (fieldName: string) => unknown;
+    /** Set value of a field (for sync effects) */
+    setValue: (fieldName: string, value: unknown) => void;
+}
+
+/**
+ * Value management operations
+ * Handles getting and setting field values with validation and effects
+ */
+
+/**
+ * Options for setValue operation
+ */
+/**
+ * Options for setValue operations.
+ *
+ * @public
+ * @stable
+ */
+interface SetValueOptions {
+    /** Validation trigger (default: "onChange") */
+    trigger?: ValidationTrigger | "manual";
+    /** If true, skip validation and effects */
+    silent?: boolean;
+}
+
+/**
+ * Form lifecycle operations
+ * Handles submit and reset operations
+ */
+
+/**
+ * Submit handler callback
+ */
+/**
+ * Callback invoked when form is successfully submitted.
+ *
+ * Only called if all validations pass. Receives all form values.
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * const onSubmit: SubmitHandler = async (values) => {
+ *   await fetch('/api/submit', {
+ *     method: 'POST',
+ *     body: JSON.stringify(values)
+ *   });
+ * };
+ * ```
+ */
+type SubmitHandler = (values: Record<string, unknown>) => void | Promise<void>;
+
+/**
+ * Form engine factory
+ * Creates FormEngine instances with configuration
+ */
+
+/**
+ * Configuration options for creating a form engine.
+ *
+ * All options use the **adapter pattern** to remain framework-agnostic.
+ * The kernel provides orchestration; adapters provide implementation.
+ *
+ * @public
+ * @stable
+ */
+interface FormEngineOptions {
+    /** Custom validator executors */
+    validators?: Record<string, ValidatorExecutor>;
+    /** Custom effect executors */
+    effectExecutors?: Record<string, EffectExecutor>;
+    /** Submit handler */
+    onSubmit?: SubmitHandler;
+}
+/**
+ * Form engine interface - the primary API for interacting with forms.
+ *
+ * This headless engine manages all form logic:
+ * - State management (values, errors, touched, dirty)
+ * - Validation orchestration with pluggable validators
+ * - Effect execution for field interactions
+ * - Multi-step navigation with validation guards
+ *
+ * The engine is **completely UI-agnostic** - no React, no DOM.
+ * UI packages consume this API to build interactive forms.
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * import { createFormEngine } from '@formos/kernel';
+ * import { normalizeSchema } from '@formos/schema';
+ *
+ * const normalized = normalizeSchema(mySchema);
+ * const engine = createFormEngine(normalized, {
+ *   validators: { required: (value) => value ? null : 'Required' }
+ * });
+ *
+ * // Get/set values
+ * await engine.setValue('email', 'user@example.com');
+ * const email = engine.getValue('email');
+ *
+ * // Validate
+ * const isValid = await engine.validate();
+ *
+ * // Submit
+ * const success = await engine.submit();
+ * ```
+ */
+interface FormEngine {
+    getValue(fieldName: string): unknown;
+    getError(fieldName: string): string | undefined;
+    getErrors(): Record<string, string | undefined>;
+    isValid(): boolean;
+    isDirty(fieldName?: string): boolean;
+    isTouched(fieldName: string): boolean;
+    setValue(fieldName: string, value: unknown, options?: SetValueOptions): Promise<void>;
+    setError(fieldName: string, error: string): void;
+    clearError(fieldName: string): void;
+    markTouched(fieldName: string): void;
+    validate(fieldName?: string, trigger?: "onChange" | "onBlur" | "onSubmit" | "manual"): Promise<boolean>;
+    submit(): Promise<boolean>;
+    reset(): void;
+    getCurrentStep?(): number;
+    getTotalSteps?(): number;
+    nextStep?(): Promise<boolean>;
+    prevStep?(): void;
+    goToStep?(stepIndex: number): Promise<boolean>;
+    canGoToStep?(stepIndex: number): boolean;
+}
+/**
+ * Create a form engine instance from a normalized schema.
+ *
+ * This is the primary entry point for the kernel. It instantiates
+ * a {@link FormEngine} that manages all form logic.
+ *
+ * The engine is stateful and mutable. Each call creates a new
+ * independent form instance with its own state.
+ *
+ * @param schema - Normalized schema from {@link normalizeSchema}
+ * @param options - Configuration with validators, effects, and submit handler
+ * @returns Fully configured form engine instance
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * import { createFormEngine } from '@formos/kernel';
+ * import { normalizeSchema } from '@formos/schema';
+ *
+ * const schema = { version: 'v1', fields: [...] };
+ * const normalized = normalizeSchema(schema);
+ *
+ * const engine = createFormEngine(normalized, {
+ *   validators: {
+ *     required: (value) => value ? null : 'Required',
+ *     email: (value) => /\\S+@\\S+/.test(value) ? null : 'Invalid'
+ *   },
+ *   onSubmit: async (values) => {
+ *     await api.post('/submit', values);
+ *   }
+ * });
+ * ```
+ */
+declare function createFormEngine(schema: NormalizedSchemaV1, options?: FormEngineOptions): FormEngine;
+
+/**
+ * Conditional evaluation engine
+ * Evaluates ConditionalRule and ConditionalGroup from schema
+ */
+
+/**
+ * Evaluate a conditional expression against current form values.
+ *
+ * Handles both single {@link ConditionalRule} and complex {@link ConditionalGroup}
+ * with AND/OR logic. This is the core function for dynamic field behavior.
+ *
+ * @param conditional - Rule or group to evaluate
+ * @param getValue - Function to retrieve field values by name
+ * @returns True if the condition is satisfied
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * const condition: ConditionalRule = {
+ *   field: 'age',
+ *   operator: 'greaterThan',
+ *   value: 18
+ * };
+ *
+ * const getValue = (name: string) => formValues[name];
+ * const result = evaluateConditional(condition, getValue);
+ * ```
+ */
+declare function evaluateConditional(conditional: Conditional, getValue: (fieldName: string) => unknown): boolean;
+/**
+ * Check if a field should be visible based on its visibleWhen condition.
+ *
+ * Returns `true` if:
+ * - Field has no `visibleWhen` property (always visible)
+ * - The `visibleWhen` condition evaluates to `true`
+ *
+ * @param field - Field schema with optional visibleWhen property
+ * @param getValue - Function to retrieve field values
+ * @returns True if field should be visible
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   name: 'ssn',
+ *   type: 'text',
+ *   visibleWhen: { field: 'country', operator: 'equals', value: 'US' }
+ * };
+ *
+ * if (isFieldVisible(field, getValue)) {
+ *   // Render the field
+ * }
+ * ```
+ */
+declare function isFieldVisible(field: {
+    visibleWhen?: Conditional;
+}, getValue: (fieldName: string) => unknown): boolean;
+/**
+ * Check if a field is required based on its required configuration.
+ *
+ * Handles three cases:
+ * - `undefined`: Field is optional (returns `false`)
+ * - `boolean`: Returns the boolean value directly
+ * - `Conditional`: Evaluates the condition dynamically
+ *
+ * @param field - Field schema with optional required property
+ * @param getValue - Function to retrieve field values
+ * @returns True if field is required
+ *
+ * @public
+ * @stable
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   name: 'phone',
+ *   type: 'tel',
+ *   required: { field: 'contactMethod', operator: 'equals', value: 'phone' }
+ * };
+ *
+ * if (isFieldRequired(field, getValue)) {
+ *   // Show required indicator
+ * }
+ * ```
+ */
+declare function isFieldRequired(field: {
+    required?: boolean | Conditional;
+}, getValue: (fieldName: string) => unknown): boolean;
+
+export { type EffectContext, type EffectExecutor, type FormEngine, type FormEngineOptions, type SetValueOptions, type SubmitHandler, type ValidationContext, type ValidatorExecutor, createFormEngine, evaluateConditional, isFieldRequired, isFieldVisible };