@famgia/omnify-typescript 0.0.66 → 0.0.68

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

@@ -0,0 +1,221 @@
+# Frontend Architecture Guide
+
+> **Related docs:**
+> - [Design Philosophy](./design-philosophy.md) ⭐ **Start here** - Architecture, principles
+> - [Types Guide](./types-guide.md) - Where to define types
+> - [Service Pattern](./service-pattern.md) - API services
+> - [TanStack Query](./tanstack-query.md) - Data fetching
+> - [Ant Design](./antd-guide.md) - UI components
+> - [i18n](./i18n-guide.md) - Multi-language
+> - [DateTime](./datetime-guide.md) - Day.js, UTC handling
+> - [Laravel Integration](./laravel-integration.md) - Backend integration
+> - [Checklists](./checklist.md) - Before commit, new resource
+
+## Overview
+
+See [Design Philosophy](./design-philosophy.md) for architecture diagram and principles.
+
+**Stack**: Next.js 16 + TypeScript + Ant Design 6 + TanStack Query + Axios
+
+---
+
+## Directory Structure
+
+```
+frontend/src/
+├── app/                        # Next.js App Router (Pages)
+│   ├── layout.tsx              # Root: Providers wrapper
+│   ├── page.tsx                # Public: Home page
+│   │
+│   ├── (auth)/                 # Group: Auth pages (no layout)
+│   │   ├── login/page.tsx
+│   │   └── register/page.tsx
+│   │
+│   └── (dashboard)/            # Group: Protected pages
+│       ├── layout.tsx          # Shared: Sidebar + Header
+│       ├── page.tsx            # /dashboard
+│       └── users/              # Resource: Users
+│           ├── page.tsx        # GET    /users      (List)
+│           ├── new/page.tsx    # POST   /users      (Create)
+│           └── [id]/
+│               ├── page.tsx    # GET    /users/:id  (Show)
+│               └── edit/page.tsx # PUT  /users/:id  (Edit)
+│
+├── features/                   # Feature-specific components & hooks
+│   ├── users/                  # User feature
+│   │   ├── UserTable.tsx       # Only used in users feature
+│   │   ├── UserForm.tsx
+│   │   └── useUserFilters.ts   # Feature-specific hook
+│   └── posts/
+│       ├── PostCard.tsx
+│       └── PostEditor.tsx
+│
+├── components/                 # SHARED components (2+ features)
+│   ├── layouts/                # Layout wrappers
+│   │   ├── DashboardLayout.tsx
+│   │   └── AuthLayout.tsx
+│   └── common/                 # Reusable UI
+│       ├── DataTable.tsx       # Generic table
+│       └── PageHeader.tsx
+│
+├── services/                   # API Service Layer (ALWAYS here)
+│   ├── auth.ts                 # POST /login, /logout, /register
+│   └── users.ts                # CRUD /api/users
+│
+├── hooks/                      # SHARED hooks (2+ features)
+│   ├── useAuth.ts              # App-wide auth
+│   └── useDebounce.ts          # Utility hook
+│
+├── lib/                        # Core Infrastructure
+│   ├── api.ts                  # Axios instance + interceptors
+│   ├── query.tsx               # QueryClient provider
+│   ├── queryKeys.ts            # Query key factory
+│   └── dayjs.ts                # Day.js config + utilities
+│
+├── i18n/                       # Internationalization
+│   ├── config.ts               # Locales config
+│   ├── request.ts              # Server-side locale detection
+│   └── messages/               # Translation files
+│       ├── ja.json
+│       ├── en.json
+│       └── vi.json
+│
+└── types/                      # TypeScript Types
+    └── model/                  # Omnify auto-generated types
+```
+
+---
+
+## When to Use Which Folder
+
+### Decision Rules
+
+| Question                             | Answer      | Location              |
+| ------------------------------------ | ----------- | --------------------- |
+| Component used in how many features? | 1 feature   | `features/{feature}/` |
+| Component used in how many features? | 2+ features | `components/common/`  |
+| Is it a layout wrapper?              | Yes         | `components/layouts/` |
+| Is it a service (API calls)?         | Yes         | `services/` (ALWAYS)  |
+| Hook used in how many features?      | 1 feature   | `features/{feature}/` |
+| Hook used in how many features?      | 2+ features | `hooks/`              |
+
+### Flowchart
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   NEW COMPONENT                         │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+          Used in how many features?
+                      │
+        ┌─────────────┴─────────────┐
+        │                           │
+    1 feature                   2+ features
+        │                           │
+        ▼                           ▼
+features/{feature}/         components/common/
+   UserTable.tsx               DataTable.tsx
+```
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     NEW HOOK                            │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+          Used in how many features?
+                      │
+        ┌─────────────┴─────────────┐
+        │                           │
+    1 feature                   2+ features
+        │                           │
+        ▼                           ▼
+features/{feature}/              hooks/
+  useUserFilters.ts           useDebounce.ts
+```
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    NEW SERVICE                          │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+                  ALWAYS
+                      │
+                      ▼
+                 services/
+                 users.ts
+```
+
+### Examples
+
+```typescript
+// ❌ WRONG: Service in features folder
+features/users/services/users.ts
+
+// ✅ CORRECT: Service always centralized
+services/users.ts
+```
+
+```typescript
+// ❌ WRONG: Feature-specific component in components/
+components/users/UserTable.tsx  // Only used in users feature
+
+// ✅ CORRECT: Feature-specific in features/
+features/users/UserTable.tsx
+```
+
+```typescript
+// ❌ WRONG: Shared component in features/
+features/users/DataTable.tsx  // Used in users AND posts
+
+// ✅ CORRECT: Shared in components/
+components/common/DataTable.tsx
+```
+
+---
+
+## Naming Conventions
+
+### Files
+
+| Type      | Pattern                  | Example                         |
+| --------- | ------------------------ | ------------------------------- |
+| Component | PascalCase               | `UserForm.tsx`, `DataTable.tsx` |
+| Hook      | camelCase + `use` prefix | `useAuth.ts`, `useUsers.ts`     |
+| Service   | camelCase                | `users.ts`, `auth.ts`           |
+| Utility   | camelCase                | `utils.ts`, `formatters.ts`     |
+| Type      | camelCase or PascalCase  | `types.ts`, `User.ts`           |
+| Page      | lowercase                | `page.tsx`, `layout.tsx`        |
+
+### Code
+
+| Type           | Pattern               | Example                     |
+| -------------- | --------------------- | --------------------------- |
+| Component      | PascalCase            | `function UserForm()`       |
+| Hook           | camelCase + `use`     | `function useAuth()`        |
+| Service object | camelCase + `Service` | `const userService = {}`    |
+| Interface      | PascalCase            | `interface User`            |
+| Type           | PascalCase            | `type UserFormData`         |
+| Constant       | UPPER_SNAKE_CASE      | `const API_TIMEOUT = 30000` |
+| Function       | camelCase             | `function formatDate()`     |
+| Variable       | camelCase             | `const userData = ...`      |
+
+---
+
+## Types
+
+See [Types Guide](./types-guide.md) for complete type definition rules.
+
+**Quick reference:**
+
+| Type               | Location                                |
+| ------------------ | --------------------------------------- |
+| Model (User, Post) | `@/types/model` (Omnify auto-generated) |
+| Input types        | Service file (colocated)                |
+| Props              | Component file                          |
+| API Response       | `lib/api.ts`                            |
+
+**Omnify files:**
+- `base/`, `rules/`, `enum/` → ❌ DO NOT EDIT
+- `User.ts` (root level) → ✅ CAN EDIT (extension)
+
+See also: [Omnify TypeScript Guide](../omnify/typescript-guide.md)

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

@@ -0,0 +1,294 @@
+# Ant Design Guide
+
+> **Related:** [README](./README.md) | [i18n](./i18n-guide.md)
+
+## ⚠️ IMPORTANT: Use Ant Design First
+
+**ALWAYS check if Ant Design has a component before creating your own.**
+
+Ant Design provides 60+ components: https://ant.design/components/overview
+
+```typescript
+// ✅ DO: Use Ant Design components
+import { Table, Form, Input, Button, Modal, Card, Descriptions } from "antd";
+
+// ❌ DON'T: Create custom components that Ant Design already has
+// DON'T create: CustomTable, CustomModal, CustomForm, CustomButton
+// DON'T create: DataGrid, Popup, FormInput
+
+// ✅ DO: Extend Ant Design if needed
+function UserTable(props: { users: User[] }) {
+  return <Table dataSource={props.users} columns={...} />; // Wraps AntD Table
+}
+
+// ❌ DON'T: Build from scratch
+function UserTable(props: { users: User[] }) {
+  return <table><tbody>{users.map(...)}</tbody></table>; // WRONG!
+}
+```
+
+---
+
+## ⚠️ No New Libraries Without Permission
+
+**DO NOT install new npm packages without explicit user approval.**
+
+```bash
+# ❌ DON'T: Install without asking
+npm install lodash
+npm install moment
+npm install react-table
+
+# ✅ DO: Ask first
+"Do you want to install library X for Y?"
+```
+
+**Already installed libraries (use these):**
+- UI: `antd`, `@ant-design/icons`
+- HTTP: `axios`
+- State: `@tanstack/react-query`
+- Styling: `tailwindcss`
+- i18n: `next-intl`
+
+---
+
+## When to Create a Component
+
+| Create Component                | Don't Create                  |
+| ------------------------------- | ----------------------------- |
+| Used in 2+ places               | Used only once                |
+| Has own state/logic (>50 lines) | Simple markup (<30 lines)     |
+| Needs unit testing              | Trivial display               |
+| Complex props interface         | Few inline props              |
+| **Ant Design doesn't have it**  | **Ant Design already has it** |
+
+---
+
+## Container vs Presentational
+
+```typescript
+// ============================================================================
+// CONTAINER COMPONENT (Smart) - pages or complex components
+// - Fetches data
+// - Handles mutations
+// - Contains business logic
+// ============================================================================
+
+// app/(dashboard)/users/page.tsx
+"use client";
+
+import { useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { userService, UserListParams } from "@/services/users";
+import { queryKeys } from "@/lib/queryKeys";
+import { UserTable } from "@/components/tables/UserTable";
+
+export default function UsersPage() {
+  const [filters, setFilters] = useState<UserListParams>({ page: 1 });
+  
+  const { data, isLoading } = useQuery({
+    queryKey: queryKeys.users.list(filters),
+    queryFn: () => userService.list(filters),
+  });
+
+  return (
+    <UserTable 
+      users={data?.data ?? []}
+      loading={isLoading}
+      pagination={data?.meta}
+      onPageChange={(page) => setFilters({ ...filters, page })}
+    />
+  );
+}
+
+// ============================================================================
+// PRESENTATIONAL COMPONENT (Dumb) - reusable UI
+// - Receives data via props
+// - No data fetching
+// - No business logic
+// ============================================================================
+
+// components/tables/UserTable.tsx
+import { Table } from "antd";
+import type { User } from "@/types/model";
+import type { PaginatedResponse } from "@/lib/api";
+
+interface UserTableProps {
+  users: User[];
+  loading: boolean;
+  pagination?: PaginatedResponse<User>["meta"];
+  onPageChange: (page: number) => void;
+}
+
+export function UserTable({ users, loading, pagination, onPageChange }: UserTableProps) {
+  return (
+    <Table
+      dataSource={users}
+      loading={loading}
+      rowKey="id"
+      pagination={{
+        current: pagination?.current_page,
+        total: pagination?.total,
+        onChange: onPageChange,
+      }}
+      columns={[
+        { title: "ID", dataIndex: "id" },
+        { title: "Name", dataIndex: "name" },
+        { title: "Email", dataIndex: "email" },
+      ]}
+    />
+  );
+}
+```
+
+---
+
+## Form Pattern with Laravel Validation
+
+```typescript
+"use client";
+
+import { Form, Input, Button, message } from "antd";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useTranslations } from "next-intl";
+import { getFormErrors } from "@/lib/api";
+import { queryKeys } from "@/lib/queryKeys";
+import { userService } from "@/services/users";
+
+export default function UserForm() {
+  const t = useTranslations();
+  const [form] = Form.useForm();
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: userService.create,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+      message.success(t("messages.created"));
+      form.resetFields();
+    },
+    onError: (error) => {
+      // This maps Laravel's 422 { errors: { email: ["Already exists"] } }
+      // to Ant Design's form.setFields format
+      form.setFields(getFormErrors(error));
+    },
+  });
+
+  return (
+    <Form
+      form={form}
+      layout="vertical"
+      onFinish={(values) => mutation.mutate(values)}
+    >
+      <Form.Item
+        name="name"
+        label={t("common.name")}
+        rules={[{ required: true }]}
+      >
+        <Input />
+      </Form.Item>
+
+      <Form.Item
+        name="email"
+        label={t("auth.email")}
+        rules={[{ required: true }, { type: "email" }]}
+      >
+        <Input />
+      </Form.Item>
+
+      <Form.Item>
+        <Button
+          type="primary"
+          htmlType="submit"
+          loading={mutation.isPending}
+        >
+          {t("common.save")}
+        </Button>
+      </Form.Item>
+    </Form>
+  );
+}
+```
+
+---
+
+## Deprecated Props (v6+)
+
+> ⚠️ **CRITICAL**: Always use the latest prop names. Using deprecated props will show console warnings.
+
+| Component    | Deprecated                 | Use Instead             |
+| ------------ | -------------------------- | ----------------------- |
+| Space        | `direction`                | `orientation`           |
+| Modal        | `visible`                  | `open`                  |
+| Drawer       | `visible`                  | `open`                  |
+| Dropdown     | `visible`                  | `open`                  |
+| Tooltip      | `visible`                  | `open`                  |
+| Popover      | `visible`                  | `open`                  |
+| Popconfirm   | `visible`                  | `open`                  |
+| Select       | `dropdownMatchSelectWidth` | `popupMatchSelectWidth` |
+| TreeSelect   | `dropdownMatchSelectWidth` | `popupMatchSelectWidth` |
+| Cascader     | `dropdownMatchSelectWidth` | `popupMatchSelectWidth` |
+| AutoComplete | `dropdownMatchSelectWidth` | `popupMatchSelectWidth` |
+| Table        | `filterDropdownVisible`    | `filterDropdownOpen`    |
+
+```typescript
+// ❌ DON'T: Use deprecated props
+<Space direction="vertical">
+<Modal visible={isOpen}>
+<Dropdown visible={show}>
+
+// ✅ DO: Use new props
+<Space orientation="vertical">
+<Modal open={isOpen}>
+<Dropdown open={show}>
+```
+
+---
+
+## Anti-Patterns
+
+```typescript
+// ❌ Creating components that Ant Design already has
+function CustomButton({ children }) { ... }  // Use <Button> from antd
+function CustomModal({ visible }) { ... }    // Use <Modal> from antd
+function CustomTable({ data }) { ... }       // Use <Table> from antd
+function DataGrid({ rows }) { ... }          // Use <Table> from antd
+
+// ❌ Installing libraries without permission
+npm install lodash          // Ask first!
+npm install react-icons     // Use @ant-design/icons
+npm install styled-components // Use Tailwind CSS
+
+// ❌ API call in component (bypass service layer)
+function UserList() {
+  const { data } = useQuery({
+    queryKey: ["users"],
+    queryFn: () => axios.get("/api/users"), // WRONG: Use service
+  });
+}
+
+// ❌ Business logic in component
+function UserList() {
+  const users = data?.filter(u => u.active).sort((a, b) => a.name > b.name);
+  // Move to service or utility function
+}
+
+// ❌ Hardcoded strings - use i18n
+<Button>Save</Button>         // WRONG
+<Button>{t("common.save")}</Button>  // CORRECT
+
+// ❌ Multiple sources of truth
+const [users, setUsers] = useState([]); // Local state
+const { data } = useQuery({ ... });     // Server state
+// Pick one: TanStack Query for server data
+
+// ❌ Prop drilling
+<Parent data={data}>
+  <Child data={data}>
+    <GrandChild data={data} /> // Use Context or pass minimal props
+  </Child>
+</Parent>
+
+// ❌ Giant components (>200 lines)
+// Split into smaller components or extract hooks
+```

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