fimo 0.17.0 → 0.18.0

package/dist/runtime/routes/contract.js

@@ -0,0 +1,377 @@
+// The single source of truth for what a `.fimo/config.json` route means:
+// which of its path placeholders are locales, which are content entries, which
+// URLs it matches, and which URLs it produces. Prefetch, SEO, SSG, sitemap and
+// `fimo validate` all read this module so they cannot drift apart.
+//
+// Browser-safe on purpose: no `node:` imports, no filesystem, no network.
+import { getFimoDefaultLocale, getFimoLocales } from '../i18n/locale.js';
+/**
+ * The reserved parameter name for the locale segment. A `:locale` placeholder
+ * is always the locale, whether or not the route declares a descriptor for it.
+ */
+export const FIMO_LOCALE_PARAM = 'locale';
+export function normalizeRoutePath(path) {
+    const withSlash = path.startsWith('/') ? path : `/${path}`;
+    const collapsed = withSlash.replace(/\/{2,}/g, '/');
+    return collapsed.length > 1 ? collapsed.replace(/\/+$/, '') : collapsed;
+}
+function splitSegments(path) {
+    return path.split('/').filter(Boolean);
+}
+function isPlaceholder(segment) {
+    return segment.startsWith(':') && segment.length > 1;
+}
+function readPlaceholder(segment) {
+    if (!isPlaceholder(segment)) {
+        return null;
+    }
+    return {
+        name: segment.slice(1).replace(/[?*]$/, ''),
+        catchAll: segment.endsWith('*'),
+    };
+}
+/**
+ * True when the path declares a locale segment, in either spelling: the config
+ * writes `:locale`, a React Router registration writes `:locale?` when the
+ * segment may be omitted.
+ */
+export function hasLocaleSegment(path) {
+    return splitSegments(normalizeRoutePath(path)).some((segment) => segment === `:${FIMO_LOCALE_PARAM}` || segment === `:${FIMO_LOCALE_PARAM}?`);
+}
+function resolveParamType(name, descriptor) {
+    if (descriptor?.type) {
+        return descriptor.type;
+    }
+    // Omitting `type` keeps every pre-existing route on the entry type; only the
+    // reserved name flips the default.
+    return name === FIMO_LOCALE_PARAM ? 'locale' : 'entry';
+}
+function buildLocaleParam(name, descriptor, index, issues) {
+    if (name !== FIMO_LOCALE_PARAM) {
+        issues.push({
+            param: name,
+            message: `Param "${name}" declares \`"type": "locale"\` but "${FIMO_LOCALE_PARAM}" is the only locale parameter name.`,
+            fix: `Rename the path segment and the descriptor to ":${FIMO_LOCALE_PARAM}", or use \`"type": "entry"\`.`,
+        });
+        return null;
+    }
+    if (index !== 0) {
+        issues.push({
+            param: name,
+            message: `The ":${FIMO_LOCALE_PARAM}" segment must be the first segment of the path.`,
+            fix: `Move it to the front, for example "/:${FIMO_LOCALE_PARAM}/blog/:slug".`,
+        });
+        return null;
+    }
+    for (const field of ['schema', 'queryField', 'displayField', 'query']) {
+        if (descriptor?.[field] !== undefined) {
+            issues.push({
+                param: name,
+                message: `Locale param "${name}" must not declare "${field}" — the locale is read from the URL, never from the CMS.`,
+                fix: `Remove "${field}" from \`params.${name}\`.`,
+            });
+        }
+    }
+    return { type: 'locale', name, optional: descriptor?.optional !== false };
+}
+function buildEntryParam(name, descriptor, issues) {
+    if (name === FIMO_LOCALE_PARAM) {
+        issues.push({
+            param: name,
+            message: `Param "${name}" is reserved for the locale segment and cannot use \`"type": "entry"\`.`,
+            fix: `Drop \`"type": "entry"\` from \`params.${name}\`, or rename the segment.`,
+        });
+        return null;
+    }
+    if (!descriptor) {
+        issues.push({
+            param: name,
+            message: `":${name}" needs \`params\` metadata before its URLs can be generated.`,
+            fix: `Add \`"params": { "${name}": { "schema": "SchemaName", "queryField": "${name}" } }\`.`,
+        });
+        return null;
+    }
+    if (descriptor.optional !== undefined) {
+        issues.push({
+            param: name,
+            message: `Entry param "${name}" cannot be optional — only the locale segment can be omitted from a URL.`,
+            fix: `Remove "optional" from \`params.${name}\`.`,
+        });
+    }
+    if (!descriptor.schema || !descriptor.queryField) {
+        issues.push({
+            param: name,
+            message: `Entry param "${name}" is missing ${!descriptor.schema ? '"schema"' : '"queryField"'}.`,
+            fix: `Set \`"${name}": { "schema": "SchemaName", "queryField": "${name}" }\`.`,
+        });
+        return null;
+    }
+    return {
+        type: 'entry',
+        name,
+        schema: descriptor.schema,
+        queryField: descriptor.queryField,
+        ...(descriptor.displayField ? { displayField: descriptor.displayField } : {}),
+    };
+}
+/**
+ * Normalize one declared route into the contract every consumer reads.
+ *
+ * Parameter types resolve in this order:
+ * 1. an explicit `type`;
+ * 2. the reserved name `locale`, which infers the locale type;
+ * 3. otherwise the entry type, which is what every route written before
+ *    locale-aware routing existed relies on.
+ */
+export function resolveRouteContract(id, route) {
+    const path = normalizeRoutePath(route.path ?? '/');
+    const segments = splitSegments(path);
+    const declared = route.params ?? {};
+    const issues = [];
+    const params = [];
+    const unresolvedParams = [];
+    const seen = new Set();
+    segments.forEach((segment, index) => {
+        if (!isPlaceholder(segment)) {
+            return;
+        }
+        const placeholder = readPlaceholder(segment);
+        if (!placeholder) {
+            return;
+        }
+        const { name } = placeholder;
+        if (seen.has(name)) {
+            issues.push({
+                param: name,
+                message: `Placeholder ":${name}" appears more than once.`,
+                fix: 'Give each placeholder a distinct name.',
+            });
+            unresolvedParams.push(name);
+            return;
+        }
+        seen.add(name);
+        const descriptor = declared[name];
+        const resolved = resolveParamType(name, descriptor) === 'locale'
+            ? buildLocaleParam(name, descriptor, index, issues)
+            : buildEntryParam(name, descriptor, issues);
+        if (resolved) {
+            params.push(resolved);
+        }
+        else {
+            unresolvedParams.push(name);
+        }
+    });
+    for (const name of Object.keys(declared)) {
+        if (!seen.has(name)) {
+            issues.push({
+                param: name,
+                message: `Declared param "${name}" has no ":${name}" segment in the path.`,
+                fix: `Add ":${name}" to the path, or remove it from "params".`,
+            });
+        }
+    }
+    const localeParam = params.find((param) => param.type === 'locale') ?? null;
+    const canonicalPath = localeParam
+        ? normalizeRoutePath(`/${segments.filter((segment) => segment !== `:${FIMO_LOCALE_PARAM}`).join('/')}`)
+        : path;
+    return {
+        id,
+        config: route,
+        path,
+        canonicalPath,
+        params,
+        entryParams: params.filter((param) => param.type === 'entry'),
+        localeParam,
+        unresolvedParams,
+        issues,
+    };
+}
+export function resolveRouteContracts(routes) {
+    return Object.entries(routes ?? {}).map(([id, route]) => resolveRouteContract(id, route));
+}
+function readLocaleVocabulary(config) {
+    return {
+        locales: config.i18n ? getFimoLocales(config) : null,
+        defaultLocale: getFimoDefaultLocale(config),
+    };
+}
+/**
+ * Whether `segment` may stand in the locale slot of this route.
+ *
+ * An optional locale rejects the default locale: `/hello` is the canonical
+ * default-locale URL, so `/en/hello` is a different URL that this route does
+ * not serve rather than an alias of it.
+ */
+function acceptsLocaleSegment(segment, localeParam, vocabulary) {
+    if (!vocabulary.locales) {
+        return segment.length > 0;
+    }
+    if (!vocabulary.locales.includes(segment)) {
+        return false;
+    }
+    return localeParam.optional ? segment !== vocabulary.defaultLocale : true;
+}
+function matchContract(urlSegments, contract, vocabulary) {
+    const patternSegments = splitSegments(contract.path);
+    const localeParam = contract.localeParam;
+    const catchAllIndex = patternSegments.findIndex((segment) => readPlaceholder(segment)?.catchAll);
+    const hasCatchAll = catchAllIndex !== -1;
+    const hasLocaleLength = hasCatchAll
+        ? urlSegments.length >= patternSegments.length
+        : urlSegments.length === patternSegments.length;
+    const withLocale = localeParam?.optional
+        ? hasLocaleLength && acceptsLocaleSegment(urlSegments[0] ?? '', localeParam, vocabulary)
+        : hasLocaleLength;
+    const withoutLocale = Boolean(localeParam?.optional) &&
+        (hasCatchAll
+            ? urlSegments.length >= patternSegments.length - 1
+            : urlSegments.length === patternSegments.length - 1);
+    if (!localeParam && !withLocale) {
+        return null;
+    }
+    if (localeParam && !withLocale && !withoutLocale) {
+        return null;
+    }
+    const params = {};
+    const entryParams = {};
+    let localeFromPath = null;
+    let score = 0;
+    let offset = 0;
+    for (const [index, patternSegment] of patternSegments.entries()) {
+        if (localeParam && patternSegment === `:${FIMO_LOCALE_PARAM}`) {
+            if (!withLocale) {
+                // The optional locale is absent: every later segment shifts left.
+                offset = -1;
+                continue;
+            }
+            const value = urlSegments[index];
+            if (!acceptsLocaleSegment(value, localeParam, vocabulary)) {
+                return null;
+            }
+            localeFromPath = value;
+            params[FIMO_LOCALE_PARAM] = value;
+            continue;
+        }
+        const value = urlSegments[index + offset];
+        if (value === undefined) {
+            return null;
+        }
+        const placeholder = readPlaceholder(patternSegment);
+        if (placeholder) {
+            const { name, catchAll } = placeholder;
+            const rawValue = catchAll ? urlSegments.slice(index + offset).join('/') : value;
+            const decoded = safeDecode(rawValue);
+            params[name] = decoded;
+            entryParams[name] = decoded;
+            if (catchAll) {
+                break;
+            }
+            continue;
+        }
+        if (patternSegment !== value) {
+            return null;
+        }
+        score += 1;
+    }
+    return {
+        contract,
+        params,
+        entryParams,
+        locale: localeFromPath ?? vocabulary.defaultLocale,
+        localeFromPath: localeFromPath !== null,
+        score,
+    };
+}
+/** Callers pass a pathname or a whole request URL; both must reduce to a path. */
+function readPathname(input) {
+    try {
+        return new URL(input, 'http://fimo.invalid').pathname;
+    }
+    catch {
+        return input.split('#')[0].split('?')[0] || '/';
+    }
+}
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Match a concrete pathname against the project's routes.
+ *
+ * The truth table, for a route declared `/:locale/x/:slug` in a project whose
+ * default locale is `en`:
+ *
+ * | URL             | locale param | resolved locale | entry params        |
+ * | --------------- | ------------ | --------------- | ------------------- |
+ * | `/x/hello`      | optional     | `en` (default)  | `{ slug: 'hello' }` |
+ * | `/fr/x/bonjour` | optional     | `fr`            | `{ slug: 'bonjour'}`|
+ * | `/en/x/hello`   | optional     | no match        | —                   |
+ * | `/x/hello`      | required     | no match        | —                   |
+ * | `/en/x/hello`   | required     | `en`            | `{ slug: 'hello' }` |
+ *
+ * A route with no locale segment always resolves the default locale.
+ */
+export function matchFimoRoute(pathnameOrUrl, config) {
+    const urlSegments = splitSegments(normalizeRoutePath(readPathname(pathnameOrUrl)));
+    const vocabulary = readLocaleVocabulary(config);
+    let best = null;
+    for (const contract of resolveRouteContracts(config.routes)) {
+        // A route entry without a declared path describes no URL — matching it
+        // against the normalized `/` default would hijack the index route.
+        if (!contract.config.path) {
+            continue;
+        }
+        const match = matchContract(urlSegments, contract, vocabulary);
+        if (match && (!best || match.score > best.score)) {
+            best = match;
+        }
+    }
+    return best;
+}
+/**
+ * The URL shapes a route produces, one per locale it can render.
+ *
+ * A route without a locale segment produces a single default-locale URL: under
+ * path-prefix routing it has no way to express another locale in its path.
+ */
+export function routeLocaleTargets(contract, config) {
+    const defaultLocale = getFimoDefaultLocale(config);
+    if (!contract.localeParam) {
+        return [{ locale: defaultLocale, prefixed: false }];
+    }
+    const optional = contract.localeParam.optional;
+    return getFimoLocales(config).map((locale) => ({
+        locale,
+        prefixed: optional ? locale !== defaultLocale : true,
+    }));
+}
+/**
+ * Build the concrete URL for one locale target. Entry param values are
+ * URL-encoded; the locale segment is a prefix, never a substitution, so the
+ * canonical default-locale URL carries no locale at all.
+ */
+export function materializeRoutePath(contract, target) {
+    const params = target.params ?? {};
+    const substituted = splitSegments(contract.canonicalPath).map((segment) => {
+        const placeholder = readPlaceholder(segment);
+        if (!placeholder) {
+            return segment;
+        }
+        const value = params[placeholder.name];
+        if (value === undefined) {
+            return segment;
+        }
+        return placeholder.catchAll
+            ? value
+                .split('/')
+                .map((part) => encodeURIComponent(part))
+                .join('/')
+            : encodeURIComponent(value);
+    });
+    const prefix = target.prefixed ? [target.locale] : [];
+    return normalizeRoutePath(`/${[...prefix, ...substituted].join('/')}`);
+}

package/dist/runtime/routes/index.d.ts

@@ -0,0 +1,3 @@
+export { FIMO_LOCALE_PARAM, hasLocaleSegment, materializeRoutePath, matchFimoRoute, normalizeRoutePath, resolveRouteContract, resolveRouteContracts, routeLocaleTargets, } from './contract.js';
+export type { FimoEntryParam, FimoLocaleParam, FimoRouteContract, FimoRouteIssue, FimoRouteLocaleTarget, FimoRouteMatch, FimoRouteParam, } from './contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/routes/index.js

@@ -0,0 +1,3 @@
+// `fimo/routes` — the shared route contract read by every consumer of
+// `.fimo/config.json#routes`.
+export { FIMO_LOCALE_PARAM, hasLocaleSegment, materializeRoutePath, matchFimoRoute, normalizeRoutePath, resolveRouteContract, resolveRouteContracts, routeLocaleTargets, } from './contract.js';

package/dist/runtime/routing/AppRoutesProvider.js

@@ -8,7 +8,7 @@ import { AppErrorBoundary, onError } from '../core/AppErrorBoundary.js';
 import { ViteLifecycles } from '../core/ViteLifecycles.js';
 import { ScreenshotProvider } from '../iframe/ScreenshotProvider.js';
 import { getSafePreviewNavigationPath, isPreviewRuntimeEnabled } from '../preview/bridge.js';
-import { getPreviewLocationChange, getPreviewParentOrigin } from '../preview/location.js';
+import { getDocumentLocale, getPreviewLocationChange, getPreviewParentOrigin } from '../preview/location.js';
 import { OptionalTracking } from '../t/OptionalTracking.js';
 import { AppResetScrollOnNavigate } from './AppResetScrollOnNavigate.js';
 const titleCase = (seg) => seg
@@ -63,15 +63,16 @@ export function AppRoutesProvider({ appRoutes, children }) {
         }
         window.parent.postMessage({ type: 'nav/routes', payload: { routes: displayRoutes } }, getPreviewParentOrigin() ?? '*');
     }, [appRoutes, displayRoutes, previewEnabled]);
+    // This runtime predates locale-aware routing and has no fimo-config to read,
+    // so the document's own `lang` is the only locale the app has declared.
     const sendLocationChange = useCallback(() => {
         if (!previewEnabled) {
             return;
         }
-        const locationChange = getPreviewLocationChange(location);
         const parentOrigin = getPreviewParentOrigin();
         window.parent.postMessage({
             type: 'nav/locationChange',
-            payload: parentOrigin ? locationChange : { path: locationChange.path },
+            payload: getPreviewLocationChange(location, getDocumentLocale(document, 'en'), parentOrigin),
         }, parentOrigin ?? '*');
     }, [location.hash, location.pathname, location.search, previewEnabled]);
     useEffect(sendRoutes, [sendRoutes]);

package/dist/runtime/seo/resolver.d.ts

@@ -28,6 +28,11 @@ import type { FimoConfig, FimoRouteConfig, FimoSEO } from '../shared/fimo-config
  */
 export declare const SEO_FIELD_KEYS: readonly ["title", "description", "siteName", "url", "image", "favicon", "twitterSite", "robots", "themeColor", "locale"];
 export declare function normalizePathname(pathname: string): string;
+/**
+ * Whether one pattern matches one path, and how specific the match is (the
+ * number of static segments it pinned down). Locale-aware: a pattern with a
+ * `:locale` segment matches both the prefixed and the canonical URL.
+ */
 export declare function matchRoutePath(pathname: string, pathPattern: string): {
     matched: boolean;
     score: number;

package/dist/runtime/seo/resolver.js

@@ -1,3 +1,4 @@
+import { matchFimoRoute } from '../routes/contract.js';
 /**
  * Shared SEO resolver for the generated app.
  *
@@ -45,53 +46,20 @@ export function normalizePathname(pathname) {
     }
     return normalized;
 }
-function splitSegments(pathname) {
-    const normalized = normalizePathname(pathname);
-    if (normalized === '/') {
-        return [];
-    }
-    return normalized.slice(1).split('/');
-}
+/**
+ * Whether one pattern matches one path, and how specific the match is (the
+ * number of static segments it pinned down). Locale-aware: a pattern with a
+ * `:locale` segment matches both the prefixed and the canonical URL.
+ */
 export function matchRoutePath(pathname, pathPattern) {
-    const pathSegments = splitSegments(pathname);
-    const patternSegments = splitSegments(pathPattern);
-    if (pathSegments.length !== patternSegments.length) {
-        return { matched: false, score: -1 };
-    }
-    let staticSegments = 0;
-    for (let i = 0; i < patternSegments.length; i += 1) {
-        const routeSegment = patternSegments[i];
-        const inputSegment = pathSegments[i];
-        if (routeSegment.startsWith(':')) {
-            continue;
-        }
-        if (routeSegment !== inputSegment) {
-            return { matched: false, score: -1 };
-        }
-        staticSegments += 1;
-    }
-    return { matched: true, score: staticSegments };
+    const match = matchFimoRoute(pathname, { routes: { route: { path: pathPattern } } });
+    return match ? { matched: true, score: match.score } : { matched: false, score: -1 };
 }
 export function resolveRouteConfig(pathname, routes) {
     if (!routes) {
         return undefined;
     }
-    const normalizedPath = normalizePathname(pathname);
-    let bestMatch;
-    for (const routeConfig of Object.values(routes)) {
-        const pathPattern = routeConfig.path;
-        if (!pathPattern) {
-            continue;
-        }
-        const result = matchRoutePath(normalizedPath, pathPattern);
-        if (!result.matched) {
-            continue;
-        }
-        if (!bestMatch || result.score > bestMatch.score) {
-            bestMatch = { score: result.score, route: routeConfig };
-        }
-    }
-    return bestMatch?.route;
+    return matchFimoRoute(pathname, { routes })?.contract.config;
 }
 export function getNestedValue(input, path) {
     if (!input || typeof input !== 'object') {
@@ -124,7 +92,7 @@ function resolveSeoField(routeValue, globalValue, context) {
 }
 export function resolveSeoForPath(pathname, config, routeData) {
     const globalSeo = config.seo ?? {};
-    const routeConfig = resolveRouteConfig(pathname, config.routes);
+    const routeConfig = matchFimoRoute(pathname, config)?.contract.config;
     const routeSeo = routeConfig?.seo;
     if (!routeSeo) {
         return Object.keys(globalSeo).length > 0 ? globalSeo : undefined;

package/dist/runtime/shared/fimo-config.types.d.ts

@@ -40,20 +40,47 @@ export interface RouteSEO {
     locale?: string;
     siteName?: string;
 }
+/**
+ * A path parameter descriptor as it appears in `.fimo/config.json`.
+ *
+ * Deliberately permissive — it mirrors hand-written JSON. `resolveRouteContract`
+ * in `runtime/routes/contract.ts` narrows it into the discriminated
+ * `FimoRouteParam` union and reports whatever does not add up; `fimo validate`
+ * surfaces those issues.
+ */
+export interface FimoRouteParamConfig {
+    /**
+     * Omitted means `'entry'`, which is what every route written before
+     * locale-aware routing relies on. The reserved name `locale` infers
+     * `'locale'` instead.
+     */
+    type?: 'entry' | 'locale';
+    /** Entry params only, and required for them. */
+    schema?: string;
+    queryField?: string;
+    displayField?: string;
+    query?: import('@fimo/api-contracts').PageCollectionSourceQuery;
+    /** Locale params only. Defaults to true: the default locale is unprefixed. */
+    optional?: boolean;
+}
 export interface FimoRouteConfig {
     label?: string;
     path?: string;
-    params?: Record<string, {
-        schema: string;
-        queryField: string;
-        displayField: string;
-    }>;
+    group?: string;
+    content?: {
+        labels?: string[];
+        singles?: string[];
+    };
+    sources?: import('@fimo/api-contracts').PageSources;
+    icon?: string;
+    params?: Record<string, FimoRouteParamConfig>;
     seo?: RouteSEO;
 }
 export interface FimoI18nRoutingConfig {
     /**
-     * Supported now:
-     * - path-prefix: default locale renders at `/pricing`, non-default locales at `/es/pricing`.
+     * Legacy compatibility for projects that still carry a global routing
+     * setting. New projects declare locale ownership on each route with a
+     * `:locale` segment; the scaffold intentionally omits this block.
      *
      * Strategies we may support later:
      * - domain: `example.es/pricing`
@@ -63,7 +90,6 @@ export interface FimoI18nRoutingConfig {
      * - custom: framework code resolves locale and passes it to `<FimoProviders locale={...}>`
      */
     strategy?: 'path-prefix';
-    prefixDefaultLocale?: boolean;
 }
 export interface FimoI18nConfig {
     defaultLocale?: string;

package/dist/runtime/shared/preview-location.d.ts

@@ -1,23 +1,2 @@
-export interface PreviewLocationLike {
-    pathname: string;
-    search?: string;
-    hash?: string;
-}
-export interface PreviewLocationChange {
-    /** Safe workspace focus value; query/hash state stays navigation-only. */
-    path: string;
-    /** Exact app location used to keep the parent's iframe URL in sync. */
-    navigationPath: string;
-}
-export interface PreviewBrowserContext {
-    readonly window: Pick<Window, 'location' | 'sessionStorage'>;
-    readonly document: Pick<Document, 'referrer'>;
-}
-/** Prefer the immediate embedding document over a potentially stale referrer. */
-export declare function resolvePreviewParentOrigin(referrer: string | undefined, ancestorOrigins: readonly string[] | undefined): string | null;
-/** Resolve and remember the trusted Studio origin across full-page navigation. */
-export declare function getPreviewParentOrigin(browser?: PreviewBrowserContext): string | null;
-/** Keep sandbox credentials and the iframe cache-buster out of app navigation state. */
-export declare function getPreviewLocationPath(location: PreviewLocationLike): string;
-export declare function getPreviewLocationChange(location: PreviewLocationLike): PreviewLocationChange;
+export * from '../preview/location.js';
 //# sourceMappingURL=preview-location.d.ts.map