@vmz/vmz 0.1.17 → 0.1.18

package/dist/locale-router.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Locale router / PageMeta: route realization · canonical · hreflang ·
  * Link locale retain · locale-aware cache key.
@@ -7,9 +6,6 @@
  */
 import { negotiateLocale } from './locale-runtime.js';
 import { DIAG_LOCALE_CACHE_KEY_STEALS_CONTENT, DIAG_LOCALE_CANONICAL_MISSING, DIAG_LOCALE_HREFLANG_INCOMPLETE, DIAG_LOCALE_LINK_HARDCODED_PATH, DIAG_LOCALE_META_LOCALE_MISMATCH, DIAG_LOCALE_PREFIX_OMIT_WITHOUT_REDIRECT, DIAG_LOCALE_ROUTE_COLLISION, LOCALE_LINK_RESOLUTION_SCHEMA, LOCALE_PAGE_META_SCHEMA, LOCALE_ROUTE_REALIZATION_SCHEMA, LOCALE_ROUTER_CHECK_SCHEMA, } from './locale-schema.js';
-/**
- * @param {string} path
- */
 function normalizePath(path) {
     let p = String(path || '/');
     if (!p.startsWith('/'))
@@ -18,12 +14,7 @@ function normalizePath(path) {
         p = p.slice(0, -1);
     return p || '/';
 }
-/**
- * Join locale prefix with a stable route path pattern.
- * @param {string} localeId
- * @param {string} pathPattern stable path without locale (e.g. /account/profile)
- * @param {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string }} routing
- */
+/** Join locale prefix with a stable route path pattern. */
 export function realizeRoutePath(localeId, pathPattern, routing = {}) {
     const strategy = routing.strategy || 'prefix';
     const defaultPrefix = routing.defaultPrefix || 'include';
@@ -60,26 +51,15 @@ export function realizeRoutePath(localeId, pathPattern, routing = {}) {
         defaultPrefix,
     };
 }
-/**
- * Build RouteId × LocaleId realization table.
- * @param {{
- * routes: Array<{ routeId: string, path: string }>,
- * locales: string[],
- * defaultLocale: string,
- * routing?: { strategy?: string, defaultPrefix?: string },
- * }} input
- */
+/** Build RouteId × LocaleId realization table. */
 export function buildLocaleRouteRealizationTable(input) {
     const routing = {
         strategy: input.routing?.strategy || 'prefix',
         defaultPrefix: input.routing?.defaultPrefix || 'include',
         defaultLocale: input.defaultLocale,
     };
-    /** @type {any[]} */
     const realizations = [];
-    /** @type {Map<string, string>} */
     const pathOwners = new Map();
-    /** @type {any[]} */
     const diagnostics = [];
     for (const route of input.routes || []) {
         for (const localeId of input.locales || []) {
@@ -129,34 +109,16 @@ export function buildLocaleRouteRealizationTable(input) {
         diagnostics,
     };
 }
-/**
- * Absolute URL helper.
- * @param {string} origin
- * @param {string} path
- */
+/** Absolute URL helper. */
 export function absoluteUrl(origin, path) {
     const o = String(origin || '').replace(/\/$/, '');
     const p = normalizePath(path);
     return `${o}${p}`;
 }
-/**
- * Locale-aware PageMeta for one RouteId × LocaleId.
- * @param {{
- * routeId: string,
- * localeId: string,
- * direction?: string,
- * title: string,
- * description?: string,
- * origin: string,
- * realizations: Array<{ routeId: string, localeId: string, path: string }>,
- * locales: string[],
- * defaultLocale: string,
- * }} input
- */
+/** Locale-aware PageMeta for one RouteId × LocaleId. */
 export function buildLocalePageMeta(input) {
     const forRoute = (input.realizations || []).filter((r) => r.routeId === input.routeId);
     const self = forRoute.find((r) => r.localeId === input.localeId);
-    /** @type {any[]} */
     const diagnostics = [];
     if (!self?.path) {
         diagnostics.push({
@@ -167,7 +129,6 @@ export function buildLocalePageMeta(input) {
     }
     const canonicalPath = self?.path || '/';
     const canonical = absoluteUrl(input.origin, canonicalPath);
-    /** @type {Array<{ localeId: string, hreflang: string, href: string }>} */
     const alternates = [];
     for (const loc of input.locales || []) {
         const hit = forRoute.find((r) => r.localeId === loc);
@@ -207,14 +168,7 @@ export function buildLocalePageMeta(input) {
         status: diagnostics.length ? 'failed' : 'ready',
     };
 }
-/**
- * `<Link to="routeId">` retains current locale — never hand-written localized paths.
- * @param {{
- * to: string,
- * currentLocale: string,
- * realizations: Array<{ routeId: string, localeId: string, path: string }>,
- * }} input
- */
+/** `<Link to="routeId">` retains current locale — never hand-written localized paths. */
 export function resolveLinkHref(input) {
     const to = input.to;
     if (typeof to === 'string' && (to.startsWith('/') || /^https?:/i.test(to))) {
@@ -263,11 +217,7 @@ export function resolveLinkHref(input) {
         diagnostics: [],
     };
 }
-/**
- * Parse locale prefix from a pathname under prefix strategy.
- * @param {string} pathname
- * @param {string[]} supportedLocales
- */
+/** Parse locale prefix from a pathname under prefix strategy. */
 export function parseLocaleFromPath(pathname, supportedLocales) {
     const parts = normalizePath(pathname).split('/').filter(Boolean);
     if (!parts.length)
@@ -278,17 +228,7 @@ export function parseLocaleFromPath(pathname, supportedLocales) {
     }
     return { localeId: null, restPath: normalizePath(pathname) };
 }
-/**
- * Rewrite a same-app href to the given LocaleId via route realization.
- * Stable path (no locale) is recovered first, then re-realized — Link never hardcodes locale.
- * @param {string} href
- * @param {string} localeId
- * @param {{
- *   locales?: Array<{ id: string }|string>,
- *   defaultLocale?: string,
- *   routing?: { strategy?: string, defaultPrefix?: string, defaultLocale?: string },
- * }} artifact
- */
+/** Rewrite a same-app href to the given LocaleId via route realization. */
 export function localizeSameAppHref(href, localeId, artifact) {
     if (!href || !localeId || !artifact)
         return href;
@@ -323,13 +263,7 @@ export function localizeSameAppHref(href, localeId, artifact) {
     const realized = realizeRoutePath(localeId, rest, routing);
     return `${realized.path}${search}${hash}`;
 }
-/**
- * Rewrite `<a data-vmz-route href>` in HTML body to retain `localeId`.
- * @param {string} html
- * @param {string} localeId
- * @param {Parameters<typeof localizeSameAppHref>[2]} artifact
- * @param {(s: string) => string} [escapeAttr]
- */
+/** Rewrite `<a data-vmz-route href>` in HTML body to retain `localeId`. */
 export function localizeBodyLinks(html, localeId, artifact, escapeAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;')) {
     if (!html || !localeId || !artifact)
         return html;
@@ -346,18 +280,7 @@ export function localizeBodyLinks(html, localeId, artifact, escapeAttr = (s) =>
         return `<a${newAttrs}>`;
     });
 }
-/**
- * Plan redirect / negotiation for an incoming URL (omit-prefix aware).
- * @param {{
- * pathname: string,
- * supportedLocales: string[],
- * defaultLocale: string,
- * routing?: { strategy?: string, defaultPrefix?: string },
- * hostCandidates?: string[],
- * preference?: string|null,
- * userChoice?: string|null,
- * }} input
- */
+/** Plan redirect / negotiation for an incoming URL (omit-prefix aware). */
 export function planLocalePathNavigation(input) {
     const routing = {
         strategy: input.routing?.strategy || 'prefix',
@@ -373,7 +296,6 @@ export function planLocalePathNavigation(input) {
         preference: input.preference,
         hostCandidates: input.hostCandidates,
     });
-    /** @type {any[]} */
     const diagnostics = [];
     let redirectTo = null;
     if (routing.strategy === 'prefix' && routing.defaultPrefix === 'omit') {
@@ -411,19 +333,12 @@ export function planLocalePathNavigation(input) {
         contentLocale: routing.defaultPrefix === 'omit' && !parsed.localeId ? input.defaultLocale : negotiated,
     };
 }
-/**
- * Locale-aware cache key — must include LocaleId so Accept-Language cannot steal content.
- * @param {{ routeId: string, localeId: string, path: string }} input
- */
+/** Locale-aware cache key — must include LocaleId so Accept-Language cannot steal content. */
 export function localeAwareCacheKey(input) {
     return `locale=${input.localeId}|route=${input.routeId}|path=${normalizePath(input.path)}`;
 }
-/**
- * Reject Vary: Accept-Language on a cache key that does not encode LocaleId.
- * @param {{ cacheKey: string, varyAcceptLanguage?: boolean, localeId?: string }} input
- */
+/** Reject Vary: Accept-Language on a cache key that does not encode LocaleId. */
 export function assertLocaleCacheKey(input) {
-    /** @type {any[]} */
     const diagnostics = [];
     const key = String(input.cacheKey || '');
     const hasLocale = /(?:^|[|&])locale=/.test(key) || (input.localeId && key.includes(input.localeId));
@@ -436,18 +351,8 @@ export function assertLocaleCacheKey(input) {
     }
     return { ok: diagnostics.length === 0, diagnostics };
 }
-/**
- * LocaleTransition must commit Route realization + PageMeta together.
- * @param {{
- * fromLocale: string,
- * toLocale: string,
- * routeId: string,
- * realizations: Array<{ routeId: string, localeId: string, path: string }>,
- * pageMetaByLocale: Record<string, { locale: string, canonical: string }>,
- * }} input
- */
+/** LocaleTransition must commit Route realization + PageMeta together. */
 export function commitLocaleRouteMetaTransition(input) {
-    /** @type {any[]} */
     const diagnostics = [];
     const fromPath = (input.realizations || []).find((r) => r.routeId === input.routeId && r.localeId === input.fromLocale)?.path;
     const toPath = (input.realizations || []).find((r) => r.routeId === input.routeId && r.localeId === input.toLocale)?.path;
@@ -485,21 +390,8 @@ export function commitLocaleRouteMetaTransition(input) {
         diagnostics,
     };
 }
-/**
- * Aggregate router/meta proof.
- * @param {{
- * manifest: {
- * defaultLocale: string,
- * locales: Array<{ id: string, direction?: string }>,
- * routing?: { strategy?: string, defaultPrefix?: string },
- * },
- * routes: Array<{ routeId: string, path: string }>,
- * titles?: Record<string, Record<string, string>>,
- * origin?: string,
- * }} input
- */
+/** Aggregate router/meta proof. */
 export function checkLocaleRouter(input) {
-    /** @type {any[]} */
     const diagnostics = [];
     const locales = (input.manifest?.locales || []).map((l) => l.id);
     const directions = Object.fromEntries((input.manifest?.locales || []).map((l) => [l.id, l.direction || 'ltr']));
@@ -512,7 +404,6 @@ export function checkLocaleRouter(input) {
     });
     diagnostics.push(...table.diagnostics);
     const origin = input.origin || 'https://example.test';
-    /** @type {any[]} */
     const pageMetas = [];
     for (const route of input.routes || []) {
         for (const loc of locales) {