@famgia/omnify-laravel 0.0.119 → 0.0.120

package/stubs/ai-guides/react/checklist.md.stub

@@ -0,0 +1,108 @@
+# Checklists
+
+> **Related:** [README](./README.md)
+
+## After Writing Code
+
+> **IMPORTANT**: Always run these commands after writing/modifying code:
+
+```bash
+# 1. Type check
+npm run typecheck
+
+# 2. Lint check
+npm run lint
+
+# Or combined
+npm run typecheck && npm run lint
+```
+
+---
+
+## Adding New Resource
+
+When adding a new resource (e.g., `posts`), follow these steps:
+
+### 1. Service Layer (Always in `services/`)
+
+```bash
+# Create: services/posts.ts
+```
+
+- [ ] Import types: `import type { Post, PostCreate, PostUpdate } from "@/types/model"`
+- [ ] Define only `PostListParams` (Create/Update come from Omnify)
+- [ ] Create `postService` object with CRUD methods
+- [ ] Add JSDoc comments for each method
+
+### 2. Query Keys
+
+```bash
+# Update: lib/queryKeys.ts
+```
+
+- [ ] Add `posts` object to `queryKeys`
+
+```typescript
+posts: {
+  all: ["posts"] as const,
+  lists: () => [...queryKeys.posts.all, "list"] as const,
+  list: (params?: PostListParams) => [...queryKeys.posts.lists(), params] as const,
+  details: () => [...queryKeys.posts.all, "detail"] as const,
+  detail: (id: number) => [...queryKeys.posts.details(), id] as const,
+},
+```
+
+### 3. Feature Components (in `features/posts/`)
+
+```bash
+# Create: features/posts/
+```
+
+- [ ] `PostTable.tsx` - Table component
+- [ ] `PostForm.tsx` - Form component
+- [ ] `usePostFilters.ts` - Feature-specific hooks (if needed)
+
+### 4. Pages
+
+```bash
+# Create pages in app/(dashboard)/posts/
+```
+
+- [ ] `page.tsx` - List page (imports from `features/posts/`)
+- [ ] `new/page.tsx` - Create form
+- [ ] `[id]/page.tsx` - Detail view
+- [ ] `[id]/edit/page.tsx` - Edit form
+
+### 5. Shared Components (only if reused)
+
+- [ ] If component used in 2+ features → move to `components/common/`
+
+### 6. Translations
+
+- [ ] Add labels to `src/i18n/messages/*.json` if needed
+
+### 7. Final Check
+
+- [ ] Run `npm run typecheck && npm run lint`
+- [ ] Test create, read, update, delete operations
+
+---
+
+## Adding New Language
+
+- [ ] Create message file: `src/i18n/messages/{locale}.json`
+- [ ] Add locale to `src/i18n/config.ts`
+- [ ] Import Ant Design locale in `src/components/AntdThemeProvider.tsx`
+- [ ] Test with `LocaleSwitcher` component
+
+---
+
+## Before Commit
+
+- [ ] `npm run typecheck` passes
+- [ ] `npm run lint` passes
+- [ ] No console warnings about deprecated props
+- [ ] No hardcoded strings (use i18n)
+- [ ] Forms handle loading state (`isPending`)
+- [ ] Forms handle validation errors (`getFormErrors`)
+- [ ] Mutations invalidate related queries

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

@@ -0,0 +1,137 @@
+# DateTime Handling Guide (Frontend)
+
+> **Related:** [README](./README.md) | [Service Pattern](./service-pattern.md) | [Laravel Integration](./laravel-integration.md)
+
+## Golden Rule: "Store UTC, Display Local"
+
+```
+API Response (UTC) → Day.js → Display (Local Timezone)
+User Input (Local) → Day.js → API Request (UTC)
+```
+
+---
+
+## Setup
+
+Day.js is already configured in this project. Import from `@/lib/dayjs`:
+
+```typescript
+import dayjs, { formatDateTime, toUTCString } from "@/lib/dayjs";
+```
+
+> **Rule:** Always import from `@/lib/dayjs`, never from `dayjs` directly.
+
+---
+
+## Usage Patterns
+
+### Display UTC from API
+
+```typescript
+import dayjs, { formatDateTime, formatRelative } from "@/lib/dayjs";
+
+// API returns: "2024-01-15T10:30:00Z" (UTC)
+const createdAt = "2024-01-15T10:30:00Z";
+
+// Using helper functions (recommended)
+formatDateTime(createdAt);        // "2024/01/15 19:30"
+formatRelative(createdAt);        // "3日前"
+
+// Using dayjs directly
+dayjs(createdAt).format("LL");    // "2024年1月15日" (localized)
+```
+
+### Send Local Input as UTC
+
+```typescript
+import dayjs, { toUTCString } from "@/lib/dayjs";
+
+// User selects: 2024/01/15 19:30 (local time)
+const localDate = dayjs("2024-01-15 19:30");
+
+// Convert to UTC for API
+const utcString = toUTCString(localDate);
+// "2024-01-15T10:30:00.000Z"
+```
+
+### With Ant Design DatePicker
+
+```typescript
+import { DatePicker, Form } from "antd";
+import dayjs, { toUTCString, fromUTCString } from "@/lib/dayjs";
+import type { Dayjs } from "@/lib/dayjs";
+
+function MyForm() {
+  const handleSubmit = (values: { date: Dayjs }) => {
+    api.post("/events", { date: toUTCString(values.date) });
+  };
+
+  return (
+    <Form onFinish={handleSubmit}>
+      <Form.Item name="date">
+        <DatePicker showTime />
+      </Form.Item>
+    </Form>
+  );
+}
+
+// Display API date in DatePicker
+<DatePicker defaultValue={fromUTCString(event.scheduled_at)} />
+```
+
+---
+
+## Available Functions
+
+| Function                       | Description           | Example Output               |
+| ------------------------------ | --------------------- | ---------------------------- |
+| `formatDate(utc)`              | Date only             | `"2024/01/15"`               |
+| `formatDateTime(utc)`          | Date + time           | `"2024/01/15 19:30"`         |
+| `formatDateLocalized(utc)`     | Localized date        | `"2024年1月15日"`            |
+| `formatDateTimeLocalized(utc)` | Localized date + time | `"2024年1月15日 19:30"`      |
+| `formatRelative(utc)`          | Relative time         | `"3日前"`                    |
+| `toUTCString(dayjs)`           | Convert to UTC ISO    | `"2024-01-15T10:30:00.000Z"` |
+| `fromUTCString(utc)`           | Parse to Dayjs        | `Dayjs object`               |
+| `nowUTC()`                     | Current UTC time      | `Dayjs object`               |
+| `isPast(utc)`                  | Check if past         | `true/false`                 |
+| `isFuture(utc)`                | Check if future       | `true/false`                 |
+
+---
+
+## Anti-Patterns ❌
+
+```typescript
+// ❌ Import dayjs directly
+import dayjs from "dayjs";
+
+// ❌ Use native Date
+new Date("2024-01-15");
+
+// ❌ Send local date string to API
+api.post({ date: "2024/01/15 19:30" });
+
+// ❌ Use moment.js
+import moment from "moment";
+```
+
+## Correct Patterns ✅
+
+```typescript
+// ✅ Import from lib
+import dayjs, { formatDateTime, toUTCString } from "@/lib/dayjs";
+
+// ✅ Use helper functions
+formatDateTime(user.created_at);
+
+// ✅ Send UTC to API
+api.post({ date: toUTCString(localDate) });
+```
+
+---
+
+## Checklist
+
+- [ ] Import from `@/lib/dayjs`, not `dayjs`
+- [ ] Use helper functions for display
+- [ ] Use `toUTCString()` when sending to API
+- [ ] Use `fromUTCString()` for form default values

package/stubs/ai-guides/react/design-philosophy.md.stub

@@ -0,0 +1,363 @@
+# Design Philosophy
+
+> This document explains the architectural decisions and design principles for this frontend project.
+
+## Architecture: Clean Architecture + Service Layer
+
+```mermaid
+flowchart TD
+    subgraph UI["UI Layer"]
+        Page["Page (Container)"]
+        Component["Component (Presentational)"]
+    end
+
+    subgraph Hooks["Hooks Layer"]
+        Query["TanStack Query"]
+    end
+
+    subgraph Services["Service Layer"]
+        Service["userService, postService"]
+    end
+
+    subgraph Infra["Infrastructure Layer"]
+        Axios["Axios (lib/api.ts)"]
+    end
+
+    Page --> Query
+    Component --> Page
+    Query --> Service
+    Service --> Axios
+    Axios -->|HTTP| API[Laravel API]
+```
+
+| Layer          | Responsibility                    | Rules                    |
+| -------------- | --------------------------------- | ------------------------ |
+| UI             | Display data, handle interactions | No direct API calls      |
+| Hooks          | Server state, caching, sync       | Uses services            |
+| Service        | API communication                 | No React, pure functions |
+| Infrastructure | HTTP client, interceptors         | Framework-agnostic       |
+
+---
+
+## Why This Architecture?
+
+### 1. Separation of Concerns
+
+Each layer has a single responsibility:
+
+| Layer          | Knows About             | Doesn't Know About     |
+| -------------- | ----------------------- | ---------------------- |
+| UI             | Components, hooks       | HTTP, API endpoints    |
+| Hooks          | Services, query keys    | Axios, response format |
+| Services       | API instance, endpoints | React, components      |
+| Infrastructure | HTTP protocol           | Business logic         |
+
+**Benefit**: Change one layer without affecting others.
+
+### 2. Testability
+
+```typescript
+// Services are pure functions - easy to test
+test("userService.get returns user", async () => {
+  const user = await userService.get(1);
+  expect(user.id).toBe(1);
+});
+
+// Components receive data via props - easy to mock
+test("UserTable renders users", () => {
+  render(<UserTable users={mockUsers} loading={false} />);
+  expect(screen.getByText("John")).toBeInTheDocument();
+});
+```
+
+### 3. Reusability
+
+```typescript
+// Services can be used anywhere
+const user = await userService.get(1);  // In a script
+const { data } = useQuery({ queryFn: () => userService.get(1) });  // In React
+```
+
+### 4. Type Safety
+
+Types flow through layers:
+
+```typescript
+// Omnify generates Model types (synced with DB)
+type User = { id: number; name: string; email: string; }
+
+// Services use Model types + define Input types
+const userService = {
+  get: (id: number): Promise<User> => ...,
+  create: (input: UserCreateInput): Promise<User> => ...,
+}
+
+// Hooks inherit types from services
+const { data } = useQuery<User>({ ... });
+
+// Components receive typed props
+function UserCard({ user }: { user: User }) { ... }
+```
+
+---
+
+## Why TanStack Query?
+
+### Problem: Server State is Different
+
+```typescript
+// ❌ Client state (useState) - you control it
+const [count, setCount] = useState(0);
+setCount(1);  // Immediately updates
+
+// ❌ Server state - you DON'T control it
+const [users, setUsers] = useState([]);
+// What if another user adds a new user?
+// What if the network fails?
+// What if the data is stale?
+```
+
+### Solution: TanStack Query
+
+| Feature            | Without TanStack     | With TanStack                    |
+| ------------------ | -------------------- | -------------------------------- |
+| Loading state      | Manual `useState`    | Automatic `isLoading`            |
+| Error handling     | Try/catch everywhere | Automatic `error`                |
+| Caching            | None or manual       | Automatic, configurable          |
+| Refetching         | Manual               | Automatic on focus/reconnect     |
+| Deduplication      | None                 | Automatic (same key = 1 request) |
+| Optimistic updates | Complex              | Built-in                         |
+
+### TanStack Query vs SWR
+
+| Feature            | TanStack Query              | SWR             |
+| ------------------ | --------------------------- | --------------- |
+| Mutations          | ✅ First-class `useMutation` | ⚠️ Manual        |
+| Devtools           | ✅ Excellent                 | ⚠️ Basic         |
+| Query invalidation | ✅ Granular control          | ⚠️ Limited       |
+| Optimistic updates | ✅ Built-in rollback         | ⚠️ Manual        |
+| Bundle size        | ~13KB                       | ~4KB            |
+| Best for           | Complex apps                | Simple fetching |
+
+**We chose TanStack Query** because:
+- Better mutation support (CRUD apps need this)
+- Granular cache invalidation (important for data consistency)
+- Better devtools for debugging
+
+---
+
+## Why Service Layer?
+
+### Problem: API Calls Scattered
+
+```typescript
+// ❌ API calls in components
+function UserList() {
+  const { data } = useQuery({
+    queryFn: () => axios.get("/api/users").then(r => r.data),
+  });
+}
+
+function UserDetail({ id }) {
+  const { data } = useQuery({
+    queryFn: () => axios.get(`/api/users/${id}`).then(r => r.data.data),
+  });
+}
+// Problems:
+// - Duplicated logic (response unwrapping)
+// - Hard to change API (update every component)
+// - Hard to test (need to mock axios in every test)
+```
+
+### Solution: Service Layer
+
+```typescript
+// ✅ Centralized in service
+const userService = {
+  list: () => api.get("/api/users").then(r => r.data),
+  get: (id) => api.get(`/api/users/${id}`).then(r => r.data.data ?? r.data),
+};
+
+// Components just use services
+function UserList() {
+  const { data } = useQuery({ queryFn: userService.list });
+}
+
+function UserDetail({ id }) {
+  const { data } = useQuery({ queryFn: () => userService.get(id) });
+}
+// Benefits:
+// - Single source of truth for API logic
+// - Easy to change (update one file)
+// - Easy to test (mock service, not axios)
+```
+
+---
+
+## Design Principles
+
+### 1. Single Source of Truth
+
+| Data Type                  | Source                         |
+| -------------------------- | ------------------------------ |
+| Server data (users, posts) | TanStack Query                 |
+| Model types                | Omnify (`@/types/model`)       |
+| Form state                 | Ant Design Form                |
+| UI state (modal open)      | Local `useState`               |
+| Global client state        | Context or Zustand (if needed) |
+
+### 2. Colocation
+
+Keep related code together:
+
+```
+// ✅ Good: Related files together
+services/
+  users.ts         # Service + Input types
+  posts.ts
+
+// ❌ Bad: Types scattered
+types/
+  UserCreateInput.ts
+  UserUpdateInput.ts
+  PostCreateInput.ts
+services/
+  users.ts
+  posts.ts
+```
+
+### 3. Explicit Over Implicit
+
+```typescript
+// ✅ Explicit: Clear what this does
+const { data: users, isLoading, error } = useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: () => userService.list(filters),
+});
+
+// ❌ Implicit: Magic happening somewhere
+const users = useUsers(filters);  // What's inside? Caching? Error handling?
+```
+
+### 4. Fail Fast
+
+```typescript
+// ✅ Types catch errors at compile time
+const user: User = { id: "1" };  // Error: id should be number
+
+// ✅ ESLint catches bad patterns
+useEffect(() => { fetchData() }, []);  // Warning: use useQuery
+
+// ✅ Runtime errors shown to user
+onError: (error) => form.setFields(getFormErrors(error));
+```
+
+### 5. Composition Over Inheritance
+
+```typescript
+// ✅ Compose small pieces
+function UserPage() {
+  return (
+    <PageLayout>
+      <UserFilters />
+      <UserTable />
+      <UserPagination />
+    </PageLayout>
+  );
+}
+
+// ❌ Don't create giant "smart" components
+function UserPage() {
+  // 500 lines of mixed concerns
+}
+```
+
+---
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Component as Component (UI)
+    participant Mutation as Mutation (TanStack)
+    participant Service as Service
+    participant Axios as Axios (Infra)
+    participant API as Laravel API
+
+    User->>Component: clicks "Save"
+    Component->>Mutation: mutation.mutate(values)
+    Mutation->>Service: userService.create(values)
+    Service->>Axios: api.post("/api/users", values)
+    Axios->>API: HTTP POST
+    API-->>Axios: Response
+    Axios-->>Service: data
+    Service-->>Mutation: User
+    Mutation->>Mutation: invalidateQueries
+    Mutation-->>Component: onSuccess
+    Component-->>User: UI updates
+```
+
+---
+
+## Coding Style: Centralized Configuration
+
+### Rule: One File Per Concern in `lib/`
+
+```
+lib/
+├── api.ts          # Axios config + interceptors + error handling
+├── query.tsx       # QueryClient config + provider
+├── queryKeys.ts    # All query keys
+└── dayjs.ts        # Day.js config + plugins + utilities
+```
+
+**Why single file?**
+- **Consistency**: One place to find all related code
+- **Maintainability**: Easy to update
+- **Discoverability**: Clear what's available
+- **No over-engineering**: Avoid splitting into multiple files unnecessarily
+
+### Anti-Pattern ❌
+
+```
+// Don't split into multiple files unnecessarily
+lib/
+├── dayjs/
+│   ├── config.ts
+│   ├── plugins.ts
+│   ├── locale.ts
+│   └── utils.ts
+```
+
+### Correct Pattern ✅
+
+```
+// Keep related code in one file
+lib/
+└── dayjs.ts        # Config + plugins + locale + utils (all in one)
+```
+
+### When to Split Files
+
+Only split when:
+1. File exceeds ~300-400 lines
+2. Clear separate concerns (e.g., `api.ts` vs `queryKeys.ts`)
+3. Different import patterns needed
+
+---
+
+## Summary
+
+| Aspect       | Choice              | Reason                              |
+| ------------ | ------------------- | ----------------------------------- |
+| Architecture | Clean Architecture  | Separation of concerns, testability |
+| Server State | TanStack Query      | Caching, mutations, devtools        |
+| HTTP Client  | Axios               | Interceptors, Laravel integration   |
+| UI Library   | Ant Design          | Comprehensive, consistent           |
+| Types        | TypeScript + Omnify | Type safety, DB sync                |
+| Styling      | Tailwind CSS        | Utility-first, fast                 |
+| i18n         | next-intl           | Server components support           |
+| Date/Time    | Day.js              | Ant Design compatible, lightweight  |
+
+**Philosophy**: Keep it simple, explicit, and type-safe. Each layer does one thing well.