Define or update the Zod schema near the owning form unless reused.
Use React Hook Form with defaultValues, zodResolver, and handleSubmit.
Normalize optional strings before sending mutation payloads.
Keep field errors next to fields and server errors in mutation state unless mapped intentionally.
Reuse shared form controls that accept native props, className, aria-invalid, and ref.

Expected Output

Forms use noValidate.
Browser required and manual FormData parsing do not own validation.
Optional empty values are omitted or converted according to the API contract.
Mutation hooks still own API calls and cache invalidation.

Verification

Check forms do not rely on browser validation for app messages.
Check optional empty values are not sent as empty strings.
Run npm --workspace @capture-flag/client run build.

Referenced Context

Reference: `ai/rules/client-form-rules.md`

Client Form Rules

Rules for forms in apps/client.

Always

Use react-hook-form for mutation forms and forms with meaningful client validation.
Use zod for form schemas when a form submits data to API mutations or has reusable validation rules.
Connect schemas with zodResolver from @hookform/resolvers/zod when using React Hook Form with Zod.
Use defaultValues for every registered React Hook Form field.
Use noValidate on forms so Zod owns validation messages.
Keep schemas close to the form unless reused by multiple forms.
Trim string values before sending them to API mutations.
Omit optional empty string values from mutation payloads instead of sending "".
Use aria-invalid on invalid fields.
Display field errors next to the field that owns them.
Use small local field wrappers such as FormField in complex forms when they reduce repeated label/control/error markup.
Lightweight filter/search forms may use local state and narrow manual validation when they only update local query filters and do not submit API mutations.
Do not ask users to type UUIDs for human UI flows; use email, search, selects, route context, or an already selected entity instead.

Never

Do not parse FormData manually in React components when React Hook Form or controlled state owns the form.
Do not rely on browser required validation for app-level messages.
Do not keep server errors in React Hook Form field state unless they map to a specific field.
Do not duplicate parsing, schema, and payload normalization across features when a colocated helper is clearer.
Do not send empty optional metadata fields when creating flags.
Do not expose raw UUID entry fields in forms for organizations, projects, configs, environments, members, flags, segments, or audit filters.

Boundaries

React Hook Form owns field state and field validation.
Zod owns client-side parsing and validation messages.
React Query mutation hooks own API calls and cache invalidation.
Server errors should remain visible from mutation state unless mapped intentionally.
Local state may own draft/applied filter values when a form only changes query filters and the validation is small and colocated.

Reference: `ai/rules/client-component-rules.md`

Client Component Rules

Rules for React component boundaries in apps/client.

Always

Extract components when UI repeats or a named component makes screen composition clearer.
Keep shared client components in src/components.
Keep context-independent utilities and reusable hooks in src/core/<category>/<name>.ts, with one exported function or hook per file.
Keep route layouts that wrap nested routes in src/layouts/<LayoutName>.
Keep route-level screens in src/pages.
Keep page-specific components and hooks under src/pages/<PageName> when they are not shared outside that page.
Import src/core utilities and hooks from their direct alias file path such as @core/json/formatJson; do not add index.ts barrels under src/core.
Import shared components directly through aliases such as @components/Button; do not assume a central src/components/index.ts barrel exists.
Keep new or substantially changed React component files in apps/client at or below 400 lines; when touching larger existing files, prefer splitting real UI responsibilities instead of expanding them further.
Keep component props small and explicit.
Prefer children for layout wrappers such as cards, shells, and empty states.
Prefer explicit JSX over array-driven rendering for a small, fixed set of known UI items.
Extract custom hooks for repeated or stateful UI behavior.
Turn repeated form field label/control/hint/error markup into small primitives before copying it again.
Shared form controls must accept native props, extra className, aria-invalid, and ref.
Add or update Storybook stories when adding or changing reusable, layout, page-specific, or route-level React components in apps/client.
Keep Storybook stories in a stories/ child folder next to the component folder they cover, using *.stories.tsx; route/panel grouping stories belong in the owning route folder's stories/ folder.
Add Storybook controls or actions for every public prop explicitly declared by the component; use controls for data props and actions for callbacks.
Keep shared component stories in src/components/stories and member component stories in src/components/members/stories.
Keep layout stories in src/layouts/<LayoutName>/stories.
Keep page or page-section stories in src/pages/<PageName>/stories or src/pages/<PageName>/<section>/stories.
Keep cross-page route or panel grouping stories in src/pages/stories.
Keep Storybook fixtures, route constants, and API mocks in src/stories; do not put component stories there.

Never

Do not extract one-off UI when it adds indirection without reuse, naming clarity, or state-boundary value.
Do not turn every extraction into a broad component library.
Do not move page, domain, route, or API-specific helpers into src/core.
Do not let route components become god components.
Do not fix a god component by moving all state and effects into a god provider or god hook.
Do not build artificial arrays just to render a handful of fixed, known navigation or action items.
Do not use React Context for mutable UI state.
Do not copy fetched React Query data into component state just to pass it down.
Do not leave component prop changes without matching Storybook args and argTypes updates.
Do not place *.stories.tsx beside component files when a nearby stories/ folder is available.

Data-Driven Rendering

Use arrays and .map() when rendering API data, dynamic collections, long repeated groups, or lists whose members are not all known at author time.
Render items directly when the UI is a short, fixed set of known product actions or navigation entries.
Split large files by ownership such as layout shell, sidebar, selectors, form, list, detail, and helper hooks; do not hide a large component behind a single large hook.

Core Utilities

Use src/core/date, src/core/json, src/core/strings, src/core/validation, or src/core/hooks only for helpers that are independent of Capture Flag domain context.
Keep tests for each core helper in src/core/<category>/__tests__/<name>.test.ts.
Prefer direct alias imports such as @core/json/formatJson over barrels or grouped core imports.

Storybook Layout

Use one *.stories.tsx file per component or cohesive route grouping.
Use shared mock entities and route strings from src/stories/mockData.ts when stories need realistic Capture Flag data.
Use the Storybook API mock installed by .storybook/preview.tsx for route and panel stories that call client API hooks.
Set route-specific parameters.router.initialEntries when a story depends on React Router params.
Prefer parameters.layout = "fullscreen" for route, layout, shell, and panel stories that need app-width context.

Verification

Ensure extracted components do not change behavior.
Check the related Storybook story was added or updated and exposes controls/actions for every public declared prop.
Run npm --workspace @capture-flag/client run storybook:build after Storybook, component, or story changes.
Run npm --workspace @capture-flag/client run build after component moves.

Reference: `ai/rules/client-api-hook-rules.md`

Client API Hook Rules

Rules for client API operations in apps/client/src/api.

Always

Group API code by domain and operation under apps/client/src/api.
Split every operation into a request function, a React Query hook, and an operation index.ts.
Keep request functions free of React imports.
Keep request functions typed with the response type they return.
Use shared request helpers from src/api/client.ts so private API calls share the /api/v1 base URL, JSON handling, API error handling, and credentials: "include" behavior.
Use useQuery or useInfiniteQuery in query hooks according to the API shape, and useMutation in mutation hooks.
Keep query keys stable in a domain-level queryKeys.ts when hooks or mutations share them.
Keep object-valued query-key inputs stable and serializable, such as applied filter DTOs.
Use enabled in query hooks when required IDs or inputs are unavailable.
Invalidate affected query keys inside mutation hooks.
Import other domain query keys inside mutation hooks when the mutation makes cross-domain server state stale.
Use explicit named exports in UI-facing barrels.

Never

Do not call raw request functions from components.
Do not expose request functions from operation or domain barrels used by UI.
Do not import domain queryKeys into components.
Do not manually synchronize server lists in components after mutations.
Do not mirror query data into Zustand or local state unless a concrete UI-only draft workflow requires it.
Do not create a central src/api/queryKeys.ts unless data is genuinely cross-domain.
Do not use fetch directly outside src/api/client.ts unless the request is intentionally outside the app API contract.

Layout

Request file: apps/client/src/api/<domain>/<operation>/<operation>.ts.
Hook file: apps/client/src/api/<domain>/<operation>/use<Operation>.ts.
Operation barrel: apps/client/src/api/<domain>/<operation>/index.ts.
Domain barrel: apps/client/src/api/<domain>/index.ts.
Query keys: apps/client/src/api/<domain>/queryKeys.ts.

Reference: `ai/examples/good-client-form.md`

Good Client Form

Source: apps/client/src/components/CreateNameForm.tsx (sha256: e60e8092b9d41bd7a2b5136ff048d6b5455abe40c796386dea079369b823e1e3) Source: apps/client/src/pages/FlagsPage/featureFlags/CreateFeatureFlagForm.tsx (sha256: a7d1e86cdb9b5082b43efe4959ecae33eb6eeda011e2a78d8df8fc7ed8a76b02)

Why this is canonical:

Keeps schema, default values, field errors, and submission in the owning form.
Uses React Hook Form with zodResolver and noValidate.
Shows field errors beside the field that owns them.
Uses a local FormField wrapper in complex forms to reduce repeated label/control/error markup.

Canonical form pattern from apps/client/src/components/CreateNameForm.tsx.

const createNameFormSchema = z.object({
  name: z.string().trim().min(1, "Enter a name.").max(120, "Use up to 120 characters."),
});

type CreateNameFormValues = z.infer<typeof createNameFormSchema>;

const {
  formState: { errors, isSubmitting },
  handleSubmit,
  register,
  reset,
} = useForm<CreateNameFormValues>({
  defaultValues: {
    name: "",
  },
  resolver: zodResolver(createNameFormSchema),
});

<form
  className="grid gap-2 sm:grid-cols-[minmax(0,1fr)_auto] sm:items-start"
  noValidate
  onSubmit={handleSubmit(submit)}
>
  <div>
    <TextInput
      aria-invalid={errors.name ? true : undefined}
      disabled={isDisabled}
      placeholder={placeholder}
      {...register("name")}
    />
    <FieldError>{errors.name?.message}</FieldError>
  </div>
  <Button className="justify-self-start" disabled={isDisabled} type="submit">
    Create
  </Button>
</form>

This pattern keeps schema, default values, noValidate, field errors, and submit reset close to the owning form.

Local Field Wrapper For Complex Forms

<FormField error={errors.key?.message} label="SDK key" required htmlFor={keyId}>
  <TextInput
    aria-invalid={errors.key ? true : undefined}
    autoComplete="off"
    disabled={isDisabled}
    id={keyId}
    placeholder="newCheckout"
    {...register("key")}
  />
</FormField>

function FormField({ children, error, htmlFor, label, required = false }: FormFieldProps) {
  return (
    <div className="grid gap-2">
      <label className="text-sm font-medium text-foreground" htmlFor={htmlFor}>
        {label}
        {required ? <span className="text-destructive"> *</span> : null}
      </label>
      {children}
      <FieldError>{error}</FieldError>
    </div>
  );
}

This pattern is local to the owning form and avoids promoting page-specific field structure into shared components too early.

client-form-validation

المزيد من هذا المستودع

المزيد من هذا المستودع

Compiled AI Skill: client-form-validation

Canonical Skill: ai/skills/client-form-validation.md