@4riders/reform 3.0.24

package/src/reform/useForm.ts

@@ -0,0 +1,246 @@
+import { useMemo } from "react"
+import { instance } from "../yop/decorators/instance"
+import { Path } from "../yop/ObjectsUtil"
+import { isPromise } from "../yop/TypesUtil"
+import { Group } from "../yop/ValidationContext"
+import { FormManager, InternalFormManager } from "./FormManager"
+import { useRender } from "./useRender"
+import { useObservers } from "./observers/useObservers"
+
+/**
+ * Configuration options for the useForm hook.
+ * @template T - The type of the form values.
+ * @category Form Management
+ */
+export type FormConfig<T extends object | any[] | null | undefined> = {
+
+    /**
+     * Initial values for the form. Can be an object, a function returning an object, or a function returning a promise that
+     * resolves to an object. Initial values are cloned and stored internally the first time they are neither `null` nor `undefined`.
+     * If a function is provided, it will be called on the first render and whenever the config changes, allowing for dynamic
+     * initial values. If the function returns a promise, the form will be in a pending state until the promise resolves, at
+     * which point the initial values will be set and the form will re-render.
+     * 
+     * @see {@link FormManager.initialValuesPending}
+     * @see {@link FormConfig.initialValuesConverter}
+     */
+    readonly initialValues?: T | (() => T) | (() => Promise<T>) | null
+
+    /**
+     * Converter function for initial values. This function is called with the initial values whenever they become neither
+     * `null` nor `undefined`. It allows for transformation or normalization of the initial values before they are set in the form.
+     * @param values - The initial values.
+     * @returns The transformed initial values.
+     */
+    readonly initialValuesConverter?: (values: T) => T
+
+    /**
+     * The validation schema for the form. This can be a schema object created with the `instance` or `array` decorator.
+     * It defines the rules for validating the form values.
+     * 
+     * Example usage:
+     * ```tsx
+     * const form = useForm({
+     *     initialValues: new Person(),
+     *     validationSchema: instance({ of: Person, required: true }),
+     * })
+     * ```
+     */
+    readonly validationSchema?: ((_: unknown, context: ClassFieldDecoratorContext<unknown, T>) => void)
+    
+    /**
+     * Path or paths to validate. This can be a single path string or an array of path strings. If specified, only the values
+     * at these paths will be validated. If not specified, the entire form values will be validated.
+     */
+    readonly validationPath?: string | string[]
+
+    /**
+     * Validation groups to use during validation. This can be a single group or an array of groups. If specified, the validation
+     * rules associated with these groups will be applied. If not specified, only the validation rules of the default group will
+     * be applied.
+     * 
+     * For example:
+     * ```tsx
+     * // will apply validation rules of "group1":
+     * validationGroups: "group1"
+     * // will apply validation rules of "group1" and "group2":
+     * validationGroups: ["group1", "group2"]
+     * // will apply validation rules of the default group and "group2":
+     * validationGroups: [undefined, "group2"]
+     * ```
+     */
+    readonly validationGroups?: Group
+
+    /**
+     * Function to determine if a path should be ignored during validation. This function is called with the path being
+     * validated and the form manager instance. If it returns `true`, the path will be ignored and no validation will be
+     * performed for it.
+     * @param path - The path being validated.
+     * @param form - The form manager instance.
+     * @returns `true` if the path should be ignored, `false` otherwise.
+     */
+    readonly ignore?: (path: Path, form: FormManager<T>) => boolean
+
+    /**
+     * Function to determine if the form can be submitted. This function is called with the form manager instance when a submit
+     * is attempted. If it returns `true`, the form will be submitted and the `onSubmit` callback will be called. If it returns
+     * `false`, the submit will be aborted and the `onSubmit` callback will not be called.
+     * @param form - The form manager instance.
+     * @returns `true` if the form can be submitted, `false` otherwise.
+     */
+    readonly submitGuard?: (form: FormManager<T>) => boolean
+
+    /**
+     * Callback for form submission. This function is called with the form manager instance when the form is submitted and the
+     * `submitGuard` (if provided) returns `true`. It is responsible for handling the form submission logic, such as sending
+     * the form values to a server or updating application state. The {@link FormManager.submitting} is automatically set to
+     * `true` while this function is called. It is the responsibility of the caller to set it back to `false` when the
+     * submission process is complete (see {@link FormManager.setSubmitting}).
+     * 
+     * Example usage:
+     * ```tsx
+     * const form = useForm({
+     *     initialValues: new Person(),
+     *     validationSchema: instance({ of: Person, required: true }),
+     *     onSubmit: (form) => {
+     *         console.log("Form submitted with values:", form.values)
+     *         try {
+     *             // perform submission logic here
+     *         }
+     *         finally {
+     *             form.setSubmitting(false)
+     *         }
+     *     }
+     * })
+     * ```
+     * @param form - The form manager instance.
+     * @returns void
+     */
+    readonly onSubmit?: (form: FormManager<T>) => void
+
+    /**
+     * Whether to dispatch events for observer propagation. If `true`, when a value changes, an event will be dispatched that can
+     * be listened to by observers to react to value changes. Default is `true`.
+     */
+    readonly dispatchEvent?: boolean
+}
+
+/**
+ * Type for a class constructor of a model.
+ * @category Form Management
+ */
+export type Model<T> = new (...args: any) => NonNullable<T>
+
+
+/**
+ * ## First overload signature
+ * 
+ * React hook to create and manage a form with all configuration options available in {@link FormConfig}. This overload allows for the most flexible
+ * usage of the `useForm` hook, with full control over initial values, validation schema, submission logic, and more.
+ * 
+ * However, it doesn't register automatically observers listeners, and you need to use the {@link useObservers} hook manually to register observers on
+ * the form manager instance, as shown in the example below.
+ *
+ * Example usage:
+ * ```tsx
+ * const form = useForm({
+ *     initialValues: new Person(),
+ *     validationSchema: instance({ of: Person, required: true }),
+ *     onSubmit: (form) => {
+ *         console.log("Form submitted with values:", form.values)   
+ *         form.setSubmitting(false)
+ *     }
+ * })
+ * // Optional, if observers are used in the form:
+ * useObservers(Person, form)
+ * ```
+ * @overload
+ * @template T - The type of the form values.
+ * @param config - The form configuration object.
+ * @param deps - Optional dependency list for memoization of the form manager.
+ * @returns The form manager instance.
+ * @category Form Management
+ */
+export function useForm<T extends object | null | undefined>(config: FormConfig<T>, deps?: React.DependencyList): FormManager<T>
+
+/**
+ * ## Second overload signature
+ * 
+ * React hook to create and manage a form with validation, and automatic observer support. This overload allows for a simpler syntax. The initial values
+ * will be created by instantiating the provided model class, and the validation schema will be automatically generated using the `instance` decorator with
+ * the provided model class and `required: true`.
+ *
+ * There is no need to use {@link useObservers} here, observers will be automatically registered on the form manager instance
+ * for the provided model class. The code example below is strictly equivalent to the one in the other overload signature,
+ * but with a simpler syntax.
+ * 
+ * Example usage:
+ * ```tsx
+ * const form = useForm(Person, (form) => {
+ *     console.log("Form submitted with values:", form.values)   
+ *     form.setSubmitting(false)
+ * })
+ * ```
+ * 
+ * @overload
+ * @template T - The type of the form values.
+ * @param model - The model class constructor.
+ * @param onSubmit - Callback for form submission.
+ * @param deps - Optional dependency list for memoization of the form manager.
+ * @returns The form manager instance.
+ * @category Form Management
+ */
+export function useForm<T extends object | null | undefined>(model: Model<T>, onSubmit: (form: FormManager<T>) => void, deps?: React.DependencyList): FormManager<T>
+
+/*
+ * Implementation of the useForm hook. Handles both config and model overloads, supports async initial values,
+ * and manages form state, validation, and observer eventing. See the overload signatures for usage details.
+ */
+export function useForm(configOrModel: any, onSubmitOrDeps?: any, deps: React.DependencyList = []) {
+
+    const model = typeof configOrModel === "function" ? configOrModel : undefined
+    const render = useRender()
+
+    deps = Array.isArray(onSubmitOrDeps) ? onSubmitOrDeps : deps
+    const manager = useMemo(() => {
+        const newManager = new InternalFormManager(render)
+        
+        if (typeof configOrModel === "function") {
+            configOrModel = {
+                initialValues: new configOrModel(),
+                validationSchema: instance({ of: configOrModel, required: true }),
+                onSubmit: onSubmitOrDeps as ((form: FormManager<any>) => void),
+            }
+        }
+        else if (typeof configOrModel.initialValues === "function") {
+            let initialValues = configOrModel.initialValues()
+            if (isPromise(initialValues)) {
+                newManager.initialValuesPending = true
+                initialValues.then((value: any) => {
+                    setTimeout(() => {
+                        configOrModel = { ...newManager.config, initialValues: value }
+                        newManager.onRender(configOrModel)
+                        newManager.commitInitialValues()
+                        newManager.initialValuesPending = false
+                        render()
+                    }, 0)
+                })
+                initialValues = newManager.initialValues
+            }
+            configOrModel = { ...configOrModel, initialValues }
+        }
+        
+        newManager.onRender(configOrModel)
+        return newManager
+    }, deps)
+
+    // We need this code to normalize configOrModel when useMemo doesn't re-run.
+    if (typeof configOrModel === "function")
+        configOrModel = { ...manager.config, onSubmit: onSubmitOrDeps as ((form: FormManager<any>) => void) }
+    else if (typeof configOrModel.initialValues === "function")
+        configOrModel = { ...configOrModel, initialValues: manager.initialValues }
+
+    manager.onRender(configOrModel)
+    useObservers(model, manager)
+    return manager
+}

package/src/reform/useFormContext.tsx

@@ -0,0 +1,37 @@
+import React from "react"
+import { FormManager } from "./FormManager"
+import { Form } from "./Form"
+
+/**
+ * React context for providing a FormManager instance to descendant components.
+ * @ignore
+ */
+export const FormContext = React.createContext<FormManager<unknown> | null>(null)
+
+/**
+ * React hook to access the current {@link FormManager} from context. This hook should be used within a component that is a descendant of a {@link Form} component,
+ * which provides the FormManager via context. The generic type parameter `T` can be used to specify the type of the form values managed by the FormManager,
+ * allowing for type-safe access to form values.
+ * 
+ * Example usage:
+ * ```tsx
+ * function MyFormComponent() {
+ *     const form = useFormContext<MyFormValues>()
+ *     // use form to access values, statuses, etc.
+ * }
+ * 
+ * const form = useForm(MyFormModel, onSubmit)
+ * return (
+ *     <Form form={form} autoComplete="off" noValidate disabled={form.submitting}>
+ *        <MyFormComponent />
+ *     </Form>
+ * )
+ * ```
+ * 
+ * @template T - The type of the form values managed by the FormManager.
+ * @returns The {@link FormManager} instance from context.
+ * @category Form Management
+ */
+export function useFormContext<T = unknown>() {
+    return React.useContext(FormContext)! as FormManager<T>
+}

package/src/reform/useFormField.ts

@@ -0,0 +1,75 @@
+import { useRef } from "react";
+import { isPromise } from "../yop/TypesUtil";
+import { ValidationStatus } from "../yop/ValidationContext";
+import { ResolvedConstraints } from "../yop/Yop";
+import { FormManager } from "./FormManager";
+import { useFormContext } from "./useFormContext";
+import { useRender } from "./useRender";
+
+/**
+ * Represents the state of a form field, including value, validation, and metadata.
+ * @template Value - The type of the field value.
+ * @template MinMax - The type for min/max constraints.
+ * @template Root - The type of the root form values.
+ * @category Form Management
+ */
+export type FieldState<Value, MinMax, Root = any> = {
+    /** The current value of the field. */
+    value: Value | undefined
+    /** Whether the field has been touched. */
+    touched: boolean
+    /** The validation status of the field, if any. See {@link ValidationStatus} for details. */
+    status?: ValidationStatus
+    /** The form manager instance. See {@link FormManager} for details. */
+    form: FormManager<Root>
+    /** Function to trigger a re-render of the component that called {@link useFormField} to get this field state. */
+    render: () => void
+    /** The resolved constraints for the field, if any. See {@link ResolvedConstraints} for details. */
+    constraints?: ResolvedConstraints<MinMax>
+}
+
+/**
+ * React hook to access and manage the state of a form field, including value, validation status, and constraints.
+ * Handles async validation and triggers re-renders as needed.
+ * 
+ * Example usage:
+ * ```tsx
+ * function MyTextField(props: { path: string }) {
+ *     const { constraints, status, value, form } = useFormField<string, number>(props.path)
+ *     // render input with value, display validation status, etc.
+ * }
+ * ```
+ *
+ * @template Value - The type of the field value.
+ * @template MinMax - The type for min/max constraints.
+ * @template Root - The type of the root form values.
+ * @param name - The field name or path.
+ * @param unsafeMetadata - Whether to use unsafe metadata for constraints.
+ * @returns The current state of the field. See {@link FieldState} for details.
+ * @category Form Management
+ */
+export function useFormField<Value, MinMax, Root = any>(name: string, unsafeMetadata = false): FieldState<Value, MinMax, Root> {
+    const render = useRender()
+    const form = useFormContext<Root>()
+    const promiseRef = useRef<Promise<unknown>>(undefined)
+
+    const status = form.statuses.get(name)
+    if (status?.level === "pending" && isPromise(status.constraint) && promiseRef.current !== status.constraint) {
+        promiseRef.current = status.constraint
+        status.constraint.finally(() => {
+            if (promiseRef.current === status.constraint) {
+                form.updateAsyncStatus(name)
+                form.render()
+            }
+        })
+    }
+
+    return {
+        value: form.getValue<Value>(name),
+        touched: form.isTouched(name),
+        status,
+        form,
+        render,
+        constraints: form.constraintsAt(name, unsafeMetadata),
+    }
+}

package/src/reform/useRender.ts

@@ -0,0 +1,12 @@
+import { useReducer } from "react"
+
+/**
+ * React hook that returns a function to force a component re-render.
+ * Useful for triggering updates in custom hooks or non-stateful logic.
+ *
+ * @returns A function that, when called, forces the component to re-render.
+ * @category Form Management
+ */
+export function useRender(): () => void {
+    return useReducer(() => ({}), {})[1] as () => void
+}

package/src/yop/MessageProvider.ts

@@ -0,0 +1,204 @@
+import { ConstraintMessage } from "./constraints/Constraint";
+import { InternalValidationContext, Level, ValidationContext } from "./ValidationContext";
+
+/**
+ * Interface for providing localized validation messages.
+ * @category Localization
+ */
+export interface MessageProvider {
+    /**
+     * The locale identifier (e.g., 'en-US', 'fr-FR').
+     */
+    readonly locale: string
+
+    /**
+     * Returns a localized message for a given validation context and code.
+     * @param context - The validation context.
+     * @param code - The message code.
+     * @param constraint - The constraint value.
+     * @param message - An optional custom message.
+     * @param level - The validation level (e.g., 'error', 'pending').
+     * @returns The resolved message.
+     */
+    getMessage(context: InternalValidationContext<unknown>, code: string, constraint: any, message: ConstraintMessage | undefined, level: Level): ConstraintMessage
+}
+
+/**
+ * Formats a value for display in a localized message, handling numbers, dates, and arrays.
+ * @param value - The value to format.
+ * @param numberFormat - The number formatter.
+ * @param dateFormat - The date formatter.
+ * @param listFormat - The list formatter.
+ * @returns The formatted string.
+ * @ignore
+ */
+function format(value: any, numberFormat: Intl.NumberFormat, dateFormat: Intl.DateTimeFormat, listFormat: Intl.ListFormat): string {
+    return (
+        typeof value === "number" ? numberFormat.format(value) :
+        value instanceof Date ? dateFormat.format(value) :
+        Array.isArray(value) ? listFormat.format(value.map(item => format(item, numberFormat, dateFormat, listFormat))) :
+        String(value)
+    )
+}
+
+/**
+ * Properties passed to a message function for formatting.
+ * @category Localization
+ */
+export type MessageProps = {
+    context: ValidationContext<unknown>
+    code: string
+    constraint: {
+        raw: any
+        formatted: string
+        plural?: Intl.LDMLPluralRule
+    }
+    level: Level
+}
+
+/**
+ * Function type for generating a message from message properties.
+ * @see {@link MessageProps}
+ * @category Localization
+ */
+export type MessageFunction = (props: MessageProps) => string
+
+/**
+ * Basic implementation of MessageProvider for localized validation messages.
+ * @category Localization
+ */
+export class BasicMessageProvider implements MessageProvider {
+
+    private readonly numberFormat: Intl.NumberFormat
+    private readonly dateFormat: Intl.DateTimeFormat
+    private readonly listFormat: Intl.ListFormat
+    private readonly pluralRules: Intl.PluralRules
+
+    /**
+     * Map of message codes to message functions.
+     */
+    readonly messages: Map<string, MessageFunction>
+
+    /**
+     * Creates a new BasicMessageProvider for a given locale and message entries.
+     * @param locale - The locale identifier.
+     * @param entries - Optional array of [code, message function] pairs.
+     */
+    constructor(readonly locale: string, entries?: (readonly [string, MessageFunction])[]) {
+        this.numberFormat = new Intl.NumberFormat(this.locale)
+        this.dateFormat = new Intl.DateTimeFormat(this.locale)
+        this.listFormat = new Intl.ListFormat(this.locale, { type: "disjunction" })
+        this.pluralRules = new Intl.PluralRules(this.locale)
+
+        this.messages = new Map<string, MessageFunction>(entries)
+    }
+
+    /**
+     * @inheritdoc
+     */
+    getMessage(context: InternalValidationContext<unknown>, code: string, constraint: any, message: ConstraintMessage | undefined, level: Level): ConstraintMessage {
+        if (message != null)
+            return message
+
+        const messageFunction = this.messages.get(`${ context.kind }.${ code }`) ?? this.messages.get(code)
+        if (messageFunction == null)
+            return `Unexpected error: ${ context.kind }.${ code }`
+
+        return messageFunction({
+            context,
+            code,
+            constraint: {
+                raw: constraint,
+                formatted: format(constraint, this.numberFormat, this.dateFormat, this.listFormat),
+                plural: typeof constraint === "number" ? this.pluralRules.select(constraint) : undefined
+            },
+            level
+        })
+    }
+}
+
+/**
+ * Returns the plural suffix 's' if the plural rule is not 'one'.
+ * @param plural - The plural rule.
+ * @returns 's' if plural, otherwise an empty string.
+ * @ignore
+ */
+function s(plural?: Intl.LDMLPluralRule): string {
+    return plural == null || plural === "one" ? "" : "s"
+}
+
+/**
+ * English (US) message provider for validation messages.
+ * @category Localization
+ */
+export const messageProvider_en_US = new BasicMessageProvider("en-US", [
+    ["string.min", ({ constraint }) => `Minimum ${ constraint.formatted } character${ s(constraint.plural) }`],
+    ["string.max", ({ constraint }) => `Maximum ${ constraint.formatted } character${ s(constraint.plural) }`],
+    ["string.match", () => "Invalid format"],
+
+    ["email.min", ({ constraint }) => `Minimum ${ constraint.formatted } character${ s(constraint.plural) }`],
+    ["email.max", ({ constraint }) => `Maximum ${ constraint.formatted } character${ s(constraint.plural) }`],
+    ["email.match", () => "Invalid email format"],
+
+    ["time.min", ({ constraint }) => `Must be after or equal to ${ constraint.formatted }`],
+    ["time.max", ({ constraint }) => `Must be before or equal to ${ constraint.formatted }`],
+    ["time.match", () => "Invalid time format"],
+
+    ["number.min", ({ constraint }) => `Must be greater or equal to ${ constraint.formatted }`],
+    ["number.max", ({ constraint }) => `Must be less or equal to ${ constraint.formatted }`],
+
+    ["date.min", ({ constraint }) => `Date must be greater or equal to ${ constraint.formatted }`],
+    ["date.max", ({ constraint }) => `Date must be less or equal to ${ constraint.formatted }`],
+
+    ["file.min", ({ constraint }) => `File must have a size of at least ${ constraint.formatted } byte${ s(constraint.plural) }`],
+    ["file.max", ({ constraint }) => `File must have a size of at most ${ constraint.formatted } byte${ s(constraint.plural) }`],
+
+    ["array.min", ({ constraint }) => `At least ${ constraint.formatted } element${ s(constraint.plural) }`],
+    ["array.max", ({ constraint }) => `At most ${ constraint.formatted } element${ s(constraint.plural) }`],
+
+    ["type", ({ constraint }) => `Wrong value type (expected ${ constraint.raw })`],
+    ["test", ({ level }) => level === "pending" ? "Pending..." : level === "error" ? "Invalid value" : ""],
+    ["oneOf", ({ constraint }) => `Must be one of: ${ constraint.formatted }`],
+    ["exists", () => "Required field"],
+    ["defined", () => "Required field"],
+    ["notnull", () => "Required field"],
+    ["required", () => "Required field"]
+])
+
+/**
+ * French (FR) message provider for validation messages.
+ * @category Localization
+ */
+export const messageProvider_fr_FR = new BasicMessageProvider("fr-FR", [
+    ["string.min", ({ constraint }) => `Minimum ${ constraint.formatted } caractère${ s(constraint.plural) }`],
+    ["string.max", ({ constraint }) => `Maximum ${ constraint.formatted } caractère${ s(constraint.plural) }`],
+    ["string.match", () => "Format incorrect"],
+
+    ["email.min", ({ constraint }) => `Minimum ${ constraint.formatted } caractère${ s(constraint.plural) }`],
+    ["email.max", ({ constraint }) => `Maximum ${ constraint.formatted } caractère${ s(constraint.plural) }`],
+    ["email.match", () => "Format d'email incorrect"],
+
+    ["time.min", ({ constraint }) => `Doit être antérieur ou égal à ${ constraint.formatted }`],
+    ["time.max", ({ constraint }) => `Doit être postérieur ou égal à ${ constraint.formatted }`],
+    ["time.match", () => "Format horaire incorrect"],
+
+    ["number.min", ({ constraint }) => `Doit être supérieur ou égal à ${ constraint.formatted }`],
+    ["number.max", ({ constraint }) => `Doit être inférieur ou égal à ${ constraint.formatted }`],
+
+    ["date.min", ({ constraint }) => `La date doit être postérieure ou égale au ${ constraint.formatted }`],
+    ["date.max", ({ constraint }) => `La date doit être antérieure ou égale au ${ constraint.formatted }`],
+
+    ["file.min", ({ constraint }) => `Le fichier doit avoir une taille d'au moins ${ constraint.formatted } octet${ s(constraint.plural) }`],
+    ["file.max", ({ constraint }) => `Le fichier doit avoir une taille d'au plus ${ constraint.formatted } octet${ s(constraint.plural) }`],
+
+    ["array.min", ({ constraint }) => `Au moins  ${ constraint.formatted } élément${ s(constraint.plural) }`],
+    ["array.max", ({ constraint }) => `Au plus ${ constraint.formatted } élément${ s(constraint.plural) }`],
+
+    ["type", ({ constraint }) => `Valeur du mauvais type (${ constraint.raw } attendu)`],
+    ["test", ({ level }) => level === "pending" ? "En cours..." : level === "error" ? "Valeur incorrecte" : ""],
+    ["oneOf", ({ constraint }) => `Doit être parmi : ${ constraint.formatted }`],
+    ["exists", () => "Champ obligatoire"],
+    ["defined", () => "Champ obligatoire"],
+    ["notnull", () => "Champ obligatoire"],
+    ["required", () => "Champ obligatoire"]
+])