@famgia/omnify-laravel 0.0.119 → 0.0.120

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

@@ -0,0 +1,277 @@
+---
+description: "React form development with Ant Design + Zod validation. Covers form instances, zodRule helper, Japanese compound fields (JapaneseName, JapaneseAddress), and backend 422 error handling. Apply when creating forms."
+globs: ["{{TYPESCRIPT_BASE}}/**/*Form*.tsx", "{{TYPESCRIPT_BASE}}/**/*form*.tsx"]
+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')} />
+```

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

@@ -0,0 +1,304 @@
+---
+description: "React service layer pattern: MUST read api-docs.json first, use TanStack Query for server state, define types from OpenAPI response. Apply when creating API integration or service files."
+globs: ["{{TYPESCRIPT_BASE}}/services/**/*.ts"]
+alwaysApply: false
+---
+
+# Frontend Services Rules
+
+> **API Reference:** `storage/api-docs/api-docs.json` (OpenAPI 3.0)  
+> **Base Config:** `lib/api.ts`
+
+## ⛔ MUST: Check api-docs.json FIRST!
+
+**BEFORE writing ANY service code, MUST read `storage/api-docs/api-docs.json`:**
+
+```bash
+# 1. ALWAYS read api-docs.json first
+cat storage/api-docs/api-docs.json | jq '.paths'
+
+# 2. Check specific endpoint
+cat storage/api-docs/api-docs.json | jq '.paths["/api/users"]'
+
+# 3. Check request/response schemas
+cat storage/api-docs/api-docs.json | jq '.components.schemas'
+```
+
+### Checklist (MANDATORY)
+
+- [ ] **Read api-docs.json** - NO guessing!
+- [ ] **Verify endpoint exists** - URL, method must match
+- [ ] **Copy exact parameter names** - `filter[search]` not `search`
+- [ ] **Match request body schema** - required fields, types
+- [ ] **Match response schema** - data structure
+
+### ❌ DON'T:
+```typescript
+// ❌ Guessing parameter names
+search?: string;           // WRONG - API uses filter[search]
+sort_by?: string;          // WRONG - API uses sort
+sort_order?: "asc"|"desc"; // WRONG - API uses "-field" format
+```
+
+### ✅ DO:
+```typescript
+// ✅ Copy exactly from api-docs.json
+
+// Sort has enum? → Create union type!
+export type UserSortField =
+  | "id" | "-id"
+  | "name_lastname" | "-name_lastname"
+  | "email" | "-email"
+  | "created_at" | "-created_at";
+
+export interface UserListParams {
+  sort?: UserSortField;    // Correct: type-safe from enum
+  filter?: {
+    search?: string;       // Correct: maps to filter[search]
+  };
+}
+```
+
+```bash
+# Regenerate OpenAPI docs if needed
+php artisan l5-swagger:generate
+```
+
+## Service File Structure
+
+```typescript
+/**
+ * {Resource} Service
+ *
+ * CRUD operations for {Resource} resource.
+ * Maps to Laravel {Resource}Controller.
+ */
+
+import api, { PaginatedResponse } from "@/lib/api";
+import type { Resource, ResourceCreate, ResourceUpdate } from "@/types/model";
+
+// =============================================================================
+// Types - Only query params (Create/Update come from Omnify)
+// =============================================================================
+
+/** Sort fields - MUST match api-docs.json enum! */
+export type ResourceSortField =
+  | "id" | "-id"
+  | "created_at" | "-created_at"
+  | "updated_at" | "-updated_at";
+  // Add other fields from api-docs.json enum
+
+/** Query params for listing resources */
+export interface ResourceListParams {
+  page?: number;
+  per_page?: number;
+  sort?: ResourceSortField;  // Type-safe from enum
+  filter?: {
+    search?: string;
+    // Add other filters from api-docs.json
+  };
+}
+
+// =============================================================================
+// Service
+// =============================================================================
+
+const BASE_URL = "/api/resources";
+
+export const resourceService = {
+  /**
+   * Axios auto-serializes nested objects:
+   * { filter: { search: "x" } } → ?filter[search]=x
+   */
+  list: async (params?: ResourceListParams): Promise<PaginatedResponse<Resource>> => {
+    const { data } = await api.get(BASE_URL, { params });
+    return data;
+  },
+
+  get: async (id: number): Promise<Resource> => {
+    const { data } = await api.get(`${BASE_URL}/${id}`);
+    return data.data ?? data;
+  },
+
+  create: async (input: ResourceCreate): Promise<Resource> => {
+    const { data } = await api.post(BASE_URL, input);
+    return data.data ?? data;
+  },
+
+  update: async (id: number, input: ResourceUpdate): Promise<Resource> => {
+    const { data } = await api.put(`${BASE_URL}/${id}`, input);
+    return data.data ?? data;
+  },
+
+  delete: async (id: number): Promise<void> => {
+    await api.delete(`${BASE_URL}/${id}`);
+  },
+};
+```
+
+## Types Rule
+
+```typescript
+// ✅ Import model types from Omnify
+import type { User, UserCreate, UserUpdate } from "@/types/model";
+
+// ✅ Define only query/filter params locally
+export interface UserListParams {
+  search?: string;
+  page?: number;
+  per_page?: number;
+}
+
+// ❌ DON'T redefine model types
+export interface User { ... }  // WRONG - use Omnify
+export interface UserCreateInput { ... }  // WRONG - use UserCreate
+```
+
+## Response Handling
+
+### Paginated List (GET /api/resources)
+```typescript
+// OpenAPI: Returns { data: T[], links: {...}, meta: {...} }
+list: async (params): Promise<PaginatedResponse<Resource>> => {
+  const { data } = await api.get(BASE_URL, { params });
+  return data;  // Full response with data, links, meta
+},
+```
+
+### Single Resource (GET /api/resources/:id)
+```typescript
+// OpenAPI: Returns { data: T }
+get: async (id: number): Promise<Resource> => {
+  const { data } = await api.get(`${BASE_URL}/${id}`);
+  return data.data ?? data;  // Unwrap { data: T } wrapper
+},
+```
+
+### Create/Update (POST/PUT)
+```typescript
+// OpenAPI: Returns { data: T }
+create: async (input: ResourceCreate): Promise<Resource> => {
+  const { data } = await api.post(BASE_URL, input);
+  return data.data ?? data;  // Unwrap { data: T } wrapper
+},
+```
+
+### Delete (DELETE /api/resources/:id)
+```typescript
+// OpenAPI: Returns 204 No Content
+delete: async (id: number): Promise<void> => {
+  await api.delete(`${BASE_URL}/${id}`);
+},
+```
+
+## Auth Service Pattern (Sanctum)
+
+For auth endpoints that need CSRF:
+
+```typescript
+import api, { csrf } from "@/lib/api";
+
+export const authService = {
+  login: async (input: LoginInput): Promise<void> => {
+    await csrf();  // Required for Sanctum
+    await api.post("/login", input);
+  },
+  
+  logout: async (): Promise<void> => {
+    await api.post("/logout");
+  },
+  
+  me: async (): Promise<User> => {
+    const { data } = await api.get<User>("/api/user");
+    return data;
+  },
+};
+```
+
+## OpenAPI Parameter Mapping
+
+Axios auto-serializes nested objects → **NO transform needed!**
+
+```typescript
+// Frontend interface
+{ filter: { search: "John" }, sort: "-created_at", page: 1 }
+
+// Axios auto-serializes to:
+// ?filter[search]=John&sort=-created_at&page=1
+```
+
+| OpenAPI Parameter | Frontend Interface | Notes                 |
+| ----------------- | ------------------ | --------------------- |
+| `filter[search]`  | `filter.search`    | Axios auto-serializes |
+| `page`            | `page`             | Direct                |
+| `per_page`        | `per_page`         | Direct                |
+| `sort`            | `sort`             | Use enum type!        |
+
+### Sort Field - MUST use enum!
+```typescript
+// ❌ WRONG - not type-safe
+sort?: string;
+
+// ✅ CORRECT - copy enum from api-docs.json
+export type ResourceSortField =
+  | "id" | "-id"
+  | "created_at" | "-created_at";
+
+sort?: ResourceSortField;  // Type-safe!
+```
+
+## Error Handling
+
+Errors are handled globally in `lib/api.ts`. Services should:
+- **NOT** catch errors (let them propagate to mutations/queries)
+- **NOT** show messages (handled by TanStack Query callbacks)
+
+```typescript
+// ❌ Wrong
+create: async (input) => {
+  try {
+    const { data } = await api.post(BASE_URL, input);
+    return data.data;
+  } catch (e) {
+    console.error(e);  // DON'T catch here
+  }
+},
+
+// ✅ Correct - let errors propagate
+create: async (input) => {
+  const { data } = await api.post(BASE_URL, input);
+  return data.data ?? data;
+},
+```
+
+## Naming Conventions
+
+| Item           | Convention                  | Example                      |
+| -------------- | --------------------------- | ---------------------------- |
+| File           | `{resource}.ts` (singular)  | `users.ts`, `auth.ts`        |
+| Service object | `{resource}Service`         | `userService`, `authService` |
+| List params    | `{Resource}ListParams`      | `UserListParams`             |
+| Base URL       | `/api/{resources}` (plural) | `/api/users`                 |
+
+## Checklist Before Creating Service
+
+- [ ] API endpoint exists in `storage/api-docs/api-docs.json`
+- [ ] Omnify types exist in `types/model/`
+- [ ] Request body matches OpenAPI `requestBody.content.application/json.schema`
+- [ ] Response matches OpenAPI `responses.200.content.application/json.schema`
+- [ ] Parameters match OpenAPI `parameters[]`
+
+## Quick Reference: Current API Endpoints
+
+> From `storage/api-docs/api-docs.json`:
+
+### Users API
+| Method | Endpoint          | Description                      |
+| ------ | ----------------- | -------------------------------- |
+| GET    | `/api/users`      | Paginated list with search, sort |
+| POST   | `/api/users`      | Create user                      |
+| GET    | `/api/users/{id}` | Get single user                  |
+| PUT    | `/api/users/{id}` | Update user                      |
+| DELETE | `/api/users/{id}` | Delete user                      |
+
+**Sort fields:** `id`, `name_lastname`, `name_firstname`, `email`, `created_at`, `updated_at`