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

package/dist/index.d.ts

@@ -1,130 +1,10 @@
-export declare const BLUESEA_VERSION = "5.0.0";
-export * from './config/config';
-export type * from './config/config';
-export { default as BSButton } from './component/basic/BSButton.vue';
-export { default as BSFormLabel } from './component/basic/BSFormLabel.vue';
-export { default as BSYesNoSelect } from './component/input/BSYesNoSelect.vue';
-export { default as BSPopupButton } from './component/basic/BSPopupButton.vue';
-export { default as BSTextInput } from './component/input/BSTextInput.vue';
-export { default as BSLink } from './component/basic/BSLink.vue';
-export { default as BSProgressBar } from './component/basic/BSProgressBar.vue';
-export { default as BSConsole } from './component/basic/BSConsole.vue';
-export { default as BSLoadingIcon } from './component/basic/BSLoadingIcon.vue';
-export { default as BSDate } from './component/basic/BSDate.vue';
-export { default as BSPageNavigation } from './component/basic/BSPageNavigation.vue';
-export { default as BSCalendar } from './component/basic/BSCalendar.vue';
-export { default as BSCalendarRange } from './component/basic/BSCalendarRange.vue';
-export { default as BSNumberInput } from './component/input/BSNumberInput.vue';
-export { default as BSPriceInput } from './component/input/BSPriceInput.vue';
-export { default as BSColorInput } from './component/input/BSColorInput.vue';
-export { default as BSDateInput } from './component/input/BSDateInput.vue';
-export { default as BSDateRange } from './component/input/BSDateRange.vue';
-export { default as BSDateRangePresets } from './component/input/BSDateRangePresets.vue';
-export { default as BSCheckbox } from './component/input/BSCheckbox.vue';
-export { default as BSCheckboxGroup } from './component/input/BSCheckboxGroup.vue';
-export { default as BSRadioButton } from './component/input/BSRadioButton.vue';
-export { default as BSRadioButtonGroup } from './component/input/BSRadioButtonGroup.vue';
-export { default as BSYesNoGroup } from './component/input/BSYesNoGroup.vue';
-export { default as BSSelect } from './component/input/BSSelect.vue';
-export { default as BSMultiSelect } from './component/input/BSMultiSelect.vue';
-export { default as BSTreeSelect } from './component/input/BSTreeSelect.vue';
-export { default as BSTreeMultiSelect } from './component/input/BSTreeMultiSelect.vue';
-export { default as BSPopupSelect } from './component/input/BSPopupSelect.vue';
-export { default as BSTextArea } from './component/input/BSTextArea.vue';
-export { default as BSRichText } from './component/richtext/BSRichText.vue';
-export type * from './component/richtext/RichTextModel';
-export { Editor } from '@tiptap/core';
-export type * from './component/input/ImageUploadModel';
-export * from './component/input/ImageUploadModel';
-export { default as BSImageUpload } from './component/input/BSImageUpload.vue';
-export { default as BSMultiImageUpload } from './component/input/BSMultiImageUpload.vue';
-export { default as BSPositionedImageUpload } from './component/input/BSPositionedImageUpload.vue';
-export { default as BSGrid } from './component/grid/BSGrid.vue';
-export * from './component/grid/GridModel';
-export * from './component/grid/GridExtension';
-export * from './component/grid/extension/gridExcelDownloadExtension';
-export type * from './component/grid/GridModel';
-export { default as BSGridLookup } from './component/grid/BSGridLookup.vue';
-export { default as BSGridControl } from './component/grid/BSGridControl.vue';
-export type * from './component/grid/DateFilterModel';
-export * from './component/grid/DateFilterModel';
-export { default as BSTextFilter } from './component/grid/BSTextFilter.vue';
-export { default as BSDateRangeFilter } from './component/grid/BSDateRangeFilter.vue';
-export { default as BSDateRangeFilters } from './component/grid/BSDateRangeFilters.vue';
-export { default as BSCardLayout } from './component/layout/BSCardLayout.vue';
-export { default as BSTabSheet } from './component/layout/BSTabSheet.vue';
-export { default as BSListLayout } from './component/layout/BSListLayout.vue';
-export { default as BSListControl } from './component/layout/BSListControl.vue';
-export type * from './component/layout/TabSheetModel';
-export * from './component/layout/TabSheetModel';
-export { default as BSHorizontalLayoutResizer } from './component/layout/BSHorizontalLayoutResizer.vue';
-export { default as BSVerticalLayoutResizer } from './component/layout/BSVerticalLayoutResizer.vue';
-export { default as BSTree } from './component/tree/BSTree.vue';
-export type * from './component/tree/TreeModel';
-export * from './component/tree/TreeModel';
-export { default as BSTreeControl } from './component/tree/BSTreeControl.vue';
-export { default as BSMultiLangTextInput } from './component/multilang/BSMultiLangTextInput.vue';
-export { default as BSMultiLangTextArea } from './component/multilang/BSMultiLangTextArea.vue';
-export { default as BSMultiLangRichText } from './component/multilang/BSMultiLangRichText.vue';
-export { default as BSMultiLangExpandButton } from './component/multilang/BSMultiLangExpandButton.vue';
-export { default as BSMultiLangImageUpload } from './component/multilang/BSMultiLangImageUpload.vue';
-export { default as BSMultiLangHtmlEditor } from './component/multilang/BSMultiLangHtmlEditor.vue';
-export * from './component/multilang/multiLangLib';
-export { default as BSLocaleSelect } from './component/global/BSLocaleSelect.vue';
-export { default as BSNameInput } from './component/global/BSNameInput.vue';
-export { default as BSTelInput } from './component/global/BSTelInput.vue';
-export { default as BSAddressInput } from './component/global/BSAddressInput.vue';
-export { default as BSImage } from './component/basic/BSImage.vue';
-export type * from './component/input/ImageUploadModel';
-export { default as BSCodeEditor } from './component/input/BSCodeEditor.vue';
-export { default as BSHtmlEditor } from './component/input/BSHtmlEditor.vue';
-export type * from './component/input/HtmlEditorModel';
-export { default as BSPopup } from './component/basic/BSPopup.vue';
-export { default as BSSelectPopup } from './component/input/BSSelectPopup.vue';
-export { default as BSDateInputPopup } from './component/input/BSDateInputPopup.vue';
-export { default as BSDateRangeInputPopup } from './component/input/BSDateRangeInputPopup.vue';
-export type * from './validator/FormValidator';
-export * from './validator/FormValidator';
-export type * from './validator/FieldValidator';
-export * from './validator/FieldValidator';
-export * from './savepoint/SavePoint';
-export type * from './model/CommonTypes';
-export * from './model/CommonTypes';
-export * from './model/PaginatedList';
-export type * from './model/FilterModel';
-export * from './model/FilterModel';
-export * from './model/SearchModel';
-export type * from './model/SearchModel';
-export * from './model/FieldContext';
-export type * from './model/FieldContext';
-export { default as BSModalContainer } from './modal/BSModalContainer.vue';
-export { default as BSModalFrame } from './modal/BSModalFrame.vue';
-export * from './modal/modalPlugin';
-export type * from './modal/modalPlugin';
-export { default as BSNotificationContainer } from './notification/BSNotificationContainer.vue';
-export * from './notification/notificationPlugin';
-export type * from './notification/notificationPlugin';
-export { default as BSAlarmFrame } from './notification/BSAlarmFrame.vue';
-export { default as BSContextMenuContainer } from './contextmenu/BSContextMenuContainer.vue';
-export * from './contextmenu/contextMenuPlugin';
-export type * from './contextmenu/contextMenuPlugin';
-export * from './frame/FrameModel';
-export type * from './frame/FrameModel';
-export { default as DefaultHeader } from './frame/default/DefaultHeader.vue';
-export { default as DefaultBody } from './frame/default/DefaultBody.vue';
-export type * from './frame/default/DefaultFrameModel';
-export * from './frame/default/DefaultFrameModel';
-export * from './frame/ShortcutKeyHandler';
-export * from './text/i18n';
-export { default as vClickOutside } from './directive/vClickOutside';
-export { default as vT, interpretMultiLangText } from './directive/vT';
-export { default as vTooltip } from './directive/vTooltip';
-export { default as vFocusOnLoad } from './directive/vFocusOnLoad';
-export { default as vFocusJump } from './directive/vFocusJump';
-export { default as vFocusLoop } from './directive/vFocusLoop';
-export * from './util/typeUtil';
-export * from './util/formatUtil';
-export * from './util/waitUtil';
-export * from './util/routeUtil';
-export * from './util/multiLangUtil';
-export * from './util/debounceUtil';
+export * from '@g1cloud/bluesea-core';
+export * from '@g1cloud/bluesea-basic';
+export * from '@g1cloud/bluesea-input';
+export * from '@g1cloud/bluesea-grid';
+export * from '@g1cloud/bluesea-tree';
+export * from '@g1cloud/bluesea-richtext';
+export * from '@g1cloud/bluesea-global';
+export * from '@g1cloud/bluesea-frame';
+export type { DndContext } from '@g1cloud/bluesea-core';
+export { vDragSupport, vDropSupport } from '@g1cloud/bluesea-input';

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "@g1cloud/bluesea-core";
+export * from "@g1cloud/bluesea-basic";
+export * from "@g1cloud/bluesea-input";
+import { vDragSupport, vDropSupport } from "@g1cloud/bluesea-input";
+export * from "@g1cloud/bluesea-grid";
+export * from "@g1cloud/bluesea-tree";
+export * from "@g1cloud/bluesea-richtext";
+export * from "@g1cloud/bluesea-global";
+export * from "@g1cloud/bluesea-frame";
+export {
+  vDragSupport,
+  vDropSupport
+};

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@g1cloud/bluesea",
-  "private": false,
-  "version": "5.0.0-beta.8",
-  "description": "Ui Library for g1cloud BackOffice.",
+  "version": "6.0.0-alpha.0",
+  "description": "Ui Library for g1cloud BackOffice. (meta package — re-exports all bluesea packages)",
   "type": "module",
   "engines": {
     "node": ">= 20.10.0"
@@ -12,69 +11,52 @@
   "files": [
     "dist",
     "css",
-    "scss",
-    "text",
-    "!dist/tests"
+    "!dist/tests",
+    "skills",
+    "bin"
   ],
-  "module": "dist/bluesea.js",
-  "main": "dist/bluesea.js",
-  "types": "dist/index.d.ts",
-  "dependencies": {
-    "@codemirror/lang-css": "^6.2.1",
-    "@codemirror/lang-html": "^6.4.9",
-    "@codemirror/lang-json": "^6.0.1",
-    "@codemirror/lang-xml": "^6.1.0",
-    "@codemirror/lang-yaml": "^6.1.1",
-    "@tiptap/core": "^2.8.0",
-    "@tiptap/extension-color": "^2.8.0",
-    "@tiptap/extension-image": "^2.8.0",
-    "@tiptap/extension-link": "^2.8.0",
-    "@tiptap/extension-table": "^2.8.0",
-    "@tiptap/extension-table-cell": "^2.8.0",
-    "@tiptap/extension-table-header": "^2.8.0",
-    "@tiptap/extension-table-row": "^2.8.0",
-    "@tiptap/extension-text-align": "^2.8.0",
-    "@tiptap/extension-text-style": "^2.8.0",
-    "@tiptap/extension-youtube": "^2.8.0",
-    "@tiptap/pm": "^2.8.0",
-    "@tiptap/starter-kit": "^2.8.0",
-    "@tiptap/vue-3": "^2.8.0",
-    "@vue/shared": "^3.5.13",
-    "codemirror": "^6.0.1",
-    "dayjs": "^1.11.13",
-    "tiptap-extension-font-size": "^1.2.0",
-    "vue": "^3.5.13",
-    "vue-codemirror": "^6.1.1",
-    "vue-router": "^4.5.0",
-    "xlsx": "^0.18.5"
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./css/*": "./css/*"
   },
-  "devDependencies": {
-    "@types/node": "^20.12.7",
-    "@vitejs/plugin-vue": "^5.0.4",
-    "@vitest/coverage-v8": "^1.5.3",
-    "@vue/test-utils": "^2.4.6",
-    "jsdom": "^26.1.0",
-    "sass": "^1.86.3",
-    "typescript": "^5.4.5",
-    "vite": "^6.3.2",
-    "vite-plugin-dts": "^3.9.0",
-    "vitest": "^3.1.1",
-    "vitest-canvas-mock": "^0.3.3",
-    "vue-tsc": "^2.2.8"
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@g1cloud/bluesea-tree": "^6.0.0-alpha.0",
+    "@g1cloud/bluesea-basic": "^6.0.0-alpha.0",
+    "@g1cloud/bluesea-input": "^6.0.0-alpha.0",
+    "@g1cloud/bluesea-grid": "^6.0.0-alpha.0",
+    "@g1cloud/bluesea-core": "^6.0.0-alpha.0",
+    "@g1cloud/bluesea-richtext": "^6.0.0-alpha.0",
+    "@g1cloud/bluesea-frame": "^6.0.0-alpha.0",
+    "@g1cloud/bluesea-global": "^6.0.0-alpha.0"
   },
   "peerDependencies": {
-    "dayjs": "^1.11.11",
     "vue": "^3.5.13",
     "vue-router": "^4.3.2",
-    "vue3-youtube": "^0.1.9"
+    "dayjs": "^1.11.11"
+  },
+  "devDependencies": {
+    "vue": "^3.5.13",
+    "vue-router": "^4.5.0",
+    "dayjs": "^1.11.11",
+    "@types/node": "^24.0.0",
+    "typescript": "~5.9.3",
+    "vite": "^7.0.0",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.9",
+    "vue-tsc": "^3.3.6"
   },
   "scripts": {
-    "dev": "vite",
-    "build": "vue-tsc && vite build && pnpm build:scss",
-    "build:vue": "vue-tsc && vite build",
-    "build:scss": "sass scss/bluesea.scss:css/bluesea.css scss/frame/default.scss:css/frame-default.css --no-source-map",
-    "preview": "vite preview",
-    "test": "vitest",
-    "generate-bluesea-message": "node ./tool/generateBlueseaMessage.js"
+    "build": "vue-tsc && vite build",
+    "test": "vitest run --passWithNoTests",
+    "install-claude-skill": "node bin/install-claude-skill.mjs"
   }
 }

package/skills/bluesea-ui/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: bluesea-ui
+description: Build g1cloud BackOffice UIs with @g1cloud/bluesea Vue 3 v6 — covers app bootstrap (createBluesea + pinia), composables (useBlueseaConfig, useTexts, useNotification, useModal), BS* components (BSButton, BSTextInput, BSGrid, BSSelect, BSModal), FieldValidator/FormValidator pattern, MultiLangText + i18n, SavePoint for inline edits, and DefaultFrame shell. Use this skill whenever the user works in a project that imports from "@g1cloud/bluesea" or mentions any BS* component, BSGrid, BSModal, createBluesea, useBlueseaConfig, useTexts, useNotification, 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 v6 — Vue 3 UI library for g1cloud BackOffice
+
+Bluesea v6 is an enterprise-focused Vue 3 component library with SSR support via Nuxt and Tailwind CSS v4 styling. 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 + 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/<package>/src/component/<group>/<Name>.vue` — the `defineProps<{...}>()` block is the source of truth. This is faster and more reliable than guessing. Packages are: core, basic, input, grid, tree, richtext, global, frame.
+
+## 1. Project bootstrap
+
+### Vite SPA
+
+Every Bluesea app calls `createBluesea(...)` after `createPinia()` and before `.mount()`. A realistic `main.ts` looks like this (trim to what you need):
+
+```ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import { createBluesea } from '@g1cloud/bluesea'
+import '@g1cloud/bluesea/css/bluesea.css'
+import '@g1cloud/bluesea/css/frame-default.css' // only if you use DefaultFrame
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(createPinia())  // Must come before createBluesea
+app.use(createBluesea({
+  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',
+  extended: {
+    gridPreferenceStore: new LocalStorageGridPreferenceStore(browserStorage),  // 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
+    },
+  },
+}))
+
+app.mount('#app')
+```
+
+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>
+```
+
+Global state lives on reactive composables; call `useBlueseaConfig()` to access config and `useBlueseaConfig().setCurrentLocale('en')` to switch language at runtime.
+
+### Nuxt 4
+
+With Nuxt, one module line handles everything (pinia, plugin, auto-import, CSS, richtext client-only):
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@g1cloud/bluesea-nuxt'],
+  bluesea: {
+    locales: ['ko', 'en', 'ja'],
+    defaultLocale: 'ko',
+    currentLocale: 'ko',
+    timeZone: 'Asia/Seoul',
+    dateFormat: 'YYYY-MM-DD HH:mm',
+  },
+})
+```
+
+The containers are auto-mounted. No manual `createBluesea()` call needed — the Nuxt module does it.
+
+## 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 `useTexts()` (or `i18n.addTexts(locale, [...])` on core import) and render them with the `t()` helper or interpolation:
+
+```ts
+import { useTexts } from '@g1cloud/bluesea'
+
+const { t, addTexts } = useTexts()
+
+// Register once in setup
+addTexts('ko', [{ key: 'btn.save', text: '저장' }])
+addTexts('en', [{ key: 'btn.save', text: 'Save' }])
+
+// Use the t() helper
+const label = t({ key: 'btn.save' })        // resolves to 'Save' or '저장'
+```
+
+In templates, use interpolation instead of `v-t` directive (removed in v6 for SSR):
+
+```vue
+<span>{{ t({ key: 'label.name' }) }}</span>
+<BSButton :caption="{ key: 'btn.save' }" />
+<input :placeholder="t({ key: 'ph.name' })" />
+```
+
+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 `vTooltip` directive (via `createTooltipDirective()`) |
+| Frame shell | `DefaultHeader`, `DefaultBody` (BackOffice app chrome) |
+| Icon | `BSIcon` (SVG-based, replaces icon font) |
+
+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 system is pinia-based. `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, useNotification } from '@g1cloud/bluesea'
+
+const modal = useModal()
+const { showNotification } = useNotification()
+
+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 `notification.showNotification(message, style, durationMs)` where `style` is `'info' | 'error'`. Longer-lived "alarm" overlays use `notification.showAlarm(component, duration)`. For a global spinner during async work:
+
+```ts
+await notification.withLoading(async () => {
+  await api.save(form)
+  notification.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 } from '@g1cloud/bluesea'
+import { useNotification } from '@g1cloud/bluesea'
+
+const formEl = ref<HTMLElement>()
+const form = ref({ email: '', age: 0 })
+const { showNotification } = useNotification()
+
+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' }, 'info')
+  } 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`, `controlEventListener`, `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
+
+- `vTooltip` — show tooltip on hover. Use via `const vTooltip = createTooltipDirective()` and register globally.
+- `vClickOutside` — fire when the user clicks outside the element.
+- `vFocusOnLoad`, `vFocusJump`, `vFocusLoop` — focus management helpers for forms.
+
+Import and use ad-hoc or register globally.
+
+## 9. Styling with Tailwind v4
+
+Bluesea v6 uses Tailwind CSS v4. Key changes from v5:
+- **Utility scale** changed: old 1px scale → 0.25rem scale. `mt-8` (8px) → `mt-2`, `p-16` → `p-4`. Non-multiple-of-4 values use bracket notation: `mr-1` → `mr-[1px]`.
+- **Dark mode** via `.dark` class (not `[data-theme="dark"]`). Toggle with `document.documentElement.classList.toggle('dark', on)`.
+- **Icon font removed** — use `BSIcon name="xyz"` instead of `<span class="font-icon">xyz</span>`.
+- **CSS source**: `@g1cloud/bluesea/css/bluesea.css` (pre-compiled) or integrate theme + component CSS files into your Tailwind build for zero duplication.
+
+## 10. 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/<package>/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/<package>/src/model/` and grid models 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, locale switching, and data vs UI locale.
+
+Load a reference file only when the user's question clearly touches that area; keep this file as the default map.