@slowclap/rezi-core 0.1.0-fork.1

package/dist/forms/useForm.js

@@ -0,0 +1,185 @@
+/**
+ * packages/core/src/forms/useForm.ts — Form management hook.
+ *
+ * Why: Provides a React-like form management hook for Rezi widgets.
+ * Manages form values, validation, touched/dirty state, submission,
+ * dynamic array fields, wizard navigation, and disabled/read-only behavior.
+ *
+ * @see docs/recipes/form-validation.md (GitHub issue #119)
+ */
+import { createFieldArrayApi } from "./internal/arrayState.js";
+import { createFieldBindings } from "./internal/bindings.js";
+import { cloneInitialValues, computeIsDirty, createFormFlagActions, createFormStateAccessors, createInitialState, } from "./internal/state.js";
+import { createResetAction, createSubmitAction } from "./internal/submit.js";
+import { clampStepIndex, createWizardActions, runWizardStepValidation } from "./internal/wizard.js";
+import { DEFAULT_ASYNC_DEBOUNCE_MS, createDebouncedAsyncValidator, isValidationClean, mergeValidationErrors, } from "./validation.js";
+/**
+ * Form management hook for Rezi widgets.
+ */
+export function useForm(ctx, options) {
+    const [state, setState] = ctx.useState(() => createInitialState(options));
+    const stateRef = ctx.useRef(state);
+    stateRef.current = state;
+    const initialValuesRef = ctx.useRef(cloneInitialValues(options.initialValues));
+    const asyncValidatorRef = ctx.useRef(undefined);
+    const pendingAsyncValuesRef = ctx.useRef(null);
+    const submittingRef = ctx.useRef(false);
+    const submitAttemptRef = ctx.useRef(0);
+    const validateRef = ctx.useRef(options.validate);
+    validateRef.current = options.validate;
+    const nonTextBindingWarningsRef = ctx.useRef(new Set());
+    const fieldArrayKeysRef = ctx.useRef({});
+    const fieldArrayKeyCounterRef = ctx.useRef(0);
+    const updateFormState = (nextState) => {
+        setState((prev) => {
+            const resolved = typeof nextState === "function"
+                ? nextState(prev)
+                : nextState;
+            stateRef.current = resolved;
+            return resolved;
+        });
+    };
+    const wizardSteps = options.wizard?.steps ?? [];
+    const stepCount = wizardSteps.length;
+    const hasWizard = stepCount > 0;
+    const currentStep = hasWizard ? clampStepIndex(state.currentStep, stepCount) : 0;
+    const isFirstStep = !hasWizard || currentStep === 0;
+    const isLastStep = !hasWizard || currentStep === stepCount - 1;
+    const { isFieldDisabledInternal, isFieldReadOnlyInternal, isFieldEditableInternal, filterDisabledValidationErrors, runSyncValidationFiltered, runAsyncValidationFiltered, warnUnsupportedTextBinding, canBindFieldAsText, } = createFormStateAccessors({
+        stateRef,
+        initialValuesRef,
+        validateRef,
+        validateAsync: options.validateAsync,
+        nonTextBindingWarningsRef,
+    });
+    const runWizardStepValidationForState = (values, stepIndex, source = stateRef.current) => runWizardStepValidation({
+        values,
+        stepIndex,
+        wizardSteps,
+        source,
+        runSyncValidationFiltered,
+        filterDisabledValidationErrors,
+    });
+    ctx.useEffect(() => {
+        if (options.validateAsync) {
+            asyncValidatorRef.current = createDebouncedAsyncValidator(options.validateAsync, options.validateAsyncDebounce ?? DEFAULT_ASYNC_DEBOUNCE_MS, (asyncErrors) => {
+                updateFormState((prev) => ({
+                    ...prev,
+                    errors: mergeValidationErrors(runSyncValidationFiltered(prev.values, prev), filterDisabledValidationErrors(asyncErrors, prev)),
+                }));
+            });
+            return () => {
+                asyncValidatorRef.current?.cancel();
+            };
+        }
+        return undefined;
+    }, [options.validateAsync, options.validateAsyncDebounce]);
+    const isValid = isValidationClean(state.errors);
+    const isDirty = computeIsDirty(state.dirty);
+    const { validateForm, validateField, setFieldValue, setFieldError, setFieldTouched, handleChange, handleBlur, bind, field, } = createFieldBindings({
+        ctx,
+        state,
+        stateRef,
+        initialValuesRef,
+        pendingAsyncValuesRef,
+        asyncValidatorRef,
+        validate: options.validate,
+        validateOnBlur: options.validateOnBlur,
+        validateOnChange: options.validateOnChange,
+        updateFormState,
+        isFieldDisabledInternal,
+        isFieldReadOnlyInternal,
+        isFieldEditableInternal,
+        runSyncValidationFiltered,
+        canBindFieldAsText,
+        warnUnsupportedTextBinding,
+    });
+    const { setDisabled, setReadOnly, setFieldDisabled, setFieldReadOnly } = createFormFlagActions({
+        updateFormState,
+        filterDisabledValidationErrors,
+    });
+    const { useFieldArray } = createFieldArrayApi({
+        state,
+        validateOnChange: options.validateOnChange,
+        initialValuesRef,
+        fieldArrayKeysRef,
+        fieldArrayKeyCounterRef,
+        pendingAsyncValuesRef,
+        asyncValidatorRef,
+        updateFormState,
+        isFieldEditableInternal,
+        runSyncValidationFiltered,
+    });
+    const { nextStep, previousStep, goToStep } = createWizardActions({
+        hasWizard,
+        stepCount,
+        wizardSteps,
+        validateAsync: options.validateAsync,
+        stateRef,
+        updateFormState,
+        runAsyncValidationFiltered,
+        runWizardStepValidation: runWizardStepValidationForState,
+    });
+    const reset = createResetAction({
+        formOptions: options,
+        asyncValidatorRef,
+        attemptRef: submitAttemptRef,
+        submittingRef,
+        fieldArrayKeysRef,
+        updateFormState,
+    });
+    const handleSubmit = createSubmitAction({
+        formOptions: options,
+        hasWizard,
+        stepCount,
+        stateRef,
+        submittingRef,
+        asyncValidatorRef,
+        attemptRef: submitAttemptRef,
+        updateFormState,
+        runSyncValidationFiltered,
+        runAsyncValidationFiltered,
+        nextStep,
+        reset,
+    });
+    return Object.freeze({
+        values: state.values,
+        errors: state.errors,
+        touched: state.touched,
+        dirty: state.dirty,
+        isValid,
+        isDirty,
+        isSubmitting: state.isSubmitting,
+        submitError: state.submitError,
+        submitCount: state.submitCount,
+        disabled: state.disabled,
+        readOnly: state.readOnly,
+        currentStep,
+        stepCount,
+        hasWizard,
+        isFirstStep,
+        isLastStep,
+        handleChange,
+        handleBlur,
+        bind,
+        field,
+        handleSubmit,
+        reset,
+        setFieldValue,
+        setFieldError,
+        setFieldTouched,
+        validateField,
+        validateForm,
+        setDisabled,
+        setReadOnly,
+        setFieldDisabled,
+        setFieldReadOnly,
+        isFieldDisabled: (fieldName) => isFieldDisabledInternal(fieldName, stateRef.current),
+        isFieldReadOnly: (fieldName) => isFieldReadOnlyInternal(fieldName, stateRef.current),
+        useFieldArray,
+        nextStep,
+        previousStep,
+        goToStep,
+    });
+}
+//# sourceMappingURL=useForm.js.map

package/dist/forms/useForm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useForm.js","sourceRoot":"","sources":["../../src/forms/useForm.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpG,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB;;GAEG;AACH,MAAM,UAAU,OAAO,CACrB,GAAyB,EACzB,OAA0B;IAE1B,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAe,GAAG,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxF,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnC,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC;IAEzB,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,CAAI,kBAAkB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAElF,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,CAElC,SAAS,CAAC,CAAC;IAEb,MAAM,qBAAqB,GAAG,GAAG,CAAC,MAAM,CAAW,IAAI,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjD,WAAW,CAAC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IACvC,MAAM,yBAAyB,GAAG,GAAG,CAAC,MAAM,CAAc,IAAI,GAAG,EAAE,CAAC,CAAC;IAErE,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,CAAqC,EAAE,CAAC,CAAC;IAC7E,MAAM,uBAAuB,GAAG,GAAG,CAAC,MAAM,CAAS,CAAC,CAAC,CAAC;IAEtD,MAAM,eAAe,GAAG,CACtB,SAAgE,EAC1D,EAAE;QACR,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE;YAChB,MAAM,QAAQ,GACZ,OAAO,SAAS,KAAK,UAAU;gBAC7B,CAAC,CAAE,SAAkD,CAAC,IAAI,CAAC;gBAC3D,CAAC,CAAC,SAAS,CAAC;YAChB,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC;YAC5B,OAAO,QAAQ,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC;IAChD,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC;IACrC,MAAM,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC;IAChC,MAAM,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,MAAM,WAAW,GAAG,CAAC,SAAS,IAAI,WAAW,KAAK,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,CAAC,SAAS,IAAI,WAAW,KAAK,SAAS,GAAG,CAAC,CAAC;IAE/D,MAAM,EACJ,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,8BAA8B,EAC9B,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,kBAAkB,GACnB,GAAG,wBAAwB,CAAC;QAC3B,QAAQ;QACR,gBAAgB;QAChB,WAAW;QACX,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,yBAAyB;KAC1B,CAAC,CAAC;IAEH,MAAM,+BAA+B,GAAG,CACtC,MAAS,EACT,SAAiB,EACjB,SAAsE,QAAQ,CAAC,OAAO,EACjE,EAAE,CACvB,uBAAuB,CAAC;QACtB,MAAM;QACN,SAAS;QACT,WAAW;QACX,MAAM;QACN,yBAAyB;QACzB,8BAA8B;KAC/B,CAAC,CAAC;IAEL,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;QACjB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;YAC1B,iBAAiB,CAAC,OAAO,GAAG,6BAA6B,CACvD,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,qBAAqB,IAAI,yBAAyB,EAC1D,CAAC,WAAW,EAAE,EAAE;gBACd,eAAe,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;oBACzB,GAAG,IAAI;oBACP,MAAM,EAAE,qBAAqB,CAC3B,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAC5C,8BAA8B,CAAC,WAAW,EAAE,IAAI,CAAC,CAClD;iBACF,CAAC,CAAC,CAAC;YACN,CAAC,CACF,CAAC;YAEF,OAAO,GAAG,EAAE;gBACV,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YACtC,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAE3D,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAE5C,MAAM,EACJ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,KAAK,GACN,GAAG,mBAAmB,CAAC;QACtB,GAAG;QACH,KAAK;QACL,QAAQ;QACR,gBAAgB;QAChB,qBAAqB;QACrB,iBAAiB;QACjB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,eAAe;QACf,uBAAuB;QACvB,uBAAuB;QACvB,uBAAuB;QACvB,yBAAyB;QACzB,kBAAkB;QAClB,0BAA0B;KAC3B,CAAC,CAAC;IAEH,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,qBAAqB,CAAC;QAC7F,eAAe;QACf,8BAA8B;KAC/B,CAAC,CAAC;IAEH,MAAM,EAAE,aAAa,EAAE,GAAG,mBAAmB,CAAC;QAC5C,KAAK;QACL,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,gBAAgB;QAChB,iBAAiB;QACjB,uBAAuB;QACvB,qBAAqB;QACrB,iBAAiB;QACjB,eAAe;QACf,uBAAuB;QACvB,yBAAyB;KAC1B,CAAC,CAAC;IAEH,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAAC;QAC/D,SAAS;QACT,SAAS;QACT,WAAW;QACX,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,QAAQ;QACR,eAAe;QACf,0BAA0B;QAC1B,uBAAuB,EAAE,+BAA+B;KACzD,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,iBAAiB,CAAC;QAC9B,WAAW,EAAE,OAAO;QACpB,iBAAiB;QACjB,UAAU,EAAE,gBAAgB;QAC5B,aAAa;QACb,iBAAiB;QACjB,eAAe;KAChB,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,kBAAkB,CAAC;QACtC,WAAW,EAAE,OAAO;QACpB,SAAS;QACT,SAAS;QACT,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU,EAAE,gBAAgB;QAC5B,eAAe;QACf,yBAAyB;QACzB,0BAA0B;QAC1B,QAAQ;QACR,KAAK;KACN,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO;QACP,OAAO;QACP,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW;QACX,SAAS;QACT,SAAS;QACT,WAAW;QACX,UAAU;QACV,YAAY;QACZ,UAAU;QACV,IAAI;QACJ,KAAK;QACL,YAAY;QACZ,KAAK;QACL,aAAa;QACb,aAAa;QACb,eAAe;QACf,aAAa;QACb,YAAY;QACZ,WAAW;QACX,WAAW;QACX,gBAAgB;QAChB,gBAAgB;QAChB,eAAe,EAAE,CAAoB,SAAY,EAAE,EAAE,CACnD,uBAAuB,CAAC,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC;QACtD,eAAe,EAAE,CAAoB,SAAY,EAAE,EAAE,CACnD,uBAAuB,CAAC,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC;QACtD,aAAa;QACb,QAAQ;QACR,YAAY;QACZ,QAAQ;KACT,CAAC,CAAC;AACL,CAAC"}

package/dist/forms/validation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * packages/core/src/forms/validation.ts — Form validation utilities.
+ *
+ * Why: Provides validation execution for forms including synchronous validation,
+ * asynchronous validation with debouncing, and field-level validation helpers.
+ *
+ * @see docs/recipes/form-validation.md (GitHub issue #119)
+ */
+import type { ValidationResult } from "./types.js";
+/** Default debounce delay for async validation in milliseconds. */
+export declare const DEFAULT_ASYNC_DEBOUNCE_MS = 300;
+/**
+ * Execute synchronous validation on form values.
+ *
+ * @param values - Current form values
+ * @param validate - Sync validation function
+ * @returns Errors object with field keys and error messages
+ */
+export declare function runSyncValidation<T extends Record<string, unknown>>(values: T, validate: ((values: T) => ValidationResult<T>) | undefined): ValidationResult<T>;
+/**
+ * Execute field-level validation from a form validator.
+ *
+ * @param values - Current form values
+ * @param field - Field to validate
+ * @param validate - Full form validation function
+ * @returns Error message for the field, or undefined if valid
+ */
+export declare function runFieldValidation<T extends Record<string, unknown>>(values: T, field: keyof T, validate: ((values: T) => ValidationResult<T>) | undefined): ValidationResult<T>[keyof T] | undefined;
+/**
+ * Merge sync and async validation errors.
+ * Async errors take precedence over sync errors for the same field.
+ *
+ * @param syncErrors - Errors from sync validation
+ * @param asyncErrors - Errors from async validation
+ * @returns Merged errors object
+ */
+export declare function mergeValidationErrors<T extends Record<string, unknown>>(syncErrors: ValidationResult<T>, asyncErrors: ValidationResult<T>): ValidationResult<T>;
+/**
+ * Check if validation result has any errors.
+ *
+ * @param errors - Validation errors object
+ * @returns True if there are no errors
+ */
+export declare function isValidationClean<T extends Record<string, unknown>>(errors: ValidationResult<T>): boolean;
+/**
+ * Create a debounced async validation runner.
+ * Returns a function that delays validation execution and cancels pending calls.
+ *
+ * @param validateAsync - Async validation function
+ * @param debounceMs - Debounce delay in milliseconds
+ * @param onResult - Callback when validation completes
+ * @param onError - Optional callback when async validation throws; if omitted the error is swallowed and onResult receives an empty result
+ * @returns Object with run and cancel methods
+ */
+export declare function createDebouncedAsyncValidator<T extends Record<string, unknown>>(validateAsync: (values: T) => Promise<ValidationResult<T>>, debounceMs: number, onResult: (errors: ValidationResult<T>) => void, onError?: (error: unknown) => void): Readonly<{
+    run: (values: T) => void;
+    cancel: () => void;
+}>;
+/**
+ * Run async validation immediately (without debounce).
+ * Used during form submission.
+ *
+ * @param values - Current form values
+ * @param validateAsync - Async validation function
+ * @returns Promise resolving to errors object
+ */
+export declare function runAsyncValidation<T extends Record<string, unknown>>(values: T, validateAsync: ((values: T) => Promise<ValidationResult<T>>) | undefined): Promise<ValidationResult<T>>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/forms/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/forms/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GACzD,gBAAgB,CAAC,CAAC,CAAC,CAKrB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,MAAM,CAAC,EACd,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GACzD,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAM1C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC/B,gBAAgB,CAAC,CAAC,CAAC,CAErB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC1B,OAAO,CAmBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7E,aAAa,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC/C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,QAAQ,CAAC;IACV,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC,CA6CD;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,MAAM,EAAE,CAAC,EACT,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GACvE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAa9B"}

package/dist/forms/validation.js

@@ -0,0 +1,151 @@
+/**
+ * packages/core/src/forms/validation.ts — Form validation utilities.
+ *
+ * Why: Provides validation execution for forms including synchronous validation,
+ * asynchronous validation with debouncing, and field-level validation helpers.
+ *
+ * @see docs/recipes/form-validation.md (GitHub issue #119)
+ */
+/** Default debounce delay for async validation in milliseconds. */
+export const DEFAULT_ASYNC_DEBOUNCE_MS = 300;
+/**
+ * Execute synchronous validation on form values.
+ *
+ * @param values - Current form values
+ * @param validate - Sync validation function
+ * @returns Errors object with field keys and error messages
+ */
+export function runSyncValidation(values, validate) {
+    if (!validate) {
+        return {};
+    }
+    return validate(values);
+}
+/**
+ * Execute field-level validation from a form validator.
+ *
+ * @param values - Current form values
+ * @param field - Field to validate
+ * @param validate - Full form validation function
+ * @returns Error message for the field, or undefined if valid
+ */
+export function runFieldValidation(values, field, validate) {
+    if (!validate) {
+        return undefined;
+    }
+    const errors = validate(values);
+    return errors[field];
+}
+/**
+ * Merge sync and async validation errors.
+ * Async errors take precedence over sync errors for the same field.
+ *
+ * @param syncErrors - Errors from sync validation
+ * @param asyncErrors - Errors from async validation
+ * @returns Merged errors object
+ */
+export function mergeValidationErrors(syncErrors, asyncErrors) {
+    return { ...syncErrors, ...asyncErrors };
+}
+/**
+ * Check if validation result has any errors.
+ *
+ * @param errors - Validation errors object
+ * @returns True if there are no errors
+ */
+export function isValidationClean(errors) {
+    const keys = Object.keys(errors);
+    for (const key of keys) {
+        const value = errors[key];
+        if (value === undefined || value === "") {
+            continue;
+        }
+        if (typeof value === "string") {
+            return false;
+        }
+        for (const item of value) {
+            if (item !== undefined && item !== "") {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Create a debounced async validation runner.
+ * Returns a function that delays validation execution and cancels pending calls.
+ *
+ * @param validateAsync - Async validation function
+ * @param debounceMs - Debounce delay in milliseconds
+ * @param onResult - Callback when validation completes
+ * @param onError - Optional callback when async validation throws; if omitted the error is swallowed and onResult receives an empty result
+ * @returns Object with run and cancel methods
+ */
+export function createDebouncedAsyncValidator(validateAsync, debounceMs, onResult, onError) {
+    let timeoutId;
+    let cancelled = false;
+    // Monotonic token used to ignore stale debounced callbacks and in-flight promises.
+    let token = 0;
+    return Object.freeze({
+        run(values) {
+            // Cancel any pending validation
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            cancelled = false;
+            token++;
+            const myToken = token;
+            timeoutId = setTimeout(() => {
+                if (cancelled || myToken !== token)
+                    return;
+                validateAsync(values)
+                    .then((errors) => {
+                    if (!cancelled && myToken === token) {
+                        onResult(errors);
+                    }
+                })
+                    .catch((e) => {
+                    if (cancelled || myToken !== token)
+                        return;
+                    if (onError) {
+                        onError(e);
+                    }
+                    else {
+                        onResult({});
+                    }
+                });
+            }, debounceMs);
+        },
+        cancel() {
+            cancelled = true;
+            token++;
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+                timeoutId = undefined;
+            }
+        },
+    });
+}
+/**
+ * Run async validation immediately (without debounce).
+ * Used during form submission.
+ *
+ * @param values - Current form values
+ * @param validateAsync - Async validation function
+ * @returns Promise resolving to errors object
+ */
+export async function runAsyncValidation(values, validateAsync) {
+    if (!validateAsync) {
+        return {};
+    }
+    try {
+        return await validateAsync(values);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        const wrapped = new Error(`async form validation failed: ${detail}`);
+        wrapped.cause = e;
+        throw wrapped;
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/forms/validation.js.map

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

package/dist/icons/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * packages/core/src/icons/index.ts — Icon system exports.
+ */
+export { FILE_ICONS, STATUS_ICONS, ARROW_ICONS, GIT_ICONS, UI_ICONS, SPINNER_FRAMES, icons, resolveIcon, getIconChar, getSpinnerFrame, type IconDefinition, type IconCategory, type IconPath, type FileIconName, type StatusIconName, type ArrowIconName, type GitIconName, type UiIconName, type SpinnerVariant, } from "./registry.js";
+export { resolveIconGlyph, type ResolvedIconGlyph } from "./resolveGlyph.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/icons/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/icons/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAEL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,QAAQ,EACR,cAAc,EACd,KAAK,EAEL,WAAW,EACX,WAAW,EACX,eAAe,EAEf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/icons/index.js

@@ -0,0 +1,10 @@
+/**
+ * packages/core/src/icons/index.ts — Icon system exports.
+ */
+export { 
+// Icon definitions
+FILE_ICONS, STATUS_ICONS, ARROW_ICONS, GIT_ICONS, UI_ICONS, SPINNER_FRAMES, icons, 
+// Resolution
+resolveIcon, getIconChar, getSpinnerFrame, } from "./registry.js";
+export { resolveIconGlyph } from "./resolveGlyph.js";
+//# sourceMappingURL=index.js.map

package/dist/icons/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/icons/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO;AACL,mBAAmB;AACnB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,QAAQ,EACR,cAAc,EACd,KAAK;AACL,aAAa;AACb,WAAW,EACX,WAAW,EACX,eAAe,GAWhB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAA0B,MAAM,mBAAmB,CAAC"}