noir-form-scaffold

name	noir-form-scaffold
description	Scaffold a React form in NOIR following the 4-rule validation standard (useValidatedForm + Zod schema + FormErrorBanner + auto-detected required fields). Use when the user asks to create, add, or build a new form, dialog form, settings form, or edit form on the frontend. Prevents the common mistakes covered in `.claude/rules/form-validation-standard.md`.

noir-form-scaffold — Forms that pass the 4-rule standard

NOIR has a mandatory form validation standard. Forms built without it produce bugs like: errors shown while user is typing, required asterisks missing, server errors shown as toasts instead of inline, or errors persisting after dialog re-open. This skill walks the canonical pattern.

Inputs to collect

Before writing code, confirm:

1. Form location: dialog (CredenzaBody) vs page (src/portal-app/...FormPage.tsx) vs settings tab (...SettingsTab.tsx)
2. Entity name (PascalCase, singular): Brand, Promotion, Employee
3. Operation: create-only, edit-only, or combined (same component handles both)
4. Backend contract: the Zod schema — is it auto-generated from FluentValidation via pnpm run generate:api, or hand-written?
5. Special fields: rich text (RichTextEditor), file upload, date picker, color picker, multi-select (Combobox), tags

If the backend command/DTO doesn't exist yet, STOP and invoke noir-feature-add first.

Step 1 — Generate / locate the Zod schema

If backend has FluentValidation:

cd src/NOIR.Web/frontend && pnpm run generate:api

Look for the schema at src/validation/generated/{Entity}{Operation}Schema.ts.

If hand-writing: follow the pattern in src/validation/ — use z.string().min(1, t('validation.required')) etc. For i18n:

import { z } from 'zod'
import type { TFunction } from 'i18next'

export const createBrandSchema = (t: TFunction) => z.object({
  name: z.string().min(1, t('validation.required')).max(200, t('validation.maxLength', { max: 200 })),
  slug: z.string().optional(),
  isActive: z.boolean().default(true),
})
export type CreateBrandFormData = z.infer<ReturnType<typeof createBrandSchema>>

Step 2 — Component skeleton (canonical)

Reference implementations (read one before writing yours — Rule 1):

• Dialog form (gold standard): src/portal-app/catalog/brands/BrandDialog.tsx
• Page-level form: src/portal-app/catalog/products/ProductFormPage.tsx
• Settings tab: src/portal-app/settings/tabs/SmtpSettingsTab.tsx

Skeleton:

import { useTranslation } from 'react-i18next'
import { zodResolver } from '@hookform/resolvers/zod'
import type { Resolver } from 'react-hook-form'
import { useValidatedForm } from '@/hooks/useValidatedForm'
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '@uikit/form'
import { FormErrorBanner, Input, Button, Credenza, CredenzaContent, CredenzaHeader, CredenzaTitle, CredenzaBody, CredenzaFooter } from '@uikit'
import { createBrandSchema, type CreateBrandFormData } from '@/validation/brandSchema'
import { useCreateBrand } from '@/queries/useBrandMutations'
import { toast } from 'sonner'

interface BrandDialogProps {
  open: boolean
  :  
  ?:    
}

   = () => {
   { t } = ()
   createMutation = ()
   updateMutation = ()
   isEdit = !!brand

   { form, handleSubmit, serverErrors, dismissServerErrors, requiredFields } = ({
    : (t),
    : {
      : brand?. ?? ,
      : brand?. ?? ,
      : brand?. ?? ,
    },
    :  (data) => {
       (isEdit) {
         updateMutation.({ : brand., ...data })
        toast.(())
      }  {
         createMutation.(data)
        toast.(())
      }
      ()
    },
  })

  
  ( {
     (open) {
      form.({
        : brand?. ?? ,
        : brand?. ?? ,
        : brand?. ?? ,
      })
      ()
    }
  }, [open, brand])

   (
    
  )
}

Step 3 — The 4 non-negotiable rules (from form-validation-standard.md)

1. Required field asterisks — requiredFields={requiredFields} on <Form>. Never hardcode required on labels.
2. Validation timing — useValidatedForm sets mode: 'onBlur' + reValidateMode: 'onChange'. Never override to 'onBlur'.
3. Server errors — FormErrorBanner as first child of CredenzaBody/form body. Never toast.error() for form submit failures. handleFormError is wired into useValidatedForm automatically.
4. BE ↔ FE sync — schema mirrors FluentValidation. Regenerate after backend changes: pnpm run generate:api.

Step 4 — i18n keys

Add to BOTH en/common.json and vi/common.json:

// en
"brands": {
  "createBrand": "Create Brand",
  "editBrand": "Edit Brand",
  "name": "Name",
  "createSuccess": "Brand created successfully",
  "updateSuccess": "Brand updated successfully"
}

// vi — sentence case, pure Vietnamese (no mixing)
"brands": {
  "createBrand": "Tạo thương hiệu",
  "editBrand": "Chỉnh sửa thương hiệu",
  "name": "Tên",
  "createSuccess": "Đã tạo thương hiệu",
  "updateSuccess": "Đã cập nhật thương hiệu"
}

Step 5 — URL-synced dialog state (if list page)

Wire the dialog open state to URL params (per url-tab-state.md):

const { isOpen: isCreateOpen, open: openCreate, onOpenChange: onCreateOpenChange } = useUrlDialog({ paramValue: 'create-brand' })
const { editItem, openEdit, onEditOpenChange } = useUrlEditDialog<BrandDto>(brands)

<BrandDialog
  open={isCreateOpen || !!editItem}
  onOpenChange={(open) => {
    if (!open) {
      if (isCreateOpen) onCreateOpenChange(false)
      if (editItem) onEditOpenChange(false)
    }
  }}
  brand={editItem}
/>

The conditional close is critical — calling both setters in the same tick causes the second to overwrite the first.

Step 6 — Verify

cd src/NOIR.Web/frontend && pnpm run build    # must pass — strict mode
pnpm test                                      # if form has unit tests

Browser check:

• Submit empty form → inline errors under required fields, red asterisks on labels
• Focus a field with an error → error text hides while focused
• Type a valid value and blur → error clears
• Submit with backend 400 (e.g. duplicate slug) → FormErrorBanner shows at top; field-specific errors inline
• Reopen dialog → no stale errors

Common mistakes this skill prevents

• Missing requiredFields on <Form> → no red asterisks
• Missing reValidateMode: 'onChange' → errors persist while user types the fix
• toast.error() on submit failure → user loses the message, can't re-read it
• Forgetting setServerErrors([]) / dismissServerErrors() on dialog open → stale errors from previous submit
• result.error.errors in Zod → throws; must be result.error.issues (Zod v3+)
• zodResolver(createSchema(t)) without as unknown as Resolver<FormData> → type mismatch due to z.default()
• Hand-writing useForm({...}) instead of useValidatedForm → drops one of the 4 rules
• Raw <input> instead of <Input> from @uikit (violates component-based-design.md)
• VI labels mixing English (e.g. "Tên Brand" instead of "Tên thương hiệu")