@bleedingdev/modern-js-plugin-i18n 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

package/src/runtime/I18nLink.tsx

@@ -1,73 +1,36 @@
-import { Link, useInRouterContext, useParams } from '@modern-js/runtime/router';
 import type React from 'react';
-import { useModernI18n } from './context';
-import { buildLocalizedUrl } from './utils';
+import { Link } from './Link';
 
 export interface I18nLinkProps {
   to: string;
   children: React.ReactNode;
-  [key: string]: any; // Allow other props to be passed through
+  [key: string]: any;
 }
 
+let warnedDeprecation = false;
+
 /**
- * I18nLink component that automatically adds language prefix to navigation links.
- * This component should be used within a :lang dynamic route context.
- *
- * @example
- * ```tsx
- * // When current language is 'en' and to="/about"
- * // The actual link will be "/en/about"
- * <I18nLink to="/about">About</I18nLink>
- *
- * // When current language is 'zh' and to="/"
- * // The actual link will be "/zh"
- * <I18nLink to="/">Home</I18nLink>
- * ```
+ * @deprecated Use {@link Link} from `@modern-js/plugin-i18n/runtime` instead.
+ * `Link` accepts the same language-agnostic `to` values and additionally
+ * supports `#hash`/`?query` targets, typed canonical routes, `params`
+ * interpolation and language-invariant active state.
  */
-// Use static imports to avoid breaking router tree-shaking. Detect router context via useInRouterContext.
-const useRouterHooks = () => {
-  const inRouter = useInRouterContext();
-  return {
-    Link: inRouter ? Link : null,
-    params: inRouter ? useParams() : ({} as any),
-    hasRouter: inRouter,
-  };
-};
-
 export const I18nLink: React.FC<I18nLinkProps> = ({
   to,
   children,
   ...props
 }) => {
-  const { Link, params, hasRouter } = useRouterHooks();
-  const { language, supportedLanguages } = useModernI18n();
-
-  // Get the current language from context (which reflects the actual current language)
-  // URL params might be stale after language changes, so we prioritize the context language
-  const currentLang = language;
-
-  // Build the localized URL by adding language prefix
-  const localizedTo = buildLocalizedUrl(to, currentLang, supportedLanguages);
-
-  // In development mode, warn if used outside of :lang route context
-  if (process.env.NODE_ENV === 'development' && hasRouter && !params.lang) {
+  if (process.env.NODE_ENV === 'development' && !warnedDeprecation) {
+    warnedDeprecation = true;
     console.warn(
-      'I18nLink is being used outside of a :lang dynamic route context. ' +
-        'This may cause unexpected behavior. Please ensure I18nLink is used within a route that has a :lang parameter.',
-    );
-  }
-
-  // If router is not available, render as a regular anchor tag
-  if (!hasRouter || !Link) {
-    return (
-      <a href={localizedTo} {...props}>
-        {children}
-      </a>
+      '[plugin-i18n] I18nLink is deprecated. Import { Link } from ' +
+        "'@modern-js/plugin-i18n/runtime' instead — it accepts the same " +
+        'language-agnostic `to` values.',
     );
   }
 
   return (
-    <Link to={localizedTo} {...props}>
+    <Link to={to} {...props}>
       {children}
     </Link>
   );

package/src/runtime/Link.tsx

@@ -0,0 +1,430 @@
+import type React from 'react';
+import { useMemo } from 'react';
+import type {
+  LinkParamsProp,
+  LinkTargetPathname,
+  ValidateLinkTo,
+} from './canonicalRoutes';
+import { useModernI18n } from './context';
+import { canonicalPath, type LocalizedPathsConfig } from './localizedPaths';
+import { useI18nRouterAdapter } from './routerAdapter';
+import { buildLocalizedUrl, splitUrlTarget } from './utils';
+
+const EXTERNAL_TARGET_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+
+const warnedTargets = new Set<string>();
+
+const warnOnce = (key: string, message: string) => {
+  if (process.env.NODE_ENV !== 'development' || warnedTargets.has(key)) {
+    return;
+  }
+  warnedTargets.add(key);
+  console.warn(message);
+};
+
+export type LinkParams = Record<string, string | number | undefined>;
+
+/**
+ * Interpolate `$param`, `:param`, optional (`{-$param}` / `:param?`) and splat
+ * (`$` / `*`) segments with concrete values before localization, so
+ * pattern-mapped slugs localize correctly.
+ */
+export const interpolateRouteParams = (
+  pathname: string,
+  params?: LinkParams,
+): string => {
+  if (!/[$:*{]/.test(pathname)) {
+    return pathname;
+  }
+
+  const resolveParam = (name: string): string | undefined => {
+    const value = params?.[name];
+    return value === undefined ? undefined : String(value);
+  };
+
+  const segments = pathname
+    .split('/')
+    .map(segment => {
+      if (!segment) {
+        return segment;
+      }
+
+      if (segment.startsWith('{-$') && segment.endsWith('}')) {
+        const value = resolveParam(segment.slice(3, -1));
+        return value === undefined ? null : encodeURIComponent(value);
+      }
+
+      if (segment === '$' || segment === '*') {
+        const value = resolveParam('_splat') ?? resolveParam('*');
+        return value === undefined
+          ? null
+          : value.split('/').map(encodeURIComponent).join('/');
+      }
+
+      if (segment.startsWith('$')) {
+        const value = resolveParam(segment.slice(1));
+        if (value === undefined) {
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${segment.slice(1)}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      if (segment.startsWith(':')) {
+        const optional = segment.endsWith('?');
+        const name = segment.slice(1, optional ? -1 : undefined);
+        const value = resolveParam(name);
+        if (value === undefined) {
+          if (optional) {
+            return null;
+          }
+          warnOnce(
+            `missing-param:${pathname}:${segment}`,
+            `[plugin-i18n] <Link to="${pathname}"> is missing required param "${name}".`,
+          );
+          return segment;
+        }
+        return encodeURIComponent(value);
+      }
+
+      return segment;
+    })
+    .filter(segment => segment !== null);
+
+  return segments.join('/') || '/';
+};
+
+export interface LinkActiveOptions {
+  /**
+   * `true`: active only when the location matches the target exactly.
+   * `false`: also active when the location is nested under the target.
+   * Defaults to prefix matching, except for `/` which defaults to exact.
+   */
+  exact?: boolean;
+}
+
+type AnchorRest = Omit<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  'href' | 'children'
+>;
+
+export interface LinkBaseProps extends AnchorRest {
+  children?: React.ReactNode;
+  /** Hash fragment without the leading `#`. Overrides a `#hash` inside `to`. */
+  hash?: string;
+  /** Search params. Object form is passed natively to TanStack Link. */
+  search?: string | Record<string, unknown>;
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions;
+  replace?: boolean;
+  /**
+   * Prefetching behavior, forwarded to the underlying router link:
+   * react-router gets it verbatim (Modern.js `PrefetchLink` supports it),
+   * TanStack receives it as its native `preload` prop (`'none'` -> `false`).
+   * Stripped from plain `<a>` fallbacks (external / no-router targets).
+   */
+  prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+  /**
+   * Native preload value of the underlying router link. When set, it wins
+   * over `prefetch` on the TanStack branch.
+   */
+  preload?: unknown;
+  activeOptions?: LinkActiveOptions;
+  /** Extra anchor props applied when the link is active. */
+  activeProps?: AnchorRest & Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export type LinkProps<TTo extends string = string> = LinkBaseProps & {
+  to: TTo;
+} & ValidateLinkTo<TTo> &
+  LinkParamsProp<LinkTargetPathname<TTo>>;
+
+const normalizeSearch = (
+  search: string | Record<string, unknown> | undefined,
+  searchFromTo: string,
+): {
+  searchString: string;
+  searchObject: Record<string, string> | undefined;
+} => {
+  if (search && typeof search === 'object') {
+    const entries = Object.entries(search).filter(
+      ([, value]) => value !== undefined && value !== null,
+    );
+    const searchObject = Object.fromEntries(
+      entries.map(([key, value]) => [key, String(value)]),
+    );
+    const params = new URLSearchParams(searchObject);
+    const serialized = params.toString();
+    return {
+      searchString: serialized ? `?${serialized}` : '',
+      searchObject,
+    };
+  }
+
+  const raw = typeof search === 'string' && search ? search : searchFromTo;
+  if (!raw) {
+    return { searchString: '', searchObject: undefined };
+  }
+
+  const searchString = raw.startsWith('?') ? raw : `?${raw}`;
+  const searchObject: Record<string, string> = {};
+  new URLSearchParams(searchString).forEach((value, key) => {
+    searchObject[key] = value;
+  });
+
+  return { searchString, searchObject };
+};
+
+const splitActiveProps = (
+  active: boolean,
+  activeProps?: LinkBaseProps['activeProps'],
+) => {
+  if (!active || !activeProps) {
+    return {};
+  }
+  return activeProps;
+};
+
+const mergeClassNames = (...values: Array<unknown>): string | undefined => {
+  const classNames = values.filter(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  );
+  return classNames.length > 0 ? classNames.join(' ') : undefined;
+};
+
+/**
+ * The standard UltraModern link: a vanilla link in every respect except that
+ * it localizes canonical, language-agnostic paths automatically.
+ *
+ * - `to` accepts canonical routes (`/talks/$slug`), optionally with `#hash`
+ *   and `?query` suffixes; both survive localization.
+ * - External URLs and bare `#hash` targets render a plain `<a>`.
+ * - Active state is language-invariant: a canonical `to` is active when the
+ *   current location matches any localized variant of that route.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/talks/$slug" params={{ slug: talk.slug }} hash="abstract" />
+ * <Link to="/platform" />            // -> /cs/platforma under cs
+ * <Link to="/#work-with-me" />       // cross-page hash, SPA navigation
+ * <Link to="https://ai.bleeding.dev" /> // external -> plain <a>
+ * ```
+ */
+export const Link = <TTo extends string = string>(
+  props: LinkProps<TTo>,
+): React.ReactElement => {
+  const {
+    to,
+    params,
+    children,
+    hash: hashProp,
+    search: searchProp,
+    hashScrollIntoView,
+    activeOptions,
+    activeProps,
+    prefetch,
+    preload,
+    ...rest
+  } = props as LinkBaseProps & { to: string; params?: LinkParams };
+
+  const adapter = useI18nRouterAdapter();
+  const { language, supportedLanguages, localisedUrls } = useModernI18n();
+
+  const config: LocalizedPathsConfig = {
+    languages: supportedLanguages,
+    localisedUrls,
+  };
+
+  const isExternal = EXTERNAL_TARGET_RE.test(to);
+  const isBareHash = to.startsWith('#');
+
+  const target = useMemo(() => {
+    if (isExternal || isBareHash) {
+      return null;
+    }
+
+    const {
+      pathname,
+      search: searchFromTo,
+      hash: hashFromTo,
+    } = splitUrlTarget(to);
+    const interpolated = interpolateRouteParams(pathname || '/', params);
+
+    const firstSegment = interpolated.split('/').filter(Boolean)[0];
+    if (firstSegment && supportedLanguages.includes(firstSegment)) {
+      warnOnce(
+        `lang-prefix:${to}`,
+        `[plugin-i18n] <Link to="${to}"> starts with a language prefix. ` +
+          'Write language-agnostic canonical paths; the Link localizes them automatically.',
+      );
+    }
+
+    const localizedPathname = buildLocalizedUrl(
+      interpolated,
+      language,
+      supportedLanguages,
+      localisedUrls,
+    );
+    const hash = hashProp ?? (hashFromTo ? hashFromTo.slice(1) : '');
+    const { searchString, searchObject } = normalizeSearch(
+      searchProp,
+      searchFromTo,
+    );
+
+    return {
+      canonicalPathname: interpolated,
+      localizedPathname,
+      hash,
+      searchString,
+      searchObject,
+      href: `${localizedPathname}${searchString}${hash ? `#${hash}` : ''}`,
+    };
+  }, [
+    to,
+    params,
+    hashProp,
+    searchProp,
+    isExternal,
+    isBareHash,
+    language,
+    supportedLanguages,
+    localisedUrls,
+  ]);
+
+  const isActive = useMemo(() => {
+    if (!target || !adapter.location) {
+      return false;
+    }
+
+    const current = canonicalPath(adapter.location.pathname, config);
+    const targetCanonical = canonicalPath(target.canonicalPathname, config);
+    const exact = activeOptions?.exact ?? targetCanonical === '/';
+
+    if (current === targetCanonical) {
+      return true;
+    }
+    if (exact) {
+      return false;
+    }
+    return current.startsWith(
+      targetCanonical === '/' ? '/' : `${targetCanonical}/`,
+    );
+  }, [
+    target,
+    adapter.location,
+    activeOptions?.exact,
+    supportedLanguages,
+    localisedUrls,
+  ]);
+
+  const resolvedActiveProps = splitActiveProps(isActive, activeProps);
+  const activeAttributes = isActive
+    ? {
+        'data-status': 'active',
+        'aria-current': (rest['aria-current'] ??
+          resolvedActiveProps['aria-current'] ??
+          'page') as React.AriaAttributes['aria-current'],
+      }
+    : {};
+
+  // External targets and same-page anchors are vanilla links.
+  if (!target) {
+    const { replace: _replace, ...anchorProps } = rest;
+
+    return (
+      <a href={to} {...anchorProps}>
+        {children}
+      </a>
+    );
+  }
+
+  const { Link: RouterLink, hasRouter, framework } = adapter;
+
+  if (!hasRouter || !RouterLink) {
+    const { replace: _replace, ...anchorProps } = rest;
+    const {
+      className: activeClassName,
+      style: activeStyle,
+      ...activeRest
+    } = resolvedActiveProps;
+
+    return (
+      <a
+        href={target.href}
+        {...anchorProps}
+        {...activeRest}
+        {...activeAttributes}
+        className={mergeClassNames(rest.className, activeClassName)}
+        style={{
+          ...(rest.style as React.CSSProperties | undefined),
+          ...(activeStyle as React.CSSProperties | undefined),
+        }}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  const {
+    className: activeClassName,
+    style: activeStyle,
+    ...activeRest
+  } = resolvedActiveProps;
+  const mergedClassName = mergeClassNames(rest.className, activeClassName);
+  const mergedStyle = {
+    ...(rest.style as React.CSSProperties | undefined),
+    ...(activeStyle as React.CSSProperties | undefined),
+  };
+
+  if (framework === 'tanstack') {
+    // TanStack's prop is `preload`; map our react-router-flavored `prefetch`
+    // onto it (`'none'` -> `false`). An explicit native `preload` wins.
+    const tanstackPreload =
+      preload !== undefined
+        ? preload
+        : prefetch === undefined
+          ? undefined
+          : prefetch === 'none'
+            ? false
+            : prefetch;
+
+    // Pass hash/search natively: string-concatenated targets silently break
+    // TanStack navigation.
+    return (
+      <RouterLink
+        to={target.localizedPathname}
+        {...(target.searchObject ? { search: target.searchObject } : {})}
+        {...(target.hash ? { hash: target.hash } : {})}
+        {...(hashScrollIntoView === undefined ? {} : { hashScrollIntoView })}
+        {...(tanstackPreload === undefined ? {} : { preload: tanstackPreload })}
+        {...rest}
+        {...activeRest}
+        {...activeAttributes}
+        className={mergedClassName}
+        style={mergedStyle}
+      >
+        {children}
+      </RouterLink>
+    );
+  }
+
+  return (
+    <RouterLink
+      to={target.href}
+      {...(prefetch === undefined ? {} : { prefetch })}
+      {...(preload === undefined ? {} : { preload })}
+      {...rest}
+      {...activeRest}
+      {...activeAttributes}
+      className={mergedClassName}
+      style={mergedStyle}
+    >
+      {children}
+    </RouterLink>
+  );
+};
+
+export default Link;

package/src/runtime/canonicalRoutes.ts

@@ -0,0 +1,93 @@
+/**
+ * Canonical (language-agnostic) route map.
+ *
+ * Empty by default; populated via declaration merging by the generated
+ * `register.gen.d.ts` that `@modern-js/plugin-tanstack` emits:
+ *
+ * ```ts
+ * declare module '@modern-js/plugin-i18n/runtime' {
+ *   interface UltramodernCanonicalRoutes {
+ *     '/': Record<string, never>;
+ *     '/talks': Record<string, never>;
+ *     '/talks/$slug': { slug: string };
+ *   }
+ * }
+ * ```
+ *
+ * Keys are canonical route patterns in TanStack notation (`$param`,
+ * `{-$param}`); values describe the route's path params.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by generated code
+export interface UltramodernCanonicalRoutes {}
+
+export type CanonicalRoutePath = keyof UltramodernCanonicalRoutes & string;
+
+type HasCanonicalRoutes = [keyof UltramodernCanonicalRoutes] extends [never]
+  ? false
+  : true;
+
+/**
+ * Targets that bypass canonical-route validation: external URLs, same-page
+ * hash anchors, and canonical paths with a `?search` and/or `#hash` suffix
+ * (the pathname part of suffixed targets is still validated).
+ */
+type ExternalLinkTarget =
+  | `http://${string}`
+  | `https://${string}`
+  | `mailto:${string}`
+  | `tel:${string}`
+  | `//${string}`;
+
+type SuffixedCanonicalTarget =
+  | `${CanonicalRoutePath}?${string}`
+  | `${CanonicalRoutePath}#${string}`;
+
+export type AllowedLinkTarget =
+  | CanonicalRoutePath
+  | SuffixedCanonicalTarget
+  | ExternalLinkTarget
+  | `#${string}`;
+
+/**
+ * Validates a literal `to` against the canonical route map. Computed strings
+ * (type `string`) always pass — the escape hatch for dynamic values. When no
+ * canonical map has been generated, everything passes.
+ */
+export type ValidateLinkTo<TTo extends string> =
+  HasCanonicalRoutes extends false
+    ? unknown
+    : string extends TTo
+      ? unknown
+      : TTo extends AllowedLinkTarget
+        ? unknown
+        : {
+            to: {
+              error: 'Not a canonical route. Authors must write language-agnostic paths; see UltramodernCanonicalRoutes.';
+              received: TTo;
+            };
+          };
+
+/** Strip `?search`/`#hash` suffixes from a link target type. */
+export type LinkTargetPathname<TTo extends string> =
+  TTo extends `${infer TPath}#${string}`
+    ? TPath extends `${infer TPure}?${string}`
+      ? TPure
+      : TPath
+    : TTo extends `${infer TPath}?${string}`
+      ? TPath
+      : TTo;
+
+/**
+ * `params` prop contract for a canonical target: required when the route has
+ * required params, optional when all params are optional, forbidden when the
+ * route has none. Non-canonical (computed/external) targets accept a loose
+ * record.
+ */
+export type LinkParamsProp<TPath extends string> =
+  TPath extends CanonicalRoutePath
+    ? UltramodernCanonicalRoutes[TPath] extends Record<string, never>
+      ? { params?: undefined }
+      : Record<string, never> extends UltramodernCanonicalRoutes[TPath]
+        ? { params?: UltramodernCanonicalRoutes[TPath] }
+        : { params: UltramodernCanonicalRoutes[TPath] }
+    : { params?: Record<string, string | number | undefined> };