@xndrjs/i18n-react 0.8.0-alpha.0

package/bin/codegen.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const script = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../src/codegen/generate-react-bindings.ts"
+);
+
+const result = spawnSync("tsx", [script, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+process.exit(result.status ?? 1);

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+import { ReactNode, ForwardedRef, ForwardRefExoticComponent, RefAttributes } from 'react';
+import { I18nCreateInput, OnMissingTranslation, FetchArtifact } from '@xndrjs/i18n';
+
+/**
+ * Internal runtime types for `@xndrjs/i18n-react` implementation modules.
+ */
+/** Locale-bound multi-namespace `t(ns, key, …)`. */
+type ScopedTranslateFn = (namespace: string, key: string, params?: Record<string, unknown>) => string;
+/** Partition key for load deduplication — locale (or delivery area when custom). */
+type LoadPartition = string | undefined;
+/** Key inputs for load deduplication. */
+interface LoadCoordinatorKey {
+    engineRef: unknown;
+    partition: LoadPartition;
+    namespaces: readonly string[];
+}
+/** Request payload for {@link createLoadCoordinator.ensure}. */
+interface LoadCoordinatorRequest<Scope> extends LoadCoordinatorKey {
+    load: () => Promise<Scope>;
+    /**
+     * Optional sync resolve for already-seeded resources. When it returns a scope,
+     * the entry is marked resolved on the same snapshot (no pending → fallback flash).
+     */
+    tryResolveSync?: () => Scope | null;
+}
+/** Snapshot of a coordinator cache entry. */
+type LoadCoordinatorEntry<Scope> = {
+    status: "pending";
+} | {
+    status: "resolved";
+    scope: Scope;
+} | {
+    status: "error";
+    error: unknown;
+};
+/** Display entry for gates — includes keep-previous and stable bound `t`. */
+type LoadDisplayEntry<Scope> = {
+    status: "pending";
+    display: {
+        scope: Scope;
+        locale: string;
+    } | null;
+    pendingLocale: string | undefined;
+    t: ScopedTranslateFn | null;
+} | {
+    status: "ready";
+    scope: Scope;
+    locale: string;
+    pendingLocale?: undefined;
+    t: ScopedTranslateFn;
+} | {
+    status: "error";
+    error: unknown;
+    display: {
+        scope: Scope;
+        locale: string;
+    } | null;
+    pendingLocale: string | undefined;
+    t: ScopedTranslateFn | null;
+    retry: () => void;
+};
+/** Options for building a display entry (namespace-bound `t`). */
+interface GetDisplayEntryOptions {
+    locale: string;
+    namespaces: readonly string[];
+    /** When false, do not keep previous scope across partition changes (default true). */
+    keepPrevious?: boolean;
+}
+/** Mutable load coordinator returned by {@link createLoadCoordinator}. */
+interface LoadCoordinator<Scope> {
+    readonly revision: number;
+    /** @deprecated Prefer {@link ensure}. */
+    request(input: LoadCoordinatorRequest<Scope>): void;
+    /** Idempotent: start load if missing. Safe from getSnapshot. */
+    ensure(input: LoadCoordinatorRequest<Scope>): void;
+    getEntry(key: LoadCoordinatorKey): LoadCoordinatorEntry<Scope>;
+    getDisplayEntry(key: LoadCoordinatorKey, options: GetDisplayEntryOptions): LoadDisplayEntry<Scope>;
+    /** Evict entry so the next ensure() re-fetches. */
+    retry(key: LoadCoordinatorKey): void;
+    subscribe(listener: () => void): () => void;
+    getPromise(): Promise<Scope>;
+    getResolvedScope(): Scope | null;
+}
+/** Options for {@link createScopedT}. */
+interface CreateScopedTOptions {
+    namespaces: readonly string[];
+    locale: string;
+}
+/** Minimal scope shape used by {@link createScopedT}. */
+interface ScopedScopeLike {
+    t: (...args: unknown[]) => string;
+    forLocale?: (locale: string) => ScopedScopeLike;
+    locale?: string;
+}
+/** Factory passed to {@link I18nRootProvider} — typically codegen `createI18n`. */
+type CreateI18nFactory = (options?: any) => unknown;
+/** Minimal handle shape from `@xndrjs/i18n` createI18n(). */
+interface I18nHandleLike {
+    load: (input: {
+        namespaces: readonly string[];
+        locale: string;
+    }) => Promise<ScopedScopeLike>;
+    peek: (input: {
+        namespaces: readonly string[];
+        locale: string;
+    }) => ScopedScopeLike | null;
+    serialize: () => {
+        dictionary: unknown;
+        resources: readonly (readonly [string, string])[];
+    };
+}
+/** Single React context value for the lazy i18n tree. */
+interface I18nRootContextValue {
+    handle: I18nHandleLike;
+    coordinator: LoadCoordinator<ScopedScopeLike>;
+    locale: string;
+}
+
+/**
+ * Builds the scoped `t` function used by providers and load gates.
+ *
+ * Takes a loaded `@xndrjs/i18n` scope and returns a capability-safe translator:
+ * namespaces outside the provider list throw at runtime. Locale is always bound.
+ */
+
+/**
+ * Wraps a loaded scope `t` with namespace guards and locale binding.
+ */
+declare function createScopedT(scope: ScopedScopeLike, options: CreateScopedTOptions): ScopedTranslateFn;
+/**
+ * Curries a multi-namespace context `t(ns, key, …)` into a namespace-bound `t(key, …)`.
+ * Used when composing gate values without introducing a separate hooks API.
+ */
+declare function bindNamespaceTranslate(t: ScopedTranslateFn, namespace: string): (key: string, params?: Record<string, unknown>) => string;
+
+/**
+ * Dedupes in-flight loads by `(engineRef, partition, namespaces)` and exposes
+ * display snapshots + retry for manual pending/resolved/error rendering.
+ */
+declare function createLoadCoordinator<Scope = ScopedScopeLike>(): LoadCoordinator<Scope>;
+
+/**
+ * Manual (non-Suspense) i18n load gate: ensure + subscribe via the load
+ * coordinator, then render fallback / keep-previous / error UI.
+ */
+
+/** Inputs for {@link useNamespaceLoad}. */
+interface UseNamespaceLoadInput<Scope> {
+    coordinator: LoadCoordinator<Scope>;
+    engineRef: unknown;
+    partition: LoadPartition;
+    namespaces: readonly string[];
+    locale: string;
+    load: () => Promise<Scope>;
+    tryResolveSync?: () => Scope | null;
+    keepPrevious?: boolean;
+}
+/**
+ * Starts (or reuses) a coordinator load and re-renders when that entry settles.
+ * Kick-off is idempotent inside the snapshot getter (safe with useSyncExternalStore).
+ */
+declare function useNamespaceLoad<Scope>(input: UseNamespaceLoadInput<Scope>): LoadDisplayEntry<Scope>;
+/** Scoped `{ t, locale }` injected into gate children / HOC when ready (or kept). */
+interface I18nLoadGateValue {
+    t: ScopedTranslateFn;
+    locale: string;
+    /** Set during keep-then-switch while a new partition is loading. */
+    pendingLocale?: string;
+    error?: unknown;
+    retry?: () => void;
+}
+/** Load wiring from React context (coordinator, engine, partition, load). */
+interface I18nLoadArgs {
+    coordinator: LoadCoordinator<ScopedScopeLike>;
+    engineRef: unknown;
+    partition: LoadPartition;
+    locale: string;
+    load: (namespaces: readonly string[]) => Promise<ScopedScopeLike>;
+    tryResolveSync?: (namespaces: readonly string[]) => ScopedScopeLike | null;
+}
+interface CreateI18nLoadGateOptions {
+    /**
+     * When true (default), keep last resolved `{ t, locale }` while a new
+     * partition is pending instead of showing fallback.
+     */
+    keepPreviousOnPartitionChange?: boolean;
+    /** Hook that resolves coordinator + load inputs from React context. */
+    useLoadArgs: () => I18nLoadArgs;
+}
+interface I18nGateProps {
+    namespaces: readonly string[];
+    fallback?: ReactNode;
+    /** When set, called for error with no keep-previous display. */
+    renderError?: (args: {
+        error: unknown;
+        retry: () => void;
+    }) => ReactNode;
+    children: (value: I18nLoadGateValue) => ReactNode;
+}
+/** Pending UI for `withI18n` — static node or derived from own props. */
+type WithI18nFallback<P extends object> = ReactNode | ((props: P) => ReactNode);
+interface I18nHocOptions<P extends object = object> {
+    namespaces: readonly string[];
+    fallback?: WithI18nFallback<P>;
+    renderError?: (args: {
+        error: unknown;
+        retry: () => void;
+        props: P;
+    }) => ReactNode;
+}
+/** Render fn for `withI18n`: own props, i18n bag, optional forwarded ref. */
+type WithI18nRender<P extends object, R = never> = (props: P, i18n: I18nLoadGateValue, ref?: ForwardedRef<R>) => ReactNode;
+/**
+ * Factory for generic `I18n` gate + `withI18n` HOC over the same Outer.
+ * Codegen emits typed wrappers; tests use this directly.
+ */
+declare function createI18nLoadGate(options: CreateI18nLoadGateOptions): {
+    I18n: (props: I18nGateProps) => ReactNode;
+    withI18n: <P extends object = object, R = never>(hocOptions: I18nHocOptions<P>, render: WithI18nRender<P, R>) => ForwardRefExoticComponent<P & RefAttributes<R>>;
+};
+
+/** Resolves the shared root from an ancestor {@link I18nRootProvider}. */
+declare function useI18nRootContext(): I18nRootContextValue;
+
+/**
+ * Single provider that shares handle + coordinator + locale across a lazy subtree.
+ */
+
+interface I18nRootProviderProps {
+    createI18n: CreateI18nFactory;
+    locale: string;
+    /**
+     * Cold-start / eager dictionary seed (defaults to `{}` when neither prop is set).
+     * Mutually exclusive with {@link state}.
+     */
+    dictionary?: Record<string, unknown>;
+    /** Full create/hydrate input from `handle.serialize()` — mutually exclusive with {@link dictionary}. */
+    state?: I18nCreateInput | undefined;
+    onMissing?: OnMissingTranslation;
+    /** Custom JSON loader for `loaderStrategy: "fetch"` projects (ignored by import loaders). */
+    fetchImpl?: FetchArtifact;
+    children: ReactNode;
+}
+/** Creates and shares one handle + load coordinator for descendant gates. */
+declare function I18nRootProvider({ createI18n, locale, dictionary, state, onMissing, fetchImpl, children, }: I18nRootProviderProps): ReactNode;
+
+export { type I18nGateProps, type I18nHocOptions, type I18nLoadGateValue, I18nRootProvider, type I18nRootProviderProps, type WithI18nFallback, type WithI18nRender, bindNamespaceTranslate, createI18nLoadGate, createLoadCoordinator, createScopedT, useI18nRootContext, useNamespaceLoad };

package/dist/index.js

@@ -0,0 +1,418 @@
+"use client";
+import { createContext, useSyncExternalStore, useContext, useRef, forwardRef } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/create-scoped-t.ts
+function assertNamespace(namespace, namespaces) {
+  if (!namespaces.includes(namespace)) {
+    throw new Error(
+      `Namespace "${namespace}" is not loaded by this provider. Allowed: [${namespaces.join(", ")}]`
+    );
+  }
+}
+function resolveActiveScope(scope, locale) {
+  if (typeof scope.forLocale === "function" && scope.locale !== locale) {
+    return scope.forLocale(locale);
+  }
+  return scope;
+}
+function createScopedT(scope, options) {
+  const activeScope = resolveActiveScope(scope, options.locale);
+  const { namespaces } = options;
+  return ((namespace, key, ...rest) => {
+    assertNamespace(namespace, namespaces);
+    return activeScope.t(namespace, key, ...rest);
+  });
+}
+function bindNamespaceTranslate(t, namespace) {
+  return (key, params) => params === void 0 ? t(namespace, key) : t(namespace, key, params);
+}
+
+// src/create-load-coordinator.ts
+var engineIds = /* @__PURE__ */ new WeakMap();
+var nextEngineId = 1;
+function engineId(ref) {
+  if (ref === null || typeof ref !== "object" && typeof ref !== "function") {
+    return 0;
+  }
+  const obj = ref;
+  let id = engineIds.get(obj);
+  if (id === void 0) {
+    id = nextEngineId++;
+    engineIds.set(obj, id);
+  }
+  return id;
+}
+function cacheKey(engineRef, partition, namespaces) {
+  return `${engineId(engineRef)}\0${partition ?? ""}\0${namespaces.join("\0")}`;
+}
+function gateId(engineRef, namespaces) {
+  return `${engineId(engineRef)}\0${namespaces.join("\0")}`;
+}
+function createLoadCoordinator() {
+  let revision = 0;
+  let nextRequestId = 0;
+  const entries = /* @__PURE__ */ new Map();
+  const displayByGate = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let lastKey = null;
+  function notify() {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function bumpAndNotify() {
+    revision += 1;
+    for (const display of displayByGate.values()) {
+      display.displaySnapshot = null;
+      display.displayKey = null;
+    }
+    notify();
+  }
+  function ensure(input) {
+    const key = cacheKey(input.engineRef, input.partition, input.namespaces);
+    lastKey = key;
+    const existing = entries.get(key);
+    if (existing !== void 0) {
+      return;
+    }
+    if (input.tryResolveSync !== void 0) {
+      const syncScope = input.tryResolveSync();
+      if (syncScope !== null) {
+        const entrySnapshot = {
+          status: "resolved",
+          scope: syncScope
+        };
+        entries.set(key, {
+          status: "resolved",
+          promise: Promise.resolve(syncScope),
+          resolvedScope: syncScope,
+          error: null,
+          requestId: ++nextRequestId,
+          entrySnapshot
+        });
+        return;
+      }
+    }
+    const requestId = ++nextRequestId;
+    const promise = input.load().then(
+      (scope) => {
+        const entry = entries.get(key);
+        if (entry === void 0 || entry.requestId !== requestId) {
+          return scope;
+        }
+        entry.status = "resolved";
+        entry.resolvedScope = scope;
+        entry.error = null;
+        entry.entrySnapshot = { status: "resolved", scope };
+        bumpAndNotify();
+        return scope;
+      },
+      (error) => {
+        const entry = entries.get(key);
+        if (entry !== void 0 && entry.requestId === requestId) {
+          entry.status = "error";
+          entry.error = error;
+          entry.resolvedScope = null;
+          entry.entrySnapshot = { status: "error", error };
+          bumpAndNotify();
+        }
+        throw error;
+      }
+    );
+    void promise.catch(() => void 0);
+    entries.set(key, {
+      status: "pending",
+      promise,
+      resolvedScope: null,
+      error: null,
+      requestId,
+      entrySnapshot: { status: "pending" }
+    });
+  }
+  function getEntry(keyInput) {
+    const key = cacheKey(keyInput.engineRef, keyInput.partition, keyInput.namespaces);
+    const entry = entries.get(key);
+    if (entry === void 0) {
+      return { status: "pending" };
+    }
+    return entry.entrySnapshot;
+  }
+  function getOrCreateDisplay(engineRef, namespaces) {
+    const id = gateId(engineRef, namespaces);
+    let display = displayByGate.get(id);
+    if (display === void 0) {
+      display = {
+        lastReady: null,
+        displaySnapshot: null,
+        displayKey: null,
+        boundT: null,
+        boundTKey: null
+      };
+      displayByGate.set(id, display);
+    }
+    return display;
+  }
+  function bindT(display, scope, locale, namespaces, scopeToken) {
+    const tKey = `${scopeToken}\0${locale}\0${namespaces.join("\0")}`;
+    if (display.boundT !== null && display.boundTKey === tKey) {
+      return display.boundT;
+    }
+    const t = createScopedT(scope, { namespaces, locale });
+    display.boundT = t;
+    display.boundTKey = tKey;
+    return t;
+  }
+  function getDisplayEntry(keyInput, options) {
+    const key = cacheKey(keyInput.engineRef, keyInput.partition, keyInput.namespaces);
+    const entry = entries.get(key);
+    const display = getOrCreateDisplay(keyInput.engineRef, options.namespaces);
+    const keepPrevious = options.keepPrevious !== false;
+    const retry = () => {
+      retryKey(keyInput);
+    };
+    let result;
+    if (entry === void 0 || entry.status === "pending") {
+      const kept = keepPrevious ? display.lastReady : null;
+      result = {
+        status: "pending",
+        display: kept,
+        pendingLocale: kept ? options.locale : void 0,
+        t: kept ? bindT(display, kept.scope, kept.locale, options.namespaces, `kept:${kept.locale}`) : null
+      };
+    } else if (entry.status === "resolved") {
+      const scope = entry.resolvedScope;
+      display.lastReady = { scope, locale: options.locale };
+      result = {
+        status: "ready",
+        scope,
+        locale: options.locale,
+        t: bindT(display, scope, options.locale, options.namespaces, `ready:${key}`)
+      };
+    } else {
+      const kept = keepPrevious ? display.lastReady : null;
+      result = {
+        status: "error",
+        error: entry.error,
+        display: kept,
+        pendingLocale: kept ? options.locale : void 0,
+        t: kept ? bindT(display, kept.scope, kept.locale, options.namespaces, `kept:${kept.locale}`) : null,
+        retry
+      };
+    }
+    const displayKey = `${key}\0${result.status}\0${options.locale}\0${String(!!result.t)}`;
+    if (display.displaySnapshot !== null && display.displayKey === displayKey) {
+      return display.displaySnapshot;
+    }
+    display.displaySnapshot = result;
+    display.displayKey = displayKey;
+    return result;
+  }
+  function retryKey(keyInput) {
+    const key = cacheKey(keyInput.engineRef, keyInput.partition, keyInput.namespaces);
+    if (!entries.has(key)) {
+      return;
+    }
+    entries.delete(key);
+    bumpAndNotify();
+  }
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  function getPromise() {
+    if (lastKey === null) {
+      throw new Error("createLoadCoordinator: call ensure()/request() before getPromise()");
+    }
+    const entry = entries.get(lastKey);
+    if (entry === void 0) {
+      throw new Error("createLoadCoordinator: call ensure()/request() before getPromise()");
+    }
+    return entry.promise;
+  }
+  function getResolvedScope() {
+    if (lastKey === null) {
+      return null;
+    }
+    const entry = entries.get(lastKey);
+    return entry?.status === "resolved" ? entry.resolvedScope : null;
+  }
+  return {
+    get revision() {
+      return revision;
+    },
+    request: ensure,
+    ensure,
+    getEntry,
+    getDisplayEntry,
+    retry: retryKey,
+    subscribe,
+    getPromise,
+    getResolvedScope
+  };
+}
+function useNamespaceLoad(input) {
+  const {
+    coordinator,
+    engineRef,
+    partition,
+    namespaces,
+    locale,
+    load,
+    tryResolveSync,
+    keepPrevious
+  } = input;
+  const request = {
+    engineRef,
+    partition,
+    namespaces,
+    load,
+    ...tryResolveSync !== void 0 ? { tryResolveSync } : {}
+  };
+  return useSyncExternalStore(
+    coordinator.subscribe,
+    () => {
+      coordinator.ensure(request);
+      return coordinator.getDisplayEntry(
+        { engineRef, partition, namespaces },
+        {
+          locale,
+          namespaces,
+          ...keepPrevious !== void 0 ? { keepPrevious } : {}
+        }
+      );
+    },
+    () => {
+      coordinator.ensure(request);
+      return coordinator.getDisplayEntry(
+        { engineRef, partition, namespaces },
+        {
+          locale,
+          namespaces,
+          ...keepPrevious !== void 0 ? { keepPrevious } : {}
+        }
+      );
+    }
+  );
+}
+function resolveNamespaces(namespaces) {
+  if (namespaces === void 0 || namespaces.length === 0) {
+    throw new Error("withI18n / I18n: requires a non-empty namespaces list");
+  }
+  return namespaces;
+}
+function renderDisplayEntry(entry, options) {
+  if (entry.status === "ready") {
+    return options.children({ t: entry.t, locale: entry.locale });
+  }
+  if (entry.status === "error" && entry.t === null) {
+    if (options.renderError) {
+      return options.renderError({ error: entry.error, retry: entry.retry });
+    }
+    return options.fallback ?? null;
+  }
+  if (entry.t !== null && entry.display) {
+    const value = {
+      t: entry.t,
+      locale: entry.display.locale
+    };
+    if (entry.pendingLocale !== void 0) {
+      value.pendingLocale = entry.pendingLocale;
+    }
+    if (entry.status === "error") {
+      value.error = entry.error;
+      value.retry = entry.retry;
+    }
+    return options.children(value);
+  }
+  return options.fallback ?? null;
+}
+function createI18nLoadGate(options) {
+  const { useLoadArgs } = options;
+  const keepPrevious = options.keepPreviousOnPartitionChange !== false;
+  function useGateEntry(namespaces) {
+    const resolved = resolveNamespaces(namespaces);
+    const args = useLoadArgs();
+    return useNamespaceLoad({
+      coordinator: args.coordinator,
+      engineRef: args.engineRef,
+      partition: args.partition,
+      namespaces: resolved,
+      locale: args.locale,
+      load: () => args.load(resolved),
+      ...args.tryResolveSync !== void 0 ? { tryResolveSync: () => args.tryResolveSync(resolved) } : {},
+      keepPrevious
+    });
+  }
+  function I18n({ namespaces, fallback, renderError, children }) {
+    const entry = useGateEntry(namespaces);
+    return renderDisplayEntry(entry, {
+      ...fallback !== void 0 ? { fallback } : {},
+      ...renderError !== void 0 ? { renderError } : {},
+      children
+    });
+  }
+  function withI18n(hocOptions, render) {
+    const { fallback, renderError } = hocOptions;
+    const Outer = forwardRef(function I18nHocOuter(props, ref) {
+      const entry = useGateEntry(hocOptions.namespaces);
+      const needsFallback = entry.status !== "ready" && entry.t === null;
+      const resolvedFallback = !needsFallback || fallback === void 0 ? void 0 : typeof fallback === "function" ? fallback(props) : fallback;
+      return renderDisplayEntry(entry, {
+        ...resolvedFallback !== void 0 ? { fallback: resolvedFallback } : {},
+        ...renderError !== void 0 ? {
+          renderError: ({ error, retry }) => renderError({ error, retry, props })
+        } : {},
+        children: (value) => render(props, value, ref)
+      });
+    });
+    const displayName = render.name || "Component";
+    Outer.displayName = `withI18n(${displayName})`;
+    return Outer;
+  }
+  return { I18n, withI18n };
+}
+var I18nRootContext = createContext(null);
+function useI18nRootContext() {
+  const value = useContext(I18nRootContext);
+  if (value === null) {
+    throw new Error("useI18nRoot must be used within I18nRoot / I18nRootProvider");
+  }
+  return value;
+}
+function I18nRootProvider({
+  createI18n,
+  locale,
+  dictionary,
+  state,
+  onMissing,
+  fetchImpl,
+  children
+}) {
+  if (state !== void 0 && dictionary !== void 0) {
+    throw new Error("I18nRootProvider: pass either `state` or `dictionary`, not both.");
+  }
+  const valueRef = useRef(null);
+  if (valueRef.current === null) {
+    const seed = state ?? { dictionary: dictionary ?? {} };
+    const handle = createI18n({
+      state: seed,
+      ...onMissing !== void 0 ? { onMissing } : {},
+      ...fetchImpl !== void 0 ? { fetchImpl } : {}
+    });
+    valueRef.current = {
+      handle,
+      coordinator: createLoadCoordinator(),
+      locale
+    };
+  } else {
+    valueRef.current.locale = locale;
+  }
+  return /* @__PURE__ */ jsx(I18nRootContext.Provider, { value: valueRef.current, children });
+}
+
+export { I18nRootProvider, bindNamespaceTranslate, createI18nLoadGate, createLoadCoordinator, createScopedT, useI18nRootContext, useNamespaceLoad };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map