@g1cloud/bluesea 5.0.0-beta.26 → 5.0.0-beta.28

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 `PageGridHandler` 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/bluesea/src/component/grid/GridModel.ts`:
+
+```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 `configureBluesea`, 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 `@/component/grid/extension/gridExcelDownloadExtension`) 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,126 @@
+# i18n and MultiLangText
+
+Bluesea treats every user-visible text prop as potentially multi-lingual. Understanding `MultiLangText` and the `i18n` helper 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
+
+```ts
+import { i18n } from '@g1cloud/bluesea'
+
+i18n.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 },
+])
+
+i18n.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
+i18n.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 (`pnpm generate-message` in bluesea-demo). 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 { t, interpretMultiLangText } from '@g1cloud/bluesea'
+
+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' })
+```
+
+## The `v-t` directive
+
+Register once (`app.directive('t', vT)`), then use it anywhere you'd hard-code text. It sets `textContent` by default; pass a modifier to target a different attribute.
+
+```vue
+<span v-t="{ key: 'btn.save' }" />
+<input v-t.placeholder="{ key: 'ph.name' }" />
+<img v-t.alt="{ key: 'alt.logo' }" />
+```
+
+The directive is reactive — switching `blueseaConfig.currentLocale` updates all bound elements.
+
+## Switching locale
+
+```ts
+import { blueseaConfig } from '@g1cloud/bluesea'
+blueseaConfig.setCurrentLocale('en')       // UI locale
+blueseaConfig.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 `blueseaConfig` 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.
+- Forgetting to register `v-t` globally and then using `v-t="..."` — the directive silently does nothing.
+- 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,176 @@
+# 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, showNotification } from '@g1cloud/bluesea'
+
+const formEl = ref<HTMLElement>()
+const form = ref({ name: '', email: '', age: 0 })
+
+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' })
+  } 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>` (from `@/model/FieldContext`) 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.