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

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.