@bleedingdev/modern-js-renderer-octane 0.0.0-stage → 3.9.3-ultramodern.10

package/src/i18n/LocalizedLink.ts

@@ -0,0 +1,86 @@
+import {
+  configuredLanguage,
+  localizePath,
+} from '@modern-js/i18n-runtime-extensions/paths';
+import { createElement, hookSlots, type OctaneNode, useContext } from 'octane';
+import {
+  type AnyRouter,
+  Link,
+  type LinkComponentProps,
+  useLocation,
+  useRouter,
+} from '../router';
+import { I18nContext } from './context';
+
+// Plain TypeScript is not rewritten by the Octane compiler: router hooks take
+// their stable slot explicitly.
+const targetLocationSlot = Symbol(hookSlots(1));
+
+export interface LocalizedLinkProps
+  extends Omit<
+    LinkComponentProps<'a', AnyRouter, string, string>,
+    'to' | 'mask' | 'href' | 'publicHref' | '_fromLocation'
+  > {
+  /** A canonical, language-agnostic target, e.g. `/products/red-shoe`. */
+  to: string;
+  /** Localize for a specific language instead of the current one. */
+  language?: string;
+}
+
+/**
+ * The native router owns client navigation, preloading and active state. Its mask
+ * keeps the canonical route while publishing the selected language URL;
+ * the entry's i18n router subscription synchronizes the instance on navigation.
+ */
+export function LocalizedLink(props: LocalizedLinkProps): OctaneNode {
+  const context = useContext(I18nContext);
+  if (!context) {
+    throw new Error(
+      '[renderer-octane] LocalizedLink was used outside of an I18nProvider.',
+    );
+  }
+  const router = useRouter();
+  const location = useLocation(undefined, targetLocationSlot);
+  const { language: requestedLanguage, to, children, ...options } = props;
+  const language =
+    requestedLanguage === undefined
+      ? context.language
+      : configuredLanguage(requestedLanguage, context.languages);
+  const externalTarget = to.startsWith('//') || URL.canParse(to);
+  const pathname = externalTarget
+    ? to
+    : localizePath(
+        router.buildLocation({
+          to,
+          from: options.from,
+          params: options.params,
+          unsafeRelative: options.unsafeRelative,
+          _fromLocation: location,
+        }).pathname,
+        language,
+        {
+          languages: [...context.languages],
+          localisedUrls: context.localisedUrls,
+        },
+      );
+
+  return createElement(
+    Link<AnyRouter, string, string, string, string>,
+    {
+      ...options,
+      to: router.options.rewrite ? to : pathname,
+      ...(router.options.rewrite && !externalTarget
+        ? {
+            mask: {
+              to: pathname,
+              inheritSearch: true,
+              hash: options.hash,
+              state: options.state,
+            },
+          }
+        : {}),
+      ...(language === context.language ? {} : { hreflang: language }),
+    },
+    children,
+  );
+}

package/src/i18n/context.ts

@@ -0,0 +1,12 @@
+import { createContext } from 'octane';
+import type { I18nContextValue } from './types';
+
+export type { I18nContextValue, I18nInstanceLike } from './types';
+
+/**
+ * Octane's `createContext<T>(defaultValue: T)` requires a default (unlike
+ * Solid 2's default-less form), so a missing provider is detected by
+ * checking for `null` in `useI18n`/`LocalizedLink` instead — the same
+ * guard shape `@modern-js/plugin-i18n`'s React `ModernI18nContext` uses.
+ */
+export const I18nContext = createContext<I18nContextValue | null>(null);

package/src/i18n/index.ts

@@ -0,0 +1,31 @@
+export {
+  createRequestLanguageRedirect,
+  detectRequestLanguage,
+  languageFromPathname,
+  type RequestLanguageDetection,
+  type ResolvedRequestLanguage,
+  type ResolveRequestLanguageOptions,
+  resolveRequestLanguage,
+} from '@modern-js/i18n-runtime-extensions/request-language';
+export {
+  createI18nSsrHandoffInlineData,
+  I18N_SSR_HANDOFF_ELEMENT_ID,
+  type I18nSsrHandoffPayload,
+  type I18nSsrHandoffResources,
+  readI18nSsrHandoff,
+} from '@modern-js/i18n-runtime-extensions/ssrLanguageHandoff';
+// Renderer-neutral pieces an application entry composes with these bindings.
+export {
+  type CreateI18nUrlRewriteOptions,
+  createI18nUrlRewrite,
+  type I18nLocationRewrite,
+} from '@modern-js/i18n-runtime-extensions/urlRewrite';
+export { I18nContext } from './context';
+export { I18nProvider, type I18nProviderProps } from './I18nProvider';
+export { LocalizedLink, type LocalizedLinkProps } from './LocalizedLink';
+export {
+  type OctaneLatestLanguageSyncOptions,
+  useLatestLanguageSync,
+} from './languageSync';
+export type { I18nContextValue, I18nInstanceLike } from './types';
+export { type UseI18nReturn, useI18n } from './useI18n';

package/src/i18n/languageSync.ts

@@ -0,0 +1,132 @@
+import {
+  createLatestLanguageSyncBinding,
+  type LanguageSyncFailure,
+  type LanguageSyncPolicy,
+} from '@modern-js/i18n-runtime-extensions/language-sync/controller';
+import { hookSlots, useCallback, useEffect, useRef } from 'octane';
+
+export interface OctaneLatestLanguageSyncOptions<TTarget extends object> {
+  changeLanguage: (
+    target: TTarget,
+    language: string,
+  ) => PromiseLike<unknown> | unknown;
+  commitLanguage: (target: TTarget, language: string) => void;
+  desiredLanguage?: string;
+  enabled?: boolean;
+  policy?: LanguageSyncPolicy;
+  readLanguage?: (target: TTarget) => string | undefined;
+  reportFailure?: (failure: LanguageSyncFailure) => void;
+  target?: TTarget;
+}
+
+// Plain TypeScript is not rewritten by the Octane compiler, so each hook call
+// site carries its own stable slot.
+const bindingSlot = Symbol(hookSlots(1));
+const callbacksSlot = Symbol(hookSlots(1));
+const activationSlot = Symbol(hookSlots(1));
+const requestSlot = Symbol(hookSlots(1));
+const retrySlot = Symbol(hookSlots(1));
+const requestCallbackSlot = Symbol(hookSlots(1));
+
+/**
+ * Octane binding over the fork's renderer-neutral `Coordinator`/`Binding`
+ * pair (`@modern-js/i18n-runtime-extensions`'s `createLatestLanguageSyncBinding`):
+ * the same "latest intent wins, retry with backoff, report terminal failure"
+ * policy the React `useLatestLanguageSync` hook drives.
+ *
+ * Octane's own hook API (`useState`/`useEffect`/`useContext`/
+ * `useSyncExternalStore`, confirmed in `node_modules/octane/dist/runtime.d.ts`)
+ * is React-shaped, so this binding mirrors
+ * `i18n-extensions/src/language-sync/react.ts`'s `useLatestLanguageSync`
+ * directly — the Solid binding needed a `createEffect`/`onCleanup`
+ * reshaping for Solid 2's different (compute/effect-split, no
+ * `useEffect`-style dependency arrays) reactivity model; Octane does not.
+ */
+export const useLatestLanguageSync = <TTarget extends object>({
+  changeLanguage,
+  commitLanguage,
+  desiredLanguage,
+  enabled = true,
+  policy,
+  readLanguage,
+  reportFailure,
+  target,
+}: OctaneLatestLanguageSyncOptions<TTarget>): ((language: string) => void) => {
+  const bindingRef = useRef<ReturnType<
+    typeof createLatestLanguageSyncBinding<TTarget>
+  > | null>(null, bindingSlot);
+  if (bindingRef.current === null) {
+    bindingRef.current = createLatestLanguageSyncBinding<TTarget>(policy);
+  }
+  const binding = bindingRef.current;
+
+  useEffect(
+    () => {
+      binding.updateCallbacks({
+        changeLanguage,
+        commitLanguage,
+        readLanguage,
+        reportFailure,
+      });
+    },
+    undefined,
+    callbacksSlot,
+  );
+
+  useEffect(
+    () => {
+      if (!enabled || !target) {
+        return;
+      }
+      binding.activate(target);
+      return () => binding.deactivate();
+    },
+    [binding, enabled, target],
+    activationSlot,
+  );
+
+  useEffect(
+    () => {
+      if (!enabled || !target || !desiredLanguage) {
+        binding.clearRequest();
+        return;
+      }
+      binding.request(desiredLanguage);
+    },
+    [binding, desiredLanguage, enabled, target],
+    requestSlot,
+  );
+
+  useEffect(
+    () => {
+      if (
+        !enabled ||
+        !target ||
+        !desiredLanguage ||
+        typeof window === 'undefined'
+      ) {
+        return;
+      }
+      const retryCurrentIntent = () => binding.request(desiredLanguage);
+      const retryVisibleIntent = () => {
+        if (document.visibilityState === 'visible') {
+          retryCurrentIntent();
+        }
+      };
+      window.addEventListener('online', retryCurrentIntent);
+      document.addEventListener('visibilitychange', retryVisibleIntent);
+      return () => {
+        window.removeEventListener('online', retryCurrentIntent);
+        document.removeEventListener('visibilitychange', retryVisibleIntent);
+      };
+    },
+    [binding, desiredLanguage, enabled, target],
+    retrySlot,
+  );
+
+  return useCallback(
+    (language: string) => binding.request(language),
+    [binding],
+    requestCallbackSlot,
+  );
+};

package/src/i18n/types.ts

@@ -0,0 +1,36 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+
+/**
+ * The slice of an i18next-shaped instance this binding needs. Deliberately
+ * not `@modern-js/plugin-i18n`'s `I18nInstance`: that type is intentionally
+ * narrowed (no index signature, non-overloaded methods — see plugin-i18n's
+ * fork notes) and, more importantly, the plugin package's peer dependencies
+ * require React/ReactDOM, which an Octane-only application must never need
+ * to install. `on`/`off` are real i18next `EventEmitter` methods this
+ * interface adds back for the reactive `languageChanged` subscription.
+ */
+export interface I18nInstanceLike {
+  language: string;
+  t(key: string | string[], options?: Record<string, unknown>): string;
+  changeLanguage?(lng?: string): Promise<unknown> | unknown;
+  on?(event: 'languageChanged', callback: (lng: string) => void): void;
+  off?(event: 'languageChanged', callback: (lng: string) => void): void;
+  /** SSR per-request isolation: the server clones a base instance per request. */
+  cloneInstance?(options?: Record<string, unknown>): I18nInstanceLike;
+}
+
+export interface I18nContextValue {
+  /** Per-request instance. Never a module-level singleton. */
+  instance: I18nInstanceLike;
+  languages: readonly string[];
+  localisedUrls?: LocalisedUrlsOption;
+  /**
+   * Reactive current language, owned by `I18nProvider`'s own `useState` +
+   * one `languageChanged` subscription. `instance.language` is a plain
+   * mutable field, not itself reactive — Octane's context only re-renders
+   * consumers when the Provider commits a *new* `value` object (its
+   * `$$version` bumps), so every consumer reads this field off the context
+   * value instead of reaching into `instance.language` directly.
+   */
+  language: string;
+}

package/src/i18n/useI18n.ts

@@ -0,0 +1,119 @@
+import {
+  configuredLanguage,
+  localizePath,
+} from '@modern-js/i18n-runtime-extensions/paths';
+import { languageFromPathname } from '@modern-js/i18n-runtime-extensions/request-language';
+import { useContext } from 'octane';
+import { useRouter } from '../router';
+import { I18nContext } from './context';
+import type { I18nInstanceLike } from './types';
+
+export interface UseI18nReturn {
+  t: I18nInstanceLike['t'];
+  /** Current language. Re-renders the calling component on `languageChanged`. */
+  language: string;
+  languages: readonly string[];
+  /** The raw per-request instance, for advanced use (namespaces, `exists`, ...). */
+  instance: I18nInstanceLike;
+  /**
+   * Switches the i18next instance's language. With a router, also navigates to
+   * the localized path so the URL and active language stay aligned.
+   */
+  changeLanguage: (language: string) => Promise<void>;
+}
+
+/**
+ * Language switches per instance run one at a time: a switch that a newer
+ * one has superseded before it starts is skipped, so no two switches ever
+ * interleave their language loads and navigations.
+ */
+const languageSwitches = new WeakMap<
+  object,
+  { latest: number; queue: Promise<void> }
+>();
+
+/**
+ * Must render under `I18nProvider`; throws rather than silently reading a
+ * fallback instance when no provider is mounted (Octane's `createContext`
+ * requires a default value, so `I18nContext`'s default is `null` and this
+ * hook turns that into a loud error instead of a shared singleton).
+ */
+export function useI18n(): UseI18nReturn {
+  const context = useContext(I18nContext);
+  if (!context) {
+    throw new Error(
+      '[renderer-octane] useI18n() was called outside of an I18nProvider.',
+    );
+  }
+  const { instance, languages, localisedUrls, language } = context;
+
+  const t: I18nInstanceLike['t'] = (key, options) => instance.t(key, options);
+
+  const router = useRouter({ warn: false });
+
+  const changeLanguage = (requested: string): Promise<void> => {
+    // i18next would fall back silently and the URL would gain an unknown
+    // segment. An unsupported request is rejected before it supersedes any
+    // queued switch.
+    let nextLanguage: string;
+    try {
+      nextLanguage = configuredLanguage(requested, languages);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    const state = languageSwitches.get(instance) ?? {
+      latest: 0,
+      queue: Promise.resolve(),
+    };
+    languageSwitches.set(instance, state);
+    const generation = ++state.latest;
+    const run = state.queue.then(async () => {
+      if (state.latest !== generation) return;
+      // Earlier switches have settled, so this is the language the current
+      // URL was committed with.
+      const committed = instance.language;
+      // The public URL carries the locale. Under the i18n URL rewrite the
+      // router's own location is canonical and has none.
+      const publicLanguage = () =>
+        router
+          ? languageFromPathname(
+              new URL(router.state.location.publicHref, 'http://localhost')
+                .pathname,
+              languages,
+              router.options.basepath,
+            )
+          : undefined;
+      // A failed, blocked or redirected switch leaves the page on some URL;
+      // the language follows that URL's locale, or the committed language on
+      // a URL without one.
+      const reconcile = async () => {
+        const language = publicLanguage() ?? committed;
+        if (instance.language !== language)
+          await instance.changeLanguage?.(language);
+      };
+      try {
+        await instance.changeLanguage?.(nextLanguage);
+      } catch (error) {
+        await reconcile();
+        throw error;
+      }
+      if (!router) return;
+      // The full href keeps the query and fragment across the language switch.
+      const href = localizePath(router.state.location.href, nextLanguage, {
+        languages: [...languages],
+        localisedUrls,
+      });
+      try {
+        await router.navigate({ to: '.', href, replace: true });
+      } catch (error) {
+        await reconcile();
+        throw error;
+      }
+      if (publicLanguage() !== nextLanguage) await reconcile();
+    });
+    state.queue = run.catch(() => {});
+    return run;
+  };
+
+  return { t, language, languages, instance, changeLanguage };
+}