lukedj78/dev-flow / forms
forms
VerifiedBuild or edit any form in a Next.js 16 App Router app through one shared toolkit in `lib/forms/`, with dirty + valid Save gating — on TanStack Form + Zod (default) or react-hook-form (auto-detected). Use when the user says "form", "edit panel", "create dialog", "settings page", "save button", "dirty state", or reaches for `useState` to hold field values, raw `useForm`, hand-rolled dirty tracking, or inline `toast.success/error` on submit. Also owns multi-step question flows — "questionnaire", "questionario", "survey", "sondaggio", "quiz", "poll", "onboarding flow", "intake form", "wizard", "step-by-step questions", "one question at a time" — which route to the shadcn `<Questionnaire />`. Refuses outside Next.js 16 web. Not for: React Native forms, search boxes that only filter, reads that populate a form (`data-fetching`), or state not bound to form fields (`state-discipline`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 38.2 KB |
| references/audit-recipe.md | markdown | 8.7 KB |
| references/contracts.md | markdown | 105.8 KB |
| references/form-actions.md | markdown | 4.5 KB |
| references/toolkit-rhf.md | markdown | 13.1 KB |
| references/toolkit-tanstack.md | markdown | 15.6 KB |
| scripts/meta_io.py | script | 9.2 KB |
| scripts/scaffold_lib_forms.pyexecutable | script | 14.3 KB |
references/toolkit-tanstack.md
View on GitHub# Toolkit reference — TanStack Form + Zod backend
The 7 files of `lib/forms/` when `meta.json#stack.forms = "tanstack-form"`.
Dependencies:
- `@tanstack/react-form` ^1
- `zod` ^4
- shadcn `Field` component installed
- a toast primitive mounted at the root layout — shadcn's **Base UI `Toast`**
(`components/ui/toast.tsx`, default for `--base base` since 2026-07) or **`sonner`**
(Radix / React Aria projects). `scaffold_lib_forms.py` detects which one is installed
and rewrites the two `// forms:toast-*` lines of `mapFormError.ts` to match.
Types verified against `@tanstack/react-form` 1.33.5 + `zod` 4.6 (FITROOM, 2026-09-22).
⚠️ Do **not** type the context as `AnyFormApi`: that is form-core's `FormApi<any…>` and has no
`Field` / `Subscribe` — those live on `ReactFormApi`, which `useForm` returns intersected with
`FormApi` as `ReactFormExtendedApi`. The toolkit exports `AnyReactFormApi` for this.
---
## `lib/forms/index.ts`
```ts
export { useEditForm } from "./useEditForm";
export { useCreateForm } from "./useCreateForm";
export { FormProvider, useFormContext } from "./FormProvider";
export { FormField } from "./FormField";
export { FormActions } from "./FormActions";
export { focusFirstInvalid } from "./focusFirstInvalid";
export { mapFormError, type FormErrorContext } from "./mapFormError";
```
---
## `lib/forms/FormProvider.tsx`
A thin React context wrapping the TanStack form instance so descendant `<FormField>` components can reach it without prop-drilling.
```tsx
"use client";
import { createContext, useContext, type ReactNode } from "react";
import type { ReactFormExtendedApi } from "@tanstack/react-form";
/**
* Any form returned by `useForm`, React bindings included (`Field`, `Subscribe`).
* Mirrors form-core's `AnyFormApi`, which drops them. The twelve generics are the
* form data, the validators and the submit meta; TanStack declares them invariant,
* so `any` is the only type a heterogeneous context can hold.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type AnyReactFormApi = ReactFormExtendedApi<any, any, any, any, any, any, any, any, any, any, any, any>;
const FormContext = createContext<AnyReactFormApi | null>(null);
export function FormProvider({
form,
children,
}: {
form: AnyReactFormApi;
children: ReactNode;
}) {
return <FormContext.Provider value={form}>{children}</FormContext.Provider>;
}
export function useFormContext(): AnyReactFormApi {
const ctx = useContext(FormContext);
if (!ctx) throw new Error("useFormContext must be used inside <FormProvider>");
return ctx;
}
```
---
## `lib/forms/useEditForm.ts`
Manual-save hook with dirty tracking + baseline reset on success. The `save` callback **must throw on failure**; errors flow through `mapFormError`.
```ts
"use client";
import { useRef } from "react";
import { useForm } from "@tanstack/react-form";
import type { z } from "zod";
import type { AnyReactFormApi } from "./FormProvider";
import { focusFirstInvalid } from "./focusFirstInvalid";
import { mapFormError } from "./mapFormError";
export interface UseEditFormOptions<T> {
// Input = the form values (what TanStack validates); output is free, so
// transforms and coercions stay allowed.
schema: z.ZodType<unknown, T>;
defaultValues: T;
save: (value: T, ctx: { signal: AbortSignal }) => Promise<T>;
}
export function useEditForm<T>(opts: UseEditFormOptions<T>): AnyReactFormApi {
// A ref, not a local: the controller must survive the re-renders between submits.
const inFlight = useRef<AbortController | null>(null);
return useForm({
defaultValues: opts.defaultValues,
validators: {
onChange: opts.schema,
onBlur: opts.schema,
},
onSubmit: async ({ value, formApi }) => {
inFlight.current?.abort();
const controller = new AbortController();
inFlight.current = controller;
try {
const saved = await opts.save(value, { signal: controller.signal });
// Reset baseline so isDirty returns to false; editing back to the saved
// value leaves the form clean.
formApi.reset(saved);
} catch (err) {
mapFormError(err, { form: formApi });
throw err; // re-throw so TanStack marks submit as failed
} finally {
if (inFlight.current === controller) inFlight.current = null;
}
},
// The Save button is enabled on an invalid form on purpose; this is what pressing it buys.
onSubmitInvalid: () => focusFirstInvalid(),
});
}
```
---
## `lib/forms/focusFirstInvalid.ts`
The other half of the submit gate. Our Save button no longer blocks on validity, so a failed submit
actually happens — and a failed submit is the moment the platform reserves for telling the user what
is wrong.
```ts
"use client";
import { announce } from "@/lib/a11y/announcer";
export function focusFirstInvalid(): void {
// The submit came from a control inside the form — the Save button, or the field the user
// pressed Enter in — so the active element locates the right form without any plumbing.
// A programmatic submit with focus elsewhere falls through to announcing only.
const formEl = (document.activeElement as HTMLElement | null)?.closest("form") ?? null;
const invalid = formEl?.querySelectorAll<HTMLElement>('[aria-invalid="true"]') ?? [];
// Focus announces that field's own message through `aria-describedby`.
invalid[0]?.focus();
// The count is the thing focus cannot say, so it is the only thing the region says.
// One field: focus already read it out, and repeating it talks over the screen reader.
if (invalid.length > 1) announce(`${invalid.length} fields need attention`);
}
```
⚠️ **On a long form, focusing the first invalid field is the wrong affordance** — the user is thrown
to the top with no sense of how much is wrong. Past roughly eight fields, render an error summary
(a heading, then a link per invalid field), focus the heading, and have the links move focus to the
controls. Same function, different target.
---
## `lib/forms/useCreateForm.ts`
Same shape, no baseline reset; on success calls `onSuccess(result)`.
```ts
"use client";
import { useRef } from "react";
import { useForm } from "@tanstack/react-form";
import type { z } from "zod";
import type { AnyReactFormApi } from "./FormProvider";
import { focusFirstInvalid } from "./focusFirstInvalid";
import { mapFormError } from "./mapFormError";
export interface UseCreateFormOptions<TInput, TResult> {
schema: z.ZodType<unknown, TInput>;
defaultValues: TInput;
submit: (value: TInput, ctx: { signal: AbortSignal }) => Promise<TResult>;
onSuccess?: (result: TResult) => void;
}
export function useCreateForm<TInput, TResult>(
opts: UseCreateFormOptions<TInput, TResult>,
): AnyReactFormApi {
const inFlight = useRef<AbortController | null>(null);
return useForm({
defaultValues: opts.defaultValues,
validators: {
onChange: opts.schema,
onBlur: opts.schema,
},
onSubmit: async ({ value, formApi }) => {
inFlight.current?.abort();
const controller = new AbortController();
inFlight.current = controller;
try {
const result = await opts.submit(value, { signal: controller.signal });
opts.onSuccess?.(result);
} catch (err) {
mapFormError(err, { form: formApi });
throw err;
} finally {
if (inFlight.current === controller) inFlight.current = null;
}
},
// On an empty create form, pressing Create is how the user learns what is required.
onSubmitInvalid: () => focusFirstInvalid(),
});
}
```
---
## `lib/forms/FormField.tsx`
Thin render-prop over `<form.Field name>` + shadcn `Field`/`FieldLabel`/`FieldError`. The child receives a narrowed view of the TanStack field API.
```tsx
"use client";
import { type ReactNode } from "react";
import {
Field,
FieldDescription,
FieldError,
FieldLabel,
} from "@/components/ui/field";
import { useFormContext } from "./FormProvider";
export interface FormFieldRenderProps {
name: string;
value: unknown;
setValue: (value: unknown) => void;
onBlur: () => void;
touched: boolean;
isValid: boolean;
errors: string[];
/** Spread onto the control as `aria-invalid`. Mirrors `:user-invalid`: the field was
* modified and left, or a submit was attempted. Never compute this in a component. */
invalid: boolean;
/** Spread onto the control as `aria-describedby`. The error element's id while the field
* is invalid, `undefined` otherwise — a permanent reference is read out before the user
* has touched the field, even when the text is hidden. */
describedBy: string | undefined;
}
// Standard Schema validators (Zod) report issues as `{ message }`; function
// validators and `onServer` (mapFormError) report plain strings.
function toMessage(error: unknown): string {
if (typeof error === "string") return error;
if (error && typeof error === "object" && "message" in error) {
return String((error as { message: unknown }).message);
}
return "";
}
export function FormField({
name,
label,
description,
children,
}: {
name: string;
label: string;
description?: string;
children: (field: FormFieldRenderProps) => ReactNode;
}) {
const form = useFormContext();
// Reactive: `form.state` read directly does not re-render. One submit attempt flips every
// field to invalid at once, which is what the failed-submit announcement needs.
const submitAttempted = form.useStore((s) => s.submissionAttempts > 0);
return (
<form.Field name={name}>
{(field) => {
const { meta } = field.state;
const errors = meta.errors.map(toMessage).filter(Boolean);
// `:user-invalid`, not `:invalid`: modified and left, or a submit was attempted.
// `meta.isTouched` alone is blur — it reports an error on a field tabbed straight through.
const invalid =
((meta.isDirty && meta.isTouched) || submitAttempted) && !meta.isValid;
const errorId = `${name}-error`;
const shown = invalid && Boolean(errors[0]);
return (
<Field data-invalid={invalid}>
<FieldLabel htmlFor={name}>{label}</FieldLabel>
{children({
name: field.name,
value: field.state.value,
setValue: field.handleChange,
onBlur: field.handleBlur,
touched: meta.isTouched,
isValid: meta.isValid,
errors,
invalid,
// Only while shown. `<FieldError>` is unmounted otherwise, so a stale id
// would point at nothing — and a permanent one is announced too early.
describedBy: shown ? errorId : undefined,
})}
{description && <FieldDescription>{description}</FieldDescription>}
{shown && <FieldError id={errorId}>{errors[0]}</FieldError>}
</Field>
);
}}
</form.Field>
);
}
```
---
## `lib/forms/FormActions.tsx`
Save + Reset button row. Reads form state via `form.Subscribe` so only this subtree re-renders on state changes.
```tsx
"use client";
import { Button } from "@/components/ui/button";
import { useFormContext } from "./FormProvider";
export function FormActions({
submitLabel,
submittingLabel,
resetLabel = "Reset",
requireDirty = true,
}: {
submitLabel: string;
submittingLabel: string;
resetLabel?: string;
requireDirty?: boolean;
}) {
const form = useFormContext();
return (
<form.Subscribe
// Deliberately NOT `s.canSubmit` — TanStack's own `canSubmit` folds in validity, which is
// the gate we removed. See the `forms` skill, §The Save button is not a validity light.
selector={(s) => ({
isSubmitting: s.isSubmitting,
isDirty: s.isDirty,
})}
>
{({ isSubmitting, isDirty }) => (
<div className="flex justify-end gap-2">
<Button
type="button"
variant="ghost"
disabled={!isDirty || isSubmitting}
onClick={() => form.reset()}
>
{resetLabel}
</Button>
<Button
type="submit"
// Disabled when there is nothing to save, or a save is in flight. An invalid form
// keeps an enabled button: pressing it is how the user is told what is wrong.
disabled={isSubmitting || (requireDirty && !isDirty)}
>
{isSubmitting ? submittingLabel : submitLabel}
</Button>
</div>
)}
</form.Subscribe>
);
}
```
---
## `lib/forms/mapFormError.ts`
Discriminated-union routing for thrown errors. Extend `switch` cases as the project's error classes evolve. **Single source of truth** for form-level error UI.
The two `// forms:toast-*` lines are the only toast-specific code. The template ships the Base UI
variant; `scaffold_lib_forms.py` swaps them for `import { toast } from "sonner"` /
`toast.error(message)` when the project has `components/ui/sonner.tsx` instead.
```ts
"use client";
import type { AnyFormApi } from "@tanstack/react-form";
import { toast } from "@/components/ui/toast"; // forms:toast-import
export interface FormErrorContext {
// form-core's FormApi is enough here (setFieldMeta); the hooks pass `formApi`.
form: AnyFormApi;
}
function notifyError(message: string): void {
toast.add({ title: message, type: "error" }); // forms:toast-call
}
// Project-specific error classes (edit to match your services layer)
class SessionExpiredError extends Error {}
class ForbiddenError extends Error {}
class ValidationProblem extends Error {
errors: Record<string, string[]>;
constructor(errors: Record<string, string[]>) {
super("validation");
this.errors = errors;
}
}
class ServerProblem extends Error {
detail: string;
constructor(detail: string) {
super(detail);
this.detail = detail;
}
}
export function mapFormError(err: unknown, ctx: FormErrorContext): void {
if (err instanceof SessionExpiredError) {
// Redirect to your auth-refresh route — project-specific.
// A full reload on purpose: it drops client state tied to the dead session.
// eslint-disable-next-line @next/next/no-location-assign-relative-destination
window.location.assign("/auth/refresh");
return;
}
if (err instanceof ForbiddenError) {
notifyError("You don't have permission to perform this action.");
return;
}
if (err instanceof ValidationProblem) {
// Per-field errors — surfaced through the `onServer` slot of the error map.
for (const [field, msgs] of Object.entries(err.errors)) {
ctx.form.setFieldMeta(field, (meta) => ({
...meta,
errorMap: { ...meta.errorMap, onServer: msgs[0] },
}));
}
notifyError("Some fields need attention.");
return;
}
if (err instanceof ServerProblem) {
notifyError(err.detail);
return;
}
if (err instanceof TypeError) {
// Network failure
notifyError("Network error. Please retry.");
return;
}
notifyError("Something went wrong.");
}
```
---
## Notes
- **Adapt error classes** to your services layer. The `mapFormError` switch is the single source of truth — every form behaves identically because every form routes through it.
- **The form state stays dirty on error** so the user can fix and retry without losing edits.
- **`requireDirty` defaults to true** on `<FormActions>` for edit forms; pass `requireDirty={false}` for create forms (or split the component if your team prefers).
- **AbortController** is wired inside the hooks so re-submitting cancels the in-flight request. The button being disabled during submit is the primary defense; AbortController is the backstop for out-of-order resolution after reset.
- **i18n**: replace inline strings (`"Network error. Please retry."` etc.) with your i18n keys. The skill ships them inline; project should swap to `t("forms.errors.network")` etc.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |