@fluenti/solid 0.3.4 → 0.4.0-rc.1

package/llms.txt

@@ -58,6 +58,50 @@ The context returned by `useI18n()` provides:
 
 ❌ AVOID: `t('some.key')` as the default — this is a legacy i18n pattern.
 
+## Code Examples — SolidJS
+
+### Tagged template (PREFERRED)
+
+```tsx
+import { useI18n } from '@fluenti/solid'
+
+function MyComponent() {
+  const { t } = useI18n()
+
+  return (
+    <div>
+      <h1>{t\`Welcome to our app\`}</h1>
+      <p>{t\`Hello, ${name()}!\`}</p>
+    </div>
+  )
+}
+```
+
+### Rich text with \<Trans\>
+
+```tsx
+import { Trans } from '@fluenti/solid/components'
+
+function Terms() {
+  return (
+    <Trans>
+      Read our <a href="/terms">terms of service</a>
+    </Trans>
+  )
+}
+```
+
+### What NOT to write
+
+❌ Do not use t() with manual key strings:
+```tsx
+// WRONG
+const msg = t('welcome_message')
+
+// CORRECT
+const msg = t\`Welcome to our app\`
+```
+
 ## Docs
 
 - Full docs: https://fluenti.dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluenti/solid",
-  "version": "0.3.4",
+  "version": "0.4.0-rc.1",
   "type": "module",
   "description": "SolidJS compile-time i18n — Trans/Plural/Select components, I18nProvider, useI18n",
   "homepage": "https://fluenti.dev",
@@ -16,6 +16,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "sideEffects": false,
   "keywords": [
     "i18n",
     "internationalization",
@@ -54,6 +55,20 @@
         "default": "./dist/server.cjs"
       }
     },
+    "./components": {
+      "solid": {
+        "types": "./dist/components-entry.d.ts",
+        "default": "./src/components-entry.ts"
+      },
+      "import": {
+        "types": "./dist/components-entry.d.ts",
+        "default": "./dist/components-entry.js"
+      },
+      "require": {
+        "types": "./dist/components-entry.d.ts",
+        "default": "./dist/components-entry.cjs"
+      }
+    },
     "./vite-plugin": {
       "import": {
         "types": "./dist/vite-plugin.d.ts",
@@ -80,8 +95,8 @@
     }
   },
   "dependencies": {
-    "@fluenti/core": "0.3.4",
-    "@fluenti/vite-plugin": "0.3.4"
+    "@fluenti/core": "0.4.0-rc.1",
+    "@fluenti/vite-plugin": "0.4.0-rc.1"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8",

package/src/components-entry.ts

@@ -0,0 +1,13 @@
+export { Trans } from './trans'
+export type { FluentiTransProps } from './trans'
+export { Plural } from './plural'
+export type { FluentiPluralProps } from './plural'
+export { SelectComp as Select } from './select'
+export type { FluentiSelectProps } from './select'
+export { DateTime } from './components/DateTime'
+export type { DateTimeProps, FluentiDateTimeProps } from './components/DateTime'
+export { NumberFormat } from './components/NumberFormat'
+export type { NumberProps, FluentiNumberFormatProps } from './components/NumberFormat'
+
+// Re-export interpolate for apps that use <Plural>/<Select> at runtime
+export { interpolate } from '@fluenti/core/internal'

package/src/context.ts

@@ -1,7 +1,6 @@
 import { createSignal, type Accessor } from 'solid-js'
-import { createDiagnostics, formatDate, formatNumber } from '@fluenti/core'
-import type { FluentiCoreConfig, Locale, LocalizedString, Messages, CompiledMessage, MessageDescriptor, DateFormatOptions, NumberFormatOptions, DiagnosticsConfig } from '@fluenti/core'
-import { interpolate as coreInterpolate, buildICUMessage, resolveDescriptorId } from '@fluenti/core/internal'
+import { createFluentiCore } from '@fluenti/core'
+import type { FluentiCoreConfig, FluentiCoreConfigFull, Locale, LocalizedString, Messages, CompiledMessage, MessageDescriptor, DateFormatOptions, NumberFormatOptions, DiagnosticsConfig, CustomFormatter } from '@fluenti/core'
 
 /** Chunk loader for lazy locale loading */
 export type ChunkLoader = (
@@ -30,6 +29,37 @@ function resolveChunkMessages(
     : loaded
 }
 
+/** @internal Map locale → default currency code */
+const LOCALE_CURRENCY_MAP: Record<string, string> = {
+  'en': 'USD', 'en-US': 'USD', 'en-GB': 'GBP', 'en-AU': 'AUD', 'en-CA': 'CAD',
+  'zh-CN': 'CNY', 'zh-TW': 'TWD', 'zh-HK': 'HKD',
+  'ja': 'JPY', 'ja-JP': 'JPY',
+  'ko': 'KRW', 'ko-KR': 'KRW',
+  'de': 'EUR', 'de-DE': 'EUR', 'de-AT': 'EUR',
+  'fr': 'EUR', 'fr-FR': 'EUR', 'fr-CA': 'CAD',
+  'es': 'EUR', 'es-ES': 'EUR', 'es-MX': 'MXN',
+  'pt': 'EUR', 'pt-BR': 'BRL', 'pt-PT': 'EUR',
+  'it': 'EUR', 'ru': 'RUB', 'ar': 'SAR', 'hi': 'INR',
+}
+
+/** @internal Built-in date format styles (merged under user-provided dateFormats) */
+const DEFAULT_DATE_FORMATS: Record<string, Intl.DateTimeFormatOptions> = {
+  short: { year: 'numeric', month: 'numeric', day: 'numeric' },
+  long: { year: 'numeric', month: 'long', day: 'numeric', weekday: 'long' },
+  time: { hour: 'numeric', minute: 'numeric' },
+  datetime: { year: 'numeric', month: 'short', day: 'numeric', hour: 'numeric', minute: 'numeric' },
+}
+
+/** @internal Built-in number format styles (merged under user-provided numberFormats) */
+const DEFAULT_NUMBER_FORMATS: Record<string, Intl.NumberFormatOptions | ((locale: Locale) => Intl.NumberFormatOptions)> = {
+  currency: (locale: string) => ({
+    style: 'currency',
+    currency: LOCALE_CURRENCY_MAP[locale] ?? LOCALE_CURRENCY_MAP[locale.split('-')[0]!] ?? 'USD',
+  }),
+  percent: { style: 'percent' },
+  decimal: { minimumFractionDigits: 2, maximumFractionDigits: 2 },
+}
+
 /** Extended config with lazy locale loading support */
 export interface FluentiConfig extends FluentiCoreConfig {
   /** Async chunk loader for lazy locale loading */
@@ -44,6 +74,19 @@ export interface FluentiConfig extends FluentiCoreConfig {
   numberFormats?: NumberFormatOptions
   /** Runtime diagnostics configuration */
   diagnostics?: DiagnosticsConfig
+  /**
+   * Custom message interpolation function.
+   *
+   * By default, the runtime uses a lightweight `{key}` replacer.
+   * Pass the full `interpolate` from `@fluenti/core/internal` for
+   * runtime ICU MessageFormat support (plurals, selects, nested arguments).
+   */
+  interpolate?: (
+    message: string,
+    values: Record<string, unknown> | undefined,
+    locale: string,
+    formatters?: Record<string, CustomFormatter>,
+  ) => string
 }
 
 /** Reactive i18n context holding locale signal and translation utilities */
@@ -83,6 +126,20 @@ export interface FluentiContext {
  *
  * The returned `t()` reads the internal `locale()` signal, so any
  * Solid computation that calls `t()` will re-run when the locale changes.
+ *
+ * @example
+ * ```tsx
+ * import { createFluentiContext } from '@fluenti/solid'
+ * import messages from './locales/compiled/en.js'
+ *
+ * const ctx = createFluentiContext({
+ *   locale: 'en',
+ *   messages: { en: messages },
+ * })
+ *
+ * // Use t`` tagged template (preferred)
+ * const greeting = ctx.t`Hello, {name}!`
+ * ```
  */
 export function createFluentiContext(config: FluentiCoreConfig | FluentiConfig): FluentiContext {
   const [locale, setLocaleSignal] = createSignal<Locale>(config.locale)
@@ -91,155 +148,42 @@ export function createFluentiContext(config: FluentiCoreConfig | FluentiConfig):
   const [loadedLocales, setLoadedLocales] = createSignal(new Set(loadedLocalesSet))
   const messages: Record<string, Messages> = { ...config.messages }
   const i18nConfig = config as FluentiConfig
-  const diagnostics = i18nConfig.diagnostics ? createDiagnostics(i18nConfig.diagnostics) : undefined
   const lazyLocaleLoading = i18nConfig.lazyLocaleLoading
     ?? (config as FluentiConfig & { splitting?: boolean }).splitting
     ?? false
 
-  function lookupCatalog(
-    id: string,
-    loc: Locale,
-    values?: Record<string, unknown>,
-  ): LocalizedString | undefined {
-    const catalog = messages[loc]
-    if (!catalog) {
-      return undefined
-    }
-
-    const msg = catalog[id]
-    if (msg === undefined) {
-      return undefined
-    }
-
-    if (typeof msg === 'function') {
-      return msg(values) as LocalizedString
-    }
-
-    if (typeof msg === 'string' && values) {
-      return coreInterpolate(msg, values, loc) as LocalizedString
-    }
-
-    return String(msg) as LocalizedString
-  }
-
-  function lookupWithFallbacks(
-    id: string,
-    loc: Locale,
-    values?: Record<string, unknown>,
-  ): LocalizedString | undefined {
-    const localesToTry: Locale[] = [loc]
-    const seen = new Set(localesToTry)
-
-    if (config.fallbackLocale && !seen.has(config.fallbackLocale)) {
-      localesToTry.push(config.fallbackLocale)
-      seen.add(config.fallbackLocale)
-    }
-
-    const chainLocales = i18nConfig.fallbackChain?.[loc] ?? i18nConfig.fallbackChain?.['*']
-    if (chainLocales) {
-      for (const chainLocale of chainLocales) {
-        if (!seen.has(chainLocale)) {
-          localesToTry.push(chainLocale)
-          seen.add(chainLocale)
-        }
-      }
-    }
-
-    for (const targetLocale of localesToTry) {
-      const result = lookupCatalog(id, targetLocale, values)
-      if (result !== undefined) {
-        if (targetLocale !== loc) {
-          diagnostics?.fallbackUsed(loc, targetLocale, id)
-        }
-        return result
-      }
-    }
-
-    return undefined
-  }
-
-  function resolveMissing(
-    id: string,
-    loc: Locale,
-  ): LocalizedString | undefined {
-    if (!config.missing) {
-      return undefined
-    }
-
-    try {
-      const result = config.missing(loc, id)
-      if (result !== undefined) {
-        return result as LocalizedString
-      }
-    } catch {
-      // Missing handler threw — fall through to next resolution path
-    }
-    return undefined
-  }
-
-  function resolveMessage(
-    id: string,
-    loc: Locale,
-    values?: Record<string, unknown>,
-  ): LocalizedString {
-    const catalogResult = lookupWithFallbacks(id, loc, values)
-    if (catalogResult !== undefined) {
-      return catalogResult
-    }
-
-    diagnostics?.missingKey(loc, id)
-
-    const missingResult = resolveMissing(id, loc)
-    if (missingResult !== undefined) {
-      return missingResult
-    }
-
-    if (id.includes('{')) {
-      return coreInterpolate(id, values, loc) as LocalizedString
-    }
-
-    return id as LocalizedString
+  // Create a core instance that handles all translation, lookup, fallback, and formatting logic.
+  // Merge built-in date/number format styles under user-provided overrides.
+  // Build config incrementally to satisfy exactOptionalPropertyTypes —
+  // optional properties must not receive `undefined` as a value.
+  const coreConfig: FluentiCoreConfigFull = {
+    locale: config.locale,
+    messages: config.messages ?? {},
+    dateFormats: { ...DEFAULT_DATE_FORMATS, ...i18nConfig.dateFormats },
+    numberFormats: { ...DEFAULT_NUMBER_FORMATS, ...i18nConfig.numberFormats },
   }
+  if (config.fallbackLocale !== undefined) coreConfig.fallbackLocale = config.fallbackLocale
+  if (i18nConfig.fallbackChain !== undefined) coreConfig.fallbackChain = i18nConfig.fallbackChain
+  if (config.missing !== undefined) coreConfig.missing = config.missing
+  if (i18nConfig.diagnostics !== undefined) coreConfig.diagnostics = i18nConfig.diagnostics as FluentiCoreConfigFull['diagnostics']
+  if (i18nConfig.interpolate !== undefined) coreConfig.interpolate = i18nConfig.interpolate
+  const i18n = createFluentiCore(coreConfig)
 
   function t(strings: TemplateStringsArray, ...exprs: unknown[]): LocalizedString
   function t(id: string | MessageDescriptor, values?: Record<string, unknown>): LocalizedString
   function t(idOrStrings: string | MessageDescriptor | TemplateStringsArray, ...rest: unknown[]): LocalizedString {
-    // Tagged template form: t`Hello ${name}`
+    const current = locale() // READ SIGNAL → reactive dependency for Solid re-renders
+    if (i18n.locale !== current) i18n.locale = current
+    // Dispatch to the correct overload based on input type
     if (Array.isArray(idOrStrings) && 'raw' in idOrStrings) {
-      const strings = idOrStrings as TemplateStringsArray
-      const icu = buildICUMessage(strings, rest)
-      const values = Object.fromEntries(rest.map((v, i) => [`arg${i}`, v]))
-      return resolveMessage(icu, locale(), values)
+      return i18n.t(idOrStrings as TemplateStringsArray, ...rest) as LocalizedString
     }
-
-    const id = idOrStrings as string | MessageDescriptor
-    const values = rest[0] as Record<string, unknown> | undefined
-    const currentLocale = locale() // reactive dependency
-    if (typeof id === 'object' && id !== null) {
-      const messageId = resolveDescriptorId(id)
-      if (messageId) {
-        const catalogResult = lookupWithFallbacks(messageId, currentLocale, values)
-        if (catalogResult !== undefined) {
-          return catalogResult
-        }
-
-        const missingResult = resolveMissing(messageId, currentLocale)
-        if (missingResult !== undefined) {
-          return missingResult
-        }
-      }
-
-      if (id.message !== undefined) {
-        return coreInterpolate(id.message, values, currentLocale) as LocalizedString
-      }
-
-      return (messageId ?? '') as LocalizedString
-    }
-
-    return resolveMessage(id, currentLocale, values)
+    return i18n.t(idOrStrings as string | MessageDescriptor, rest[0] as Record<string, unknown> | undefined) as LocalizedString
   }
 
   const loadMessages = (loc: Locale, msgs: Messages): void => {
+    i18n.loadMessages(loc, msgs)
+    // Keep local messages in sync for te/tm which check the local object
     // Intentional mutation: messages record is locally scoped to this context closure
     messages[loc] = { ...messages[loc], ...msgs }
     loadedLocalesSet.add(loc)
@@ -257,8 +201,12 @@ export function createFluentiContext(config: FluentiCoreConfig | FluentiConfig):
     const splitRuntime = getSplitRuntimeModule()
 
     if (loadedLocalesSet.has(newLocale)) {
-      if (splitRuntime?.__switchLocale) {
-        await splitRuntime.__switchLocale(newLocale)
+      try {
+        if (splitRuntime?.__switchLocale) {
+          await splitRuntime.__switchLocale(newLocale)
+        }
+      } catch (e) {
+        console.warn(`[fluenti] split runtime switch failed for locale "${newLocale}"`, e)
       }
       setLocaleSignal(newLocale)
       return
@@ -270,14 +218,19 @@ export function createFluentiContext(config: FluentiCoreConfig | FluentiConfig):
     try {
       const loaded = resolveChunkMessages(await i18nConfig.chunkLoader(newLocale))
       // Always store loaded messages — they may be needed if locale is switched back
+      i18n.loadMessages(newLocale, loaded)
       // Intentional mutation: messages record is locally scoped to this context closure
       messages[newLocale] = { ...messages[newLocale], ...loaded }
       loadedLocalesSet.add(newLocale)
       setLoadedLocales(new Set(loadedLocalesSet))
       // Stale request — a newer setLocale call superseded this one; don't switch locale
       if (thisRequest !== _localeRequestId) return
-      if (splitRuntime?.__switchLocale) {
-        await splitRuntime.__switchLocale(newLocale)
+      try {
+        if (splitRuntime?.__switchLocale) {
+          await splitRuntime.__switchLocale(newLocale)
+        }
+      } catch (e) {
+        console.warn(`[fluenti] split runtime switch failed for locale "${newLocale}"`, e)
       }
       // Re-check after async __switchLocale — a newer setLocale() may have superseded this one
       if (thisRequest !== _localeRequestId) return
@@ -297,6 +250,7 @@ export function createFluentiContext(config: FluentiCoreConfig | FluentiConfig):
     const splitRuntime = getSplitRuntimeModule()
     i18nConfig.chunkLoader(loc).then(async (loaded) => {
       const resolved = resolveChunkMessages(loaded)
+      i18n.loadMessages(loc, resolved)
       // Intentional mutation: messages record is locally scoped to this context closure
       messages[loc] = { ...messages[loc], ...resolved }
       loadedLocalesSet.add(loc)
@@ -311,16 +265,24 @@ export function createFluentiContext(config: FluentiCoreConfig | FluentiConfig):
     })
   }
 
-  const getLocales = (): Locale[] => Object.keys(messages)
+  const getLocales = (): Locale[] => i18n.getLocales()
 
-  const d = (value: Date | number, style?: string): LocalizedString =>
-    formatDate(value, locale(), style, i18nConfig.dateFormats) as LocalizedString
+  const d = (value: Date | number, style?: string): LocalizedString => {
+    const current = locale() // READ SIGNAL → reactive dependency
+    if (i18n.locale !== current) i18n.locale = current
+    return i18n.d(value, style) as LocalizedString
+  }
 
-  const n = (value: number, style?: string): LocalizedString =>
-    formatNumber(value, locale(), style, i18nConfig.numberFormats) as LocalizedString
+  const n = (value: number, style?: string): LocalizedString => {
+    const current = locale() // READ SIGNAL → reactive dependency
+    if (i18n.locale !== current) i18n.locale = current
+    return i18n.n(value, style) as LocalizedString
+  }
 
   const format = (message: string, values?: Record<string, unknown>): LocalizedString => {
-    return coreInterpolate(message, values, locale()) as LocalizedString
+    const current = locale() // READ SIGNAL → reactive dependency
+    if (i18n.locale !== current) i18n.locale = current
+    return i18n.format(message, values) as LocalizedString
   }
 
   const te = (key: string, loc?: string): boolean => {

package/src/index.ts

@@ -3,14 +3,13 @@ export type { FluentiContext, FluentiConfig } from './context'
 export { I18nProvider } from './provider'
 export { useI18n } from './use-i18n'
 export { t } from './compile-time-t'
-export { Trans } from './trans'
+export { msg } from './msg'
+
+// Components moved to @fluenti/solid/components:
+//   import { Trans, Plural, Select, DateTime, NumberFormat } from '@fluenti/solid/components'
 export type { FluentiTransProps } from './trans'
-export { Plural } from './plural'
 export type { FluentiPluralProps } from './plural'
-export { SelectComp as Select } from './select'
 export type { FluentiSelectProps } from './select'
-export { msg } from './msg'
-export { DateTime } from './components/DateTime'
 export type { DateTimeProps, FluentiDateTimeProps } from './components/DateTime'
-export { NumberFormat } from './components/NumberFormat'
 export type { NumberProps, FluentiNumberFormatProps } from './components/NumberFormat'
+

package/src/plural.tsx

@@ -56,6 +56,15 @@ export interface FluentiPluralProps {
  * ```tsx
  * <Plural value={count()} zero="No items" one="# item" other="# items" />
  * ```
+ *
+ * @example
+ * ```tsx
+ * import { Plural } from '@fluenti/solid'
+ *
+ * function ItemCount(props: { count: number }) {
+ *   return <Plural value={props.count} one="# item" other="# items" />
+ * }
+ * ```
  */
 export const Plural: Component<FluentiPluralProps> = (props) => {
   const { t } = useI18n()

package/src/provider.tsx

@@ -7,8 +7,26 @@ import type { FluentiConfig, FluentiContext } from './context'
 export const I18nCtx = createContext<FluentiContext>()
 
 /**
- * Provide i18n context to the component tree.
+ * Provides the Fluenti i18n context to the Solid component tree.
  *
+ * @example
+ * ```tsx
+ * import { I18nProvider, useI18n } from '@fluenti/solid'
+ * import messages from './locales/compiled/en.js'
+ *
+ * function App() {
+ *   return (
+ *     <I18nProvider locale="en" messages={{ en: messages }}>
+ *       <Content />
+ *     </I18nProvider>
+ *   )
+ * }
+ *
+ * function Content() {
+ *   const { t } = useI18n()
+ *   return <h1>{t`Welcome to our app`}</h1>
+ * }
+ * ```
  */
 export const I18nProvider: ParentComponent<FluentiConfig> = (props) => {
   const ctx = createFluentiContext(props)

package/src/rich-dom.tsx

@@ -90,6 +90,16 @@ export function reconstruct(
 
     const idx = Number(match[1])
     const isSelfClosing = match[2] === undefined
+
+    if (!Number.isInteger(idx) || idx < 0 || idx >= components.length) {
+      if (!isSelfClosing) {
+        result.push(match[3] ?? '')
+      }
+      lastIndex = combinedRe.lastIndex
+      match = combinedRe.exec(translated)
+      continue
+    }
+
     const template = components[idx]
 
     if (isSelfClosing) {

package/src/select.tsx

@@ -50,6 +50,21 @@ export interface FluentiSelectProps {
  * ```
  *
  * Falls back to the `other` prop when no key matches.
+ *
+ * @example
+ * ```tsx
+ * import { Select } from '@fluenti/solid'
+ *
+ * function Greeting(props: { gender: string }) {
+ *   return (
+ *     <Select value={props.gender}
+ *       male="He liked your post"
+ *       female="She liked your post"
+ *       other="They liked your post"
+ *     />
+ *   )
+ * }
+ * ```
  */
 export const SelectComp: Component<FluentiSelectProps> = (props) => {
   const { t } = useI18n()

package/src/solid-runtime.ts

@@ -7,7 +7,6 @@ export const solidRuntimeGenerator: RuntimeGenerator = createRuntimeGenerator({
   localeInit: (defaultLocale) => `const [__currentLocale, __setCurrentLocale] = createSignal('${defaultLocale}')`,
   loadingInit: 'const [__loading, __setLoading] = createSignal(false)',
   catalogUpdate: (msgs) => `__setCatalog(reconcile(${msgs}))`,
-  catalogMerge: (msgs) => `__setCatalog(reconcile({ ...__catalog, ...${msgs} }))`,
   localeUpdate: (locale) => `__setCurrentLocale(${locale})`,
   loadingUpdate: (value) => `__setLoading(${value})`,
   localeRead: '__currentLocale()',

package/src/trans.tsx

@@ -46,6 +46,8 @@ interface TagToken {
 
 type Token = TextToken | TagToken
 
+const MAX_TOKEN_DEPTH = 100
+
 /**
  * Parse a message string containing XML-like tags into a token tree.
  *
@@ -54,7 +56,11 @@ type Token = TextToken | TagToken
  * - Self-closing tags: `<br/>`
  * - Nested tags: `<bold>hello <italic>world</italic></bold>`
  */
-function parseTokens(input: string): readonly Token[] {
+function parseTokens(input: string, depth: number = 0): readonly Token[] {
+  if (depth > MAX_TOKEN_DEPTH) {
+    // Bail out as plain text to prevent stack overflow
+    return [{ type: 'text', value: input }]
+  }
   const tokens: Token[] = []
   let pos = 0
 
@@ -106,7 +112,7 @@ function parseTokens(input: string): readonly Token[] {
     tokens.push({
       type: 'tag',
       name: tagName,
-      children: parseTokens(innerContent),
+      children: parseTokens(innerContent, depth + 1),
     })
     pos = innerEnd + closingTag.length
   }