@famgia/omnify-ai-guides 2.0.15

package/dist/knowledge/react/types-guide.md

@@ -0,0 +1,669 @@
+# TypeScript Types Guide
+
+> This guide defines where and how to define types in this project.
+
+## Type Categories
+
+| Category            | Location          | Generated | Example                                 |
+| ------------------- | ----------------- | --------- | --------------------------------------- |
+| **Model**           | `@omnify/schemas` | ✅ Omnify  | `User`, `Post`                          |
+| **Create/Update**   | `@omnify/schemas` | ✅ Omnify  | `UserCreate`, `UserUpdate`              |
+| **Common**          | `@omnify/schemas` | ✅ Omnify  | `DateTimeString`, `LocaleMap`           |
+| **Zod Schemas**     | `@omnify/schemas` | ✅ Omnify  | `userSchemas`, `userCreateSchema`       |
+| **i18n**            | `@omnify/schemas` | ✅ Omnify  | `getUserLabel()`, `getUserFieldLabel()` |
+| **Enum**            | `@omnify/enum`    | ✅ Omnify  | `PostStatus`, `MediaType`               |
+| **API Params**      | Service file      | ❌ Manual  | `UserListParams`                        |
+| **API Response**    | `@/lib/api.ts`    | ❌ Manual  | `PaginatedResponse<T>`                  |
+| **Component Props** | Component file    | ❌ Manual  | `UserTableProps`                        |
+
+---
+
+## 1. Model Types (Omnify)
+
+**Location**: `{{TYPESCRIPT_BASE}}/omnify/schemas/`
+
+**Source**: Auto-generated from Omnify schema YAML files
+
+```typescript
+// ✅ Import from @omnify/schemas
+import type { User, UserCreate, UserUpdate } from "@omnify/schemas";
+import type { DateTimeString, LocaleMap } from "@omnify/schemas";
+import { userSchemas, userCreateSchema, userUpdateSchema } from "@omnify/schemas";
+import { getUserLabel, getUserFieldLabel, getUserFieldPlaceholder } from "@omnify/schemas";
+
+// ❌ DON'T define model types manually
+interface User { ... }  // WRONG - already generated
+```
+
+### Structure
+
+```
+{{TYPESCRIPT_BASE}}/omnify/
+├── schemas/                  # Model types and schemas
+│   ├── index.ts             ❌ DO NOT EDIT (re-exports)
+│   ├── i18n.ts              ❌ DO NOT EDIT (i18n config)
+│   └── User.ts              ✅ CAN EDIT (extension file)
+└── enum/                     # Enum types
+    └── PostStatus.ts        ❌ DO NOT EDIT
+```
+
+**Note**: Base types come from `@omnify-base/schemas/` (in node_modules), enums from `@omnify-base/enum/`
+
+### Generated Types Per Model
+
+```typescript
+// Auto-generated in base/User.ts:
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  created_at?: DateTimeString;  // Uses DateTimeString
+  updated_at?: DateTimeString;
+}
+
+type UserCreate = Omit<User, 'id' | 'created_at' | 'updated_at'>;
+type UserUpdate = Partial<UserCreate>;
+```
+
+### Extending Model Types
+
+```typescript
+// src/types/model/User.ts (safe to edit)
+import type { User as UserBase } from "./base/User";
+
+export interface User extends UserBase {
+  // Frontend-only computed properties
+  fullName?: string;
+  
+  // UI state
+  isSelected?: boolean;
+}
+```
+
+---
+
+## 2. Enum Types (CRITICAL)
+
+**Location**: `@omnify/enum/` or re-exported from `@omnify/schemas`
+
+**ALWAYS use generated Enums - NEVER inline union types!**
+
+### Generated Enum Structure
+
+```typescript
+// @omnify/enum/PostStatus.ts (auto-generated)
+
+// 1. Enum type
+export enum PostStatus {
+  Draft = "draft",
+  Published = "published",
+  Archived = "archived",
+}
+
+// 2. Values array (for iteration)
+export const PostStatusValues = [
+  PostStatus.Draft,
+  PostStatus.Published,
+  PostStatus.Archived,
+] as const;
+
+// 3. Type guard
+export function isPostStatus(value: unknown): value is PostStatus {
+  return PostStatusValues.includes(value as PostStatus);
+}
+
+// 4. i18n label getter
+export function getPostStatusLabel(value: PostStatus, locale: string): string {
+  // Returns localized label
+}
+```
+
+### ❌ FORBIDDEN Patterns
+
+```typescript
+// ❌ Complex type extraction - FORBIDDEN!
+const status = value as NonNullable<ListParams["filter"]>["status"];
+
+// ❌ Hardcoded union type - NOT DRY!
+const status: "draft" | "published" | "archived" = "draft";
+
+// ❌ String type - NO TYPE SAFETY!
+const [status, setStatus] = useState<string>("");
+
+// ❌ Hardcoded string comparisons
+if (status === "draft") { ... }
+```
+
+### ✅ REQUIRED Patterns
+
+```typescript
+// ✅ Import from generated enum file
+import { 
+  PostStatus, 
+  PostStatusValues,
+  isPostStatus,
+  getPostStatusLabel 
+} from "@omnify/enum/PostStatus";
+
+// ✅ Type assertions
+const status = unknownValue as PostStatus;
+
+// ✅ State with Enum
+const [status, setStatus] = useState<PostStatus | "">(""); 
+const [status, setStatus] = useState<PostStatus>(PostStatus.Pending);
+
+// ✅ Enum comparisons
+if (status === PostStatus.Pending) { ... }
+
+// ✅ Iterate with Values array
+const options = PostStatusValues.map(value => ({
+  value,
+  label: getPostStatusLabel(value, locale)
+}));
+
+// ✅ Type guard
+if (isPostStatus(value)) {
+  // value is PostStatus
+}
+```
+
+### Select/Filter Options Pattern
+
+```typescript
+import { 
+  PostStatus, 
+  PostStatusValues, 
+  getPostStatusLabel 
+} from "@omnify/enum/PostStatus";
+import { useLocale } from "next-intl";
+
+function StatusFilter() {
+  const locale = useLocale();
+  
+  // ✅ Build options from generated enum
+  const statusOptions = PostStatusValues.map(value => ({
+    value,
+    label: getPostStatusLabel(value, locale)
+  }));
+  
+  // ✅ State with Enum type
+  const [status, setStatus] = useState<PostStatus | "all">("all");
+
+  return (
+    <Select
+      value={status}
+      onChange={setStatus}
+      options={[
+        { value: "all", label: t("common.all") },
+        ...statusOptions
+      ]}
+    />
+  );
+}
+```
+
+### Filter Params with Enum
+
+```typescript
+import { PostStatus } from "@omnify/enum/PostStatus";
+
+interface AttendanceListParams {
+  filter?: {
+    approval_status?: PostStatus;  // ✅ Use Enum type
+  };
+}
+
+// ✅ Type assertion with Enum
+const handleStatusChange = (value: string) => {
+  setFilters(prev => ({
+    ...prev,
+    filter: {
+      ...prev.filter,
+      approval_status: value as PostStatus  // ✅ Not inline union type!
+    }
+  }));
+};
+```
+
+---
+
+## 3. Using Generated Types
+
+### Create/Update Types
+
+```typescript
+// ✅ Use Omnify-generated types
+import type { User, UserCreate, UserUpdate } from "@omnify/schemas";
+
+const userService = {
+  create: (input: UserCreate) => api.post("/api/users", input),
+  update: (id: number, input: UserUpdate) => api.put(`/api/users/${id}`, input),
+};
+```
+
+### Validation Rules with Ant Design Form.Item
+
+```typescript
+import { userSchemas, getUserFieldLabel } from "@omnify/schemas/User";
+import { zodRule } from "@/lib/form-validation";
+import { useLocale } from "next-intl";
+
+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>
+      
+      {/* Email */}
+      <Form.Item 
+        name="email" 
+        label={label("email")}
+        rules={[zodRule(userSchemas.email, label("email"))]}
+      >
+        <Input />
+      </Form.Item>
+    </Form>
+  );
+}
+```
+
+**Key Points:**
+- Import `{model}Schemas` for Zod validation schemas
+- Import `zodRule` from `@/lib/form-validation`
+- Use `zodRule(schema, displayName)` in Form.Item rules
+- Comment `{/* Field Name */}` before each Form.Item for clarity
+
+### DateTimeString
+
+```typescript
+import type { DateTimeString } from "@omnify/schemas";
+import { formatDateTime } from "@/lib/dayjs";
+
+interface Event {
+  scheduled_at: DateTimeString;  // ISO 8601 UTC string
+}
+
+// Display
+formatDateTime(event.scheduled_at);  // "2024/01/15 19:30"
+```
+
+---
+
+## 3. API Params Types (Manual)
+
+**Location**: Service file (colocated)
+
+**Only define query params (not in Omnify):**
+
+```typescript
+// services/users.ts
+import type { User, UserCreate, UserUpdate } from "@omnify/schemas";
+
+/** Query params for listing users (GET /api/users) */
+export interface UserListParams {
+  search?: string;
+  role?: string;
+  page?: number;
+  per_page?: number;
+  sort_by?: keyof User;
+  sort_order?: "asc" | "desc";
+}
+
+export const userService = {
+  list: (params?: UserListParams) => ...,
+  create: (input: UserCreate) => ...,      // ← Use Omnify type
+  update: (id: number, input: UserUpdate) => ...,  // ← Use Omnify type
+};
+```
+
+---
+
+## 4. API Response Types
+
+**Location**: `src/lib/api.ts`
+
+**Naming**: `{Name}Response`, `Paginated{Name}`
+
+```typescript
+// lib/api.ts
+
+/** Laravel paginated response */
+export 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 single resource response */
+export interface ResourceResponse<T> {
+  data: T;
+}
+
+/** Laravel validation error (422) */
+export interface ValidationError {
+  message: string;
+  errors: Record<string, string[]>;
+}
+```
+
+### Usage in Service
+
+```typescript
+import api, { PaginatedResponse } from "@/lib/api";
+import type { User } from "@omnify/schemas";
+
+export const userService = {
+  list: async (params?: UserListParams): Promise<PaginatedResponse<User>> => {
+    const { data } = await api.get("/api/users", { params });
+    return data;
+  },
+};
+```
+
+---
+
+## 4. Component Props Types
+
+**Location**: Same file as component (inline)
+
+**Naming**: `{Component}Props`
+
+```typescript
+// components/tables/UserTable.tsx
+
+import type { User } from "@omnify/schemas";
+import type { PaginatedResponse } from "@/lib/api";
+
+// ─────────────────────────────────────────────────────────────────
+// Props - Define at top of file
+// ─────────────────────────────────────────────────────────────────
+
+interface UserTableProps {
+  users: User[];
+  loading?: boolean;
+  pagination?: PaginatedResponse<User>["meta"];
+  onPageChange?: (page: number) => void;
+  onEdit?: (user: User) => void;
+  onDelete?: (user: User) => void;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Component
+// ─────────────────────────────────────────────────────────────────
+
+export function UserTable({
+  users,
+  loading = false,
+  pagination,
+  onPageChange,
+  onEdit,
+  onDelete,
+}: UserTableProps) {
+  return <Table ... />;
+}
+```
+
+### When to Export Props
+
+```typescript
+// ✅ Export if other components need it
+export interface UserTableProps { ... }
+
+// ✅ Don't export if only used internally
+interface UserTableProps { ... }
+```
+
+---
+
+## 5. Hook Types
+
+**Location**: Hook file (inline or inferred)
+
+**Approach**: Let TypeScript infer return types when possible
+
+```typescript
+// hooks/useUsers.ts
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { userService, UserCreateInput } from "@/services/users";
+import { queryKeys } from "@/lib/queryKeys";
+
+export function useUsers(params?: UserListParams) {
+  // Return type is inferred from userService.list
+  return useQuery({
+    queryKey: queryKeys.users.list(params),
+    queryFn: () => userService.list(params),
+  });
+}
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+  
+  // Return type is inferred from useMutation
+  return useMutation({
+    mutationFn: (input: UserCreateInput) => userService.create(input),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+    },
+  });
+}
+```
+
+### When to Define Return Type
+
+```typescript
+// ✅ Let TypeScript infer (simpler, less maintenance)
+export function useUsers(params?: UserListParams) {
+  return useQuery({ ... });
+}
+
+// ✅ Define explicitly if complex or for documentation
+export function useAuth(): {
+  user: User | undefined;
+  isLoading: boolean;
+  login: (input: LoginInput) => Promise<void>;
+  logout: () => Promise<void>;
+} {
+  ...
+}
+```
+
+---
+
+## 6. Shared/Utility Types
+
+**Location**: `src/types/index.ts` (only if used across many files)
+
+```typescript
+// types/index.ts
+
+/** Common ID type */
+export type ID = number;
+
+/** Nullable type helper */
+export type Nullable<T> = T | null;
+
+/** Make specific keys optional */
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/** Extract array element type */
+export type ArrayElement<T> = T extends (infer U)[] ? U : never;
+```
+
+### When to Use Shared Types
+
+```typescript
+// ✅ Use shared types for truly common patterns
+import type { ID, Nullable } from "@/types";
+
+interface Post {
+  id: ID;
+  author_id: ID;
+  published_at: Nullable<string>;
+}
+
+// ❌ Don't over-abstract
+// Bad: Creating shared types for every little thing
+export type UserName = string;  // Just use string
+export type UserId = number;    // Just use number
+```
+
+---
+
+## Type Definition Checklist
+
+### Before Creating a Type
+
+1. **Is it a Model?** → Use `@omnify/schemas` (Omnify)
+2. **Is it API input?** → Define in service file
+3. **Is it API response?** → Use/extend types in `lib/api.ts`
+4. **Is it component props?** → Define in component file
+5. **Is it used in 3+ places?** → Consider `types/index.ts`
+
+### Type Naming Conventions
+
+| Type         | Pattern              | Example             |
+| ------------ | -------------------- | ------------------- |
+| Model        | PascalCase           | `User`, `Post`      |
+| Create Input | `{Model}CreateInput` | `UserCreateInput`   |
+| Update Input | `{Model}UpdateInput` | `UserUpdateInput`   |
+| List Params  | `{Model}ListParams`  | `UserListParams`    |
+| Props        | `{Component}Props`   | `UserTableProps`    |
+| Response     | `{Name}Response`     | `PaginatedResponse` |
+
+---
+
+## Complete Example
+
+```typescript
+// ═══════════════════════════════════════════════════════════════════
+// types/model/User.ts (Omnify extension)
+// ═══════════════════════════════════════════════════════════════════
+import type { User as UserBase } from "./base/User";
+
+export interface User extends UserBase {
+  // Add frontend-only properties if needed
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// services/users.ts
+// ═══════════════════════════════════════════════════════════════════
+import api, { PaginatedResponse } from "@/lib/api";
+import type { User } from "@omnify/schemas";
+
+export interface UserCreateInput {
+  name: string;
+  email: string;
+  password: string;
+}
+
+export interface UserUpdateInput {
+  name?: string;
+  email?: string;
+}
+
+export interface UserListParams {
+  search?: string;
+  page?: number;
+}
+
+export const userService = {
+  list: async (params?: UserListParams): Promise<PaginatedResponse<User>> => {
+    const { data } = await api.get("/api/users", { params });
+    return data;
+  },
+  get: async (id: number): Promise<User> => {
+    const { data } = await api.get(`/api/users/${id}`);
+    return data.data ?? data;
+  },
+  create: async (input: UserCreateInput): Promise<User> => {
+    const { data } = await api.post("/api/users", input);
+    return data.data ?? data;
+  },
+  update: async (id: number, input: UserUpdateInput): Promise<User> => {
+    const { data } = await api.put(`/api/users/${id}`, input);
+    return data.data ?? data;
+  },
+  delete: async (id: number): Promise<void> => {
+    await api.delete(`/api/users/${id}`);
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════
+// components/tables/UserTable.tsx
+// ═══════════════════════════════════════════════════════════════════
+import type { User } from "@omnify/schemas";
+
+interface UserTableProps {
+  users: User[];
+  loading?: boolean;
+  onEdit?: (user: User) => void;
+}
+
+export function UserTable({ users, loading, onEdit }: UserTableProps) {
+  return <Table dataSource={users} loading={loading} ... />;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// app/(dashboard)/users/page.tsx
+// ═══════════════════════════════════════════════════════════════════
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { userService, UserListParams } from "@/services/users";
+import { UserTable } from "@/components/tables/UserTable";
+import { queryKeys } from "@/lib/queryKeys";
+
+export default function UsersPage() {
+  const [params, setParams] = useState<UserListParams>({ page: 1 });
+  
+  const { data, isLoading } = useQuery({
+    queryKey: queryKeys.users.list(params),
+    queryFn: () => userService.list(params),
+  });
+
+  return (
+    <UserTable
+      users={data?.data ?? []}
+      loading={isLoading}
+      onEdit={(user) => router.push(`/users/${user.id}/edit`)}
+    />
+  );
+}
+```
+
+---
+
+## Summary
+
+| Type     | Location             | Why                       |
+| -------- | -------------------- | ------------------------- |
+| Model    | `@omnify/schemas`    | Synced with DB via Omnify |
+| Input    | Service file         | Colocated with API logic  |
+| Response | `lib/api.ts`         | Shared Laravel patterns   |
+| Props    | Component file       | Colocated with component  |
+| Hook     | Hook file (inferred) | TypeScript handles it     |
+| Utility  | `types/index.ts`     | Only if widely used       |
+
+**Philosophy**: Keep types close to their usage. Don't over-organize.