@xndrjs/i18n-react 0.8.1 → 0.8.2-alpha.0

package/src/namespace-load-gate.tsx

@@ -1,265 +0,0 @@
-/**
- * Manual (non-Suspense) i18n load gate: ensure + subscribe via the load
- * coordinator, then render fallback / keep-previous / error UI / throw.
- */
-import {
-  forwardRef,
-  useSyncExternalStore,
-  type ForwardedRef,
-  type ForwardRefExoticComponent,
-  type ReactNode,
-  type RefAttributes,
-} from "react";
-import type {
-  LoadCoordinator,
-  LoadCoordinatorRequest,
-  LoadDisplayEntry,
-  LoadPartition,
-  ScopedScopeLike,
-  ScopedTranslateFn,
-} from "./types.js";
-
-/** Inputs for {@link useNamespaceLoad}. */
-export 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.
- * Client getSnapshot may kick `load()`; SSR getServerSnapshot only peeks sync
- * (hydrated `state`) and never starts a client fetch during prerender.
- */
-export function useNamespaceLoad<Scope>(
-  input: UseNamespaceLoadInput<Scope>
-): LoadDisplayEntry<Scope> {
-  const {
-    coordinator,
-    engineRef,
-    partition,
-    namespaces,
-    locale,
-    load,
-    tryResolveSync,
-    keepPrevious,
-  } = input;
-
-  const request: LoadCoordinatorRequest<Scope> = {
-    engineRef,
-    partition,
-    namespaces,
-    load,
-    ...(tryResolveSync !== undefined ? { tryResolveSync } : {}),
-  };
-
-  const displayOptions = {
-    locale,
-    namespaces,
-    ...(keepPrevious !== undefined ? { keepPrevious } : {}),
-  };
-
-  return useSyncExternalStore(
-    coordinator.subscribe,
-    () => {
-      coordinator.ensure(request);
-      return coordinator.getDisplayEntry({ engineRef, partition, namespaces }, displayOptions);
-    },
-    () => {
-      coordinator.ensureSync(request);
-      return coordinator.getDisplayEntry({ engineRef, partition, namespaces }, displayOptions);
-    }
-  );
-}
-
-/** Scoped `{ t, locale }` injected into gate children / HOC when ready (or kept). */
-export 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). */
-export interface I18nLoadArgs {
-  coordinator: LoadCoordinator<ScopedScopeLike>;
-  engineRef: unknown;
-  partition: LoadPartition;
-  locale: string;
-  load: (namespaces: readonly string[]) => Promise<ScopedScopeLike>;
-  tryResolveSync?: (namespaces: readonly string[]) => ScopedScopeLike | null;
-}
-
-export 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;
-}
-
-export interface I18nGateProps {
-  namespaces: readonly string[];
-  /** Shown only while the load is pending (not on error). */
-  fallback?: ReactNode;
-  /**
-   * When set, called for error with no keep-previous display.
-   * Otherwise the load error is thrown for a React error boundary.
-   */
-  renderError?: (args: { error: unknown; retry: () => void }) => ReactNode;
-  children: (value: I18nLoadGateValue) => ReactNode;
-}
-
-/** Pending UI for `withI18n` — static node or derived from own props. */
-export type WithI18nFallback<P extends object> = ReactNode | ((props: P) => ReactNode);
-
-export 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. */
-export type WithI18nRender<P extends object, R = never> = (
-  props: P,
-  i18n: I18nLoadGateValue,
-  ref?: ForwardedRef<R>
-) => ReactNode;
-
-function resolveNamespaces(namespaces: readonly string[] | undefined): readonly string[] {
-  if (namespaces === undefined || namespaces.length === 0) {
-    throw new Error("withI18n / I18n: requires a non-empty namespaces list");
-  }
-  return namespaces;
-}
-
-function toThrownError(error: unknown): Error {
-  if (error instanceof Error) {
-    return error;
-  }
-  if (typeof error === "string") {
-    return new Error(error);
-  }
-  return new Error("i18n namespace load failed");
-}
-
-function renderDisplayEntry(
-  entry: LoadDisplayEntry<ScopedScopeLike>,
-  options: {
-    fallback?: ReactNode;
-    renderError?: (args: { error: unknown; retry: () => void }) => ReactNode;
-    children: (value: I18nLoadGateValue) => ReactNode;
-  }
-): ReactNode {
-  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! });
-    }
-    throw toThrownError(entry.error);
-  }
-
-  if (entry.t !== null && entry.display) {
-    const value: I18nLoadGateValue = {
-      t: entry.t,
-      locale: entry.display.locale,
-    };
-    if (entry.pendingLocale !== undefined) {
-      value.pendingLocale = entry.pendingLocale;
-    }
-    if (entry.status === "error") {
-      value.error = entry.error;
-      value.retry = entry.retry;
-    }
-    return options.children(value);
-  }
-
-  return options.fallback ?? null;
-}
-
-/**
- * Factory for generic `I18n` gate + `withI18n` HOC over the same Outer.
- * Codegen emits typed wrappers; tests use this directly.
- */
-export 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>>;
-} {
-  const { useLoadArgs } = options;
-  const keepPrevious = options.keepPreviousOnPartitionChange !== false;
-
-  function useGateEntry(namespaces: readonly string[]): LoadDisplayEntry<ScopedScopeLike> {
-    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 !== undefined
-        ? { tryResolveSync: () => args.tryResolveSync!(resolved) }
-        : {}),
-      keepPrevious,
-    });
-  }
-
-  function I18n({ namespaces, fallback, renderError, children }: I18nGateProps): ReactNode {
-    const entry = useGateEntry(namespaces);
-    return renderDisplayEntry(entry, {
-      ...(fallback !== undefined ? { fallback } : {}),
-      ...(renderError !== undefined ? { renderError } : {}),
-      children,
-    });
-  }
-
-  function withI18n<P extends object = object, R = never>(
-    hocOptions: I18nHocOptions<P>,
-    render: WithI18nRender<P, R>
-  ): ForwardRefExoticComponent<P & RefAttributes<R>> {
-    const { fallback, renderError } = hocOptions;
-    const Outer = forwardRef<R, P>(function I18nHocOuter(props, ref) {
-      const entry = useGateEntry(hocOptions.namespaces);
-
-      const needsFallback = entry.status === "pending" && entry.t === null;
-      const resolvedFallback =
-        !needsFallback || fallback === undefined
-          ? undefined
-          : typeof fallback === "function"
-            ? fallback(props as P)
-            : fallback;
-
-      return renderDisplayEntry(entry, {
-        ...(resolvedFallback !== undefined ? { fallback: resolvedFallback } : {}),
-        ...(renderError !== undefined
-          ? {
-              renderError: ({ error, retry }) => renderError({ error, retry, props: props as P }),
-            }
-          : {}),
-        children: (value) => render(props as P, value, ref),
-      });
-    });
-
-    const displayName = render.name || "Component";
-    Outer.displayName = `withI18n(${displayName})`;
-    return Outer as ForwardRefExoticComponent<P & RefAttributes<R>>;
-  }
-
-  return { I18n, withI18n };
-}

package/src/root-context.tsx

@@ -1,21 +0,0 @@
-/**
- * Holds the shared i18n root: handle + coordinator + active locale.
- *
- * Generated {@link useI18nRoot} casts the handle to the project's typed factory return.
- */
-import { createContext, useContext } from "react";
-import type { I18nRootContextValue } from "./types.js";
-
-const I18nRootContext = createContext<I18nRootContextValue | null>(null);
-
-/** Resolves the shared root from an ancestor {@link I18nRootProvider}. */
-export function useI18nRootContext(): I18nRootContextValue {
-  const value = useContext(I18nRootContext);
-  if (value === null) {
-    throw new Error("useI18nRoot must be used within I18nRoot / I18nRootProvider");
-  }
-  return value;
-}
-
-/** Internal — provider wiring. */
-export { I18nRootContext };

package/src/root-provider.tsx

@@ -1,65 +0,0 @@
-/**
- * Single provider that shares handle + coordinator + locale across a lazy subtree.
- */
-import { useRef, type ReactNode } from "react";
-import type { FetchArtifact, I18nCreateInput, OnMissingTranslation } from "@xndrjs/i18n";
-import { createLoadCoordinator } from "./create-load-coordinator.js";
-import { I18nRootContext } from "./root-context.js";
-import type {
-  CreateI18nFactory,
-  I18nHandleLike,
-  I18nRootContextValue,
-  ScopedScopeLike,
-} from "./types.js";
-
-export 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. */
-export function I18nRootProvider({
-  createI18n,
-  locale,
-  dictionary,
-  state,
-  onMissing,
-  fetchImpl,
-  children,
-}: I18nRootProviderProps): ReactNode {
-  if (state !== undefined && dictionary !== undefined) {
-    throw new Error("I18nRootProvider: pass either `state` or `dictionary`, not both.");
-  }
-
-  const valueRef = useRef<I18nRootContextValue | null>(null);
-
-  if (valueRef.current === null) {
-    const seed: I18nCreateInput =
-      state ?? ({ dictionary: dictionary ?? {} } satisfies I18nCreateInput);
-    const handle = createI18n({
-      state: seed,
-      ...(onMissing !== undefined ? { onMissing } : {}),
-      ...(fetchImpl !== undefined ? { fetchImpl } : {}),
-    });
-    valueRef.current = {
-      handle: handle as I18nHandleLike,
-      coordinator: createLoadCoordinator<ScopedScopeLike>(),
-      locale,
-    };
-  } else {
-    valueRef.current.locale = locale;
-  }
-
-  return <I18nRootContext.Provider value={valueRef.current}>{children}</I18nRootContext.Provider>;
-}

package/src/runtime.test.tsx

@@ -1,88 +0,0 @@
-import { act } from "react";
-import { createI18nHandle, IcuTranslationProviderMulti } from "@xndrjs/i18n";
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
-import { createI18nLoadGate, I18nRootProvider, useI18nRootContext } from "./index.js";
-import type { I18nLoadArgs } from "./namespace-load-gate.js";
-
-type MultiSchema = {
-  default: { greeting: { en: string; it: string } };
-};
-type MultiParams = { default: { greeting: never } };
-
-function createTestI18n() {
-  const engine = new IcuTranslationProviderMulti<MultiSchema, MultiParams>({});
-  return createI18nHandle(engine, {
-    namespaceLoaders: {
-      default: async (locale: string) => ({
-        greeting: { [locale]: locale === "it" ? "Ciao" : "Hello" },
-      }),
-    },
-  });
-}
-
-/** Mirrors codegen: gate factory wired to `I18nRootProvider`. */
-function createDefaultLoadGate() {
-  return createI18nLoadGate({
-    keepPreviousOnPartitionChange: false,
-    useLoadArgs: (): I18nLoadArgs => {
-      const root = useI18nRootContext();
-      const { handle, coordinator, locale } = root;
-      return {
-        coordinator,
-        engineRef: handle,
-        partition: locale,
-        locale,
-        load: (namespaces) =>
-          handle.load({
-            namespaces: namespaces as ["default"],
-            locale,
-          }),
-        tryResolveSync: (namespaces) =>
-          handle.peek({
-            namespaces: namespaces as ["default"],
-            locale,
-          }),
-      };
-    },
-  });
-}
-
-describe("runtime primitives", () => {
-  it("per-namespace load via gate then translate", async () => {
-    const { I18n } = createDefaultLoadGate();
-
-    await act(async () => {
-      render(
-        <I18nRootProvider createI18n={createTestI18n} locale="it">
-          <I18n namespaces={["default"]} fallback={<span data-testid="fallback">loading</span>}>
-            {({ t, locale }) => (
-              <span data-testid="greeting">
-                {locale}:{t("default", "greeting")}
-              </span>
-            )}
-          </I18n>
-        </I18nRootProvider>
-      );
-    });
-
-    const greeting = await screen.findByTestId("greeting");
-    expect(greeting.textContent).toBe("it:Ciao");
-    expect(screen.queryByTestId("fallback")).toBeNull();
-  });
-
-  it("I18nRootProvider rejects dictionary + state together", () => {
-    expect(() =>
-      render(
-        <I18nRootProvider
-          createI18n={createTestI18n}
-          locale="en"
-          dictionary={{}}
-          state={{ dictionary: {} }}
-        >
-          <span />
-        </I18nRootProvider>
-      )
-    ).toThrow(/pass either `state` or `dictionary`/);
-  });
-});

package/src/types.ts

@@ -1,138 +0,0 @@
-/**
- * Internal runtime types for `@xndrjs/i18n-react` implementation modules.
- */
-
-/** Locale-bound multi-namespace `t(ns, key, …)`. */
-export type ScopedTranslateFn = (
-  namespace: string,
-  key: string,
-  params?: Record<string, unknown>
-) => string;
-
-/** Partition key for load deduplication — locale (or delivery area when custom). */
-export type LoadPartition = string | undefined;
-
-/** Key inputs for load deduplication. */
-export interface LoadCoordinatorKey {
-  engineRef: unknown;
-  partition: LoadPartition;
-  namespaces: readonly string[];
-}
-
-/** Request payload for {@link createLoadCoordinator.ensure}. */
-export 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. */
-export type LoadCoordinatorEntry<Scope> =
-  | { status: "pending" }
-  | { status: "resolved"; scope: Scope }
-  | { status: "error"; error: unknown };
-
-/** Display entry for gates — includes keep-previous and stable bound `t`. */
-export 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`). */
-export 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}. */
-export interface LoadCoordinator<Scope> {
-  readonly revision: number;
-  /** @deprecated Prefer {@link ensure}. */
-  request(input: LoadCoordinatorRequest<Scope>): void;
-  /** Idempotent: start load if missing. Safe from client getSnapshot. */
-  ensure(input: LoadCoordinatorRequest<Scope>): void;
-  /**
-   * Idempotent: resolve from {@link LoadCoordinatorRequest.tryResolveSync} only.
-   * Never starts `load()` — use from SSR `getServerSnapshot`.
-   */
-  ensureSync(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}. */
-export interface CreateScopedTOptions {
-  namespaces: readonly string[];
-  locale: string;
-}
-
-/** Minimal scope shape used by {@link createScopedT}. */
-export interface ScopedScopeLike {
-  t: (...args: unknown[]) => string;
-  forLocale?: (locale: string) => ScopedScopeLike;
-  locale?: string;
-}
-
-/** Factory passed to {@link I18nRootProvider} — typically codegen `createI18n`. */
-export type CreateI18nFactory = (
-  // Project factories type options per loaderStrategy (fetch requires fetchImpl).
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- bridge codegen-specific option shapes
-  options?: any
-  // Return is project-typed; runtime casts to {@link I18nHandleLike}.
-) => unknown;
-
-/** Minimal handle shape from `@xndrjs/i18n` createI18n(). */
-export 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])[];
-  };
-  getLoadState: () => {
-    resources: readonly {
-      namespace: string;
-      partition: string;
-      status: "pending" | "loaded" | "error";
-      error?: unknown;
-    }[];
-  };
-}
-
-/** Single React context value for the lazy i18n tree. */
-export interface I18nRootContextValue {
-  handle: I18nHandleLike;
-  coordinator: LoadCoordinator<ScopedScopeLike>;
-  locale: string;
-}