@g1cloud/bluesea 5.0.0-beta.8 → 6.0.0-alpha.0

package/skills/bluesea-ui/references/components.md

@@ -0,0 +1,196 @@
+# Bluesea components — detailed prop reference
+
+Use this as a prop lookup. When in doubt read the `.vue` file — the `defineProps<{...}>()` block is always the ground truth. v6 distributes components across packages: core, basic, input, grid, tree, richtext, global, frame. The canonical source is `packages/<package>/src/component/`.
+
+## Shared conventions
+
+Most inputs share this surface — only deltas are listed per component below.
+
+| Prop | Type | Notes |
+|---|---|---|
+| `v-model` | matches cell type | Two-way binding. |
+| `name` | `string` | Required for validation + SavePoint tracking. Auto-generated when omitted, but explicit names are easier to debug. |
+| `disabled` | `boolean` | Also disables validation unless `forceValidateWhenDisabled` is set. |
+| `required` | `boolean` | Enables built-in "required" rule. |
+| `viewMode` | `boolean` | Renders as read-only text (no `<input>`). |
+| `placeholder` | `MultiLangText` | |
+| `width` | CSS size string | Default `'200px'` on text/number inputs. |
+| `tabindex` | `number` | |
+| `hideErrorMessage` | `boolean` | Suppress the inline error `<span>`. |
+| `showErrorMessageOnDisabled` | `boolean` | Show errors even when disabled. |
+| `ignoreSavePoint` | `boolean` | Opt out of SavePoint "modified" tracking. |
+| `extraValidationRules` | `FieldValidationRule<T>[]` | Custom rules appended after built-ins. |
+| `validationMessage*` | `MultiLangText` | Overrides for each built-in rule's error message. |
+
+## Basic
+
+### BSButton (`basic/BSButton.vue`)
+Renders as `<button>`, `<a>`, or `<router-link>` depending on props.
+
+- `caption: string | MultiLangText`
+- `buttonColor: 'default' | 'blue' | 'red' | 'orange' | 'green' | 'gray' | 'underline'` (default `'default'`)
+- `leftIcon`, `rightIcon: string` — BSIcon name (not font-icon ligature; v6 uses SVG)
+- `disabled: boolean`
+- `linkUrl: string`, `linkTarget: string` — renders `<a>`
+- `routePath: string` — renders `<router-link :to>`
+- `tooltip: MultiLangText`
+
+### BSIcon (`basic/BSIcon.vue`)
+Material Symbols SVG replacement for the old icon font.
+
+- `name: string` — Material Symbol name (e.g. `'check'`, `'delete'`, `'edit'`)
+- `filled: boolean` (default `false`)
+- Size via Tailwind classes on the parent or custom CSS
+
+### BSFormLabel (`basic/BSFormLabel.vue`)
+- `label: MultiLangText`
+- `required: boolean`
+- `tooltip: MultiLangText`
+
+### BSLink, BSImage, BSPopup, BSPopupButton, BSProgressBar, BSLoadingIcon, BSDate, BSCalendar, BSCalendarRange, BSPageNavigation, BSConsole
+Read the individual files — they are short and each has a targeted purpose.
+
+## Text / number / money
+
+### BSTextInput (`input/BSTextInput.vue`)
+`v-model` is `string`.
+
+- `inputType: 'text' | 'password'`
+- `maxlength: number` — HTML attribute
+- `minLength: number`, `maxLength: number` — validation rules
+- `regExp: string`
+- `trimValue: boolean` (default `true`) — trims before emit
+- `prefix`, `suffix: MultiLangText | MultiLangText[] | PrefixSuffix | PrefixSuffix[]` — decoration in the input border
+- `autocomplete: string`
+
+### BSNumberInput, BSPriceInput, BSPercentInput (`input/BSNumberInput.vue`, etc.)
+`v-model` is `number | undefined`.
+
+- `minValue`, `maxValue: number`
+- `decimalPlace: number`
+- `thousandSeparator: boolean`
+- `unit: MultiLangText` — e.g. `'원'`, `'%'`
+- `currencyCode: CurrencyCode` — on `BSPriceInput`; falls back to `useBlueseaConfig().defaultCurrencyCode`
+
+### BSTextArea (`input/BSTextArea.vue`)
+`v-model` is `string`. Adds `rows: number`, `autoResize: boolean`.
+
+### BSColorInput (`input/BSColorInput.vue`)
+`v-model` is a hex string like `'#RRGGBB'`.
+
+## Date / time
+
+### BSDateInput, BSDateRange (`input/BSDateInput.vue`, `BSDateRange.vue`)
+`v-model` is an ISO string (`dayjs`-parseable).
+
+- `dateFormat: string` — dayjs format; falls back to `useBlueseaConfig().dateFormat`
+- `timeZone: TimeZone` — falls back to `useBlueseaConfig().timeZone`
+- `resolution: DateResolution` — `'DAY' | 'HOUR' | 'MINUTE' | 'MINUTE_10' | 'MINUTE_30' | 'SECOND'`
+- `minValue`, `maxValue: string` — ISO bounds
+
+Range version emits two values via `v-model:from` / `v-model:to`, or via a `DateRange` object depending on flavor; check the component.
+
+### BSCalendar, BSCalendarRange
+Embedded calendars; useful inside custom popups. (Moved from basic to input in v6.)
+
+## Selection
+
+### BSSelect (`input/BSSelect.vue`)
+Generic: `<BSSelect :items="items" :key-provider="..." :label-provider="..." />`.
+
+- `items: T[]`
+- `keyProvider: (item: T) => string | undefined`
+- `labelProvider: (item: T) => MultiLangText | undefined`
+- `iconProvider`, `tooltipProvider`, `enabledItemProvider`
+- `allowEmpty: boolean`, `emptyLabel: MultiLangText`
+- `filterable: boolean` — show search box in popup
+
+### BSMultiSelect, BSTreeSelect, BSTreeMultiSelect, BSPopupSelect
+Same general shape; multi-select uses `Set<T>` or `T[]`. `BSTreeSelect` / `BSTreeMultiSelect` moved to tree package in v6.
+
+### BSCheckbox, BSCheckboxGroup, BSRadioButton, BSRadioButtonGroup, BSYesNoSelect, BSYesNoGroup
+Check the `defineProps` block; `items` + `keyProvider` + `labelProvider` pattern is consistent.
+
+## Upload
+
+### BSImageUpload (`input/BSImageUpload.vue`), BSFileUpload, BSMultiImageUpload, BSPositionedImageUpload
+`v-model` is `StoredFile | StoredFile[]`.
+
+Key props:
+- `maxFileSize: number` (falls back to `useBlueseaConfig().maxFileSize`)
+- `accept: string` — mime filter
+- `preloadOverlay: boolean` — preload preview overlay image
+- Upload handlers come from your backend; Bluesea itself doesn't own the upload URL. You store the resulting URL on the `StoredFile.fileUrl` when the upload succeeds.
+
+## Multi-language inputs
+
+`BSMultiLangTextInput`, `BSMultiLangTextArea`, `BSMultiLangRichText`, `BSMultiLangHtmlEditor`, `BSMultiLangImageUpload` wrap their single-language counterparts and bind to a `MultiLangString` (or `MultiLangStoredFile`) keyed by `dataLocales` from config. They render one input per locale with a language selector.
+
+## Rich text / code
+
+### BSRichText (`richtext/BSRichText.vue`)
+TipTap-based WYSIWYG.
+
+- `v-model` — HTML string
+- `toolButtons: ToolButton[]` — subset of `'Heading' | 'FontSize' | 'FontColor' | 'FontStyle' | 'TextAlign' | 'ListItem' | 'Link' | 'Table' | 'Image' | 'Video' | 'Youtube'`
+- `imageInsertModal`, `videoInsertModal: Component` — override default modals
+
+### BSHtmlEditor (`richtext/BSHtmlEditor.vue`)
+Split view (source + preview) for raw HTML.
+
+### BSCodeEditor (`input/BSCodeEditor.vue`)
+CodeMirror 6 — props `language`, `theme`, `readonly`.
+
+## Layout
+
+### BSCardLayout (`basic/BSCardLayout.vue`)
+Container with header/footer slots.
+
+### BSListLayout + BSListControl (`basic/BSListLayout.vue`)
+Master-detail layout with resizable panes.
+
+### BSTabSheet (`basic/BSTabSheet.vue`)
+Manages tabs, provides a SavePoint to each tab. Config toggles `blockLeavingModifiedTab` / `confirmLeavingModifiedTab` via `createBluesea` options.
+
+### BSHorizontalLayoutResizer, BSVerticalLayoutResizer
+Drag-to-resize between two DOM siblings.
+
+## Tree
+
+### BSTree (`tree/BSTree.vue`)
+- `items: T[]`, `childrenProvider: (item: T) => T[] | undefined`
+- `keyProvider`, `labelProvider`, `iconProvider`
+- `draggable: boolean`
+- `selection: Set<T>` via `v-model:selected`
+- Scoped slot `#item="{ item }"` to customise rendering
+
+### BSTreeControl
+Toolbar for BSTree (add / remove / expand-all).
+
+## Global entity inputs (in global package)
+
+### BSNameInput, BSTelInput, BSAddressInput
+Bind to `Name`, `Tel`, `Address` models. Layout comes from `createBluesea({ extended: { componentConfig: { nameInput: {...}, ... } } })`, so configure once globally.
+
+### BSLocaleSelect
+Dropdown that switches `useBlueseaConfig().currentLocale`. Handy for a language toggle in the header.
+
+## Popup
+
+### BSPopup, BSPopupButton, BSSelectPopup, BSDateInputPopup, BSDateRangeInputPopup
+The popup system anchors a component to a target element. `BSPopup` is the low-level primitive — pass `target`, `open`, `position`. Most selection components already wrap `BSPopup` internally; reach for it yourself only for custom pickers.
+
+## Grid
+
+See `references/grid.md`. Top-level exports: `BSGrid`, `BSGridLookup`, `BSGridControl`, plus types `Column`, `EditingRows`, `PageGridHandler`, `createPageGridHandler`.
+
+## Notification / modal / context menu containers
+
+- `BSModalContainer` — mount once; the modal system renders into it.
+- `BSNotificationContainer` — mount once; drives notifications and alarms.
+- `BSContextMenuContainer` — mount once; the context-menu system renders into it.
+
+## Frame
+
+- `DefaultHeader`, `DefaultBody` — BackOffice app shell.
+- `BSAlarmFrame` — standalone alarm container if you don't use DefaultFrame.

package/skills/bluesea-ui/references/grid.md

@@ -0,0 +1,159 @@
+# BSGrid deep-dive
+
+BSGrid is the highest-surface-area component in Bluesea. This reference covers the parts you won't guess from prop names: the `createPageGridHandler` factory, lookup/filter wiring, inline editing, column preferences, extensions, and Excel export. For quick starts use the `BSGridGuide.vue` demo and the snippet in the main SKILL.md.
+
+## When to use which wiring
+
+| Scenario | Use |
+|---|---|
+| Client-side, fixed data, no paging | `<BSGrid :columns :data />` directly. |
+| Server-side paging + sorting | `createPageGridHandler(option)` and bind its `grid`, `gridEventListener`, `control`, `controlEventListener`, `lookup`, `lookupEventListener` to `BSGrid`, `BSGridControl`, `BSGridLookup`. |
+| Inline add/remove/edit | `createPageGridHandler({ editable: true, ... })` or pass `:editing-rows` + `#<prop>.edit` slots manually. |
+
+## `createPageGridHandler` option
+
+From `packages/grid/src/`:
+
+```ts
+createPageGridHandler<T>({
+  gridId: string,          // used by gridPreferenceStore; omit to opt out of persistence
+  editable: boolean,
+  getRowKey: (row: T) => string,
+  newRowCreator: () => T | undefined,  // when editable
+  addRowToLast: boolean,               // default false — new rows go to top
+  removeRowHandler: (rows: Set<T>) => boolean,  // return true if you handle deletion yourself
+  isRowEditable: (row, editingRows) => boolean,
+  isRowSelectable: (row) => boolean,
+  getGridData: (param: SearchParam) => PaginatedList<T> | Promise<PaginatedList<T>>,
+  limit: number,                       // default 100
+  limitItems: number[],                // default [100, 300, 500]
+  defaultFilter: Filter[],
+  defaultSorts: Sort[],
+})
+```
+
+`SearchParam` carries `offset`, `limit`, `sorts`, `defaultFilter`, `lookupFilter`, `gridFilter`. `PaginatedList<T>` is `{ offset, totalCount, data: T[] }`. Return these from your API.
+
+Call `handler.loadGridData()` once after setup to populate. Afterwards, Bluesea refreshes on sort/limit/offset/filter changes automatically via `gridEventListener` / `controlEventListener` / `lookupEventListener`.
+
+## Column definition
+
+```ts
+type Column<T> = {
+  propertyId: string            // key into row data
+  templateId?: string           // slot name override (defaults to propertyId)
+  caption: MultiLangText
+  cellType?: 'TEXT' | 'NUMBER' | 'DATE' | 'PERCENTAGE' | 'BOOL' | 'MULTI_LANG_STRING' | 'NAME' | 'TEL' | 'ADDRESS' | 'MONEY'
+  dateFormat?: string | 'DAY' | 'MINUTE' | 'SECOND'
+  width?: number
+  sortable?: boolean
+  sortPropertyId?: string       // if sort key ≠ display key
+  cellStyleClass?: string
+  cellStyleCss?: string
+  headerCellStyleClass?: string
+  headerCellStyleCss?: string
+  tooltipProvider?: (row: T) => MultiLangText | undefined
+}
+```
+
+`cellType` gives you free formatting. `MULTI_LANG_STRING` picks the current data locale; `MONEY` uses the configured `moneySerializer`. Override any cell by defining a `#<propertyId>` slot.
+
+## Slots
+
+| Slot | Purpose |
+|---|---|
+| `#<propertyId>="{ row }"` | Display cell |
+| `#<propertyId>.edit="{ row }"` | Editor cell (when row is in `editingRows`) |
+| `#<propertyId>.filter="{ ... }"` | Header filter cell |
+| `#emptyMessage` | Shown when `data.length === 0` |
+
+Slot names come from `propertyId` (or `templateId` when provided). You can mix — only override the columns you need.
+
+## Inline editing lifecycle
+
+```
+user clicks edit icon
+  → gridEventListener.changeEditingRow(row, true)
+  → handler adds row to editingRows
+  → #propertyId.edit slot renders for that row, with a BSTextInput/BSNumberInput etc.
+  → SavePoint on the row tracks modified state
+user clicks save/cancel
+  → you validate, call editingRows.removeRow(row) + savePoint.set() or rollback()
+```
+
+`EditingRows<T>` supports `addRow`, `removeRow`, `getModifiedRows`, `getRows`. You usually pass an instance into `BSGrid :editing-rows="..."`.
+
+## Filter (BSGridLookup)
+
+`BSGridLookup` renders above the grid as the "search bar". Its config shape:
+
+```ts
+type GridLookupConfig = {
+  textFilter?: {
+    filterItems: Array<{
+      propertyId: string
+      caption: MultiLangText
+      prefix?: boolean   // wrap keyword with leading %  (default true)
+      suffix?: boolean   // trailing %                   (default true)
+      filterCreator?: TextFilterCreator   // custom filter builder
+      filterType?: 'STRING' | 'NUMBER'
+    }>
+  }
+  dateFilter?: {
+    filterItems: Array<{
+      propertyId: string
+      caption: MultiLangText
+      timeZone?: TimeZone
+      dateFormat?: string
+      popupDateFormat?: string
+      filterWidth?: string
+    }>
+  }
+}
+```
+
+For an "embedded Name" column that should search across `name.name1..4`, use the built-in `nameFilterCreator(maxIndex)`:
+
+```ts
+import { nameFilterCreator } from '@g1cloud/bluesea'
+filterItems: [{ propertyId: 'memberName', caption: '회원명', filterCreator: nameFilterCreator() }]
+```
+
+## GridFilter (header-level per-column filter)
+
+Separate from Lookup — this is the popup that appears from column headers. Enable with `<BSTextFilter>` / `<BSDateRangeFilter>` / `<BSDateRangeFilters>` in the `#<propertyId>.filter` slot. They emit filters that feed back into `searchParam.gridFilter`.
+
+## Column preferences
+
+If you pass `gridId` and install a `gridPreferenceStore` in `createBluesea({ extended: { gridPreferenceStore: ... } })`, Bluesea persists column widths, order, hidden flags, and the last `dateFilter` per gridId. `LocalStorageGridPreferenceStore` is the canonical implementation. Implement the `GridPreferenceStore` interface to back it with something else (cloud user prefs, etc.).
+
+## Extensions
+
+`GridExtension` lets external packages inject cell renderers, row actions, toolbar buttons. The canonical example is `gridExcelDownloadExtension` (from grid package) which adds an Excel-export button to `BSGridControl`. Import and pass via the `extensions` prop.
+
+```ts
+import { BSGrid, BSGridControl, gridExcelDownloadExtension } from '@g1cloud/bluesea'
+
+const extensions = [gridExcelDownloadExtension({
+  fileName: 'users.xlsx',
+  getRows: async () => (await api.users.searchAll(searchParam)).data,
+})]
+```
+
+## Fixed columns
+
+`fixedColumnCount: number` on `GridBinding` freezes the first N columns during horizontal scroll. The user can also drag a divider to change it live — bind `settingChanged` on `gridEventListener` to persist.
+
+## Row display/select policy
+
+- `rowDisplayPolicy: (row) => boolean` — hide specific rows client-side
+- `rowSelectPolicy: (row) => boolean` — disable checkbox for specific rows
+- `rowEditPolicy: (row, editingRows) => boolean` — per-row editability (also `option.isRowEditable` on the handler)
+
+## Common mistakes
+
+- Forgetting to call `await gridHandler.loadGridData()` after setup — grid stays empty.
+- Passing `defaultSorts` and expecting them to show as active sort chevrons; defaults are **appended** to user sorts in the query, not shown in the header.
+- Using `propertyId: 'a.b'` for nested data — valid, but cells look up with dot-notation. Be sure `b` exists.
+- Forgetting that `editingRows` must be the same reactive instance across parent/child; the handler already creates one, so use `gridHandler.grid.editingRows`.
+- Overriding `#<prop>` slot and forgetting `.edit` variant — result: edit cells fall back to the default text display.

package/skills/bluesea-ui/references/i18n.md

@@ -0,0 +1,149 @@
+# i18n and MultiLangText
+
+Bluesea treats every user-visible text prop as potentially multi-lingual. Understanding `MultiLangText` and the `useTexts()` composable up front prevents 90% of "caption is showing `{ key: 'xxx' }`" mistakes.
+
+## The `MultiLangText` union
+
+```ts
+type LocaleName = string   // e.g. 'ko', 'en', 'ja', 'ko-KR'
+
+type MultiLangString  = Record<LocaleName, string>             // { ko: '저장', en: 'Save' }
+type MultiLangMessage = { key: string; args?: unknown[]; locale?: LocaleName }
+
+type MultiLangText =
+  | string
+  | MultiLangString
+  | MultiLangMessage
+```
+
+Bluesea uses these rules to render:
+
+1. If it's a plain string, use it as-is.
+2. If it's an object with `key`, look the key up in the `I18NTexts` registry for the current locale and substitute `args`.
+3. Otherwise, treat it as per-locale map and pick `currentLocale` (with fallbacks).
+
+You detect `MultiLangMessage` by the presence of a `key` property; `isMultiLangMessage(text)` does this check.
+
+## Registering texts
+
+v6 uses composables instead of module-scope singletons. Get the `useTexts()` composable and call methods on it:
+
+```ts
+import { useTexts } from '@g1cloud/bluesea'
+
+const { addTexts } = useTexts()
+
+addTexts('ko', [
+  { key: 'btn.save',        text: '저장' },
+  { key: 'err.required',    text: '필수 입력 항목입니다.' },
+  { key: 'msg.saved',       text: '{0} 개가 저장되었습니다.' },    // {0} {1} for args
+  { key: 'help.html',       text: '<strong>주의</strong>',  html: true },
+])
+
+addTexts('en', [
+  { key: 'btn.save',        text: 'Save' },
+  { key: 'err.required',    text: 'This field is required.' },
+  { key: 'msg.saved',       text: '{0} items saved.' },
+])
+```
+
+### Compact JSON format
+
+For large catalogues, `addTexts` also accepts a compact object form so the JSON file stays small. Same call — the runtime detects the shape via `Array.isArray`:
+
+```ts
+const { addTexts } = useTexts()
+
+addTexts('ko', {
+  'btn.save':  '저장',                                  // plain text
+  'help.html': ['<strong>주의</strong>', 1],            // array → html: true
+})
+```
+
+- value is a **string** → equivalent to `{ key, text, html: false }`
+- value is `[text, 1]` (any truthy second element) → equivalent to `{ key, text, html: true }`
+
+The shipped `@g1cloud/bluesea/text/bluesea_text_*.json` files use this compact format. Both formats can be mixed for the same locale; later calls overwrite earlier keys.
+
+For real apps, store texts in `texts_ko.json` / `texts_en.json` and run the message generator. The generator produces type-safe key constants.
+
+Locale fallback chain: `currentLocale` → parent locale (`ko-KR` → `ko`) → `defaultLocale`. If no match, the key itself is returned — that is what "unresolved" text looks like in the UI.
+
+## Looking up at runtime
+
+```ts
+import { useTexts } from '@g1cloud/bluesea'
+
+const { t, interpretMultiLangText } = useTexts()
+
+const msg = t({ key: 'msg.saved', args: [3] })   // → '3 items saved.' (in en)
+
+// Generic interpreter that accepts any MultiLangText
+const label = interpretMultiLangText({ ko: '저장', en: 'Save' })
+```
+
+## Templates: interpolation instead of v-t
+
+v5 used the `v-t` directive, which relied on DOM manipulation and doesn't work in SSR. v6 removes it — use `{{ t(...) }}` interpolation instead:
+
+```vue
+<span>{{ t({ key: 'btn.save' }) }}</span>
+<input :placeholder="t({ key: 'ph.name' })" />
+<img :alt="t({ key: 'alt.logo' })" />
+```
+
+When you have an HTML string to render, get it via `tr()` (text-render, returns HTML):
+
+```ts
+const { tr } = useTexts()
+const htmlMsg = tr({ key: 'help.html' })   // if registered with html: true
+```
+
+And render with `v-html`:
+
+```vue
+<div v-html="htmlMsg"></div>
+```
+
+## Switching locale
+
+v6 uses composables to access config:
+
+```ts
+import { useBlueseaConfig } from '@g1cloud/bluesea'
+
+const { setCurrentLocale, setCurrentDataLocale } = useBlueseaConfig()
+setCurrentLocale('en')       // UI locale
+setCurrentDataLocale('en')   // BSMultiLang* pickers
+```
+
+There is also `<BSLocaleSelect>` for a ready-made dropdown in the header.
+
+## Data locale vs UI locale
+
+Bluesea separates two concerns:
+
+- `currentLocale` / `locales` — which language the **chrome** renders in (labels, buttons, errors).
+- `currentDataLocale` / `dataLocales` — which language the **data** is authored in, used by `BSMultiLang*` inputs (e.g. editing product name in `ko`, `en`, `ja`).
+
+You can run the UI in Korean while editing English-only content, or vice versa. Most apps set both the same for end users but expose a separate data-locale toggle in admin tools.
+
+## `MultiLangString` in data models
+
+When a DB field is multilingual, model it as `MultiLangString` and render it with `cellType: 'MULTI_LANG_STRING'` in grids or `<BSMultiLangTextInput>` in forms. Bluesea picks the `currentDataLocale` with the same fallback chain.
+
+```ts
+type Product = {
+  id: string
+  name: MultiLangString      // { ko: '양말', en: 'Socks', ja: '靴下' }
+  description: MultiLangString
+}
+```
+
+## Common mistakes
+
+- Hard-coding Korean strings in a library component and wondering why they don't switch locale — wrap them as `{ key: '...' }` and register for each locale.
+- Using `interpretMultiLangText` inside a `computed` and expecting it not to re-run when locale changes — it does, because the composable is reactive.
+- Passing a key that doesn't exist — the key itself leaks into the UI. Check your text files or run the message generator.
+- Using `{{ t(...) }}` without importing `useTexts()` — you get an undefined reference. Do it at the top of `<script setup>`.
+- Storing `{ key: '...' }` in the database. Keys are UI concerns; database data should be `MultiLangString` values.

package/skills/bluesea-ui/references/validation.md

@@ -0,0 +1,178 @@
+# Validation in Bluesea
+
+Bluesea's validation is deliberately unusual. Instead of wiring a validator per field, inputs *register themselves* on their DOM element. A `FormValidator` then walks the DOM tree inside a root element, finds every registered `FieldValidator`, runs them, and collects errors. This means you rarely touch `FieldValidator` directly — just give each input a `name` and scope a `FormValidator` to the form root.
+
+## Types at a glance
+
+```ts
+type ValidationPhase = 'input' | 'change' | 'blur' | 'form'
+
+type ValidationError = {
+  code: string
+  message: MultiLangText
+}
+
+type FieldValidationRule<T> = (
+  value: T,
+  phase: ValidationPhase,
+  fieldContext?: FieldContext<any>,
+) => Promise<ValidationError[] | undefined> | ValidationError[] | undefined
+
+type FormValidationError = ValidationError & { name?: string }
+
+type FormValidationRule = (phase?: ValidationPhase) => Promise<FormValidationError[] | undefined>
+
+class ValidationFailedError {
+  constructor(public errors: FormValidationError[]) {}
+}
+```
+
+## Standard form flow
+
+```vue
+<template>
+  <div ref="formEl">
+    <BSTextInput v-model="form.name"  name="name"  required :max-length="50" />
+    <BSTextInput v-model="form.email" name="email" required reg-exp="^[^@]+@[^@]+$" />
+    <BSNumberInput v-model="form.age" name="age"   :min-value="0" :max-value="150" />
+    <BSButton caption="저장" @click="save" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { formValidator, isValidationFailedError } from '@g1cloud/bluesea'
+import { useNotification } from '@g1cloud/bluesea'
+
+const formEl = ref<HTMLElement>()
+const form = ref({ name: '', email: '', age: 0 })
+const { showNotification } = useNotification()
+
+const validator = formValidator({
+  element: formEl,
+  rules: [
+    // form-level cross-field rule
+    async () => form.value.age < 18 && form.value.name.includes('kid')
+      ? [{ code: 'ageMismatch', message: { key: 'err.ageMismatch' } }]
+      : undefined,
+  ],
+})
+
+async function save() {
+  try {
+    await validator.validate()  // throws on failure
+    await api.save(form.value)
+    showNotification({ key: 'msg.saved' }, 'info')
+  } catch (e) {
+    if (isValidationFailedError(e)) {
+      showNotification({ key: 'err.validationFailed' }, 'error')
+      return
+    }
+    throw e
+  }
+}
+</script>
+```
+
+`validate()` throws `ValidationFailedError` with the full error list. `validationResult()` returns the errors without throwing, which is handy for custom UI (e.g. show a summary banner).
+
+## Built-in field rules per input
+
+Built-in rules are configured via props on each input. Each has a companion `validationMessage*` prop to override the default message.
+
+| Rule | Inputs | Props |
+|---|---|---|
+| required | All input components | `required`, `validationMessageRequired` |
+| length | `BSTextInput`, `BSTextArea` | `minLength`, `maxLength`, `validationMessageMinLength`, `validationMessageMaxLength`, `validationMessageBetweenLength` |
+| regexp | `BSTextInput` | `regExp`, `validationMessageRegExp` |
+| numeric range | `BSNumberInput`, `BSPriceInput`, `BSPercentInput` | `minValue`, `maxValue`, `validationMessageMinValue`, `validationMessageMaxValue`, `validationMessageBetweenValue` |
+| date order | `BSDateRange` | auto; override `validationMessageDateOrder` |
+| date bounds | `BSDateInput`, `BSDateRange` | `minValue`, `maxValue` |
+| file size / count | `BSFileUpload`, `BS*ImageUpload` | `maxFileSize`, `maxFileCount` |
+
+Default error messages are i18n keys like `bs.error.validation.required`, `bs.error.validation.lengthMin`, so translations come "for free" if you registered Bluesea's text files.
+
+## Custom field rules (`extraValidationRules`)
+
+When built-ins aren't enough, pass `:extra-validation-rules` — an array of functions. Each returns `ValidationError[]` (or empty / undefined for "ok"). Phase control lets you defer expensive checks.
+
+```ts
+import type { FieldValidationRule } from '@g1cloud/bluesea'
+
+const uniqueEmail: FieldValidationRule<string> = async (value, phase) => {
+  if (!value || phase === 'input') return  // run on blur / form only
+  const exists = await api.users.exists(value)
+  return exists ? [{ code: 'duplicate', message: { key: 'err.emailTaken' } }] : undefined
+}
+
+// in template
+<BSTextInput v-model="form.email" name="email" required
+             :extra-validation-rules="[uniqueEmail]" />
+```
+
+Rules of thumb:
+- Use `phase === 'form'` to skip expensive work on keystrokes.
+- Return `undefined` for "pass"; return an empty array also passes, but `undefined` is clearer.
+- Throw *inside* rules sparingly — the validator does not convert thrown errors into nice messages.
+
+## Form-level rules
+
+Cross-field rules go in `formValidator({ rules: [...] })`. They receive the phase but no value; you read your reactive state directly.
+
+```ts
+formValidator({
+  element: formEl,
+  rules: [
+    async () => form.value.password !== form.value.passwordConfirm
+      ? [{ name: 'passwordConfirm', code: 'mismatch', message: { key: 'err.pwMismatch' } }]
+      : undefined,
+  ],
+})
+```
+
+The `name` on the error aligns the failure with a specific input so `validator.getFieldValidator(name)` can jump to it.
+
+## Talking to individual FieldValidators
+
+Rarely needed, but when you want to trigger validation imperatively:
+
+```ts
+import { validateField, validateFields } from '@g1cloud/bluesea'
+
+await validateField('email')       // by name
+await validateFields(['email', 'age'])
+await validator.getFieldValidator('email')?.validate('blur')
+```
+
+Clearing errors (e.g. on `cancel`):
+
+```ts
+validator.clear()
+```
+
+## Async rules and the "disabled" gotcha
+
+If a field is `disabled`, its validator short-circuits to valid. Pass `:force-validate-when-disabled="true"` only when you really need validation despite the disabled state (rare — usually disabled means "field is derived / not user-editable").
+
+For conditionally-disabled rules, prefer returning `undefined` early rather than toggling `disabled`, because `disabled` also skips the built-in rules.
+
+## FieldContext
+
+A `FieldContext<T>` is injected when a field is rendered inside a grid editor. It gives the rule access to `row`, sibling values, and the editingRows collection. Use it when one cell's validity depends on another cell in the same row.
+
+```ts
+const priceMustExceedCost: FieldValidationRule<number> = (price, _phase, ctx) => {
+  const row = ctx?.row as { cost?: number } | undefined
+  return (row && price !== undefined && row.cost !== undefined && price < row.cost)
+    ? [{ code: 'priceLtCost', message: { key: 'err.priceLtCost' } }]
+    : undefined
+}
+```
+
+## Common mistakes
+
+- Forgetting `name` on an input — the validator still runs, but `error.name` is empty, so "jump to error" UX breaks.
+- Wrapping the `ref` target with `v-if` that unmounts on error — the error clears because the validator is unregistered. Prefer `:disabled` or `:view-mode` to hide without unmounting.
+- Calling `validator.validate()` from a plain synchronous handler — it's async. `await` it.
+- Using `throw new Error(...)` in a rule. Return `[{ code, message }]` instead.
+- Re-creating `formValidator` on every render; create it once in `<script setup>` at module scope.