@conform-to/react 0.5.0 → 0.6.0-pre.0

package/README.md

@@ -9,8 +9,11 @@
 - [useForm](#useform)
 - [useFieldset](#usefieldset)
 - [useFieldList](#usefieldlist)
-- [useControlledInput](#usecontrolledinput)
+- [useInputEvent](#useinputevent)
 - [conform](#conform)
+- [list](#list)
+- [validate](#validate)
+- [requestIntent](#requestintent)
 - [getFormElements](#getformelements)
 - [hasError](#haserror)
 - [parse](#parse)
@@ -39,14 +42,6 @@ function LoginForm() {
      */
     id: undefined,
 
-    /**
-     * Validation mode.
-     * Support "client-only" or "server-validation".
-     *
-     * Default to `client-only`.
-     */
-    mode: 'client-only',
-
     /**
      * Define when the error should be reported initially.
      * Support "onSubmit", "onChange", "onBlur".
@@ -278,34 +273,40 @@ function Example() {
 
 ---
 
-### useControlledInput
+### useInputEvent
 
-It returns the properties required to configure a shadow input for validation and helper to integrate it. This is particularly useful when [integrating custom input components](/docs/integrations.md#custom-input-component) like dropdown and datepicker.
+It returns a ref object and a set of helpers that dispatch corresponding dom event.
 
 ```tsx
-import { useForm, useControlledInput } from '@conform-to/react';
+import { useForm, useInputEvent } from '@conform-to/react';
 import { Select, MenuItem } from '@mui/material';
-import { useRef } from 'react';
+import { useState, useRef } from 'react';
 
 function MuiForm() {
   const [form, { category }] = useForm();
-  const [inputProps, control] = useControlledInput(category.config);
+  const [value, setValue] = useState(category.config.defaultValue ?? '');
+  const [ref, control] = useInputEvent({
+    onReset: () => setValue(category.config.defaultValue ?? ''),
+  });
+  const inputRef = useRef<HTMLInputElement>(null);
 
   return (
     <form {...form.props}>
       {/* Render a shadow input somewhere */}
-      <input {...inputProps} />
+      <input
+        ref={ref}
+        {...conform.input(category.config, { hidden: true })}
+        onChange={(e) => setValue(e.target.value)}
+        onFocus={() => inputRef.current?.focus()}
+      />
 
       {/* MUI Select is a controlled component */}
       <TextField
         label="Category"
-        inputRef={control.ref}
-        value={control.value}
-        onChange={control.onChange}
-        onBlur={control.onBlur}
-        inputProps={{
-          onInvalid: control.onInvalid,
-        }}
+        inputRef={inputRef}
+        value={value}
+        onChange={control.change}
+        onBlur={control.blur}
         select
       >
         <MenuItem value="">Please select</MenuItem>
@@ -446,9 +447,9 @@ function Example() {
 
 ---
 
-### requestCommand
+### requestIntent
 
-It lets you [trigger a command](/docs/commands.md#triggering-a-command) without requiring users to click on a button. It supports both [list](#list) and [validate](#validate) command.
+It lets you [trigger an intent](/docs/commands.md#triggering-an-intent) without requiring users to click on a button. It supports both [list](#list) and [validate](#validate) intent.
 
 ```tsx
 import {
@@ -456,7 +457,7 @@ import {
   useFieldList,
   conform,
   list,
-  requestCommand,
+  requestIntent,
 } from '@conform-to/react';
 import DragAndDrop from 'awesome-dnd-example';
 
@@ -465,7 +466,7 @@ export default function Todos() {
   const taskList = useFieldList(form.ref, tasks.config);
 
   const handleDrop = (from, to) =>
-    requestCommand(form.ref.current, list.reorder({ from, to }));
+    requestIntent(form.ref.current, list.reorder({ from, to }));
 
   return (
     <form {...form.props}>
@@ -527,27 +528,6 @@ export default function LoginForm() {
 
 ---
 
-### hasError
-
-This helper checks if there is any message defined in error array with the provided name.
-
-```ts
-import { hasError } from '@conform-to/react';
-
-/**
- * Assume the error looks like this:
- */
-const error = [['email', 'Email is required']];
-
-// This will log `true`
-console.log(hasError(error, 'email'));
-
-// This will log `false`
-console.log(hasError(error, 'password'));
-```
-
----
-
 ### parse
 
 It parses the formData based on the [naming convention](/docs/submission).
@@ -571,20 +551,15 @@ This helper checks if the scope of validation includes a specific field by check
 import { shouldValidate } from '@conform-to/react';
 
 /**
- * The submission type and intent give us hint on what should be valdiated.
- * If the type is 'validate', only the field with name matching the metadata must be validated.
- * If the type is 'submit', everything should be validated (Default submission)
+ * The submission intent give us hint on what should be valdiated.
+ * If the intent is 'validate/:field', only the field with name matching must be validated.
+ * If the intent is undefined, everything should be validated (Default submission)
  */
-const submission = {
-  context: 'validate',
-  intent: 'email',
-  value: {},
-  error: [],
-};
+const intent = 'validate/email';
 
 // This will log 'true'
-console.log(shouldValidate(submission, 'email'));
+console.log(shouldValidate(intent, 'email'));
 
 // This will log 'false'
-console.log(shouldValidate(submission, 'password'));
+console.log(shouldValidate(intent, 'password'));
 ```

package/_virtual/_rollupPluginBabelHelpers.js

@@ -24,6 +24,7 @@ function _objectSpread2(target) {
   return target;
 }
 function _defineProperty(obj, key, value) {
+  key = _toPropertyKey(key);
   if (key in obj) {
     Object.defineProperty(obj, key, {
       value: value,
@@ -36,6 +37,22 @@ function _defineProperty(obj, key, value) {
   }
   return obj;
 }
+function _toPrimitive(input, hint) {
+  if (typeof input !== "object" || input === null) return input;
+  var prim = input[Symbol.toPrimitive];
+  if (prim !== undefined) {
+    var res = prim.call(input, hint || "default");
+    if (typeof res !== "object") return res;
+    throw new TypeError("@@toPrimitive must return a primitive value.");
+  }
+  return (hint === "string" ? String : Number)(input);
+}
+function _toPropertyKey(arg) {
+  var key = _toPrimitive(arg, "string");
+  return typeof key === "symbol" ? key : String(key);
+}
 
 exports.defineProperty = _defineProperty;
 exports.objectSpread2 = _objectSpread2;
+exports.toPrimitive = _toPrimitive;
+exports.toPropertyKey = _toPropertyKey;

package/helpers.d.ts

@@ -1,13 +1,16 @@
-import type { FieldConfig } from '@conform-to/dom';
-import type { HTMLInputTypeAttribute } from 'react';
+import { type FieldConfig, VALIDATION_SKIPPED, VALIDATION_UNDEFINED } from '@conform-to/dom';
+import type { CSSProperties, HTMLInputTypeAttribute } from 'react';
 interface FieldProps {
     id?: string;
     name: string;
     form?: string;
     required?: boolean;
     autoFocus?: boolean;
+    tabIndex?: number;
+    style?: CSSProperties;
     'aria-invalid': boolean;
     'aria-describedby'?: string;
+    'aria-hidden'?: boolean;
 }
 interface InputProps<Schema> extends FieldProps {
     type?: HTMLInputTypeAttribute;
@@ -31,20 +34,24 @@ interface TextareaProps extends FieldProps {
     maxLength?: number;
     defaultValue?: string;
 }
-declare type InputOptions = {
+type InputOptions = {
     type: 'checkbox' | 'radio';
+    hidden?: boolean;
     value?: string;
 } | {
-    type: 'file';
-    value?: never;
-} | {
-    type?: Exclude<HTMLInputTypeAttribute, 'button' | 'submit' | 'hidden' | 'file'>;
+    type?: Exclude<HTMLInputTypeAttribute, 'button' | 'submit' | 'hidden'>;
+    hidden?: boolean;
     value?: never;
 };
 export declare function input<Schema extends File | File[]>(config: FieldConfig<Schema>, options: {
     type: 'file';
 }): InputProps<Schema>;
 export declare function input<Schema extends any>(config: FieldConfig<Schema>, options?: InputOptions): InputProps<Schema>;
-export declare function select<Schema>(config: FieldConfig<Schema>): SelectProps;
-export declare function textarea<Schema>(config: FieldConfig<Schema>): TextareaProps;
-export {};
+export declare function select<Schema>(config: FieldConfig<Schema>, options?: {
+    hidden?: boolean;
+}): SelectProps;
+export declare function textarea<Schema>(config: FieldConfig<Schema>, options?: {
+    hidden?: boolean;
+}): TextareaProps;
+export declare const intent = "__intent__";
+export { VALIDATION_UNDEFINED, VALIDATION_SKIPPED };

package/helpers.js

@@ -2,6 +2,23 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var dom = require('@conform-to/dom');
+
+/**
+ * Style to make the input element visually hidden
+ * Based on the `sr-only` class from tailwindcss
+ */
+var hiddenStyle = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: 0,
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0,0,0,0)',
+  whiteSpace: 'nowrap',
+  border: 0
+};
 function input(config) {
   var _config$initialError;
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -21,7 +38,12 @@ function input(config) {
     'aria-invalid': Boolean((_config$initialError = config.initialError) === null || _config$initialError === void 0 ? void 0 : _config$initialError.length),
     'aria-describedby': config.errorId
   };
-  if (config.initialError && config.initialError.length > 0) {
+  if (options !== null && options !== void 0 && options.hidden) {
+    attributes.style = hiddenStyle;
+    attributes.tabIndex = -1;
+    attributes['aria-hidden'] = true;
+  }
+  if (config.initialError && Object.entries(config.initialError).length > 0) {
     attributes.autoFocus = true;
   }
   if (options.type === 'checkbox' || options.type === 'radio') {
@@ -33,7 +55,7 @@ function input(config) {
   }
   return attributes;
 }
-function select(config) {
+function select(config, options) {
   var _config$defaultValue, _config$initialError2;
   var attributes = {
     id: config.id,
@@ -45,12 +67,17 @@ function select(config) {
     'aria-invalid': Boolean((_config$initialError2 = config.initialError) === null || _config$initialError2 === void 0 ? void 0 : _config$initialError2.length),
     'aria-describedby': config.errorId
   };
-  if (config.initialError && config.initialError.length > 0) {
+  if (options !== null && options !== void 0 && options.hidden) {
+    attributes.style = hiddenStyle;
+    attributes.tabIndex = -1;
+    attributes['aria-hidden'] = true;
+  }
+  if (config.initialError && Object.entries(config.initialError).length > 0) {
     attributes.autoFocus = true;
   }
   return attributes;
 }
-function textarea(config) {
+function textarea(config, options) {
   var _config$defaultValue2, _config$initialError3;
   var attributes = {
     id: config.id,
@@ -64,12 +91,27 @@ function textarea(config) {
     'aria-invalid': Boolean((_config$initialError3 = config.initialError) === null || _config$initialError3 === void 0 ? void 0 : _config$initialError3.length),
     'aria-describedby': config.errorId
   };
-  if (config.initialError && config.initialError.length > 0) {
+  if (options !== null && options !== void 0 && options.hidden) {
+    attributes.style = hiddenStyle;
+    attributes.tabIndex = -1;
+    attributes['aria-hidden'] = true;
+  }
+  if (config.initialError && Object.entries(config.initialError).length > 0) {
     attributes.autoFocus = true;
   }
   return attributes;
 }
+var intent = '__intent__';
 
+Object.defineProperty(exports, 'VALIDATION_SKIPPED', {
+	enumerable: true,
+	get: function () { return dom.VALIDATION_SKIPPED; }
+});
+Object.defineProperty(exports, 'VALIDATION_UNDEFINED', {
+	enumerable: true,
+	get: function () { return dom.VALIDATION_UNDEFINED; }
+});
 exports.input = input;
+exports.intent = intent;
 exports.select = select;
 exports.textarea = textarea;

package/hooks.d.ts

@@ -1,15 +1,11 @@
-import { type FieldConfig, type FieldElement, type FieldValue, type FieldsetConstraint, type Primitive, type Submission } from '@conform-to/dom';
-import { type InputHTMLAttributes, type FormEvent, type RefObject } from 'react';
-export interface FormConfig<Schema extends Record<string, any>> {
+import { type FieldConfig, type FieldElement, type FieldValue, type FieldsetConstraint, type FormMethod, type FormEncType, type Submission } from '@conform-to/dom';
+import { type FormEvent, type RefObject } from 'react';
+export interface FormConfig<Schema extends Record<string, any>, ClientSubmission extends Submission | Submission<Schema> = Submission> {
     /**
      * If the form id is provided, Id for label,
      * input and error elements will be derived.
      */
     id?: string;
-    /**
-     * Validation mode. Default to `client-only`.
-     */
-    mode?: 'client-only' | 'server-validation';
     /**
      * Define when the error should be reported initially.
      * Support "onSubmit", "onChange", "onBlur".
@@ -24,7 +20,7 @@ export interface FormConfig<Schema extends Record<string, any>> {
     /**
      * An object describing the state from the last submission
      */
-    state?: Submission<Schema>;
+    state?: Submission;
     /**
      * An object describing the constraint of each field
      */
@@ -47,14 +43,17 @@ export interface FormConfig<Schema extends Record<string, any>> {
     onValidate?: ({ form, formData, }: {
         form: HTMLFormElement;
         formData: FormData;
-    }) => Submission<Schema>;
+    }) => ClientSubmission;
     /**
      * The submit event handler of the form. It will be called
      * only when the form is considered valid.
      */
     onSubmit?: (event: FormEvent<HTMLFormElement>, context: {
         formData: FormData;
-        submission: Submission<Schema>;
+        submission: ClientSubmission;
+        action: string;
+        encType: FormEncType;
+        method: FormMethod;
     }) => void;
 }
 /**
@@ -79,18 +78,19 @@ interface Form<Schema extends Record<string, any>> {
  *
  * @see https://conform.guide/api/react#useform
  */
-export declare function useForm<Schema extends Record<string, any>>(config?: FormConfig<Schema>): [Form<Schema>, Fieldset<Schema>];
+export declare function useForm<Schema extends Record<string, any>, ClientSubmission extends Submission | Submission<Schema> = Submission>(config?: FormConfig<Schema, ClientSubmission>): [Form<Schema>, Fieldset<Schema>];
 /**
  * All the information of the field, including state and config.
  */
-export declare type Field<Schema> = {
+export type Field<Schema> = {
     config: FieldConfig<Schema>;
     error?: string;
+    errors?: string[];
 };
 /**
  * A set of field information.
  */
-export declare type Fieldset<Schema extends Record<string, any>> = {
+export type Fieldset<Schema extends Record<string, any>> = {
     [Key in keyof Schema]-?: Field<Schema[Key]>;
 };
 export interface FieldsetConfig<Schema extends Record<string, any>> {
@@ -105,7 +105,7 @@ export interface FieldsetConfig<Schema extends Record<string, any>> {
     /**
      * An object describing the initial error of each field
      */
-    initialError?: Array<[string, string]>;
+    initialError?: Record<string, string | string[]>;
     /**
      * An object describing the constraint of each field
      */
@@ -131,32 +131,30 @@ export declare function useFieldset<Schema extends Record<string, any>>(ref: Ref
 export declare function useFieldList<Payload = any>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config: FieldConfig<Array<Payload>>): Array<{
     key: string;
     error: string | undefined;
+    errors: string[] | undefined;
     config: FieldConfig<Payload>;
 }>;
-interface ShadowInputProps extends InputHTMLAttributes<HTMLInputElement> {
-    ref: RefObject<HTMLInputElement>;
-}
-interface InputControl<Element extends {
-    focus: () => void;
-}> {
-    ref: RefObject<Element>;
-    value: string;
-    onChange: (eventOrValue: {
+interface InputControl {
+    change: (eventOrValue: {
         target: {
             value: string;
         };
     } | string) => void;
-    onBlur: () => void;
-    onInvalid: (event: FormEvent<FieldElement>) => void;
+    focus: () => void;
+    blur: () => void;
 }
 /**
- * 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.
+ * Returns a ref object and a set of helpers that dispatch corresponding dom event.
  *
- * @see https://conform.guide/api/react#usecontrolledinput
+ * @see https://conform.guide/api/react#useinputevent
  */
-export declare function useControlledInput<Element extends {
-    focus: () => void;
-} = HTMLInputElement, Schema extends Primitive = Primitive>(config: FieldConfig<Schema>): [ShadowInputProps, InputControl<Element>];
+export declare function useInputEvent<RefShape extends FieldElement = HTMLInputElement>(options?: {
+    onSubmit?: (event: SubmitEvent) => void;
+    onReset?: (event: Event) => void;
+}): [RefObject<RefShape>, InputControl];
+export declare function useInputEvent<RefShape extends Exclude<any, FieldElement>>(options: {
+    getElement: (ref: RefShape | null) => FieldElement | null | undefined;
+    onSubmit?: (event: SubmitEvent) => void;
+    onReset?: (event: Event) => void;
+}): [RefObject<RefShape>, InputControl];
 export {};