@famgia/omnify-laravel 0.0.119 → 0.0.121

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

@@ -0,0 +1,336 @@
+---
+description: "React + Ant Design + TanStack Query rules for Omnify projects: component patterns, form validation with Zod, i18n, service layer, and generated types. Apply when creating React components, forms, or API integrations."
+globs: ["{{TYPESCRIPT_BASE}}/**/*.{ts,tsx}"]
+alwaysApply: false
+---
+
+# React + Ant Design Rules
+
+> **Related Rules:**
+> - **Form Development:** `.cursor/rules/omnify/react-form.mdc`
+> - **Design System:** `.cursor/rules/omnify/react-design.mdc`
+> - **Services:** `.cursor/rules/omnify/react-services.mdc`
+> - **Schema Creation:** `.cursor/rules/omnify/schema-create.mdc` (mention `@schema-create` in chat)
+
+## Guide Documentation
+
+- Read `.claude/omnify/guides/react/` for patterns
+
+## Critical Rules
+
+1. **Use Ant Design** - Don't recreate existing components
+2. **Use Omnify types** - Import from `@/types/model`, don't duplicate
+3. **Use i18n** - Use `useTranslations()` for UI text
+4. **Service Layer** - API calls in `services/`, not components
+5. **TanStack Query** - For all server state, no `useState` + `useEffect`
+
+## Quick Patterns
+
+### Service
+
+```typescript
+export const userService = {
+  list: (params?: UserListParams) => api.get("/api/users", { params }).then(r => r.data),
+  create: (input: UserCreate) => api.post("/api/users", input).then(r => r.data.data),
+};
+```
+
+### Query
+
+```typescript
+const { data, isLoading } = useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: () => userService.list(filters),
+});
+```
+
+### Mutation
+
+```typescript
+const mutation = useMutation({
+  mutationFn: userService.create,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+    message.success(t("messages.created"));
+  },
+  onError: (error) => form.setFields(getFormErrors(error)),
+});
+```
+
+## Types Rule
+
+```typescript
+// ✅ Use Omnify-generated types
+import type { User, UserCreate } from "@/types/model";
+
+// ✅ Only define query params locally
+export interface UserListParams { ... }
+
+// ❌ Don't redefine Omnify types
+export interface UserCreateInput { ... }  // WRONG
+```
+
+## ⚠️ Enum Usage Rules (CRITICAL)
+
+**ALWAYS use generated Enums** - NEVER inline union types or type extractions!
+
+### ❌ BAD Patterns (FORBIDDEN)
+
+```typescript
+// ❌ Complex type extraction - FORBIDDEN!
+newFilter.approval_status = status as NonNullable<ListParams["filter"]>["approval_status"];
+
+// ❌ Hardcoded union type - NOT DRY!
+newFilter.approval_status = status as "pending" | "approved" | "rejected";
+
+// ❌ Using string type - NO TYPE SAFETY!
+const [status, setStatus] = useState<string>("");
+
+// ❌ Hardcoded comparisons
+if (status === "pending") { ... }
+```
+
+### ✅ GOOD Patterns (REQUIRED)
+
+```typescript
+// ✅ Import Enum from generated file
+import { 
+  ApprovalStatus, 
+  ApprovalStatusValues,
+  isApprovalStatus,
+  getApprovalStatusLabel
+} from "@/omnify/enum/ApprovalStatus";
+
+// ✅ Type assertions with Enum
+newFilter.approval_status = status as ApprovalStatus;
+
+// ✅ State with Enum type
+const [status, setStatus] = useState<ApprovalStatus | "">(""); 
+// OR with default value:
+const [status, setStatus] = useState<ApprovalStatus>(ApprovalStatus.Pending);
+
+// ✅ Enum comparisons
+if (status === ApprovalStatus.Pending) { ... }
+
+// ✅ Iterate with Values array
+const options = ApprovalStatusValues.map(value => ({
+  value,
+  label: getApprovalStatusLabel(value, locale)
+}));
+
+// ✅ Type guard for validation
+if (isApprovalStatus(unknownValue)) {
+  // unknownValue is ApprovalStatus here
+}
+```
+
+### Generated Enum Files Structure
+
+```
+@/omnify/enum/
+├── ApprovalStatus.ts
+│   ├── ApprovalStatus        (enum)
+│   ├── ApprovalStatusValues  (array of all values)
+│   ├── isApprovalStatus()    (type guard)
+│   └── getApprovalStatusLabel()  (i18n label)
+├── OrderStatus.ts
+└── ...
+```
+
+### Select/Filter Options Pattern
+
+```typescript
+import { ApprovalStatus, ApprovalStatusValues, getApprovalStatusLabel } from "@/omnify/enum/ApprovalStatus";
+
+// ✅ Build options from Enum
+const statusOptions = ApprovalStatusValues.map(value => ({
+  value,
+  label: getApprovalStatusLabel(value, locale)
+}));
+
+<Select options={statusOptions} />
+```
+
+## Form Pattern (Omnify)
+
+> **Detailed Guide:** See `react-form.mdc` for complete form development guide.
+
+**Quick Reference:**
+
+```typescript
+// 1. Imports
+import { zodRule, setZodLocale } from '@/omnify/lib';
+import { OmnifyForm } from '@/omnify/components';
+import { customerSchemas, customerI18n, getCustomerFieldLabel } from '@/omnify/schemas';
+
+// 2. Helper functions (MUST define in every form)
+const LOCALE = 'ja';
+const label = (key: string) => getCustomerFieldLabel(key, LOCALE);
+const rule = (key: keyof typeof customerSchemas) => zodRule(customerSchemas[key], label(key));
+
+// 3. Form.Item pattern
+<Form.Item name="email" label={label('email')} rules={[rule('email')]}>
+  <Input />
+</Form.Item>
+
+// 4. Japanese compound fields
+<OmnifyForm.JapaneseName schemas={customerSchemas} i18n={customerI18n} prefix="name" />
+<OmnifyForm.JapaneseAddress form={form} schemas={customerSchemas} i18n={customerI18n} prefix="address" />
+```
+
+## File Location
+
+| What                    | Where                                       |
+| ----------------------- | ------------------------------------------- |
+| Component (1 feature)   | `features/{feature}/`                       |
+| Component (2+ features) | `components/common/`                        |
+| Service (API)           | `services/` (ALWAYS)                        |
+| Hook (1 feature)        | `features/{feature}/`                       |
+| Hook (2+ features)      | `hooks/`                                    |
+| Zod Schema              | `schemas/{model}.ts`                        |
+| Validation utils        | `lib/form-validation.ts`, `lib/zod-i18n.ts` |
+
+## Ant Design v6 Deprecated Props
+
+| Deprecated                 | Use Instead             |
+| -------------------------- | ----------------------- |
+| `visible`                  | `open`                  |
+| `direction` (Space)        | `orientation`           |
+| `dropdownMatchSelectWidth` | `popupMatchSelectWidth` |
+
+## Ant Design Static Method Warning
+
+⚠️ **Warning:** `Static function can not consume context like dynamic theme`
+
+```typescript
+// ❌ Wrong - Static import has no context
+import { message } from "antd";
+message.success("Done");  // Warning!
+
+// ✅ Correct - Use App.useApp() hook
+import { App } from "antd";
+
+function MyComponent() {
+  const { message, notification, modal } = App.useApp();
+  message.success("Done");  // ✅ No warning
+}
+```
+
+**Note:**
+- `App` component is already wrapped in `AntdThemeProvider`
+- Just use `App.useApp()` in your component/hook
+- Applies to: `message`, `notification`, `modal`
+
+## Common Mistakes
+
+```typescript
+// ❌ Wrong
+useEffect(() => { fetchData() }, []);  // Use useQuery
+const [users, setUsers] = useState([]);  // Use TanStack for server state
+<Button>Save</Button>  // Use i18n
+
+// ✅ Correct
+const { data } = useQuery({ queryKey, queryFn });
+<Button>{t("common.save")}</Button>
+```
+
+### Form Validation Mistakes
+
+```typescript
+// ❌ Wrong - Hardcoded message in schema
+z.string().min(1, "Name is required")
+
+// ❌ Wrong - Define schema in component
+const schema = z.object({ name: z.string() });
+
+// ❌ Wrong - No field label comment
+<Form.Item name="name" label={label("name")}>
+
+// ✅ Correct - Schema in schemas/, messages in i18n/
+import { userSchemas } from "@/schemas/user";
+{/* Name */}
+<Form.Item name="name" label={label("name")} rules={[zodRule(userSchemas.name, label("name"))]}>
+```
+
+### Form.useForm() Warning
+
+⚠️ **Warning:** `Instance created by useForm is not connected to any Form element`
+
+```typescript
+// ❌ Wrong - Export hook creates unused form instance
+export function useUserForm() {
+  return Form.useForm();  // Instance not connected to any Form!
+}
+
+// ❌ Wrong - Create form instance but don't pass to Form
+const [form] = Form.useForm();
+return <Form>...</Form>  // Missing form={form}
+
+// ✅ Correct - Form instance must connect to Form
+const [form] = Form.useForm();
+return <Form form={form}>...</Form>
+```
+
+**Rule:** Each `Form.useForm()` must have exactly one corresponding `<Form form={form}>`.
+
+### Backend Validation Errors (422)
+
+⚠️ **IMPORTANT:** Form must display errors from backend!
+
+**Form component MUST receive `form` prop from parent:**
+
+```typescript
+// Form component
+interface UserFormProps {
+  form: FormInstance;  // ← REQUIRED
+  onSubmit: (values: UserCreate) => void;
+  // ...
+}
+
+export function UserForm({ form, onSubmit, ... }: UserFormProps) {
+  return (
+    <Form form={form} onFinish={onSubmit}>
+      ...
+    </Form>
+  );
+}
+```
+
+**Page creates form and handles backend errors:**
+
+```typescript
+// Page component
+export default function NewUserPage() {
+  const [form] = Form.useForm();  // ← Create in parent
+
+  const mutation = useMutation({
+    mutationFn: userService.create,
+    onSuccess: () => { ... },
+    onError: (error) => {
+      form.setFields(getFormErrors(error));  // ← Set errors from backend
+    },
+  });
+
+  return (
+    <UserForm
+      form={form}  // ← Pass to form component
+      onSubmit={(values) => mutation.mutate(values)}
+    />
+  );
+}
+```
+
+**Helper `getFormErrors`** (available in `lib/api.ts`):
+
+```typescript
+import { getFormErrors } from "@/lib/api";
+
+// Converts Laravel 422 response to Ant Design format:
+// { errors: { email: ["Email already exists"] } }
+// → [{ name: "email", errors: ["Email already exists"] }]
+```
+
+**Rules:**
+1. Form component does NOT create `Form.useForm()` - receives from parent
+2. Page creates form instance and passes down
+3. `onError` calls `form.setFields(getFormErrors(error))`

package/stubs/ai-guides/cursor/schema-create.mdc.stub

@@ -0,0 +1,344 @@
+---
+description: "Step-by-step schema creation workflow: 1) Read guide, 2) Create YAML, 3) npx omnify generate, 4) Validate output, 5) Migrate. CRITICAL: String defaults must be plain values without quotes wrapper!"
+globs: ["schemas/**/*.yaml", "schemas/**/*.yml", "{{LARAVEL_BASE}}/database/migrations/**"]
+alwaysApply: false
+---
+
+# Omnify Schema Creation Workflow
+
+> **Usage:** Mention `@schema-create` in chat OR this rule auto-applies when editing schema files
+
+## 📋 Workflow Steps
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. READ GUIDE     →  Read schema guide documentation           │
+│  2. CREATE SCHEMA  →  Create/modify YAML schema file            │
+│  3. GENERATE       →  Run `npx omnify generate`                 │
+│  4. VALIDATE       →  Check generated code matches requirements │
+│  5. MIGRATE        →  Run database migration                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Step 1: Read Schema Guide 📖
+
+**MUST READ before creating schema:**
+
+```bash
+# Read the schema guide
+cat .claude/omnify/guides/omnify/schema-guide.md
+# OR
+cat packages/omnify/ai-guides/schema-guide.md
+```
+
+**Key Documentation:**
+- Schema syntax and property types
+- Relationships (belongsTo, hasMany, etc.)
+- Validation rules (nullable, minLength, maxLength)
+- Display names (ja, en, vi)
+- Special types (JapaneseName, JapaneseAddress, etc.)
+
+---
+
+## Step 2: Create Schema 📝
+
+### Schema File Location
+
+```
+schemas/
+├── {domain}/           # Group by domain
+│   ├── {Model}.yaml    # PascalCase filename
+│   └── {Enum}.yaml     # Enum schemas
+└── shared/             # Shared enums/types
+```
+
+### Basic Schema Template
+
+```yaml
+# schemas/{domain}/{ModelName}.yaml
+name: ModelName
+kind: object
+
+displayName:
+  ja: モデル名
+  en: Model Name
+
+options:
+  timestamps: true      # created_at, updated_at
+  softDelete: false     # deleted_at
+
+properties:
+  # Required field
+  name:
+    type: String
+    length: 100
+    displayName:
+      ja: 名前
+      en: Name
+    placeholder:
+      ja: 例：田中太郎
+      en: e.g. John Doe
+
+  # Optional field
+  description:
+    type: Text
+    nullable: true
+    displayName:
+      ja: 説明
+      en: Description
+
+  # Enum field
+  status:
+    type: OrderStatus
+    default: pending
+    displayName:
+      ja: ステータス
+      en: Status
+
+  # Relationship
+  category:
+    type: Category
+    relation: belongsTo
+    nullable: true
+```
+
+### From SQL/Database Requirements
+
+When creating schema from SQL or database design:
+
+```yaml
+# SQL: VARCHAR(255) NOT NULL
+property_name:
+  type: String
+  length: 255
+
+# SQL: VARCHAR(100) NULL
+property_name:
+  type: String
+  length: 100
+  nullable: true
+
+# SQL: TEXT
+property_name:
+  type: Text
+
+# SQL: INT / BIGINT
+property_name:
+  type: Int  # or BigInt
+
+# SQL: DECIMAL(10,2)
+property_name:
+  type: Float
+
+# SQL: BOOLEAN DEFAULT false
+property_name:
+  type: Boolean
+  default: false
+
+# SQL: DATE
+property_name:
+  type: Date
+
+# SQL: DATETIME / TIMESTAMP
+property_name:
+  type: DateTime
+
+# SQL: ENUM('draft', 'published', 'archived')
+# → Create separate enum schema
+```
+
+---
+
+## Step 3: Generate Code 🔧
+
+```bash
+# Generate all code from schemas
+npx omnify generate
+```
+
+**What gets generated:**
+- TypeScript types & Zod schemas
+- Laravel migrations & models
+- API resources & controllers
+- Form requests & validation
+
+---
+
+## Step 4: Validate Generated Code ✅
+
+### ⚠️ CRITICAL for SQL-based schemas
+
+**If creating schema from SQL requirements, MUST verify:**
+
+```bash
+# 1. Check generated migration matches SQL design
+cat database/migrations/*_create_{table_name}_table.php
+
+# 2. Check TypeScript types match requirements
+cat resources/ts/omnify/schemas/{ModelName}.ts
+
+# 3. Check Laravel model relationships
+cat app/Models/{ModelName}.php
+```
+
+### Validation Checklist
+
+| Check | What to Verify |
+|-------|----------------|
+| ✅ Column names | snake_case in migration matches schema |
+| ✅ Column types | VARCHAR, TEXT, INT match schema types |
+| ✅ Nullable | NULL/NOT NULL matches `nullable: true/false` |
+| ✅ Defaults | DEFAULT values match `default:` in schema |
+| ✅ Foreign keys | Relationships generate correct FK |
+| ✅ Indexes | Required indexes are present |
+
+### If Generated Code is Wrong
+
+```
+┌─────────────────────────────────────────┐
+│  Generated code doesn't match SQL?      │
+│                                         │
+│  1. Fix the YAML schema                 │
+│  2. Run `npx omnify generate` again     │
+│  3. Verify generated code               │
+│  4. Repeat until correct                │
+└─────────────────────────────────────────┘
+```
+
+**Common fixes:**
+
+```yaml
+# Problem: Column should be nullable
+# Fix: Add nullable: true
+property_name:
+  type: String
+  nullable: true  # ← Add this
+
+# Problem: Wrong column length
+# Fix: Adjust length
+property_name:
+  type: String
+  length: 255  # ← Change this
+
+# Problem: Missing default value
+# Fix: Add default
+status:
+  type: OrderStatus
+  default: pending  # ← Add this
+
+# Problem: Wrong relationship type
+# Fix: Change relation
+category:
+  type: Category
+  relation: belongsTo  # belongsTo, hasMany, hasOne, belongsToMany
+```
+
+---
+
+## Step 5: Run Migration 🗄️
+
+```bash
+# Run migration
+php artisan migrate
+
+# If migration fails, rollback and fix
+php artisan migrate:rollback
+# Fix schema, regenerate, try again
+```
+
+---
+
+## 🔄 Complete Workflow Example
+
+```bash
+# 1. Read guide
+cat .claude/omnify/guides/omnify/schema-guide.md
+
+# 2. Create schema file
+# schemas/shop/Product.yaml
+
+# 3. Generate code
+npx omnify generate
+
+# 4. Validate (especially for SQL-based requirements)
+cat database/migrations/*_create_products_table.php
+# If wrong: fix schema → regenerate → validate again
+
+# 5. Run migration
+php artisan migrate
+```
+
+---
+
+## 📌 Quick Reference
+
+### Property Types
+
+| Type | SQL | TypeScript |
+|------|-----|------------|
+| `String` | VARCHAR | `string` |
+| `Text` | TEXT | `string` |
+| `LongText` | LONGTEXT | `string` |
+| `Int` | INT | `number` |
+| `BigInt` | BIGINT | `number` |
+| `Float` | DECIMAL | `number` |
+| `Boolean` | BOOLEAN | `boolean` |
+| `Date` | DATE | `string` |
+| `DateTime` | DATETIME | `string` |
+| `Email` | VARCHAR | `string` |
+| `Url` | VARCHAR | `string` |
+| `Json` | JSON | `Record<string, unknown>` |
+
+### Japanese Compound Types
+
+| Type | Fields Generated |
+|------|------------------|
+| `JapaneseName` | `{prefix}_lastname`, `{prefix}_firstname`, `{prefix}_kana_lastname`, `{prefix}_kana_firstname` |
+| `JapaneseAddress` | `{prefix}_postal_code`, `{prefix}_prefecture`, `{prefix}_address1`, `{prefix}_address2`, `{prefix}_address3` |
+| `JapaneseBankAccount` | `{prefix}_bank_code`, `{prefix}_bank_name`, `{prefix}_branch_code`, etc. |
+
+### Relationship Types
+
+| Relation | Description | Foreign Key |
+|----------|-------------|-------------|
+| `belongsTo` | N:1 | `{property}_id` on this table |
+| `hasMany` | 1:N | `{this_model}_id` on related table |
+| `hasOne` | 1:1 | `{this_model}_id` on related table |
+| `belongsToMany` | N:N | Pivot table |
+
+---
+
+## ⚠️ Common Mistakes
+
+```yaml
+# ❌ CRITICAL: String defaults with quotes produce CURLY QUOTES!
+default: "'cloud'"     # ❌ Produces: ''cloud'' (broken!)
+default: "'member'"    # ❌ Produces: ''member'' (broken!)
+
+# ✅ CORRECT: Just the value, no quotes wrapper
+default: cloud         # ✅ Produces: 'cloud'
+default: member        # ✅ Produces: 'member'
+
+# ❌ Wrong: Missing displayName for non-English projects
+name:
+  type: String
+  # Missing displayName!
+
+# ✅ Correct: Always add displayName
+name:
+  type: String
+  displayName:
+    ja: 名前
+    en: Name
+
+# ❌ Wrong: Hardcoded enum values in property
+status:
+  type: String
+  enum: [draft, published]  # Don't do this
+
+# ✅ Correct: Create separate enum schema
+status:
+  type: PostStatus  # Reference enum schema
+```