qdadm 1.13.0 → 1.19.2

package/src/i18n/I18n.ts

@@ -0,0 +1,344 @@
+/**
+ * I18n - Top-level orchestrator (exposed as `kernel.i18n`).
+ *
+ * Owns:
+ *   - the active locale (reactive ref)
+ *   - the MessagesRegistry
+ *   - registered TranslationProviders
+ *   - the active strategy's pattern aliases
+ *   - the Resolver
+ *
+ * Public API:
+ *   - t(key, params?)
+ *   - locale (ref)
+ *   - availableLocales
+ *   - resolve(key)         (debug trace)
+ *   - dump(locale)         (export merged bundle)
+ *   - changeLocale(locale) (programmatic; the public way is signals.emit('locale:change', loc))
+ *   - addProvider(p)
+ *   - addMessages(locale, bundle)
+ *   - addAliases(patterns)
+ *   - registerEntityModule(entity, module) (for the 'module' strategy)
+ */
+
+import { ref, type Ref } from 'vue'
+
+import {
+  MessagesRegistry,
+  Resolver,
+  InlineTranslationProvider,
+  resolveStrategy,
+} from '@quazardous/qdcore'
+import type {
+  AliasPattern,
+  MessagesBundle,
+  ResolveTrace,
+  TranslateParams,
+  TranslationProvider,
+} from '@quazardous/qdcore'
+import { createDefaultCoreProvider } from './defaults/DefaultCoreProvider'
+import { isDomainAwareProvider } from './IncrementalDomainProvider'
+import type { I18nOptions } from './types'
+
+export interface I18nDeps {
+  /** SignalBus instance for emitting locale:changed and i18n:missing. */
+  signals?: {
+    emit: (signal: string, payload?: unknown) => void | Promise<void>
+    on: (signal: string, handler: (e: { data: unknown }) => void) => () => void
+  } | null
+}
+
+export class I18n {
+  readonly inline: InlineTranslationProvider
+  readonly locale: Ref<string>
+
+  private _registry: MessagesRegistry
+  private _resolver: Resolver
+  private _providers: TranslationProvider[]
+  private _strategyName: string | string[]
+  private _appAliases: AliasPattern[]
+  private _entityToModule: Map<string, string> = new Map()
+  private _signals: I18nDeps['signals']
+  private _defaultLocale: string
+  private _fallbackLocale: string
+  private _loadedLocales: Set<string> = new Set()
+  // Track which (locale::domain) pairs have already been resolved through a
+  // domain-aware provider, so we don't re-trigger an async load on every
+  // subsequent miss for the same domain.
+  private _loadedDomains: Set<string> = new Set()
+  // Concurrent domain loads — share one in-flight promise per (locale, domain)
+  // pair across providers and t() callers.
+  private _inflightDomains: Map<string, Promise<void>> = new Map()
+
+  constructor(options: I18nOptions = {}, deps: I18nDeps = {}) {
+    this._defaultLocale = options.defaultLocale ?? 'en'
+    this._fallbackLocale = options.fallbackLocale ?? this._defaultLocale
+    this._strategyName = options.keyStrategy ?? 'global'
+    this._appAliases = options.aliases ? [...options.aliases] : []
+    this._signals = deps.signals ?? null
+
+    this._registry = new MessagesRegistry()
+    this.inline = new InlineTranslationProvider()
+
+    // Provider chain: framework defaults (lazy) → inline (ctx.messages) → user.
+    // _loadLocale merges providers in order, so later entries override earlier
+    // ones. The default core is first so app-level overrides always win.
+    const defaultCoreProviders: TranslationProvider[] = options.disableDefaultCoreBundle
+      ? []
+      : [createDefaultCoreProvider()]
+    this._providers = [
+      ...defaultCoreProviders,
+      this.inline,
+      ...(options.providers ?? []),
+    ]
+
+    this.locale = ref(this._defaultLocale)
+
+    this._resolver = new Resolver(this._registry, {
+      defaultLocale: this._defaultLocale,
+      fallbackLocale: this._fallbackLocale,
+      globalAliases: this._currentStrategyAliases(),
+      onMissing: (key, locale) => {
+        this._signals?.emit('i18n:missing', { key, locale })
+      },
+    })
+
+    // App-level messages from kernel options.
+    if (options.messages) {
+      for (const [loc, bundle] of Object.entries(options.messages)) {
+        this.inline.push(loc, bundle)
+      }
+    }
+
+    // Listen for locale:change requests on the bus, if present.
+    if (this._signals) {
+      this._signals.on('locale:change', (event) => {
+        const loc = typeof event.data === 'string' ? event.data : null
+        if (loc) void this.changeLocale(loc)
+      })
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Translate a convention-derived key.
+   *
+   * On a miss whose top-level segment matches a domain known to one of the
+   * registered domain-aware providers (e.g. `IncrementalDomainProvider`),
+   * triggers a lazy load for that (locale, domain) pair in the background
+   * and emits `i18n:domain-loaded` once merged. The current call still
+   * returns the raw key — callers that want to react to the late arrival
+   * should listen to `i18n:domain-loaded`.
+   */
+  t(key: string, params?: TranslateParams): string {
+    const trace = this._resolver.resolve(key, this.locale.value, params)
+    if (!trace.hit) {
+      this._maybeEnsureDomain(key, this.locale.value)
+    }
+    return trace.result
+  }
+
+  /**
+   * Explicitly request a domain to be loaded for a locale, ahead of any
+   * `t()` miss that would have triggered it. Useful when a screen is about
+   * to need a rare domain and the dev wants to avoid the placeholder flash.
+   *
+   * Resolves once the domain is merged into the registry (or rejects if no
+   * domain-aware provider knows it).
+   */
+  loadDomain(domain: string, locale: string = this.locale.value): Promise<void> {
+    return this._ensureDomain(locale, domain)
+  }
+
+  /**
+   * Return the resolution trace (for debugging).
+   */
+  resolve(key: string, params?: TranslateParams): ResolveTrace {
+    return this._resolver.resolve(key, this.locale.value, params)
+  }
+
+  /**
+   * Union of available locales across registered providers.
+   */
+  async availableLocales(): Promise<string[]> {
+    const set = new Set<string>()
+    for (const p of this._providers) {
+      if (typeof p.availableLocales === 'function') {
+        const locs = await p.availableLocales()
+        for (const l of locs) set.add(l)
+      }
+    }
+    return Array.from(set)
+  }
+
+  /**
+   * Switch to a new locale. Loads bundles from providers if not yet cached.
+   * Public callers should prefer `signals.emit('locale:change', loc)`.
+   */
+  async changeLocale(locale: string): Promise<void> {
+    if (this.locale.value === locale && this._loadedLocales.has(locale)) return
+    await this._loadLocale(locale)
+    this.locale.value = locale
+    this._signals?.emit('locale:changed', locale)
+  }
+
+  /**
+   * Initial bootstrap: load default + fallback locales from providers.
+   * Called by the kernel during warmup.
+   */
+  async bootstrap(): Promise<void> {
+    const targets = new Set<string>([this._defaultLocale, this._fallbackLocale])
+    for (const loc of targets) {
+      await this._loadLocale(loc)
+    }
+  }
+
+  /**
+   * Register an additional provider after construction.
+   */
+  addProvider(provider: TranslationProvider): void {
+    this._providers.push(provider)
+  }
+
+  /**
+   * Push messages into the inline provider (used by ctx.messages()).
+   * Bundles merge into the registry on next load. If the locale is already
+   * loaded, the bundle is also merged immediately for hot updates.
+   */
+  addMessages(locale: string, bundle: MessagesBundle): void {
+    this.inline.push(locale, bundle)
+    if (this._loadedLocales.has(locale)) {
+      this._registry.merge(locale, bundle)
+    }
+  }
+
+  /**
+   * Append app/module-level pattern aliases to the active strategy.
+   */
+  addAliases(patterns: AliasPattern[]): void {
+    this._appAliases.push(...patterns)
+    this._resolver.setOptions({ globalAliases: this._currentStrategyAliases() })
+  }
+
+  /**
+   * Track which module owns which entity. Used to materialize the 'module'
+   * key strategy at runtime (entities.<entity>.* → modules.<module>.*).
+   */
+  registerEntityModule(entity: string, module: string): void {
+    this._entityToModule.set(entity, module)
+    if (this._strategyIncludes('module')) {
+      this._resolver.setOptions({ globalAliases: this._currentStrategyAliases() })
+    }
+  }
+
+  /**
+   * Export the currently merged bundle for a locale (for translator workflows).
+   */
+  dump(locale: string): MessagesBundle {
+    return this.inline.load(locale)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internals
+  // ---------------------------------------------------------------------------
+
+  private async _loadLocale(locale: string): Promise<void> {
+    for (const p of this._providers) {
+      const bundle = await p.load(locale)
+      if (bundle && Object.keys(bundle).length > 0) {
+        this._registry.merge(locale, bundle)
+      }
+    }
+    this._loadedLocales.add(locale)
+  }
+
+  /**
+   * Fire-and-forget: invoked from t() on a miss to opportunistically pull in
+   * a domain-aware provider's bundle for the missed top-level segment.
+   * Errors are swallowed (logged as a missing-domain signal) — the current
+   * t() call has already returned.
+   */
+  private _maybeEnsureDomain(key: string, locale: string): void {
+    const dot = key.indexOf('.')
+    const domain = dot === -1 ? key : key.slice(0, dot)
+    if (!domain) return
+    if (this._loadedDomains.has(`${locale}::${domain}`)) return
+    if (!this._providers.some((p) => isDomainAwareProvider(p) && p.knowsDomain(domain))) {
+      return
+    }
+    void this._ensureDomain(locale, domain).catch(() => {
+      // Already surfaced via i18n:missing on the original miss; silent here.
+    })
+  }
+
+  /**
+   * Resolves once a domain has been pulled from any domain-aware provider
+   * that knows it. Safe to call concurrently — loads are deduped per
+   * (locale, domain) pair. Emits `i18n:domain-loaded` after the merge.
+   */
+  private _ensureDomain(locale: string, domain: string): Promise<void> {
+    const cacheKey = `${locale}::${domain}`
+    if (this._loadedDomains.has(cacheKey)) return Promise.resolve()
+    const existing = this._inflightDomains.get(cacheKey)
+    if (existing) return existing
+
+    const promise = (async () => {
+      let merged = false
+      for (const p of this._providers) {
+        if (!isDomainAwareProvider(p) || !p.knowsDomain(domain)) continue
+        const bundle = await p.loadDomain(locale, domain)
+        if (bundle && Object.keys(bundle).length > 0) {
+          this._registry.merge(locale, bundle)
+          merged = true
+        }
+      }
+      this._loadedDomains.add(cacheKey)
+      this._inflightDomains.delete(cacheKey)
+      if (merged) {
+        this._signals?.emit('i18n:domain-loaded', { locale, domain })
+      }
+    })()
+
+    this._inflightDomains.set(cacheKey, promise)
+    return promise
+  }
+
+  private _currentStrategyAliases(): AliasPattern[] {
+    const fromStrategy = resolveStrategy(this._strategyName)
+    const fromModuleStrategy = this._strategyIncludes('module')
+      ? this._materializeModuleAliases()
+      : []
+    return [...fromStrategy, ...fromModuleStrategy, ...this._appAliases]
+  }
+
+  private _strategyIncludes(name: string): boolean {
+    if (this._strategyName === name) return true
+    if (Array.isArray(this._strategyName)) return this._strategyName.includes(name)
+    return false
+  }
+
+  /**
+   * For each known entity → module mapping, emit two pattern aliases:
+   *   entities.<entity>.actions.* → modules.<module>.actions.$1
+   *   entities.<entity>.errors.*  → modules.<module>.errors.$1
+   * (plus a more specific actions/errors per-module fallback to core.*.)
+   */
+  private _materializeModuleAliases(): AliasPattern[] {
+    const out: AliasPattern[] = []
+    for (const [entity, module] of this._entityToModule) {
+      out.push(
+        { pattern: `entities.${entity}.actions.*`, target: `modules.${module}.actions.$1` },
+        { pattern: `entities.${entity}.errors.*`, target: `modules.${module}.errors.$1` }
+      )
+    }
+    // Module-level fallbacks to core.
+    out.push(
+      { pattern: 'modules.*.actions.*', target: 'core.actions.$2' },
+      { pattern: 'modules.*.errors.*', target: 'core.errors.$2' }
+    )
+    return out
+  }
+}

package/src/i18n/IncrementalDomainProvider.ts

@@ -0,0 +1,153 @@
+/**
+ * IncrementalDomainProvider - declares one loader per top-level translation
+ * domain (`core`, `shop`, `legal`, …) and only fetches each (locale, domain)
+ * pair when it's first needed.
+ *
+ * On `load(locale)` (bootstrap / locale change) the provider only resolves
+ * the domains listed in `eagerDomains` (typically `['core']`). The rest stay
+ * dormant until `loadDomain(locale, domain)` is called — which `I18n.t()`
+ * triggers automatically on a miss whose top-level segment is a
+ * known-but-not-yet-loaded domain. The host app can also pre-warm explicitly
+ * via `i18n.loadDomain(domain, locale?)`. Inflight loads are deduped per
+ * `(locale, domain)`.
+ *
+ * Bundles returned by domain loaders are wrapped under their domain key so
+ * the registry merges them at the right place:
+ *   loader('shop')(locale) → { cart: {...} } → merged as { shop: { cart: {...} } }
+ *
+ * ## When to use this vs `LazyTranslationProvider`
+ *
+ * Use **`IncrementalDomainProvider`** when at least one of these matters:
+ *   - **Bundle size**: large app with rarely-used sections (admin, legal,
+ *     marketing) and you want to defer their cost.
+ *   - **Per-domain caching**: domains have different freshness needs, or
+ *     come from different transports.
+ *   - **Granularity**: you want to know exactly when a domain has landed
+ *     (`i18n:domain-loaded` signal).
+ *
+ * Use **`LazyTranslationProvider`** when the full locale bundle is
+ * reasonable to fetch up-front and you just want to organise translations
+ * across multiple files. See `LazyTranslationProvider.ts`.
+ *
+ * ## Tradeoff
+ *
+ * `t()` returns synchronously even for an unloaded domain — on first miss
+ * it returns the raw key (which renders as a placeholder for one frame),
+ * kicks off the async load, then emits `i18n:domain-loaded` once merged.
+ * The host app subscribes to that signal if it wants to react (e.g. force a
+ * re-render of components that hit the placeholder). Pre-warming via
+ * `i18n.loadDomain(domain)` avoids the placeholder entirely.
+ */
+
+import type { MessagesBundle, MessagesNode, TranslationProvider } from '@quazardous/qdcore'
+
+export type DomainLoader = (locale: string) => Promise<MessagesNode | null>
+
+export interface IncrementalDomainProviderOptions {
+  /** Provider name (for debugging / introspection). */
+  name?: string
+  /** Loader per top-level domain. Key is the domain (e.g. `core`, `shop`). */
+  domains: Record<string, DomainLoader>
+  /**
+   * Domains to load eagerly during `load(locale)` (i.e. on bootstrap or
+   * locale change). Default: empty — every domain is purely lazy.
+   */
+  eagerDomains?: string[]
+  /** Locales advertised through `availableLocales()`. */
+  locales?: string[]
+}
+
+export class IncrementalDomainProvider implements TranslationProvider {
+  readonly name: string
+  private readonly _domains: Record<string, DomainLoader>
+  private readonly _eagerDomains: string[]
+  private readonly _locales: string[] | undefined
+  private readonly _inflight: Map<string, Promise<MessagesBundle | null>> = new Map()
+
+  constructor(options: IncrementalDomainProviderOptions) {
+    this.name = options.name ?? 'incremental-domain'
+    this._domains = { ...options.domains }
+    this._eagerDomains = options.eagerDomains ? [...options.eagerDomains] : []
+    this._locales = options.locales ? [...options.locales] : undefined
+  }
+
+  /**
+   * Eagerly load only the domains listed in `eagerDomains`. Other domains
+   * are loaded on demand via `loadDomain`.
+   */
+  async load(locale: string): Promise<MessagesBundle> {
+    if (this._eagerDomains.length === 0) return {}
+    const merged: MessagesBundle = {}
+    await Promise.all(
+      this._eagerDomains.map(async (domain) => {
+        const partial = await this._loadDomain(locale, domain)
+        if (partial) Object.assign(merged, partial)
+      })
+    )
+    return merged
+  }
+
+  /**
+   * Returns whether this provider has a loader registered for `domain`.
+   * Used by `I18n.t()` to decide whether a miss can be recovered by a lazy
+   * load.
+   */
+  knowsDomain(domain: string): boolean {
+    return Object.prototype.hasOwnProperty.call(this._domains, domain)
+  }
+
+  /**
+   * Lazy-load a single domain. Concurrent calls for the same (locale, domain)
+   * pair share one in-flight promise. Returns the wrapped bundle (i.e.
+   * `{ [domain]: <node> }`) or `null` if the domain is unknown / loader
+   * returns nothing.
+   */
+  loadDomain(locale: string, domain: string): Promise<MessagesBundle | null> {
+    if (!this.knowsDomain(domain)) return Promise.resolve(null)
+    const cacheKey = `${locale}::${domain}`
+    const existing = this._inflight.get(cacheKey)
+    if (existing) return existing
+    const promise = this._loadDomain(locale, domain)
+    this._inflight.set(cacheKey, promise)
+    // Keep the inflight cache populated until the promise settles so a second
+    // concurrent caller dedupes; once settled, drop the entry — successive
+    // calls go through the loader again only if the I18n caller has lost
+    // track. In practice I18n keeps its own loaded set and won't re-call.
+    void promise.finally(() => {
+      this._inflight.delete(cacheKey)
+    })
+    return promise
+  }
+
+  availableLocales(): string[] {
+    return this._locales ? [...this._locales] : []
+  }
+
+  private async _loadDomain(
+    locale: string,
+    domain: string
+  ): Promise<MessagesBundle | null> {
+    const loader = this._domains[domain]
+    if (!loader) return null
+    const node = await loader(locale)
+    if (node === null || node === undefined) return null
+    return { [domain]: node }
+  }
+}
+
+/**
+ * Type guard: detects a provider that supports per-domain lazy loading.
+ * Used by I18n.t() to recover from a domain-miss without coupling I18n to
+ * the IncrementalDomainProvider class.
+ */
+export function isDomainAwareProvider(
+  p: TranslationProvider
+): p is TranslationProvider & {
+  loadDomain(locale: string, domain: string): Promise<MessagesBundle | null>
+  knowsDomain(domain: string): boolean
+} {
+  return (
+    typeof (p as { loadDomain?: unknown }).loadDomain === 'function' &&
+    typeof (p as { knowsDomain?: unknown }).knowsDomain === 'function'
+  )
+}

package/src/i18n/InlineTranslationProvider.ts

@@ -0,0 +1,4 @@
+/**
+ * InlineTranslationProvider — qdadm re-export from `@quazardous/qdcore/i18n`.
+ */
+export { InlineTranslationProvider } from '@quazardous/qdcore'

package/src/i18n/LazyTranslationProvider.ts

@@ -0,0 +1,102 @@
+/**
+ * LazyTranslationProvider - generic, format-agnostic provider that resolves
+ * locale bundles via a cascade of lazy loaders.
+ *
+ * Each loader is a `(locale) => Promise<MessagesBundle | null>` function. On
+ * `load(locale)`, the provider runs **all** loaders in order and deep-merges
+ * the partial bundles they return (later loaders override earlier ones —
+ * "last-merge-wins" semantics, same as the rest of the i18n stack).
+ *
+ * This lets consumers split bundles across multiple files — e.g. one loader
+ * for `core.*`, one for `entities.*`, one for `nav.*` — each backed by its
+ * own source (YAML file, JSON, fetch, etc.) without the provider knowing
+ * about any of those formats.
+ *
+ * ## When to use this vs `IncrementalDomainProvider`
+ *
+ * Use **`LazyTranslationProvider`** when you want one bundle per locale and
+ * don't care about loading domains independently:
+ *   - All loaders run on `_loadLocale(locale)` (i.e. bootstrap or locale
+ *     change). No partial state — once `bootstrap()` resolves, every key in
+ *     every domain is in the registry for that locale.
+ *   - Best for small/medium apps where the full bundle for a locale is
+ *     reasonable to fetch up-front.
+ *   - Domains are still split across files (the "cascade" lets you organise
+ *     translations by topic), they're just resolved together.
+ *
+ * Use **`IncrementalDomainProvider`** when domains should be loaded only on
+ * demand — `t('shop.cart.title')` for an unloaded `shop` domain triggers an
+ * async load in the background and emits `i18n:domain-loaded` once merged.
+ * Best for large apps with rarely-used sections (admin, legal, marketing
+ * landing pages, …) where shipping every domain on bootstrap would be
+ * wasteful. See `IncrementalDomainProvider.ts`.
+ */
+
+import type { MessagesBundle, MessagesNode, TranslationProvider } from '@quazardous/qdcore'
+
+export type LazyLoader = (locale: string) => Promise<MessagesBundle | null>
+
+export interface LazyTranslationProviderOptions {
+  /** Provider name (for debugging / introspection). */
+  name?: string
+  /** Cascade of loaders. Earlier loaders are overridden by later ones. */
+  loaders: LazyLoader[]
+  /**
+   * Locales advertised through `availableLocales()`. If omitted, the provider
+   * doesn't advertise any (callers should still be able to ask `load(locale)`
+   * — loaders that don't have the locale return null and are skipped).
+   */
+  locales?: string[]
+}
+
+export class LazyTranslationProvider implements TranslationProvider {
+  readonly name: string
+  private readonly _loaders: LazyLoader[]
+  private readonly _locales: string[] | undefined
+
+  constructor(options: LazyTranslationProviderOptions) {
+    this.name = options.name ?? 'lazy'
+    this._loaders = [...options.loaders]
+    this._locales = options.locales ? [...options.locales] : undefined
+  }
+
+  async load(locale: string): Promise<MessagesBundle> {
+    let merged: MessagesBundle = {}
+    for (const loader of this._loaders) {
+      const partial = await loader(locale)
+      if (partial && Object.keys(partial).length > 0) {
+        merged = deepMerge(merged, partial)
+      }
+    }
+    return merged
+  }
+
+  availableLocales(): string[] {
+    return this._locales ? [...this._locales] : []
+  }
+}
+
+/**
+ * Recursive merge of two MessagesBundle (or any plain-object MessagesNode):
+ * objects merge recursively, leaf values from `b` override leaf values from
+ * `a`. Arrays are replaced wholesale (we don't expect arrays in bundles, but
+ * be safe). Returns a new object — does not mutate inputs.
+ */
+function deepMerge(a: MessagesBundle, b: MessagesBundle): MessagesBundle
+function deepMerge(a: MessagesNode, b: MessagesNode): MessagesNode
+function deepMerge(a: MessagesNode, b: MessagesNode): MessagesNode {
+  if (!isPlainObject(a) || !isPlainObject(b)) return b
+  const out: Record<string, MessagesNode> = { ...(a as Record<string, MessagesNode>) }
+  for (const [key, bv] of Object.entries(b as Record<string, MessagesNode>)) {
+    const av = out[key]
+    out[key] =
+      isPlainObject(av) && isPlainObject(bv) ? (deepMerge(av, bv) as MessagesNode) : bv
+  }
+  return out as MessagesNode
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}

package/src/i18n/MessagesRegistry.ts

@@ -0,0 +1,4 @@
+/**
+ * MessagesRegistry — qdadm re-export from `@quazardous/qdcore/i18n`.
+ */
+export { MessagesRegistry } from '@quazardous/qdcore'

package/src/i18n/Resolver.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolver — qdadm re-export from `@quazardous/qdcore/i18n`.
+ */
+export { Resolver, snakeCaseToTitle } from '@quazardous/qdcore'