@quazardous/qdadm 1.19.3

package/src/i18n/__tests__/Resolver.test.ts

@@ -0,0 +1,271 @@
+import { describe, it, expect } from 'vitest'
+
+import { MessagesRegistry } from '../MessagesRegistry'
+import { Resolver, snakeCaseToTitle } from '../Resolver'
+import type { AliasPattern } from '../types'
+
+function makeResolver(opts: {
+  bundles?: Record<string, Parameters<MessagesRegistry['merge']>[1]>
+  globalAliases?: AliasPattern[]
+  defaultLocale?: string
+  fallbackLocale?: string
+  onMissing?: (key: string, locale: string) => void
+}) {
+  const reg = new MessagesRegistry()
+  for (const [locale, bundle] of Object.entries(opts.bundles ?? {})) {
+    reg.merge(locale, bundle)
+  }
+  const resolver = new Resolver(reg, {
+    defaultLocale: opts.defaultLocale ?? 'en',
+    fallbackLocale: opts.fallbackLocale ?? 'en',
+    globalAliases: opts.globalAliases,
+    onMissing: opts.onMissing,
+  })
+  return { reg, resolver }
+}
+
+describe('snakeCaseToTitle', () => {
+  it('handles snake_case', () => {
+    expect(snakeCaseToTitle('first_name')).toBe('First Name')
+  })
+  it('handles camelCase', () => {
+    expect(snakeCaseToTitle('firstName')).toBe('First Name')
+  })
+  it('handles kebab-case', () => {
+    expect(snakeCaseToTitle('first-name')).toBe('First Name')
+  })
+  it('handles single word', () => {
+    expect(snakeCaseToTitle('title')).toBe('Title')
+  })
+})
+
+describe('Resolver — convention lookup', () => {
+  it('returns the matching value from the active locale', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { entities: { books: { fields: { title: 'Title' } } } } },
+    })
+    expect(resolver.translate('entities.books.fields.title', 'en')).toBe('Title')
+  })
+
+  it('falls back to fallbackLocale on miss', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { entities: { books: { fields: { title: 'Title' } } } } },
+      defaultLocale: 'fr',
+      fallbackLocale: 'en',
+    })
+    // No 'fr' bundle — falls back to 'en'
+    expect(resolver.translate('entities.books.fields.title', 'fr')).toBe('Title')
+  })
+
+  it('reads _label from object node', () => {
+    const { resolver } = makeResolver({
+      bundles: {
+        en: {
+          entities: {
+            books: {
+              fields: {
+                genre: { _label: 'Genre', options: { fiction: 'Fiction' } },
+              },
+            },
+          },
+        },
+      },
+    })
+    expect(resolver.translate('entities.books.fields.genre', 'en')).toBe('Genre')
+    expect(
+      resolver.translate('entities.books.fields.genre.options.fiction', 'en')
+    ).toBe('Fiction')
+  })
+})
+
+describe('Resolver — interpolation', () => {
+  it('replaces {placeholder} params', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { core: { errors: { tooShort: 'Too short (min {min})' } } } },
+    })
+    expect(resolver.translate('core.errors.tooShort', 'en', { min: 3 })).toBe(
+      'Too short (min 3)'
+    )
+  })
+
+  it('leaves unknown placeholders untouched', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { foo: 'Hello {name}' } },
+    })
+    expect(resolver.translate('foo', 'en')).toBe('Hello {name}')
+  })
+})
+
+describe('Resolver — value-level @-aliases', () => {
+  it('follows a single @-alias', () => {
+    const { resolver } = makeResolver({
+      bundles: {
+        en: {
+          entities: { books: { actions: { save: '@core.actions.save' } } },
+          core: { actions: { save: 'Save' } },
+        },
+      },
+    })
+    expect(resolver.translate('entities.books.actions.save', 'en')).toBe('Save')
+  })
+
+  it('follows a chain of @-aliases', () => {
+    const { resolver } = makeResolver({
+      bundles: {
+        en: {
+          a: '@b',
+          b: '@c',
+          c: 'Bottom',
+        },
+      },
+    })
+    expect(resolver.translate('a', 'en')).toBe('Bottom')
+  })
+
+  it('detects cycles and falls through', () => {
+    const onMissing = vitestFn()
+    const { resolver } = makeResolver({
+      bundles: { en: { a: '@b', b: '@a' } },
+      onMissing,
+    })
+    // No final string → ends up as miss → returns raw key
+    expect(resolver.translate('a', 'en')).toBe('a')
+    expect(onMissing.calls.length).toBeGreaterThan(0)
+  })
+
+  it('escapes literal @ via @@ prefix', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { ping: '@@home' } },
+    })
+    expect(resolver.translate('ping', 'en')).toBe('@home')
+  })
+})
+
+describe('Resolver — pattern aliases', () => {
+  const globalAliases: AliasPattern[] = [
+    { pattern: 'entities.*.actions.*', target: 'core.actions.$2' },
+    { pattern: 'entities.*.fields.created_at', target: 'core.fields.created_at' },
+  ]
+
+  it('rewrites via wildcard pattern with $2 capture', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { core: { actions: { save: 'Save' } } } },
+      globalAliases,
+    })
+    expect(resolver.translate('entities.books.actions.save', 'en')).toBe('Save')
+  })
+
+  it('rewrites a specific exact pattern', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { core: { fields: { created_at: 'Created at' } } } },
+      globalAliases,
+    })
+    expect(resolver.translate('entities.books.fields.created_at', 'en')).toBe('Created at')
+  })
+
+  it('longest-match wins when multiple patterns match', () => {
+    const aliases: AliasPattern[] = [
+      { pattern: 'entities.*.actions.*', target: 'core.actions.$2' },
+      // More specific, should win
+      { pattern: 'entities.books.actions.delete', target: 'books.specialDelete' },
+    ]
+    const { resolver } = makeResolver({
+      bundles: {
+        en: {
+          core: { actions: { delete: 'Delete' } },
+          books: { specialDelete: 'Discard' },
+        },
+      },
+      globalAliases: aliases,
+    })
+    expect(resolver.translate('entities.books.actions.delete', 'en')).toBe('Discard')
+    // Other entities still go through the wildcard
+    expect(resolver.translate('entities.users.actions.delete', 'en')).toBe('Delete')
+  })
+
+  it('does not loop forever when patterns ping-pong', () => {
+    const aliases: AliasPattern[] = [
+      { pattern: 'a.*', target: 'b.$1' },
+      { pattern: 'b.*', target: 'a.$1' },
+    ]
+    const { resolver } = makeResolver({
+      bundles: { en: {} },
+      globalAliases: aliases,
+    })
+    // Should bail out — no actual value found anywhere
+    expect(resolver.translate('a.foo', 'en')).toBe('a.foo')
+  })
+})
+
+describe('Resolver — final fallbacks', () => {
+  it('humanizes field key via snakeCaseToTitle on miss', () => {
+    const { resolver } = makeResolver({ bundles: { en: {} } })
+    expect(resolver.translate('entities.books.fields.first_name', 'en')).toBe('First Name')
+  })
+
+  it('does NOT humanize non-field keys', () => {
+    const { resolver } = makeResolver({ bundles: { en: {} } })
+    expect(resolver.translate('core.actions.save', 'en')).toBe('core.actions.save')
+  })
+
+  it('emits onMissing on every miss', () => {
+    const onMissing = vitestFn<[string, string]>()
+    const { resolver } = makeResolver({ bundles: { en: {} }, onMissing })
+    resolver.translate('core.actions.save', 'en')
+    resolver.translate('entities.books.fields.title', 'en') // miss but humanized
+    expect(onMissing.calls.length).toBe(2)
+    expect(onMissing.calls[0]).toEqual(['core.actions.save', 'en'])
+    expect(onMissing.calls[1]).toEqual(['entities.books.fields.title', 'en'])
+  })
+})
+
+describe('Resolver — trace', () => {
+  it('returns lookup steps', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { entities: { books: { fields: { title: 'Title' } } } } },
+    })
+    const trace = resolver.resolve('entities.books.fields.title', 'en')
+    expect(trace.hit).toBe(true)
+    expect(trace.result).toBe('Title')
+    expect(trace.steps[0]).toEqual({
+      kind: 'lookup',
+      locale: 'en',
+      key: 'entities.books.fields.title',
+      found: true,
+    })
+  })
+
+  it('records the alias-pattern step on rewrite', () => {
+    const { resolver } = makeResolver({
+      bundles: { en: { core: { actions: { save: 'Save' } } } },
+      globalAliases: [{ pattern: 'entities.*.actions.*', target: 'core.actions.$2' }],
+    })
+    const trace = resolver.resolve('entities.books.actions.save', 'en')
+    expect(trace.hit).toBe(true)
+    const aliasStep = trace.steps.find((s) => s.kind === 'alias-pattern')
+    expect(aliasStep).toBeDefined()
+  })
+
+  it('records snake-case-fallback for missing field', () => {
+    const { resolver } = makeResolver({ bundles: { en: {} } })
+    const trace = resolver.resolve('entities.books.fields.first_name', 'en')
+    expect(trace.hit).toBe(false)
+    expect(trace.result).toBe('First Name')
+    const last = trace.steps[trace.steps.length - 1]
+    expect(last?.kind).toBe('snake-case-fallback')
+  })
+})
+
+// ----------------------------------------------------------------------------
+// Tiny mock helper (avoids import-order quirks with vi.fn() in some setups)
+// ----------------------------------------------------------------------------
+function vitestFn<A extends unknown[] = unknown[]>(): ((...args: A) => void) & {
+  calls: A[]
+} {
+  const calls: A[] = []
+  const fn = ((...args: A) => {
+    calls.push(args)
+  }) as ((...args: A) => void) & { calls: A[] }
+  fn.calls = calls
+  return fn
+}

package/src/i18n/defaults/DefaultCoreProvider.ts

@@ -0,0 +1,28 @@
+/**
+ * Default core provider — ships qdadm's `core.*` defaults (EN + FR) as a
+ * `LazyTranslationProvider` configured with a YAML loader.
+ *
+ * The YAML files (`core.en.yml`, `core.fr.yml`) are imported via Vite's
+ * `?raw` query so the text is fetched on-demand, then parsed at runtime.
+ * Splitting the bundle by locale (and, in the future, by domain) keeps the
+ * provider tree-shakeable and translator-friendly.
+ *
+ * Adding a built-in locale = drop `core.<locale>.yml` next to this file and
+ * add it to the loader map below.
+ */
+
+import { LazyTranslationProvider } from '../LazyTranslationProvider'
+import { createYamlLoader } from '../loaders/yaml'
+
+export function createDefaultCoreProvider(): LazyTranslationProvider {
+  const yamlLoader = createYamlLoader({
+    en: () => import('./core.en.yml?raw'),
+    fr: () => import('./core.fr.yml?raw'),
+  })
+
+  return new LazyTranslationProvider({
+    name: 'default-core',
+    loaders: [yamlLoader],
+    locales: ['en', 'fr'],
+  })
+}

package/src/i18n/defaults/core.en.yml

@@ -0,0 +1,55 @@
+core:
+  actions:
+    save: Save
+    cancel: Cancel
+    delete: Delete
+    edit: Edit
+    create: Create
+    update: Update
+    createAndClose: Create & Close
+    updateAndClose: Update & Close
+    add: Add
+    remove: Remove
+    submit: Submit
+    reset: Reset
+    back: Back
+    next: Next
+    previous: Previous
+    close: Close
+    confirm: Confirm
+    search: Search
+    filter: Filter
+    clear: Clear
+    refresh: Refresh
+    export: Export
+    import: Import
+  tooltips:
+    saveAndContinue: Save and continue editing
+    saveAndReturn: Save and return to list
+    unsavedChanges: Unsaved changes
+  placeholders:
+    search: Search…
+    noSelection: Click to select…
+  fields:
+    id: ID
+    created_at: Created at
+    updated_at: Updated at
+    created_by: Created by
+    updated_by: Updated by
+  messages:
+    empty: No items available
+    loading: Loading…
+    noResults: No results
+    noMatching: No matching items
+    saved: Saved
+    deleted: Deleted
+    created: Created
+    updated: Updated
+    confirmDelete: Are you sure you want to delete this item?
+  errors:
+    required: Required
+    tooShort: Too short (min {min})
+    tooLong: Too long (max {max})
+    invalid: Invalid value
+    notFound: Not found
+    unknown: An unknown error occurred

package/src/i18n/defaults/core.fr.yml

@@ -0,0 +1,55 @@
+core:
+  actions:
+    save: Enregistrer
+    cancel: Annuler
+    delete: Supprimer
+    edit: Modifier
+    create: Créer
+    update: Mettre à jour
+    createAndClose: Créer et fermer
+    updateAndClose: Mettre à jour et fermer
+    add: Ajouter
+    remove: Retirer
+    submit: Valider
+    reset: Réinitialiser
+    back: Retour
+    next: Suivant
+    previous: Précédent
+    close: Fermer
+    confirm: Confirmer
+    search: Rechercher
+    filter: Filtrer
+    clear: Effacer
+    refresh: Actualiser
+    export: Exporter
+    import: Importer
+  tooltips:
+    saveAndContinue: Enregistrer et continuer la modification
+    saveAndReturn: Enregistrer et revenir à la liste
+    unsavedChanges: Modifications non enregistrées
+  placeholders:
+    search: Rechercher…
+    noSelection: Cliquez pour sélectionner…
+  fields:
+    id: Identifiant
+    created_at: Créé le
+    updated_at: Modifié le
+    created_by: Créé par
+    updated_by: Modifié par
+  messages:
+    empty: Aucun élément
+    loading: Chargement…
+    noResults: Aucun résultat
+    noMatching: Aucune correspondance
+    saved: Enregistré
+    deleted: Supprimé
+    created: Créé
+    updated: Modifié
+    confirmDelete: Êtes-vous sûr de vouloir supprimer cet élément ?
+  errors:
+    required: Requis
+    tooShort: Trop court (min {min})
+    tooLong: Trop long (max {max})
+    invalid: Valeur invalide
+    notFound: Introuvable
+    unknown: Une erreur inconnue est survenue

package/src/i18n/index.ts

@@ -0,0 +1,55 @@
+/**
+ * qdadm i18n - public exports.
+ *
+ * ## Two providers to choose from
+ *
+ *   - **`LazyTranslationProvider`** — full bundle on `load(locale)`, split
+ *     across multiple loaders (one per file/domain) deep-merged on resolve.
+ *     Use when the locale bundle is reasonable to fetch up-front.
+ *
+ *   - **`IncrementalDomainProvider`** — one loader per top-level domain,
+ *     fetched on demand. `t()` on an unloaded domain returns the raw key
+ *     synchronously and emits `i18n:domain-loaded` once merged. Use for
+ *     large apps with rarely-used sections.
+ *
+ * Both support `createYamlLoader({ <locale>: () => import('./xx.yml?raw') })`
+ * for the typical "split YAML files in a directory" setup.
+ *
+ * See docs/todo-i18n.md for the broader design rationale.
+ */
+
+export { I18n } from './I18n'
+export type { I18nDeps } from './I18n'
+export { MessagesRegistry } from './MessagesRegistry'
+export { Resolver, snakeCaseToTitle } from './Resolver'
+export { InlineTranslationProvider } from './InlineTranslationProvider'
+export { defineStrategy, resolveStrategy, STRATEGIES } from './strategies'
+export { LazyTranslationProvider } from './LazyTranslationProvider'
+export type { LazyLoader, LazyTranslationProviderOptions } from './LazyTranslationProvider'
+export {
+  IncrementalDomainProvider,
+  isDomainAwareProvider,
+} from './IncrementalDomainProvider'
+export type {
+  DomainLoader,
+  IncrementalDomainProviderOptions,
+} from './IncrementalDomainProvider'
+export { createYamlLoader } from './loaders/yaml'
+export type { YamlTextImport } from './loaders/yaml'
+export { createDefaultCoreProvider } from './defaults/DefaultCoreProvider'
+export { useI18n, I18N_INJECTION_KEY } from './useI18n'
+export type {
+  AliasPattern,
+  CoreMessages,
+  EntityMessages,
+  I18nOptions,
+  KeyStrategy,
+  KeyStrategyName,
+  MessagesBundle,
+  MessagesNode,
+  NavMessages,
+  ResolveStep,
+  ResolveTrace,
+  TranslateParams,
+  TranslationProvider,
+} from './types'

package/src/i18n/loaders/raw-modules.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ambient declarations for Vite/Vitest `?raw` imports of arbitrary text
+ * files (YAML, etc.). Lets `import yamlText from './foo.yml?raw'` type-check
+ * without per-call casts.
+ */
+
+declare module '*.yml?raw' {
+  const content: string
+  export default content
+}
+
+declare module '*.yaml?raw' {
+  const content: string
+  export default content
+}

package/src/i18n/loaders/yaml.ts

@@ -0,0 +1,35 @@
+/**
+ * YAML loader factory for LazyTranslationProvider.
+ *
+ * Given a `locale → () => Promise<{ default: string }>` map, returns a
+ * `LazyLoader` that resolves the YAML text for the requested locale and
+ * parses it through the `yaml` package.
+ *
+ * Typical usage with Vite/Vitest `?raw` imports (qdadm-internal default):
+ *
+ *   const loader = createYamlLoader({
+ *     en: () => import('./core.en.yml?raw'),
+ *     fr: () => import('./core.fr.yml?raw'),
+ *   })
+ *
+ * The dynamic-import boundary is what gives us code-splitting: the YAML for
+ * a locale is only fetched + parsed when that locale is requested.
+ */
+
+import { parse as parseYaml } from 'yaml'
+
+import type { MessagesBundle } from '@quazardous/qdcore'
+import type { LazyLoader } from '../LazyTranslationProvider'
+
+export type YamlTextImport = () => Promise<{ default: string }>
+
+export function createYamlLoader(textImports: Record<string, YamlTextImport>): LazyLoader {
+  return async (locale: string) => {
+    const importer = textImports[locale]
+    if (!importer) return null
+    const mod = await importer()
+    const parsed = parseYaml(mod.default)
+    if (!parsed || typeof parsed !== 'object') return null
+    return parsed as MessagesBundle
+  }
+}

package/src/i18n/strategies.ts

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

package/src/i18n/types.ts

@@ -0,0 +1,34 @@
+/**
+ * qdadm i18n types.
+ *
+ * Generic types come from `@quazardous/qdcore/i18n`; this module adds the
+ * admin-specific `I18nOptions` (kernel constructor option that toggles the
+ * default core admin bundles shipped via DefaultCoreProvider).
+ */
+
+import type { BaseI18nOptions } from '@quazardous/qdcore'
+
+export type {
+  AliasPattern,
+  BaseI18nOptions,
+  CoreMessages,
+  EntityMessages,
+  KeyStrategy,
+  KeyStrategyName,
+  MessagesBundle,
+  MessagesNode,
+  NavMessages,
+  ResolveStep,
+  ResolveTrace,
+  TranslateParams,
+  TranslationProvider,
+} from '@quazardous/qdcore'
+
+/**
+ * Kernel-level i18n options for qdadm. Extends the generic shared shape with
+ * admin-only knobs.
+ */
+export interface I18nOptions extends BaseI18nOptions {
+  /** Disable shipping qdadm's default core.* bundles (EN + FR). Default: false. */
+  disableDefaultCoreBundle?: boolean
+}

package/src/i18n/useI18n.ts

@@ -0,0 +1,34 @@
+/**
+ * useI18n - Vue composable for accessing the kernel I18n instance.
+ *
+ * Falls back to a no-op shim if no I18n has been provided to the app — useful
+ * for components rendered outside a kernel (tests, isolated examples).
+ */
+
+import { computed, inject, type Ref, type ComputedRef } from 'vue'
+import type { I18n } from './I18n'
+import type { TranslateParams } from './types'
+
+export const I18N_INJECTION_KEY = Symbol('qdadm.i18n')
+
+export interface UseI18nResult {
+  t: (key: string, params?: TranslateParams) => string
+  locale: ComputedRef<string> | Ref<string>
+  i18n: I18n | null
+}
+
+export function useI18n(): UseI18nResult {
+  const i18n = inject<I18n | null>(I18N_INJECTION_KEY, null)
+  if (!i18n) {
+    return {
+      t: (key: string) => key,
+      locale: computed(() => 'en'),
+      i18n: null,
+    }
+  }
+  return {
+    t: (key, params) => i18n.t(key, params),
+    locale: i18n.locale,
+    i18n,
+  }
+}