@bleedingdev/modern-js-renderer-solid 0.0.0-stage → 3.9.3-ultramodern.2

package/src/entry-client.tsx

@@ -0,0 +1,48 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import {
+  type NativeClientEntryOptions,
+  type NativeI18nInstance,
+  startNativeClientEntry,
+} from '@modern-js/renderer-core/entry-client';
+import { createNativeRouter } from '@modern-js/renderer-core/router';
+import {
+  hydrateApplication,
+  mountApplication,
+  readSolidDocumentBootstrap,
+} from './client';
+import {
+  componentView,
+  routerView,
+  solidRouterFactory,
+} from './entry-application';
+
+export type SolidClientEntryOptions = NativeClientEntryOptions<
+  NativeI18nInstance,
+  LocalisedUrlsOption
+>;
+
+/** Start a generated Solid browser entry: mount, or hydrate the server document. */
+export function startNativeClient(options: SolidClientEntryOptions): void {
+  startNativeClientEntry(options, {
+    readBootstrap: readSolidDocumentBootstrap,
+    createRouter: (application, routerOptions) =>
+      createNativeRouter(application, routerOptions, solidRouterFactory),
+    async prepareRouter(router, hydrating) {
+      // Hydration adopts the server's matches; a fresh mount loads its own.
+      if (!hydrating) await router.load();
+    },
+    async start({ root, bootstrap, load }) {
+      const view = await load();
+      return (bootstrap?.hydrating ? hydrateApplication : mountApplication)(
+        view.kind === 'component'
+          ? componentView(view.component, view.i18n)
+          : routerView(view.router, view.i18n),
+        root,
+        {
+          ...(bootstrap ? { renderId: bootstrap.documentId } : {}),
+          federation: options.federation,
+        },
+      );
+    },
+  });
+}

package/src/entry-server.tsx

@@ -0,0 +1,85 @@
+import type { LocalisedUrlsOption } from '@modern-js/i18n-runtime-extensions/paths';
+import {
+  dataMetadataToDocumentPolicy,
+  mergeDataResponseIntoResponse,
+  mergeDataResponseMetadata,
+} from '@modern-js/renderer-core/data';
+import {
+  createNativeServerEntry as createServerEntry,
+  type NativeI18nInstance,
+  type NativeServerEntry,
+  type NativeServerEntryOptions,
+} from '@modern-js/renderer-core/entry-server';
+import { createNativeRouter } from '@modern-js/renderer-core/router';
+import {
+  componentView,
+  routerView,
+  solidRouterFactory,
+} from './entry-application';
+import { validateSolidModuleManifest } from './manifest';
+import { getApplicationStatus, resolveApplicationRedirect } from './router';
+import { prepareRouterMatchTransfer } from './router-binding/index';
+import {
+  renderCSRDocument,
+  renderDocumentApplication,
+  respondApplicationResponse,
+  runApplicationRequest,
+} from './server';
+
+export type SolidServerEntryOptions = NativeServerEntryOptions<
+  NativeI18nInstance,
+  LocalisedUrlsOption
+>;
+
+/** The native transport handlers of a generated Solid server entry. */
+export function createNativeServerEntry(
+  options: SolidServerEntryOptions,
+): NativeServerEntry {
+  return createServerEntry(options, {
+    document: (document, nativeManifest, identity) => ({
+      ...document,
+      renderId: document.documentId,
+      manifest: validateSolidModuleManifest(nativeManifest, identity).modules,
+    }),
+    run: (session, callback) => runApplicationRequest(session, callback),
+    respond: respondApplicationResponse,
+    createRouter: (application, routerOptions) =>
+      createNativeRouter(application, routerOptions, solidRouterFactory),
+    renderCSR: ({ session }, document) =>
+      renderCSRDocument({ session, document }),
+    renderComponent: ({ session }, component, document, i18n) =>
+      renderDocumentApplication({
+        session,
+        view: componentView(component, i18n),
+        document,
+        federation: options.federation,
+      }),
+    async renderRoutes({
+      context: { session },
+      router,
+      outcomes,
+      document,
+      forbiddenValues,
+      i18n,
+    }) {
+      await router.load();
+      prepareRouterMatchTransfer(router, session, forbiddenValues);
+      const metadata = mergeDataResponseMetadata(outcomes, {
+        status: getApplicationStatus(router),
+      });
+      const redirect = resolveApplicationRedirect(router);
+      if (redirect)
+        return respondApplicationResponse(
+          session,
+          mergeDataResponseIntoResponse(redirect, metadata),
+        );
+      session.resolveResponse(dataMetadataToDocumentPolicy(metadata));
+      return renderDocumentApplication({
+        session,
+        view: routerView(router, i18n),
+        document,
+        federation: options.federation,
+      });
+    },
+  });
+}

package/src/federation-context.ts

@@ -0,0 +1,47 @@
+import {
+  type FederationInstance,
+  getFederationHost,
+  type NativeFederationBinding,
+} from '@modern-js/renderer-core/federation';
+import type { JSX } from '@solidjs/web';
+import { createComponent, createContext } from 'solid-js';
+
+/** One application owns its host runtime; each response owns its render scope. */
+export interface SolidFederationScope {
+  readonly instance: FederationInstance | undefined;
+  /** Server scopes: the host's client module that hydrates a remote. */
+  readonly hydrationModule?: string;
+}
+
+/** Outside a generated entry, remote ids have no host; custom loaders work. */
+export const FederationContext = createContext<SolidFederationScope>(
+  Object.freeze({ instance: undefined }),
+);
+
+export function createFederationScope(
+  binding: NativeFederationBinding | undefined,
+): SolidFederationScope | undefined {
+  if (binding === undefined) return undefined;
+  const instance = getFederationHost(binding);
+  return binding.hydrationModule === undefined
+    ? { instance }
+    : { instance, hydrationModule: binding.hydrationModule };
+}
+
+/**
+ * Provide the scope to an application view. The server and the browser wrap
+ * the same view, so both render the provider at the same hydration position.
+ */
+export function provideFederation(
+  scope: SolidFederationScope | undefined,
+  view: () => JSX.Element,
+): () => JSX.Element {
+  if (!scope) return view;
+  return () =>
+    createComponent(FederationContext, {
+      value: scope,
+      get children() {
+        return view();
+      },
+    });
+}

package/src/federation-ssr.ts

@@ -0,0 +1,117 @@
+import { remoteBrowserAssets } from '@modern-js/renderer-core/federation';
+import type { SolidFederationScope } from './federation-context';
+
+/**
+ * The server half of same-renderer Module Federation. federatedComponent()
+ * names each remote it server-rendered by an asset key, and the response's
+ * document resolves that key through the same host's federation scope.
+ */
+
+/** Asset keys for server-rendered remotes, e.g. `ultramodern-federation:remote/Widget`. */
+export const FEDERATED_ASSET_PREFIX = 'ultramodern-federation:';
+
+/** The host's server state for a remote: its browser assets and hydration module. */
+export function federatedServerAssets(
+  scope: SolidFederationScope | undefined,
+  id: string,
+) {
+  const instance = scope?.instance;
+  const assets = instance && remoteBrowserAssets(instance, id);
+  if (!assets || !scope?.hydrationModule || !instance.name) return undefined;
+  // The browser module finds this host by name among the realm's instances.
+  const hydration = `${scope.hydrationModule}?id=${encodeURIComponent(id)}&host=${encodeURIComponent(instance.name)}`;
+  return { hydration, assets };
+}
+
+export function federatedAssetKey(id: string): string {
+  return `${FEDERATED_ASSET_PREFIX}${id}`;
+}
+
+interface ResolvedDocumentAssets {
+  js: string[];
+  css: string[];
+  preloads?: Record<string, unknown>[];
+}
+
+interface StaticAssetChunk {
+  file: string;
+  css?: string[];
+  imports?: string[];
+  preloads?: Record<string, unknown>[];
+}
+
+/** Solid's own asset path join: absolute URLs pass through. */
+function joinAssetPath(base: unknown, file: string): string {
+  if (/^(?:[a-z][a-z0-9+.-]*:)?\/\//iu.test(file)) return file;
+  let prefix = typeof base === 'string' && base ? base : '/';
+  if (!prefix.endsWith('/')) prefix += '/';
+  return prefix + (file.startsWith('/') ? file.slice(1) : file);
+}
+
+/** Solid's static manifest walk, so a resolver can extend a static manifest. */
+function resolveStaticAssets(
+  manifest: Record<string, unknown>,
+  key: string,
+): ResolvedDocumentAssets | null {
+  if (key === '_base' || !Object.hasOwn(manifest, key)) return null;
+  const base = manifest._base;
+  const js: string[] = [];
+  const css: string[] = [];
+  let preloads: Record<string, unknown>[] | undefined;
+  const visited = new Set<string>();
+  const walk = (name: string) => {
+    if (visited.has(name) || name === '_base') return;
+    visited.add(name);
+    const chunk = manifest[name] as StaticAssetChunk | undefined;
+    if (!chunk) return;
+    js.push(joinAssetPath(base, chunk.file));
+    for (const file of chunk.css ?? []) css.push(joinAssetPath(base, file));
+    for (const link of chunk.preloads ?? []) {
+      const href = typeof link.href === 'string' && link.href;
+      if (!href && typeof link.imagesrcset !== 'string') continue;
+      preloads ??= [];
+      if (href) preloads.push({ ...link, href: joinAssetPath(base, href) });
+      else {
+        const { href: _ignored, ...rest } = link;
+        preloads.push(rest);
+      }
+    }
+    for (const dependency of chunk.imports ?? []) walk(dependency);
+  };
+  walk(key);
+  return preloads ? { js, css, preloads } : { js, css };
+}
+
+/**
+ * Extend a static Solid asset manifest with the remotes this response
+ * server-rendered through its host. The first module is the host's hydration
+ * module for that remote, which Solid imports before hydrating the boundary
+ * that rendered it.
+ */
+export function withFederatedAssets<Manifest>(
+  manifest: Manifest,
+  scope: SolidFederationScope | undefined,
+): Manifest {
+  if (
+    !scope?.hydrationModule ||
+    manifest === null ||
+    typeof manifest !== 'object' ||
+    typeof (manifest as { resolve?: unknown }).resolve === 'function'
+  )
+    return manifest;
+  const modules = manifest as Record<string, unknown>;
+  const resolve = (key: string): ResolvedDocumentAssets | null => {
+    if (!key.startsWith(FEDERATED_ASSET_PREFIX))
+      return resolveStaticAssets(modules, key);
+    const remote = federatedServerAssets(
+      scope,
+      key.slice(FEDERATED_ASSET_PREFIX.length),
+    );
+    if (!remote) return null;
+    return {
+      js: [joinAssetPath(modules._base, remote.hydration), ...remote.assets.js],
+      css: [...remote.assets.css],
+    };
+  };
+  return { resolve, resolveSync: resolve } as Manifest;
+}

package/src/federation.tsx

@@ -0,0 +1,193 @@
+import { loadFederatedModule } from '@modern-js/renderer-core/federation';
+import { isServer, type JSX } from '@solidjs/web';
+import * as solid from 'solid-js';
+import {
+  type Component,
+  createComponent,
+  createSignal,
+  Errored,
+  isHydrating,
+  Loading,
+  lazy,
+  onCleanup,
+  useContext,
+} from 'solid-js';
+import {
+  FederationContext,
+  type SolidFederationScope,
+} from './federation-context';
+import { federatedAssetKey, federatedServerAssets } from './federation-ssr';
+
+/** The module shape a same-renderer Module Federation remote exposes. */
+export interface FederatedModule<P extends object> {
+  readonly default: Component<P>;
+}
+
+export interface FederatedComponentOptions {
+  /** Rendered while the remote loads, and on the server when it cannot load. */
+  readonly fallback?: () => JSX.Element;
+  /**
+   * Milliseconds a remote load may take before it fails. Defaults to 3000 on
+   * the server, so an unavailable remote cannot hold the document; the
+   * browser waits without a limit unless one is given.
+   */
+  readonly timeout?: number;
+}
+
+const DEFAULT_SERVER_TIMEOUT = 3000;
+
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeout: number | undefined,
+  label: string,
+): Promise<T> {
+  if (timeout === undefined) return promise;
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () =>
+        reject(
+          new Error(`Remote module ${label} did not load within ${timeout}ms`),
+        ),
+      timeout,
+    );
+    // A pending remote must not keep a server process alive.
+    (timer as { unref?: () => void }).unref?.();
+    promise.then(
+      value => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      error => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Run once the document has hydrated. A retry inside a hydration pass would
+ * look for server data the failed render never produced.
+ */
+function afterHydration(callback: () => void): void {
+  // The hydration runtime installs this hook on Solid's shared config.
+  const { sharedConfig } = solid as unknown as {
+    sharedConfig?: { onHydrationEnd?: (callback: () => void) => void };
+  };
+  const onHydrationEnd = sharedConfig?.onHydrationEnd;
+  if (onHydrationEnd) onHydrationEnd(callback);
+  else queueMicrotask(callback);
+}
+
+/**
+ * Render a Solid component exposed by a Module Federation remote, by its
+ * `remote/Expose` id or a custom loader.
+ *
+ * A remote id loads through the federation instance of the application that
+ * renders it, so co-located hosts keep their own remotes. On the server it
+ * renders into the document with the remote's stylesheets and module
+ * preloads; the browser loads the same remote before hydrating it.
+ * A remote that fails or exceeds its timeout on the server renders the
+ * fallback, and the browser retries it after hydration. Custom loaders render
+ * in the browser only. Browser load and renderer-admission failures throw to
+ * the nearest `Errored` boundary.
+ */
+export function federatedComponent<P extends object = Record<string, never>>(
+  remote: string | (() => Promise<FederatedModule<P>>),
+  options: FederatedComponentOptions = {},
+): Component<P> {
+  if (
+    typeof remote === 'string'
+      ? !/^[^/]+\/.+/u.test(remote)
+      : typeof remote !== 'function'
+  )
+    throw new TypeError(
+      "federatedComponent requires a remote id such as 'remote/Widget' or a loader",
+    );
+  if (
+    options.timeout !== undefined &&
+    (!Number.isFinite(options.timeout) || options.timeout <= 0)
+  )
+    throw new TypeError(
+      'federatedComponent timeout must be a positive number of milliseconds',
+    );
+  const id = typeof remote === 'string' ? remote : undefined;
+  const timeout =
+    options.timeout ?? (isServer ? DEFAULT_SERVER_TIMEOUT : undefined);
+  const load = (scope: SolidFederationScope): Component<P> =>
+    lazy(async () => {
+      if (isServer && !id)
+        throw new Error(
+          'A federatedComponent loader renders in the browser only; use a remote id to server-render it',
+        );
+      const module = await withTimeout(
+        Promise.resolve().then(() =>
+          id
+            ? loadFederatedModule<FederatedModule<P>>(scope.instance, id)
+            : (remote as () => Promise<never>)(),
+        ),
+        timeout,
+        id ?? 'loader',
+      );
+      const component = module?.default;
+      if (typeof component !== 'function')
+        throw new TypeError(
+          'A federated Solid module must default-export a component',
+        );
+      if (!isServer || !id) return { default: component };
+      if (!federatedServerAssets(scope, id))
+        throw new Error(
+          `Cannot server-render ${id}: the host has no server federation state for its browser assets`,
+        );
+      // Solid resolves a loaded module's $$moduleUrl through the response's
+      // asset resolver: stylesheets, preloads and the hydration module.
+      return { default: component, $$moduleUrl: federatedAssetKey(id) };
+    }) as Component<P>;
+  // Solid's lazy caches its module. Scope the cache to one application or
+  // response, so two hosts rendering this component never share a remote.
+  const remotes = new WeakMap<SolidFederationScope, Component<P>>();
+  const fallback = (): JSX.Element => options.fallback?.();
+
+  return (props: P): JSX.Element => {
+    const scope = useContext(FederationContext);
+    const Remote = remotes.get(scope) ?? load(scope);
+    remotes.set(scope, Remote);
+    const remoteView = () => createComponent(Remote, props);
+    // After a server failure, the browser renders the remote afresh: like a
+    // client-only mount, its failures reach the application's boundaries.
+    const [retried, retry] = createSignal(false);
+    const recover = (error: () => unknown): JSX.Element => {
+      // A server failure renders the fallback and serializes the failure;
+      // hydration claims that fallback, then the browser retries the remote.
+      if (isServer) return fallback();
+      if (isHydrating()) {
+        let active = true;
+        onCleanup(() => {
+          active = false;
+        });
+        afterHydration(() => {
+          if (active) retry(true);
+        });
+        return fallback();
+      }
+      throw error();
+    };
+    // Loading owns the pending load. On the first render Errored sits inside
+    // it, so a load that fails after suspending still reaches it on the server.
+    return createComponent(Loading, {
+      get fallback() {
+        return fallback();
+      },
+      get children() {
+        return retried()
+          ? remoteView()
+          : createComponent(Errored, {
+              fallback: recover,
+              get children() {
+                return remoteView();
+              },
+            });
+      },
+    });
+  };
+}

package/src/i18n/I18nProvider.tsx

@@ -0,0 +1,54 @@
+import type { JSX } from '@solidjs/web';
+import * as Solid from 'solid-js';
+import { I18nContext } from './context';
+import type { I18nContextValue } from './types';
+
+export interface I18nProviderProps extends Omit<I18nContextValue, 'language'> {
+  children: JSX.Element;
+}
+
+/**
+ * Provides a per-request i18next-shaped instance to the Solid tree. The
+ * instance must come from the caller (created with `cloneInstance` per
+ * request on the server, and the same instance reused on hydration) — this
+ * provider holds no module-level state of its own beyond the one reactive
+ * `language` signal it derives from `instance` and shares with every
+ * consumer through context (see `I18nContextValue.language`'s doc for why
+ * that single shared subscription matters, instead of each consumer
+ * subscribing to `languageChanged` independently).
+ *
+ * In Solid 2 a `Context` doubles as its own provider component: `value` is
+ * read reactively off `props` here, so an ancestor re-rendering this
+ * provider with a new `instance`/`languages`/`localisedUrls` propagates
+ * without needing a `.Provider` subcomponent.
+ */
+export function I18nProvider(props: I18nProviderProps): JSX.Element {
+  const [language, setLanguage] = Solid.createSignal(props.instance.language);
+
+  Solid.createEffect(
+    () => props.instance,
+    instance => {
+      setLanguage(instance.language);
+      const handleLanguageChanged = (lng: string) => setLanguage(lng);
+      instance.on?.('languageChanged', handleLanguageChanged);
+      return () => {
+        instance.off?.('languageChanged', handleLanguageChanged);
+      };
+    },
+  );
+
+  const value: I18nContextValue = {
+    get instance() {
+      return props.instance;
+    },
+    get languages() {
+      return props.languages;
+    },
+    get localisedUrls() {
+      return props.localisedUrls;
+    },
+    language,
+  };
+
+  return <I18nContext value={value}>{props.children}</I18nContext>;
+}

package/src/i18n/LocalizedLink.tsx

@@ -0,0 +1,122 @@
+import {
+  canonicalPath,
+  configuredLanguage,
+  localizePath,
+} from '@modern-js/i18n-runtime-extensions/paths';
+import type { JSX } from '@solidjs/web';
+import * as Solid from 'solid-js';
+import {
+  Link,
+  type LinkComponentProps,
+  useLocation,
+  useRouter,
+} from '../router';
+import { I18nContext } from './context';
+
+export interface LocalizedLinkProps {
+  /** A canonical, language-agnostic target, e.g. `/products/red-shoe`. */
+  to: string;
+  /** Localize for a specific language instead of the current one. */
+  language?: string;
+  children?: LinkComponentProps<'a'>['children'];
+  class?: string;
+  activeProps?: LinkComponentProps<'a'>['activeProps'];
+  inactiveProps?: LinkComponentProps<'a'>['inactiveProps'];
+  activeOptions?: LinkComponentProps<'a'>['activeOptions'];
+  replace?: boolean;
+  preload?: LinkComponentProps<'a'>['preload'];
+  [key: `data-${string}`]: unknown;
+}
+
+/**
+ * A thin wrapper over the native Solid router `Link` that localizes a
+ * canonical `to` for the current (or an explicit) language before handing it
+ * to the real link, the same contract as `@modern-js/plugin-i18n`'s React
+ * `Link`. It resolves the href itself via the shared pathname helpers, so it
+ * works with or without the router's i18n `rewrite`. Every link, including
+ * one to another language, is the native `Link`: navigation, preloading and
+ * active state stay with the router.
+ *
+ * Under the i18n `rewrite` the router matches canonical paths and localizes
+ * outgoing locations to the current language, so a link to another language
+ * routes to the canonical `to` and publishes the target language's URL as a
+ * route mask (the rewrite keeps a mask's explicit language). The entry's
+ * router language synchronization (`syncWithRouter`) switches the i18next
+ * instance from the navigated URL, as it does for history navigation.
+ *
+ * Props are forwarded explicitly (not via object-rest or a missing
+ * `splitProps`/`mergeProps` primitive — Solid 2 only exports `merge`) so
+ * each one is read directly from `props` in JSX position and keeps its
+ * per-key reactivity.
+ */
+export function LocalizedLink(props: LocalizedLinkProps): JSX.Element {
+  const context = Solid.useContext(I18nContext);
+  const router = useRouter();
+  const rewrite = Boolean(router.options.rewrite);
+
+  // An explicit language must be configured: it becomes the locale prefix.
+  const targetLanguage = () =>
+    props.language === undefined
+      ? context.language()
+      : configuredLanguage(props.language, context.languages);
+  const href = Solid.createMemo(() =>
+    localizePath(props.to, targetLanguage(), {
+      languages: [...context.languages],
+      localisedUrls: context.localisedUrls,
+    }),
+  );
+  const crossLanguage = () => targetLanguage() !== context.language();
+  const masked = () => rewrite && crossLanguage();
+  // Declared `data-*` attributes reach the anchor through getters, so each
+  // keeps its own reactivity like the explicitly forwarded props.
+  const dataAttributes = Object.defineProperties(
+    {},
+    Object.fromEntries(
+      Object.keys(props)
+        .filter(key => key.startsWith('data-'))
+        .map(key => [
+          key,
+          {
+            enumerable: true,
+            get: () => props[key as `data-${string}`],
+          },
+        ]),
+    ),
+  );
+
+  return (
+    <Link
+      {...dataAttributes}
+      // A masked link routes to the canonical `to`. Otherwise `href` wins over
+      // `to` in router-core's `buildLocation` (it checks `dest.href` first);
+      // `to="."` only satisfies the type-level requirement that a `to` be
+      // present and is otherwise inert.
+      to={masked() ? props.to : '.'}
+      href={masked() ? undefined : href()}
+      mask={masked() ? { to: href() } : undefined}
+      hreflang={crossLanguage() ? targetLanguage() : undefined}
+      class={props.class}
+      activeProps={props.activeProps}
+      inactiveProps={props.inactiveProps}
+      activeOptions={props.activeOptions}
+      replace={props.replace}
+      preload={props.preload}
+    >
+      {props.children}
+    </Link>
+  );
+}
+
+/**
+ * Language-invariant active check: `to="/products"` is active whether the
+ * current location is `/en/products` or `/produkty` under a mapped locale.
+ */
+export function useIsLocalizedActive(canonicalTarget: string): () => boolean {
+  const context = Solid.useContext(I18nContext);
+  const location = useLocation();
+  return () =>
+    canonicalPath(location().pathname, {
+      languages: [...context.languages],
+      localisedUrls: context.localisedUrls,
+    }) === canonicalTarget;
+}

package/src/i18n/context.ts

@@ -0,0 +1,13 @@
+import * as Solid from 'solid-js';
+import type { I18nContextValue } from './types';
+
+export type { I18nContextValue, I18nInstanceLike } from './types';
+
+/**
+ * Default-less form (Solid 2): `useContext` on this throws
+ * `ContextNotFoundError` when no `I18nProvider` is mounted, instead of
+ * silently reading a shared fallback instance across requests — exactly the
+ * failure mode a per-request i18n instance needs. The context object is
+ * itself the provider component: render `<I18nContext value={...}>`.
+ */
+export const I18nContext = Solid.createContext<I18nContextValue>();