@famgia/omnify-typescript 0.0.67 → 0.0.69

package/stubs/ai-guides/cursor/react-design.mdc.stub

@@ -0,0 +1,289 @@
+---
+description: Frontend Design System - Japanese Business UI Guidelines
+globs: ["{{TYPESCRIPT_BASE}}/**/*.tsx", "{{TYPESCRIPT_BASE}}/**/*.css"]
+alwaysApply: false
+---
+
+# React Design System
+
+## Overview
+
+This design system follows **Japanese Business UI principles**: compact, functional, and minimal.
+Primary color: Violet (#7C3AED).
+
+## Design Principles
+
+### 日本のビジネスUI (Japanese Business UI)
+
+1. **コンパクト (Compact)** - High information density, minimal wasted space
+2. **機能的 (Functional)** - Prioritize usability and efficiency
+3. **シンプル (Simple)** - Minimize visual noise, flat design
+4. **高密度 (High Density)** - More information visible on screen
+
+## Color System
+
+### HSL-Based Color Harmony
+
+All colors follow HSL color theory with consistent saturation (~84%) for harmony.
+
+```
+Primary Hue: 258° (Violet)
+```
+
+### Brand Colors
+
+| Role              | Hex       | HSL            | Usage                            |
+| ----------------- | --------- | -------------- | -------------------------------- |
+| **Primary**       | `#7C3AED` | 258°, 84%, 58% | Buttons, links, sidebar, accents |
+| **Primary Light** | `#9061F9` | 258°, 84%, 68% | Hover states, selected items     |
+| **Primary Dark**  | `#6D28D9` | 258°, 84%, 50% | Active states, sub-menus         |
+
+### Semantic Colors (Complementary Harmony)
+
+| Role        | Hex       | HSL            | Usage                              |
+| ----------- | --------- | -------------- | ---------------------------------- |
+| **Success** | `#10B981` | 160°, 84%, 39% | Success messages, positive actions |
+| **Warning** | `#F59E0B` | 38°, 92%, 50%  | Warnings, caution states           |
+| **Error**   | `#EF4444` | 0°, 84%, 60%   | Errors, destructive actions        |
+
+### Neutral Colors (Violet Undertone)
+
+| Role                     | Hex       | Usage                         |
+| ------------------------ | --------- | ----------------------------- |
+| **Text Primary**         | `#1E1B2E` | Main text, headings           |
+| **Text Secondary**       | `#4B5563` | Secondary text, labels        |
+| **Text Tertiary**        | `#9CA3AF` | Placeholder, disabled text    |
+| **Background Layout**    | `#F8F7FA` | Page background (violet-gray) |
+| **Background Container** | `#FFFFFF` | Cards, containers             |
+| **Border**               | `#E5E7EB` | Borders, dividers             |
+| **Border Secondary**     | `#F3F4F6` | Subtle borders                |
+
+### Color Usage Rules
+
+1. **60-30-10 Rule**: 60% neutral, 30% primary, 10% accent
+2. **Same Saturation Family**: Keep semantic colors at ~84% saturation
+3. **Cool Tone Neutrals**: Grays should have slight violet undertone
+4. **WCAG AA Compliance**: Maintain contrast ratio ≥ 4.5:1 for text
+
+## Typography
+
+### Locale-Specific Font Stacks
+
+```typescript
+const fontFamilies = {
+  // Japanese - CJK optimized
+  ja: "'Noto Sans JP', 'Hiragino Sans', 'Hiragino Kaku Gothic ProN', Meiryo, sans-serif",
+  
+  // English - Modern western
+  en: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+  
+  // Vietnamese - Light, clean font with diacritics support
+  vi: "'Inter', 'Nunito Sans', -apple-system, BlinkMacSystemFont, sans-serif",
+};
+```
+
+### Font Sizes (Compact)
+
+| Token              | Size | Usage          |
+| ------------------ | ---- | -------------- |
+| `fontSize`         | 13px | Base text      |
+| `fontSizeLG`       | 14px | Large text     |
+| `fontSizeHeading1` | 24px | Page titles    |
+| `fontSizeHeading2` | 20px | Section titles |
+| `fontSizeHeading3` | 16px | Card titles    |
+| `fontSizeHeading4` | 14px | Sub-headings   |
+| `fontSizeHeading5` | 13px | Small headings |
+
+### Line Height
+
+- Default: `1.5` (compact, suitable for Japanese text)
+
+## Spacing System
+
+### Compact Spacing Scale
+
+| Token       | Value | Usage           |
+| ----------- | ----- | --------------- |
+| `paddingXS` | 4px   | Minimal spacing |
+| `paddingSM` | 8px   | Small spacing   |
+| `padding`   | 12px  | Default spacing |
+| `paddingLG` | 16px  | Large spacing   |
+| `marginXS`  | 4px   | Minimal margin  |
+| `marginSM`  | 8px   | Small margin    |
+| `margin`    | 12px  | Default margin  |
+| `marginLG`  | 16px  | Large margin    |
+
+### Layout Spacing
+
+- Content margin: `12px`
+- Content padding: `16px`
+- Header height: `48px`
+- Sidebar width: `180px`
+
+## Border Radius
+
+### Subtle, Professional Corners
+
+| Token            | Value | Usage                    |
+| ---------------- | ----- | ------------------------ |
+| `borderRadiusSM` | 2px   | Tags, badges             |
+| `borderRadius`   | 4px   | Buttons, inputs, cards   |
+| `borderRadiusLG` | 6px   | Modals, large containers |
+
+> **Note**: Japanese business UIs prefer subtle corners over heavily rounded designs.
+
+## Shadows
+
+### Almost Flat Design
+
+```css
+/* Primary shadow - very subtle */
+boxShadow: "0 1px 2px rgba(0, 0, 0, 0.03)"
+
+/* Secondary shadow - hover states */
+boxShadowSecondary: "0 1px 3px rgba(0, 0, 0, 0.04)"
+```
+
+> **Note**: Prefer borders over shadows for Japanese business style.
+
+## Control Sizes
+
+### Compact Controls
+
+| Token             | Value | Usage                 |
+| ----------------- | ----- | --------------------- |
+| `controlHeightSM` | 28px  | Small buttons, inputs |
+| `controlHeight`   | 32px  | Default controls      |
+| `controlHeightLG` | 36px  | Large controls        |
+
+## Component Guidelines
+
+### Buttons
+
+```typescript
+Button: {
+  controlHeight: 32,
+  paddingInline: 12,
+  fontWeight: 500,
+}
+```
+
+### Inputs
+
+```typescript
+Input: {
+  controlHeight: 32,
+  paddingInline: 8,
+}
+```
+
+### Tables
+
+```typescript
+Table: {
+  cellPaddingBlock: 8,
+  cellPaddingInline: 8,
+  headerBg: "#F8F7FA",
+}
+```
+
+### Forms
+
+```typescript
+Form: {
+  itemMarginBottom: 16,
+  verticalLabelPadding: "0 0 4px",
+}
+```
+
+### Menu (Dark Theme for Sidebar)
+
+```typescript
+Menu: {
+  itemHeight: 36,
+  itemMarginBlock: 2,
+  itemMarginInline: 4,
+  darkItemBg: "#7C3AED",
+  darkSubMenuItemBg: "#6D28D9",
+  darkItemSelectedBg: "#9061F9",
+  darkItemSelectedColor: "#FFFFFF",
+  darkItemColor: "rgba(255, 255, 255, 0.9)",
+  darkItemHoverBg: "rgba(144, 97, 249, 0.6)",
+  darkItemHoverColor: "#FFFFFF",
+}
+```
+
+### Layout
+
+```typescript
+Layout: {
+  siderBg: "#7C3AED",
+  headerPadding: "0 16px",
+  headerHeight: 48,
+}
+```
+
+## Implementation
+
+### Ant Design Theme Configuration
+
+All design tokens are configured in:
+```
+frontend/src/components/AntdThemeProvider.tsx
+```
+
+### Google Fonts Loading
+
+Fonts are loaded in:
+```
+frontend/src/app/layout.tsx
+```
+
+Required fonts:
+- Noto Sans JP (Japanese)
+- Inter (English)
+- Be Vietnam Pro (Vietnamese)
+
+## Do's and Don'ts
+
+### ✅ Do
+
+- Use compact spacing (8-16px)
+- Keep shadows minimal or none
+- Use subtle border radius (2-6px)
+- Maintain high information density
+- Use locale-specific fonts
+- Follow HSL color harmony
+
+### ❌ Don't
+
+- Use excessive padding (>24px)
+- Use heavy shadows
+- Use large border radius (>10px)
+- Leave large empty spaces
+- Mix warm and cool grays
+- Use colors outside the harmony system
+
+## Quick Reference
+
+```typescript
+// Primary colors
+const primary = "#7C3AED";
+const primaryLight = "#9061F9";
+const primaryDark = "#6D28D9";
+
+// Semantic colors
+const success = "#10B981";
+const warning = "#F59E0B";
+const error = "#EF4444";
+
+// Neutrals
+const textPrimary = "#1E1B2E";
+const bgLayout = "#F8F7FA";
+const border = "#E5E7EB";
+
+// Sizes
+const controlHeight = 32;
+const borderRadius = 4;
+const padding = 12;
+```

package/stubs/ai-guides/cursor/react-form.mdc.stub

@@ -0,0 +1,277 @@
+---
+description: "Form development guide - Omnify patterns, Zod validation, backend errors"
+globs: ["{{TYPESCRIPT_BASE}}/features/**", "{{TYPESCRIPT_BASE}}/components/**"]
+alwaysApply: false
+---
+
+# Form Development Guide
+
+## Quick Start
+
+```tsx
+import { Form, Input, Button, Space, Card, Divider } from 'antd';
+import type { FormInstance } from 'antd';
+import { zodRule, setZodLocale } from '@/omnify/lib';
+import { OmnifyForm } from '@/omnify/components';
+import {
+  type Customer,
+  type CustomerCreate,
+  customerSchemas,
+  customerI18n,
+  getCustomerFieldLabel,
+  getCustomerFieldPlaceholder,
+} from '@/omnify/schemas';
+
+const LOCALE = 'ja'; // TODO: Get from context
+
+export function CustomerForm({
+  form,
+  initialValues,
+  onSubmit,
+  loading = false,
+  isEdit = false,
+  onCancel,
+}: {
+  form: FormInstance<CustomerCreate>;
+  initialValues?: Partial<Customer>;
+  onSubmit: (values: CustomerCreate) => void;
+  loading?: boolean;
+  isEdit?: boolean;
+  onCancel?: () => void;
+}) {
+  // Set locale for validation messages
+  setZodLocale(LOCALE);
+
+  // Helper functions
+  const label = (key: string) => getCustomerFieldLabel(key, LOCALE);
+  const placeholder = (key: string) => getCustomerFieldPlaceholder(key, LOCALE);
+  const rule = (key: keyof typeof customerSchemas) =>
+    zodRule(customerSchemas[key], label(key));
+
+  return (
+    <Card>
+      <Form
+        form={form}
+        layout="horizontal"
+        labelCol={{ span: 6 }}
+        wrapperCol={{ span: 18 }}
+        initialValues={initialValues}
+        onFinish={onSubmit}
+        style={{ maxWidth: 800 }}
+      >
+        {/* Section: Contact */}
+        <Divider orientation="left">Contact</Divider>
+
+        <Form.Item
+          name="email"
+          label={label('email')}
+          rules={[rule('email')]}
+        >
+          <Input type="email" placeholder={placeholder('email')} />
+        </Form.Item>
+
+        {/* Submit Buttons */}
+        <Form.Item wrapperCol={{ offset: 6, span: 18 }}>
+          <Space>
+            <Button type="primary" htmlType="submit" loading={loading}>
+              {isEdit ? 'Update' : 'Create'}
+            </Button>
+            {onCancel && <Button onClick={onCancel}>Cancel</Button>}
+          </Space>
+        </Form.Item>
+      </Form>
+    </Card>
+  );
+}
+```
+
+## Key Patterns
+
+### 1. Imports
+
+```tsx
+// Omnify utilities
+import { zodRule, setZodLocale } from '@/omnify/lib';
+import { OmnifyForm } from '@/omnify/components';
+
+// Model-specific (generated by Omnify)
+import {
+  type Customer,
+  type CustomerCreate,
+  customerSchemas,
+  customerI18n,
+  getCustomerFieldLabel,
+  getCustomerFieldPlaceholder,
+} from '@/omnify/schemas';
+```
+
+### 2. Helper Functions (MUST define in every form)
+
+```tsx
+const LOCALE = 'ja'; // Get from context in real app
+
+// Set locale once at start
+setZodLocale(LOCALE);
+
+// Define helper functions
+const label = (key: string) => getCustomerFieldLabel(key, LOCALE);
+const placeholder = (key: string) => getCustomerFieldPlaceholder(key, LOCALE);
+const rule = (key: keyof typeof customerSchemas) =>
+  zodRule(customerSchemas[key], label(key));
+```
+
+### 3. Form.Item Pattern
+
+```tsx
+<Form.Item
+  name="email"                        // Field name (matches backend)
+  label={label('email')}              // i18n label
+  rules={[rule('email')]}             // Zod validation
+>
+  <Input 
+    type="email" 
+    placeholder={placeholder('email')} // i18n placeholder
+  />
+</Form.Item>
+```
+
+### 4. Section Dividers
+
+```tsx
+<Divider orientation="left">Contact Info</Divider>
+```
+
+## Compound Fields (Japan Plugin)
+
+For Japanese compound types, use `OmnifyForm` components:
+
+### JapaneseName
+
+```tsx
+<OmnifyForm.JapaneseName
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="name"
+  required
+/>
+```
+
+### JapaneseAddress
+
+```tsx
+<OmnifyForm.JapaneseAddress
+  form={form}
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="address"
+/>
+```
+
+### JapaneseBank
+
+```tsx
+<OmnifyForm.JapaneseBank
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="bank"
+/>
+```
+
+## Props Pattern
+
+```tsx
+interface CustomerFormProps {
+  form: FormInstance<CustomerCreate>;    // REQUIRED - from parent
+  initialValues?: Partial<Customer>;     // For edit mode
+  onSubmit: (values: CustomerCreate) => void;
+  loading?: boolean;
+  isEdit?: boolean;
+  onCancel?: () => void;
+}
+```
+
+## Page Component (Parent)
+
+```tsx
+import { Form } from 'antd';
+import { useFormMutation } from '@/hooks/useFormMutation';
+import { customerService } from '@/services/customers';
+import { queryKeys } from '@/lib/queryKeys';
+import { CustomerForm } from '@/features/customers/CustomerForm';
+import type { CustomerCreate } from '@/omnify/schemas';
+
+export default function CreateCustomerPage() {
+  const [form] = Form.useForm<CustomerCreate>();
+
+  const { mutate, isPending } = useFormMutation({
+    form,
+    mutationFn: customerService.create,
+    invalidateKeys: [queryKeys.customers.all],
+    successMessage: "messages.created",
+    redirectTo: "/customers",
+  });
+
+  return (
+    <CustomerForm
+      form={form}
+      onSubmit={(values) => mutate(values)}
+      loading={isPending}
+    />
+  );
+}
+```
+
+## Backend Errors (422)
+
+`useFormMutation` automatically handles:
+1. `form.setFields(getFormErrors(error))` - display on form fields
+2. `message.error(validationMessage)` - toast message
+
+**Field names MUST match Laravel:**
+```tsx
+// Laravel: { errors: { "name_lastname": ["..."] } }
+<Form.Item name="name_lastname">  // ✅ Matches
+<Form.Item name="lastName">       // ❌ Doesn't match
+```
+
+## Checklist
+
+- [ ] Import from `@/omnify/lib`, `@/omnify/components`, `@/omnify/schemas`
+- [ ] Define `label()`, `placeholder()`, `rule()` helper functions
+- [ ] Call `setZodLocale(LOCALE)` at start
+- [ ] Form receives `form` prop from parent (not create own)
+- [ ] Use `Divider` for sections
+- [ ] Use `OmnifyForm.*` for compound fields (JapaneseName, etc.)
+- [ ] Field names match Laravel field names
+- [ ] Submit buttons with loading state
+
+## Common Mistakes
+
+```tsx
+// ❌ Wrong - Create form instance in form component
+function MyForm() {
+  const [form] = Form.useForm();  // DON'T create here
+  return <Form form={form}>...
+}
+
+// ✅ Correct - Receive from parent
+function MyForm({ form }: { form: FormInstance }) {
+  return <Form form={form}>...
+}
+```
+
+```tsx
+// ❌ Wrong - Inline validation message
+rules={[{ required: true, message: 'Email is required' }]}
+
+// ✅ Correct - Use zodRule with i18n
+rules={[rule('email')]}
+```
+
+```tsx
+// ❌ Wrong - Hardcoded placeholder
+<Input placeholder="Enter email" />
+
+// ✅ Correct - Use placeholder helper
+<Input placeholder={placeholder('email')} />
+```