[docs][form] Add an example with React.useActionState

docs/src/app/(public)/(content)/react/components/form/demos/form-action/css-modules/index.module.css

@@ -0,0 +1,87 @@
+.Form {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  width: 100%;
+  max-width: 16rem;
+}
+
+.Field {
+  display: flex;
+  flex-direction: column;
+  align-items: start;
+  gap: 0.25rem;
+}
+
+.Label {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+  color: var(--color-gray-900);
+}
+
+.Input {
+  box-sizing: border-box;
+  padding-left: 0.875rem;
+  margin: 0;
+  border: 1px solid var(--color-gray-200);
+  width: 100%;
+  height: 2.5rem;
+  border-radius: 0.375rem;
+  font-family: inherit;
+  font-size: 1rem;
+  background-color: transparent;
+  color: var(--color-gray-900);
+
+  &:focus {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}
+
+.Error {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: var(--color-red-800);
+}
+
+.Button {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 2.5rem;
+  padding: 0 0.875rem;
+  margin: 0;
+  outline: 0;
+  border: 1px solid var(--color-gray-200);
+  border-radius: 0.375rem;
+  background-color: var(--color-gray-50);
+  font-family: inherit;
+  font-size: 1rem;
+  font-weight: 500;
+  line-height: 1.5rem;
+  color: var(--color-gray-900);
+  user-select: none;
+
+  @media (hover: hover) {
+    &:hover {
+      background-color: var(--color-gray-100);
+    }
+  }
+
+  &:active {
+    background-color: var(--color-gray-100);
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    color: var(--color-gray-400);
+    background-color: var(--color-gray-100);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--color-blue);
+    outline-offset: -1px;
+  }
+}

docs/src/app/(public)/(content)/react/components/form/demos/form-action/css-modules/index.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import { Field } from '@base-ui-components/react/field';
+import { Form } from '@base-ui-components/react/form';
+import styles from './index.module.css';
+
+interface FormState {
+  success: boolean;
+  serverErrors: { [fieldName: string]: string | undefined };
+}
+
+export default function ActionStateForm() {
+  const [state, formAction, loading] = React.useActionState<FormState, FormData>(submitForm, {
+    success: false,
+    serverErrors: {},
+  });
+
+  return (
+    <Form className={styles.Form} action={formAction}>
+      <Field.Root name="username" className={styles.Field}>
+        <Field.Label className={styles.Label}>Username</Field.Label>
+        <Field.Control
+          type="username"
+          required
+          defaultValue="admin"
+          placeholder="e.g. alice132"
+          className={styles.Input}
+        />
+        <Field.Error className={styles.Error} />
+
+        <Field.Error match={!!state.serverErrors.username}>
+          {state.serverErrors.username}
+        </Field.Error>
+      </Field.Root>
+      <button disabled={loading} type="submit" className={styles.Button}>
+        Submit
+      </button>
+    </Form>
+  );
+}
+
+async function submitForm(_previousState: FormState, formData: FormData) {
+  // Mimic a server response
+  await new Promise((resolve) => {
+    setTimeout(resolve, 1000);
+  });
+
+  try {
+    const username = formData.get('username') as string | null;
+
+    if (username === 'admin') {
+      return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
+    }
+
+    // 50% chance the username is taken
+    const success = Math.random() > 0.5;
+
+    if (!success) {
+      return {
+        success: false,
+        serverErrors: { username: `${username} is unavailable` },
+      };
+    }
+  } catch {
+    return { success: false, serverErrors: { username: 'A server error has occurred' } };
+  }
+
+  return { success: true, serverErrors: {} };
+}

docs/src/app/(public)/(content)/react/components/form/demos/form-action/index.ts

@@ -0,0 +1,3 @@
+'use client';
+export { default as CssModules } from './css-modules';
+export { default as Tailwind } from './tailwind';

docs/src/app/(public)/(content)/react/components/form/demos/form-action/tailwind/index.tsx

@@ -0,0 +1,71 @@
+import * as React from 'react';
+import { Field } from '@base-ui-components/react/field';
+import { Form } from '@base-ui-components/react/form';
+
+interface FormState {
+  success: boolean;
+  serverErrors: { [fieldName: string]: string | undefined };
+}
+
+export default function ActionStateForm() {
+  const [state, formAction, loading] = React.useActionState<FormState, FormData>(submitForm, {
+    success: false,
+    serverErrors: {},
+  });
+
+  return (
+    <Form className="flex w-full max-w-64 flex-col gap-4" action={formAction}>
+      <Field.Root name="username" className="flex flex-col items-start gap-1">
+        <Field.Label className="text-sm font-medium text-gray-900">Username</Field.Label>
+        <Field.Control
+          type="username"
+          required
+          defaultValue="admin"
+          placeholder="e.g. alice132"
+          className="h-10 w-full rounded-md border border-gray-200 pl-3.5 text-base text-gray-900 focus:outline focus:outline-2 focus:-outline-offset-1 focus:outline-blue-800"
+        />
+        <Field.Error className="text-sm text-red-800" />
+
+        <Field.Error className="text-sm text-red-800" match={!!state.serverErrors.username}>
+          {state.serverErrors.username}
+        </Field.Error>
+      </Field.Root>
+      <button
+        disabled={loading}
+        type="submit"
+        className="flex h-10 items-center justify-center rounded-md border border-gray-200 bg-gray-50 px-3.5 text-base font-medium text-gray-900 select-none hover:bg-gray-100 focus-visible:outline focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-blue-800 active:bg-gray-100 disabled:cursor-not-allowed disabled:bg-gray-100 disabled:text-gray-400"
+      >
+        Submit
+      </button>
+    </Form>
+  );
+}
+
+async function submitForm(_previousState: FormState, formData: FormData) {
+  // Mimic a server response
+  await new Promise((resolve) => {
+    setTimeout(resolve, 1000);
+  });
+
+  try {
+    const username = formData.get('username') as string | null;
+
+    if (username === 'admin') {
+      return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
+    }
+
+    // 50% chance the username is taken
+    const success = Math.random() > 0.5;
+
+    if (!success) {
+      return {
+        success: false,
+        serverErrors: { username: `${username} is unavailable` },
+      };
+    }
+  } catch {
+    return { success: false, serverErrors: { username: 'A server error has occurred' } };
+  }
+
+  return { success: true, serverErrors: {} };
+}

docs/src/app/(public)/(content)/react/components/form/page.mdx

@@ -32,6 +32,12 @@ import { Form } from '@base-ui-components/react/form';
 
 ## Examples
 
+### Submit with a Server Function
+
+Forms can be submitted with a [Server Function](https://react.dev/reference/react-dom/components/form#handle-form-submission-with-a-server-function) instead of `onSubmit`.
+
+<Demo path="./demos/form-action" />
+
 ### Using with Zod
 
 When parsing the schema using `schema.safeParse()`, the `z.flattenError(result.error).fieldErrors` data can be used to map the errors to each field's `name`.