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

package/helpers.d.ts

@@ -1,8 +1,8 @@
-import { type FieldProps } from '@conform-to/dom';
+import { type FieldConfig, type Primitive } from '@conform-to/dom';
 import { type InputHTMLAttributes, type SelectHTMLAttributes, type TextareaHTMLAttributes } from 'react';
-export declare function input<Type extends string | number | Date | boolean | undefined>(props: FieldProps<Type>, { type, value }?: {
+export declare function input<Schema extends Primitive>(config: FieldConfig<Schema>, { type, value }?: {
     type?: string;
     value?: string;
 }): InputHTMLAttributes<HTMLInputElement>;
-export declare function select<T extends any>(props: FieldProps<T>): SelectHTMLAttributes<HTMLSelectElement>;
-export declare function textarea<T extends string | undefined>(props: FieldProps<T>): TextareaHTMLAttributes<HTMLTextAreaElement>;
+export declare function select<Schema extends Primitive | Array<Primitive>>(config: FieldConfig<Schema>): SelectHTMLAttributes<HTMLSelectElement>;
+export declare function textarea<Schema extends Primitive>(config: FieldConfig<Schema>): TextareaHTMLAttributes<HTMLTextAreaElement>;

package/helpers.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-function input(props) {
+function input(config) {
   var {
     type,
     value
@@ -10,50 +10,48 @@ function input(props) {
   var isCheckboxOrRadio = type === 'checkbox' || type === 'radio';
   var attributes = {
     type,
-    name: props.name,
-    form: props.form,
-    required: props.required,
-    minLength: props.minLength,
-    maxLength: props.maxLength,
-    min: props.min,
-    max: props.max,
-    step: props.step,
-    pattern: props.pattern,
-    multiple: props.multiple
+    name: config.name,
+    form: config.form,
+    required: config.required,
+    minLength: config.minLength,
+    maxLength: config.maxLength,
+    min: config.min,
+    max: config.max,
+    step: config.step,
+    pattern: config.pattern,
+    multiple: config.multiple
   };
 
   if (isCheckboxOrRadio) {
     attributes.value = value !== null && value !== void 0 ? value : 'on';
-    attributes.defaultChecked = props.defaultValue === attributes.value;
+    attributes.defaultChecked = config.defaultValue === attributes.value;
   } else {
-    var _props$defaultValue;
-
-    attributes.defaultValue = "".concat((_props$defaultValue = props.defaultValue) !== null && _props$defaultValue !== void 0 ? _props$defaultValue : '');
+    attributes.defaultValue = config.defaultValue;
   }
 
   return attributes;
 }
-function select(props) {
-  var _props$defaultValue2;
+function select(config) {
+  var _config$defaultValue;
 
   return {
-    name: props.name,
-    form: props.form,
-    defaultValue: props.multiple ? Array.isArray(props.defaultValue) ? props.defaultValue : [] : "".concat((_props$defaultValue2 = props.defaultValue) !== null && _props$defaultValue2 !== void 0 ? _props$defaultValue2 : ''),
-    required: props.required,
-    multiple: props.multiple
+    name: config.name,
+    form: config.form,
+    defaultValue: config.multiple ? Array.isArray(config.defaultValue) ? config.defaultValue : [] : "".concat((_config$defaultValue = config.defaultValue) !== null && _config$defaultValue !== void 0 ? _config$defaultValue : ''),
+    required: config.required,
+    multiple: config.multiple
   };
 }
-function textarea(props) {
-  var _props$defaultValue3;
+function textarea(config) {
+  var _config$defaultValue2;
 
   return {
-    name: props.name,
-    form: props.form,
-    defaultValue: "".concat((_props$defaultValue3 = props.defaultValue) !== null && _props$defaultValue3 !== void 0 ? _props$defaultValue3 : ''),
-    required: props.required,
-    minLength: props.minLength,
-    maxLength: props.maxLength
+    name: config.name,
+    form: config.form,
+    defaultValue: "".concat((_config$defaultValue2 = config.defaultValue) !== null && _config$defaultValue2 !== void 0 ? _config$defaultValue2 : ''),
+    required: config.required,
+    minLength: config.minLength,
+    maxLength: config.maxLength
   };
 }
 

package/hooks.d.ts

@@ -1,64 +1,143 @@
-import { type FieldProps, type Schema, type FieldsetData } from '@conform-to/dom';
-import { type ButtonHTMLAttributes, type FormEventHandler, type FormHTMLAttributes, type RefObject, type ReactElement } from 'react';
+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;
+}
+/**
+ * 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;
 }
-export declare function useForm({ onReset, onSubmit, noValidate, fallbackNative, initialReport, }?: FormConfig): FormProps;
-export declare type FieldsetConfig<Type> = Partial<Pick<FieldProps<Type>, 'name' | 'form' | 'defaultValue' | 'error'>>;
-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>;
-    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]-?: FieldProps<Type[Key]>;
-}];
-interface FieldListControl<T> {
-    prepend(defaultValue?: FieldsetData<T, string>): ButtonHTMLAttributes<HTMLButtonElement>;
-    append(defaultValue?: FieldsetData<T, string>): ButtonHTMLAttributes<HTMLButtonElement>;
-    replace(index: number, defaultValue: FieldsetData<T, string>): ButtonHTMLAttributes<HTMLButtonElement>;
-    remove(index: number): ButtonHTMLAttributes<HTMLButtonElement>;
-    reorder(fromIndex: number, toIndex: 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<Payload>(props: FieldProps<Array<Payload>>): [
+/**
+ * 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;
-        props: FieldProps<Payload>;
+        config: FieldConfig<Payload>;
     }>,
-    FieldListControl<Payload>
+    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: FieldProps<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 {};