@famgia/omnify-laravel 0.0.119 → 0.0.120

package/stubs/ai-guides/react/i18n-guide.md.stub

@@ -0,0 +1,211 @@
+# Internationalization (i18n) Guide
+
+> **Related:** [README](./README.md) | [Ant Design](./antd-guide.md)
+
+This project uses `next-intl` for internationalization.
+
+## Current Locales
+
+| Code | Language   | Default |
+| ---- | ---------- | ------- |
+| ja   | 日本語     | ✅       |
+| en   | English    |         |
+| vi   | Tiếng Việt |         |
+
+---
+
+## Usage
+
+### Basic Translation
+
+```typescript
+import { useTranslations } from "next-intl";
+
+function MyComponent() {
+  const t = useTranslations();
+  
+  return (
+    <Button>{t("common.save")}</Button>
+  );
+}
+```
+
+### With Namespace
+
+```typescript
+const t = useTranslations("messages");
+t("created")  // "作成しました" (ja) | "Created successfully" (en)
+```
+
+### With Parameters
+
+```typescript
+t("validation.minLength", { field: "Password", min: 8 })
+// "Password must be at least 8 characters"
+```
+
+### LocaleSwitcher Component
+
+```typescript
+import LocaleSwitcher from "@/components/LocaleSwitcher";
+
+<LocaleSwitcher />  // Dropdown to switch language
+```
+
+### Get Current Locale
+
+```typescript
+import { useLocale } from "@/hooks/useLocale";
+
+function MyComponent() {
+  const { locale, setLocale, localeNames } = useLocale();
+  // locale: "ja" | "en" | "vi"
+  // setLocale: (locale) => void
+  // localeNames: { ja: "日本語", en: "English", vi: "Tiếng Việt" }
+}
+```
+
+---
+
+## Adding New Language
+
+### Step 1: Create Message File
+
+Create `src/i18n/messages/{locale}.json`:
+
+```json
+{
+  "common": {
+    "save": "저장",
+    "cancel": "취소",
+    "delete": "삭제",
+    "edit": "편집",
+    "create": "만들기",
+    "search": "검색",
+    "loading": "로딩 중...",
+    "noData": "데이터 없음",
+    "confirm": "확인",
+    "back": "뒤로",
+    "next": "다음",
+    "previous": "이전",
+    "submit": "제출",
+    "reset": "초기화",
+    "close": "닫기",
+    "yes": "예",
+    "no": "아니오"
+  },
+  "messages": {
+    "created": "생성되었습니다",
+    "updated": "업데이트되었습니다",
+    "deleted": "삭제되었습니다",
+    "saved": "저장되었습니다",
+    "error": "오류가 발생했습니다",
+    "confirmDelete": "정말 삭제하시겠습니까?",
+    "networkError": "네트워크 오류",
+    "serverError": "서버 오류",
+    "unauthorized": "로그인해 주세요",
+    "forbidden": "접근 권한이 없습니다",
+    "notFound": "찾을 수 없습니다",
+    "sessionExpired": "세션이 만료되었습니다. 페이지를 새로고침해 주세요",
+    "tooManyRequests": "요청이 너무 많습니다. 잠시 기다려 주세요"
+  },
+  "auth": {
+    "login": "로그인",
+    "logout": "로그아웃",
+    "register": "회원가입",
+    "email": "이메일",
+    "password": "비밀번호",
+    "passwordConfirm": "비밀번호 확인",
+    "rememberMe": "로그인 상태 유지",
+    "forgotPassword": "비밀번호를 잊으셨나요?",
+    "resetPassword": "비밀번호 재설정",
+    "loginSuccess": "로그인되었습니다",
+    "logoutSuccess": "로그아웃되었습니다",
+    "registerSuccess": "가입이 완료되었습니다"
+  },
+  "validation": {
+    "required": "{field}은(는) 필수입니다",
+    "email": "유효한 이메일 주소를 입력해 주세요",
+    "minLength": "{field}은(는) {min}자 이상이어야 합니다",
+    "maxLength": "{field}은(는) {max}자 이하여야 합니다",
+    "passwordMatch": "비밀번호가 일치하지 않습니다"
+  },
+  "nav": {
+    "home": "홈",
+    "dashboard": "대시보드",
+    "users": "사용자",
+    "settings": "설정",
+    "profile": "프로필"
+  }
+}
+```
+
+### Step 2: Update Config
+
+Edit `src/i18n/config.ts`:
+
+```typescript
+export const locales = ["ja", "en", "vi", "ko"] as const;  // Add new locale
+
+export const localeNames: Record<Locale, string> = {
+  ja: "日本語",
+  en: "English",
+  vi: "Tiếng Việt",
+  ko: "한국어",  // Add display name
+};
+```
+
+### Step 3: Add Ant Design Locale
+
+Edit `src/components/AntdThemeProvider.tsx`:
+
+```typescript
+import jaJP from "antd/locale/ja_JP";
+import enUS from "antd/locale/en_US";
+import viVN from "antd/locale/vi_VN";
+import koKR from "antd/locale/ko_KR";  // Add import
+
+const antdLocales = {
+  ja: jaJP,
+  en: enUS,
+  vi: viVN,
+  ko: koKR,  // Add mapping
+};
+```
+
+---
+
+## File Structure
+
+```
+src/i18n/
+├── config.ts               # Locales configuration
+├── request.ts              # Server-side locale detection
+├── index.ts                # Exports
+└── messages/
+    ├── ja.json             # Japanese translations
+    ├── en.json             # English translations
+    └── vi.json             # Vietnamese translations
+```
+
+---
+
+## Best Practices
+
+```typescript
+// ✅ DO: Use translation keys
+<Button>{t("common.save")}</Button>
+
+// ❌ DON'T: Hardcode strings
+<Button>保存</Button>
+
+// ✅ DO: Use namespaces for context
+const tAuth = useTranslations("auth");
+const tMessages = useTranslations("messages");
+
+// ✅ DO: Use parameters for dynamic content
+t("validation.minLength", { field: t("auth.password"), min: 8 })
+
+// ❌ DON'T: Concatenate strings
+`${t("auth.password")} must be at least 8 characters`
+```

package/stubs/ai-guides/react/laravel-integration.md.stub

@@ -0,0 +1,181 @@
+# Laravel Integration
+
+> **Related:** [README](./README.md) | [Service Pattern](./service-pattern.md)
+
+## Sanctum Authentication Flow
+
+```typescript
+// Step 1: Get CSRF cookie (required before POST requests)
+await api.get("/sanctum/csrf-cookie");
+
+// Step 2: Login
+await api.post("/login", { email, password });
+// Cookie is now set automatically
+
+// Step 3: Access protected routes
+await api.get("/api/user"); // Works! Cookie sent automatically
+```
+
+---
+
+## Error Handling Map
+
+| HTTP Status | Laravel Meaning     | Frontend Action           |
+| ----------- | ------------------- | ------------------------- |
+| 200         | Success             | Process response          |
+| 201         | Created             | Process response          |
+| 204         | No Content          | Success (no body)         |
+| 401         | Unauthenticated     | Redirect to `/login`      |
+| 403         | Forbidden           | Show error message        |
+| 404         | Not Found           | Show error message        |
+| 419         | CSRF Token Mismatch | Refresh page              |
+| 422         | Validation Error    | Display in form fields    |
+| 429         | Too Many Requests   | Show rate limit message   |
+| 500+        | Server Error        | Show server error message |
+
+---
+
+## API Response Types
+
+### Laravel Pagination Response
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  links: {
+    first: string | null;
+    last: string | null;
+    prev: string | null;
+    next: string | null;
+  };
+  meta: {
+    current_page: number;
+    from: number | null;
+    last_page: number;
+    per_page: number;
+    to: number | null;
+    total: number;
+  };
+}
+```
+
+### Laravel API Resource Response (single item)
+
+```typescript
+interface ResourceResponse<T> {
+  data: T;
+}
+```
+
+### Laravel Validation Error Response (422)
+
+```typescript
+interface ValidationErrorResponse {
+  message: string;
+  errors: Record<string, string[]>;
+}
+```
+
+---
+
+## Handling Laravel Responses
+
+### In Service Layer
+
+```typescript
+const userService = {
+  // Paginated list
+  list: async (params?: UserListParams): Promise<PaginatedResponse<User>> => {
+    const { data } = await api.get("/api/users", { params });
+    return data;  // Already typed as PaginatedResponse
+  },
+
+  // Single resource (handle { data: ... } wrapper)
+  get: async (id: number): Promise<User> => {
+    const { data } = await api.get(`/api/users/${id}`);
+    return data.data ?? data;  // Handle both wrapped and unwrapped
+  },
+};
+```
+
+### In Components (Form Validation)
+
+```typescript
+import { getFormErrors } from "@/lib/api";
+
+const mutation = useMutation({
+  mutationFn: userService.create,
+  onError: (error) => {
+    // Transform Laravel 422 errors to Ant Design format
+    form.setFields(getFormErrors(error));
+  },
+});
+```
+
+---
+
+## Axios Instance Configuration
+
+The `lib/api.ts` is pre-configured for Laravel Sanctum:
+
+```typescript
+const api = axios.create({
+  baseURL: process.env.NEXT_PUBLIC_API_URL,
+  timeout: 30000,
+  headers: {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  },
+  withCredentials: true,      // Required for Sanctum cookies
+  withXSRFToken: true,        // Auto send XSRF-TOKEN cookie as header
+  xsrfCookieName: "XSRF-TOKEN",
+  xsrfHeaderName: "X-XSRF-TOKEN",
+});
+```
+
+---
+
+## Common Patterns
+
+### Login Flow
+
+```typescript
+import { csrf } from "@/lib/api";
+
+const login = async (email: string, password: string) => {
+  // 1. Get CSRF cookie first
+  await csrf();
+  
+  // 2. Login
+  await api.post("/login", { email, password });
+  
+  // 3. Get user data
+  const { data } = await api.get("/api/user");
+  return data;
+};
+```
+
+### Protected API Call
+
+```typescript
+// No special handling needed - cookies are sent automatically
+const users = await userService.list();
+```
+
+### Handling 401 (Unauthenticated)
+
+The interceptor in `lib/api.ts` automatically redirects to `/login` on 401:
+
+```typescript
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      if (!window.location.pathname.includes("/login")) {
+        window.location.href = "/login";
+      }
+    }
+    return Promise.reject(error);
+  }
+);
+```

package/stubs/ai-guides/react/service-pattern.md.stub

@@ -0,0 +1,180 @@
+# Service Layer Pattern
+
+> **Related:** [README](./README.md) | [TanStack Query](./tanstack-query.md) | [Laravel Integration](./laravel-integration.md)
+
+## Types Rule
+
+```typescript
+// ✅ DO: Import Model + Create/Update types from Omnify
+import type { User, UserCreate, UserUpdate } from "@/types/model";
+
+// ✅ DO: Only define query params locally (not generated by Omnify)
+export interface UserListParams {
+  search?: string;
+  page?: number;
+}
+
+// ❌ DON'T: Define types that Omnify already generates
+export interface UserCreateInput { ... }  // WRONG - use UserCreate from Omnify
+export interface User { ... }              // WRONG - use User from Omnify
+```
+
+---
+
+## Service Template
+
+```typescript
+/**
+ * Users Service
+ *
+ * CRUD operations for User resource.
+ * Maps to Laravel UserController.
+ */
+
+import api, { PaginatedResponse } from "@/lib/api";
+import type { User, UserCreate, UserUpdate } from "@/types/model";
+
+// =============================================================================
+// Types - Only query params (Create/Update come from Omnify)
+// =============================================================================
+
+/** Query params for listing users */
+export interface UserListParams {
+  search?: string;
+  page?: number;
+  per_page?: number;
+  sort_by?: keyof User;
+  sort_order?: "asc" | "desc";
+}
+
+// =============================================================================
+// Service
+// =============================================================================
+
+const BASE_URL = "/api/users";
+
+export const userService = {
+  /**
+   * Get paginated list of users
+   * GET /api/users
+   */
+  list: async (params?: UserListParams): Promise<PaginatedResponse<User>> => {
+    const { data } = await api.get(BASE_URL, { params });
+    return data;
+  },
+
+  /**
+   * Get single user by ID
+   * GET /api/users/:id
+   */
+  get: async (id: number): Promise<User> => {
+    const { data } = await api.get(`${BASE_URL}/${id}`);
+    return data.data ?? data;
+  },
+
+  /**
+   * Create new user
+   * POST /api/users
+   */
+  create: async (input: UserCreate): Promise<User> => {
+    const { data } = await api.post(BASE_URL, input);
+    return data.data ?? data;
+  },
+
+  /**
+   * Update existing user
+   * PUT /api/users/:id
+   */
+  update: async (id: number, input: UserUpdate): Promise<User> => {
+    const { data } = await api.put(`${BASE_URL}/${id}`, input);
+    return data.data ?? data;
+  },
+
+  /**
+   * Delete user
+   * DELETE /api/users/:id
+   */
+  delete: async (id: number): Promise<void> => {
+    await api.delete(`${BASE_URL}/${id}`);
+  },
+};
+```
+
+---
+
+## Service Rules
+
+```typescript
+// ✅ DO: Import all types from Omnify
+import type { User, UserCreate, UserUpdate } from "@/types/model";
+
+// ❌ DON'T: Define types that Omnify generates
+export interface UserCreate { ... }  // WRONG!
+export interface User { ... }        // WRONG!
+
+// ✅ DO: Only define query params locally
+export interface UserListParams { ... }  // OK - not in Omnify
+
+// ✅ DO: Keep services pure (no React hooks)
+export const userService = {
+  get: (id) => api.get(`/api/users/${id}`).then(r => r.data.data ?? r.data),
+};
+
+// ❌ DON'T: Use React hooks in services
+export const userService = {
+  get: (id) => {
+    const [data, setData] = useState(); // WRONG!
+  },
+};
+
+// ✅ DO: Handle Laravel's { data: ... } wrapper
+get: (id) => api.get(`/api/users/${id}`).then(r => r.data.data ?? r.data),
+
+// ❌ DON'T: Return raw axios response
+get: (id) => api.get(`/api/users/${id}`), // Returns AxiosResponse, not data
+```
+
+---
+
+## Using Validation Rules
+
+```typescript
+import { Form, Input } from "antd";
+import { useLocale } from "next-intl";
+import { userSchemas, getUserFieldLabel } from "@/types/model/User";
+import { zodRule } from "@/lib/form-validation";
+
+function UserForm() {
+  const locale = useLocale();
+  const label = (key: string) => getUserFieldLabel(key, locale);
+
+  return (
+    <Form>
+      {/* Name */}
+      <Form.Item 
+        name="name" 
+        label={label("name")}
+        rules={[zodRule(userSchemas.name, label("name"))]}
+      >
+        <Input />
+      </Form.Item>
+    </Form>
+  );
+}
+```
+
+---
+
+## Types Summary
+
+| Type     | Source                       | Example                                    |
+| -------- | ---------------------------- | ------------------------------------------ |
+| Model    | `@/types/model` (Omnify)     | `User`                                     |
+| Create   | `@/types/model` (Omnify)     | `UserCreate`                               |
+| Update   | `@/types/model` (Omnify)     | `UserUpdate`                               |
+| Schemas  | `@/types/model` (Omnify)     | `userSchemas.email`                        |
+| Params   | Service file (manual)        | `UserListParams`                           |
+| Response | `@/lib/api.ts`               | `PaginatedResponse<T>`                     |
+| Rules    | `@/lib/form-validation`      | `zodRule(schema, label)`                   |
+
+See [Types Guide](./types-guide.md) for complete details.