@famgia/omnify-laravel 0.0.118 → 0.0.120

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,457 @@
+# 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>
+  );
+}
+```
+
+---
+
+## ⚠️ Ant Design 6+ Breaking Changes & Deprecated Props
+
+> **CRITICAL**: Always use the latest prop names. Using deprecated props will show console warnings and may break in future versions.
+
+### Deprecated Props Reference Table
+
+| Component    | ❌ Deprecated              | ✅ Use Instead          | Warning Message                                    |
+| ------------ | -------------------------- | ----------------------- | -------------------------------------------------- |
+| **Divider**  | `orientation`              | `titlePlacement`        | `orientation` is used for direction, use `titlePlacement` |
+| 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`    |                                                    |
+| DatePicker   | `dropdownClassName`        | `popupClassName`        |                                                    |
+| TimePicker   | `dropdownClassName`        | `popupClassName`        |                                                    |
+| Mentions     | `dropdownClassName`        | `popupClassName`        |                                                    |
+| Tag          | `closable`                 | `closeIcon={false}`     | Use `closeIcon={false}` to hide close icon         |
+| Notification | `message`                  | `description`           | Some API changes in v6                             |
+
+```typescript
+// ❌ DON'T: Use deprecated props (causes console warnings)
+<Divider orientation="left">Title</Divider>
+<Modal visible={isOpen}>
+<Dropdown visible={show}>
+<Select dropdownMatchSelectWidth={false}>
+
+// ✅ DO: Use new props (Ant Design 6+)
+<Divider titlePlacement="left">Title</Divider>
+<Modal open={isOpen}>
+<Dropdown open={show}>
+<Select popupMatchSelectWidth={false}>
+```
+
+---
+
+## 🚨 Common Ant Design 6+ Mistakes
+
+### 1. Divider - `orientation` vs `titlePlacement`
+
+```typescript
+// ❌ WRONG: This will show a deprecation warning!
+<Divider orientation="left">Section Title</Divider>
+// Warning: [antd: Divider] `orientation` is used for direction, please use `titlePlacement` replace this
+
+// ✅ CORRECT: Use titlePlacement for title position
+<Divider titlePlacement="left">Section Title</Divider>
+<Divider titlePlacement="center">Section Title</Divider>
+<Divider titlePlacement="right">Section Title</Divider>
+
+// For horizontal/vertical dividers, use `type`:
+<Divider type="horizontal" />  // default
+<Divider type="vertical" />
+```
+
+### 2. Modal/Drawer - `visible` vs `open`
+
+```typescript
+// ❌ WRONG
+const [visible, setVisible] = useState(false);
+<Modal visible={visible} onCancel={() => setVisible(false)}>
+
+// ✅ CORRECT
+const [open, setOpen] = useState(false);
+<Modal open={open} onCancel={() => setOpen(false)}>
+```
+
+### 3. Form.Item - `dependencies` must be array
+
+```typescript
+// ❌ WRONG: dependencies as string
+<Form.Item dependencies="password">
+
+// ✅ CORRECT: dependencies as array
+<Form.Item dependencies={['password']}>
+```
+
+### 4. Table - Column `render` function signature
+
+```typescript
+// ❌ WRONG: Using wrong parameter order
+columns={[{
+  render: (record, text) => <span>{text}</span>  // WRONG ORDER!
+}]}
+
+// ✅ CORRECT: (text, record, index)
+columns={[{
+  render: (text, record, index) => <span>{text}</span>
+}]}
+```
+
+### 5. Select/TreeSelect - Option rendering
+
+```typescript
+// ❌ WRONG: Using children in v6+
+<Select>
+  <Select.Option value="1">Option 1</Select.Option>
+</Select>
+
+// ✅ PREFERRED: Use options prop (better performance)
+<Select options={[
+  { value: '1', label: 'Option 1' },
+  { value: '2', label: 'Option 2' },
+]} />
+```
+
+### 6. DatePicker - Dayjs instead of Moment
+
+```typescript
+// ❌ WRONG: Ant Design 6+ uses dayjs, not moment
+import moment from 'moment';
+<DatePicker value={moment(date)} />
+
+// ✅ CORRECT: Use dayjs
+import dayjs from 'dayjs';
+<DatePicker value={dayjs(date)} />
+```
+
+### 7. ConfigProvider - Theme customization
+
+```typescript
+// ❌ WRONG: Old less variable approach
+@primary-color: #1890ff;
+
+// ✅ CORRECT: Use ConfigProvider theme token
+<ConfigProvider
+  theme={{
+    token: {
+      colorPrimary: '#1890ff',
+      borderRadius: 6,
+    },
+  }}
+>
+  <App />
+</ConfigProvider>
+```
+
+### 8. App Component - message/notification/modal
+
+```typescript
+// ❌ WRONG: Direct import (won't respect ConfigProvider)
+import { message } from 'antd';
+message.success('Done!');
+
+// ✅ CORRECT: Use App.useApp() hook
+import { App } from 'antd';
+
+function MyComponent() {
+  const { message, notification, modal } = App.useApp();
+  
+  const handleClick = () => {
+    message.success('Done!');  // Respects ConfigProvider theme
+  };
+}
+
+// Wrap your app with App component
+<ConfigProvider theme={...}>
+  <App>
+    <YourApp />
+  </App>
+</ConfigProvider>
+```
+
+### 9. Icons - Named imports required
+
+```typescript
+// ❌ WRONG: Default import
+import Icon from '@ant-design/icons';
+<Icon type="user" />
+
+// ✅ CORRECT: Named imports
+import { UserOutlined, EditOutlined } from '@ant-design/icons';
+<UserOutlined />
+<EditOutlined />
+```
+
+### 10. Grid - `xs`, `sm`, etc. as objects
+
+```typescript
+// ❌ CAREFUL: Mixing number and object syntax
+<Col xs={24} sm={{ span: 12, offset: 6 }}>
+
+// ✅ PREFERRED: Be consistent
+<Col xs={{ span: 24 }} sm={{ span: 12, offset: 6 }}>
+// OR
+<Col xs={24} sm={12}>
+```
+
+---
+
+## 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
+```