feat: implement comprehensive Form UI library with React Hook Form integration, Zod validation, and i18n support.

2026-06-15 18:40:22 +07:00
parent 00a2f218cc
commit a72b73bac4
45 changed files with 2064 additions and 10 deletions
@@ -0,0 +1,80 @@
+# @repo/ui — Shared UI Component Library
+
+The centralized UI component library for the monorepo. Provides consistent design primitives, system pages, and **a comprehensive Form UI Library** for building enterprise-grade forms.
+
+## Features
+
+- **Mantine v8** components re-exported with unified theming
+- **ThemeProvider** with dark/light mode, brand colors, and density modes (compact/standard)
+- **Design tokens** — Colors, typography, radius, spacing, shadows mapped between Mantine and Tailwind
+- **System pages** — Pre-built 404, 403, Maintenance, and Coming Soon pages
+- **Form UI Library** — 22 RHF-connected Mantine form components with Zod validation and i18n error translation
+
+## Exports
+
+| Entry Point | Path | Description |
+|---|---|---|
+| `@repo/ui/components` | `./src/components/index.ts` | All components (Mantine re-exports + system pages + Form fields) |
+| `@repo/ui/form` | `./src/components/Form/index.ts` | Form field components, `withRHF` factory, RHF/Zod re-exports |
+| `@repo/ui/hooks` | `./src/hooks/index.ts` | Mantine hooks re-export |
+| `@repo/ui/provider` | `./src/provider/index.ts` | `ThemeProvider` with color scheme and density controls |
+| `@repo/ui/theme.css` | `./src/theme.css` | Base CSS with Mantine → Tailwind token mapping |
+
+## 📋 Form UI Library
+
+> **Full Documentation**: [docs/FORM-COMPONENTS.md](docs/FORM-COMPONENTS.md)
+
+The Form UI Library wraps **all 22 applicable Mantine form components** with React Hook Form via a single `withRHF()` HOC factory. Key features:
+
+- **`useController` micro-subscriptions** — O(1) render cost per keystroke, even in 1500+ field ERP forms
+- **`React.memo` wrapper** — Prevents parent-driven cascade re-renders
+- **Zod + i18n error translation** — JSON error payloads are auto-parsed and translated via `@repo/core-i18n`
+- **Zero hardcoded styles** — All components inherit the active `ThemeProvider` configuration
+- **`Field` prefix naming** — `FieldTextInput`, `FieldSelect`, etc. to avoid collisions with native Mantine exports
+
+### Quick Start
+
+```tsx
+import { z } from 'zod';
+import { useForm, zodResolver, FieldTextInput, FieldSelect } from '@repo/ui/form';
+
+const schema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  role: z.string().min(1, 'Please select a role'),
+});
+
+function UserForm() {
+  const { control, handleSubmit } = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: { name: '', role: '' },
+  });
+
+  return (
+    <form onSubmit={handleSubmit(console.log)}>
+      <FieldTextInput name="name" control={control} label="Name" />
+      <FieldSelect
+        name="role"
+        control={control}
+        label="Role"
+        data={['Admin', 'Editor', 'Viewer']}
+      />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+## Scripts
+
+| Command | Description |
+|---|---|
+| `pnpm test` | Run unit tests (Vitest) |
+| `pnpm test:watch` | Run tests in watch mode |
+| `pnpm lint` | Run ESLint |
+
+## Dependencies
+
+- `@mantine/core` v8, `@mantine/hooks` v8
+- `react-hook-form` v7, `@hookform/resolvers` v5, `zod` v3
+- `@repo/core-i18n` (workspace)
+- `tailwindcss` v4, `tailwind-variants`, `tailwind-merge`