getpaseo__paseo/docs/forms.md

Forms

The paved road for building forms in the app. The schedule form is the golden example; when building or fixing any form, copy its shape, not the shape of whatever screen you happen to be near.

Golden example files:

• packages/app/src/schedules/schedule-form-model.ts (+ .test.ts) — the model
• packages/app/src/schedules/use-schedule-form-model.ts — model lifetime adapter
• packages/app/src/schedules/use-schedule-form-provider-snapshot.ts — async input adapter
• packages/app/src/components/schedules/schedule-form-sheet.tsx — render + intent dispatch
• packages/app/src/schedules/aggregated-schedules.ts / hooks/use-schedules.ts — load-state gating
• packages/app/e2e/schedules-*.spec.ts — the behavioral contract

The form model

Every non-trivial form gets a plain TypeScript model — zero React imports:

• openXxxForm(snapshot) constructs a fresh instance from declared inputs (mode, the record being edited, hosts, defaults). Edit mode seeds every value AND display from the snapshot — never from a previous instance.
• Commands mutate (setHost, setProject(value, display), setModel, …). Derived state (disclosure, canSubmit, displays) is recomputed inside the model on every publish.
• close() destroys the instance. subscribe/getState feed one useSyncExternalStore in the component.

The component renders state and dispatches intent. That is all it does.

Lifecycle rules (each one killed a real shipped bug)

1. Fresh mount per open. The sheet returns null when not visible and mounts the open form with a key derived from mode + record identity. A long-lived component instance shared across create/edit is how edit contaminated create.
2. Construct the model ONCE per mount — useState(() => openXxxForm(snapshot)). NEVER useMemo(() => open(...), [snapshot]): the snapshot's identity depends on live data (projects, hosts, preferences), and any background churn — e.g. a scheduled run creating a workspace — would reconstruct the model and wipe the user's in-progress input.
3. Late data is an explicit model input, not a reconstruction. applyProviderSnapshot(serverId, …), applyProjectTargets(…), applyHosts(…). Adapters pipe identity changes into these with mechanical effects. Input plumbing is fine; orchestration effects are not — the sheet itself has zero useEffect/useRef, and that is the target for every form.
4. Resolution is explicit model state, per host (idle | pending | complete), keyed off the opened snapshot's serverId. Waiting for data is a state you can render, not an effect race.
5. Displays are owned state. The selected option's label is captured at selection/seed time (setProject(value, display)), never re-derived from a live options list — list churn must not flicker or blank a selection.
6. Disclosure is derived in the model from user intent (host → project → model → thinking/mode), so fields cannot pop in from cache timing.

Form kit

• Compose Field / SelectField / FormTextInput / SegmentedControl / Switch from components/ui/. Geometry (heights, padding, radii, focus/hover states) is owned by components/ui/control-geometry.ts — controls never declare their own, and screens never nudge global component styles to align a row.
• Every text field consumes EditingTextInput, directly or through a UI wrapper. The editing surface owns in-progress text; React observes committed edits through onChangeText, and programmatic mutations use the input's replaceText command. Its props omit value and defaultValue, web IME candidates stay unpublished until composition commits, and lint rejects raw React Native TextInput imports outside the primitive.
• The form declares one size for all fields: sm on desktop, md compact (useIsCompactFormFactor).
• Availability hierarchy: a field whose capability doesn't apply is hidden (isolation on a non-git project — same gating as New Workspace), not rendered disabled with an explanation. Disabled-with-a-reason hint is only for transient states the user can resolve.
• Copy is opt-in and rare. No hint/subtext unless the maintainer approved the exact string; validation errors are the exception. State a fact (like the timezone) once — never in a preview line AND a helper line.
• useUnistyles is banned (see docs/unistyles.md); lint enforces.

Settings rows

Use the named components from @/components/settings for settings cards and controls. SettingsCard owns row separators; SettingsRow accepts custom content. Heading-only screens can import SettingsGroup and SettingsSection directly from their modules in @/components/settings/headings/. The plugin UI entry exposes the same components; keep them independent of storage and routing.

Data gating

Aggregate hooks return a discriminated load state:

type AggregateLoadState<T> =
  | { status: "connecting" } // an answer may still be pending
  | { status: "loading" }
  | { status: "loaded"; data: T[] };

Empty states are only typeable inside loaded — a fetch that "succeeded" before hosts connected is connecting, not empty. Query keys carry real fetch inputs (host set, connection statuses), never synthetic version counters.

Anti-patterns (reject in review on sight)

• useEffect choreography impersonating construct/hydrate/resolve/destroy.
• One mounted form instance serving create and edit.
• useMemo-keyed model construction on live-data identity.
• Selected labels derived from live query lists.
• isLoading/isEmpty boolean bags where a load-state union belongs.
• Conditional mounting of hint/error rows that shifts layout (subtext renders only when present, but the pattern for that lives in Field, not ad hoc).