ghcopilot-hub 1.0.0

package/hub/skills/react-hook-form/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: react-hook-form
+description: >
+  High-performance React Hook Form patterns for Clean Architecture applications, including subscription isolation,
+  controlled-component wiring, field-array safety, async defaults, and Zod boundary design. Use this skill when
+  implementing or reviewing useForm, useWatch, useController, useFieldArray, resolver/defaultValues, or when
+  debugging form re-render/performance issues in React + TypeScript projects.
+license: Apache-2.0
+metadata:
+  author: jmgomezdev
+  version: "1.0"
+---
+
+## When to Use
+
+Use this skill when you need to:
+
+- Create or refactor form hooks in `application/{feature}/hooks/forms/`.
+- Integrate RHF with controlled UI libraries (Shadcn/Radix, MUI, AntD).
+- Diagnose re-render storms, laggy typing, or unstable form state.
+- Implement dynamic arrays with `useFieldArray` safely.
+- Decide where validation rules belong between Domain/Application/Presentation.
+
+## Progressive Loading Strategy
+
+Read only what is needed for the current task.
+
+| Scenario                                                                | Action                                                  |
+| ----------------------------------------------------------------------- | ------------------------------------------------------- |
+| Re-renders, lag, subscription issues (`watch`, `useWatch`, `formState`) | **MANDATORY**: Read `references/performance.md` fully.  |
+| UI library wiring issues (`Controller`, `useController`, Shadcn/MUI)    | **MANDATORY**: Read `references/integration.md` fully.  |
+| Dynamic rows/lists (`useFieldArray`, append/remove/reorder bugs)        | **MANDATORY**: Read `references/field-arrays.md` fully. |
+| General form setup with no special issue                                | Stay in this file only.                                 |
+
+Do NOT load reference files that are unrelated to the active scenario.
+
+## Clean Architecture Boundaries
+
+- Domain: base Zod schemas and business invariants only. No UI-only constraints.
+- Application: form hooks (`useForm*`) and mapping to defaults.
+- Presentation: rendering, input components, visual feedback, submit UX.
+
+Boundary rule:
+
+- Presentation must not import DTOs or repositories.
+- Form-specific UI rules that do not belong to enterprise business rules live in Application.
+
+## Expert Mindset
+
+Before writing form code, ask:
+
+- Subscription scope: "Who truly needs this value, and what is the smallest component that can subscribe?"
+- Validation cost: "Can this rule run on submit/blur instead of every keystroke?"
+- State ownership: "Is this server shape, domain shape, or UI-transient shape?"
+- Mutation safety: "Will this array/input operation preserve RHF internal identity and state?"
+
+These questions prevent the most common performance and consistency regressions.
+
+## Critical Patterns
+
+### 1) Stable `useForm` Baseline
+
+Always provide explicit `defaultValues` and explicit validation timing.
+
+```ts
+export function useProfileForm(): UseFormReturn<ProfileForm> {
+  return useForm<ProfileForm>({
+    resolver: zodResolver(profileSchema),
+    defaultValues: getInitialProfile(),
+    mode: "onSubmit",
+    reValidateMode: "onBlur",
+  });
+}
+```
+
+Why this matters:
+
+- Missing defaults causes uncontrolled/controlled drift and unreliable `reset` behavior.
+- Aggressive modes (`onChange`) can inflate re-render and validation cost.
+
+### 2) Isolate Subscriptions with `useWatch`
+
+Watch as deep as possible, never broadly at the form root unless you intentionally need full-form updates.
+
+```tsx
+function OrderForm() {
+  const { control, register, handleSubmit } = useOrderForm();
+
+  return (
+    <form onSubmit={handleSubmit(console.log)}>
+      <input {...register("customerName")} />
+      <ShippingPreview control={control} />
+    </form>
+  );
+}
+
+function ShippingPreview({ control }: { control: Control<OrderFormData> }) {
+  const method = useWatch({ control, name: "shippingMethod" });
+  return <p>Method: {method}</p>;
+}
+```
+
+### 3) Isolate Controlled Inputs with `useController`
+
+Wrap each controlled input in a leaf component so one input update does not re-render large parents.
+
+```tsx
+function ControlledCurrencyInput({
+  control,
+  name,
+}: {
+  control: Control<InvoiceForm>;
+  name: "amount";
+}) {
+  const { field, fieldState } = useController({ control, name });
+
+  return (
+    <>
+      <Input
+        value={field.value}
+        onBlur={field.onBlur}
+        onChange={(e) => field.onChange(Number(e.target.value || 0))}
+        ref={field.ref}
+      />
+      {fieldState.error?.message && <span>{fieldState.error.message}</span>}
+    </>
+  );
+}
+```
+
+### 4) Keep Schemas and Resolvers Stable
+
+Define schemas outside render scope. Never recreate schema/resolver per render.
+
+```ts
+export const loginSchema = z.object({
+  email: z.email(),
+  password: z.string().min(1, "Required"),
+});
+
+export function useLoginForm(): UseFormReturn<LoginForm> {
+  return useForm<LoginForm>({
+    resolver: zodResolver(loginSchema),
+    defaultValues: getInitialLogin(),
+    mode: "onSubmit",
+  });
+}
+```
+
+### 5) Use Async `defaultValues` for One-shot Hydration
+
+When initial values depend on remote data, prefer async `defaultValues` over `useEffect + reset`.
+
+```ts
+export function useProfileEditForm(userId: string): UseFormReturn<ProfileForm> {
+  return useForm<ProfileForm>({
+    resolver: zodResolver(profileSchema),
+    defaultValues: async () => {
+      const user = await getUserProfile(userId);
+      return getInitialProfile(user);
+    },
+    mode: "onSubmit",
+  });
+}
+```
+
+### 6) Field Array Identity Safety
+
+Use `field.id` as key and append complete objects only.
+
+```tsx
+const { fields, append, remove } = useFieldArray({ control, name: "items" });
+
+{
+  fields.map((field, index) => (
+    <div key={field.id}>
+      <input {...register(`items.${index}.sku`)} />
+      <button type="button" onClick={() => remove(index)}>
+        Remove
+      </button>
+    </div>
+  ));
+}
+
+<button type="button" onClick={() => append(getInitialCartItem())}>
+  Add
+</button>;
+```
+
+## Never Do This
+
+- Never call `watch()` without args in the root form by default. Reason: it subscribes the root to everything and
+  amplifies re-renders.
+
+- Never mix `register()` and `useController` for the same field. Reason: duplicate registration creates conflicting
+  state ownership.
+
+- Never build Zod schemas inside components. Reason: resolver cache is invalidated and validation cost spikes.
+
+- Never use array index as React key in `useFieldArray` lists. Reason: reorder/remove operations can corrupt
+  item-field association.
+
+- Never put DTO/API contracts in Presentation forms. Reason: it leaks infrastructure concerns and breaks layering
+  boundaries.
+
+- Never enable `shouldUnregister: true` by default in wizard-like forms. Reason: step transitions unmount fields and
+  silently drop values the user expects to persist.
+
+- Never chain array mutations like `append()` and `remove()` in the same synchronous handler. Reason: RHF internal
+  item identity can shift mid-tick, producing hard-to-reproduce row/value mismatch.
+
+## Decision Matrix
+
+| Problem                    | First Check                                            | Fallback                                                   |
+| -------------------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
+| Typing lag in big form     | Root-level `watch()` or broad `formState` subscription | Move watchers to leaf + use `useFormState`/`getFieldState` |
+| Controlled UI not updating | `onChange`/`value` mapping in `useController`          | Wrap library component in dedicated adapter                |
+| Form hydration race        | `useEffect + reset` pattern                            | Replace with async `defaultValues`                         |
+| Array rows losing values   | `key={index}` or partial `append` object               | Switch to `field.id` and complete defaults                 |
+
+## Common Failure Modes
+
+| Symptom                                       | Likely Cause                                                  | Recommended Fix                                                     |
+| --------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------- |
+| First change is missed in dependent UI        | `useWatch` subscription established after an early `setValue` | Pair `useWatch` with `getValues` for initial read, then subscribe   |
+| Wizard step values disappear                  | `shouldUnregister: true` on multi-step forms                  | Keep `shouldUnregister` disabled for wizard flows                   |
+| Numeric field flips to `NaN`                  | Empty string passed through `valueAsNumber`                   | Normalize empty input before `onChange` coercion                    |
+| Switching entity ID does not refresh defaults | Assuming async `defaultValues` re-runs automatically          | Trigger explicit `reset(nextDefaults)` when entity identity changes |
+
+## Minimal End-to-End Pattern
+
+```ts
+// Domain
+export const createProductSchema = z.object({
+  name: z.string().min(1),
+  price: z.number().nonnegative(),
+});
+
+export function getInitialCreateProduct(): z.infer<typeof createProductSchema> {
+  return { name: "", price: 0 };
+}
+
+// Application
+export function useCreateProductForm(): UseFormReturn<CreateProductForm> {
+  return useForm<CreateProductForm>({
+    resolver: zodResolver(createProductSchema),
+    defaultValues: getInitialCreateProduct(),
+    mode: "onSubmit",
+  });
+}
+```
+
+```tsx
+// Presentation
+export function CreateProductPage() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useCreateProductForm();
+
+  const onSubmit: SubmitHandler<CreateProductForm> = async (data) => {
+    await createProduct(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("name")} />
+      {errors.name?.message}
+      <input type="number" {...register("price", { valueAsNumber: true })} />
+      {errors.price?.message}
+      <button disabled={isSubmitting}>Save</button>
+    </form>
+  );
+}
+```
+
+## Commands
+
+Use VS Code native search (`#tool:search`) with these patterns:
+
+- Dangerous root subscriptions: `query: watch\(\)` (regex), path: `src`
+- Index keys in field arrays: `query: key=\{index\}` (regex), path: `src`
+- Broad `formState` usage in hot components: `query: formState`, path: `src`
+
+## Resources
+
+- Performance and subscriptions: `references/performance.md`
+- UI-library integration: `references/integration.md`
+- Dynamic arrays: `references/field-arrays.md`
+- Zod schema guidance: use the `zod` skill

package/hub/skills/react-hook-form/references/field-arrays.md

@@ -0,0 +1,98 @@
+# Field Arrays Reference (`useFieldArray`)
+
+Load this file when implementing dynamic rows/lists, reorder actions, or debugging value loss in array items.
+
+## Invariants
+
+- Use `field.id` as React key. Never use index.
+- Append/prepend/insert complete objects, not partials.
+- Keep one `useFieldArray` instance per `name`.
+- Keep operations separated when state order can change.
+
+These invariants protect RHF's internal item identity.
+
+## Correct Baseline
+
+```tsx
+const { control, register } = useOrderForm();
+const { fields, append, remove, move } = useFieldArray({
+  control,
+  name: "items",
+});
+
+return (
+  <>
+    {fields.map((field, index) => (
+      <div key={field.id}>
+        <input {...register(`items.${index}.sku`)} />
+        <input type="number" {...register(`items.${index}.qty`, { valueAsNumber: true })} />
+        <button type="button" onClick={() => remove(index)}>
+          Remove
+        </button>
+      </div>
+    ))}
+
+    <button type="button" onClick={() => append(getInitialOrderItem())}>
+      Add item
+    </button>
+  </>
+);
+```
+
+## Operation Semantics
+
+| Operation                       | Safe Usage                     | Risk                                                               |
+| ------------------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| `append` / `prepend` / `insert` | Provide full item defaults     | Partial objects break validation/state                             |
+| `remove`                        | Trigger from isolated action   | Chaining with append in same tick can create confusing transitions |
+| `move` / `swap`                 | Keep stable `field.id` keys    | Index keys corrupt mapping after reorder                           |
+| `replace`                       | Prefer for full server re-sync | Can reset dirty/touched assumptions                                |
+
+## Common Failure Modes
+
+| Symptom                                  | Root Cause                                   | Fix                                                       |
+| ---------------------------------------- | -------------------------------------------- | --------------------------------------------------------- |
+| Values jump to another row after reorder | `key={index}`                                | Use `key={field.id}`                                      |
+| New rows fail validation immediately     | Missing required properties in appended item | Use `getInitial*` full object                             |
+| Nested arrays become unstable            | Multiple hooks controlling same path         | One `useFieldArray` per path and isolate child components |
+| Row state lost with virtualization       | Rows unmount without persistent form context | Keep `FormProvider` context and verify mount strategy     |
+
+## Nested Arrays Guidance
+
+For nested paths, keep names explicit and typed where possible.
+
+```tsx
+const childArray = useFieldArray({
+  control,
+  name: `sections.${sectionIndex}.items` as const,
+});
+```
+
+Use child row components so each level subscribes only to the path it renders.
+
+## Never Do This
+
+- Never key rows by index.
+  Reason: after reorder/remove, React reuses DOM nodes for different RHF items and values appear to jump rows.
+
+- Never append partial items.
+  Reason: missing properties create mixed default/dirty state and validation behavior diverges between old and new rows.
+  Recovery: append only `getInitial*()` full objects.
+
+- Never share one array field name across multiple independent components.
+  Reason: multiple controllers mutate the same path, causing race-like updates and unstable field registration order.
+
+- Never execute `append` and `remove` for the same array in a single synchronous click handler.
+  Reason: identity recalculation can happen between operations and produce intermittent row/state mismatch.
+  Recovery: split into separate user actions or defer second mutation.
+
+## Useful Commands
+
+Use VS Code native search (`#tool:search`) with these patterns:
+
+- Risky index keys:
+  `query: key=\{index\}` (regex), path: `src`
+- `useFieldArray` usage:
+  `query: useFieldArray`, path: `src`
+- `append(` calls that may use partials:
+  `query: append\(` (regex), path: `src`

package/hub/skills/react-hook-form/references/integration.md

@@ -0,0 +1,102 @@
+# Integration Reference (UI Libraries)
+
+Load this file when wiring RHF with controlled or headless UI components (Shadcn/Radix, MUI, AntD, custom inputs).
+
+## Integration Mindset
+
+Treat every third-party input as an adapter problem:
+
+- Application owns `useForm` and schema wiring.
+- Presentation owns the component adapter.
+- Adapter maps library event/value contract <-> RHF `field` contract.
+
+If mapping is ambiguous, create a dedicated wrapper component instead of inlining custom wiring repeatedly.
+
+## Adapter Contract Checklist
+
+For any controlled component, verify all 4 mappings:
+
+- `value`
+- `onChange`
+- `onBlur`
+- `ref`
+
+Missing one usually causes dirty/touched/validation inconsistencies.
+
+## Shadcn / Radix Specifics
+
+Key point: many controls expose `onValueChange`, not native `onChange`.
+
+```tsx
+<FormField
+  control={control}
+  name="role"
+  render={({ field }) => (
+    <Select value={field.value} onValueChange={field.onChange}>
+      <SelectTrigger onBlur={field.onBlur} ref={field.ref} />
+      <SelectContent>{/* options */}</SelectContent>
+    </Select>
+  )}
+/>
+```
+
+Notes:
+
+- Do not spread `field` blindly into components that are not input-compatible.
+- Ensure the imported `Form` components are from your UI layer, not a conflicting package.
+
+## MUI Specifics
+
+MUI components can emit either event objects or direct values depending on component/version.
+
+```tsx
+<Controller
+  control={control}
+  name="amount"
+  render={({ field, fieldState }) => (
+    <TextField
+      value={field.value}
+      onChange={(e) => field.onChange(Number(e.target.value || 0))}
+      onBlur={field.onBlur}
+      inputRef={field.ref}
+      error={!!fieldState.error}
+      helperText={fieldState.error?.message}
+    />
+  )}
+/>
+```
+
+Always normalize before calling `field.onChange` when the domain type is not string.
+
+## Anti-Patterns
+
+- Never double-register a field (`register` + `Controller/useController`).
+  Reason: creates competing owners for the same value/touched/dirty lifecycle and leads to non-deterministic updates.
+
+- Never spread conversion/parsing logic across many pages.
+  Reason: numeric/date coercion drifts over time and creates inconsistent validation behavior per screen.
+  Recovery: move coercion into one reusable adapter component per input family.
+
+- Never hide library-specific event contracts behind ambiguous wrappers.
+  Reason: maintainers assume native DOM `onChange`, then break touched/blur semantics when refactoring.
+
+- Never omit `onBlur`/`ref` mapping when wiring controlled components.
+  Reason: field may appear to work while touched tracking, focus management, and validation timing become incorrect.
+
+## Verification Checklist
+
+Prioritize behavioral checks over snapshots:
+
+- Changing value updates RHF state.
+- Blur marks field as touched.
+- Validation messages appear/disappear correctly.
+- Numeric/date parsing is stable for empty and invalid values.
+
+## Useful Commands
+
+Use VS Code native search (`#tool:search`) with these patterns:
+
+- Controlled wrappers and `Controller` usage:
+  `query: useController|<Controller` (regex), path: `src`
+- Possible double registration smells:
+  `query: register\(|name=\"` (regex), path: `src/presentation`

package/hub/skills/react-hook-form/references/performance.md

@@ -0,0 +1,96 @@
+# Performance Reference (RHF)
+
+Load this file when the issue is about lag, excessive re-renders, unstable subscriptions, or expensive validation cycles.
+
+## Quick Diagnosis Flow
+
+1. Confirm where subscriptions happen.
+
+- Search root form for `watch()` and broad `formState` usage.
+- If parent subscribes, all children pay the render cost.
+
+2. Confirm validation timing.
+
+- `mode: 'onChange'` on large forms often creates avoidable work.
+- Prefer `mode: 'onSubmit'` and `reValidateMode: 'onBlur'` unless UX requires immediate feedback.
+
+3. Confirm hydration strategy.
+
+- If code uses `useEffect + reset` for initial fetch, replace with async `defaultValues`.
+- If entity identity changes later (edit A -> edit B), explicit `reset(nextDefaults)` is still required.
+
+## Subscription Rules That Matter
+
+- Use `useWatch` at the leaf where the value is consumed.
+- Use `getValues` for one-time reads in event handlers or effects.
+- Use `getFieldState(name)` for a single-field state check.
+- Use `useFormState` in child components when only a subset of form state is needed.
+
+Why:
+
+- `watch()` at root subscribes the entire form.
+- Reading full `formState` in a hot parent broadens subscriptions and increases render fan-out.
+
+## `formState` Access Pattern
+
+Bad:
+
+```tsx
+const { formState } = useFormContext<MyForm>();
+return <SaveButton disabled={!formState.isValid || formState.isSubmitting} />;
+```
+
+Better:
+
+```tsx
+const {
+  formState: { isSubmitting },
+} = useFormContext<MyForm>();
+return <SaveButton disabled={isSubmitting} />;
+```
+
+For single-field checks:
+
+```tsx
+const { getFieldState } = useFormContext<MyForm>();
+const emailState = getFieldState("email");
+```
+
+## `shouldUnregister` Decision
+
+| Scenario                                               | Use `shouldUnregister` | Why                                          |
+| ------------------------------------------------------ | ---------------------- | -------------------------------------------- |
+| Frequently mounted/unmounted conditional fragments     | Yes (case by case)     | Can reduce retained state footprint          |
+| Multi-step wizards where hidden step data must persist | No                     | Unmounted fields lose values                 |
+| Large tables with virtualization                       | Usually no             | Rows unmount often; unregister may drop data |
+
+## Common Failure Modes
+
+| Symptom                                            | Root Cause                                   | Fix                                                 |
+| -------------------------------------------------- | -------------------------------------------- | --------------------------------------------------- |
+| Typing in one field re-renders unrelated sections  | Root `watch()` or broad parent subscriptions | Move to leaf `useWatch`; split child components     |
+| First dependent render misses latest value         | Subscription created after `setValue`        | Combine `useWatch` with initial `getValues` read    |
+| Form flips uncontrolled/controlled                 | Missing `defaultValues` keys                 | Provide complete defaults for all mounted fields    |
+| Async edit form loads stale values after id change | Async defaults run once per mount            | Call `reset(getInitial(entity))` on identity change |
+
+## Never Do This
+
+- Never put `methods` (whole `useForm` object) in a dependency array.
+  Reason: object identity is unstable and can trigger loops.
+
+- Never optimize by `memo` first while root subscriptions remain broad.
+  Reason: subscription topology dominates; memo cannot fix wrong observer placement.
+
+- Never disable resolver/schema stability by rebuilding schema in render.
+  Reason: breaks caching and increases validation churn.
+
+## Useful Commands
+
+Use VS Code native search (`#tool:search`) with these patterns:
+
+- Root `watch()` usage (often a hotspot):
+  `query: watch\(\)` (regex), path: `src`
+- Potential broad `formState` reads:
+  `query: formState`, path: `src`
+- `onChange` validation mode in large forms:
+  `query: mode: 'onChange'`, path: `src`