FormState Guide

npm install react react-dom zod
npm install github:dstarosta/FormState#v1.0.0

import { useFormState, z } from 'form-state';

// eslint.config.js
import { defineConfig } from 'eslint/config';
import formStatePlugin from 'form-state/eslint';

export default defineConfig([
  {
    extends: [
      // ... your other configs
      formStatePlugin.configs.recommended,
    ],
    rules: {},
  },
]);

rules: {
  'form-state/avoid-input-password': 'error',
}

import { getState } from 'form-state';

const address1Zip = getState(formSchema, data, (path) => path.addresses[0].zipCode);

import { createState } from 'form-state';

const data = createState(schema);

// Override some default property values with a partial initial state object.
const data = createState(schema, { name: 'John', info: { age: 24 } });

import { updateState } from 'form-state';

const updatedTags = updateState(data.tags, (draft) => {
  draft.push('Important'); // can be a complex array/object structure
});

formActions.change('tags', updatedTags);

import { createSymbol } from 'form-state';

// Duplicate an existing note with a fresh identity
const duplicated = {
  ...formState.data.notes[0],
  uniqueId: createSymbol(),
};

formActions.array.append((path) => path.notes, duplicated);

import { type FormPath } from 'form-state';

// A component that displays an error for any field
function FormError<T>({
  path,
  errors,
}: {
  path: FormPath<T>;
  errors: FormState<T>['errors'];
}) {
  const message = errors.get(path as (p: T) => unknown);
  return message ? <p className="error">{message}</p> : null;
}

// Caller — the compiler checks the path against FormSchema
<FormError path={(path: FormSchema) => path.info.age} errors={formState.errors} />

import { type FormState } from 'form-state';

// Debounce callback — typed state snapshot
function NoteTextInput({
  index,
  callback,
}: {
  index: number;
  callback?: (state: FormState<FormSchema>) => void;
}) {
  const { formActions } = useSchemaFormState();

  return (
    <input
      onChange={(e) =>
        formActions.change((path) => path.notes[index].text, e.target.value, {
          debounceIntervalMs: 500,
          callback,           // fires after debounce with latest FormState
          touch: true,
        })
      }
    />
  );
}

import { type FormMode } from 'form-state';

type ModeSelectorProps = {
  mode: FormMode;
  onChange: (mode: FormMode) => void;
};

// The compiler rejects anything that is not a valid mode string
formActions.setMode('readOnly');   // ✅
formActions.setMode('published');  // ❌ Type error

import { type SubmitState } from 'form-state';

const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) {
    // state.errors is Record<string, string>
    // state.data is DeepPartial<FormSchema> — may have empty/invalid fields
    return state.errors;
  }

  // state.data is fully typed FormSchema here — no cast needed
  await api.save(state.data.name);   // string, not string | ''
  await api.save(state.data.age);    // number, not number | ''
  return true;
};

import { type SubmitSuccessState } from 'form-state';

function App() {
  const handleFormSubmit = ({ data, formData }: SubmitSuccessState<FormSchema>) => {
    // data is fully typed FormSchema
    const output = formData.get('output');
    if (output === 'redirect') {
      router.push('/done');
    } else {
      showDialog({ data, formData });
    }
  };

  return <AppForm onSubmitted={handleFormSubmit} />;
}

import { type SchemaDataObject } from 'form-state';

// Component that displays clean API-ready data
function JsonData({ data }: { data: SchemaDataObject<FormSchema> }) {
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

// Usage
<JsonData data={schema.toObject(formState.data)} />

import { type StateChangeListener } from 'form-state';

// Defined outside the component
const listener: StateChangeListener<FormSchema> = ({ type, data, submitCount }) => {
  if (type === 'submit') {
    analytics.track('form_submit', { count: submitCount, name: data.name });
  }
};

// In the component
formHooks.useListener(listener);

import { type Group } from 'form-state';

// A section component that receives one group's bundle as a prop
function ContactSection({ contact }: { contact: Group<FormSchema, 'contact'> }) {
  return (
    <fieldset>
      <legend>Contact</legend>
      <input value={contact.data.email} readOnly />
      <input value={contact.data.phone} readOnly />
      {/* contact.data.age — compile error: 'age' is not in the 'contact' group */}
    </fieldset>
  );
}

// Caller — getGroup() returns a value assignable to the Group prop
<ContactSection contact={formState.getGroup('contact')} />

import { type DeepPartial } from 'form-state';

const { data: draft } = useQuery<DeepPartial<FormSchema>>({
  queryKey: ['draft', draftId],
  queryFn:  () => api.getDraft(draftId),
});

// Pass it directly as initialData — no need to fill in every field
const { formState, formActions } = useFormState(schema, {
  initialData: draft,
});

type FormClassCallback = (state: FormClassState) => FormClassValue;

type FormClassValue =
  | string
  | Record<string, boolean | null | undefined>
  | readonly FormClassValue[]
  | false
  | null
  | undefined;

import { type FormClassCallback } from 'form-state';

// Shared field styling — defined once, reused across forms.
const fieldClasses: FormClassCallback = ({ isError, isTouched, mode }) => [
  'block w-full rounded border px-3 py-2',
  mode === 'disabled' && 'bg-slate-100 text-slate-400 cursor-not-allowed',
  isError && isTouched && 'border-red-400 bg-red-50/50',
];

// Apply per call.
<input className={formClasses('name', fieldClasses)} />

// Or as the form-level default.
useFormState(schema, { cssOptions: { classNames: fieldClasses } });

MIT License

Copyright (c) 2026 Dmitry Starosta

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

import { z } from 'form-state';

const schema = z.strictObject({
  // Required string with custom error and extra validators
  name: z
    .formString(
      { required: true, error: 'Name is required' },
      z.regex(/^[\w\s'-]+$/, 'Name contains invalid characters'),
      z.maxLength(50, 'Name must be 50 characters or less')
    )
    .with(z.describe('Full Name')),

  // Optional number with range constraints
  age: z
    .formNumber(z.gte(0, 'Age must be positive'), z.lte(150, 'Age is out of range'))
    .with(z.describe('Age')),

  // Date with a specific display format
  birthDate: z
    .formDate(
      { dateFormat: 'MM/dd/yyyy' },
      z.gte(new Date(1900, 0, 1), 'Date too far in the past')
    )
    .with(z.describe('Birth Date')),

  // Enum — only these string literals are valid
  status: z.formValues(['active', 'inactive', 'pending']).with(z.describe('Status')),

  // Boolean without an empty string value
  isAdmin: z.formBoolean({ required: true }).with(z.describe('Admin')),

  // Array of strings with length limits
  tags: z.formArray(z.string(), { minLength: 0, maxLength: 10 }).with(z.describe('Tags')),
});

type Schema = z.infer<typeof schema>;
/*
{
  name: string;
  age: number | '';
  birthDate: Date | '';
  status: 'active' | 'inactive' | 'pending' | '';
  isAdmin: boolean;
  tags: string[];
}
*/

const schema = z
  .strictObject({
    priority: z.formBoolean(),
    notes: z.formArray(
      z.object({ typeId: z.formNumber(), text: z.formString() })
    ),
  })
  .check(
    z.validate(
      (data) => data.priority || data.notes.every((note) => note.typeId !== 2),
      { path: 'priority', error: 'Priority must be set to allow priority notes.' }
    )
  );

// Optional string
z.formString()

// Required with custom error
z.formString({ required: true, error: 'Name is required' })

// Checks only — no options object needed
z.formString(z.maxLength(100, 'Too long'), z.regex(/^\w+$/, 'Letters only'))

// Required with options and checks
z.formString({ required: true, error: 'Required' }, z.maxLength(50))

// Strip empty strings from toObject() output
z.formString({ allowEmpty: false })

// Use built-in regex patterns from z.regexes instead of writing your own
z.formString({ required: true, error: 'Email is required' }, z.regex(z.regexes.email, 'Invalid email address'))
z.formString(z.regex(z.regexes.e164, 'Must be in international format, e.g. +12125551234'))

// Optional number
z.formNumber()

// Required with custom error
z.formNumber({ required: true, error: 'Age is required' })

// Checks only — no options object needed
z.formNumber(z.gte(0, 'Must be positive'), z.lte(150))

// Required with options and checks
z.formNumber({ required: true, error: 'Required' }, z.gte(18, 'Must be 18 or older'))

// Optional — value is boolean or ''
z.formBoolean()

// Required — must be a boolean
z.formBoolean({ required: true })

// Optional date — defaults to 'yyyy-MM-dd' parsing
z.formDate()

// Custom display format
z.formDate({ dateFormat: 'MM/dd/yyyy' })

// Required with custom format and range check
z.formDate(
  { required: true, dateFormat: 'MM/dd/yyyy', error: 'Date is required' },
  z.gte(new Date(1900, 0, 1), 'Date too far in the past')
)

// Checks only — no options object needed
z.formDate(z.gte(new Date(2000, 0, 1), 'Must be after year 2000'))

// Optional — 'active' | 'inactive' | 'pending' | ''
z.formValues(['active', 'inactive', 'pending'])

// Required — '' is invalid; type is 'active' | 'inactive' | 'pending'
z.formValues(['active', 'inactive', 'pending'], { required: true, error: 'Select a status' })

// Required array of strings
z.formArray(z.string())

// With length constraints
z.formArray(z.formString(), { minLength: 1, maxLength: 10, lengthError: 'Must have 1–10 tags' })

// Optional — may be undefined
z.formArray(z.formNumber(), { required: false })

// Shorthand — second argument is the error string
z.validate(
  (data) => data.endDate > data.startDate,
  'End date must be after start date'
)

// With path — error is stored under 'endDate'
z.validate(
  (data) => !data.endDate || data.endDate > data.startDate,
  { path: 'endDate', error: 'End date must be after start date' }
)

// With condition — skips this check when 'startDate' already has an error
z.validate(
  (data) => data.endDate > data.startDate,
  {
    condition: (errors) => !errors.some((e) => e.pathNotation === 'startDate'),
    path: 'endDate',
    error: 'End date must be after start date',
  }
)

// Attach to an object schema
const schema = z
  .strictObject({ startDate: z.formDate(), endDate: z.formDate() })
  .check(
    z.validate(
      (data) => !data.endDate || !data.startDate || data.endDate > data.startDate,
      { path: 'endDate', error: 'End date must be after start date' }
    )
  );

// Skip a complex validation when no relevant fields were changed.
const schema = z
  .strictObject({
    id: z.formString(),
    firstName: z.formString(),
    lastName: z.formString(),
  })
  .check(
    z.validate(
      (data, prevData, prevResult) => {
        if (
          prevResult !== undefined &&
          data.firstName === prevData?.firstName &&
          data.lastName === prevData.lastName
        ) {
          return prevResult;
        }

        // an intentionally over-complicated validation here
        let count = 0;
        for (const char of data.lastName) {
          count++;
        }
        for (const char of data.lastName) {
          count++;
        }
        return count <= 30;
      },
      { path: 'lastName', error: 'Full name must be 30 characters or less.' }
    )
  );

// Field-level async check — verify the username is not already taken.
// The default `skipWhen` (deep equality) automatically suppresses the
// network call when the input hasn't changed since the last committed pass.
const schema = z.object({
  username: z
    .formString({ required: true, error: 'Username is required' })
    .check(
      z.validateAsync(async (name) => {
        const res = await fetch(`/api/usernames/${encodeURIComponent(name)}`);
        const { available } = await res.json();
        return available;
      }, 'Username is already taken')
    ),
});

// Object-level async check with a condition gate and a custom skipWhen.
// Only the `sku` and `quantity` fields matter for the stock lookup, so the
// custom comparator ignores any other root-level changes.
const orderSchema = z
  .strictObject({
    sku: z.formString({ required: true }),
    quantity: z.formNumber({ required: true }),
    notes: z.formString(),
  })
  .check(
    z.validateAsync(
      async (order) => {
        const res = await fetch(`/api/stock?sku=${order.sku}&qty=${order.quantity}`);
        return res.ok;
      },
      {
        // Skip the network call until both fields parse cleanly.
        condition: (errors) => errors.length === 0,
        skipWhen: (a, b) =>
          b !== undefined && a.sku === b.sku && a.quantity === b.quantity,
        path: 'quantity',
        error: 'Not enough stock for the selected quantity',
      }
    )
  );

// Debounced async check — collapses keystroke bursts to a single network call
const usernameSchema = z.object({
  username: z
    .formString({ required: true })
    .check(
      z.validateAsync(
        async (name) => {
          const res = await fetch(`/api/usernames/${encodeURIComponent(name)}`);
          const { available } = await res.json();
          return available;
        },
        {
          path: 'username',
          error: 'Username is already taken',
          // Wait 400ms of inactivity before hitting the server.
          debounceMs: 400,
        }
      )
    ),
});

// Submit-only async check — the payment-method authorization is expensive
// and only meaningful right before submission. It is skipped on every
// change-driven validation and runs once when `formActions.validateAsync()`
// (or the submit flow) fires.
const paymentSchema = z.object({
  cardToken: z
    .formString({ required: true })
    .check(
      z.validateAsync(
        async (token) => {
          const res = await fetch(`/api/payments/authorize?token=${token}`);
          return res.ok;
        },
        {
          error: 'Card could not be authorized',
          submitOnly: true,
        }
      )
    ),
});

const schema = z.strictObject({
  participants: z.formArray(
    z.object({ role: z.formValues(['owner', 'member']), name: z.formString() })
  ).check(
    z.someItem(
      (item) => item.role === 'owner',
      'At least one participant must be an owner'
    )
  ),
});

const schema = z.strictObject({
  prices: z.formArray(z.formNumber()).check(
    z.everyItem((price) => price === '' || price > 0, 'All prices must be positive')
  ),
});

// Unique primitive strings — ignore blanks
z.formArray(z.formString()).check(
  z.uniqueItems(false, { error: 'Duplicate tag', ignoreValues: [''] })
)

// Unique by a property — error appears at the duplicate item's 'email' field
z.formArray(z.object({ email: z.formString(), name: z.formString() })).check(
  z.uniqueItems(false, {
    mapFn: (item) => item.email,
    elementPath: ['email'],
    error: 'Email must be unique',
    ignoreValues: [''],
  })
)

// Deep equality for object items
z.formArray(z.object({ x: z.formNumber(), y: z.formNumber() })).check(
  z.uniqueItems(true, { error: 'Duplicate coordinate' })
)

import { useFormState, z, convert } from 'form-state';

const STATUS_VALUES = ['active', 'inactive', 'pending'] as const;

const schema = z.strictObject({
  name: z.formString({ required: true, error: 'Name is required' }).with(z.describe('Name')),
  email: z.formString().with(z.describe('Email')),
  status: z.formValues(STATUS_VALUES).with(z.describe('Status')),
  isAdmin: z.formBoolean({ required: true }).with(z.describe('Admin')),
}).with(z.describe('Profile'));

export function ProfileForm() {
  const {
    formState,
    formStatus,
    formActions,
    formHandlers,
    formHooks,
    Form,
  } = useFormState(schema, {
    initialData: { name: 'Alice' },
  });

  const handleSubmit = formHandlers.handleSubmit(async (submitState) => {
    if (!submitState.valid) return submitState.errors;
    await saveProfile(submitState.data);
    return true;
  });

  return (
    <Form action={handleSubmit}>
      <h2>{formState.descriptions['']}</h2> {/* 'Profile' */}

      <label>
        {formState.descriptions.name}
        <input
          type="text"
          value={formState.data.name}
          onChange={(e) => formActions.change('name', e.target.value)}
          onBlur={() => formActions.touch('name')}
        />
        {formState.errors.name && <span>{formState.errors.name}</span>}
      </label>

      <label>
        {formState.descriptions.email}
        <input
          type="email"
          value={formState.data.email}
          onChange={(e) => formActions.change('email', e.target.value)}
        />
      </label>

      <label>
        {formState.descriptions.status}
        <select
          value={formState.data.status}
          onChange={(e) =>
            formActions.change('status', convert.toLiteral(e.target.value, STATUS_VALUES))
          }
          onBlur={() => formActions.touch('status')}
        >
          <option value="">Select status…</option>
          <option value="active">Active</option>
          <option value="inactive">Inactive</option>
          <option value="pending">Pending</option>
        </select>
        {formState.errors.status && <span>{formState.errors.status}</span>}
      </label>

      {/* Radio buttons — alternative rendering of the same field */}
      <fieldset onBlur={() => formActions.touch('status')}>
        <legend>{formState.descriptions.status}</legend>
        {STATUS_VALUES.map((status) => (
          <label key={status}>
            <input
              type="radio"
              value={status}
              checked={formState.data.status === status}
              onChange={(e) =>
                formActions.change('status', convert.toLiteral(e.target.value, STATUS_VALUES))
              }
            />
            {status}
          </label>
        ))}
        {formState.errors.status && <span>{formState.errors.status}</span>}
      </fieldset>

      <label>
        <input
          type="checkbox"
          checked={formState.data.isAdmin}
          onChange={(e) => formActions.change('isAdmin', e.target.checked)}
        />
        {formState.descriptions.isAdmin}
      </label>

      <button type="submit" disabled={formStatus.submitting}>
        {formStatus.submitting ? 'Saving…' : 'Save'}
      </button>
    </Form>
  );
}

const schema = z.strictObject({
  user: z.object({
    age: z.formNumber(),
    name: z.formString(),
  }),
});

const { formActions, formState } = useFormState(schema);

// ✅ Correct — TypeScript knows 'age' accepts number | ''
formActions.change((path) => path.user.age, 30);

// ✅ Correct — TypeScript knows 'name' accepts string
formActions.change((path) => path.user.name, 'Alice');

// ❌ Type error — 'user.age' is number | '', not string
formActions.change((path) => path.user.age, 'hello');

// ❌ Type error — 'user.typo' does not exist on the schema
formActions.change((path) => path.user.typo, 'value');

formState.data.name              // string
formState.data.age               // number | ''
formState.data.info.address.city // string (nested)
formState.data.tags              // string[]
formState.data.tags[0]           // string

// Top-level field — direct property access
formState.errors.name                              // 'Name is required' | undefined

// Nested field — use .get() with a path expression
formState.errors.get((path) => path.info.age)           // string | undefined
formState.errors.get((path) => path.notes[index].text)  // string | undefined

// Manual errors set via setError()
formState.errors.getManual('serverError')

// All current errors
formState.errors.getAll()    // string[]  — all messages
formState.errors.getKeys()   // string[]  — e.g. ['name', 'info.age']

// Direct access for top-level fields
formState.dirty.name            // true after first change
formState.touched.name          // true after blur / explicit touch call
formState.required.name         // derived from schema — never changes

// .get() for nested fields
formState.dirty.get((path) => path.info.address.city)
formState.touched.get((path) => path.notes[index].text)
formState.required.get((path) => path.info.age)

// Enumerate all keys that are currently truthy
formState.dirty.getKeys()       // ['name', 'info.age', ...]
formState.touched.getKeys()

// Get the full range object
const ageRange = formState.ranges.get((path) => path.age);
// { type: 'range', format: 'integer', min: 0, max: 150 }

// Direct min/max helpers accept both forms
formState.ranges.getMin('age')              // 0
formState.ranges.getMax((path) => path.age)      // 150
formState.ranges.getMax('name')             // 50  (string maxLength)

// Wire directly to input attributes
<input
  type="number"
  min={formState.ranges.getMin((path) => path.age)}
  max={formState.ranges.getMax((path) => path.age)}
/>
<input
  type="text"
  maxLength={formState.ranges.getMax('name')}
/>

// z.describe() values are available at runtime
formState.descriptions.name                         // 'Full Name'
formState.descriptions.get((path) => path.info.age) // 'Age'
formState.descriptions.get((path) => path.notes[0]) // 'Note'  (index normalised to [0])

// Patterns (from z.regex(), or z.formDate()) as raw strings for input[pattern]
formState.patterns.name                             // '^[\\w\\s\'-]+$'
formState.patterns.get((path) => path.info.id)      // '^\d+(-\d+)?$'
formState.patterns.get((path) => path.birthDate)    // 'yyyy-MM-dd'

// Use in JSX
<label>{formState.descriptions.get((path) => path.auto.modelId)}</label>

const payload = schema.toObject(formState.data);
// uuid symbols stripped, optional empty strings omitted
await api.post('/users', payload);

const schema = z.object({
  birthDate: z.formDate(z.date(), { format: 'MM-dd-yyyy' }),
  registeredOn: z.formDate(z.date(), { format: 'MM/dd/yyyy' }),
  updateDates: z.formArray(z.formDate(z.date())), // default 'yyyy-MM-dd'
});

schema.toObject(formState.data);
/*
{
  birthDate: '12-31-2020',
  registeredOn: '06/30/2020',
  updateDates: ['2019-12-12', '2020-04-15'],
}
*/

const schema = z.object({
  name: z.formString({ required: true }, z.maxLength(50)),
  age: z.formNumber(z.gte(0)),
  category: z.formValues(['standard', 'premium'], { required: true }),
  joined: z.formDate({ required: true, format: 'MM/dd/yyyy' }),
});

schema.toJSONSchema();
/*
{
  "type": "object",
  "properties": {
    "name":     { "type": "string", "minLength": 1, "maxLength": 50 },
    "age":      { "type": "number", "minimum": 0 },
    "category": { "type": "string", "enum": ["standard", "premium"] },
    "joined":   { "type": "string", "pattern": "^(0[1-9]|1[0-2])/(0[1-9]|[12]\\d|3[01])/\\d{4}$", "minLength": 1 }
  },
  "required": ["name", "category", "joined"]
}
*/

schema.toJSONSchema();      // pretty-printed (default)
schema.toJSONSchema(false); // compact, single line

<button type="submit" disabled={!formStatus.dirty || formStatus.submitting}>
  Save changes
</button>

{formStatus.valid === false && (
  <p>Please fix the errors above before saving.</p>
)}

const schema = z.strictObject({
  name: z.formString({ required: true }).with(z.describe('Full Name')),
  age:  z.formNumber(z.gte(0), z.lte(150)).with(z.describe('Age')),
  info: z.object({
    email: z.formString().with(z.describe('Email Address')),
  }),
});

// Top-level field — direct property access
<label htmlFor="name">{formState.descriptions.name}</label>

// Nested field — use .get() with a path expression
<label htmlFor="email">
  {formState.descriptions.get((path) => path.info.email)}
</label>

// Array item field — index is normalised to [0] in descriptions
<label>{formState.descriptions.get((path) => path.notes[0].text)}</label>

import { useFormState, z, convert } from "form-state";

const schema = z.strictObject({
  username: z
    .formString(z.minLength(3, 'Too short'), z.maxLength(20, 'Too long'))
    .with(z.describe('Username')),
  age: z
    .formNumber(z.gte(18, 'Must be 18+'), z.lte(120))
    .with(z.describe('Age')),
  birthDate: z
    .formDate({ dateFormat: 'yyyy-MM-dd' }, z.gte(new Date(1900, 0, 1)))
    .with(z.describe('Birth Date')),
  bio: z
    .formString(z.maxLength(500, 'Too long'))
    .with(z.describe('Bio')),
  tags: z
    .formArray(z.string(), { minLength: 1, maxLength: 5 })
    .with(z.describe('Tags')),
});

// ── Text input ─────────────────────────────────────────────────
<div>
  <label htmlFor="username">{formState.descriptions.username}</label>
  <input
    id="username"
    type="text"
    value={formState.data.username}
    minLength={formState.ranges.getMin('username')}   // 3
    maxLength={formState.ranges.getMax('username')}   // 20
    required={formState.required.username}
    onChange={(e) => formActions.change('username', e.target.value)}
    onBlur={() => formActions.touch('username')}
  />
</div>

// ── Number input ───────────────────────────────────────────────
<div>
  <label htmlFor="age">{formState.descriptions.age}</label>
  <input
    id="age"
    type="number"
    value={formState.data.age}
    min={formState.ranges.getMin('age')}              // 18
    max={formState.ranges.getMax('age')}              // 120
    required={formState.required.age}
    onChange={(e) => formActions.change('age', convert.toInt(e.target.value))}
    onBlur={() => formActions.touch('age')}
  />
</div>

// ── Date input ─────────────────────────────────────────────────
const rawDate = formState.data.birthDate;
const dateValue = rawDate instanceof Date ? formatDate(rawDate, 'yyyy-MM-dd') : rawDate;
const minDate = formState.ranges.getMin((path) => path.birthDate);
const minAttr = minDate instanceof Date ? formatDate(minDate, 'yyyy-MM-dd') : undefined;

<div>
  <label htmlFor="birthDate">{formState.descriptions.birthDate}</label>
  <input
    id="birthDate"
    type="date"
    value={dateValue}
    min={minAttr}
    onChange={(e) => formActions.change('birthDate', convert.toDate(e.target.value, { format: 'yyyy-MM-dd' }))}
    onBlur={() => formActions.touch('birthDate')}
  />
</div>

// ── Textarea ───────────────────────────────────────────────────
<div>
  <label htmlFor="bio">{formState.descriptions.bio}</label>
  <textarea
    id="bio"
    value={formState.data.bio}
    maxLength={formState.ranges.getMax('bio')}        // 500
    onChange={(e) => formActions.change('bio', e.target.value)}
  />
  <small>{formState.data.bio.length} / {formState.ranges.getMax('bio')}</small>
</div>

// ── Array length guard ─────────────────────────────────────────
<button
  onClick={() => formActions.array.append('tags', [''])}
  disabled={formState.data.tags.length >= (formState.ranges.getMax('tags') ?? Infinity)}
>
  Add tag {formState.data.tags.length} / {formState.ranges.getMax('tags')}
</button>

// Top-level field
formState.required.name                          // true | false

// Nested field
formState.required.get((path) => path.info.age)       // true | false

// In JSX — drives the attribute and the visible asterisk together
<label htmlFor="name">
  {formState.descriptions.name}
  {formState.required.name && <span> *</span>}
</label>
<input
  id="name"
  type="text"
  required={formState.required.name}
  value={formState.data.name}
  onChange={(e) => formActions.change('name', e.target.value)}
/>

// Top-level field
formState.patterns.id                            // "^\d+(-\d+)?$" | undefined

// Nested field
formState.patterns.get((path) => path.info.code)      // string | undefined

// Date field — returns the dateFormat (defaults to 'yyyy-MM-dd')
formState.patterns.get((path) => path.birthDate)      // 'MM-dd-yyyy'

// In JSX
<input
  type="text"
  value={formState.data.id}
  pattern={formState.patterns.id}
  title="Must be a number or number range, e.g. 10-20"
  onChange={(e) => formActions.change('id', e.target.value)}
/>

// Read — top-level and nested
formState.touched.name                           // boolean
formState.touched.get((path) => path.info.age)        // boolean

// Typical pattern: show error only after interaction
{formState.touched.name && formState.errors.name && (
  <span role="alert">{formState.errors.name}</span>
)}

// Set on blur (most common)
<input onBlur={() => formActions.touch('name')} />

// Set immediately on change — good for selects and checkboxes
formActions.change((path) => path.category, value, { touch: true });

// Touch a field programmatically without changing its value
formActions.touch('name');
formActions.touch((path) => path.notes[index].text);

// Touch without running validation (validation runs by default)
formActions.touch('name', { validate: false });

// Inspect which fields have been touched
formState.touched.getKeys()                      // ['name', 'info.age', ...]
formStatus.touched                               // true if any field is touched

function TextField({ name }: { name: keyof FormSchema }) {
  const { formState, formActions, formClasses } = useSchemaFormState();

  const label     = formState.descriptions[name];
  const value     = formState.data[name] as string;
  const error     = formState.errors[name];
  const touched   = formState.touched[name];
  const maxLength = formState.ranges.getMax(name);
  const minLength = formState.ranges.getMin(name);
  const pattern   = formState.patterns[name];
  const required  = formState.required[name];

  return (
    <div className={formClasses(name)}>
      <label htmlFor={name}>
        {label}
        {required && <span aria-hidden> *</span>}
      </label>
      <input
        id={name}
        type="text"
        value={value}
        minLength={minLength}
        maxLength={maxLength}
        pattern={pattern}
        required={required}
        aria-invalid={touched && Boolean(error)}
        aria-describedby={error ? `${name}-error` : undefined}
        onChange={(e) => formActions.change(name, e.target.value)}
        onBlur={() => formActions.touch(name)}
      />
      {touched && error && (
        <span id={`${name}-error`} role="alert">{error}</span>
      )}
      {maxLength && (
        <small>{value.length} / {maxLength}</small>
      )}
    </div>
  );
}

const schema = z.object({
  email: z.group(z.formString({ required: true }), 'contact'),
  phone: z.group(z.formString(), 'contact'),
  street: z.group(z.formString({ required: true }), 'address'),
  city: z.group(z.formString({ required: true }), 'address'),
  newsletter: z.formBoolean(),
});

const contact = formState.getGroup('contact');

contact.data.email;     // 'jane@example.com'
contact.errors.phone;   // error message, if any
contact.touched.email;  // true
contact.dirty.email;    // false
contact.required.email; // true

contact.dirtyGroup;   // false - none of the group fields are dirty
contact.touchedGroup; // true - at least one of the group fields has been touched
contact.validGroup;   // true - validates all the group fields

// Render a whole section from the bundle
<fieldset>
  <legend>Contact</legend>
  {Object.keys(contact.data).map((field) => (
    <div key={field}>
      <label htmlFor={field}>{contact.descriptions[field]}</label>
      <input
        type="text"
        id={field}
        value={contact.data[field]}
        onChange={(e) => formActions.change(field, e.target.value)}
        onBlur={() => formActions.touch(field)}
      />
      {contact.errors[field] && <span>{contact.errors[field]}</span>}
    </div>
  ))}
</fieldset>

// Append one or more items
formActions.array.append('tags', ['react', 'typescript']);
formActions.array.append((path) => path.notes, [{ text: '', typeId: '' }]);

// Insert at a specific position
formActions.array.insert('tags', 0, 'featured');

// Update item at index
formActions.array.update('tags', 1, 'updated-tag');

// Swap two items
formActions.array.swap('tags', 0, 2);

// Remove by index
formActions.array.remove('tags', 0);

// Remove by predicate
formActions.array.remove('tags', (tag) => tag === 'deprecated');
formActions.array.remove((path) => path.notes, (note) => note.text === '');

// Clear the array
formActions.array.clear('tags');

const schema = z.strictObject({
  notes: z.formArray(
    z.object({
      uniqueId: z.symbol(),      // auto UUID — use as React key
      typeId: z.formNumber({ required: true, error: 'Note type is required.' }),
      text: z.formString({ required: true }, z.maxLength(100)),
    }),
    { minLength: 2, maxLength: 5 }
  ),
});

// In your component:
{formState.data.notes.map((note, index) => (
  <div key={note.uniqueId.toString()}>
    <input
      value={note.text}
      onChange={(e) =>
        formActions.change((path) => path.notes[index].text, e.target.value, { touch: true })
      }
    />
    {formState.errors.get((path) => path.notes[index].text) && (
      <span>{formState.errors.get((path) => path.notes[index].text)}</span>
    )}
    <button onClick={() => formActions.array.remove('notes', index)}>
      Remove
    </button>
  </div>
))}

<button
  onClick={() => formActions.array.append('notes', [{ text: '', typeId: '' }])}
  disabled={formState.data.notes.length >= formState.ranges.getMax('notes')}
>
  Add note
</button>

// Validate the full schema
formActions.validate();

// Validate and mark as submitted on success
formActions.validate({ submit: true });

// Validate with a custom async check (e.g. server-side uniqueness)
formActions.validate(
  async () => {
    const taken = await api.checkUsername(formState.data.username);
    return taken ? { username: 'Username is already taken' } : true;
  },
  { submit: true }
);

const isValid = await formActions.validateAsync();

if (!isValid) {
  // Branch on isValid — formState.errors and formStatus.valid in this
  // closure are from the previous render and may not reflect the result.
  return;
}

<input
  value={formState.data.email}
  onChange={(e) => formActions.change('email', e.target.value)}
  onBlur={() => formActions.touch('email')}
/>

{/* Only shown after blur */}
{formState.touched.email && formState.errors.email && (
  <p className="error">{formState.errors.email}</p>
)}

// Select / dropdown — touch immediately on pick
formActions.change((path) => path.auto.modelId, selectedId, { touch: true });

// Checkbox — touch and validate on click
formActions.change((path) => path.priority, e.target.checked, { touch: true });

// Radio buttons — top-level string form is fine here
formActions.change('sendEmail', 'yes', { touch: true });

useFormState(schema, {
  initialData: existingRecord,
  initialTouched: ['name', 'email', (path) => path.info.age],
});

import { type SubmitState } from 'form-state';

const handleSubmit = formHandlers.handleSubmit(
  async (submitState: SubmitState<typeof schema>, formData: FormData) => {
    // Schema validation failed — return the error map
    if (!submitState.valid) {
      formActions.focusOnFirstError({ selectText: true });
      return submitState.errors;
    }

    // submitState.data is fully typed and validated here
    try {
      await fetch('/api/profile', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(submitState.data),
      });
      return true; // success
    } catch (err) {
      // Surface a form-level error under any key you choose (here: serverError)
      return { serverError: 'Something went wrong. Please try again.' };
    }
  },
  {
    onSuccess: ({ data, formData }: SubmitSuccessState<typeof schema>) => {
      router.push('/dashboard');
    },
    onError: (state, status) => {
      formActions.focusOnFirstError();
    },
  }
);

return <Form action={handleSubmit}>...</Form>;

formActions.focusOnFirstError({ selectText: true });

// Or focus a specific element
formActions.focus('email', { selectText: true });

// Focus only if the field has an error
formActions.focus('email', { errorKey: 'email' });

// Blur the currently focused element — useful to dismiss
// the on-screen keyboard on mobile after a successful submit,
// or to move focus out of the form before opening a modal.
formActions.blur();

const { formState, formStatus, formActions, formHandlers } = useFormState(schema);

const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault();

  formActions.validate(
    async () => {
      // Optional: async cross-field or server-side check
      const taken = await api.checkEmail(formState.data.email);
      return taken ? { email: 'Email already registered' } : true;
    },
    {
      submit: true,
      callback: (state, status) => {
        if (status.valid) {
          api.save(schema.toObject(state.data));
        } else {
          formActions.focusOnFirstError({ selectText: true });
        }
      },
    }
  );
};

return (
  <form
    noValidate
    onSubmit={handleSubmit}
    onReset={formHandlers.handleReset}
  >
    <input
      value={formState.data.name}
      onChange={(e) => formActions.change('name', e.target.value)}
      onBlur={() => formActions.touch('name')}
    />
    {formState.errors.name && <span>{formState.errors.name}</span>}

    <button type="submit" disabled={formStatus.submitting}>Save</button>
    <button type="reset">Reset</button>
  </form>
);

// name="email"
//   formData.get('email')
// name={inferName(path => path.info.age)}
//   formData.get('info["age"]')
// name={inferName(path => path.tags[0], 'dot')}
//   formData.get('tags.0')

const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) return state.errors;

  // Raw string from FormData — useful for fields outside the schema
  const redirectTo = formData.get('redirectTo') as string | null;
  const age        = formData.get('info["age"]') as string | null;

  await api.save(state.data);
  return true;
};

// Two submit buttons with the same name but different values
<Form action={handleSubmit}>
  <button name="action" value="save">Save draft</button>
  <button name="action" value="publish">Publish</button>
</Form>

// In your handler — formData always carries the clicked button's value
const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) return state.errors;

  const action = formData.get('action'); // 'save' | 'publish'

  if (action === 'publish') {
    await api.publish(state.data);
  } else {
    await api.saveDraft(state.data);
  }
  return true;
};

import { useFormStatus } from 'react-dom';

// Must be a child of the <form> element — not the same component
export function FormMask() {
  const { pending } = useFormStatus();

  if (!pending) return null;

  return (
    <div
      role="status"
      aria-label="Saving…"
      style={{
        position: 'absolute',
        inset: 0,
        display: 'grid',
        placeItems: 'center',
        background: 'rgba(0,0,0,0.4)',
        zIndex: 10,
      }}
    >
      <Spinner />
    </div>
  );
}

// Use it inside <Form>
<Form action={action} style={{ position: 'relative' }}>
  <FormMask />
  {/* ... */}
</Form>

import { formDataEncode } from 'form-state';

const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  if (!state.valid) return state.errors;

  // Encode all entries as a URL-encoded string
  const body = formDataEncode(formData).toString();
  // "name=Alice&info%5B%22age%22%5D=30"  (bracket notation — useFormState default)
  // "name=Alice&info.age=30"  (dot notation — pass 'dot' as nameFormat arg,
  //                            or use inferName(path, 'dot'))

  // Omit specific fields (e.g. internal tracking values)
  const bodyClean = formDataEncode(formData, ['csrf', 'action']).toString();

  await fetch('/api/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body,
  });
  return true;
};

const submission = formState.submittedData;

// populate the wizard, undo some changes, etc.

// Set by field key
formActions.setError('email', 'This email address is already registered');

// Set by path expression — nested field inside an array item
formActions.setError((path) => path.notes[index].text, '666 is not allowed as note text');

// Set a form-level error (arbitrary string key)
formActions.setError('serverError', 'Something went wrong. Please try again.');

// Clear a specific manual error (pass null, undefined, or call with one argument)
formActions.setError('email', null);
formActions.setError((path) => path.notes[index].text); // clears it

// Clear all manual errors
formActions.clearManualErrors();

// Clear only errors matching a predicate
formActions.clearManualErrors({
  predicate: (key) => key === 'serverError',
});

{formState.errors.getManual('serverError') && (
  <div className="form-error">
    {formState.errors.getManual('serverError')}
  </div>
)}

// Set initial mode
useFormState(schema, { initialMode: 'readOnly' });

// Switch at runtime
formActions.setMode('editable');
formActions.setMode('readOnly');
formActions.setMode('disabled');

const { formState, formStatus, formActions } = useSchemaFormState();
const { readOnly } = formStatus;

// ── Select / dropdown ──────────────────────────────────────────
{readOnly ? (
  <input
    type="text"
    readOnly
    tabIndex={-1}
    value={noteTypes.find((noteType) => noteType.value === note.typeId)?.label ?? ''}
    autoComplete="off"
  />
) : (
  <Select
    options={noteTypes}
    value={note.typeId}
    onChange={(opt) =>
      formActions.change((path) => path.notes[index].typeId, opt?.value ?? '', { touch: true })
    }
  />
)}

// ── Checkbox ───────────────────────────────────────────────────
{readOnly ? (
  <input
    type="text"
    readOnly
    tabIndex={-1}
    value={data.priority === true ? 'Yes' : data.priority === false ? 'No' : 'N/A'}
    autoComplete="off"
  />
) : (
  <input
    id="priority"
    type="checkbox"
    checked={Boolean(data.priority)}
    onChange={(e) => formActions.change((path) => path.priority, e.target.checked, { touch: true })}
  />
)}

// ── Radio buttons ──────────────────────────────────────────────
{readOnly ? (
  <input type="text" readOnly tabIndex={-1} value={data.sendEmail === 'yes' ? 'Yes' : 'No'} />
) : (
  <span role="group">
    <label>
      <input type="radio" value="yes"
        onChange={() => formActions.change('sendEmail', 'yes', { touch: true })} />
      Yes
    </label>
    <label>
      <input type="radio" value="no"
        onChange={() => formActions.change('sendEmail', 'no', { touch: true })} />
      No
    </label>
  </span>
)}

// ── Array controls ─────────────────────────────────────────────
{!readOnly && (
  <button onClick={() => formActions.array.remove((path) => path.notes, index)}>
    Remove
  </button>
)}
{!readOnly && (
  <button onClick={() => formActions.array.append('notes', [emptyNote])}>
    Add note
  </button>
)}

<Form
  action={formHandlers.handleSubmit(onSubmit)}
  data-readonly={formStatus.readOnly}  // CSS hook for styling
>
  <fieldset disabled={formStatus.disabled}>
    <IdInput />
    <NoteInputs />
    <AutoSelects />
    {!formStatus.readOnly && <Footer />}
  </fieldset>
</Form>

import { type FormMode } from 'form-state';

function ModeSelector({
  mode,
  onChange,
}: {
  mode: FormMode;
  onChange: (mode: FormMode) => void;
}) {
  return (
    <div>
      {(['editable', 'readOnly', 'disabled'] as FormMode[]).map((option) => (
        <label key={option}>
          <input
            type="radio"
            checked={mode === option}
            onChange={() => onChange(option)}
          />
          {option}
        </label>
      ))}
    </div>
  );
}

// In parent:
<ModeSelector
  mode={formStatus.mode}
  onChange={(m) => formActions.setMode(m)}
/>

// Generates e.g.: "form-state__required form-state__touched form-state__error"

<div className={formClasses('name')}>
  <label>Name</label>
  <input ... />
  <span>{formState.errors.name}</span>
</div>

// Arrow function path expression — works for nested fields too.
<label className={formClasses((path) => path.info.name)}>
  {formState.descriptions.get((path) => path.info.name)}
</label>

// Custom prefix per call.
formClasses('name', { prefix: 'my-form' });
// "my-form__required my-form__error"

// Just the prefix.
useFormState(schema, { cssOptions: { prefix: 'my-form' } });

// Prefix plus a static `classNames` string applied to every field.
useFormState(schema, {
  cssOptions: {
    prefix: 'my-form',
    classNames: 'block w-full rounded border px-3 py-2',
  },
});

// Prefix plus a callback driving classes from the field state.
useFormState(schema, {
  cssOptions: {
    prefix: 'my-form',
    classNames: ({ isError, isTouched }) =>
      isError && isTouched ? 'border-red-400' : 'border-zinc-300',
  },
});

const { formClasses } = useFormState(schema, {
  cssOptions: {
    prefix: 'my-form',
    classNames: ({ isError }) => ['field', isError && 'field--invalid'],
  },
});

formClasses('name');
// "my-form__required my-form__error field field--invalid"

formClasses('name', ({ isError }) => isError && 'field--server-error');
// "my-form__required my-form__error field--server-error"
// The per-call callback fully replaces the form-level `classNames`.

useFormState(schema, { cssOptions: { prefix: null } });

// 1) Static string — applied regardless of state.
<input className={formClasses('name', 'block w-full rounded border px-3 py-2')} />

// 2) Callback returning a string.
<input
  className={formClasses('name', ({ isError, isTouched }) =>
    isError && isTouched
      ? 'border-red-400 bg-red-50/50'
      : 'border-zinc-300 bg-white'
  )}
/>

// 3) Callback returning a clsx-style object.
<input
  className={formClasses('email', ({ isError, isTouched }) => ({
    'form-control': true,
    'is-invalid': isError && isTouched,
  }))}
/>

// 4) Callback returning an array (falsy entries are dropped).
<input
  className={formClasses('name', ({ isError, isTouched, mode }) => [
    'block w-full rounded border px-3 py-2',
    mode === 'disabled' && 'bg-slate-100 text-slate-400 cursor-not-allowed',
    mode === 'readOnly' && 'bg-slate-50 text-slate-600',
    isTouched && 'border-slate-400',
    isError && isTouched && 'ring-1 ring-red-500',
  ])}
/>

// 5) Options object — custom prefix plus a callback.
formClasses('name', {
  prefix: 'fld',
  classNames: ({ isError }) => ['field', isError && 'field--invalid'],
});
// e.g. "fld__required fld__error field field--invalid"

import { classNames } from 'form-state';

// String — returned as-is.
classNames('btn btn-primary');
// "btn btn-primary"

// Object — keys with truthy values are kept.
classNames({ 'btn': true, 'btn-primary': isPrimary, 'is-disabled': disabled });
// e.g. "btn btn-primary"

// Array — flattened recursively, falsy entries dropped.
classNames(['btn', isPrimary && 'btn-primary', { 'is-loading': loading }]);
// e.g. "btn btn-primary is-loading"

// Sequence — combine any mix of strings, objects, arrays, and falsy values.
classNames(
  'btn',
  isPrimary && 'btn-primary',
  { 'is-loading': loading, 'is-disabled': disabled },
  [size && `btn-${size}`, extraClass]
);
// e.g. "btn btn-primary is-loading btn-lg my-extra-class"

// Falsy input — returns an empty string.
classNames(null);
// ""

// No arguments — returns an empty string.
classNames();
// ""

// app-schema.ts
import { useFormStateContext, z } from 'form-state';

export const formSchema = z.strictObject({ /* ... */ });
export type FormSchema = z.infer<typeof formSchema>;

// One typed hook — used everywhere in the form tree
export const useSchemaFormState = () => useFormStateContext(formSchema);

// NameField.tsx — leaf component, no props needed
import { useSchemaFormState } from './app-schema';

export function NameField() {
  const { formState, formActions, formClasses } = useSchemaFormState();

  return (
    <div>
      <label className={formClasses((path) => path.info.name)}>
        {formState.descriptions.get((path) => path.info.name)}
      </label>
      <input
        type="text"
        value={formState.data.info.name}
        maxLength={formState.ranges.getMax((path) => path.info.name)}
        onChange={(e) => formActions.change((path) => path.info.name, e.target.value)}
        onBlur={() => formActions.touch((path) => path.info.name)}
      />
      {formState.errors.get((path) => path.info.name) && (
        <p>{formState.errors.get((path) => path.info.name)}</p>
      )}
    </div>
  );
}

// AppForm.tsx — root form component wrapped with formConnect
import { formConnect } from 'form-state';
import { formSchema } from './app-schema';

function AppForm({ onSubmitted }: { onSubmitted: () => void }) {
  const { Form, formHandlers } = useSchemaFormState();

  return (
    <Form action={formHandlers.handleSubmit(onSubmit, { onSuccess: onSubmitted })}>
      <fieldset>
        <NameField />
        <AgeField />
      </fieldset>
      <button type="submit">Save</button>
    </Form>
  );
}

export default formConnect({
  schema: formSchema,
  watch: true,  // enable useWatch
})(AppForm);

import { MaskedInput } from 'form-state';

<MaskedInput
  mask="(999) 999-9999"
  onChange={(event) => {
    formActions.change('phone', event.target.value);
    if (event.complete) {
      // Fires on the change that fills every required slot
    }
  }}
/>

<MaskedInput mask="99/99/9999" placeholder="DD/MM/YYYY" />

<MaskedInput mask="(999) 999-9999" placeholderChar=" " />

<MaskedInput
  mask="(999) 999-9999"
  onChange={(event) => {
    // event.target.value   = "(555) 123-4567"
    // event.unmaskedValue  = "5551234567"
    // event.complete       = true
  }}
  onBlur={(event) => {
    if (!event.complete) {
      formActions.touch('phone', { error: 'Please enter a full phone number' });
    }
  }}
/>

import { SecureInput } from 'form-state';

<SecureInput
  type="password"
  onSecureChange={(value) => {
    // 'value' is the real plaintext — never touches the DOM
    formActions.change('password', value);
  }}
  onSecureBlur={(value) => {
    formActions.change('password', value, { touch: true });
  }}
/>

// Define the callback at module level so it has a stable reference.
function onSearch(state: FormState<FormSchema>, status: FormStatus) {
  // Fires 400ms after the last keystroke
  performSearch(state.data.search);
}

formActions.change('search', inputValue, {
  debounceIntervalMs: 400,
  touch: true,
  callback: onSearch,
});

// Bracket format (default) — infers: info["age"]
formActions.inferName((path) => path.info.age)

// Dot format — infers: info.age
formActions.inferName((path) => path.info.age, 'dot')

// Top-level string — always just the key itself
formActions.inferName('name')

// Uncontrolled input + useWatch combo
<input
  name={formActions.inferName((path) => path.id)}
  defaultValue={formState.data.id}
  onChange={(e) => formActions.change((path) => path.id, e.target.value)}
/>

// useWatch subscribes by the same name string
const watched = formHooks.useWatch(formActions.inferName((path) => path.id));

// Reading back from FormData on submit
const onSubmit = async (state: SubmitState<FormSchema>, formData: FormData) => {
  // bracket key (default format)
  formData.get('info["age"]');    // value of info.age
  // dot key
  formData.get('info.age');       // only if that field used 'dot' format
};

const { Form, formActions } = useFormState(schema, {
  inferredNameFormat: 'dot', // all inferName calls default to dot notation
});

import { convert } from 'form-state';

// Optional number to number type conversion
convert.asNumber(1);          // 1
convert.asNumber('');         // 0
convert.asNumber('', 100.0);  // 100.0

// Safe numeric parsing — returns the number or '' if invalid
convert.toInt('42')          // 42
convert.toFloat('3.14')      // 3.14
convert.toInt('abc')         // ''

// Date to string type conversion
convert.asDateString('')                                 // ''
convert.asDateString('2022-01-01')                       // '2022-01-01'
convert.asDateString(new Date(2022, 0, 1))               // '2022-01-01'
convert.asDateString(new Date(2022, 0, 1), 'MM/dd/yyyy') // '01/01/2022'

// Date parsing with format string
convert.toDate('12/31/2024', { format: 'MM/dd/yyyy' })  // Date object

// Optional boolean to boolean type conversion
convert.asBoolean(true);      // true
convert.asBoolean('', false); // false
convert.asBoolean('', true);  // true

// Boolean coercion
convert.toBoolean('true')     // true
convert.toBoolean('0')        // false

// Validated literal — returns the value or '' if not in set
convert.toLiteral('active', ['active', 'inactive'])  // 'active'
convert.toLiteral('other',  ['active', 'inactive'])  // ''

import { formatDate } from 'form-state';

const date = formState.data.birthDate; // Date | ''

if (date instanceof Date) {
  formatDate(date, 'MM/dd/yyyy')   // '12/31/2024'
  formatDate(date, 'yyyy-MM-dd')   // '2024-12-31'
}

import { safeParseDate } from 'form-state';

const { success: startDateSuccess, date: startDate } = safeParseDate('2020-12-01'); // yyyy-MM-dd
// startDateSuccess: true
// startDate: new Date(2020, 11, 1)

const { date: endDate } = safeParseDate('12/31/2020', 'MM/dd/yyyy');

const { success: finalDateSuccess, date: finalDate } = safeParseDate('abcd1234', 'MM/dd/yyyy');
// finalDateSuccess: false
// finalDate: null

// Mark a file as pending upload
formActions.setDirty('#avatar', true);
formState.dirty.get('#avatar')   // true
formStatus.dirty                 // true (includes #avatar)

// Clear after upload completes
formActions.setDirty('#avatar', false);

import { parseState } from 'form-state';

const result = parseState(formSchema, apiResponse);

if (result.success) {
  formActions.replace(result.data);
} else {
  // result.errors.getAll() — array of validation messages
  // result.errors.getKeys() — failed field paths
  console.warn('API data has validation issues:', result.errors.getAll().join(' | '));
  // Still use the coerced data if errors are non-critical
  formActions.replace(result.data);
}

const { formState, formHooks } = useFormState(schema);

// Extract a field as-is
const selectName = formHooks.useSelector(state => state.name);

// Derive a boolean from a field
const selectIsAdult = formHooks.useSelector(
  state => state.age,
  age => typeof age === 'number' && age >= 18
);

selectName(formState.data)     // string
selectIsAdult(formState.data)  // boolean

// Filters the items array — reruns only when items changes
const selectActiveItems = formHooks.useSelector(
  state => state.items,
  items => items.filter(item => item.active)
);

// Counts the filtered list — reruns only when selectActiveItems output changes
const selectActiveCount = formHooks.useSelector(
  selectActiveItems,
  items => items.length
);

// Maps names — also reads from the already-filtered list
const selectActiveNames = formHooks.useSelector(
  selectActiveItems,
  items => items.map(item => item.name)
);

selectActiveCount(formState.data)  // number
selectActiveNames(formState.data)  // string[]

const schema = z.strictObject({
  orders: z.array(
    z.object({
      product: z.formString(),
      quantity: z.formNumber(),
      unitPrice: z.formNumber(),
      shipped: z.formBoolean(),
    })
  ),
  discountPct: z.formNumber(),
});

const { formState, formHooks } = useFormState(schema);

// Select unshipped orders
const selectPendingOrders = formHooks.useSelector(
  state => state.orders,
  orders => orders.filter(order => !order.shipped)
);

// Combine the filtered list with the discount to compute an order summary
const selectOrderSummary = formHooks.useSelector(
  [selectPendingOrders, state => state.discountPct], // array of selectors
  (pending, discountPct) => {
    const subtotal = pending.reduce((sum, o) => sum + o.quantity * o.unitPrice, 0);
    const discount = typeof discountPct === 'number' ? discountPct / 100 : 0;
    return {
      count: pending.length,
      subtotal,
      total: subtotal * (1 - discount),
    };
  }
);

const summary = selectOrderSummary(formState.data);
// { count: number; subtotal: number; total: number }

// Whole data slice for the 'contact' group
const selectContact = formHooks.useSelector('contact');
const contact = selectContact(formState.data);
// { email: string; phone: string }   (only the group's fields)

// Scoped selector — input is narrowed to the group's data
const selectEmailDomain = formHooks.useSelector('contact', (data) =>
  data.email.split('@')[1]
);
const domain = selectEmailDomain(formState.data);

// Group slice as the data source
const domainFromSlice = selectEmailDomain(formState.getGroup('contact').data);

// formHooks.useSelector('contact', (data) => data.age)
//   ^ compile error: 'age' is not in the 'contact' group

import { type StateChangeListener } from 'form-state';

const listener: StateChangeListener<FormSchema> = ({ type, data }) => {
  console.info(type, data);
};

function AppForm() {
  formHooks.useListener(listener);
  // ...
}

import { useState } from 'react';
import { type StateChangeListener } from 'form-state';

function UsernameForm() {
  const [validatingField, setValidatingField] = useState<string | null>(null);

  const listener: StateChangeListener<FormSchema> = (event) => {
    // `schemaPath` identifies which async refinement fired — match by the
    // refinement's attachment path so multiple async checks don't interfere.
    if (event.type === 'asyncValidating' && event.schemaPath === 'username') {
      setValidatingField('username');
    } else if (event.type === 'asyncValidated' && event.schemaPath === 'username') {
      setValidatingField(null);
    }
  };

  const { formHooks, formActions } = useFormState(schema);
  formHooks.useListener(listener);

  return (
    <label>
      Username
      <input
        name={formActions.inferName('username')}
        onChange={(e) => formActions.change('username', e.target.value)}
      />
      {validatingField === 'username' && <span>Checking availability…</span>}
    </label>
  );
}

// Enable watching at the hook / formConnect level
useFormState(schema, { watch: true });
// or: formConnect({ schema, watch: true })(MyForm)

// Watch a field by its inferName value, with an optional transform
const idValue = formHooks.useWatch(
  formActions.inferName((path) => path.id),
  (value) => value.trim()
);

// Use the live value to drive conditional rendering
{/^666(-\d*)?$/.test(idValue) && <DevilIcon />}

// Watch with a more complex transform — only keep valid values
const cleanId = formHooks.useWatch(
  formActions.inferName((path) => path.id),
  (val) => (/^\d+$|^(\d+-\d+)$/.test(val) ? val : '')
);

const { blockerState, guard, proceed, reset } = formHooks.useBlocker(
  (state, status) => status.dirty
);

import { useFormState } from 'form-state';
import { navigate } from 'router'; // whichever React router you use

const { formHooks } = useFormState(schema, { initialData });
const { blockerState, guard, proceed, reset } = formHooks.useBlocker(
  (state, status) => status.dirty
);

// Instead of navigating directly, go through the guard:
<button onClick={() => guard(() => navigate('/next'))}>Next</button>

// When a navigation is held, show your own confirmation UI:
{blockerState === 'blocked' && (
  <div role="alertdialog">
    <p>You have unsaved changes. Leave anyway?</p>
    <button onClick={proceed}>Leave</button>
    <button onClick={reset}>Stay</button>
  </div>
)}

import { useEffect } from 'react';
import { useFormState } from 'form-state';

const { formHooks } = useFormState(schema, { initialData });
const { blockerState, guard, proceed, reset } = formHooks.useBlocker(
  (state, status) => status.dirty
);

// Forward navigation: push through the guard instead of calling history directly.
const go = (url: string) => guard(() => history.pushState({}, '', url));

// Back / forward buttons: re-push the current URL, then guard the real move.
useEffect(() => {
  const onPopState = () => {
    history.pushState({}, '', location.href); // undo the browser's move first
    guard(() => history.back());              // then ask before actually leaving
  };
  window.addEventListener('popstate', onPopState);
  return () => window.removeEventListener('popstate', onPopState);
}, [guard]);

<button onClick={() => go('/next')}>Next</button>
{blockerState === 'blocked' && (
  <Confirm onYes={proceed} onNo={reset} />
)}

"use server";

import { parseState, z } from "form-state";
import { schema } from "./contact-form";

export async function submitContact(data: z.infer<typeof schema>) {
  const result = parseState(schema, data, true);

  if (!result.success) {
    throw new Error(result.errors.getAll().join(" | "));
  }

  await db.contacts.create({ data: result.data });

  return { success: true };
}

"use client";

import { useFormState, z } from "form-state";
import { submitContact } from "./actions/submit-contact";

const schema = z.object({
  name: z.formString({ required: true, error: "Name is required" }),
  email: z.formString(
    { required: true, error: "Email is required" },
    z.regex(z.regexes.email, "Enter a valid email"),
  ),
  message: z.formString(
    { required: true, error: "Message is required" },
    z.minLength(10, "Must be at least 10 characters"),
  ),
  agreeToTerms: z.formBoolean({ required: true, error: "Agreement is required" })
    .check(z.validate((v) => v === true, "You must agree to continue")),
});

export default function ContactForm() {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema);

  const handleSubmit = formHandlers.handleSubmit(async (state) => {
    if (!state.valid) {
      formActions.focusOnFirstError({ selectText: true });
      return {};
    }

    try {
      await submitContact(state.data);
    } catch (error) {
      return { serverError: error instanceof Error ? error.message : "Server error" };
    }

    return true;
  });

  return (
    <Form action={handleSubmit}>
      {errors.getManual("serverError") && (
        <p className="error">{errors.getManual("serverError")}</p>
      )}

      <label>
        Name
        <input
          type="text"
          name={formActions.inferName("name")}
          defaultValue={data.name}
          onBlur={(e) => formActions.change("name", e.target.value, { touch: true })}
        />
        {errors.name && <span>{errors.name}</span>}
      </label>

      <label>
        Email
        <input
          type="email"
          name={formActions.inferName("email")}
          defaultValue={data.email}
          onBlur={(e) => formActions.change("email", e.target.value, { touch: true })}
        />
        {errors.email && <span>{errors.email}</span>}
      </label>

      <label>
        Message
        <textarea
          name={formActions.inferName("message")}
          defaultValue={data.message}
          onBlur={(e) => formActions.change("message", e.target.value, { touch: true })}
        />
        {errors.message && <span>{errors.message}</span>}
      </label>

      <label>
        <input
          type="checkbox"
          name={formActions.inferName("agreeToTerms")}
          defaultChecked={data.agreeToTerms === true}
          onChange={(e) => formActions.change("agreeToTerms", e.target.checked, { touch: true })}
        />
        I agree to the terms
        {errors.agreeToTerms && <span>{errors.agreeToTerms}</span>}
      </label>

      <button type="submit" disabled={submitting}>
        {submitting ? "Sending…" : "Send"}
      </button>

      <button type="reset" disabled={!dirty}>
        Reset
      </button>
    </Form>
  );
}

// app/contact/page.tsx
import { parseState } from "form-state";
import ContactForm, { schema } from "./contact-form";

export default async function ContactPage() {
  const user = await db.users.findFirst({ where: { id: await getSessionUserId() } });
  const result = parseState(schema, user);

  if (!result.success) {
    throw new Error("Unexpected user data shape");
  }

  return <ContactForm user={result.data} />;
}

"use client";

import { useFormState, z } from "form-state";
import { submitContact } from "./actions/submit-contact";

// schema definition unchanged …

export default function ContactForm({
  user,
}: {
  user?: z.infer<typeof schema>;
}) {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema, { initialData: user });

  // … rest of the component unchanged
}

// app/routes/contact.ts
import type { Route } from "./+types/contact";
import { parseState, z } from "form-state";
import { schema } from "../contact-form";

export async function action({ request }: Route.ActionArgs) {
  const { data: formData } = await request.json() as { data: z.infer<typeof schema> };
  const result = parseState(schema, formData, true);

  if (!result.success) {
    return Response.json({ error: result.errors.getAll().join(" | ") }, { status: 400 });
  }

  await db.contacts.create({ data: result.data });

  return { success: true };
}

import { useFormState, z } from "form-state";

const schema = z.object({
  name: z.formString({ required: true, error: "Name is required" }),
  email: z.formString(
    { required: true, error: "Email is required" },
    z.regex(z.regexes.email, "Enter a valid email"),
  ),
  message: z.formString(
    { required: true, error: "Message is required" },
    z.minLength(10, "Must be at least 10 characters"),
  ),
  agreeToTerms: z.formBoolean({ required: true, error: "Agreement is required" })
    .check(z.validate((v) => v === true, "You must agree to continue")),
});

export default function ContactForm() {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema);

  const handleSubmit = formHandlers.handleSubmit(async (state) => {
    if (!state.valid) {
      formActions.focusOnFirstError({ selectText: true });
      return {};
    }

    // Without experimental RSC support, use fetch (or a client like Axios)
    // to call the route action.
    const res = await fetch("/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ data: state.data }),
    });

    if (!res.ok) {
      const error = await res.json() as Error;
      return { serverError: error?.message ?? "Server error" };
    }

    return true;
  });

  return (
    <Form action={handleSubmit}>
      {errors.getManual("serverError") && (
        <p className="error">{errors.getManual("serverError")}</p>
      )}

      <label>
        Name
        <input
          type="text"
          name={formActions.inferName("name")}
          defaultValue={data.name}
          onBlur={(e) => formActions.change("name", e.target.value, { touch: true })}
        />
        {errors.name && <span>{errors.name}</span>}
      </label>

      <label>
        Email
        <input
          type="email"
          name={formActions.inferName("email")}
          defaultValue={data.email}
          onBlur={(e) => formActions.change("email", e.target.value, { touch: true })}
        />
        {errors.email && <span>{errors.email}</span>}
      </label>

      <label>
        Message
        <textarea
          name={formActions.inferName("message")}
          defaultValue={data.message}
          onBlur={(e) => formActions.change("message", e.target.value, { touch: true })}
        />
        {errors.message && <span>{errors.message}</span>}
      </label>

      <label>
        <input
          type="checkbox"
          name={formActions.inferName("agreeToTerms")}
          defaultChecked={data.agreeToTerms === true}
          onChange={(e) => formActions.change("agreeToTerms", e.target.checked, { touch: true })}
        />
        I agree to the terms
        {errors.agreeToTerms && <span>{errors.agreeToTerms}</span>}
      </label>

      <button type="submit" disabled={submitting}>
        {submitting ? "Sending…" : "Send"}
      </button>

      <button type="reset" disabled={!dirty}>
        Reset
      </button>
    </Form>
  );
}

// app/actions/submit-contact.ts
"use server";

import { parseState, z } from "form-state";
import { schema } from "../contact-form";

export async function submitContact(data: z.infer<typeof schema>) {
  const result = parseState(schema, data, true);

  if (!result.success) {
    throw new Error(result.errors.getAll().join(" | "));
  }

  await db.contacts.create({ data: result.data });

  return { success: true };
}

import { submitContact } from "./actions/submit-contact";

const handleSubmit = formHandlers.handleSubmit(async (state) => {
  if (!state.valid) {
    formActions.focusOnFirstError({ selectText: true });
    return {};
  }

  try {
    await submitContact(state.data);
  } catch (error) {
    return { serverError: error instanceof Error ? error.message : "Server error" };
  }

  return true;
});

// app/routes/contact.tsx
import type { Route } from "./+types/contact";
import { parseState } from "form-state";
import ContactForm, { schema } from "../contact-form";

export async function loader() {
  const user = await db.users.findFirst({ where: { id: await getSessionUserId() } });
  const result = parseState(schema, user);

  if (!result.success) {
    throw new Error("Unexpected user data shape");
  }

  return result.data;
}

export default function ContactRoute({ loaderData }: Route.ComponentProps) {
  return <ContactForm user={loaderData} />;
}

import { useFormState, z } from "form-state";

// schema definition unchanged …

export default function ContactForm({
  user,
}: {
  user?: z.infer<typeof schema>;
}) {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema, { initialData: user });

  // … rest of the component unchanged
}

// src/actions/submit-contact.ts
import { createServerFn } from "@tanstack/react-start";
import { parseState, z } from "form-state";
import { schema } from "../contact-form";

export const submitContact = createServerFn({ method: "POST" })
  .inputValidator((data: z.infer<typeof schema>) => data)
  .handler(async ({ data }) => {
    const result = parseState(schema, data, true);

    if (!result.success) {
      throw new Error(result.errors.getAll().join(" | "));
    }

    await db.contacts.create({ data: result.data });

    return { success: true };
  });

// src/routes/contact.tsx
import { createFileRoute } from "@tanstack/react-router";
import ContactForm from "../contact-form";

export const Route = createFileRoute("/contact")({
  component: ContactRoute,
});

function ContactRoute() {
  return <ContactForm />;
}

import { useFormState, z } from "form-state";
import { submitContact } from "./actions/submit-contact";

export const schema = z.object({
  name: z.formString({ required: true, error: "Name is required" }),
  email: z.formString(
    { required: true, error: "Email is required" },
    z.regex(z.regexes.email, "Enter a valid email"),
  ),
  message: z.formString(
    { required: true, error: "Message is required" },
    z.minLength(10, "Must be at least 10 characters"),
  ),
  agreeToTerms: z.formBoolean({ required: true, error: "Agreement is required" })
    .check(z.validate((v) => v === true, "You must agree to continue")),
});

export default function ContactForm() {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema);

  const handleSubmit = formHandlers.handleSubmit(async (state) => {
    if (!state.valid) {
      formActions.focusOnFirstError({ selectText: true });
      return {};
    }

    try {
      await submitContact({ data: state.data });
    } catch (error) {
      return { serverError: error instanceof Error ? error.message : "Server error" };
    }

    return true;
  });

  return (
    <Form action={handleSubmit}>
      {errors.getManual("serverError") && (
        <p className="error">{errors.getManual("serverError")}</p>
      )}

      <label>
        Name
        <input
          type="text"
          name={formActions.inferName("name")}
          defaultValue={data.name}
          onBlur={(e) => formActions.change("name", e.target.value, { touch: true })}
        />
        {errors.name && <span>{errors.name}</span>}
      </label>

      <label>
        Email
        <input
          type="email"
          name={formActions.inferName("email")}
          defaultValue={data.email}
          onBlur={(e) => formActions.change("email", e.target.value, { touch: true })}
        />
        {errors.email && <span>{errors.email}</span>}
      </label>

      <label>
        Message
        <textarea
          name={formActions.inferName("message")}
          defaultValue={data.message}
          onBlur={(e) => formActions.change("message", e.target.value, { touch: true })}
        />
        {errors.message && <span>{errors.message}</span>}
      </label>

      <label>
        <input
          type="checkbox"
          name={formActions.inferName("agreeToTerms")}
          defaultChecked={data.agreeToTerms === true}
          onChange={(e) => formActions.change("agreeToTerms", e.target.checked, { touch: true })}
        />
        I agree to the terms
        {errors.agreeToTerms && <span>{errors.agreeToTerms}</span>}
      </label>

      <button type="submit" disabled={submitting}>
        {submitting ? "Sending…" : "Send"}
      </button>

      <button type="reset" disabled={!dirty}>
        Reset
      </button>
    </Form>
  );
}

// src/routes/contact.tsx
import { createFileRoute } from "@tanstack/react-router";
import { parseState } from "form-state";
import ContactForm, { schema } from "../contact-form";

export const Route = createFileRoute("/contact")({
  component: ContactRoute,
  loader: async () => {
    const user = await db.users.findFirst({ where: { id: await getSessionUserId() } });
    const result = parseState(schema, user);

    if (!result.success) {
      throw new Error("Unexpected user data shape");
    }

    return result.data;
  },
});

function ContactRoute() {
  const loaderData = Route.useLoaderData();
  return <ContactForm user={loaderData} />;
}

import { useFormState, z } from "form-state";

// schema definition unchanged …

export default function ContactForm({
  user,
}: {
  user?: z.infer<typeof schema>;
}) {
  const {
    formState: { data, errors },
    formStatus: { dirty, submitting },
    formActions,
    formHandlers,
    Form,
  } = useFormState(schema, { initialData: user });

  // … rest of the component unchanged
}

npm install @tanstack/react-query

import { useSuspenseQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { useFormState, parseState, z, type SchemaDataObject, type SubmitState } from 'form-state';

const profileSchema = z.strictObject({
  name:        z.formString({ required: true }).with(z.describe('Name')),
  email:       z.formString({ required: true }).with(z.describe('Email')),
  dateOfBirth: z.formDate({ dateFormat: 'MM/dd/yyyy' }).with(z.describe('Date of Birth')),
  bio:         z.formString().with(z.describe('Bio')),
});

// Inferred form state shape TypeScript type
type ProfileData = z.infer<typeof profileSchema>;

// Derived API type — empty literals replaced with `undefined`, optional fields use `?`
type ProfileApiData = SchemaDataObject<ProfileData>;

// Your fetch layer — swap for any HTTP client
declare const api: {
  getProfile(userId: string): Promise<ProfileApiData>;
  updateProfile(userId: string, values: ProfileApiData): Promise<void>;
};

function FormError({ error }: { error?: string }) {
  return error ? <span className="field-error">{error}</span> : null;
}

function ProfileForm({ userId }: { userId: string }) {
  const queryClient = useQueryClient();

  // 1. Fetch and validate current server data
  const { data } = useSuspenseQuery({
    queryKey: ['profile', userId],
    queryFn: async () => {
      const apiData = await api.getProfile(userId);

      // Validate the API response against the schema.
      const result = parseState(profileSchema, apiData);

      if (result.success) {
        return result.data;
      } else {
        throw new Error(result.errors.getAll().join(' | '));
      }
    },
  });

  // 2. Seed the form with the loaded server data
  const { Form, formState, formStatus, formActions, formHandlers } =
    useFormState(profileSchema, {
      initialData: data,
    });

  // 3. Mutation for saving
  const { mutateAsync } = useMutation({
    mutationFn: (values: ProfileApiData) => api.updateProfile(userId, values),
  });

  // 4. Submit handler — mutateAsync lives inside the async callback
  const handleSubmit = formHandlers.handleSubmit(
    async (submitState: SubmitState<typeof profileSchema>) => {
      if (!submitState.valid) {
        return submitState.errors;
      }

      try {
        await mutateAsync(profileSchema.toObject(submitState.data));
        return true;
      } catch (err) {
        return { serverError: err instanceof Error ? err.message : 'Save failed.' };
      }
    },
    {
      onSuccess: () => {
        queryClient.invalidateQueries({ queryKey: ['profile', userId] });
      },
    }
  );

  return (
    <Form action={handleSubmit}>
      <FormError error={formState.errors.getManual('serverError')} />

      <label>
        {formState.descriptions.name}
        {formState.required.name && <span> *</span>}
        <input
          value={formState.data.name}
          required={formState.required.name}
          onChange={(e) => formActions.change('name', e.target.value)}
          onBlur={() => formActions.touch('name')}
        />
        <FormError error={formState.errors.name} />
      </label>

      <label>
        {formState.descriptions.email}
        {formState.required.email && <span> *</span>}
        <input
          type="email"
          value={formState.data.email}
          required={formState.required.email}
          onChange={(e) => formActions.change('email', e.target.value)}
          onBlur={() => formActions.touch('email')}
        />
        <FormError error={formState.errors.email} />
      </label>

      <label>
        {formState.descriptions.dateOfBirth}
        <input
          type="text"
          placeholder={formState.patterns.dateOfBirth}
          value={formState.data.dateOfBirth}
          onChange={(e) => formActions.change('dateOfBirth', e.target.value)}
          onBlur={() => formActions.touch('dateOfBirth')}
        />
        <FormError error={formState.errors.dateOfBirth} />
      </label>

      <label>
        {formState.descriptions.bio}
        <textarea
          value={formState.data.bio ?? ''}
          onChange={(e) => formActions.change('bio', e.target.value)}
          onBlur={() => formActions.touch('bio')}
        />
      </label>

      <button type="submit" disabled={formStatus.submitting}>Save Changes</button>
    </Form>
  );
}

// Wrap at the call site — Suspense handles loading, ErrorBoundary handles fetch errors
function ProfilePage({ userId }: { userId: string }) {
  return (
    <ErrorBoundary fallback={<ErrorMessage />}>
      <Suspense fallback={<Skeleton />}>
        <ProfileForm userId={userId} />
      </Suspense>
    </ErrorBoundary>
  );
}

const { data } = useSuspenseQuery({
  queryKey: ['profile', userId],
  queryFn:  () => api.getProfile(userId),
});

// data is always ProfileData here — the component suspends until resolved
useFormState(profileSchema, { initialData: data });

import { parseState } from 'form-state';

const { data } = useSuspenseQuery({
  queryKey: ['profile', userId],
  queryFn: async () => {
    const apiData = await api.getProfile(userId);
    const result = parseState(profileSchema, apiData);

    if (result.success) {
      return result.data;
    } else {
      throw new Error(result.errors.getAll().join(' | '));
    }
  },
});

<ErrorBoundary fallback={<ErrorMessage />}>
  <Suspense fallback={<Skeleton />}>
    <ProfileForm userId={userId} />
  </Suspense>
</ErrorBoundary>

const { mutateAsync } = useMutation({
  mutationFn: (values: ProfileApiData) => api.updateProfile(userId, values),
});

const handleSubmit = formHandlers.handleSubmit(
  async (submitState: SubmitState<typeof profileSchema>) => {
    // Abort and display schema errors if client-side validation failed
    if (!submitState.valid) return submitState.errors;

    try {
      await mutateAsync(profileSchema.toObject(submitState.data));
      return true;                         // signals success to formStatus
    } catch (err) {
      // Returning an object surfaces it as a manual error in the form
      return { serverError: err instanceof Error ? err.message : 'Save failed.' };
    }
  }
);

const handleSubmit = formHandlers.handleSubmit(
  async (submitState) => { /* ... */ },
  {
    resetDirty: true,
    onSuccess: () => {
      // Refetch fires in the background; dirty-field protection means the
      // fresh data fills only fields the user hasn't touched since the save.
      queryClient.invalidateQueries({ queryKey: ['profile', userId] });
    },
  }
);

// Form-level error — display it near the submit button or at the top
return { serverError: 'The server is unavailable. Try again later.' };

// Field-level error returned from the server
return { email: 'This email is already registered.' };

// Read either with getManual() — schema errors use errors.name, errors.email etc.
<FormError error={formState.errors.getManual('serverError')} />

npm install github:dstarosta/FormStateTools#v1.0.0

import { FormDock } from 'form-state-tools';

function AppForm() {
  const form = useFormState(schema);   // or useFormStateContext(schema)
  const { Form, formHandlers } = form;

  return (
    <>
      <Form action={formHandlers.handleSubmit(onSubmit)}>
        {/* ... */}
      </Form>

      <FormDock form={form} />
    </>
  );
}

'use client';

import dynamic from 'next/dynamic';

const FormDock = dynamic(
  () => import('form-state-tools').then(({ FormDock }) => FormDock),
  { ssr: false },
);

function AppForm() {
  const form = useFormState(schema);   // or useFormStateContext(schema)
  const { Form, formHandlers } = form;

  return (
    <>
      <Form action={formHandlers.handleSubmit(onSubmit)}>
        {/* ... */}
      </Form>

      {process.env.NODE_ENV === 'development' && <FormDock form={form} />}
    </>
  );
}

// vite.config.ts
import { defineConfig } from 'vite';
import formStateTools from 'form-state-tools/vite';

export default defineConfig({
  plugins: [
    formStateTools(),
    // ...your other plugins
  ],
});

import { useFormDock } from 'form-state-tools';

function AppForm() {
  const form = useFormState(schema);   // or useFormStateContext(schema)
  const { Form, formHandlers } = form;

  useFormDock(form);   // feeds the plugin-injected dock — no <FormDock> needed

  return (
    <Form action={formHandlers.handleSubmit(onSubmit)}>
      {/* ... */}
    </Form>
  );
}

// Only show the dock when the URL carries `?devtools=true`.
useFormDock(form, new URLSearchParams(location.search).get('devtools') === 'true');

formStateTools({
  collapsed: false,
  captureErrors: 'console',
  ignoreErrorPatterns: [/ResizeObserver/, 'Network request failed'],
})

// Start expanded, only capture console.error calls
<FormDock form={form} collapsed={false} captureErrors="console" />

// Suppress noisy third-party errors
<FormDock
  form={form}
  ignoreErrorPatterns={[
    /ResizeObserver loop/,
    'Non-Error promise rejection',
  ]}
/>

// Force-disable in dev for a specific story/test
<FormDock form={form} devMode={false} />