@famgia/omnify-typescript 0.0.67 → 0.0.69

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

@@ -0,0 +1,524 @@
+# TypeScript Types Guide
+
+> This guide defines where and how to define types in this project.
+
+## Type Categories
+
+| Category            | Location             | Generated | Example                       |
+| ------------------- | -------------------- | --------- | ----------------------------- |
+| **Model**           | `@/types/model`      | ✅ Omnify  | `User`, `Post`                |
+| **Create/Update**   | `@/types/model`      | ✅ Omnify  | `UserCreate`, `UserUpdate`    |
+| **Common**          | `@/types/model`      | ✅ Omnify  | `DateTimeString`, `LocaleMap` |
+| **Validation**      | `@/types/model`      | ✅ Omnify  | `getUserRules(locale)`        |
+| **Enum**            | `@/types/model/enum` | ✅ Omnify  | `PostStatus`, `UserRole`      |
+| **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**: `src/types/model/`
+
+**Source**: Auto-generated from `.omnify/schemas/`
+
+```typescript
+// ✅ Import from @/types/model
+import type { User, UserCreate, UserUpdate } from "@/types/model";
+import type { DateTimeString } from "@/types/model";
+import { getUserRules } from "@/types/model";
+
+// ❌ DON'T define model types manually
+interface User { ... }  // WRONG - already generated
+```
+
+### Structure
+
+```
+src/types/model/
+├── common.ts                ❌ DO NOT EDIT
+│                            # LocaleMap, ValidationRule, DateTimeString
+├── base/                    ❌ DO NOT EDIT
+│   └── User.ts              # User + UserCreate + UserUpdate
+├── rules/                   ❌ DO NOT EDIT
+│   └── User.rules.ts        # getUserRules(), getUserDisplayName()
+├── enum/                    ❌ DO NOT EDIT (if exists)
+│   └── PostStatus.ts
+├── index.ts                 ❌ DO NOT EDIT (re-exports)
+└── User.ts                  ✅ CAN EDIT (extension)
+```
+
+### 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.js";
+
+export interface User extends UserBase {
+  // Frontend-only computed properties
+  fullName?: string;
+  
+  // UI state
+  isSelected?: boolean;
+}
+```
+
+---
+
+## 2. Using Generated Types
+
+### Create/Update Types
+
+```typescript
+// ✅ Use Omnify-generated types
+import type { User, UserCreate, UserUpdate } from "@/types/model";
+
+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, getCustomerFieldLabel } from "@/types/model/User";
+import { zodRule } from "@/lib/form-validation";
+import { useLocale } from "next-intl";
+
+function UserForm() {
+  const locale = useLocale();
+  const label = (key: string) => getCustomerFieldLabel(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 "@/types/model";
+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 "@/types/model";
+
+/** 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 "@/types/model";
+
+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 "@/types/model";
+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 `@/types/model` (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.js";
+
+export interface User extends UserBase {
+  // Add frontend-only properties if needed
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// services/users.ts
+// ═══════════════════════════════════════════════════════════════════
+import api, { PaginatedResponse } from "@/lib/api";
+import type { User } from "@/types/model";
+
+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 "@/types/model";
+
+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    | `@/types/model`      | 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.

package/stubs/components-index.ts.stub

@@ -0,0 +1,13 @@
+import { JapaneseNameField } from './JapaneseNameField.js';
+import { JapaneseAddressField } from './JapaneseAddressField.js';
+import { JapaneseBankField } from './JapaneseBankField.js';
+
+// Namespace style exports (recommended)
+export const OmnifyForm = {
+  JapaneseName: JapaneseNameField,
+  JapaneseAddress: JapaneseAddressField,
+  JapaneseBank: JapaneseBankField,
+} as const;
+
+// Legacy exports (backward compatible)
+export { JapaneseNameField, JapaneseAddressField, JapaneseBankField };

package/stubs/form-validation.ts.stub

@@ -0,0 +1,106 @@
+/**
+ * Form validation utilities for Ant Design + Zod
+ * Generated by Omnify. You can customize this file.
+ */
+
+import type { RuleObject } from 'antd/es/form';
+import type { z } from 'zod';
+import { getZodMessage } from './zod-i18n.js';
+
+/**
+ * Convert Zod schema to Ant Design Form rule with i18n support
+ *
+ * @example
+ * // Set locale once at component level
+ * setZodLocale('ja');
+ *
+ * // Use without passing locale
+ * <Form.Item
+ *   name="email"
+ *   rules={[zodRule(customerSchemas.email, 'メールアドレス')]}
+ * >
+ *   <Input />
+ * </Form.Item>
+ */
+export function zodRule<T extends z.ZodTypeAny>(
+  schema: T,
+  displayName?: string
+): RuleObject {
+  const field = displayName ?? 'この項目';
+
+  return {
+    validator: async (_, value) => {
+      // Empty check - treat as required
+      if (value === undefined || value === null || value === '') {
+        if (schema.safeParse(undefined).success) return;
+        throw new Error(getZodMessage('required', { displayName: field }));
+      }
+
+      const result = schema.safeParse(value);
+      if (result.success) return;
+
+      // Get first Zod error
+      const issue = result.error.issues[0];
+      if (!issue) {
+        throw new Error(getZodMessage('required', { displayName: field }));
+      }
+
+      // Translate based on error type
+      switch (issue.code) {
+        case 'too_small':
+          if (issue.type === 'string' && issue.minimum === 1) {
+            throw new Error(getZodMessage('required', { displayName: field }));
+          }
+          if (issue.type === 'string') {
+            throw new Error(getZodMessage('minLength', { displayName: field, min: issue.minimum as number }));
+          }
+          throw new Error(getZodMessage('min', { displayName: field, min: issue.minimum as number }));
+
+        case 'too_big':
+          if (issue.type === 'string') {
+            throw new Error(getZodMessage('maxLength', { displayName: field, max: issue.maximum as number }));
+          }
+          throw new Error(getZodMessage('max', { displayName: field, max: issue.maximum as number }));
+
+        case 'invalid_string':
+          if (issue.validation === 'email') {
+            throw new Error(getZodMessage('email', { displayName: field }));
+          }
+          if (issue.validation === 'url') {
+            throw new Error(getZodMessage('url', { displayName: field }));
+          }
+          if (issue.validation === 'regex') {
+            throw new Error(getZodMessage('pattern', { displayName: field }));
+          }
+          break;
+
+        case 'invalid_type':
+          if (issue.received === 'undefined' || issue.received === 'null') {
+            throw new Error(getZodMessage('required', { displayName: field }));
+          }
+          break;
+      }
+
+      // Fallback to Zod's original message
+      throw new Error(issue.message);
+    },
+  };
+}
+
+/**
+ * Create required rule with i18n message
+ *
+ * @example
+ * <Form.Item
+ *   name="name"
+ *   rules={[requiredRule('名前')]}
+ * >
+ *   <Input />
+ * </Form.Item>
+ */
+export function requiredRule(displayName: string): RuleObject {
+  return {
+    required: true,
+    message: getZodMessage('required', { displayName }),
+  };
+}

package/stubs/rules/index.ts.stub

@@ -0,0 +1,48 @@
+/**
+ * Japanese validation rules
+ * 
+ * Usage with Zod:
+ * ```typescript
+ * import { z } from 'zod';
+ * import { kanaString, KATAKANA_PATTERN } from '@/omnify/lib/rules';
+ * 
+ * // Method 1: Use kanaString helper
+ * const schema = z.object({
+ *   name_kana: kanaString(),  // 全角カタカナ (default)
+ * });
+ * 
+ * // Method 2: Use pattern directly
+ * const schema2 = z.object({
+ *   name_kana: z.string().regex(KATAKANA_PATTERN, '全角カタカナで入力してください'),
+ * });
+ * ```
+ */
+
+export {
+    // Kana validation
+    kanaRules,
+    createKanaRegex,
+    validateKana,
+    getKanaPattern,
+    getKanaErrorMessage,
+    // Zod helpers
+    kanaString,
+    withKana,
+    // Pattern constants
+    KATAKANA_PATTERN,
+    KATAKANA_HALF_PATTERN,
+    HIRAGANA_PATTERN,
+    KANA_ANY_PATTERN,
+    // Presets
+    KATAKANA_FULL_WIDTH,
+    KATAKANA_HALF_WIDTH,
+    HIRAGANA,
+    KANA_ANY,
+    KATAKANA_WITH_NUMBERS,
+    // Types
+    type KanaRuleOptions,
+} from './kana';
+
+// Re-export as convenient aliases
+export { getKanaPattern as kanaPattern } from './kana';
+export { createKanaRegex as kanaRegex } from './kana';