@conform-to/react 0.6.0 → 0.6.2

package/README.md

@@ -42,12 +42,20 @@ function LoginForm() {
     id: undefined,
 
     /**
-     * Define when the error should be reported initially.
+     * Define when conform should start validation.
      * Support "onSubmit", "onChange", "onBlur".
      *
      * Default to `onSubmit`.
      */
-    initialReport: 'onBlur',
+    shouldValidate: 'onSubmit',
+
+    /**
+     * Define when conform should revalidate again.
+     * Support "onSubmit", "onChange", "onBlur".
+     *
+     * Default to `onInput`.
+     */
+    shouldRevalidate: 'onInput',
 
     /**
      * An object representing the initial value of the form.

package/helpers.d.ts

@@ -1,4 +1,5 @@
-import { type FieldConfig, type Primitive, VALIDATION_UNDEFINED, VALIDATION_SKIPPED, INTENT } from '@conform-to/dom';
+import { INTENT } from '@conform-to/dom';
+import { type FieldConfig, type Primitive, VALIDATION_UNDEFINED, VALIDATION_SKIPPED } from './hooks';
 import type { CSSProperties, HTMLInputTypeAttribute } from 'react';
 interface FormControlProps {
     id?: string;
@@ -34,23 +35,21 @@ interface TextareaProps extends FormControlProps {
     maxLength?: number;
     defaultValue?: string;
 }
-type InputOptions = {
-    type: 'checkbox' | 'radio';
+type BaseOptions = {
+    description?: boolean;
     hidden?: boolean;
+};
+type InputOptions = BaseOptions & ({
+    type: 'checkbox' | 'radio';
     value?: string;
 } | {
     type?: Exclude<HTMLInputTypeAttribute, 'button' | 'submit' | 'hidden'>;
-    hidden?: boolean;
     value?: never;
-};
-export declare function input<Schema extends File | File[]>(config: FieldConfig<Schema>, options: {
+});
+export declare function input<Schema extends File | File[]>(config: FieldConfig<Schema>, options: InputOptions & {
     type: 'file';
 }): InputProps<Schema>;
 export declare function input<Schema extends Primitive>(config: FieldConfig<Schema>, options?: InputOptions): InputProps<Schema>;
-export declare function select(config: FieldConfig<Primitive | Primitive[]>, options?: {
-    hidden?: boolean;
-}): SelectProps;
-export declare function textarea(config: FieldConfig<Primitive>, options?: {
-    hidden?: boolean;
-}): TextareaProps;
+export declare function select(config: FieldConfig<Primitive | Primitive[]>, options?: BaseOptions): SelectProps;
+export declare function textarea(config: FieldConfig<Primitive>, options?: BaseOptions): TextareaProps;
 export { INTENT, VALIDATION_UNDEFINED, VALIDATION_SKIPPED };

package/helpers.js

@@ -4,6 +4,7 @@ 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
@@ -30,10 +31,13 @@ function getFormControlProps(config, options) {
   };
   if (config.id) {
     props.id = config.id;
-    props['aria-describedby'] = config.errorId;
+  }
+  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;
@@ -86,14 +90,8 @@ Object.defineProperty(exports, 'INTENT', {
 	enumerable: true,
 	get: function () { return dom.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.VALIDATION_SKIPPED = hooks.VALIDATION_SKIPPED;
+exports.VALIDATION_UNDEFINED = hooks.VALIDATION_UNDEFINED;
 exports.input = input;
 exports.select = select;
 exports.textarea = textarea;

package/hooks.d.ts

@@ -1,22 +1,58 @@
-import { type FieldConfig, type FieldElement, type FieldValue, type FieldsetConstraint, type FormMethod, type FormEncType, type Submission } from '@conform-to/dom';
+import { type FieldConstraint, type FieldElement, type FieldsetConstraint, type Submission, type KeysOf, type ResolveType, getFormEncType, getFormMethod } 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> {
+export type Primitive = null | undefined | string | number | boolean | Date;
+export interface FieldConfig<Schema> extends FieldConstraint<Schema> {
+    id?: string;
+    name: string;
+    defaultValue?: FieldValue<Schema>;
+    initialError?: Record<string, string | string[]>;
+    form?: string;
+    descriptionId?: string;
+    errorId?: string;
+    /**
+     * The frist error of the field
+     */
+    error?: string;
+    /**
+     * All of the field errors
+     */
+    errors?: string[];
+}
+export type FieldValue<Schema> = Schema extends Primitive ? string : Schema extends File ? File : Schema extends Array<infer InnerType> ? Array<FieldValue<InnerType>> : Schema extends Record<string, any> ? {
+    [Key in KeysOf<Schema>]?: FieldValue<ResolveType<Schema, Key>>;
+} : any;
+export interface FormConfig<Output extends Record<string, any>, Input extends Record<string, any> = Output> {
     /**
      * If the form id is provided, Id for label,
      * input and error elements will be derived.
      */
     id?: string;
     /**
-     * Define when the error should be reported initially.
+     * 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`.
      */
-    initialReport?: 'onSubmit' | 'onChange' | 'onBlur';
+    shouldValidate?: 'onSubmit' | 'onBlur' | 'onInput';
+    /**
+     * Define when conform should revalidate again.
+     * Support "onSubmit", "onChange", "onBlur".
+     *
+     * Default to `onInput`.
+     */
+    shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput';
     /**
      * An object representing the initial value of the form.
      */
-    defaultValue?: FieldValue<Schema>;
+    defaultValue?: FieldValue<Input>;
     /**
      * An object describing the result of the last submission
      */
@@ -24,7 +60,7 @@ export interface FormConfig<Schema extends Record<string, any>, ClientSubmission
     /**
      * An object describing the constraint of each field
      */
-    constraint?: FieldsetConstraint<Schema>;
+    constraint?: FieldsetConstraint<Input>;
     /**
      * Enable native validation before hydation.
      *
@@ -43,17 +79,17 @@ export interface FormConfig<Schema extends Record<string, any>, ClientSubmission
     onValidate?: ({ form, formData, }: {
         form: HTMLFormElement;
         formData: FormData;
-    }) => ClientSubmission;
+    }) => Submission | Submission<Output>;
     /**
      * 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: ClientSubmission;
+        submission: Submission;
         action: string;
-        encType: FormEncType;
-        method: FormMethod;
+        encType: ReturnType<typeof getFormEncType>;
+        method: ReturnType<typeof getFormMethod>;
     }) => void;
 }
 /**
@@ -81,12 +117,12 @@ interface Form {
  *
  * @see https://conform.guide/api/react#useform
  */
-export declare function useForm<Schema extends Record<string, any>, ClientSubmission extends Submission | Submission<Schema> = Submission>(config?: FormConfig<Schema, ClientSubmission>): [Form, Fieldset<Schema>];
+export declare function useForm<Output extends Record<string, any>, Input extends Record<string, any> = Output>(config?: FormConfig<Output, Input>): [Form, Fieldset<Input>];
 /**
  * A set of field configuration
  */
 export type Fieldset<Schema extends Record<string, any>> = {
-    [Key in keyof Schema]-?: FieldConfig<Schema[Key]>;
+    [Key in KeysOf<Schema>]-?: FieldConfig<ResolveType<Schema, Key>>;
 };
 export interface FieldsetConfig<Schema extends Record<string, any>> {
     /**
@@ -118,8 +154,7 @@ export interface FieldsetConfig<Schema extends Record<string, any>> {
 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>;
 /**
- * Returns a list of key and config, with a group of helpers
- * configuring buttons for list manipulation
+ * Returns a list of key and field config.
  *
  * @see https://conform.guide/api/react#usefieldlist
  */
@@ -149,4 +184,35 @@ export declare function useInputEvent<RefShape extends Exclude<any, FieldElement
     onSubmit?: (event: SubmitEvent) => void;
     onReset?: (event: Event) => void;
 }): [RefObject<RefShape>, InputControl];
+export declare const VALIDATION_UNDEFINED = "__undefined__";
+export declare const VALIDATION_SKIPPED = "__skipped__";
+export declare const FORM_ERROR_ELEMENT_NAME = "__form__";
+/**
+ * Validate the form with the Constraint Validation API
+ * @see https://conform.guide/api/react#validateconstraint
+ */
+export declare function validateConstraint(options: {
+    form: HTMLFormElement;
+    formData?: FormData;
+    constraint?: Record<Lowercase<string>, (value: string, context: {
+        formData: FormData;
+        attributeValue: string;
+    }) => boolean>;
+    acceptMultipleErrors?: ({ name, intent, payload, }: {
+        name: string;
+        intent: string;
+        payload: Record<string, any>;
+    }) => boolean;
+    formatMessages?: ({ name, validity, constraint, defaultErrors, }: {
+        name: string;
+        validity: ValidityState;
+        constraint: Record<string, boolean>;
+        defaultErrors: string[];
+    }) => string[];
+}): Submission;
+export declare function reportSubmission(form: HTMLFormElement, submission: Submission): void;
+/**
+ * Check if the current focus is on a intent button.
+ */
+export declare function isFocusedOnIntentButton(form: HTMLFormElement, intent: string): boolean;
 export {};