@4riders/reform 3.0.24

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@4riders/reform",
+  "version": "3.0.24",
+  "description": "Reform is a powerful, type-safe, and extensible validation and form management library for TypeScript and React",
+  "type": "module",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://github.com/4riders/reform#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/4riders/reform.git"
+  },
+  "bugs": {
+    "url": "https://github.com/4riders/reform/issues"
+  },
+  "keywords": [
+    "react",
+    "form",
+    "typescript"
+  ],
+  "author": "Franck Wolff <franck.wolff@4riders.net>",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc && vite build",
+    "test": "vitest --run",
+    "prepublishOnly": "NODE_ENV=release tsc && vite build",
+    "typedoc": "typedoc --options typedoc.json"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@babel/plugin-proposal-decorators": "^7.29.0",
+    "@rolldown/plugin-babel": "^0.2.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^25.5.0",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^6.0.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "jsdom": "^29.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typedoc": "^0.28.18",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.2"
+  },
+  "packageManager": "yarn@4.13.0"
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * @packageDocumentation
+ * 
+ * @categoryDescription Property Decorators
+ * Property decorators are a powerful feature in Javascript that allow you to annotate and modify the behavior of class properties.
+ * In the context of form management, property decorators can be used to define metadata for form fields, such as validation rules,
+ * input types, or custom behavior. By applying decorators to your form model classes, you can easily specify how each field should
+ * be handled without having to write additional boilerplate code. This makes it easier to maintain and extend your form models as your
+ * application grows.
+ * 
+ * @categoryDescription Class Decorators
+ * Class decorators are a type of decorator in JavaScript that can be applied to classes to modify their behavior or add metadata.
+ * In the context of form management, class decorators can be used to define metadata for form models, such as validation rules.
+ * 
+ * @categoryDescription Shared Constraints
+ * Shared constraints are common validation rules that can be applied to form fields or entire form models. They define the conditions
+ * that the field values must satisfy in order to be considered valid. Constraints can be simple, such as checking if a value is required
+ * or if it falls within a certain range, or they can be complex, involving custom logic that depends on multiple fields.
+ * 
+ * @categoryDescription Observers
+ * Observers allow you to react to changes in other fields by specifying a path to observe and a callback function that
+ * receives context about the change. The observer paths support a flexible syntax for targeting specific fields, including
+ * wildcards, absolute and relative paths.
+ * 
+ * @categoryDescription Form Management
+ * Form management involves handling the state and behavior of forms in a web application. This includes managing form data, validation,
+ * and user interactions. A form management library can provide tools and utilities to simplify these tasks, allowing developers to
+ * focus on building the user interface and business logic of their applications.
+ * 
+ * @categoryDescription Base Inputs Components
+ * Base input components are reusable building blocks for creating form fields in a web application. They provide a consistent interface and
+ * behavior for common input types, such as text fields, checkboxes, radio buttons, and select dropdowns.
+ * 
+ * @categoryDescription Validation Management
+ * Validation management involves defining and enforcing rules for validating form data. This can include simple checks, such as ensuring
+ * that a field is not empty, as well as more complex rules that involve multiple fields or custom logic.
+ * 
+ * @categoryDescription Localization
+ * Localization is the process of adapting a product or content to a specific locale or market. In the context of form management, localization
+ * involves providing translations for error messages.
+ * 
+ * @categoryDescription Utilities
+ * Utilities are helper functions or classes that provide common functionality that can be reused across different parts of an application. In the
+ * context of form management, utilities include functions for manipulating and comparing form data.
+ */
+
+export * from "./reform/ArrayHelper"
+export * from "./reform/Form"
+export * from "./reform/FormManager"
+export * from "./reform/observers/observer"
+export * from "./reform/observers/useObservers"
+export * from "./reform/Reform"
+export * from "./reform/useForm"
+export * from "./reform/useFormContext"
+export * from "./reform/useFormField"
+export * from "./reform/useRender"
+
+export * from "./reform/components/BaseCheckboxField"
+export * from "./reform/components/BaseDateField"
+export * from "./reform/components/BaseRadioField"
+export * from "./reform/components/BaseSelectField"
+export * from "./reform/components/BaseTextAreaField"
+export * from "./reform/components/BaseTextField"
+export * from "./reform/components/InputHTMLProps"
+
+export * from "./yop/constraints/CommonConstraints"
+export * from "./yop/constraints/Constraint"
+export * from "./yop/constraints/MinMaxConstraints"
+export * from "./yop/constraints/OneOfConstraint"
+export * from "./yop/constraints/TestConstraint"
+
+export * from "./yop/decorators/array"
+export * from "./yop/decorators/boolean"
+export * from "./yop/decorators/date"
+export * from "./yop/decorators/email"
+export * from "./yop/decorators/file"
+export * from "./yop/decorators/id"
+export * from "./yop/decorators/ignored"
+export * from "./yop/decorators/instance"
+export * from "./yop/decorators/number"
+export * from "./yop/decorators/string"
+export * from "./yop/decorators/test"
+export * from "./yop/decorators/time"
+
+export * from "./yop/MessageProvider"
+export * from "./yop/Metadata"
+export * from "./yop/ObjectsUtil"
+export * from "./yop/TypesUtil"
+export * from "./yop/ValidationContext"
+export * from "./yop/Yop"

package/src/reform/ArrayHelper.ts

@@ -0,0 +1,164 @@
+import { Path } from "../yop/ObjectsUtil"
+import { FormManager, InternalFormManager } from "./FormManager"
+
+/**
+ * Utility class for manipulating array fields in a form model, with automatic touch, validation, and rendering. See {@link FormManager.array} for details.
+ * @template T - The type of array elements.
+ * @category Form Management
+ */
+export class ArrayHelper<T = any> {
+
+    private array: T[] | undefined
+
+    /**
+     * Creates an ArrayHelper for a given form and path.
+     * @param form - The form manager instance.
+     * @param path - The path to the array field in the form.
+     */
+    constructor(readonly form: InternalFormManager<any>, readonly path: string | Path) {
+        this.array = form.getValue<T[]>(path)
+        if (!Array.isArray(this.array))
+            this.array = undefined
+    }
+
+    /**
+     * Tells if the field at the given path was an array.
+     * @returns True if the field was an array, false otherwise.
+     */
+    isArray() {
+        return this.array != null
+    }
+
+    /**
+     * Appends an element to the array.
+     * @param element - The element to append.
+     * @param commit - Whether to validate and render after the operation (default: true).
+     */
+    append(element: T, commit = true) {
+        this.array!.push(element)
+        this.form.touch(this.path)
+        this.commit(commit)
+    }
+
+    /**
+     * Replaces the element at the given index.
+     * @param index - The index to replace.
+     * @param element - The new element.
+     * @param commit - Whether to validate and render after the operation (default: true).
+     */
+    replace(index: number, element: T, commit = true) {
+        this.array![index] = element
+        const touched = this.form.getTouchedValue<any[]>(this.path)
+        if (touched == null)
+            this.form.touch(this.path)
+        else if (Array.isArray(touched))
+            touched[index] = undefined
+        this.commit(commit)
+    }
+
+    /**
+     * Inserts an element at the given index.
+     * @param index - The index to insert at.
+     * @param element - The element to insert.
+     * @param commit - Whether to validate and render after the operation (default: true).
+     */
+    insert(index: number, element: T, commit = true) {
+        this.array!.splice(index, 0, element)
+        const touched = this.form.getTouchedValue<any[]>(this.path)
+        if (touched == null)
+            this.form.touch(this.path)
+        else if (Array.isArray(touched))
+            touched.splice(index, 0, undefined)
+        this.commit(commit)
+    }
+
+    /**
+     * Removes the element at the given index.
+     * @param index - The index to remove.
+     * @param commit - Whether to validate and render after the operation (default: true).
+     */
+    remove(index: number, commit = true) {
+        this.array!.splice(index, 1)
+        const touched = this.form.getTouchedValue<any[]>(this.path)
+        if (touched == null)
+            this.form.touch(this.path)
+        else if (Array.isArray(touched))
+            touched.splice(index, 1)
+        this.commit(commit)
+    }
+
+    /**
+     * Swaps two elements in the array.
+     * @param index1 - The first index.
+     * @param index2 - The second index.
+     * @param commit - Whether to validate and render after the operation (default: true).
+     */
+    swap(index1: number, index2: number, commit = true) {
+        const action = <T>(array: T[]) => {
+            const value1 = array[index1]
+            array[index1] = array[index2]
+            array[index2] = value1
+        }
+
+        action(this.array!)
+        const touched = this.form.getTouchedValue<any[]>(this.path)
+        if (touched == null)
+            this.form.touch(this.path)
+        else if (Array.isArray(touched))
+            action(touched)
+        this.commit(commit)
+    }
+
+    /**
+     * Moves an element from one index to another.
+     * @param from - The source index.
+     * @param to - The destination index.
+     * @param commit - Whether to validate and render after the operation (default: true).
+     */
+    move(from: number, to: number, commit = true) {
+        if (from !== to) {
+            const action = from < to ?
+                <T>(array: T[]) => {
+                    const fromElement = array[from]
+                    for (let i = from; i < to; i++)
+                        array[i] = array[i + 1]
+                    array[to] = fromElement
+                } :
+                <T>(array: T[]) => {
+                    const toElement = array[to]
+                    for (let i = to; i > from; i--)
+                        array[i + 1] = array[i]
+                    array[from] = toElement
+                }
+            
+            action(this.array!)
+            const touched = this.form.getTouchedValue<any[]>(this.path)
+            if (touched == null)
+                this.form.touch(this.path)
+            else if (Array.isArray(touched))
+                action(touched)
+            this.commit(commit)
+        }
+    }
+
+    /**
+     * Removes all elements from the array.
+     * @param commit - Whether to validate and render after the operation (default: true).
+     */
+    clear(commit = true) {
+        this.array!.splice(0, this.array!.length)
+        this.form.setTouchedValue(this.path, true)
+        this.commit(commit)
+    }
+
+    /**
+     * Validates and renders the form if value is true.
+     * @param value - Whether to commit (validate and render).
+     */
+    private commit(value: boolean) {
+        if (value) {
+            this.form.validate()
+            this.form.render()
+        }
+    }
+}

package/src/reform/Form.tsx

@@ -0,0 +1,81 @@
+import { FormHTMLAttributes, useCallback } from "react"
+import { FormContext } from "./useFormContext"
+import React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { FormManager, InternalFormManager } from "./FormManager"
+import { ValidationStatus } from "../yop/ValidationContext"
+import { Reform } from "./Reform"
+
+/**
+ * Props for the Form component.
+ * @property form - The form manager instance.
+ * @property disabled - Whether the form is disabled.
+ * @category Form Management
+ */
+export interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> {
+
+    /** The form manager instance. */
+    form: FormManager<unknown>
+    /** Whether the form is disabled. */
+    disabled?: boolean
+}
+
+/**
+ * React component for rendering an HTML form with context, error display, and automatic form disabling. All children of
+ * this component will have access to the form manager via context, and they will be enclosed in an HTML `fieldset` that is disabled according to the
+ * `disabled` prop. If there are any validation errors, and if the debug option `displayFormErrors` is enabled (see {@link Reform.displayFormErrors}),
+ * they will be displayed in a formatted block below the form.
+ * 
+ * Example usage:
+ * ```tsx
+ * const form = useForm(MyFormModel, onSubmit)
+ * return (
+ *     <Form form={form} autoComplete="off" noValidate disabled={form.submitting}>
+ *        // form fields here, using form context
+ *        <button type="submit">Submit</button>
+ *     </Form>
+ * )
+ * ```
+ * 
+ * @param props - The Form props.
+ * @returns The rendered Form component.
+ * @category Form Management
+ */
+export function Form(props: FormProps) {
+    const { form, children, disabled, ...formAttrs } = props
+    
+    const formRef = useCallback((htmlForm: HTMLFormElement) => {
+        (form as InternalFormManager<any>).htmlForm = htmlForm
+    }, [form])
+
+    const errors = new Map<string, ValidationStatus>([...form.statuses].filter(([_, status]) => status.level === "error"))
+
+    return (
+        <FormContext.Provider value={ form }>
+            <form ref={ formRef } onSubmit={ (e) => form.submit(e) } { ...formAttrs }>
+                <fieldset disabled={ disabled }>{ children }</fieldset>
+                
+                { errors.size > 0 && Reform.displayFormErrors &&
+                <div style={{
+                    all: "initial",
+                    display: "block",
+                    marginTop: "1em",
+                    padding: "1em",
+                    fontFamily: "monospace",
+                    border: "2px solid firebrick",
+                    borderInline: "2px solid firebrick",
+                    color: "firebrick",
+                    background: "white",
+                    whiteSpace: "pre-wrap"
+                }}>
+                    { JSON.stringify(
+                        Object.fromEntries(errors.entries()),
+                        (key, value) => key === "message" && React.isValidElement(value) ? renderToStaticMarkup(value) : value,
+                        4
+                    )}
+                </div>
+                }
+            </form>
+        </FormContext.Provider>
+    )
+}