@fluenti/solid 0.1.0

package/src/select.tsx

@@ -0,0 +1,90 @@
+import type { Component, JSX } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+import { hashMessage } from '@fluenti/core'
+import { useI18n } from './use-i18n'
+import { buildICUSelectMessage, normalizeSelectForms, reconstruct, serializeRichForms } from './rich-dom'
+
+/** Props for the `<Select>` component */
+export interface SelectProps {
+  /** The value to match against prop keys */
+  value: string
+  /** Override the auto-generated synthetic ICU message id */
+  id?: string
+  /** Message context used for identity and translator disambiguation */
+  context?: string
+  /** Translator-facing note preserved in extraction catalogs */
+  comment?: string
+  /** Fallback message when no key matches */
+  other: string | JSX.Element
+  /**
+   * Named options map. Keys are match values, values are display strings or JSX.
+   * Takes precedence over dynamic attrs when both are provided.
+   *
+   * @example `{ male: 'He', female: 'She' }`
+   */
+  options?: Record<string, string | JSX.Element>
+  /** Wrapper element tag name (default: `span`) */
+  tag?: string
+  /** Additional key/message pairs for matching (attrs fallback) */
+  [key: string]: unknown
+}
+
+/**
+ * Render a message selected by matching `value` against prop keys.
+ *
+ * Options can be provided via the type-safe `options` prop (recommended)
+ * or as direct attrs (convenience). When both are present, `options` takes
+ * precedence.
+ *
+ * Rich text is supported via JSX element values in the `options` prop or
+ * as direct JSX element props:
+ * ```tsx
+ * <Select
+ *   value={gender()}
+ *   options={{
+ *     male: <><strong>He</strong> liked this</>,
+ *     female: <><strong>She</strong> liked this</>,
+ *   }}
+ *   other={<><em>They</em> liked this</>}
+ * />
+ * ```
+ *
+ * Falls back to the `other` prop when no key matches.
+ */
+export const SelectComp: Component<SelectProps> = (props) => {
+  const { t } = useI18n()
+
+  const resolvedTag = () => props.tag ?? 'span'
+
+  const content = () => {
+    const forms: Record<string, unknown> = props.options !== undefined
+      ? { ...props.options, other: props.other }
+      : {
+        ...Object.fromEntries(
+          Object.entries(props).filter(([key]) => !['value', 'id', 'context', 'comment', 'options', 'other', 'tag'].includes(key)),
+        ),
+        other: props.other,
+      }
+
+    const orderedKeys = [...Object.keys(forms).filter(key => key !== 'other'), 'other'] as const
+    const { messages, components } = serializeRichForms(orderedKeys, forms)
+    const normalized = normalizeSelectForms(
+      Object.fromEntries([...orderedKeys].map((key) => [key, messages[key] ?? ''])),
+    )
+    const translated = t(
+      {
+        id: props.id ?? (props.context === undefined
+          ? buildICUSelectMessage(normalized.forms)
+          : hashMessage(buildICUSelectMessage(normalized.forms), props.context)),
+        message: buildICUSelectMessage(normalized.forms),
+        ...(props.context !== undefined ? { context: props.context } : {}),
+        ...(props.comment !== undefined ? { comment: props.comment } : {}),
+      },
+      { value: normalized.valueMap[props.value] ?? 'other' },
+    )
+
+    return components.length > 0 ? reconstruct(translated, components) : translated
+  }
+
+  return (<Dynamic component={resolvedTag()}>{content()}</Dynamic>) as JSX.Element
+}

package/src/server.ts

@@ -0,0 +1,153 @@
+import { createFluent } from '@fluenti/core'
+import type {
+  FluentInstanceExtended,
+  FluentConfigExtended,
+  Locale,
+  Messages,
+  DateFormatOptions,
+  NumberFormatOptions,
+} from '@fluenti/core'
+
+// Re-export SSR utilities from core for convenience
+export { detectLocale, getSSRLocaleScript, getHydratedLocale, isRTL, getDirection } from '@fluenti/core'
+export type { DetectLocaleOptions } from '@fluenti/core'
+
+/**
+ * Configuration for `createServerI18n`.
+ */
+export interface ServerI18nConfig {
+  /** Load messages for a given locale. Called once per locale per request. */
+  loadMessages: (locale: string) => Promise<Messages | { default: Messages }>
+  /** Fallback locale when a translation is missing */
+  fallbackLocale?: string
+  /**
+   * Auto-resolve locale when `setLocale()` was not called.
+   *
+   * This is the fallback for contexts where the layout doesn't run — most
+   * notably `"use server"` functions, which are independent requests
+   * that skip the layout tree entirely.
+   *
+   * Common patterns:
+   * - Read from a cookie via `getRequestEvent()`
+   * - Read from a request header set by middleware
+   *
+   * If omitted and `setLocale()` was not called, `getI18n()` will throw.
+   */
+  resolveLocale?: () => string | Promise<string>
+  /** Custom fallback chains per locale */
+  fallbackChain?: Record<string, Locale[]>
+  /** Custom date format styles */
+  dateFormats?: DateFormatOptions
+  /** Custom number format styles */
+  numberFormats?: NumberFormatOptions
+  /** Handler for missing translation keys */
+  missing?: (locale: Locale, id: string) => string | undefined
+}
+
+/**
+ * The object returned by `createServerI18n`.
+ */
+export interface ServerI18n {
+  /**
+   * Set the locale for the current server request.
+   * Call this once in your entry-server or root layout before any `getI18n()` calls.
+   */
+  setLocale: (locale: string) => void
+
+  /**
+   * Get a fully configured i18n instance for the current request.
+   * Messages are loaded lazily and cached.
+   */
+  getI18n: () => Promise<FluentInstanceExtended & { locale: string }>
+}
+
+/**
+ * Create server-side i18n utilities for SolidStart.
+ *
+ * Unlike React's `createServerI18n` which uses `React.cache()` for RSC
+ * per-request isolation, this version uses a simple module-level store
+ * matching SolidStart's synchronous rendering model.
+ *
+ * For per-request isolation in SolidStart, use `getRequestEvent()` in
+ * your `resolveLocale` callback, or call `setLocale()` in your
+ * entry-server middleware.
+ *
+ * @example
+ * ```ts
+ * // lib/i18n.server.ts
+ * import { createServerI18n } from '@fluenti/solid/server'
+ *
+ * export const { setLocale, getI18n } = createServerI18n({
+ *   loadMessages: (locale) => import(`../locales/compiled/${locale}.ts`),
+ *   fallbackLocale: 'en',
+ * })
+ * ```
+ */
+export function createServerI18n(config: ServerI18nConfig): ServerI18n {
+  let currentLocale: string | null = null
+  let cachedInstance: (FluentInstanceExtended & { locale: string }) | null = null
+  const messageCache = new Map<string, Messages>()
+
+  function setLocale(locale: string): void {
+    currentLocale = locale
+  }
+
+  async function loadLocaleMessages(locale: string): Promise<Messages> {
+    const cached = messageCache.get(locale)
+    if (cached) return cached
+
+    const raw = await config.loadMessages(locale)
+    const messages: Messages =
+      typeof raw === 'object' && raw !== null && 'default' in raw
+        ? (raw as { default: Messages }).default
+        : (raw as Messages)
+
+    messageCache.set(locale, messages)
+    return messages
+  }
+
+  async function getI18n(): Promise<FluentInstanceExtended & { locale: string }> {
+    // If setLocale() was never called, try the resolveLocale fallback.
+    if (!currentLocale && config.resolveLocale) {
+      currentLocale = await config.resolveLocale()
+    }
+
+    const locale = currentLocale
+
+    if (!locale) {
+      throw new Error(
+        '[fluenti] No locale set. Call setLocale(locale) in your entry-server or layout before using getI18n(), ' +
+          'or provide a resolveLocale function in createServerI18n config to auto-detect locale ' +
+          'in server functions and other contexts where the layout does not run.',
+      )
+    }
+
+    // Return cached instance if locale hasn't changed
+    if (cachedInstance && cachedInstance.locale === locale) {
+      return cachedInstance
+    }
+
+    // Load messages for current locale (and fallback if configured)
+    const allMessages: Record<string, Messages> = {}
+    allMessages[locale] = await loadLocaleMessages(locale)
+
+    if (config.fallbackLocale && config.fallbackLocale !== locale) {
+      allMessages[config.fallbackLocale] = await loadLocaleMessages(config.fallbackLocale)
+    }
+
+    const fluentConfig: FluentConfigExtended = {
+      locale,
+      messages: allMessages,
+    }
+    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale
+    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain
+    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats
+    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats
+    if (config.missing !== undefined) fluentConfig.missing = config.missing
+
+    cachedInstance = createFluent(fluentConfig)
+    return cachedInstance
+  }
+
+  return { setLocale, getI18n }
+}

package/src/trans.tsx

@@ -0,0 +1,243 @@
+import { Dynamic } from 'solid-js/web'
+import { children as resolveChildren, createMemo } from 'solid-js'
+import type { Component, JSX } from 'solid-js'
+import { useI18n } from './use-i18n'
+import { extractMessage as extractDomMessage, reconstruct as reconstructDomMessage } from './rich-dom'
+
+/** A Solid component that accepts children */
+export type RichComponent = Component<{ children?: JSX.Element }>
+
+/** Props for the `<Trans>` component */
+export interface TransProps {
+  /** Override auto-generated hash ID */
+  id?: string
+  /** Message context used for identity and translator disambiguation */
+  context?: string
+  /** Translator-facing note preserved in extraction catalogs */
+  comment?: string
+  /** Wrapper element tag name (default: `'span'`) — used in children-only mode */
+  tag?: string
+  /** Children — the content to translate (legacy API) */
+  children?: JSX.Element
+  /** Translated message string with XML-like tags (e.g. `<bold>text</bold>`) */
+  message?: string
+  /** Map of tag names to Solid components */
+  components?: Record<string, RichComponent>
+  /** @internal Pre-computed message from build plugin */
+  __message?: string
+  /** @internal Pre-computed component map from build plugin */
+  __components?: Record<string, RichComponent>
+}
+
+/**
+ * A token from parsing the message string.
+ * Either a plain text segment or a tag with inner content.
+ */
+interface TextToken {
+  readonly type: 'text'
+  readonly value: string
+}
+
+interface TagToken {
+  readonly type: 'tag'
+  readonly name: string
+  readonly children: readonly Token[]
+}
+
+type Token = TextToken | TagToken
+
+/**
+ * Parse a message string containing XML-like tags into a token tree.
+ *
+ * Supports:
+ * - Named tags: `<bold>content</bold>`
+ * - Self-closing tags: `<br/>`
+ * - Nested tags: `<bold>hello <italic>world</italic></bold>`
+ */
+function parseTokens(input: string): readonly Token[] {
+  const tokens: Token[] = []
+  let pos = 0
+
+  while (pos < input.length) {
+    const openIdx = input.indexOf('<', pos)
+
+    if (openIdx === -1) {
+      // No more tags — rest is plain text
+      tokens.push({ type: 'text', value: input.slice(pos) })
+      break
+    }
+
+    // Push any text before this tag
+    if (openIdx > pos) {
+      tokens.push({ type: 'text', value: input.slice(pos, openIdx) })
+    }
+
+    // Check for self-closing tag: <tagName/>
+    const selfCloseMatch = input.slice(openIdx).match(/^<(\w+)\s*\/>/)
+    if (selfCloseMatch) {
+      tokens.push({ type: 'tag', name: selfCloseMatch[1]!, children: [] })
+      pos = openIdx + selfCloseMatch[0].length
+      continue
+    }
+
+    // Check for opening tag: <tagName>
+    const openMatch = input.slice(openIdx).match(/^<(\w+)>/)
+    if (!openMatch) {
+      // Not a valid tag — treat '<' as text
+      tokens.push({ type: 'text', value: '<' })
+      pos = openIdx + 1
+      continue
+    }
+
+    const tagName = openMatch[1]!
+    const contentStart = openIdx + openMatch[0].length
+
+    // Find the matching closing tag, respecting nesting
+    const innerEnd = findClosingTag(input, tagName, contentStart)
+    if (innerEnd === -1) {
+      // No closing tag found — treat as plain text
+      tokens.push({ type: 'text', value: input.slice(openIdx, contentStart) })
+      pos = contentStart
+      continue
+    }
+
+    const innerContent = input.slice(contentStart, innerEnd)
+    const closingTag = `</${tagName}>`
+    tokens.push({
+      type: 'tag',
+      name: tagName,
+      children: parseTokens(innerContent),
+    })
+    pos = innerEnd + closingTag.length
+  }
+
+  return tokens
+}
+
+/**
+ * Find the position of the matching closing tag, accounting for nesting
+ * of the same tag name.
+ *
+ * Returns the index of the start of the closing tag, or -1 if not found.
+ */
+function findClosingTag(input: string, tagName: string, startPos: number): number {
+  const openTag = `<${tagName}>`
+  const closeTag = `</${tagName}>`
+  let depth = 1
+  let pos = startPos
+
+  while (pos < input.length && depth > 0) {
+    const nextOpen = input.indexOf(openTag, pos)
+    const nextClose = input.indexOf(closeTag, pos)
+
+    if (nextClose === -1) return -1
+
+    if (nextOpen !== -1 && nextOpen < nextClose) {
+      depth++
+      pos = nextOpen + openTag.length
+    } else {
+      depth--
+      if (depth === 0) return nextClose
+      pos = nextClose + closeTag.length
+    }
+  }
+
+  return -1
+}
+
+/**
+ * Render a token tree into Solid JSX elements using the components map.
+ */
+function renderTokens(
+  tokens: readonly Token[],
+  components: Record<string, RichComponent>,
+): JSX.Element {
+  const elements = tokens.map((token): JSX.Element => {
+    if (token.type === 'text') {
+      return token.value as unknown as JSX.Element
+    }
+
+    const Comp = components[token.name]
+    if (!Comp) {
+      // Unknown component — render inner content as plain text
+      return renderTokens(token.children, components)
+    }
+
+    const innerContent = token.children.length > 0
+      ? renderTokens(token.children, components)
+      : undefined
+
+    return (<Dynamic component={Comp}>{innerContent}</Dynamic>) as JSX.Element
+  })
+
+  if (elements.length === 1) return elements[0]!
+  return (<>{elements}</>) as JSX.Element
+}
+
+/**
+ * Render translated content with inline components.
+ *
+ * Supports two APIs:
+ *
+ * 1. **message + components** (recommended for rich text):
+ * ```tsx
+ * <Trans
+ *   message={t`Welcome to <bold>Fluenti</bold>!`}
+ *   components={{ bold: (props) => <strong>{props.children}</strong> }}
+ * />
+ * ```
+ *
+ * 2. **children** (legacy / simple passthrough):
+ * ```tsx
+ * <Trans>Click <a href="/next">here</a> to continue</Trans>
+ * ```
+ */
+export const Trans: Component<TransProps> = (props) => {
+  const { t } = useI18n()
+  const resolvedChildren = resolveChildren(() => props.children)
+  // message + components API (including build-time __message/__components)
+  // Note: the vite-plugin tagged-template transform wraps Solid expressions in
+  // createMemo(), so props.message may be a memo accessor (function) instead of
+  // a string. We unwrap it here to handle both cases.
+  const message = createMemo(() => {
+    const raw = props.__message ?? props.message
+    return typeof raw === 'function' ? (raw as () => string)() : raw
+  })
+  const components = createMemo(() => props.__components ?? props.components)
+
+  return (() => {
+    const msg = message()
+    const comps = components()
+
+    if (msg !== undefined && comps) {
+      const translated = t({
+        ...(props.id !== undefined ? { id: props.id } : {}),
+        message: msg,
+        ...(props.context !== undefined ? { context: props.context } : {}),
+        ...(props.comment !== undefined ? { comment: props.comment } : {}),
+      })
+      const tokens = parseTokens(translated)
+      return renderTokens(tokens, comps)
+    }
+
+    // Fallback: children-only API with runtime extraction/reconstruction
+    const children = resolvedChildren.toArray()
+    if (children.length === 0) return null
+    const extracted = extractDomMessage(children)
+    const translated = t({
+      ...(props.id !== undefined ? { id: props.id } : {}),
+      message: extracted.message,
+      ...(props.context !== undefined ? { context: props.context } : {}),
+      ...(props.comment !== undefined ? { comment: props.comment } : {}),
+    })
+    const result = extracted.components.length > 0
+      ? reconstructDomMessage(translated, extracted.components)
+      : translated
+
+    if (Array.isArray(result) && result.length > 1) {
+      return (<Dynamic component={props.tag ?? 'span'}>{result}</Dynamic>) as JSX.Element
+    }
+
+    return result as JSX.Element
+  }) as unknown as JSX.Element
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+import type { Accessor } from 'solid-js'
+import type {
+  FluentConfig,
+  Locale,
+  Messages,
+  CompiledMessage,
+  MessageDescriptor,
+  DateFormatOptions,
+  NumberFormatOptions,
+} from '@fluenti/core'
+
+/** Chunk loader for lazy locale loading */
+export type ChunkLoader = (
+  locale: string,
+) => Promise<Record<string, CompiledMessage> | { default: Record<string, CompiledMessage> }>
+
+/** Extended config with lazy locale loading support */
+export interface I18nConfig extends FluentConfig {
+  /** Async chunk loader for lazy locale loading */
+  chunkLoader?: ChunkLoader
+  /** Enable lazy locale loading through chunkLoader */
+  lazyLocaleLoading?: boolean
+  /** Named date format styles */
+  dateFormats?: DateFormatOptions
+  /** Named number format styles */
+  numberFormats?: NumberFormatOptions
+}
+
+/** Reactive i18n context holding locale signal and translation utilities */
+export interface I18nContext {
+  /** Reactive accessor for the current locale */
+  locale(): Locale
+  /** Set the active locale (async when lazy locale loading is enabled) */
+  setLocale(locale: Locale): Promise<void>
+  /** Translate a message by id with optional interpolation values */
+  t(id: string | MessageDescriptor, values?: Record<string, unknown>): string
+  /** Tagged template form: t`Hello ${name}` */
+  t(strings: TemplateStringsArray, ...exprs: unknown[]): string
+  /** Merge additional messages into a locale catalog at runtime */
+  loadMessages(locale: Locale, messages: Messages): void
+  /** Return all locale codes that have loaded messages */
+  getLocales(): Locale[]
+  /** Format a date value for the current locale */
+  d(value: Date | number, style?: string): string
+  /** Format a number value for the current locale */
+  n(value: number, style?: string): string
+  /** Format an ICU message string directly (no catalog lookup) */
+  format(message: string, values?: Record<string, unknown>): string
+  /** Whether a locale chunk is currently being loaded */
+  isLoading: Accessor<boolean>
+  /** Set of locales whose messages have been loaded */
+  loadedLocales: Accessor<Set<string>>
+  /** Preload a locale in the background without switching to it */
+  preloadLocale(locale: string): void
+}

package/src/use-i18n.ts

@@ -0,0 +1,30 @@
+import { useContext } from 'solid-js'
+import { I18nCtx } from './provider'
+import { getGlobalI18nContext } from './context'
+import type { I18nContext } from './context'
+
+/**
+ * Access the i18n context.
+ *
+ * Resolution order:
+ * 1. Nearest `<I18nProvider>` in the component tree
+ * 2. Module-level singleton created by `createI18n()`
+ *
+ * Throws if neither is available.
+ */
+export function useI18n(): I18nContext {
+  const ctx = useContext(I18nCtx)
+  if (ctx) {
+    return ctx
+  }
+
+  const global = getGlobalI18nContext()
+  if (global) {
+    return global
+  }
+
+  throw new Error(
+    'useI18n requires either createI18n() to be called at startup, ' +
+    'or the component to be inside an <I18nProvider>.',
+  )
+}

package/src/vite-runtime.d.ts

@@ -0,0 +1,4 @@
+declare module 'virtual:fluenti/runtime' {
+  export const __switchLocale: ((locale: string) => Promise<void>) | undefined
+  export const __preloadLocale: ((locale: string) => Promise<void>) | undefined
+}