@conform-to/react 0.1.0 → 0.3.0-pre.0

package/hooks.d.ts

@@ -1,64 +1,143 @@
-import { type FieldConfig, type Schema } from '@conform-to/dom';
-import { type ButtonHTMLAttributes, type FormEventHandler, type FormHTMLAttributes, type RefObject, type ReactElement } from 'react';
-interface FormConfig {
+import { type FieldConfig, type FieldError, type FieldValue, type FieldElement, type FieldsetConstraint, type ListCommand, type Primitive } from '@conform-to/dom';
+import { type InputHTMLAttributes, type FormEvent, type RefObject } from 'react';
+export interface FormConfig {
     /**
-     * Decide when the error should be reported initially.
-     * Default to `onSubmit`
+     * Define when the error should be reported initially.
+     * Support "onSubmit", "onChange", "onBlur".
+     *
+     * Default to `onSubmit`.
      */
     initialReport?: 'onSubmit' | 'onChange' | 'onBlur';
     /**
-     * Native browser report will be used before hydation if it is set to `true`.
-     * Default to `false`
+     * Enable native validation before hydation.
+     *
+     * Default to `false`.
      */
     fallbackNative?: boolean;
     /**
-     * The form could be submitted even if there is invalid input control if it is set to `true`.
-     * Default to `false`
+     * Accept form submission regardless of the form validity.
+     *
+     * Default to `false`.
      */
     noValidate?: boolean;
     /**
-     * The submit handler will be triggered only when the form is valid.
-     * Or when noValidate is set to `true`
+     * A function to be called when the form should be (re)validated.
      */
-    onSubmit?: FormHTMLAttributes<HTMLFormElement>['onSubmit'];
-    onReset?: FormHTMLAttributes<HTMLFormElement>['onReset'];
+    validate?: (form: HTMLFormElement, submitter?: HTMLInputElement | HTMLButtonElement | null) => void;
+    /**
+     * The submit event handler of the form. It will be called
+     * only when the form is considered valid.
+     */
+    onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
 }
+/**
+ * Properties to be applied to the form element
+ */
 interface FormProps {
     ref: RefObject<HTMLFormElement>;
-    onSubmit: Required<FormHTMLAttributes<HTMLFormElement>>['onSubmit'];
-    onReset: Required<FormHTMLAttributes<HTMLFormElement>>['onReset'];
-    noValidate: Required<FormHTMLAttributes<HTMLFormElement>>['noValidate'];
+    onSubmit: (event: FormEvent<HTMLFormElement>) => void;
+    noValidate: boolean;
 }
-export declare function useForm({ onReset, onSubmit, noValidate, fallbackNative, initialReport, }?: FormConfig): FormProps;
-interface FieldsetConfig<Type> extends Partial<FieldConfig<Type>> {
+/**
+ * Returns properties required to hook into form events.
+ * Applied custom validation and define when error should be reported.
+ *
+ * @see https://github.com/edmundhung/conform/tree/v0.3.0-pre.0/packages/conform-react/README.md#useform
+ */
+export declare function useForm(config?: FormConfig): FormProps;
+/**
+ * All the information of the field, including state and config.
+ */
+export declare type Field<Schema> = {
+    config: FieldConfig<Schema>;
+    error?: string;
+};
+/**
+ * A set of field information.
+ */
+export declare type Fieldset<Schema extends Record<string, any>> = {
+    [Key in keyof Schema]-?: Field<Schema[Key]>;
+};
+export interface FieldsetConfig<Schema extends Record<string, any>> {
+    /**
+     * The prefix used to generate the name of nested fields.
+     */
+    name?: string;
+    /**
+     * An object representing the initial value of the fieldset.
+     */
+    defaultValue?: FieldValue<Schema>;
+    /**
+     * An object describing the initial error of each field
+     */
+    initialError?: FieldError<Schema>['details'];
+    /**
+     * An object describing the constraint of each field
+     */
+    constraint?: FieldsetConstraint<Schema>;
+    /**
+     * The id of the form, connecting each field to a form remotely.
+     */
+    form?: string;
 }
-interface FieldsetProps {
-    ref: RefObject<HTMLFieldSetElement>;
+/**
+ * Returns all the information about the fieldset.
+ *
+ * @see https://github.com/edmundhung/conform/tree/v0.3.0-pre.0/packages/conform-react/README.md#usefieldset
+ */
+export declare function useFieldset<Schema extends Record<string, any>>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config?: FieldsetConfig<Schema>): Fieldset<Schema>;
+export declare function useFieldset<Schema extends Record<string, any>>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config?: FieldConfig<Schema>): Fieldset<Schema>;
+interface ControlButtonProps {
     name?: string;
+    value?: string;
     form?: string;
-    onInput: FormEventHandler<HTMLFieldSetElement>;
-    onReset: FormEventHandler<HTMLFieldSetElement>;
-    onInvalid: FormEventHandler<HTMLFieldSetElement>;
+    formNoValidate: true;
 }
-export declare function useFieldset<Type extends Record<string, any>>(schema: Schema<Type>, config?: FieldsetConfig<Type>): [FieldsetProps, {
-    [Key in keyof Type]-?: FieldConfig<Type[Key]>;
-}];
-interface FieldListControl {
-    prepend(): ButtonHTMLAttributes<HTMLButtonElement>;
-    append(): ButtonHTMLAttributes<HTMLButtonElement>;
-    remove(index: number): ButtonHTMLAttributes<HTMLButtonElement>;
+declare type CommandPayload<Schema, Type extends ListCommand<FieldValue<Schema>>['type']> = Extract<ListCommand<FieldValue<Schema>>, {
+    type: Type;
+}>['payload'];
+/**
+ * A group of helpers for configuring a list control button
+ */
+interface ListControl<Schema> {
+    prepend(payload?: CommandPayload<Schema, 'prepend'>): ControlButtonProps;
+    append(payload?: CommandPayload<Schema, 'append'>): ControlButtonProps;
+    replace(payload: CommandPayload<Schema, 'replace'>): ControlButtonProps;
+    remove(payload: CommandPayload<Schema, 'remove'>): ControlButtonProps;
+    reorder(payload: CommandPayload<Schema, 'reorder'>): ControlButtonProps;
 }
-export declare function useFieldList<Type extends Array<any>>(config: FieldConfig<Type>): [
+/**
+ * Returns a list of key and config, with a group of helpers
+ * configuring buttons for list manipulation
+ *
+ * @see https://github.com/edmundhung/conform/tree/v0.3.0-pre.0/packages/conform-react/README.md#usefieldlist
+ */
+export declare function useFieldList<Payload = any>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config: FieldConfig<Array<Payload>>): [
     Array<{
         key: string;
-        config: FieldConfig<Type extends Array<infer InnerType> ? InnerType : never>;
+        config: FieldConfig<Payload>;
     }>,
-    FieldListControl
+    ListControl<Payload>
 ];
+interface ShadowInputProps extends InputHTMLAttributes<HTMLInputElement> {
+    ref: RefObject<HTMLInputElement>;
+}
 interface InputControl {
     value: string;
-    onChange: (value: string) => void;
+    onChange: (eventOrValue: {
+        target: {
+            value: string;
+        };
+    } | string) => void;
     onBlur: () => void;
+    onInvalid: (event: FormEvent<FieldElement>) => void;
 }
-export declare function useControlledInput<T extends string | number | Date | undefined>(field: FieldConfig<T>): [ReactElement, InputControl];
+/**
+ * Returns the properties required to configure a shadow input for validation.
+ * This is particular useful when integrating dropdown and datepicker whichs
+ * introduces custom input mode.
+ *
+ * @see https://github.com/edmundhung/conform/tree/v0.3.0-pre.0/packages/conform-react/README.md#usecontrolledinput
+ */
+export declare function useControlledInput<Schema extends Primitive = Primitive>(field: FieldConfig<Schema>): [ShadowInputProps, InputControl];
 export {};