Skip to content

lukedj78/dev-flow / forms

Build 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`).

FileKindSize
SKILL.mdskill md38.2 KB
references/audit-recipe.mdmarkdown8.7 KB
references/contracts.mdmarkdown105.8 KB
references/form-actions.mdmarkdown4.5 KB
references/toolkit-rhf.mdmarkdown13.1 KB
references/toolkit-tanstack.mdmarkdown15.6 KB
scripts/meta_io.pyscript9.2 KB
scripts/scaffold_lib_forms.pyexecutablescript14.3 KB

references/form-actions.md

View on GitHub
# `<FormActions>` — custom layouts

The default `<FormActions submitLabel="Save" submittingLabel="Saving…" resetLabel="Reset" />` ships Save + Reset right-aligned. For non-trivial layouts (Cancel button, dialog footer docking, three-button row), drop `<FormActions>` and inline the equivalent subscribe block.

## TanStack Form — inline subscribe

```tsx
<form.Subscribe
  // Not `s.canSubmit`: TanStack's own flag folds in validity, which is not a gate here.
  selector={(s) => ({ isSubmitting: s.isSubmitting, isDirty: s.isDirty })}
>
  {({ isSubmitting, isDirty }) => (
    <div className="flex items-center justify-between gap-2">
      <Button type="button" variant="ghost" onClick={onCancel}>
        Cancel
      </Button>
      <div className="flex gap-2">
        <Button
          type="button"
          variant="outline"
          disabled={!isDirty || isSubmitting}
          onClick={() => form.reset()}
        >
          Reset
        </Button>
        <Button type="submit" disabled={!isDirty || isSubmitting}>
          {isSubmitting ? "Saving…" : "Save"}
        </Button>
      </div>
    </div>
  )}
</form.Subscribe>
```

## react-hook-form — `useFormState`

```tsx
// `isValid` is deliberately absent: it is not a gate. See the skill, §The Save button is
// not a validity light.
const { isDirty, isSubmitting } = useFormState({ control: form.control });
const canSave = isDirty && !isSubmitting;

return (
  <div className="flex items-center justify-between gap-2">
    <Button type="button" variant="ghost" onClick={onCancel}>
      Cancel
    </Button>
    <div className="flex gap-2">
      <Button
        type="button"
        variant="outline"
        disabled={!isDirty || isSubmitting}
        onClick={() => form.reset()}
      >
        Reset
      </Button>
      <Button type="submit" disabled={!canSave}>
        {isSubmitting ? "Saving…" : "Save"}
      </Button>
    </div>
  </div>
);
```

## Dialog footer pattern

When the form lives inside a shadcn `<Dialog>`, the natural place for actions is `<DialogFooter>`:

```tsx
<DialogFooter>
  <Button type="button" variant="ghost" onClick={() => setOpen(false)}>
    Cancel
  </Button>
  <Button type="submit" disabled={!canSave}>
    {isSubmitting ? "Saving…" : "Save"}
  </Button>
</DialogFooter>
```

If `isDirty === true` when the user clicks Cancel, run the unsaved-changes guard (see `SKILL.md` § "Unsaved-changes guard") before closing.

## Three-button row (Save / Save and close / Cancel)

Common in admin tools:

```tsx
<form.Subscribe selector={(s) => ({ isDirty: s.isDirty, isSubmitting: s.isSubmitting })}>
  {({ isDirty, isSubmitting }) => (
    <div className="flex justify-end gap-2">
      <Button type="button" variant="ghost" onClick={onCancel}>Cancel</Button>
      <Button
        type="submit"
        variant="outline"
        disabled={!isDirty || isSubmitting}
        onClick={() => { /* set a flag the onSubmit reads */ }}
      >
        Save and close
      </Button>
      <Button type="submit" disabled={!isDirty || isSubmitting}>
        {isSubmitting ? "Saving…" : "Save"}
      </Button>
    </div>
  )}
</form.Subscribe>
```

To distinguish "Save" from "Save and close" inside the hook's `save` callback, pass a `useState`-controlled flag through React context, **or** prefer two separate handlers wired to two separate `<Button onClick>` handlers that each call `form.handleSubmit()` after setting the flag.

## What `<FormActions>` is NOT

- Not a Cancel button. Cancel is a parent concern (close the dialog, navigate away, etc.); the form has no opinion on it.
- Not a place for "Save and continue editing" auto-save. The skill bans auto-save — the contract is explicit Save click. If you genuinely need workflow buttons, inline the subscribe block and own the layout.
- Not a place for confirmation modals. "Are you sure?" UX is the parent's concern; `<FormActions>` only disables while there is nothing to save or a save is in flight.
- 🔴 **Not a validity light.** Whatever layout you inline, the submit button must stay **enabled on an invalid form** — pressing it is the only thing that tells a screen-reader user which field is wrong. Any `disabled={!isValid}` you write here deletes that, and the error never reaches them. See the skill, §The Save button is not a validity light.

## Rule of thumb

Use `<FormActions>` when the layout is Save + Reset right-aligned. For anything else, drop to the subscribe block and own the layout. The skill flags the boundary but doesn't enforce the wrapper — the contract is the underlying form state discipline, not the button row.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall