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

package/dist/text/i18n.d.ts

@@ -6,9 +6,10 @@ export type TextRecord = {
 export type ResolvedTextRecord = TextRecord & {
     resolved: boolean;
 };
+export type CompactTexts = Record<string, string | (string | number)[]>;
 export declare class I18NTexts {
     private localeTexts;
-    addTexts(locale: string, textList: TextRecord[]): void;
+    addTexts(locale: string, input: TextRecord[] | CompactTexts): void;
     /**
      * 현재 언어코드에서 `key` 에 해당하는 `TextRecord` 를 리턴한다.
      * @param key

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@g1cloud/bluesea",
   "private": false,
-  "version": "5.0.0-beta.26",
+  "version": "5.0.0-beta.28",
   "description": "Ui Library for g1cloud BackOffice.",
   "type": "module",
   "engines": {
@@ -14,11 +14,16 @@
     "css",
     "scss",
     "text",
+    "skills",
+    "bin",
     "!dist/tests"
   ],
   "module": "dist/bluesea.js",
   "main": "dist/bluesea.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "bluesea-install-skill": "./bin/install-claude-skill.mjs"
+  },
   "dependencies": {
     "@codemirror/lang-css": "^6.2.1",
     "@codemirror/lang-html": "^6.4.9",

package/skills/bluesea-ui/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: bluesea-ui
+description: How to build g1cloud BackOffice UIs with the @g1cloud/bluesea Vue 3 component library — covers app bootstrap (configureBluesea, plugins), BS* components (BSButton, BSTextInput, BSGrid, BSSelect, BSModal, etc.), the FieldValidator/FormValidator pattern, useModal / showNotification, MultiLangText + i18n, SavePoint for inline edits, and the DefaultFrame shell. Use this skill whenever the user works in a project that imports from "@g1cloud/bluesea" or mentions any BS* component, BSGrid, BSModal, configureBluesea, useModal, MultiLangText, FieldValidator, formValidator, ValidationFailedError, SavePoint, or DefaultFrame — even when they only show a Vue snippet without naming the library. Also apply when the user asks about Bluesea, 블루씨, g1cloud BackOffice UI, or pastes code using <BSButton>, <BSTextInput>, <BSGrid>, etc.
+---
+
+# @g1cloud/bluesea — Vue 3 UI library for g1cloud BackOffice
+
+Bluesea is an enterprise-focused Vue 3 component library. Its design goals shape every API in this skill, so read them first — the patterns that look unusual usually follow from here:
+
+- **Strict types.** Every component has explicit prop types. Prefer `<script setup lang="ts">` with `defineProps<{...}>()`. Don't invent loose props.
+- **Unidirectional data flow.** Props down, `update:xxx` events up. Two-way binding is always `v-model:xxx`.
+- **i18n-first.** Almost every text prop (caption, placeholder, tooltip, error message) accepts `MultiLangText`, not just `string`. See "MultiLangText" below.
+- **Inversion of control.** Components expose scoped slots + plugin/extension hooks. Don't fork the component — fill the slot or pass an extension.
+- **Validation is a first-class concern.** Inputs register themselves with a `FormValidator`. Submit handlers throw `ValidationFailedError`. See "Validation".
+
+When you are unsure about a component's props, read the `.vue` file directly at `packages/bluesea/src/component/<group>/<Name>.vue` — the `defineProps<{...}>()` block is the source of truth. This is faster and more reliable than guessing.
+
+## 1. Project bootstrap
+
+Every Bluesea app calls `configureBluesea(...)` before `createApp(...).mount(...)`, and installs the modal / notification / context-menu plugins that the library depends on. A realistic `main.ts` looks like this (trim to what you need):
+
+```ts
+import { createApp } from 'vue'
+import '@g1cloud/bluesea/css/bluesea.css'
+import '@g1cloud/bluesea/css/frame-default.css' // only if you use DefaultFrame
+import {
+  configureBluesea,
+  createModalPlugin,
+  createContextMenuPlugin,
+  LocalStorageGridPreferenceStore,
+  vT,
+} from '@g1cloud/bluesea'
+import App from './App.vue'
+
+configureBluesea({
+  locales: ['ko', 'en', 'ja'],
+  defaultLocale: 'ko',
+  currentLocale: 'ko',
+  dataLocales: ['ko', 'en', 'ja'],    // used by BSMultiLang* inputs
+  currentDataLocale: 'ko',
+  timeZone: 'Asia/Seoul',
+  dateFormat: 'YYYY-MM-DD HH:mm',
+  defaultCurrencyCode: 'KRW',
+  gridPreferenceStore: new LocalStorageGridPreferenceStore(), // persists BSGrid column widths/order
+  fileUrlResolver: (url) => url?.startsWith('http') ? url : `https://cdn.example.com/${url}`,
+  componentConfig: {
+    telInput:    { requiredCountryNo: true, countries: [{ code: 'KR', name: 'Korea (+82)' }] },
+    addressInput:{ countries: [{ code: 'KR', name: 'Korea' }] },
+    calendar:    { startYear: '-40', endYear: '+40' }, // relative to this year
+  },
+})
+
+createApp(App)
+  .use(createModalPlugin())
+  .use(createContextMenuPlugin())
+  // BSNotificationContainer does not need a plugin — just mount it once (see §4)
+  .directive('t', vT) // enables v-t="multiLangText"
+  .mount('#app')
+```
+
+Global state lives on the reactive `blueseaConfig` object; call `blueseaConfig.setCurrentLocale('en')` to switch language at runtime and every `v-t` / caption updates.
+
+You must also mount the container components somewhere near the app root — they are the portals the plugins render into:
+
+```vue
+<template>
+  <router-view />
+  <BSModalContainer />
+  <BSNotificationContainer />
+  <BSContextMenuContainer />
+</template>
+```
+
+## 2. MultiLangText (almost every text prop)
+
+`MultiLangText` is the union that lets captions be either a plain string, a per-locale record, or an i18n key with args:
+
+```ts
+type MultiLangText =
+  | string                                   // plain — 'Save'
+  | Record<LocaleName, string>               // per-locale — { ko: '저장', en: 'Save' }
+  | { key: string; args?: unknown[] }        // i18n key — { key: 'btn.save' }
+```
+
+Use i18n keys by default in real apps so the UI follows the user's locale. Register texts with `i18n.addTexts(locale, [...])` and render them with the `v-t` directive or the `t()` helper:
+
+```ts
+import { i18n, t, interpretMultiLangText } from '@g1cloud/bluesea'
+
+i18n.addTexts('ko', [{ key: 'btn.save', text: '저장' }])
+i18n.addTexts('en', [{ key: 'btn.save', text: 'Save' }])
+
+// inside <script setup>
+const label = t({ key: 'btn.save' })        // resolves to 'Save' or '저장'
+```
+
+```vue
+<span v-t="{ key: 'label.name' }" />
+<BSButton :caption="{ key: 'btn.save' }" />
+```
+
+When the user gives you a Korean/English string literal in demo code, pass it through as-is — components accept a plain string too. For library code that will be reused across locales, prefer keys.
+
+## 3. Components — what exists and when to reach for it
+
+All components come from the single package entry: `import { BSxxx } from '@g1cloud/bluesea'`. There is **no** subpath import. Types and helpers are exported from the same entry.
+
+| Need | Component |
+|---|---|
+| Button / link / router-link | `BSButton` (buttonColor: default/blue/red/orange/green/gray; linkUrl, routePath) |
+| Plain text input | `BSTextInput` (validation: required, minLength, maxLength, regExp, extraValidationRules) |
+| Number / price / percent | `BSNumberInput`, `BSPriceInput`, `BSPercentInput` |
+| Date / date range | `BSDateInput`, `BSDateRange`, `BSCalendar`, `BSCalendarRange`, `BSDateRangePresets` |
+| Select | `BSSelect`, `BSMultiSelect`, `BSTreeSelect`, `BSTreeMultiSelect`, `BSPopupSelect`, `BSYesNoSelect` |
+| Checkbox / radio | `BSCheckbox`, `BSCheckboxGroup`, `BSRadioButton`, `BSRadioButtonGroup`, `BSYesNoGroup` |
+| Textarea / rich text / HTML editor / code editor | `BSTextArea`, `BSRichText`, `BSHtmlEditor`, `BSCodeEditor` |
+| File / image upload | `BSFileUpload`, `BSImageUpload`, `BSMultiImageUpload`, `BSPositionedImageUpload` |
+| Data grid | `BSGrid` + `BSGridControl` + `BSGridLookup` (see §6) |
+| Layout | `BSCardLayout`, `BSListLayout`, `BSTabSheet`, `BSHorizontalLayoutResizer`, `BSVerticalLayoutResizer` |
+| Tree | `BSTree`, `BSTreeControl` |
+| Multi-language inputs | `BSMultiLangTextInput`, `BSMultiLangTextArea`, `BSMultiLangRichText`, `BSMultiLangHtmlEditor`, `BSMultiLangImageUpload` |
+| Global entities | `BSNameInput`, `BSTelInput`, `BSAddressInput`, `BSLocaleSelect` |
+| Popup / tooltip | `BSPopup`, `BSPopupButton`, plus `v-tooltip` directive |
+| Frame shell | `DefaultHeader`, `DefaultBody` (BackOffice app chrome) |
+
+Prop naming is consistent across inputs: `v-model` for the value, `name` (required for validation), `disabled`, `required`, `width` ('200px' by default), `placeholder`, `viewMode` (read-only display), `hideErrorMessage`. Date inputs add `dateFormat`, `timeZone`. Upload inputs take `StoredFile` / `StoredFile[]`.
+
+Typical usage:
+
+```vue
+<BSFormLabel label="이름" required />
+<BSTextInput v-model="form.name" name="name" required :max-length="50" />
+
+<BSFormLabel label="등급" />
+<BSSelect v-model="form.grade" name="grade"
+          :items="grades" :label-provider="g => g.label" :key-provider="g => g.id" />
+
+<BSButton :caption="{ key: 'btn.save' }" button-color="blue" @click="handleSave" />
+```
+
+When you need a component that this table doesn't list, check `packages/bluesea/src/index.ts` for the full export list before assuming it doesn't exist. Use the demo pages under `packages/bluesea-demo/src/page/guide/BS*Guide.vue` as copy-paste-ready examples — they are the canonical "how do I use this component" reference.
+
+## 4. Modals and notifications
+
+The modal plugin is *the* way to open overlays. `useModal()` gives you `openModal`, `openAlert`, `openYesNo`; each returns a `RegisteredModalItem` whose `modalHandle.close()` programmatically closes it. Modals are plain Vue components — pass props via `bind`, listen to events via `on`.
+
+```ts
+import { useModal, showNotification, withLoading } from '@g1cloud/bluesea'
+
+const modal = useModal()
+
+modal.openAlert('알림', '저장되었습니다.')
+
+modal.openYesNo('삭제', '정말 삭제할까요?',
+  async () => { await api.delete(id) },
+  () => { /* cancelled */ })
+
+// custom component
+const handle = modal.openModal({
+  component: EditUserModal,
+  style: { width: '600px', resizable: true },
+  bind: { userId: 123 },
+  on: { submit: (user) => { console.log(user); handle.modalHandle.close() } },
+})
+```
+
+Inside the modal component, call `useModalHandle()` to get the same handle (`handle.close()`, `setDefaultStyle()`, etc.).
+
+Toast-style messages go through `showNotification(message, style, durationMs)` where `style` is `'info' | 'error'`. Longer-lived "alarm" overlays use `showAlarm(component, duration)`. For a global spinner during async work:
+
+```ts
+await withLoading(async () => {
+  await api.save(form)
+  showNotification({ key: 'msg.saved' })
+})
+```
+
+## 5. Validation (the most distinctive Bluesea pattern)
+
+Every input that takes a `name` prop auto-registers a `FieldValidator` on its DOM element. A `FormValidator` walks the DOM of a given root element, collects every registered `FieldValidator`, and runs validation. This means you do **not** wire up validators manually per field — you just give each field a `name` and scope a `FormValidator` to your form root.
+
+```vue
+<template>
+  <div ref="formEl">
+    <BSTextInput v-model="form.email" name="email" required
+                 reg-exp="^[^@]+@[^@]+$"
+                 :validation-message-reg-exp="{ key: 'err.email' }" />
+    <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, ValidationFailedError, isValidationFailedError, showNotification } from '@g1cloud/bluesea'
+
+const formEl = ref<HTMLElement>()
+const form = ref({ email: '', age: 0 })
+const validator = formValidator({
+  element: formEl,
+  rules: [
+    async () => form.value.age < 18
+      ? [{ code: 'tooYoung', message: { key: 'err.adultOnly' } }]
+      : undefined,
+  ],
+})
+
+async function save() {
+  try {
+    await validator.validate()     // throws ValidationFailedError 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>
+```
+
+Built-in rules on inputs: `required`, `minLength` / `maxLength`, `regExp`, `minValue` / `maxValue`, `validation-message-*` overrides for each rule. For custom rules, pass `:extra-validation-rules` — an array of `(value, phase, fieldContext) => ValidationError[] | undefined`. `phase` is `'input' | 'change' | 'blur' | 'form'`, so you can defer expensive async checks to `'blur'` or `'form'` only.
+
+`ValidationError` is `{ code: string; message: MultiLangText }`. `ValidationFailedError.errors` is an array that includes the field `name`, so you can highlight specific fields if needed.
+
+## 6. BSGrid
+
+BSGrid is the workhorse for data tables. Prefer the `createPageGridHandler` factory when you need paging + server-side sorting/filtering — it wires `grid`, `gridEventListener`, `control`, `lookup`, `lookupEventListener` together for you. For simple client-side tables, use `BSGrid` directly with `:columns` + `:data`.
+
+```vue
+<BSGridLookup v-bind="gridHandler.lookup" v-on="gridHandler.lookupEventListener" :config="lookupConfig" />
+<BSGridControl v-bind="gridHandler.control" v-on="gridHandler.controlEventListener" />
+<BSGrid v-bind="gridHandler.grid" v-on="gridHandler.gridEventListener">
+  <template #name="{ row }"><strong>{{ row.name }}</strong></template>
+  <template #status="{ row }"><span class="badge">{{ row.status }}</span></template>
+  <template #price.edit="{ row }"><BSNumberInput v-model="row.price" name="price" /></template>
+</BSGrid>
+
+<script setup lang="ts">
+import { createPageGridHandler, type Column, type PaginatedList } from '@g1cloud/bluesea'
+
+type User = { id: number; name: string; email: string; status: string; price?: number }
+
+const columns: Column<User>[] = [
+  { propertyId: 'name',   caption: { key: 'col.name' },   width: 160, sortable: true },
+  { propertyId: 'email',  caption: { key: 'col.email' },  width: 220 },
+  { propertyId: 'price',  caption: '가격', width: 120, cellType: 'NUMBER' },
+  { propertyId: 'status', caption: '상태', width: 100 },
+]
+
+const gridHandler = createPageGridHandler<User>({
+  gridId: 'user-list',           // used by gridPreferenceStore to remember column widths
+  getRowKey: (u) => String(u.id),
+  editable: true,
+  getGridData: async (param): Promise<PaginatedList<User>> => api.users.search(param),
+  defaultSorts: [{ property: 'name', direction: 'ASC' }],
+  limit: 100,
+  limitItems: [100, 300, 500],
+})
+gridHandler.grid.columnSettings = columns.map(c => ({ propertyId: c.propertyId, hidden: false }))
+await gridHandler.loadGridData()
+</script>
+```
+
+Cell customisation uses named slots: `#<propertyId>` for display, `#<propertyId>.edit` for the editor when `editable: true` and the row is in `editingRows`. Use `cellType` to get built-in formatting (`'TEXT' | 'NUMBER' | 'DATE' | 'PERCENTAGE' | 'BOOL' | 'MULTI_LANG_STRING' | 'NAME' | 'TEL' | 'ADDRESS' | 'MONEY'`). For date columns also set `dateFormat: 'DAY' | 'MINUTE' | 'SECOND'` or a dayjs format string.
+
+For deeper grid topics (inline add/remove, filters, Excel export, fixed columns, extensions) read the `BSGrid` section in `references/grid.md` and the guide page `packages/bluesea-demo/src/page/guide/BSGridGuide.vue`.
+
+## 7. SavePoint (inline-edit modified state)
+
+SavePoint lets a form remember its "saved" state and surface a `modified` flag per field. It is automatically injected by `BSTabSheet` and available via `useSavePoint()` — most inputs (`BSTextInput`, etc.) register themselves so the "modified" dot appears without any extra code. You typically only interact with it to `set()` after a successful save or `rollback()` on cancel:
+
+```ts
+import { useSavePoint } from '@g1cloud/bluesea'
+const savePoint = useSavePoint()
+
+async function save() { await api.save(form.value); savePoint?.set() }
+function cancel() { savePoint?.rollback() }
+```
+
+Pass `:ignore-save-point="true"` on an input to opt it out of modified-tracking.
+
+## 8. Directives
+
+- `v-t="multiLangText"` — set element textContent from a MultiLangText.
+- `v-t.placeholder="multiLangText"` — set the `placeholder` attribute (or any attribute via the modifier name).
+- `v-tooltip="{ content: multiLangText }"` — show on hover.
+- `v-click-outside="handler"` — fire when the user clicks outside the element.
+- `v-focus-on-load`, `v-focus-jump`, `v-focus-loop` — focus management helpers for forms.
+
+Register `vT` globally (`.directive('t', vT)`). The others can be imported and used ad-hoc.
+
+## 9. DefaultFrame (BackOffice app shell)
+
+If the app is a BackOffice application, use `DefaultHeader` + `DefaultBody` for sidebar + tab management. Build a `FrameModel` with your menu tree and tab controller. This is an opinionated shell — skip it for standalone screens. Detailed wiring lives in `references/frame.md` and the `DefaultFrameGuide` demo page.
+
+## When to write code vs read the source
+
+- For a component's exact prop set, **read the `.vue` file** under `packages/bluesea/src/component/`. The `defineProps<{...}>()` block is authoritative; what a docs page says may lag behind.
+- For a real-world wiring example, **open the matching `BS*Guide.vue`** in `packages/bluesea-demo/src/page/guide/`. They cover the common scenarios end-to-end.
+- For types (`MultiLangText`, `StoredFile`, `Money`, `Filter`, `Sort`, `PaginatedList`, `Column`, etc.), the model files in `packages/bluesea/src/model/` and `packages/bluesea/src/component/grid/GridModel.ts` are short and worth reading directly.
+
+## Reference files
+
+- `references/components.md` — fuller prop reference for the most-used components, grouped by category.
+- `references/grid.md` — BSGrid deep-dive: PageGridHandler, filters, inline editing, extensions, Excel export.
+- `references/validation.md` — custom field rules, form-level rules, async validation, and error mapping.
+- `references/i18n.md` — i18n setup, MultiLangText patterns, and locale switching.
+
+Load a reference file only when the user's question clearly touches that area; keep this file as the default map.

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

@@ -0,0 +1,189 @@
+# 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. Paths below are relative to `packages/bluesea/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` — font-icon ligature
+- `disabled: boolean`
+- `linkUrl: string`, `linkTarget: string` — renders `<a>`
+- `routePath: string` — renders `<router-link :to>`
+- `tooltip: MultiLangText`
+
+### 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 `blueseaConfig.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 `blueseaConfig.dateFormat`
+- `timeZone: TimeZone` — falls back to `blueseaConfig.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.
+
+## 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[]`.
+
+### 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 `blueseaConfig.maxFileSize`)
+- `accept: string` — mime filter
+- `preloadOverlay: boolean` — preload preview overlay image (recently renamed from `preloadPreview`)
+- 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 (`input/BSHtmlEditor.vue`)
+Split view (source + preview) for raw HTML.
+
+### BSCodeEditor (`input/BSCodeEditor.vue`)
+CodeMirror 6 — props `language`, `theme`, `readonly`.
+
+## Layout
+
+### BSCardLayout (`layout/BSCardLayout.vue`)
+Container with header/footer slots.
+
+### BSListLayout + BSListControl (`layout/BSListLayout.vue`)
+Master-detail layout with resizable panes.
+
+### BSTabSheet (`layout/BSTabSheet.vue`)
+Manages tabs, provides a SavePoint to each tab. Config toggles `blockLeavingModifiedTab` / `confirmLeavingModifiedTab` via global `componentConfig.tabSheet`.
+
+### 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
+
+### BSNameInput, BSTelInput, BSAddressInput
+Bind to `Name`, `Tel`, `Address` models from `@/model/CommonTypes`. Layout (number of input boxes, widths, line breaks) comes from `componentConfig.nameInput / telInput / addressInput`, so configure them once globally.
+
+### BSLocaleSelect
+Dropdown that switches `blueseaConfig.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 plugin renders into it.
+- `BSNotificationContainer` — mount once; drives `showNotification`, `showAlarm`, `showLoading`.
+- `BSContextMenuContainer` — mount once; the context-menu plugin renders into it.
+
+## Frame
+
+- `DefaultHeader`, `DefaultBody` — BackOffice app shell.
+- `BSAlarmFrame` — standalone alarm container if you don't use DefaultFrame.