@famgia/omnify-typescript 0.0.67 → 0.0.69

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

@@ -0,0 +1,304 @@
+---
+description: "Frontend Services layer - API communication with backend"
+globs: ["{{TYPESCRIPT_BASE}}/services/**"]
+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`

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

@@ -0,0 +1,254 @@
+---
+description: "React + Ant Design frontend development rules"
+globs: ["{{TYPESCRIPT_BASE}}/**"]
+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`
+
+## Guide Documentation
+
+- Read `.claude/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
+```
+
+## 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))`