feat(conform-react): metadata customization (#1047)

Author: edmundhung

.changeset/rare-olives-kneel.md

@@ -0,0 +1,70 @@
+---
+'@conform-to/react': minor
+---
+
+Add metadata customization support to future `useForm` hook
+
+This update introduces a `<FormOptionsProvider />` component that allows users to define global form options, including custom metadata properties that match your form component types when integrating with UI libraries or any custom components:
+
+```tsx
+import {
+  FormOptionsProvider,
+  type BaseMetadata,
+} from '@conform-to/react/future';
+import { TextField } from './components/TextField';
+
+// Define custom metadata properties that matches the type of our custom form components
+function defineCustomMetadata<FieldShape, ErrorShape>(
+  metadata: BaseMetadata<FieldShape, ErrorShape>,
+) {
+  return {
+    get textFieldProps() {
+      return {
+        name: metadata.name,
+        defaultValue: metadata.defaultValue,
+        isInvalid: !metadata.valid,
+      } satisfies Partial<React.ComponentProps<typeof TextField>>;
+    },
+  };
+}
+
+// Extend the CustomMetadata interface with our implementation
+// This makes the custom metadata types available on all field metadata objects
+declare module '@conform-to/react/future' {
+  interface CustomMetadata<FieldShape, ErrorShape>
+    extends ReturnType<typeof defineCustomMetadata<FieldShape, ErrorShape>> {}
+}
+
+// Wrap your app with FormOptionsProvider
+<FormOptionsProvider
+  shouldValidate="onBlur"
+  defineCustomMetadata={defineCustomMetadata}
+>
+  <App />
+</FormOptionsProvider>;
+
+// Use custom metadata properties in your components
+function Example() {
+  const { form, fields } = useForm({
+    // shouldValidate now defaults to "onBlur"
+  });
+
+  return (
+    <form {...form.props}>
+      <TextField {...fields.email.textFieldProps} />
+    </form>
+  );
+}
+```
+
+Additionally, you can now customize the base error shape globally using the `CustomTypes` interface:
+
+```tsx
+declare module '@conform-to/react/future' {
+  interface CustomTypes {
+    errorShape: { message: string; code: string };
+  }
+}
+```
+
+This restricts the error shape expected from forms and improves type inference when using `useField` and `useFormMetadata`.

docs/api/react/future/FormOptionsProvider.md

@@ -0,0 +1,160 @@
+# FormOptionsProvider
+
+> The `FormOptionsProvider` component is part of Conform's future export. These APIs are experimental and may change in minor versions. [Learn more](https://github.com/edmundhung/conform/discussions/954)
+
+A React component that provides global form options to all forms in your application.
+
+```tsx
+import { FormOptionsProvider } from '@conform-to/react/future';
+
+export default function App() {
+  return (
+    <FormOptionsProvider shouldValidate="onBlur" shouldRevalidate="onInput">
+      {/* Your app components */}
+    </FormOptionsProvider>
+  );
+}
+```
+
+## Props
+
+All props are optional. When a prop is not provided, it inherits the default value or from a parent `FormOptionsProvider` if nested.
+
+### `shouldValidate?: 'onSubmit' | 'onBlur' | 'onInput'`
+
+Determines when validation should run for the first time on a field. Default is `onSubmit`.
+
+This option sets the default validation timing for all forms in your application. Individual forms can override this by passing their own `shouldValidate` option to [useForm](./useForm.md).
+
+```tsx
+<FormOptionsProvider shouldValidate="onBlur">
+  {/* All forms will validate on blur by default */}
+</FormOptionsProvider>
+```
+
+### `shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput'`
+
+Determines when validation should run again after the field has been validated once. Default is the same as `shouldValidate`.
+
+This is useful when you want an immediate update after the user has interacted with a field. For example, validate on blur initially, but revalidate on every input after the first validation.
+
+```tsx
+<FormOptionsProvider shouldValidate="onBlur" shouldRevalidate="onInput">
+  {/* Validate on blur, but show live feedback after first validation */}
+</FormOptionsProvider>
+```
+
+### `defineCustomMetadata?: <FieldShape, ErrorShape>(metadata: BaseMetadata<FieldShape, ErrorShape>) => CustomMetadata`
+
+A function that defines custom metadata properties for your form fields. This is particularly useful when integrating with UI libraries or custom form components.
+
+```tsx
+import {
+  FormOptionsProvider,
+  type BaseMetadata,
+} from '@conform-to/react/future';
+import type { TextField } from './components/TextField';
+
+// Define custom metadata properties that matches the type of our custom form components
+function defineCustomMetadata<FieldShape, ErrorShape>(
+  metadata: BaseMetadata<FieldShape, ErrorShape>,
+) {
+  return {
+    get textFieldProps() {
+      return {
+        name: metadata.name,
+        defaultValue: metadata.defaultValue,
+        isInvalid: !metadata.valid,
+        errors: metadata.errors,
+      } satisfies Partial<React.ComponentProps<typeof TextField>>;
+    },
+  };
+}
+
+// Extend the CustomMetadata interface with our implementation
+// This makes the custom metadata types available on all field metadata objects
+declare module '@conform-to/react/future' {
+  interface CustomMetadata<FieldShape, ErrorShape>
+    extends ReturnType<typeof defineCustomMetadata<FieldShape, ErrorShape>> {}
+}
+
+// Wrap your app with FormOptionsProvider
+<FormOptionsProvider defineCustomMetadata={defineCustomMetadata}>
+  <App />
+</FormOptionsProvider>;
+```
+
+Once defined, custom metadata properties are available on all field metadata objects:
+
+```tsx
+function LoginForm() {
+  const { form, fields } = useForm({
+    // form options
+  });
+
+  return (
+    <form {...form.props}>
+      {/* TypeScript knows about textFieldProps! */}
+      <TextField {...fields.email.textFieldProps} />
+      <TextField {...fields.password.textFieldProps} />
+      <button>Login</button>
+    </form>
+  );
+}
+```
+
+### `intentName?: string`
+
+The name of the submit button field that indicates the submission intent. Default is `'__intent__'`.
+
+This is an advanced option. You typically don't need to change this unless you have conflicts with existing field names.
+
+### `serialize(value: unknown) => string | string[] | File | File[] | null | undefined`
+
+A custom serialization function for converting form data.
+
+This is an advanced option. You typically don't need to change this unless you have special serialization requirements.
+
+## Tips
+
+### Conditional metadata based on field shape
+
+You can use TypeScript's conditional types to restrict custom metadata based on the field shape:
+
+```tsx
+function defineCustomMetadata<FieldShape, ErrorShape>(
+  metadata: BaseMetadata<FieldShape, ErrorShape>,
+) {
+  return {
+    get dateRangePickerProps() {
+      // Only available for field with start and end properties
+      const rangeFields = metadata.getFieldset<{
+        start: string;
+        end: string;
+      }>();
+
+      return {
+        startName: rangeFields.start.name,
+        endName: rangeFields.end.name,
+        defaultValue: {
+          start: rangeFields.start.defaultValue,
+          end: rangeFields.end.defaultValue,
+        },
+        isInvalid: !metadata.valid,
+        errors: metadata.errors?.map((error) => `${error}`),
+      } satisfies Partial<React.ComponentProps<typeof DateRangePicker>>;
+    },
+  };
+}
+
+declare module '@conform-to/react/future' {
+  interface CustomMetadata<FieldShape, ErrorShape> {
+    // Make dateRangePickerProps only available if the field shape has start and end properties
+    dateRangePickerProps: FieldShape extends { start: string; end: string }
+      ? ReturnType<
+          typeof defineCustomMetadata<FieldShape, ErrorShape>
+        >['dateRangePickerProps']
+      : unknown;
+  }
+}
+```

docs/api/react/future/useField.md

@@ -78,6 +78,14 @@ Array of validation error messages for this field.
 
 Object containing errors for all touched subfields.
 
+### `ariaInvalid: boolean | undefined`
+
+Boolean value for the `aria-invalid` attribute. Indicates whether the field has validation errors for screen readers. This is `true` when the field has errors, `undefined` otherwise.
+
+### `ariaDescribedBy: string | undefined`
+
+String value for the `aria-describedby` attribute. Contains the `errorId` when the field is invalid, `undefined` otherwise. If you need to reference both help text and errors, merge with `descriptionId` manually (e.g., `${field.descriptionId} ${field.ariaDescribedBy}`).
+
 ### Validation Attributes
 
 HTML validation attributes automatically derived from schema constraints:
@@ -134,7 +142,8 @@ function FormField({ name, label, type = 'text' }: FieldProps) {
         min={field.min}
         max={field.max}
         step={field.step}
-        aria-describedby={field.errors ? field.errorId : undefined}
+        aria-invalid={field.ariaInvalid}
+        aria-describedby={field.ariaDescribedBy}
       />
 
       {field.errors && (

examples/chakra-ui/README.md

@@ -1,6 +1,45 @@
 # Chakra UI Example
 
-This example shows you how to integrate [chakra-ui](https://chakra-ui.com/docs/components) forms components with Conform.
+[Chakra UI](https://chakra-ui.com/) is a simple, modular and accessible component library that gives you the building blocks you need to build your React applications.
+
+This example demonstrates how to integrate Conform with Chakra UI using custom metadata.
+
+## Understanding the Integration
+
+The main application ([`App.tsx`](./src/App.tsx)) uses explicit prop assignment for educational purposes, making it easy to see how field metadata maps to Chakra UI component props:
+
+```tsx
+<Input
+  name={fields.text.name}
+  defaultValue={fields.text.defaultValue}
+  isInvalid={!fields.text.valid}
+/>
+```
+
+While this is clear and straightforward for learning, it becomes repetitive in production applications.
+
+## Custom Metadata
+
+The example also showcases metadata customization for a more DRY approach. Custom metadata properties are defined once in [`main.tsx`](./src/main.tsx) and provide type-safe props that match Chakra UI component types:
+
+```tsx
+// Define custom metadata once
+function defineCustomMetadata(metadata) {
+  return {
+    get inputProps() {
+      return {
+        name: metadata.name,
+        defaultValue: metadata.defaultValue,
+        isInvalid: !metadata.valid,
+      } satisfies Partial<React.ComponentProps<typeof Input>>;
+    },
+    // ... other component props
+  };
+}
+
+// Use with full type safety
+<Input {...fields.text.inputProps} />
+```
 
 ## Compatibility
 
@@ -22,6 +61,8 @@ This example shows you how to integrate [chakra-ui](https://chakra-ui.com/docs/c
 - PinInput
 - Slider
 
+## Demo
+
 <!-- sandbox src="/examples/chakra-ui" -->
 
 Try it out on [Stackblitz](https://stackblitz.com/github/edmundhung/conform/tree/main/examples/chakra-ui).