# Conform + Zod Form Wiring

Conform's Zod helpers import from the `@conform-to/zod/v4` subpath, the bare `@conform-to/zod` targets Zod 3 and throws at runtime (typecheck/lint/build don't catch it). The react-code SKILL.md carries this as the always-on rule; the examples below use `/v4` throughout.

## Basic Form Setup

### 1. Define Zod schema (in route file)

```tsx
const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  role: z.literal(['admin', 'member']),
});
```

### 2. Action (in route file)

```tsx
export const action = async ({request}: ActionFunctionArgs) => {
  const formData = await request.formData();
  const submission = parseWithZod(formData, {schema});

  if (submission.status !== 'success') {
    return data({result: submission.reply()});
  }

  // Use submission.value for typed data
  await fetch('/api/users', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(submission.value),
  });
  return redirect('/users');
};
```

### 3. Page component with useForm

```tsx
import {useForm, getFormProps, getInputProps} from '@conform-to/react';
import {getZodConstraint, parseWithZod} from '@conform-to/zod/v4';
import {useTranslation} from 'react-i18next';

const MyPage: FC = () => {
  const {t} = useTranslation('pages');
  const actionData = useActionData<{result: SubmissionResult}>();

  const [form, fields] = useForm({
    lastResult: actionData?.result,
    constraint: getZodConstraint(schema),
    onValidate: ({formData}) => parseWithZod(formData, {schema}),
    shouldValidate: 'onBlur',
    shouldRevalidate: 'onInput',
  });

  return (
    <Form method="post" {...getFormProps(form)}>
      <InputText
        {...getInputProps(fields.name, {type: 'text'})}
        label={t('nameLabel')}
        errors={fields.name.errors}
      />
      <InputText
        {...getInputProps(fields.email, {type: 'email'})}
        label={t('emailLabel')}
        errors={fields.email.errors}
      />
      <Select
        {...getInputProps(fields.role, {type: 'text'})}
        label={t('roleLabel')}
        options={roleOptions}
        errors={fields.role.errors}
      />
      <button type="submit">Save</button>
    </Form>
  );
};
```

## Form Component Mapping

For the native-element → Form-component table, see **Gate 2: Form Element Check** in `react-code/SKILL.md` (the authoritative superset, including the native-OK exceptions `hidden` / `file` / `range`).

## Compound Component Gotcha

Conform reads stale hidden input values from compound components (YearMonthDay, TimePicker). Fix: native `addEventListener('input', e => e.stopPropagation())` via ref callback on container div + sync hidden input DOM value via `useRef` in `onChange`. React `onInput` won't work (SSR hydration puts both handlers on same node).

## Zod Patterns

This project uses Zod 4, the typescript skill's `references/zod.md` is the full Zod 3 → Zod 4 migration map. Project convention: `z.literal([...])` not `z.enum()` for string unions (sort values alphanumerically).

# Hook Patterns, Extended Examples

## Contents

- [useEffect Anti-Patterns](#useeffect-anti-patterns)
- [When Effects ARE Correct](#when-effects-are-correct)
- [Strict Mode & Cleanup](#strict-mode--cleanup)
- [useCallback, When to Use](#usecallback--when-to-use)
- [useMemo, When to Use](#usememo--when-to-use)
- [useEffectEvent, Non-Reactive Effect Logic](#useeffectevent-non-reactive-effect-logic)
- [Ref Callback Cleanup](#ref-callback-cleanup)

---

## useEffect Anti-Patterns

### Don't transform data for rendering

```tsx
// BAD, unnecessary state + Effect + extra render cycle
const [filtered, setFiltered] = useState<Exercise[]>([]);
useEffect(() => {
  setFiltered(exercises.filter((e) => e.muscleGroup === selected));
}, [exercises, selected]);

// GOOD, derive inline
const filtered = exercises.filter((e) => e.muscleGroup === selected);
```

### Don't use Effects for expensive calculations

```tsx
// BAD, triggers a render to set state, then Effect runs and triggers a second render
useEffect(() => {
  setSorted(exercises.slice().sort((a, b) => a.name.localeCompare(b.name)));
}, [exercises]);

// GOOD, useMemo runs synchronously, no extra render
const sorted = useMemo(
  () => exercises.slice().sort((a, b) => a.name.localeCompare(b.name)),
  [exercises]
);
```

### Don't derive redundant state

```tsx
// BAD, Effect sets state after render, causing an extra render cycle every time deps change
useEffect(() => {
  setFullName(`${firstName} ${lastName}`);
}, [firstName, lastName]);

// GOOD
const fullName = `${firstName} ${lastName}`;
```

### Don't put user-event logic in Effects

```tsx
// BAD, notification in Effect triggered by state change; effects fire after render,
// so the causal link between action and side effect is indirect; also runs on mount
// and every dep change, not just the user action
useEffect(() => {
  if (justAdded) showToast(`${product.name} added`);
}, [justAdded]);

// GOOD, in the event handler
function handleAddToPlan() {
  dispatch({type: 'add', product});
  showToast(`${product.name} added to your plan`);
}
```

### Don't chain Effects

```tsx
// BAD, multiple Effects cascading state updates; each setState triggers its own render,
// so n chained effects = n+1 render cycles
useEffect(() => {
  setCard(deck[index]);
}, [index]);
useEffect(() => {
  setGoldCount(card.isGold ? count + 1 : count);
}, [card]);

// GOOD, derive everything from the event
function pickCard(index: number) {
  const card = deck[index];
  const newGoldCount = card.isGold ? goldCardCount + 1 : goldCardCount;
  setIndex(index);
  setCard(card);
  setGoldCardCount(newGoldCount);
  setIsWon(newGoldCount >= 5);
}
```

### Don't notify parent via Effect

```tsx
// BAD, fires after every render where isOn changed, including the initial mount;
// easy source of infinite loops if parent updates props that feed back into this child
useEffect(() => {
  onChange(isOn);
}, [isOn]);

// GOOD
function handleToggle() {
  const next = !isOn;
  setIsOn(next);
  onChange(next);
}
```

### State reset, use key, not Effect

```tsx
// BAD, Effect fires after the stale state has already rendered, causing a visible flash before reset
useEffect(() => {
  setNotes('');
  setEditing(false);
}, [userId]);

// GOOD, key forces unmount/remount, all state resets before the first paint
<WorkoutNotes key={userId} userId={userId} />;
```

---

## When Effects ARE Correct

Effects are appropriate for synchronizing with external systems.

### Data fetching with ignore flag

```tsx
useEffect(() => {
  let ignore = false;

  async function fetchExercises() {
    const {data} = await supabase
      .from('exercises')
      .select('*')
      .eq('gym_id', gymId);
    if (!ignore) setExercises(data ?? []);
  }

  fetchExercises();
  return () => {
    ignore = true;
  };
}, [gymId]);
```

### External store subscription

Prefer `useSyncExternalStore` when possible. Use Effect for third-party widgets or browser APIs that don't expose a subscribe/getSnapshot pattern.

---

## Strict Mode & Cleanup

React 18 Strict Mode mounts → unmounts → remounts every component in development. Effects run twice. Cleanup must fully undo the setup, or the second invocation leaves duplicate state or stale listeners. This is intentional, it surfaces missing cleanups before they leak in production.

```tsx
// BAD, missing cleanup leaks the listener (and fires twice in dev with Strict Mode)
useEffect(() => {
  window.addEventListener('resize', handleResize);
}, [handleResize]);

// GOOD, cleanup mirrors setup exactly
useEffect(() => {
  window.addEventListener('resize', handleResize);
  return () => window.removeEventListener('resize', handleResize);
}, [handleResize]);
```

The same principle applies to any subscription, timer, or third-party widget: if the Effect sets something up, the cleanup must tear it down completely.

---

## useCallback, When to Use

```tsx
// ✅ Passed to memo-wrapped child, prevents unnecessary child re-renders
const handleSubmitForm = useCallback((data: FormData) => {
  post('/api/submit', data);
}, []);
return <MemoizedForm onSubmit={handleSubmitForm} />;

// ✅ Used in useEffect dependency array, keeps a stable reference
const fetchData = useCallback(async () => {
  const result = await api.get(endpoint);
  setData(result);
}, [endpoint]);

useEffect(() => {
  fetchData();
}, [fetchData]);

// ❌ Not passed to a memo child, not in any hook deps, skip useCallback
const handleClickIncrement = () => {
  setCount(count + 1);
};
```

### Anti-pattern: wrapping every handler "just in case"

```tsx
// BAD, premature optimization; every render still allocates the deps array,
// so if deps change often useCallback saves nothing. An empty deps array is
// a stale closure waiting to happen if the handler ever needs to read state or props.
const handleChangeName = useCallback((e: ChangeEvent<HTMLInputElement>) => {
  setName(e.target.value);
}, []); // looks safe now, breaks the moment handleChangeName needs to read other state

// GOOD, plain function is the right default
const handleChangeName = (e: ChangeEvent<HTMLInputElement>) => {
  setName(e.target.value);
};
```

The default should be a plain function. Reach for `useCallback` only when you have a concrete reason: a `memo`-wrapped child that's visibly re-rendering, or a stable reference needed by an Effect.

---

## useMemo, When to Use

Use `useMemo` for computations that are:

- Genuinely expensive (sorting/filtering large arrays, building derived structures)
- Passed as props to `memo`-wrapped children where reference stability matters
- Used in `useEffect` dependency arrays to maintain a stable reference

### Anti-pattern: memoizing cheap calculations

```tsx
// BAD, trivial calculation; memo bookkeeping costs more than it saves
const label = useMemo(() => `Hello, ${name}`, [name]);

// GOOD, just compute inline
const label = `Hello, ${name}`;
```

Missing or stale deps in `useMemo` introduce the same stale closure bugs as `useCallback`, the memoized value silently reads an old snapshot of whatever was omitted from the deps array.

---

## useEffectEvent, Non-Reactive Effect Logic

`useEffectEvent` (stable in React 19.2) extracts a non-reactive read out of an Effect, so the Effect uses a current value without listing it as a dependency. It is the sanctioned replacement for "I had to omit X from the deps array" and for the latest-ref workaround (e.g. `TextArea` keeping `onAutoSizeRef.current = onAutoSize` behind an `eslint-disable react-hooks/refs`).

```tsx
// onVisit reads numItems, but the Effect should re-run only when url changes
const onVisit = useEffectEvent((visitedUrl: string) => {
  log(visitedUrl, numItems); // numItems is non-reactive here
});

useEffect(() => {
  onVisit(url);
}, [url]); // numItems intentionally absent, and lint won't demand it
```

Use sparingly, only for values that are genuinely non-reactive (the Effect should not re-run when they change). If the Effect should react to the value, keep it in the deps array.

---

## Ref Callback Cleanup

A ref callback may return a cleanup function, run when the element leaves the DOM. When it returns a cleanup, React no longer calls the callback again with `null`.

```tsx
<div
  ref={(node) => {
    const observer = new ResizeObserver(() => {/* … */});
    observer.observe(node);
    return () => observer.disconnect(); // runs on unmount
  }}
/>;
```

**Strict-TS pitfall:** because a returned value is now read as a cleanup function, an arrow ref-callback with an implicit return of a non-`undefined` value flags. Use a block body so the callback returns `undefined`.

```tsx
// BAD, implicit return of the assignment is read as a cleanup
<input ref={(node) => (ref.current = node)} />;
// GOOD, block body returns undefined
<input ref={(node) => { ref.current = node; }} />;
```

# Translation Patterns, Edge Cases

## Core Rule

One `useTranslation()` per component. Use `{ns: 'other'}` for cross-namespace access.

```tsx
// GOOD
const {t} = useTranslation('pages');
t('onboarding.step1.title'); // 'pages' namespace
t('previous', {ns: 'common'}); // override to 'common'

// BAD
const {t} = useTranslation('pages');
const {t: tc} = useTranslation('common');
```

Choose whichever namespace is used most frequently. If more calls override than use the declared namespace, switch it.

## keyPrefix

`keyPrefix` is useful when many keys share a deep prefix, it keeps `t()` calls short. But it conflicts with `{ns: '...'}` overrides (the prefix is applied before the namespace switch, producing wrong keys). If you need both, drop `keyPrefix` and prefix manually:

```tsx
// GOOD, keyPrefix alone, no namespace overrides needed
const {t} = useTranslation('pages', {keyPrefix: 'onboarding.step1'});
t('title'); // → pages:onboarding.step1.title
t('subtitle'); // → pages:onboarding.step1.subtitle

// BAD, keyPrefix + namespace override: prefix is misapplied
const {t} = useTranslation('pages', {keyPrefix: 'onboarding.step1'});
t('previous', {ns: 'common'}); // ❌ looks up common:onboarding.step1.previous

// GOOD, drop keyPrefix when namespace overrides needed
const {t} = useTranslation('pages');
t('onboarding.step1.title');
t('previous', {ns: 'common'}); // ✓
```

## Dynamic Translation Keys

i18next's typed `t()` only accepts statically-known keys. Template literals with `${string}` fail type-checking.

**Fix:** Ensure the interpolated value has a literal union type, not `string`.

```tsx
// BAD, value is string
const options = values.map((value) => ({
  label: t(`exercises.categoryValues.${value}`), // TS error
  value,
}));

// BAD, casting is a workaround
label: t(`exercises.categoryValues.${value}` as 'exercises.categoryValues.cardio'),

// GOOD, value is ExerciseCategory (literal union), typed at prop/LoaderData level
import type {ExerciseCategory} from '~/types/database';
// categoryOptions: ExerciseCategory[]  ← typed upstream, no cast needed
const options = categoryOptions.map((value) => ({
  label: t(`exercises.categoryValues.${value}`), // ✓ TypeScript happy
  value,
}));
```

**Where to define the union type:** add it to `app/types/database.ts` alongside other DB-derived types. Then use it in `LoaderData`, component props, and anywhere else the value flows, the template literal in `t()` will just work.

## Inline Styled Segments (Trans component)

When part of a translated string needs different styling, use `Trans` with XML tags, never split into separate keys:

```ts
// Translation string
previousWorkout: 'Previous <accent>Workout</accent>',
```

```tsx
// Component
import {Trans} from 'react-i18next';

// Pass ns as a separate prop, never embed it in i18nKey.
// i18nKey is namespace-relative: "dashboard.previousWorkout", not "pages:dashboard.previousWorkout"
<Trans
  components={{accent: <span className="text-orange-500" />}}
  i18nKey="dashboard.previousWorkout"
  ns="pages"
/>;
```

## String Deduplication

Before adding a new key:

1. Search `app/languages/en/common.ts` for generic labels
2. Search all `app/languages/en/` files for the exact string value
3. If found, reuse with namespace override: `t('key', {ns: 'namespace'})`
4. If not found, add to the most appropriate namespace

### Where shared labels belong

- **Enum display labels** → `common` namespace, snake_case keys matching DB values (enables ``t(`key.${dbValue}`, {ns: 'common'})``)
- **Generic UI actions** (Save, Cancel, Edit, etc.) → already in `common`
- **Page-specific content** → page's namespace

**Locale placeholders:** when adding a new locale folder, copy the English string verbatim, no empty strings, no TODO comments. Translation happens in a separate pass.

## Plurals

i18next uses `_one`/`_other` key suffixes for pluralization:

```ts
// Translation file (en)
exerciseCount_one: '{{count}} exercise',
exerciseCount_other: '{{count}} exercises',
```

```tsx
// Component, i18next selects the right suffix automatically
t('exerciseCount', {count: n});
```

Always define both `_one` and `_other`. For locales without grammatical plural (e.g. Japanese, Chinese), define only `_other`.