@famgia/omnify-typescript 0.0.87 → 0.0.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify-typescript",
-  "version": "0.0.87",
+  "version": "0.0.89",
   "description": "TypeScript type definitions generator for Omnify schemas",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -48,7 +48,7 @@
     "directory": "packages/typescript-generator"
   },
   "dependencies": {
-    "@famgia/omnify-types": "0.0.97"
+    "@famgia/omnify-types": "0.0.99"
   },
   "peerDependencies": {
     "zod": "^3.0.0"

package/stubs/ai-guides/cursor/react.mdc.stub

@@ -70,6 +70,87 @@ export interface UserListParams { ... }
 export interface UserCreateInput { ... }  // WRONG
 ```
 
+## ⚠️ Enum Usage Rules (CRITICAL)
+
+**ALWAYS use generated Enums** - NEVER inline union types or type extractions!
+
+### ❌ BAD Patterns (FORBIDDEN)
+
+```typescript
+// ❌ Complex type extraction - FORBIDDEN!
+newFilter.approval_status = status as NonNullable<ListParams["filter"]>["approval_status"];
+
+// ❌ Hardcoded union type - NOT DRY!
+newFilter.approval_status = status as "pending" | "approved" | "rejected";
+
+// ❌ Using string type - NO TYPE SAFETY!
+const [status, setStatus] = useState<string>("");
+
+// ❌ Hardcoded comparisons
+if (status === "pending") { ... }
+```
+
+### ✅ GOOD Patterns (REQUIRED)
+
+```typescript
+// ✅ Import Enum from generated file
+import { 
+  ApprovalStatus, 
+  ApprovalStatusValues,
+  isApprovalStatus,
+  getApprovalStatusLabel
+} from "@/omnify/enum/ApprovalStatus";
+
+// ✅ Type assertions with Enum
+newFilter.approval_status = status as ApprovalStatus;
+
+// ✅ State with Enum type
+const [status, setStatus] = useState<ApprovalStatus | "">(""); 
+// OR with default value:
+const [status, setStatus] = useState<ApprovalStatus>(ApprovalStatus.Pending);
+
+// ✅ Enum comparisons
+if (status === ApprovalStatus.Pending) { ... }
+
+// ✅ Iterate with Values array
+const options = ApprovalStatusValues.map(value => ({
+  value,
+  label: getApprovalStatusLabel(value, locale)
+}));
+
+// ✅ Type guard for validation
+if (isApprovalStatus(unknownValue)) {
+  // unknownValue is ApprovalStatus here
+}
+```
+
+### Generated Enum Files Structure
+
+```
+@/omnify/enum/
+├── ApprovalStatus.ts
+│   ├── ApprovalStatus        (enum)
+│   ├── ApprovalStatusValues  (array of all values)
+│   ├── isApprovalStatus()    (type guard)
+│   └── getApprovalStatusLabel()  (i18n label)
+├── OrderStatus.ts
+└── ...
+```
+
+### Select/Filter Options Pattern
+
+```typescript
+import { ApprovalStatus, ApprovalStatusValues, getApprovalStatusLabel } from "@/omnify/enum/ApprovalStatus";
+
+// ✅ Build options from Enum
+const statusOptions = ApprovalStatusValues.map(value => ({
+  value,
+  label: getApprovalStatusLabel(value, locale)
+}));
+
+<Select options={statusOptions} />
+```
+
 ## Form Pattern (Omnify)
 
 > **Detailed Guide:** See `react-form.mdc` for complete form development guide.

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

@@ -82,7 +82,154 @@ export interface User extends UserBase {
 
 ---
 
-## 2. Using Generated Types
+## 2. Enum Types (CRITICAL)
+
+**Location**: `@/omnify/enum/` or `@/types/model/enum/`
+
+**ALWAYS use generated Enums - NEVER inline union types!**
+
+### Generated Enum Structure
+
+```typescript
+// @/omnify/enum/ApprovalStatus.ts (auto-generated)
+
+// 1. Enum type
+export enum ApprovalStatus {
+  Pending = "pending",
+  Approved = "approved",
+  Rejected = "rejected",
+  Cancelled = "cancelled",
+}
+
+// 2. Values array (for iteration)
+export const ApprovalStatusValues = [
+  ApprovalStatus.Pending,
+  ApprovalStatus.Approved,
+  ApprovalStatus.Rejected,
+  ApprovalStatus.Cancelled,
+] as const;
+
+// 3. Type guard
+export function isApprovalStatus(value: unknown): value is ApprovalStatus {
+  return ApprovalStatusValues.includes(value as ApprovalStatus);
+}
+
+// 4. i18n label getter
+export function getApprovalStatusLabel(value: ApprovalStatus, 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: "pending" | "approved" | "rejected" = "pending";
+
+// ❌ String type - NO TYPE SAFETY!
+const [status, setStatus] = useState<string>("");
+
+// ❌ Hardcoded string comparisons
+if (status === "pending") { ... }
+```
+
+### ✅ REQUIRED Patterns
+
+```typescript
+// ✅ Import from generated enum file
+import { 
+  ApprovalStatus, 
+  ApprovalStatusValues,
+  isApprovalStatus,
+  getApprovalStatusLabel 
+} from "@/omnify/enum/ApprovalStatus";
+
+// ✅ Type assertions
+const status = unknownValue as ApprovalStatus;
+
+// ✅ State with Enum
+const [status, setStatus] = useState<ApprovalStatus | "">(""); 
+const [status, setStatus] = useState<ApprovalStatus>(ApprovalStatus.Pending);
+
+// ✅ Enum comparisons
+if (status === ApprovalStatus.Pending) { ... }
+
+// ✅ Iterate with Values array
+const options = ApprovalStatusValues.map(value => ({
+  value,
+  label: getApprovalStatusLabel(value, locale)
+}));
+
+// ✅ Type guard
+if (isApprovalStatus(value)) {
+  // value is ApprovalStatus
+}
+```
+
+### Select/Filter Options Pattern
+
+```typescript
+import { 
+  ApprovalStatus, 
+  ApprovalStatusValues, 
+  getApprovalStatusLabel 
+} from "@/omnify/enum/ApprovalStatus";
+import { useLocale } from "next-intl";
+
+function StatusFilter() {
+  const locale = useLocale();
+  
+  // ✅ Build options from generated enum
+  const statusOptions = ApprovalStatusValues.map(value => ({
+    value,
+    label: getApprovalStatusLabel(value, locale)
+  }));
+  
+  // ✅ State with Enum type
+  const [status, setStatus] = useState<ApprovalStatus | "all">("all");
+
+  return (
+    <Select
+      value={status}
+      onChange={setStatus}
+      options={[
+        { value: "all", label: t("common.all") },
+        ...statusOptions
+      ]}
+    />
+  );
+}
+```
+
+### Filter Params with Enum
+
+```typescript
+import { ApprovalStatus } from "@/omnify/enum/ApprovalStatus";
+
+interface AttendanceListParams {
+  filter?: {
+    approval_status?: ApprovalStatus;  // ✅ Use Enum type
+  };
+}
+
+// ✅ Type assertion with Enum
+const handleStatusChange = (value: string) => {
+  setFilters(prev => ({
+    ...prev,
+    filter: {
+      ...prev.filter,
+      approval_status: value as ApprovalStatus  // ✅ Not inline union type!
+    }
+  }));
+};
+```
+
+---
+
+## 3. Using Generated Types
 
 ### Create/Update Types