AgentSkillsCN

jeff-forms-and-overlays

Jeff为TanStack Form及覆盖式交互（对话框、弹出面板、路由驱动的状态管理）所设定的规范。无论是新增或编辑流程，还是模态框与弹出面板的交互操作，均可参考这些规范。

SKILL.md
--- frontmatter
name: jeff-forms-and-overlays
description: Jeff's conventions for TanStack Form and overlay UX (Dialog, Sheet, route-driven state). Use for add/edit flows and modal/sheet interactions.

Jeff's Forms and Overlays

Use consistent patterns for maintainable forms and predictable overlay behavior.

Apply when

  • •Creating/editing entity forms.
  • •Adding dialogs, sheets, or confirmations.

Form rules

  • •Use @tanstack/react-form (useForm, form.Field, form.Subscribe).
  • •Avoid manual useState for submit payload fields.
  • •Keep field validation near fields or shared schemas.
  • •Reset form on overlay close where appropriate.

Local useState is acceptable for:

  • •transient search terms
  • •file objects
  • •local-only toggles and interaction state

Overlay rules

  • •Route-level overlays must use URL query state.
  • •Opening overlay updates URL; closing clears URL params.
  • •Derive selected entity from id in URL + loaded data.

Dialog vs Sheet

Use Dialog for:

  • •short, blocking, single-purpose actions
  • •small forms (about 1-4 fields)

Use Sheet for:

  • •longer/multi-section forms
  • •workflows needing more context and space

Sheet defaults

  • •Use a single scrollable body container.
  • •Keep action footer visible/sticky.
  • •Use size by complexity (sm:max-w-sm simple, sm:max-w-lg denser forms).

Validation checklist

  • • Form submission state uses TanStack Form subscriptions.
  • • Overlay open/close is URL-consistent for route-level flows.
  • • Dialog/Sheet choice matches form complexity.