@famgia/omnify 1.0.100 → 1.0.102

package/ai-guides/schema-guide.md

@@ -4,6 +4,91 @@
 
 All schemas are stored in `schemas/` directory with `.yaml` extension.
 
+## Multi-language Support (i18n)
+
+Omnify supports multi-language labels and placeholders for internationalized applications.
+
+### Supported Locales
+
+| Code    | Language                       |
+| ------- | ------------------------------ |
+| `ja`    | Japanese (日本語)              |
+| `en`    | English                        |
+| `vi`    | Vietnamese (Tiếng Việt)        |
+| `ko`    | Korean (한국어)                |
+| `zh-CN` | Simplified Chinese (简体中文)  |
+| `zh-TW` | Traditional Chinese (繁體中文) |
+| `th`    | Thai (ภาษาไทย)                 |
+| `es`    | Spanish (Español)              |
+
+### Usage in Schema
+
+```yaml
+# Model-level i18n
+displayName:
+  ja: 顧客
+  en: Customer
+  vi: Khách hàng
+
+description:
+  ja: 顧客情報を管理するモデル
+  en: Model for managing customer information
+  vi: Model quản lý thông tin khách hàng
+
+properties:
+  email:
+    type: Email
+    # Property-level i18n
+    displayName:
+      ja: メールアドレス
+      en: Email Address
+      vi: Địa chỉ email
+    placeholder:
+      ja: "例：customer@example.com"
+      en: "e.g. customer@example.com"
+      vi: "VD: customer@example.com"
+    description:
+      ja: 連絡先メールアドレス
+      en: Contact email address
+      vi: Địa chỉ email liên hệ
+
+  notes:
+    type: Text
+    nullable: true
+    displayName:
+      ja: 備考
+      en: Notes
+      vi: Ghi chú
+    placeholder:
+      ja: 顧客に関するメモを入力してください
+      en: Enter notes about this customer
+      vi: Nhập ghi chú về khách hàng này
+```
+
+### Enum i18n
+
+```yaml
+name: PostStatus
+kind: enum
+displayName:
+  ja: 投稿ステータス
+  en: Post Status
+  vi: Trạng thái bài viết
+values:
+  draft:
+    ja: 下書き
+    en: Draft
+    vi: Bản nháp
+  published:
+    ja: 公開済み
+    en: Published
+    vi: Đã xuất bản
+  archived:
+    ja: アーカイブ
+    en: Archived
+    vi: Đã lưu trữ
+```
+
 ## Object Schema Structure
 
 ```yaml
@@ -17,77 +102,370 @@ description:             # Optional: i18n description
   ja: 説明文
   en: Description
 group: group-name        # Optional: for organizing schemas
+titleIndex: name         # Optional: property to use as record title/label
 options:
-  id: true               # Auto-generate id column (default: true)
-  idType: BigInt         # Id type: BigInt, Int, Uuid, String (default: BigInt)
-  softDelete: true       # Enable soft delete (deleted_at column)
-  timestamps: true       # Enable created_at, updated_at
-  tableName: custom_name # Custom table name
-  hidden: false          # Hide from model generation (default: false)
+  # See Schema Options below
 properties:
   # Property definitions here
 ```
 
+### Schema Options Reference
+
+| Option                         | Type    | Default    | Description                                        |
+| ------------------------------ | ------- | ---------- | -------------------------------------------------- |
+| `id`                           | boolean | `true`     | Auto-generate `id` primary key column              |
+| `idType`                       | string  | `BigInt`   | ID type: `BigInt`, `Int`, `Uuid`, `String`         |
+| `timestamps`                   | boolean | `false`    | Add `created_at`, `updated_at` columns             |
+| `softDelete`                   | boolean | `false`    | Add `deleted_at` column for soft deletes           |
+| `tableName`                    | string  | -          | Custom table name (default: pluralized snake_case) |
+| `hidden`                       | boolean | `false`    | Skip model generation (migrations only)            |
+| `translations`                 | boolean | `false`    | Enable translations support                        |
+| `unique`                       | array   | -          | Unique constraints (see below)                     |
+| `indexes`                      | array   | -          | Database indexes (see below)                       |
+| `authenticatable`              | boolean | `false`    | Enable auth trait (User-like schemas)              |
+| `authenticatableLoginIdField`  | string  | `email`    | Login ID field for auth                            |
+| `authenticatablePasswordField` | string  | `password` | Password field for auth                            |
+| `authenticatableGuardName`     | string  | -          | Guard name for auth                                |
+
+### Schema Options Example
+
+```yaml
+options:
+  id: true
+  idType: BigInt
+  timestamps: true
+  softDelete: true
+  tableName: custom_table_name
+  hidden: false
+  
+  # Unique constraints
+  unique:
+    - email                      # Single column unique
+    - [tenant_id, slug]          # Composite unique
+  
+  # Database indexes
+  indexes:
+    - columns: [status]          # Simple index
+    - columns: [published_at]
+      name: idx_published        # Custom index name
+    - columns: [status, published_at]
+      unique: true               # Unique index
+    - columns: [title]
+      type: fulltext             # Fulltext index (MySQL)
+```
+
+### Authenticatable Schema (User)
+
+```yaml
+name: User
+displayName:
+  ja: ユーザー
+  en: User
+options:
+  timestamps: true
+  softDelete: true
+  authenticatable: true
+  authenticatableLoginIdField: email
+  authenticatablePasswordField: password
+  authenticatableGuardName: web
+
+properties:
+  email:
+    type: Email
+    unique: true
+  password:
+    type: Password
+  name:
+    type: String
+```
+
 ## Property Types
 
 ### String Types
-| Type | Description | Options |
-|------|-------------|---------|
-| `String` | Short text (varchar) | `length`, `default` |
-| `Text` | Text (~65KB) | `default` |
-| `MediumText` | Medium text (~16MB) | `default` |
-| `LongText` | Long text (~4GB) | `default` |
+| Type         | Description          | Options                |
+| ------------ | -------------------- | ---------------------- |
+| `String`     | Short text (varchar) | `length`, `default`    |
+| `Email`      | Email address        | `length`, `default`    |
+| `Password`   | Hashed password      | `length` (auto-hidden) |
+| `Text`       | Text (~65KB)         | `default`              |
+| `MediumText` | Medium text (~16MB)  | `default`              |
+| `LongText`   | Long text (~4GB)     | `default`              |
 
 ### Numeric Types
-| Type | Description | Options |
-|------|-------------|---------|
-| `TinyInt` | 8-bit integer (-128~127) | `default`, `unsigned` |
-| `Int` | 32-bit integer | `default`, `unsigned` |
-| `BigInt` | 64-bit integer | `default`, `unsigned` |
-| `Float` | Floating point | `default` |
-| `Decimal` | Precise decimal | `precision`, `scale`, `default` |
+| Type      | Description              | Options                         |
+| --------- | ------------------------ | ------------------------------- |
+| `TinyInt` | 8-bit integer (-128~127) | `default`, `unsigned`           |
+| `Int`     | 32-bit integer           | `default`, `unsigned`           |
+| `BigInt`  | 64-bit integer           | `default`, `unsigned`           |
+| `Float`   | Floating point           | `default`                       |
+| `Decimal` | Precise decimal          | `precision`, `scale`, `default` |
 
 ### Date/Time Types
-| Type | Description | Options |
-|------|-------------|---------|
-| `Date` | Date only | `default` |
-| `DateTime` | Date and time | `default` |
-| `Timestamp` | Timestamp | `useCurrent`, `useCurrentOnUpdate` |
+| Type        | Description   | Options                            |
+| ----------- | ------------- | ---------------------------------- |
+| `Date`      | Date only     | `default`                          |
+| `Time`      | Time only     | `default`                          |
+| `DateTime`  | Date and time | `default`                          |
+| `Timestamp` | Timestamp     | `useCurrent`, `useCurrentOnUpdate` |
 
 ### Other Types
-| Type | Description | Options |
-|------|-------------|---------|
-| `Boolean` | True/false | `default` |
-| `Json` | JSON object | `default` |
-| `EnumRef` | Reference to enum | `enum` (required), `default` |
+| Type          | Description                   | Options                                     |
+| ------------- | ----------------------------- | ------------------------------------------- |
+| `Boolean`     | True/false                    | `default`                                   |
+| `Json`        | JSON object                   | `default`                                   |
+| `EnumRef`     | Reference to shared enum      | `enum` (required), `default`                |
+| `Enum`        | Inline enum values            | `enum` (array of values), `default`         |
+| `File`        | File attachment (polymorphic) | `multiple`, `maxFiles`, `accept`, `maxSize` |
+| `Point`       | Spatial POINT (lat/lng)       | -                                           |
+| `Coordinates` | Two DECIMALs (lat, lng)       | - (more portable than Point)                |
+
+### File Type Example
+
+```yaml
+avatar:
+  type: File
+  displayName:
+    ja: プロフィール画像
+    en: Profile Image
+  accept: [jpg, png, webp]    # Allowed extensions
+  maxSize: 2048               # Max file size in KB
+
+attachments:
+  type: File
+  multiple: true              # Allow multiple files
+  maxFiles: 5                 # Maximum number of files
+  accept: [pdf, doc, docx]
+  maxSize: 10240
+```
+
+### Inline Enum Example
+
+```yaml
+priority:
+  type: Enum
+  enum: [low, medium, high]   # Inline values
+  default: medium
+  displayName:
+    ja: 優先度
+    en: Priority
+```
+
+### Japan Types (Plugin: @famgia/omnify-japan)
+
+Requires `@famgia/omnify-japan` plugin in `omnify.config.ts`.
+
+#### Simple Types
+| Type                 | Description                        | SQL Output    |
+| -------------------- | ---------------------------------- | ------------- |
+| `JapanesePhone`      | Phone number (e.g., 090-1234-5678) | `VARCHAR(15)` |
+| `JapanesePostalCode` | Postal code (e.g., 123-4567)       | `VARCHAR(8)`  |
+
+```yaml
+phone:
+  type: JapanesePhone
+  displayName:
+    ja: 電話番号
+    en: Phone Number
+  placeholder:
+    ja: "例：090-1234-5678"
+    en: "e.g. 090-1234-5678"
+
+postal_code:
+  type: JapanesePostalCode
+  displayName:
+    ja: 郵便番号
+    en: Postal Code
+```
+
+#### Compound Types (Auto-expand to multiple columns)
+
+| Type                  | Expanded Columns                                                                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `JapaneseName`        | `{prefix}_lastname`, `{prefix}_firstname`, `{prefix}_kana_lastname`, `{prefix}_kana_firstname`                                                                            |
+| `JapaneseAddress`     | `{prefix}_postal_code`, `{prefix}_prefecture`, `{prefix}_address1`, `{prefix}_address2`, `{prefix}_address3`                                                              |
+| `JapaneseBankAccount` | `{prefix}_bank_code`, `{prefix}_bank_name`, `{prefix}_branch_code`, `{prefix}_branch_name`, `{prefix}_account_type`, `{prefix}_account_number`, `{prefix}_account_holder` |
+
+##### JapaneseName Example
+
+```yaml
+name:
+  type: JapaneseName
+  displayName:
+    ja: 氏名
+    en: Full Name
+  # Override individual fields
+  fields:
+    Lastname:
+      length: 100              # Override VARCHAR length (default: 50)
+      displayName:
+        ja: 顧客姓
+        en: Customer Last Name
+      placeholder:
+        ja: "例：山田"
+        en: "e.g. Yamada"
+    Firstname:
+      length: 100
+      placeholder:
+        ja: "例：太郎"
+        en: "e.g. Taro"
+    KanaLastname:
+      length: 200
+      nullable: true           # Make optional (default: required)
+      hidden: true             # Hide from forms
+      placeholder:
+        ja: "例：ヤマダ"
+        en: "e.g. Yamada (Kana)"
+    KanaFirstname:
+      length: 200
+      nullable: true
+      hidden: true
+```
+
+##### JapaneseAddress Example
+
+```yaml
+address:
+  type: JapaneseAddress
+  displayName:
+    ja: 住所
+    en: Address
+  fields:
+    # PostalCode: uses plugin default (例：123-4567)
+    # Prefecture: uses Prefecture enum from plugin (47 prefectures)
+    Address1:
+      displayName:
+        ja: 市区町村
+        en: City/Ward
+    Address2:
+      displayName:
+        ja: 番地
+        en: Street Address
+    Address3:
+      nullable: true
+      placeholder:
+        ja: "マンション名・部屋番号（任意）"
+        en: "Apartment/Room (optional)"
+```
+
+##### JapaneseBankAccount Example
+
+```yaml
+bank:
+  type: JapaneseBankAccount
+  nullable: true
+  displayName:
+    ja: 銀行口座
+    en: Bank Account
+  fields:
+    BankCode:
+      nullable: true
+      # Format: 4-digit code (e.g., 0001)
+    BankName:
+      nullable: true
+    BranchCode:
+      nullable: true
+      # Format: 3-digit code (e.g., 001)
+    BranchName:
+      nullable: true
+    AccountType:
+      nullable: true
+      # Uses BankAccountType enum: 1(普通), 2(当座), 4(貯蓄)
+    AccountNumber:
+      nullable: true
+      # Format: 7-digit number
+    AccountHolder:
+      nullable: true
+      # Katakana only (e.g., ヤマダ タロウ)
+```
+
+#### Plugin Enums
+
+| Enum              | Description             | Values                                          |
+| ----------------- | ----------------------- | ----------------------------------------------- |
+| `Prefecture`      | 47 Japanese prefectures | `hokkaido`, `tokyo`, `osaka`, ... (string keys) |
+| `PrefectureCode`  | Prefecture JIS codes    | `1`-`47` (numeric)                              |
+| `BankAccountType` | Bank account types      | `1`=普通, `2`=当座, `4`=貯蓄                    |
 
 ### Association Type
-| Type | Description | Options |
-|------|-------------|---------|
-| `Association` | Relation | `relation`, `target`, `onDelete`, `mappedBy` |
+| Type          | Description | Options                                      |
+| ------------- | ----------- | -------------------------------------------- |
+| `Association` | Relation    | `relation`, `target`, `onDelete`, `mappedBy` |
 
 ## Property Options
 
+### All Property Options Reference
+
+| Option        | Type            | Default | Description                                  |
+| ------------- | --------------- | ------- | -------------------------------------------- |
+| `type`        | string          | -       | **Required.** Property type                  |
+| `displayName` | LocalizedString | -       | Human-readable label (i18n)                  |
+| `description` | LocalizedString | -       | Field description/help text (i18n)           |
+| `placeholder` | LocalizedString | -       | Form input placeholder (i18n)                |
+| `nullable`    | boolean         | `false` | Allow NULL in database                       |
+| `unique`      | boolean         | `false` | Unique constraint                            |
+| `default`     | any             | -       | Default value                                |
+| `primary`     | boolean         | `false` | Primary key (use with `options.id: false`)   |
+| `hidden`      | boolean         | `false` | Hide from API responses (Laravel: `$hidden`) |
+| `fillable`    | boolean         | `true`  | Mass assignable (Laravel: `$fillable`)       |
+| `renamedFrom` | string          | -       | Previous column name (for rename migrations) |
+| `length`      | number          | `255`   | VARCHAR length (String/Email/Password only)  |
+| `unsigned`    | boolean         | `false` | Unsigned number (numeric types only)         |
+| `precision`   | number          | `8`     | Total digits (Decimal only)                  |
+| `scale`       | number          | `2`     | Decimal places (Decimal only)                |
+| `rules`       | object          | -       | Validation rules (app-level, NOT database)   |
+| `fields`      | object          | -       | Per-field overrides (compound types only)    |
+
+### Example with All Options
+
 ```yaml
 properties:
   name:
     type: String
+    length: 100              # VARCHAR(100)
     displayName:
       ja: 名前
       en: Name
-    placeholder:             # Placeholder for form inputs (multi-language)
+    description:
+      ja: ユーザーの表示名
+      en: Display name for the user
+    placeholder:
       ja: 名前を入力
       en: Enter name
-      vi: Nhập tên
-    nullable: false          # Nullable (default: false)
-    unique: true             # Unique constraint
-    primary: true            # Primary key (use with options.id: false)
-    default: 'default'       # Default value
-    rules:                   # Validation rules (app-level, not DB)
-      required: true
-      maxLength: 255
+    nullable: false          # NOT NULL
+    unique: true             # UNIQUE constraint
+    default: 'Guest'         # Default value
+    rules:
+      required: true         # App-level validation
+      minLength: 2
+      maxLength: 100
+
+  password:
+    type: Password
+    hidden: true             # Auto-hidden for Password, but explicit is clearer
+    fillable: true           # Allow mass assignment
+
+  old_email:
+    type: Email
+    renamedFrom: email_address  # Rename migration from old column name
+
+  price:
+    type: Decimal
+    precision: 10            # Total 10 digits
+    scale: 2                 # 2 decimal places (e.g., 99999999.99)
+    unsigned: true           # Positive only
 ```
 
+### Validation Rules (App-level)
+
+```yaml
+rules:
+  required: true          # Field is required (form validation)
+  minLength: 2            # Minimum string length
+  maxLength: 255          # Maximum string length
+```
+
+**Note:** `rules` are for application/form validation only. They do NOT affect database structure. Use `nullable: false` for database-level NOT NULL constraint.
+
 ## Placeholder for Compound Types
 
 For compound types (like JapaneseName, JapaneseAddress), you can customize placeholders per field:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify",
-  "version": "1.0.100",
+  "version": "1.0.102",
   "description": "Schema-driven database migration system with TypeScript types and Laravel migrations",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,14 +25,14 @@
     "README.md"
   ],
   "dependencies": {
-    "@famgia/omnify-cli": "0.0.96",
-    "@famgia/omnify-core": "0.0.90",
-    "@famgia/omnify-typescript": "0.0.78",
-    "@famgia/omnify-types": "0.0.88",
-    "@famgia/omnify-laravel": "0.0.99",
-    "@famgia/omnify-atlas": "0.0.84",
-    "@famgia/omnify-mcp": "0.0.76",
-    "@famgia/omnify-japan": "0.0.83"
+    "@famgia/omnify-typescript": "0.0.80",
+    "@famgia/omnify-laravel": "0.0.101",
+    "@famgia/omnify-atlas": "0.0.86",
+    "@famgia/omnify-core": "0.0.92",
+    "@famgia/omnify-types": "0.0.90",
+    "@famgia/omnify-cli": "0.0.98",
+    "@famgia/omnify-japan": "0.0.85",
+    "@famgia/omnify-mcp": "0.0.78"
   },
   "keywords": [
     "omnify",