@conform-to/react 0.1.1 → 0.2.0

package/README.md

@@ -1,21 +1,475 @@
 # @conform-to/react
 
-> View adapter for [react](https://github.com/facebook/react), built on top of `@conform-to/dom`
+> [React](https://github.com/facebook/react) adapter for [conform](https://github.com/edmundhung/conform)
 
 ## API Reference
 
-- [conform](#conform)
-- [useControlledInput](#useControlledInput)
 - [useForm](#useForm)
 - [useFieldset](#useFieldset)
 - [useFieldList](#useFieldList)
+- [useControlledInput](#useControlledInput)
+- [conform](#conform)
 
-### conform
-
-### useControlledInput
+---
 
 ### useForm
 
+By default, the browser calls [reportValidity()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reportValidity) on the form element when you submit the form. This checks the validity of all the fields in it and reports if there are errors through the bubbles.
+
+This hook enhances this behaviour by allowing the developers to decide the best timing to start reporting errors using the `initialReport` option. This could start as earliest as the user typing or as late as the user submit the form.
+
+But, setting `initialReport` to `onSubmit` still works different from the native browser behaviour, which basically calls `reportValidity()` only at the time a submit event is received. The `useForm` hook introduces a **touched** state to each fields. It will eagerly report the validity of the field once it is touched. Any errors reported later will be updated as soon as new errors are found.
+
+Feel free to **SKIP** this if the native browser behaviour fullfills your need.
+
+```tsx
+import { useForm } from '@conform-to/react';
+
+function RandomForm() {
+  const formProps = useForm({
+    /**
+     * Decide when the error should be reported initially.
+     * The options are `onSubmit`, `onBlur` or `onChange`.
+     * Default to `onSubmit`
+     */
+    initialReport: 'onBlur',
+
+    /**
+     * Native browser report will be enabled before hydation
+     * if this is set to `true`. Default to `false`.
+     */
+    fallbackNative: true,
+
+    /**
+     * The form could be submitted regardless of the validity
+     * of the form if this is set to `true`. Default to
+     * `false`.
+     */
+    noValidate: false,
+
+    /**
+     * Form submit handler
+     *
+     * It will NOT be called if
+     * (1) one of the fields is invalid, and
+     * (2) noValidate is set to false
+     */
+    onSubmit(e) {
+      // ...
+    },
+
+    /**
+     * Form reset handler
+     */
+    onReset(e) {
+      // ...
+    },
+  });
+
+  return <form {...formProps}>{/* ... */}</form>;
+}
+```
+
+<details>
+<summary>What is `formProps`?</summary>
+
+It is a group of properties required to setup the form. They can also be set explicitly as shown below:
+
+```tsx
+<form
+  ref={formProps.ref}
+  onSubmit={formProps.onSubmit}
+  onReset={formProps.onReset}
+  noValidate={formProps.noValidate}
+>
+  {/* ... */}
+</form>
+```
+
+</details>
+
+---
+
 ### useFieldset
 
+This hook prepares all the config you need to setup the fieldset based on the provided schema.
+
+```tsx
+import { useFieldset } from '@conform-to/react';
+
+/**
+ * Schema of the fieldset
+ *
+ * Defining a schema manually could be error-prone. It
+ * is strongly recommended to use a schema validation
+ * library with a schema resolver.
+ *
+ * Currently only Zod is supported and Yup support is
+ * coming soon. Please check the corresponding package
+ * for the setup required
+ */
+const schema = /*
+  Assuming this to be a schema for book and it looks like this:
+
+  type Book = {
+    name: string;
+    isbn: string;
+  }
+
+*/
+
+function BookFieldset() {
+  const [
+    fieldsetProps,
+    /**
+     * The variables `name` and `isbn` are FieldProps objects
+     * They are used to configure the field (input, select, textarea)
+     *
+     * Please check the docs of the `conform` helpers for how to
+     * use them together
+     */
+    {
+      name,
+      isbn,
+    },
+  ] = useFieldset(schema, {
+    /**
+     * Name of the fieldset
+     * Required only for nested fieldset.
+     */
+    name: 'book',
+
+    /**
+     * Id of the form
+     * Required only if the fieldset is placed out of the form
+     */
+    form: 'random-form-id',
+
+    /**
+     * Default value of the fieldset
+     */
+    defaultValue: {
+      isbn: '0340013818',
+    },
+
+    /**
+     * Error reported by the server
+     */
+    error: {
+      isbn: 'Invalid ISBN',
+    },
+  });
+
+  const {
+    /**
+     * This would be `book.isbn` instead of `isbn`
+     * if the `name` option is provided
+     */
+    name,
+
+    /**
+     * This would be `random-form-id`
+     * because of the `form` option provided
+     */
+    form,
+
+    /**
+     * This would be `0340013818` if specified
+     * on the `initalValue` option
+     */
+    defaultValue,
+
+    /**
+     * Current error message
+     * This would be 'Invalid ISBN' initially if specified
+     * on the `error` option
+     */
+    error,
+
+    /**
+     * Constraint of the field (required, minLength etc)
+     *
+     * For example, the constraint of the isbn field could be:
+     * {
+     *   required: true,
+     *   pattern: '[0-9]{10,13}'
+     * }
+     */
+    ...constraint,
+  } = isbn;
+
+  return (
+    <fieldset {...fieldsetProps}>
+      {/* ... */}
+    </fieldset>)
+  );
+}
+```
+
+<details>
+  <summary>What is `fieldsetProps`?</summary>
+
+It is a group of properties required to setup the fieldset. They can also be set explicitly as shown below:
+
+```tsx
+<fieldset
+  ref={fieldsetProps.ref}
+  name={fieldsetProps.name}
+  form={fieldsetProps.form}
+  onInput={fieldsetProps.onInput}
+  onInvalid={fieldsetProps.onInvalid}
+>
+  {/* ... */}
+</fieldset>
+```
+
+</details>
+
+<details>
+<summary>How is a schema looks like?</summary>
+
+```tsx
+import type { Schema } from '@conform-to/react';
+
+/**
+ * Defining a schema manually
+ */
+const bookSchema: Schema<{
+  name: string;
+  isbn: string;
+  quantity?: number;
+}> = {
+  /**
+   * Define the fields with its constraint together
+   */
+  fields: {
+    name: {
+      required: true,
+    },
+    isbn: {
+      required: true,
+      minLength: 10,
+      maxLength: 13,
+      pattern: '[0-9]{10,13}',
+    },
+    quantity: {
+      min: '0',
+    },
+  },
+
+  /**
+   * Customise validation behaviour
+   * Fallbacks to native browser validation if not specified
+   */
+  validate(fieldset) {
+    /**
+     * Lookup the field elements using the fieldset element
+     */
+    const [name] = getFieldElements(fieldset, 'name');
+
+    if (name.validity.valueMissing) {
+      /**
+       * Setting error message based on validity
+       */
+      name.setCustomValidity('Required');
+    } else if (name.value === 'something') {
+      /**
+       * Setting error message based on custom constraint
+       */
+      name.setCustomValidity('Please enter a valid name');
+    } else {
+      /**
+       * Clearing the error message (Important!)
+       */
+      name.setCustomValidity('');
+    }
+  },
+};
+```
+
+</details>
+
+---
+
 ### useFieldList
+
+This hook is used in combination with `useFieldset` to handle array structure:
+
+```tsx
+import { useFieldset, useFieldList } from '@conform-to/react';
+
+/**
+ * Consider the schema as follow:
+ *
+ * type Collection = {
+ *   books: Array<{ name: string; isbn: string; }>
+ * }
+ */
+
+function CollectionForm() {
+  const [fieldsetProps, { books }] = useFieldset(collectionSchema);
+  const [bookList, control] = useFieldList(books);
+
+  return (
+    <fieldset {...fieldsetProps}>
+      {bookList.map((book, index) => (
+        <div key={book.key}>
+          {/* `book.props` is a FieldProps object similar to `books` */}
+          <BookFieldset {...book.props}>
+
+          {/* To setup a delete button */}
+          <button {...control.remove(index)}>Delete</button>
+        </div>
+      ))}
+
+      {/* To setup a button that can append a new row */}
+      <button {...control.append()}>add</button>
+    </fieldset>
+  );
+}
+
+/**
+ * This is basically the BookFieldset component from
+ * the `useFieldset` example, but setting all the
+ * options with the component props instead
+ */
+function BookFieldset({ name, form, defaultValue, error }) {
+  const [fieldsetProps, { name, isbn }] = useFieldset(bookSchema, {
+    name,
+    form,
+    defaultValue,
+    error,
+  });
+
+  return (
+    <fieldset {...fieldsetProps}>
+      {/* ... */}
+    </fieldset>
+  );
+}
+```
+
+<details>
+  <summary>What can I do with `controls`?</summary>
+
+```tsx
+// To append a new row with optional defaultValue
+<button {...controls.append(defaultValue)}>Append</button>;
+
+// To prepend a new row with optional defaultValue
+<button {...controls.prepend(defaultValue)}>Prepend</button>;
+
+// To remove a row by index
+<button {...controls.remove(index)}>Remove</button>;
+
+// To replace a row with another defaultValue
+<button {...controls.replace(index, defaultValue)}>Replace</button>;
+
+// To reorder a particular row to an another index
+<button {...controls.reorder(fromIndex, toIndex)}>Reorder</button>;
+```
+
+</details>
+
+---
+
+### useControlledInput
+
+This hooks creates a shadow input that would be used to validate against the schema. Mainly used to get around problem integrating with controlled component.
+
+```tsx
+import { useControlledInput } from '@conform-to/react';
+import { Select, MenuItem } from '@mui/material';
+
+function RandomFieldset() {
+  const [fieldsetProps, { category }] = useFieldset(schema);
+  const [input, control] = useControlledInput(category);
+
+  return (
+    <fieldset {...fieldsetProps}>
+      {/* Render the shadow input somewhere within the fieldset */}
+      {input}
+
+      {/* MUI Select is a controlled component */}
+      <Select
+        label="Category"
+        value={control.value ?? ''}
+        onChange={(e) => control.onChange(e.target.value)}
+        onBlur={() => control.onBlur()}
+        error={Boolean(category.error)}
+        helperText={category.error}
+      >
+        <MenuItem value="">Please select</MenuItem>
+        <MenuItem value="a">Category A</MenuItem>
+        <MenuItem value="b">Category B</MenuItem>
+        <MenuItem value="c">Category C</MenuItem>
+      </TextField>
+    </fieldset>
+  )
+}
+```
+
+---
+
+### conform
+
+It provides several helpers to setup a native input field quickly:
+
+```tsx
+import { conform } from '@conform-to/react';
+
+function RandomForm() {
+  const [setupFieldset, { cateogry }] = useFieldset(/* ... */);
+
+  return (
+    <fieldset {...setupFieldset}>
+      <input {...conform.input(cateogry, { type: 'text' })} />
+      <textarea {...conform.textarea(cateogry)} />
+      <select {...conform.select(cateogry)}>{/* ... */}</select>
+    </fieldset>
+  );
+}
+```
+
+This is equivalent to:
+
+```tsx
+function RandomForm() {
+  const [setupFieldset, { cateogry }] = useFieldset(/* ... */);
+
+  return (
+    <fieldset {...setupFieldset}>
+      <input
+        type="text"
+        name={cateogry.name}
+        form={cateogry.form}
+        defaultValue={cateogry.defaultValue}
+        requried={cateogry.required}
+        minLength={cateogry.minLength}
+        maxLength={cateogry.maxLength}
+        min={cateogry.min}
+        max={cateogry.max}
+        multiple={cateogry.multiple}
+        pattern={cateogry.pattern}
+      >
+      <textarea
+        name={cateogry.name}
+        form={cateogry.form}
+        defaultValue={cateogry.defaultValue}
+        requried={cateogry.required}
+        minLength={cateogry.minLength}
+        maxLength={cateogry.maxLength}
+      />
+      <select
+        name={cateogry.name}
+        form={cateogry.form}
+        defaultValue={cateogry.defaultValue}
+        requried={cateogry.required}
+        multiple={cateogry.multiple}
+      >
+        {/* ... */}
+      </select>
+    </fieldset>
+  );
+}
+```

package/helpers.d.ts

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

package/helpers.js

@@ -2,9 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-function input(config) {
-  var _config$constraint, _config$constraint2, _config$constraint3, _config$constraint4, _config$constraint5, _config$constraint6, _config$constraint7;
-
+function input(props) {
   var {
     type,
     value
@@ -12,49 +10,50 @@ function input(config) {
   var isCheckboxOrRadio = type === 'checkbox' || type === 'radio';
   var attributes = {
     type,
-    name: config.name,
-    form: config.form,
-    required: (_config$constraint = config.constraint) === null || _config$constraint === void 0 ? void 0 : _config$constraint.required,
-    minLength: (_config$constraint2 = config.constraint) === null || _config$constraint2 === void 0 ? void 0 : _config$constraint2.minLength,
-    maxLength: (_config$constraint3 = config.constraint) === null || _config$constraint3 === void 0 ? void 0 : _config$constraint3.maxLength,
-    min: (_config$constraint4 = config.constraint) === null || _config$constraint4 === void 0 ? void 0 : _config$constraint4.min,
-    max: (_config$constraint5 = config.constraint) === null || _config$constraint5 === void 0 ? void 0 : _config$constraint5.max,
-    step: (_config$constraint6 = config.constraint) === null || _config$constraint6 === void 0 ? void 0 : _config$constraint6.step,
-    pattern: (_config$constraint7 = config.constraint) === null || _config$constraint7 === void 0 ? void 0 : _config$constraint7.pattern
+    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
   };
 
   if (isCheckboxOrRadio) {
     attributes.value = value !== null && value !== void 0 ? value : 'on';
-    attributes.defaultChecked = config.initialValue === attributes.value;
+    attributes.defaultChecked = props.defaultValue === attributes.value;
   } else {
-    var _config$initialValue;
+    var _props$defaultValue;
 
-    attributes.defaultValue = "".concat((_config$initialValue = config.initialValue) !== null && _config$initialValue !== void 0 ? _config$initialValue : '');
+    attributes.defaultValue = "".concat((_props$defaultValue = props.defaultValue) !== null && _props$defaultValue !== void 0 ? _props$defaultValue : '');
   }
 
   return attributes;
 }
-function select(config) {
-  var _config$initialValue2, _config$constraint8, _config$constraint9;
+function select(props) {
+  var _props$defaultValue2;
 
   return {
-    name: config.name,
-    form: config.form,
-    defaultValue: "".concat((_config$initialValue2 = config.initialValue) !== null && _config$initialValue2 !== void 0 ? _config$initialValue2 : ''),
-    required: (_config$constraint8 = config.constraint) === null || _config$constraint8 === void 0 ? void 0 : _config$constraint8.required,
-    multiple: (_config$constraint9 = config.constraint) === null || _config$constraint9 === void 0 ? void 0 : _config$constraint9.multiple
+    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
   };
 }
-function textarea(config) {
-  var _config$initialValue3, _config$constraint10, _config$constraint11, _config$constraint12;
+function textarea(props) {
+  var _props$defaultValue3;
 
   return {
-    name: config.name,
-    form: config.form,
-    defaultValue: "".concat((_config$initialValue3 = config.initialValue) !== null && _config$initialValue3 !== void 0 ? _config$initialValue3 : ''),
-    required: (_config$constraint10 = config.constraint) === null || _config$constraint10 === void 0 ? void 0 : _config$constraint10.required,
-    minLength: (_config$constraint11 = config.constraint) === null || _config$constraint11 === void 0 ? void 0 : _config$constraint11.minLength,
-    maxLength: (_config$constraint12 = config.constraint) === null || _config$constraint12 === void 0 ? void 0 : _config$constraint12.maxLength
+    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
   };
 }
 

package/hooks.d.ts

@@ -1,6 +1,6 @@
-import { type FieldConfig, type Schema } from '@conform-to/dom';
+import { type FieldProps, type Schema, type FieldsetData } from '@conform-to/dom';
 import { type ButtonHTMLAttributes, type FormEventHandler, type FormHTMLAttributes, type RefObject, type ReactElement } from 'react';
-interface FormConfig {
+export interface FormConfig {
     /**
      * Decide when the error should be reported initially.
      * Default to `onSubmit`
@@ -30,35 +30,35 @@ interface FormProps {
     noValidate: Required<FormHTMLAttributes<HTMLFormElement>>['noValidate'];
 }
 export declare function useForm({ onReset, onSubmit, noValidate, fallbackNative, initialReport, }?: FormConfig): FormProps;
-interface FieldsetConfig<Type> extends Partial<FieldConfig<Type>> {
-}
+export declare type FieldsetConfig<Type> = Partial<Pick<FieldProps<Type>, 'name' | 'form' | 'defaultValue' | 'error'>>;
 interface FieldsetProps {
     ref: RefObject<HTMLFieldSetElement>;
     name?: string;
     form?: string;
     onInput: FormEventHandler<HTMLFieldSetElement>;
-    onReset: FormEventHandler<HTMLFieldSetElement>;
     onInvalid: FormEventHandler<HTMLFieldSetElement>;
 }
 export declare function useFieldset<Type extends Record<string, any>>(schema: Schema<Type>, config?: FieldsetConfig<Type>): [FieldsetProps, {
-    [Key in keyof Type]-?: FieldConfig<Type[Key]>;
+    [Key in keyof Type]-?: FieldProps<Type[Key]>;
 }];
-interface FieldListControl {
-    prepend(): ButtonHTMLAttributes<HTMLButtonElement>;
-    append(): ButtonHTMLAttributes<HTMLButtonElement>;
+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>;
 }
-export declare function useFieldList<Type extends Array<any>>(config: FieldConfig<Type>): [
+export declare function useFieldList<Payload>(props: FieldProps<Array<Payload>>): [
     Array<{
         key: string;
-        config: FieldConfig<Type extends Array<infer InnerType> ? InnerType : never>;
+        props: FieldProps<Payload>;
     }>,
-    FieldListControl
+    FieldListControl<Payload>
 ];
 interface InputControl {
     value: string;
     onChange: (value: string) => void;
     onBlur: () => void;
 }
-export declare function useControlledInput<T extends string | number | Date | undefined>(field: FieldConfig<T>): [ReactElement, InputControl];
+export declare function useControlledInput<T extends string | number | Date | undefined>(field: FieldProps<T>): [ReactElement, InputControl];
 export {};