@4riders/reform 3.0.24

package/src/reform/components/BaseRadioField.tsx

@@ -0,0 +1,72 @@
+import React, { InputHTMLAttributes, useRef } from "react"
+import { InputAttributes, ReformEvents } from "./InputHTMLProps"
+import { useFormField } from "../.."
+
+/**
+ * @ignore
+ */
+export type BaseRadioFieldHTMLAttributes = Omit<InputAttributes<'radio'>,
+    'accept' |
+    'alt' |
+    'autocomplete' |
+    'capture' |
+    'dirname' |
+    'height' |
+    'list' |
+    'max' |
+    'maxLength' |
+    'min' |
+    'minLength' |
+    'multiple' |
+    'placeholder' |
+    'readOnly' |
+    'size' |
+    'src' |
+    'step' |
+    'type' |
+    'width'
+>
+
+/**
+ * @category Base Inputs Components
+ */
+export type BaseRadioFieldProps<V> = BaseRadioFieldHTMLAttributes & ReformEvents<V> & {
+    modelValue: V
+    render: () => void
+}
+
+/**
+ * A base radio field component that can be used to create custom radio input components connected to the form state.
+ * @category Base Inputs Components
+ */
+export function BaseRadioField<V = any>(props: BaseRadioFieldProps<V>) {
+    const { onChange, onBlur, modelValue, render, ...inputProps } = props
+    const { value: fieldValue, form } = useFormField<V | null, number>(props.name)
+
+    const inputRef = useRef<HTMLInputElement>(null)
+
+    const internalOnChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+        if (event.currentTarget.checked && modelValue !== fieldValue) {
+            form.setValue(props.name, modelValue, true)
+            onChange?.(modelValue, form)
+        }
+    }
+
+    // If this is the first render or if this input isn't currently edited
+    if (inputRef.current == null || inputRef.current !== document.activeElement) {
+        const value = fieldValue === modelValue
+        if (inputRef.current)
+            inputRef.current.checked = value
+        else
+            (inputProps as InputHTMLAttributes<HTMLInputElement>).defaultChecked = value
+    }
+
+    return (
+        <input
+            { ...inputProps }
+            type="radio"
+            ref={ inputRef }
+            onChange={ internalOnChange }
+        />
+    )
+}

package/src/reform/components/BaseSelectField.tsx

@@ -0,0 +1,103 @@
+import React, { DOMAttributes, SelectHTMLAttributes, useRef } from "react"
+import { ReformEvents } from "./InputHTMLProps"
+import { useFormField } from "../useFormField"
+
+/**
+ * @ignore
+ */
+export type BaseSelectFieldHTMLAttributes = (
+    Omit<SelectHTMLAttributes<HTMLSelectElement>,
+        // HTMLAttributes
+        'name' |
+
+        'value' |
+
+        'defaultValue' |
+        'defaultChecked' |
+        'suppressContentEditableWarning' |
+        'suppressHydrationWarning' |
+
+        'contentEditable' |
+        'contextMenu' |
+        'hidden' |
+        'is' |
+
+        // SelectHTMLAttributes
+        'autoComplete' |
+        'form' |        
+        'multiple' |
+
+        keyof DOMAttributes<HTMLSelectElement>
+    > &
+    {
+        name: string
+    }
+)
+
+/**
+ * @category Base Inputs Components
+ */
+export type BaseSelectFieldProps<V> = BaseSelectFieldHTMLAttributes & ReformEvents<V> & {
+    modelValues: V[]
+    toOptionValue: (modelValue: V) => string
+    toOptionContent: (modelValue: V) => string
+    toModelValue: (optionValue: string) => V
+    render: () => void
+}
+
+/**
+ * A base select field component that can be used to create custom select input components connected to the form state.
+ * 
+ * To use it with with a basic { value, label } pair, you can use the following props:
+ * ```tsx
+ * <BaseSelectField
+ *     name="mySelectId"
+ *     modelValues={[ null, "1", "2" ]}
+ *     toOptionValue={ modelValue => modelValue ?? "" }
+ *     toOptionContent={ modelValue => modelValue == null ? "Select..." : `Option ${modelValue}` }
+ *     toModelValue={ optionValue => optionValue === "" ? null : optionValue }
+ *     render={ myRenderFunction } />
+ * ```
+ * @category Base Inputs Components
+ */
+export function BaseSelectField<Value = string>(props: BaseSelectFieldProps<Value | null>) {
+
+    const { onChange, onBlur, toModelValue, render, modelValues, toOptionValue, toOptionContent, ...selectProps } = props
+    const { value: fieldValue, form } = useFormField<Value | null, number>(props.name)
+
+    const selectRef = useRef<HTMLSelectElement>(null)
+
+    const internalOnChange = (event: React.ChangeEvent<HTMLSelectElement>) => {
+        const value = toModelValue(event.currentTarget.value)
+        if (value !== fieldValue) {
+            form.setValue(props.name, value, true)
+            onChange?.(value, form)
+        }
+    }
+
+    // If this is the first render or if this select isn't currently edited
+    if (selectRef.current == null || selectRef.current !== document.activeElement) {
+        const value = toOptionValue(fieldValue ?? null)
+        if (selectRef.current != null)
+            selectRef.current.value = value
+        else
+            (selectProps as SelectHTMLAttributes<HTMLSelectElement>).defaultValue = value
+    }
+
+    return (
+        <select
+            { ...selectProps }
+            ref={ selectRef }
+            onChange={ internalOnChange }
+        >
+            { modelValues.map(modelValue => {
+                const optionValue = toOptionValue(modelValue)
+                return (
+                    <option key={ optionValue } value={ optionValue }>
+                        { toOptionContent(modelValue)}
+                    </option>
+                )
+            })}
+        </select>
+    )
+}

package/src/reform/components/BaseTextAreaField.tsx

@@ -0,0 +1,87 @@
+import React, { DOMAttributes, TextareaHTMLAttributes, useRef } from "react"
+import { useFormField } from "../useFormField"
+import { ReformEvents } from "./InputHTMLProps"
+
+/**
+ * @ignore
+ */
+export type BaseTextAreaFieldHTMLAttributes = (
+    Omit<TextareaHTMLAttributes<HTMLTextAreaElement>,
+        // HTMLAttributes
+        'name' |
+
+        'value' |
+
+        'defaultValue' |
+        'defaultChecked' |
+        'suppressContentEditableWarning' |
+        'suppressHydrationWarning' |
+
+        'contentEditable' |
+        'contextMenu' |
+        'hidden' |
+        'is' |
+
+        // TextareaHTMLAttributes
+        'autoComplete' |
+        'dirName' |
+        'form' |        
+
+        keyof DOMAttributes<HTMLTextAreaElement>
+    > &
+    {
+        name: string
+    }
+)
+
+/**
+ * @category Base Inputs Components
+ */
+export type BaseTextAreaFieldProps = BaseTextAreaFieldHTMLAttributes & ReformEvents<string> & {
+    render: () => void
+}
+
+/**
+ * A base text area component that can be used to create custom text area input components connected to the form state.
+ * @category Base Inputs Components
+ */
+export function BaseTextAreaField(props: BaseTextAreaFieldProps) {
+
+    const { render, onChange, onBlur, ...textAreaProps } = props
+    const { value: fieldValue, form } = useFormField<string | null, number>(props.name)
+
+    const textAreaRef = useRef<HTMLTextAreaElement>(null)
+
+    const internalOnChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+        const value = event.currentTarget.value || null
+        if (value !== fieldValue) {
+            form.setValue(props.name, value)
+            form.validateAt(props.name) && render()
+            onChange?.(value, form)
+        }
+    }
+
+    const internalOnBlur = (event: React.FocusEvent<HTMLTextAreaElement>) => {
+        const value = event.currentTarget.value || null
+        form.setValue(props.name, value, true)
+        onBlur?.(value, form)
+    }
+
+    // If this is the first render or if this textarea isn't currently edited
+    if (textAreaRef.current == null || textAreaRef.current !== document.activeElement) {
+        const value = fieldValue ?? ""
+        if (textAreaRef.current != null)
+            textAreaRef.current.value = value
+        else
+            (textAreaProps as TextareaHTMLAttributes<HTMLTextAreaElement>).defaultValue = value
+    }
+
+    return (
+        <textarea
+            { ...textAreaProps }
+            ref={ textAreaRef }
+            onChange={ internalOnChange }
+            onBlur={ internalOnBlur }
+        />
+    )
+}

package/src/reform/components/BaseTextField.tsx

@@ -0,0 +1,135 @@
+import React, { InputHTMLAttributes, useRef } from "react"
+import { InputAttributes, ReformEvents } from "./InputHTMLProps"
+import { useFormField } from "../useFormField"
+
+/**
+ * @ignore
+ */
+export interface InputSelection {
+    start: number | null
+    end: number | null
+    direction?: "forward" | "backward" | "none"
+}
+
+/**
+ * @ignore
+ */
+export type BaseTextFieldHTMLAttributes = Omit<InputAttributes<"text" | "search" | "number" | "date" | "email" | "password" | "tel" | "time">,
+    'accept' |
+    'alt' |
+    'capture' |
+    'height' |
+    'multiple' |
+    'src' |
+    'step' |
+    'width'
+>
+
+/**
+ * @category Base Inputs Components
+ */
+export type BaseTextFieldProps<V> = BaseTextFieldHTMLAttributes & ReformEvents<V> & {
+    toModelValue?: (value: string) => V | null
+    toTextValue?: (value: V | null) => string
+    acceptInputValue?: (value: string) => boolean
+    formatDisplayedValue?: (value: string) => string
+    formatOnEdit?: boolean
+    render: () => void
+}
+
+/**
+ * A base text field component that can be used to create custom text input components connected to the form state. It handles change and blur events,
+ * converts between the input value and the model value using the provided `toModelValue` and `toTextValue` functions, and calls the provided `render`
+ * function to update the form state when the value changes. It also supports an `acceptInputValue` function to validate the input value on each change
+ * and a `formatDisplayedValue` function to format the displayed value while editing.
+ * @category Base Inputs Components
+ */
+export function BaseTextField<Value = string>(props: BaseTextFieldProps<Value>) {
+
+    const { onChange, onBlur, toModelValue, toTextValue, acceptInputValue, formatDisplayedValue, formatOnEdit, render, ...inputProps } = props
+    const { value: fieldValue, form } = useFormField<Value | null, number>(props.name)
+
+    const inputRef = useRef<HTMLInputElement>(null)
+    const previousInputValue = useRef('')
+    const previousInputSelection = useRef<InputSelection>({ start: null, end: null })
+
+    const getInputValue = (event: React.SyntheticEvent<HTMLInputElement>) => {
+        const value = event.currentTarget.value.replace(/\0/g, '')
+        if (toModelValue)
+            return toModelValue(value)
+        return value === '' ? null : value as Value
+    }
+
+    const internalOnSelect = (event: React.FormEvent<HTMLInputElement>) => {
+        const target = event.currentTarget
+        
+        previousInputSelection.current = {
+            start: target.selectionStart,
+            end: target.selectionEnd,
+            direction: target.selectionDirection ?? undefined
+        }
+        
+        // format displayed value when cursor is moved at the end of typed text
+        if (formatOnEdit  !== false && formatDisplayedValue && target.selectionStart === target.value.length) {
+            const formattedValue = formatDisplayedValue(target.value)
+            if (target.value !== formattedValue)
+                target.value = formattedValue
+        }
+    }
+
+    const internalOnInput = (event: React.FormEvent<HTMLInputElement>) => {
+        const target = event.currentTarget
+        
+        // Discard changes if it doesn't conform to acceptInputValue (could also be handled by a beforeInput event)
+        if (acceptInputValue?.(target.value) === false) {
+            target.value = previousInputValue.current
+            const selection = previousInputSelection.current!
+            target.setSelectionRange(selection.start, selection.end, selection.direction)
+        }
+        // format displayed value when cursor is at the end of typed text
+        else if (formatOnEdit !== false && formatDisplayedValue && target.selectionStart === target.value.length) {
+            const formattedValue = formatDisplayedValue(target.value)
+            if (target.value !== formattedValue)
+                target.value = formattedValue
+        }
+    }
+
+    const internalOnChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+        previousInputValue.current = event.currentTarget.value
+        const value = getInputValue(event)
+        if (value !== fieldValue) {
+            form.setValue(props.name, value)
+            if (form.validateAt(props.name).changed)
+                render()
+            onChange?.(value, form)
+        }
+    }
+
+    const internalOnBlur = (event: React.FocusEvent<HTMLInputElement>) => {
+        const value = getInputValue(event)
+        form.setValue(props.name, value, true)
+        onBlur?.(value, form)
+    }
+
+    // If this is the first render or if this input isn't currently edited
+    if (inputRef.current == null || inputRef.current !== document.activeElement) {
+        const convertedValue = toTextValue?.(fieldValue ?? null) ?? String(fieldValue ?? '')
+        const value = formatDisplayedValue?.(convertedValue) ?? convertedValue
+        if (inputRef.current)
+            inputRef.current.value = value
+        else
+            (inputProps as InputHTMLAttributes<HTMLInputElement>).defaultValue = value
+        previousInputValue.current = value
+    }
+
+    return (
+        <input
+            { ...inputProps }
+            ref={ inputRef }
+            onSelect={ internalOnSelect }
+            onInput={ internalOnInput }
+            onChange={ internalOnChange }
+            onBlur={ internalOnBlur }
+        />
+    )
+}

package/src/reform/components/InputHTMLProps.tsx

@@ -0,0 +1,89 @@
+import { DOMAttributes, InputHTMLAttributes } from "react"
+import { FormManager } from "../FormManager";
+
+/**
+ * The HTMLInputTypeAttribute type is a union of string literals that represent the valid values for the "type" attribute of an HTML input element
+ * It includes common input types such as "text", "password", "email", etc., as well as a catch-all for any other string value that may be used as a
+ * custom input type. This allows for flexibility while still providing type safety for known input types.
+ * @ignore
+ */
+type HTMLInputTypeAttribute =
+        | 'button'
+        | 'checkbox'
+        | 'color'
+        | 'date'
+        | 'datetime-local'
+        | 'email'
+        | 'file'
+        | 'hidden'
+        | 'image'
+        | 'month'
+        | 'number'
+        | 'password'
+        | 'radio'
+        | 'range'
+        | 'reset'
+        | 'search'
+        | 'submit'
+        | 'tel'
+        | 'text'
+        | 'time'
+        | 'url'
+        | 'week'
+        | (string & {});
+
+/**
+ * The InputAttributes type is a utility type that takes an InputType parameter, which extends the HTMLInputTypeAttribute type. It uses the Omit utility
+ * type to exclude certain properties from the InputHTMLAttributes type, such as 'name', 'type', 'value', 'checked', and others that are not relevant
+ * for the input component. It then adds back the 'name' property as a required string and the 'type' property as an optional InputType. This allows for
+ * creating a more specific set of attributes for input components while still maintaining flexibility for different input types.
+ * @ignore
+ */
+export type InputAttributes<InputType extends HTMLInputTypeAttribute> = (
+    Omit<InputHTMLAttributes<HTMLInputElement>,
+        // HTMLAttributes
+        'name' |
+        'type' |
+
+        'value' |
+        'checked' |
+
+        'defaultValue' |
+        'defaultChecked' |
+        'suppressContentEditableWarning' |
+        'suppressHydrationWarning' |
+
+        'contentEditable' |
+        'contextMenu' |
+        'hidden' |
+        'is' |
+
+        // InputHTMLAttributes
+        'alt' |
+        'form' |
+        'formaction' |
+        'formenctype' |
+        'formmethod' |
+        'formnovalidate' |
+        'formtarget' |
+        'pattern' |
+        'src' |
+        keyof DOMAttributes<HTMLInputElement>
+    > &
+    {
+        name: string
+        type?: InputType
+    }
+)
+
+/**
+ * The ReformEvents type is a generic type that takes two parameters: Value, which represents the type of the value being handled, and Root,
+ * which extends object and represents the type of the form's root state. It defines two optional event handler properties: onChange and onBlur.
+ * Both handlers receive the current value (which can be of type Value or null) and an instance of FormManager that manages the form's state.
+ * This allows for handling changes and blur events in a way that is integrated with the form management system.
+ * @category Base Inputs Components
+ */
+export type ReformEvents<Value, Root extends object = any> = {
+    onChange?: (value: Value | null, form: FormManager<Root>) => void
+    onBlur?: (value: Value | null, form: FormManager<Root>) => void
+}

package/src/reform/observers/observer.ts

@@ -0,0 +1,131 @@
+/**
+ * Defines types and a decorator for observers in the Reform form management system. 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 and
+ * relative paths.
+ */
+import { useObservers } from "./useObservers"
+import { InternalCommonConstraints } from "../../yop/constraints/CommonConstraints"
+import { fieldDecorator } from "../../yop/Metadata"
+import { Path } from "../../yop/ObjectsUtil"
+import { ReformSetValueEvent } from "../FormManager"
+import { FormConfig } from "../useForm"
+
+/**
+ * Options for observer callback behavior.
+ * @category Observers
+ */
+export type ObserverCallbackOptions = {
+
+    /** If `true`, marks the field as untouched. */
+    untouch?: boolean
+    /** If `true`, propagates the value change to other observers. Defaults to `false` to prevent potential infinite loops*/
+    propagate?: boolean
+}
+
+/**
+ * Context object passed to observer callbacks.
+ *
+ * @template T - The type of the field value where the observer is attached.
+ * @category Observers
+ */
+export type ObserverCallbackContext<T> = {
+    
+    /** The absolute path of the field value where the observer is attached */
+    path: Path
+    /** The value being observed. */
+    observedValue: unknown
+    /** The current value of the field where the observer is attached. */
+    currentValue: T
+    /** Sets the value of the field where the observer is attached. */
+    setValue: (value: T, options?: ObserverCallbackOptions) => void
+    /** The event object providing context. See {@link ReformSetValueEvent}. */
+    event: ReformSetValueEvent<unknown>
+}
+
+/**
+ * Observer callback function type.
+ *
+ * @template T - The type of the field value where the observer is attached.
+ * @param context - The context for the observer callback. See {@link ObserverCallbackContext}.
+ * @category Observers
+ */
+export type ObserverCallback<T> = (context: ObserverCallbackContext<T>) => void
+
+/**
+ * Metadata for an observer, including its path and callback.
+ *
+ * @template T - The type of the field value where the observer is attached.
+ * @ignore
+ */
+export type ObserverMetadata<T> = {
+
+    /** The path of the field being observed. */
+    path: string
+    /** The observer callback function. */
+    callback: ObserverCallback<T>
+}
+
+/**
+ * Map of observer metadata, keyed by observed path.
+ * @ignore
+ */
+export type Observers = Map<string, ObserverMetadata<any>>
+
+/**
+ * Field metadata type that can hold observers in addition to common constraints.
+ * @ignore
+ */
+export type ObserversField = InternalCommonConstraints & { observers?: Observers }
+
+/**
+ * Decorator to register or remove an observer callback for a field. Observer paths use a syntax similar to Unix file paths,
+ * supporting wildcards and array indices, and are relative to the parent object of the field where the observer is attached.
+ * Paths can also be absolute (starting with a slash `/`) to observe fields from the root, or use `..` to observe fields from
+ * higher up in the object tree.
+ * 
+ * Observers are only triggered if {@link FormConfig.dispatchEvent} isn't set to `false` and if the class holding `observers`
+ * decorators is bound to the current form using {@link useObservers}.
+ *
+ * Examples:
+ * - `name` observes the `name` field of the parent object.
+ * - `user/name` observes the `name` field of the sibling `user` object.
+ * - `items[*]/price` observes the `price` field of all items in the sibling `items` array.
+ * - `orders[0]/status` observes the `status` field of the first order in the sibling `orders` array.
+ * - `/name` observes the `name` field at the root level.
+ * - `../name` observes the `name` field in the parent of the parent object.
+ *
+ * Example usage:
+ * ```tsx
+ * class MyFormModel {
+ * 
+ *    age: number | null = null
+ * 
+ *    ＠observer("age", (context) => context.setValue(
+ *          context.observedValue != null ? (context.observedValue as number) >= 18 : null,
+ *          { untouch: true }
+ *    ))
+ *    adult: boolean | null = null
+ * }
+ * 
+ * const form = useForm(MyFormModel, ...)
+ * 
+ * ```
+ *
+ * @template Value - The type of the field value where the observer is attached.
+ * @template Parent - The parent type containing the field.
+ * @param path - The path to observe.
+ * @param callback - The observer callback function, or undefined to remove it.
+ * @returns A field decorator function.
+ * @category Observers
+ */
+export function observer<Value, Parent>(path: string, callback: ObserverCallback<Value> | undefined) {
+    return fieldDecorator<Parent, Value>(field => {
+        const metadata = field as ObserversField
+        metadata.observers ??= new Map()
+        if (callback != null)
+            metadata.observers.set(path, { path, callback })
+        else
+            metadata.observers.delete(path)
+    })
+}