@famgia/omnify-laravel 0.0.88 → 0.0.90

package/stubs/ai-guides/claude-omnify/react-form-guide.md.stub

@@ -0,0 +1,259 @@
+# Omnify React Form Guide
+
+This guide explains how to build forms using Omnify generated schemas with **Ant Design** and **TanStack Query**.
+
+## Quick Start
+
+```tsx
+import { Form } from 'antd';
+import { useFormMutation } from '@/omnify/hooks';
+import { type CustomerCreate } from '@/omnify/schemas';
+import { CustomerForm } from '@/features/customers';
+import { api } from '@/lib/api';
+
+function CreateCustomerPage() {
+  const [form] = Form.useForm<CustomerCreate>();
+
+  const mutation = useFormMutation<CustomerCreate>({
+    form,
+    mutationFn: (data) => api.post('/customers', data),
+    invalidateKeys: [['customers']],
+    successMessage: 'Customer created successfully',
+    onSuccess: () => form.resetFields(),
+  });
+
+  return (
+    <CustomerForm
+      form={form}
+      onSubmit={mutation.mutate}
+      loading={mutation.isPending}
+    />
+  );
+}
+```
+
+## useFormMutation Hook
+
+Location: `resources/ts/omnify/hooks/use-form-mutation.ts`
+
+### Usage with Types
+
+```tsx
+import { useFormMutation } from '@/omnify/hooks';
+import { type CustomerCreate } from '@/omnify/schemas';
+
+// With type parameter for type safety
+const mutation = useFormMutation<CustomerCreate>({
+  form,
+  mutationFn: (data) => api.post('/customers', data),
+  invalidateKeys: [['customers']],
+  successMessage: 'Saved successfully',
+  onSuccess: () => form.resetFields(),
+});
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `form` | `FormInstance<T>` | Ant Design form instance (required) |
+| `mutationFn` | `(data: T) => Promise` | API call function (required) |
+| `invalidateKeys` | `string[][]` | Query keys to invalidate on success |
+| `successMessage` | `string` | Toast message on success |
+| `onSuccess` | `(data) => void` | Callback after success |
+| `onError` | `(error) => void` | Callback after error |
+
+### Laravel Error Handling
+
+The hook automatically handles Laravel validation errors (422):
+
+```json
+{
+  "message": "The given data was invalid.",
+  "errors": {
+    "email": ["The email has already been taken."]
+  }
+}
+```
+
+## Japanese Form Components
+
+Omnify provides specialized components for Japanese data input.
+
+### OmnifyForm.JapaneseName
+
+```tsx
+import { OmnifyForm } from '@/omnify/components';
+
+<OmnifyForm.JapaneseName
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="name"        // name_lastname, name_firstname, etc.
+  required             // Show required asterisk
+  showKana={true}      // Show kana fields (default)
+/>
+```
+
+**Fields:** `{prefix}_lastname`, `{prefix}_firstname`, `{prefix}_kana_lastname`, `{prefix}_kana_firstname`
+
+### OmnifyForm.JapaneseAddress
+
+```tsx
+import { OmnifyForm } from '@/omnify/components';
+
+<OmnifyForm.JapaneseAddress
+  form={form}
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="address"
+  enablePostalLookup={true}  // Postal code → address lookup
+/>
+```
+
+**Fields:** `{prefix}_postal_code`, `{prefix}_prefecture`, `{prefix}_address1`, `{prefix}_address2`, `{prefix}_address3`
+
+**Options:**
+- `enablePostalLookup` - Enable postal code search
+- `autoSearch` - Auto-search when 7 digits entered
+- `usePrefectureId` - Use numeric ID instead of string enum
+
+### OmnifyForm.JapaneseBank
+
+```tsx
+import { OmnifyForm } from '@/omnify/components';
+
+<OmnifyForm.JapaneseBank
+  schemas={customerSchemas}
+  i18n={customerI18n}
+  prefix="bank"
+/>
+```
+
+**Fields:** `{prefix}_bank_code`, `{prefix}_branch_code`, `{prefix}_account_type`, `{prefix}_account_number`, `{prefix}_account_holder`
+
+Account type options auto-loaded from `BankAccountType` enum with i18n.
+
+## Complete Form Example
+
+```tsx
+import { Form, Input, Button, Card, Space, Divider } from 'antd';
+import type { FormInstance } from 'antd';
+import { zodRule, setZodLocale } from '@/omnify/lib';
+import { OmnifyForm } from '@/omnify/components';
+import {
+  type Customer, type CustomerCreate,
+  customerSchemas, customerI18n,
+  getCustomerFieldLabel, getCustomerFieldPlaceholder,
+} from '@/omnify/schemas';
+
+const LOCALE = 'ja';
+
+interface CustomerFormProps {
+  form: FormInstance<CustomerCreate>;
+  initialValues?: Partial<Customer>;
+  onSubmit: (values: CustomerCreate) => void;
+  loading?: boolean;
+  isEdit?: boolean;
+}
+
+export function CustomerForm({ form, initialValues, onSubmit, loading, isEdit }: CustomerFormProps) {
+  setZodLocale(LOCALE);
+
+  const label = (key: string) => getCustomerFieldLabel(key, LOCALE);
+  const placeholder = (key: string) => getCustomerFieldPlaceholder(key, LOCALE);
+  const rule = (key: keyof typeof customerSchemas) => zodRule(customerSchemas[key], label(key));
+
+  return (
+    <Card>
+      <Form form={form} layout="horizontal" labelCol={{ span: 6 }} wrapperCol={{ span: 18 }}
+            initialValues={initialValues} onFinish={onSubmit} style={{ maxWidth: 800 }}>
+        
+        <Divider orientation="left">Name</Divider>
+        <OmnifyForm.JapaneseName schemas={customerSchemas} i18n={customerI18n} prefix="name" required />
+
+        <Divider orientation="left">Contact</Divider>
+        <Form.Item name="phone" label={label('phone')} rules={[rule('phone')]}>
+          <Input placeholder={placeholder('phone')} />
+        </Form.Item>
+        <Form.Item name="email" label={label('email')} rules={[rule('email')]}>
+          <Input type="email" placeholder={placeholder('email')} />
+        </Form.Item>
+
+        <Divider orientation="left">Address</Divider>
+        <OmnifyForm.JapaneseAddress form={form} schemas={customerSchemas} i18n={customerI18n}
+                              prefix="address" enablePostalLookup={true} />
+
+        <Divider orientation="left">Bank Account</Divider>
+        <OmnifyForm.JapaneseBank schemas={customerSchemas} i18n={customerI18n} prefix="bank" />
+
+        <Form.Item wrapperCol={{ offset: 6, span: 18 }}>
+          <Space>
+            <Button type="primary" htmlType="submit" loading={loading}>
+              {isEdit ? 'Update' : 'Create'}
+            </Button>
+          </Space>
+        </Form.Item>
+      </Form>
+    </Card>
+  );
+}
+```
+
+## Zod Validation with i18n
+
+```tsx
+import { zodRule, setZodLocale } from '@/omnify/lib';
+
+// Set locale once at component level
+setZodLocale('ja');
+
+// Use zodRule for field validation
+<Form.Item name="email" label={label('email')} rules={[zodRule(customerSchemas.email, label('email'))]}>
+  <Input />
+</Form.Item>
+```
+
+## Kana Validation Rules
+
+```tsx
+import { kanaString, KATAKANA_PATTERN } from '@/omnify/lib/rules';
+
+// Full-width katakana (default)
+const kanaSchema = kanaString();
+
+// Custom options
+const kanaSchema = kanaString({
+  fullWidthKatakana: true,
+  hiragana: true,
+  allowNumbers: true,
+});
+```
+
+## File Structure
+
+```
+resources/ts/omnify/
+├── components/
+│   ├── JapaneseNameField.tsx
+│   ├── JapaneseAddressField.tsx
+│   └── JapaneseBankField.tsx
+├── enum/
+│   └── plugin/
+│       ├── Prefecture.ts
+│       └── BankAccountType.ts
+├── hooks/
+│   └── use-form-mutation.ts
+├── lib/
+│   ├── form-validation.ts
+│   ├── zod-i18n.ts
+│   └── rules/kana.ts
+└── schemas/
+```
+
+## Tips
+
+1. **Use type generics** - `useFormMutation<CustomerCreate>` for type safety
+2. **Use `setZodLocale`** - Call once for localized validation messages
+3. **Use OmnifyForm.* components** - Built-in i18n, validation, postal lookup
+4. **Set `invalidateKeys`** - Auto-refresh lists after mutations
+5. **Don't pass `form` to Name/Bank components** - Only Address needs it for postal lookup

package/stubs/ai-guides/claude-omnify/schema-guide.md.stub

@@ -0,0 +1,115 @@
+# Omnify Schema Guide
+
+## Schema File Format
+
+Schemas are YAML files defining data models. Each file represents one entity.
+
+```yaml
+name: User
+displayName:
+  ja: ユーザー
+  en: User
+kind: object
+
+properties:
+  email:
+    type: Email
+    unique: true
+  name:
+    type: String
+  bio:
+    type: Text
+    nullable: true
+
+options:
+  timestamps: true
+  softDelete: true
+```
+
+## Property Types
+
+### String Types
+- `String` - VARCHAR(255)
+- `Text` - TEXT
+- `LongText` - LONGTEXT
+- `Email` - VARCHAR(255) for email addresses
+- `Password` - VARCHAR(255), hidden in serialization
+
+### Numeric Types
+- `Int` - INTEGER
+- `BigInt` - BIGINT
+- `TinyInt` - TINYINT
+- `Float` - DOUBLE
+- `Decimal` - DECIMAL(precision, scale)
+
+### Date/Time Types
+- `Date` - DATE
+- `Time` - TIME
+- `DateTime` - DATETIME
+- `Timestamp` - TIMESTAMP
+
+### Other Types
+- `Boolean` - BOOLEAN
+- `Json` - JSON
+- `Enum` - ENUM with values
+- `EnumRef` - Reference to enum schema
+
+## Property Options
+
+```yaml
+propertyName:
+  type: String
+  nullable: true       # Can be NULL
+  unique: true         # Unique constraint
+  default: "value"     # Default value
+  length: 100          # VARCHAR length
+  hidden: true         # Hide from JSON output
+  fillable: false      # Exclude from mass assignment
+```
+
+## Associations
+
+```yaml
+# Many-to-One (belongsTo)
+author:
+  type: Association
+  relation: ManyToOne
+  target: User
+  onDelete: CASCADE
+
+# One-to-Many (hasMany)
+posts:
+  type: Association
+  relation: OneToMany
+  target: Post
+
+# Many-to-Many (belongsToMany)
+tags:
+  type: Association
+  relation: ManyToMany
+  target: Tag
+  joinTable: post_tags
+
+# Polymorphic
+commentable:
+  type: Association
+  relation: MorphTo
+```
+
+## Indexes
+
+```yaml
+indexes:
+  - columns: [status, published_at]
+  - columns: [email]
+    unique: true
+```
+
+## Schema Options
+
+```yaml
+options:
+  timestamps: true   # Add created_at, updated_at
+  softDelete: true   # Add deleted_at
+  idType: BigInt     # Primary key type (Int, BigInt, Uuid)
+```

package/stubs/ai-guides/claude-omnify/typescript-guide.md.stub

@@ -0,0 +1,310 @@
+# Omnify TypeScript Generator Guide
+
+This guide covers TypeScript-specific features and generated code patterns for Omnify.
+
+## Quick Start
+
+```bash
+# Create new project (recommended)
+npx @famgia/omnify create-laravel-project my-app
+cd my-app
+
+# Or initialize in existing project
+npx @famgia/omnify init
+
+# Generate TypeScript types
+npx @famgia/omnify generate
+```
+
+## Generated Files
+
+When you run `npx @famgia/omnify generate`, the following TypeScript files are generated:
+
+- `base/*.ts` - Base model interfaces
+- `enum/*.ts` - Enum types with multi-locale labels
+- `rules/*.ts` - Ant Design compatible validation rules
+
+## Type Generation
+
+### Object Schema → Interface
+
+```yaml
+# yaml-language-server: $schema=./node_modules/.omnify/combined-schema.json
+name: User
+properties:
+  id:
+    type: BigInt
+    required: true
+  name:
+    type: String
+    required: true
+    maxLength: 255
+  email:
+    type: String
+    required: true
+    unique: true
+  profile:
+    type: Json
+  createdAt:
+    type: DateTime
+```
+
+Generated:
+```typescript
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+  profile: Record<string, unknown> | null;
+  createdAt: Date | null;
+}
+```
+
+## Type Mapping
+
+| Schema Type | TypeScript Type |
+|-------------|-----------------|
+| `String` | `string` |
+| `Text` | `string` |
+| `MediumText` | `string` |
+| `LongText` | `string` |
+| `TinyInt` | `number` |
+| `Int` | `number` |
+| `BigInt` | `number` |
+| `Float` | `number` |
+| `Decimal` | `number` |
+| `Boolean` | `boolean` |
+| `Date` | `Date` |
+| `DateTime` | `Date` |
+| `Timestamp` | `Date` |
+| `Json` | `Record<string, unknown>` |
+| `EnumRef` | Generated enum type |
+| `Association` | Related model type / array |
+
+## Hidden Schemas
+
+Schemas with `options.hidden: true` are skipped for TypeScript generation:
+
+```yaml
+name: AppCache
+options:
+  hidden: true    # No TypeScript interface generated
+```
+
+Use cases:
+- System tables (cache, sessions, jobs)
+- Tables that don't need frontend types
+
+## Enum Generation (Multi-locale)
+
+```yaml
+# schemas/PostStatus.yaml
+name: PostStatus
+kind: enum
+displayName:
+  ja: 投稿ステータス
+  en: Post Status
+values:
+  draft:
+    ja: 下書き
+    en: Draft
+  published:
+    ja: 公開済み
+    en: Published
+  archived:
+    ja: アーカイブ
+    en: Archived
+```
+
+Generated:
+```typescript
+export const PostStatus = {
+  draft: 'draft',
+  published: 'published',
+  archived: 'archived',
+} as const;
+
+export type PostStatus = typeof PostStatus[keyof typeof PostStatus];
+
+// Multi-locale labels
+export const PostStatusLabels: Record<PostStatus, Record<string, string>> = {
+  draft: { ja: '下書き', en: 'Draft' },
+  published: { ja: '公開済み', en: 'Published' },
+  archived: { ja: 'アーカイブ', en: 'Archived' },
+};
+
+// Get label for specific locale
+export function getPostStatusLabel(value: PostStatus, locale: string = 'en'): string {
+  return PostStatusLabels[value]?.[locale] ?? PostStatusLabels[value]?.['en'] ?? value;
+}
+
+// Helper functions
+export const PostStatusValues = Object.values(PostStatus);
+export function isPostStatus(value: unknown): value is PostStatus {
+  return PostStatusValues.includes(value as PostStatus);
+}
+```
+
+## Validation Rules (Ant Design)
+
+Omnify generates Ant Design compatible validation rules in `rules/` directory.
+
+**See detailed guide:** `.claude/omnify/antdesign-guide.md`
+
+Quick example:
+```tsx
+import { Form, Input } from 'antd';
+import { getUserRules, getUserPropertyDisplayName } from './types/model/rules/User.rules';
+
+function UserForm({ locale = 'ja' }) {
+  const rules = getUserRules(locale);
+  return (
+    <Form>
+      <Form.Item name="name" label={getUserPropertyDisplayName('name', locale)} rules={rules.name}>
+        <Input />
+      </Form.Item>
+    </Form>
+  );
+}
+```
+
+## Association Types
+
+### ManyToOne
+```yaml
+author:
+  type: Association
+  relation: ManyToOne
+  target: User
+```
+
+Generated:
+```typescript
+export interface Post {
+  authorId: number;
+  author?: User;  // Optional: loaded relation
+}
+```
+
+### OneToMany
+```yaml
+posts:
+  type: Association
+  relation: OneToMany
+  target: Post
+```
+
+Generated:
+```typescript
+export interface User {
+  posts?: Post[];  // Optional: loaded relation array
+}
+```
+
+### ManyToMany
+```yaml
+tags:
+  type: Association
+  relation: ManyToMany
+  target: Tag
+```
+
+Generated:
+```typescript
+export interface Post {
+  tags?: Tag[];  // Optional: loaded relation array
+}
+```
+
+## Nullable Fields
+
+Fields without `required: true` are nullable:
+
+```yaml
+description:
+  type: LongText  # No required: true
+```
+
+Generated:
+```typescript
+description: string | null;
+```
+
+## Using Generated Types
+
+```typescript
+import { User, Post, PostStatus, isPostStatus } from './types/omnify-types';
+
+// Type-safe object creation
+const user: User = {
+  id: 1,
+  name: 'John',
+  email: 'john@example.com',
+  profile: null,
+  createdAt: new Date(),
+};
+
+// Enum usage
+const status: PostStatus = PostStatus.draft;
+
+// Type guard
+function handleStatus(value: unknown) {
+  if (isPostStatus(value)) {
+    console.log('Valid status:', value);
+  }
+}
+```
+
+## Commands
+
+```bash
+# Create new project
+npx @famgia/omnify create-laravel-project my-app
+
+# Generate TypeScript types
+npx @famgia/omnify generate
+
+# Force regenerate all files
+npx @famgia/omnify generate --force
+
+# Only generate TypeScript types
+npx @famgia/omnify generate --types-only
+
+# Validate schemas
+npx @famgia/omnify validate
+```
+
+## Configuration
+
+```typescript
+// omnify.config.ts
+import { defineConfig } from '@famgia/omnify';
+import typescript from '@famgia/omnify-typescript/plugin';
+
+export default defineConfig({
+  schemasDir: './schemas',
+  lockFilePath: './.omnify.lock',
+
+  plugins: [
+    typescript({
+      // Output path for TypeScript files
+      path: './resources/ts/types/models',
+
+      // Generate Ant Design validation rules
+      generateRules: true,
+    }),
+  ],
+
+  locale: {
+    locales: ['ja', 'en'],
+    defaultLocale: 'ja',
+  },
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | `string` | `./src/types/model` | TypeScript output directory |
+| `generateRules` | `boolean` | `true` | Generate Ant Design validation rules |