@conform-to/react 0.9.1 → 1.0.0-pre.1

package/helpers.mjs

@@ -1,11 +1,11 @@
 import { objectSpread2 as _objectSpread2 } from './_virtual/_rollupPluginBabelHelpers.mjs';
-export { INTENT, VALIDATION_SKIPPED, VALIDATION_UNDEFINED } from '@conform-to/dom';
+import { INTENT, serializeIntents } from '@conform-to/dom';
 
 /**
- * Cleanup `undefined` from the dervied props
+ * Cleanup `undefined` from the result.
  * To minimize conflicts when merging with user defined props
  */
-function cleanup(props) {
+function simplify(props) {
   for (var key in props) {
     if (props[key] === undefined) {
       delete props[key];
@@ -13,99 +13,213 @@ function cleanup(props) {
   }
   return props;
 }
-function getFormElementProps(config) {
-  var _options$ariaAttribut, _config$error, _config$error2;
+
+/**
+ * Derives aria attributes of a form control based on the field metadata.
+ */
+function getAriaAttributes(metadata) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-  var hasAriaAttributes = (_options$ariaAttribut = options.ariaAttributes) !== null && _options$ariaAttribut !== void 0 ? _options$ariaAttribut : true;
-  return cleanup({
-    id: config.id,
-    name: config.name,
-    form: config.form,
-    'aria-invalid': hasAriaAttributes && config.errorId && (_config$error = config.error) !== null && _config$error !== void 0 && _config$error.length ? true : undefined,
-    'aria-describedby': hasAriaAttributes ? [config.errorId && (_config$error2 = config.error) !== null && _config$error2 !== void 0 && _config$error2.length ? config.errorId : undefined, config.descriptionId && options.ariaAttributes !== false && options.description ? config.descriptionId : undefined].reduce((result, id) => {
-      if (!result) {
-        return id;
-      }
-      if (!id) {
-        return result;
-      }
-      return "".concat(result, " ").concat(id);
-    }) : undefined
+  if (typeof options.ariaAttributes !== 'undefined' && !options.ariaAttributes) {
+    return {};
+  }
+  var invalid = options.ariaInvalid === 'all' ? !metadata.allValid : !metadata.valid;
+  var ariaDescribedBy = typeof options.ariaDescribedBy === 'string' ? options.ariaDescribedBy : options.ariaDescribedBy ? metadata.descriptionId : undefined;
+  return simplify({
+    'aria-invalid': invalid || undefined,
+    'aria-describedby': invalid ? "".concat(metadata.errorId, " ").concat(ariaDescribedBy !== null && ariaDescribedBy !== void 0 ? ariaDescribedBy : '').trim() : ariaDescribedBy
   });
 }
-function getFormControlProps(config, options) {
-  return cleanup(_objectSpread2(_objectSpread2({}, getFormElementProps(config, options)), {}, {
-    required: config.required,
-    autoFocus: config.initialError && Object.entries(config.initialError).length > 0 ? true : undefined
-  }, options !== null && options !== void 0 && options.hidden ? hiddenProps : undefined));
+
+/**
+ * Derives the properties of a form element based on the form metadata,
+ * including `id`, `onSubmit`, `noValidate`, `aria-invalid` and `aria-describedby`.
+ *
+ * @example
+ * ```tsx
+ * <form {...getFormProps(metadata)} />
+ * ```
+ */
+function getFormProps(metadata, options) {
+  return simplify(_objectSpread2({
+    id: metadata.id,
+    onSubmit: metadata.onSubmit,
+    noValidate: metadata.noValidate
+  }, getAriaAttributes(metadata, options)));
 }
-var hiddenProps = {
-  /**
-   * Style to make the input element visually hidden
-   * Based on the `sr-only` class from tailwindcss
-   */
-  style: {
-    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) {
+
+/**
+ * Derives the properties of a fieldset element based on the field metadata,
+ * including `id`, `name`, `form`, `aria-invalid` and `aria-describedby`.
+ *
+ * @example
+ * ```tsx
+ * <fieldset {...getFieldsetProps(metadata)} />
+ * ```
+ */
+function getFieldsetProps(metadata, options) {
+  return simplify(_objectSpread2({
+    id: metadata.id,
+    name: metadata.name,
+    form: metadata.formId
+  }, getAriaAttributes(metadata, options)));
+}
+
+/**
+ * Derives common properties of a form control based on the field metadata,
+ * including `key`, `id`, `name`, `form`, `required`, `autoFocus`, `aria-invalid` and `aria-describedby`.
+ */
+function getFormControlProps(metadata, options) {
+  var _metadata$constraint;
+  return simplify(_objectSpread2({
+    key: metadata.key,
+    required: ((_metadata$constraint = metadata.constraint) === null || _metadata$constraint === void 0 ? void 0 : _metadata$constraint.required) || undefined,
+    autoFocus: !metadata.valid || undefined
+  }, getFieldsetProps(metadata, options)));
+}
+
+/**
+ * Derives the properties of an input element based on the field metadata,
+ * including common form control attributes like `key`, `id`, `name`, `form`, `autoFocus`, `aria-invalid`, `aria-describedby`
+ * and constraint attributes such as `type`, `required`, `minLength`, `maxLength`, `min`, `max`, `step`, `pattern`, `multiple`.
+ * Depends on the provided options, it will also set `defaultChecked` / `checked` if it is a checkbox or radio button,
+ * or otherwise `defaultValue` / `value`.
+ *
+ * @see https://conform.guide/api/react/get-input-props
+ * @example
+ * ```tsx
+ * // To setup an uncontrolled input
+ * <input {...getInputProps(metadata)} />
+ * // To setup an uncontrolled checkbox
+ * <input {...getInputProps(metadata, { type: 'checkbox' })} />
+ * // To setup an input without defaultValue
+ * <input {...getInputProps(metadata, { value: false })} />
+ * // To setup a radio button without defaultChecked state
+ * <input {...getInputProps(metadata, { type: 'radio', value: false })} />
+ * ```
+ */
+
+function getInputProps(metadata) {
+  var _metadata$constraint2, _metadata$constraint3, _metadata$constraint4, _metadata$constraint5, _metadata$constraint6, _metadata$constraint7, _metadata$constraint8;
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-  var props = _objectSpread2(_objectSpread2({}, getFormControlProps(config, options)), {}, {
+  var props = _objectSpread2(_objectSpread2({}, getFormControlProps(metadata, options)), {}, {
     type: options.type,
-    minLength: config.minLength,
-    maxLength: config.maxLength,
-    min: config.min,
-    max: config.max,
-    step: config.step,
-    pattern: config.pattern,
-    multiple: config.multiple
+    minLength: (_metadata$constraint2 = metadata.constraint) === null || _metadata$constraint2 === void 0 ? void 0 : _metadata$constraint2.minLength,
+    maxLength: (_metadata$constraint3 = metadata.constraint) === null || _metadata$constraint3 === void 0 ? void 0 : _metadata$constraint3.maxLength,
+    min: (_metadata$constraint4 = metadata.constraint) === null || _metadata$constraint4 === void 0 ? void 0 : _metadata$constraint4.min,
+    max: (_metadata$constraint5 = metadata.constraint) === null || _metadata$constraint5 === void 0 ? void 0 : _metadata$constraint5.max,
+    step: (_metadata$constraint6 = metadata.constraint) === null || _metadata$constraint6 === void 0 ? void 0 : _metadata$constraint6.step,
+    pattern: (_metadata$constraint7 = metadata.constraint) === null || _metadata$constraint7 === void 0 ? void 0 : _metadata$constraint7.pattern,
+    multiple: (_metadata$constraint8 = metadata.constraint) === null || _metadata$constraint8 === void 0 ? void 0 : _metadata$constraint8.multiple
   });
-  if (options.type === 'checkbox' || options.type === 'radio') {
-    var _options$value;
-    props.value = (_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : 'on';
-    props.defaultChecked = config.defaultValue === props.value;
-  } else if (options.type !== 'file') {
-    props.defaultValue = config.defaultValue;
+  if (typeof options.value === 'undefined' || options.value) {
+    if (options.type === 'checkbox' || options.type === 'radio') {
+      props.value = typeof options.value === 'string' ? options.value : 'on';
+      props.defaultChecked = typeof metadata.initialValue === 'boolean' ? metadata.initialValue : metadata.initialValue === props.value;
+    } else if (typeof metadata.initialValue === 'string') {
+      props.defaultValue = metadata.initialValue;
+    }
   }
-  return cleanup(props);
+  return simplify(props);
 }
-function select(config, options) {
-  return cleanup(_objectSpread2(_objectSpread2({}, getFormControlProps(config, options)), {}, {
-    defaultValue: config.defaultValue,
-    multiple: config.multiple
-  }));
+
+/**
+ * Derives the properties of a select element based on the field metadata,
+ * including common form control attributes like `key`, `id`, `name`, `form`, `autoFocus`, `aria-invalid`, `aria-describedby`
+ * and constraint attributes such as `required` or `multiple`.
+ * Depends on the provided options, it will also set `defaultValue` / `value`.
+ *
+ * @see https://conform.guide/api/react/get-select-props
+ * @example
+ * ```tsx
+ * // To setup an uncontrolled select
+ * <select {...getSelectProps(metadata)} />
+ * // To setup a select without defaultValue
+ * <select {...getSelectProps(metadata, { value: false })} />
+ * ```
+ */
+function getSelectProps(metadata) {
+  var _metadata$constraint9;
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var props = _objectSpread2(_objectSpread2({}, getFormControlProps(metadata, options)), {}, {
+    multiple: (_metadata$constraint9 = metadata.constraint) === null || _metadata$constraint9 === void 0 ? void 0 : _metadata$constraint9.multiple
+  });
+  if (typeof options.value === 'undefined' || options.value) {
+    props.defaultValue = Array.isArray(metadata.initialValue) ? metadata.initialValue.map(item => "".concat(item !== null && item !== void 0 ? item : '')) : metadata.initialValue;
+  }
+  return simplify(props);
 }
-function textarea(config, options) {
-  return cleanup(_objectSpread2(_objectSpread2({}, getFormControlProps(config, options)), {}, {
-    defaultValue: config.defaultValue,
-    minLength: config.minLength,
-    maxLength: config.maxLength
-  }));
+
+/**
+ * Derives the properties of a textarea element based on the field metadata,
+ * including common form control attributes like `key`, `id`, `name`, `form`, `autoFocus`, `aria-invalid`, `aria-describedby`
+ * and constraint attributes such as `required`, `minLength` or `maxLength`.
+ * Depends on the provided options, it will also set `defaultValue` / `value`.
+ *
+ * @see https://conform.guide/api/react/get-textarea-props
+ * @example
+ * ```tsx
+ * // To setup an uncontrolled textarea
+ * <textarea {...getTextareaProps(metadata)} />
+ * // To setup a textarea without defaultValue
+ * <textarea {...getTextareaProps(metadata, { value: false })} />
+ * ```
+ */
+function getTextareaProps(metadata) {
+  var _metadata$constraint10, _metadata$constraint11;
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var props = _objectSpread2(_objectSpread2({}, getFormControlProps(metadata, options)), {}, {
+    minLength: (_metadata$constraint10 = metadata.constraint) === null || _metadata$constraint10 === void 0 ? void 0 : _metadata$constraint10.minLength,
+    maxLength: (_metadata$constraint11 = metadata.constraint) === null || _metadata$constraint11 === void 0 ? void 0 : _metadata$constraint11.maxLength
+  });
+  if (typeof options.value === 'undefined' || options.value) {
+    props.defaultValue = metadata.initialValue;
+  }
+  return simplify(props);
 }
-function fieldset(config, options) {
-  return getFormElementProps(config, options);
+
+/**
+ * Derives the properties of a collection of checkboxes or radio buttons based on the field metadata,
+ * including common form control attributes like `key`, `id`, `name`, `form`, `autoFocus`, `aria-invalid`, `aria-describedby` and `required`.
+ *
+ * @see https://conform.guide/api/react/get-textarea-props
+ * @example
+ * ```tsx
+ * <fieldset>
+ *   {getCollectionProps(metadata, {
+ *     type: 'checkbox',
+ *     options: ['a', 'b', 'c']
+ *   }).map((props) => (
+ *     <div key={props.key}>
+ *       <label htmlFor={props.id}>{props.value}</label>
+ *       <input {...props} />
+ *     </div>
+ *  ))}
+ * </fieldset>
+ * ```
+ */
+function getCollectionProps(metadata, options) {
+  return options.options.map(value => {
+    var _metadata$key, _metadata$constraint12;
+    return simplify(_objectSpread2(_objectSpread2({}, getFormControlProps(metadata, options)), {}, {
+      key: "".concat((_metadata$key = metadata.key) !== null && _metadata$key !== void 0 ? _metadata$key : '').concat(value),
+      id: "".concat(metadata.id, "-").concat(value),
+      type: options.type,
+      value,
+      defaultChecked: typeof options.value === 'undefined' || options.value ? options.type === 'checkbox' && Array.isArray(metadata.initialValue) ? metadata.initialValue.includes(value) : metadata.initialValue === value : undefined,
+      // The required attribute doesn't make sense for checkbox group
+      // As it would require all checkboxes to be checked instead of at least one
+      // It is overriden with `undefiend` so it could be cleaned up properly
+      required: options.type === 'checkbox' ? undefined : (_metadata$constraint12 = metadata.constraint) === null || _metadata$constraint12 === void 0 ? void 0 : _metadata$constraint12.required
+    }));
+  });
 }
-function collection(config, options) {
-  return options.options.map(value => cleanup(_objectSpread2(_objectSpread2({}, getFormControlProps(config, options)), {}, {
-    id: config.id ? "".concat(config.id, "-").concat(value) : undefined,
-    type: options.type,
-    value,
-    defaultChecked: options.type === 'checkbox' && Array.isArray(config.defaultValue) ? config.defaultValue.includes(value) : config.defaultValue === value,
-    // The required attribute doesn't make sense for checkbox group
-    // As it would require all checkboxes to be checked instead of at least one
-    // overriden with `undefiend` so it gets cleaned up
-    required: options.type === 'checkbox' ? undefined : config.required
-  })));
+function getControlButtonProps(formId, intents) {
+  return {
+    name: INTENT,
+    value: serializeIntents(intents),
+    form: formId,
+    formNoValidate: true
+  };
 }
 
-export { collection, fieldset, hiddenProps, input, select, textarea };
+export { getAriaAttributes, getCollectionProps, getControlButtonProps, getFieldsetProps, getFormControlProps, getFormProps, getInputProps, getSelectProps, getTextareaProps };

package/hooks.d.ts

@@ -1,208 +1,42 @@
-import { type FieldConstraint, type FieldElement, type FieldsetConstraint, type Submission, type KeysOf, type ResolveType, getFormEncType, getFormMethod, parseIntent } from '@conform-to/dom';
-import { type FormEvent, type RefObject } from 'react';
-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[]>;
-    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>> : unknown extends Schema ? any : Record<string, any> extends Schema ? {
-    [Key in KeysOf<Schema>]?: FieldValue<ResolveType<Schema, Key>>;
-} : any;
-type SubmissionResult = {
-    intent: Submission['intent'];
-    payload: Submission['payload'] | null;
-    error: Submission['error'];
-};
-export interface FormConfig<Output extends Record<string, any>, Input extends Record<string, any> = Output> {
+import { type FormId, type FieldName, type FormOptions } from '@conform-to/dom';
+import { useEffect } from 'react';
+import { type FormMetadata, type FieldMetadata, type Pretty } from './context';
+/**
+ * useLayoutEffect is client-only.
+ * This basically makes it a no-op on server
+ */
+export declare const useSafeLayoutEffect: typeof useEffect;
+export declare function useFormId<Schema extends Record<string, unknown>, Error>(preferredId?: string): FormId<Schema, Error>;
+export declare function useNoValidate(defaultNoValidate?: boolean): boolean;
+export declare function useForm<Schema extends Record<string, any>, Error = string[], Value = Schema>(options: Pretty<FormOptions<Schema, Error, Value> & {
     /**
      * If the form id is provided, Id for label,
      * input and error elements will be derived.
      */
     id?: string;
     /**
-     * A form ref object. Conform will fallback to its own ref object if it is not provided.
-     */
-    ref?: RefObject<HTMLFormElement>;
-    /**
-     * Define when conform should start validation.
-     * Support "onSubmit", "onInput", "onBlur".
-     *
-     * @default "onSubmit"
-     */
-    shouldValidate?: 'onSubmit' | 'onBlur' | 'onInput';
-    /**
-     * Define when conform should revalidate again.
-     * Support "onSubmit", "onInput", "onBlur".
-     *
-     * @default shouldValidate, or "onSubmit" if shouldValidate is not provided.
-     */
-    shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput';
-    /**
-     * An object representing the initial value of the form.
-     */
-    defaultValue?: FieldValue<Input>;
-    /**
-     * An object describing the result of the last submission
-     */
-    lastSubmission?: SubmissionResult | null;
-    /**
-     * An object describing the constraint of each field
-     */
-    constraint?: FieldsetConstraint<Input>;
-    /**
-     * Enable native validation before hydation.
-     *
-     * Default to `false`.
-     */
-    fallbackNative?: boolean;
-    /**
-     * Accept form submission regardless of the form validity.
+     * Enable constraint validation before the dom is hydated.
      *
-     * Default to `false`.
-     */
-    noValidate?: boolean;
-    /**
-     * A function to be called when the form should be (re)validated.
-     */
-    onValidate?: ({ form, formData, }: {
-        form: HTMLFormElement;
-        formData: FormData;
-    }) => Submission | Submission<Output>;
-    /**
-     * The submit event handler of the form. It will be called
-     * only when the form is considered valid.
+     * Default to `true`.
      */
-    onSubmit?: (event: FormEvent<HTMLFormElement>, context: {
-        formData: FormData;
-        submission: Submission;
-        action: string;
-        encType: ReturnType<typeof getFormEncType>;
-        method: ReturnType<typeof getFormMethod>;
-    }) => void;
-}
-/**
- * Properties to be applied to the form element
- */
-interface FormProps {
-    id?: string;
-    ref: RefObject<HTMLFormElement>;
-    onSubmit: (event: FormEvent<HTMLFormElement>) => void;
-    noValidate: boolean;
-    'aria-invalid'?: 'true';
-    'aria-describedby'?: string;
-}
-interface Form {
-    id?: string;
-    errorId?: string;
-    error: string | undefined;
-    errors: string[];
-    ref: RefObject<HTMLFormElement>;
-    props: FormProps;
-}
-/**
- * Returns properties required to hook into form events.
- * Applied custom validation and define when error should be reported.
- *
- * @see https://conform.guide/api/react#useform
- */
-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> | undefined> = {
-    [Key in KeysOf<Schema>]-?: FieldConfig<ResolveType<Schema, Key>>;
+    defaultNoValidate?: boolean;
+}>): {
+    meta: FormMetadata<Schema, Error>;
+    fields: ReturnType<FormMetadata<Schema, Error>['getFieldset']>;
+};
+export declare function useFormMetadata<Schema extends Record<string, any>, Error>(options: {
+    formId: FormId<Schema, Error>;
+    defaultNoValidate?: boolean;
+}): FormMetadata<Schema, Error>;
+export declare function useField<FormSchema extends Record<string, unknown>, FieldSchema = FormSchema, Error = unknown>(options: {
+    formId: FormId<FormSchema, Error>;
+    name: FieldName<FieldSchema>;
+} | {
+    formId: FormId<FormSchema, Error>;
+    name?: undefined;
+}): {
+    meta: FieldMetadata<FieldSchema, Error, FormSchema>;
+    fields: FieldMetadata<FieldSchema, Error, FormSchema>['getFieldset'] extends Function ? ReturnType<FieldMetadata<FieldSchema, Error, FormSchema>['getFieldset']> : never;
+    list: FieldMetadata<FieldSchema, Error, FormSchema>['getFieldList'] extends Function ? ReturnType<FieldMetadata<FieldSchema, Error, FormSchema>['getFieldList']> : never;
+    form: FormMetadata<FormSchema, Error>;
 };
-export interface FieldsetConfig<Schema extends Record<string, any> | undefined> {
-    /**
-     * 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?: Record<string, string[]>;
-    /**
-     * 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;
-}
-/**
- * Returns all the information about the fieldset.
- *
- * @see https://conform.guide/api/react#usefieldset
- */
-export declare function useFieldset<Schema extends Record<string, any> | undefined>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config: FieldsetConfig<Schema>): Fieldset<Schema>;
-export declare function useFieldset<Schema extends Record<string, any> | undefined>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config: FieldConfig<Schema>): Fieldset<Schema>;
-/**
- * Returns a list of key and field config.
- *
- * @see https://conform.guide/api/react#usefieldlist
- */
-export declare function useFieldList<Schema extends Array<any> | undefined>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config: FieldConfig<Schema>): Array<{
-    key: string;
-} & FieldConfig<Schema extends Array<infer Item> ? Item : never>>;
-interface InputControl {
-    change: (eventOrValue: {
-        target: {
-            value: string;
-        };
-    } | string | boolean) => void;
-    focus: () => void;
-    blur: () => 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(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;
-}): InputControl;
-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>;
-    formatMessages?: ({ name, validity, constraint, defaultErrors, }: {
-        name: string;
-        validity: ValidityState;
-        constraint: Record<string, boolean>;
-        defaultErrors: string[];
-    }) => string[];
-}): Submission;
-export declare function getUniqueKey(): string;
-export declare function reportSubmission(form: HTMLFormElement, submission: SubmissionResult): void;
-export declare function getScope(intent: ReturnType<typeof parseIntent>): string | null;
-export {};