@conform-to/react 0.7.0-pre.2 → 0.7.0

package/README.md

@@ -53,7 +53,7 @@ function LoginForm() {
      * Define when conform should revalidate again.
      * Support "onSubmit", "onChange", "onBlur".
      *
-     * Default to `onInput`.
+     * Default based on `shouldValidate`
      */
     shouldRevalidate: 'onInput',
 
@@ -159,7 +159,7 @@ function LoginForm() {
 This hook enables you to work with [nested object](/docs/configuration.md#nested-object) by monitoring the state of each nested field and prepraing the config required.
 
 ```tsx
-import { useForm, useFieldset, conform } from '@conform-to/react';
+import { useForm, useFieldset } from '@conform-to/react';
 
 interface Address {
   street: string;
@@ -179,13 +179,13 @@ function Example() {
     <form {...form.props}>
       <fieldset>
         <legned>Address</legend>
-        <input {...conform.input(street)} />
+        <input name={street.name} />
         <div>{street.error}</div>
-        <input {...conform.input(zipcode)} />
+        <input name={zipcode.name} />
         <div>{zipcode.error}</div>
-        <input {...conform.input(city)} />
+        <input name={city.name} />
         <div>{city.error}</div>
-        <input {...conform.input(country)} />
+        <input name={country.name} />
         <div>{country.error}</div>
       </fieldset>
       <button>Submit</button>
@@ -259,7 +259,7 @@ function Example() {
       {itemsList.map((item, index) => (
         <div key={item.key}>
           {/* Setup an input per item */}
-          <input {...conform.input(item)} />
+          <input name={item.name} />
 
           {/* Error of each item */}
           <span>{item.error}</span>
@@ -280,7 +280,7 @@ function Example() {
 
 ### useInputEvent
 
-It returns a ref object and a set of helpers that dispatch corresponding dom event.
+It returns a set of helpers that dispatch corresponding dom event.
 
 ```tsx
 import { useForm, useInputEvent } from '@conform-to/react';
@@ -290,25 +290,28 @@ import { useState, useRef } from 'react';
 function MuiForm() {
   const [form, { category }] = useForm();
   const [value, setValue] = useState(category.defaultValue ?? '');
-  const [ref, control] = useInputEvent({
+  const baseInputRef = useRef<HTMLInputElement>(null);
+  const customInputRef = useRef<HTMLInputElement>(null);
+  const control = useInputEvent({
+    ref: baseInputRef,
+    // Reset the state on form reset
     onReset: () => setValue(category.defaultValue ?? ''),
   });
-  const inputRef = useRef<HTMLInputElement>(null);
 
   return (
     <form {...form.props}>
-      {/* Render a shadow input somewhere */}
+      {/* Render a base input somewhere */}
       <input
-        ref={ref}
+        ref={baseInputRef}
         {...conform.input(category, { hidden: true })}
         onChange={(e) => setValue(e.target.value)}
-        onFocus={() => inputRef.current?.focus()}
+        onFocus={() => customInputRef.current?.focus()}
       />
 
       {/* MUI Select is a controlled component */}
       <TextField
         label="Category"
-        inputRef={inputRef}
+        inputRef={customInputRef}
         value={value}
         onChange={control.change}
         onBlur={control.blur}
@@ -328,17 +331,16 @@ function MuiForm() {
 
 ### conform
 
-It provides several helpers to remove the boilerplate when configuring a form control and derives attributes for [accessibility](/docs/accessibility.md#configuration) concerns and helps [focus management](/docs/focus-management.md#focusing-before-javascript-is-loaded).
+It provides several helpers to:
 
-You can also create a wrapper on top if you need to integrate with custom input component.
-
-Before:
+- Minimize the boilerplate when configuring a form control
+- Derive aria attributes for [accessibility](/docs/accessibility.md#configuration)
+- Helps [focus management](/docs/focus-management.md#focusing-before-javascript-is-loaded)
 
 ```tsx
-import { useForm } from '@conform-to/react';
-
+// Before
 function Example() {
-  const [form, { title, description, category }] = useForm();
+  const [form, { title }] = useForm();
 
   return (
     <form {...form.props}>
@@ -347,6 +349,7 @@ function Example() {
         name={title.name}
         form={title.form}
         defaultValue={title.defaultValue}
+        autoFocus={title.initialError ? true : undefined}
         requried={title.required}
         minLength={title.minLength}
         maxLength={title.maxLength}
@@ -354,42 +357,25 @@ function Example() {
         max={title.max}
         multiple={title.multiple}
         pattern={title.pattern}
+        aria-invalid={title.error ? true : undefined}
+        aria-describedby={title.error ? `${title.name}-error` : undefined}
       />
-      <textarea
-        name={description.name}
-        form={description.form}
-        defaultValue={description.defaultValue}
-        requried={description.required}
-        minLength={description.minLength}
-        maxLength={description.maxLength}
-      />
-      <select
-        name={category.name}
-        form={category.form}
-        defaultValue={category.defaultValue}
-        requried={category.required}
-        multiple={category.multiple}
-      >
-        {/* ... */}
-      </select>
     </form>
   );
 }
-```
-
-After:
-
-```tsx
-import { useForm, conform } from '@conform-to/react';
 
+// After:
 function Example() {
   const [form, { title, description, category }] = useForm();
 
   return (
     <form {...form.props}>
-      <input {...conform.input(title, { type: 'text' })} />
-      <textarea {...conform.textarea(description)} />
-      <select {...conform.select(category)}>{/* ... */}</select>
+      <input
+        {...conform.input(title, {
+          type: 'text',
+          ariaAttributes: true,
+        })}
+      />
     </form>
   );
 }
@@ -434,6 +420,8 @@ const submission = parse(formData, {
 
 ### validateConstraint
 
+> This is a client only API
+
 This enable Constraint Validation with ability to enable custom constraint using data-attribute and customizing error messages. By default, the error message would be the attribute that triggered the error (e.g. `required` / `type` / 'minLength' etc).
 
 ```tsx

package/helpers.d.ts

@@ -1,5 +1,5 @@
-import { INTENT } from '@conform-to/dom';
-import { type FieldConfig, type Primitive, VALIDATION_UNDEFINED, VALIDATION_SKIPPED } from './hooks.js';
+import { INTENT, VALIDATION_UNDEFINED, VALIDATION_SKIPPED } from '@conform-to/dom';
+import type { FieldConfig, Primitive } from './hooks.js';
 import type { CSSProperties, HTMLInputTypeAttribute } from 'react';
 interface FormControlProps {
     id?: string;
@@ -36,6 +36,10 @@ interface TextareaProps extends FormControlProps {
     defaultValue?: string;
 }
 type BaseOptions = {
+    ariaAttributes?: false;
+    hidden?: boolean;
+} | {
+    ariaAttributes: true;
     description?: boolean;
     hidden?: boolean;
 };
@@ -46,6 +50,11 @@ type InputOptions = BaseOptions & ({
     type?: Exclude<HTMLInputTypeAttribute, 'button' | 'submit' | 'hidden'>;
     value?: never;
 });
+export declare const hiddenProps: {
+    hiddenStyle: CSSProperties;
+    tabIndex: number;
+    'aria-hidden': boolean;
+};
 export declare function input<Schema extends Primitive | unknown>(config: FieldConfig<Schema>, options?: InputOptions): InputProps<Schema>;
 export declare function input<Schema extends File | File[]>(config: FieldConfig<Schema>, options: InputOptions & {
     type: 'file';

package/helpers.js

@@ -4,25 +4,8 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var _rollupPluginBabelHelpers = require('./_virtual/_rollupPluginBabelHelpers.js');
 var dom = require('@conform-to/dom');
-var hooks = require('./hooks.js');
 
-/**
- * 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 getFormControlProps(config, options) {
-  var _config$error;
   var props = {
     id: config.id,
     name: config.name,
@@ -32,23 +15,40 @@ function getFormControlProps(config, options) {
   if (config.id) {
     props.id = config.id;
   }
-  if (config.descriptionId && options !== null && options !== void 0 && options.description) {
-    props['aria-describedby'] = config.descriptionId;
-  }
-  if (config.errorId && (_config$error = config.error) !== null && _config$error !== void 0 && _config$error.length) {
-    props['aria-invalid'] = true;
-    props['aria-describedby'] = config.descriptionId && options !== null && options !== void 0 && options.description ? "".concat(config.errorId, " ").concat(config.descriptionId) : config.errorId;
+  if (options !== null && options !== void 0 && options.ariaAttributes) {
+    var _config$error;
+    if (config.descriptionId && options !== null && options !== void 0 && options.description) {
+      props['aria-describedby'] = config.descriptionId;
+    }
+    if (config.errorId && (_config$error = config.error) !== null && _config$error !== void 0 && _config$error.length) {
+      props['aria-invalid'] = true;
+      props['aria-describedby'] = config.descriptionId && options !== null && options !== void 0 && options.description ? "".concat(config.errorId, " ").concat(config.descriptionId) : config.errorId;
+    }
   }
   if (config.initialError && Object.entries(config.initialError).length > 0) {
     props.autoFocus = true;
   }
-  if (options !== null && options !== void 0 && options.hidden) {
-    props.style = hiddenStyle;
-    props.tabIndex = -1;
-    props['aria-hidden'] = true;
-  }
-  return props;
+  return options !== null && options !== void 0 && options.hidden ? _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, props), hiddenProps) : props;
 }
+var hiddenProps = {
+  /**
+   * Style to make the input element visually hidden
+   * Based on the `sr-only` class from tailwindcss
+   */
+  hiddenStyle: {
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    padding: 0,
+    margin: '-1px',
+    overflow: 'hidden',
+    clip: 'rect(0,0,0,0)',
+    whiteSpace: 'nowrap',
+    border: 0
+  },
+  tabIndex: -1,
+  'aria-hidden': true
+};
 function input(config) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var props = _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, getFormControlProps(config, options)), {}, {
@@ -90,8 +90,15 @@ Object.defineProperty(exports, 'INTENT', {
 	enumerable: true,
 	get: function () { return dom.INTENT; }
 });
-exports.VALIDATION_SKIPPED = hooks.VALIDATION_SKIPPED;
-exports.VALIDATION_UNDEFINED = hooks.VALIDATION_UNDEFINED;
+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.hiddenProps = hiddenProps;
 exports.input = input;
 exports.select = select;
 exports.textarea = textarea;

package/helpers.mjs

@@ -1,24 +1,7 @@
 import { objectSpread2 as _objectSpread2 } from './_virtual/_rollupPluginBabelHelpers.mjs';
-export { INTENT } from '@conform-to/dom';
-export { VALIDATION_SKIPPED, VALIDATION_UNDEFINED } from './hooks.mjs';
+export { INTENT, VALIDATION_SKIPPED, VALIDATION_UNDEFINED } from '@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 getFormControlProps(config, options) {
-  var _config$error;
   var props = {
     id: config.id,
     name: config.name,
@@ -28,23 +11,40 @@ function getFormControlProps(config, options) {
   if (config.id) {
     props.id = config.id;
   }
-  if (config.descriptionId && options !== null && options !== void 0 && options.description) {
-    props['aria-describedby'] = config.descriptionId;
-  }
-  if (config.errorId && (_config$error = config.error) !== null && _config$error !== void 0 && _config$error.length) {
-    props['aria-invalid'] = true;
-    props['aria-describedby'] = config.descriptionId && options !== null && options !== void 0 && options.description ? "".concat(config.errorId, " ").concat(config.descriptionId) : config.errorId;
+  if (options !== null && options !== void 0 && options.ariaAttributes) {
+    var _config$error;
+    if (config.descriptionId && options !== null && options !== void 0 && options.description) {
+      props['aria-describedby'] = config.descriptionId;
+    }
+    if (config.errorId && (_config$error = config.error) !== null && _config$error !== void 0 && _config$error.length) {
+      props['aria-invalid'] = true;
+      props['aria-describedby'] = config.descriptionId && options !== null && options !== void 0 && options.description ? "".concat(config.errorId, " ").concat(config.descriptionId) : config.errorId;
+    }
   }
   if (config.initialError && Object.entries(config.initialError).length > 0) {
     props.autoFocus = true;
   }
-  if (options !== null && options !== void 0 && options.hidden) {
-    props.style = hiddenStyle;
-    props.tabIndex = -1;
-    props['aria-hidden'] = true;
-  }
-  return props;
+  return options !== null && options !== void 0 && options.hidden ? _objectSpread2(_objectSpread2({}, props), hiddenProps) : props;
 }
+var hiddenProps = {
+  /**
+   * Style to make the input element visually hidden
+   * Based on the `sr-only` class from tailwindcss
+   */
+  hiddenStyle: {
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    padding: 0,
+    margin: '-1px',
+    overflow: 'hidden',
+    clip: 'rect(0,0,0,0)',
+    whiteSpace: 'nowrap',
+    border: 0
+  },
+  tabIndex: -1,
+  'aria-hidden': true
+};
 function input(config) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var props = _objectSpread2(_objectSpread2({}, getFormControlProps(config, options)), {}, {
@@ -82,4 +82,4 @@ function textarea(config, options) {
   return props;
 }
 
-export { input, select, textarea };
+export { hiddenProps, input, select, textarea };

package/hooks.d.ts

@@ -31,22 +31,18 @@ export interface FormConfig<Output extends Record<string, any>, Input extends Re
      * A form ref object. Conform will fallback to its own ref object if it is not provided.
      */
     ref?: RefObject<HTMLFormElement>;
-    /**
-     * @deprecated Use `shouldValidate` and `shouldRevalidate` instead.
-     */
-    initialReport?: 'onSubmit' | 'onChange' | 'onBlur';
     /**
      * Define when conform should start validation.
      * Support "onSubmit", "onChange", "onBlur".
      *
-     * Default to `onSubmit`.
+     * @default "onSubmit"
      */
     shouldValidate?: 'onSubmit' | 'onBlur' | 'onInput';
     /**
      * Define when conform should revalidate again.
      * Support "onSubmit", "onChange", "onBlur".
      *
-     * Default to `onInput`.
+     * @default shouldValidate, or "onSubmit" if shouldValidate is not provided.
      */
     shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput';
     /**
@@ -56,7 +52,7 @@ export interface FormConfig<Output extends Record<string, any>, Input extends Re
     /**
      * An object describing the result of the last submission
      */
-    lastSubmission?: Submission;
+    lastSubmission?: Submission | null;
     /**
      * An object describing the constraint of each field
      */
@@ -166,26 +162,23 @@ interface InputControl {
         target: {
             value: string;
         };
-    } | string) => void;
+    } | string | boolean) => void;
     focus: () => void;
     blur: () => void;
 }
+export declare function useEventListeners(type: string, ref: RefObject<FieldElement>): void;
 /**
  * Returns a ref object and a set of helpers that dispatch corresponding dom event.
  *
  * @see https://conform.guide/api/react#useinputevent
  */
-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;
+export declare function useInputEvent(options: {
+    ref: RefObject<FieldElement> | (() => Element | RadioNodeList | FieldElement | null | undefined);
+    onInput?: (event: Event) => void;
+    onFocus?: (event: FocusEvent) => void;
+    onBlur?: (event: FocusEvent) => void;
     onReset?: (event: Event) => void;
-}): [RefObject<RefShape>, InputControl];
-export declare const VALIDATION_UNDEFINED = "__undefined__";
-export declare const VALIDATION_SKIPPED = "__skipped__";
+}): InputControl;
 export declare const FORM_ERROR_ELEMENT_NAME = "__form__";
 /**
  * Validate the form with the Constraint Validation API