fimo 0.16.0 → 0.18.0

package/dist/runtime/paths/get-fimo-paths.js

@@ -3,7 +3,7 @@
 // dynamic routes are expanded by fetching schema entries from the content API.
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { getFimoLocales, localizeFimoPath } from '../i18n/locale.js';
+import { materializeRoutePath, resolveRouteContracts, routeLocaleTargets } from '../routes/contract.js';
 import { resolveSeoForPath } from '../seo/resolver.js';
 import { getConfigServer } from '../shared/fimo-config.server.js';
 import { resolveLocalRuntimeEnv } from '../shared/local-runtime-env.js';
@@ -82,11 +82,12 @@ function matchesAny(routeKey, patterns) {
  * robots.txt, or any per-route logic.
  *
  * - Static paths in config: emitted as-is.
- * - Dynamic paths (with `:slug`-style params): expanded by fetching schema
- *   entries from `VITE_API_URL`. One returned entry per dynamic expansion.
- * - With `i18n.routing.strategy: "path-prefix"`, paths are emitted for every
- *   configured locale: default locale unprefixed by default, non-default
- *   locales prefixed (`/es/...`). The app router still needs matching routes.
+ * - Dynamic paths (with `:slug`-style entry params): expanded by fetching
+ *   schema entries from `VITE_API_URL`. One returned entry per expansion.
+ * - Locales come from the route contract, not from the project locale list: a
+ *   route is emitted once per locale only when its path declares a `:locale`
+ *   segment. The default locale is always unprefixed. A route without a
+ *   `:locale` segment yields exactly one default-locale path.
  * - Pure-string return shape (`p.path`) is suitable for RR's `prerender`.
  *
  * If no API URL is set, dynamic routes are skipped with a console warning.
@@ -110,14 +111,20 @@ function matchesAny(routeKey, patterns) {
 export async function getFimoPaths(opts = {}) {
     const rootDir = opts.cwd ?? process.cwd();
     const config = getConfigServer(rootDir);
-    const locales = getFimoLocales(config);
-    const routesEntries = Object.entries(config.routes ?? {});
     // Pre-filter route keys by include/exclude before doing any network I/O.
-    const filteredRoutes = routesEntries.filter(([routeKey]) => {
-        if (opts.include && opts.include.length > 0 && !matchesAny(routeKey, opts.include)) {
+    const contracts = resolveRouteContracts(config.routes).filter((contract) => {
+        if (!contract.config.path) {
             return false;
         }
-        if (opts.exclude && opts.exclude.length > 0 && matchesAny(routeKey, opts.exclude)) {
+        // A placeholder no descriptor resolves cannot be expanded into a URL;
+        // `fimo validate` is what reports it.
+        if (contract.unresolvedParams.length > 0) {
+            return false;
+        }
+        if (opts.include && opts.include.length > 0 && !matchesAny(contract.id, opts.include)) {
+            return false;
+        }
+        if (opts.exclude && opts.exclude.length > 0 && matchesAny(contract.id, opts.exclude)) {
             return false;
         }
         return true;
@@ -125,20 +132,18 @@ export async function getFimoPaths(opts = {}) {
     const results = [];
     const schemaCache = new Map();
     let baseUrl = null; // lazy-resolved on first dynamic route
-    for (const [routeKey, routeConfig] of filteredRoutes) {
-        const pathPattern = routeConfig.path;
-        if (!pathPattern) {
-            continue;
-        }
-        const isDynamic = pathPattern.includes(':') && routeConfig.params;
-        if (!isDynamic) {
-            for (const locale of locales) {
+    for (const contract of contracts) {
+        const targets = routeLocaleTargets(contract, config);
+        // Static — no entry param, so no content to fetch. A locale param alone
+        // never reaches the CMS.
+        if (contract.entryParams.length === 0) {
+            for (const target of targets) {
                 results.push({
-                    routeKey,
-                    pathPattern,
-                    path: localizeFimoPath(pathPattern, locale, config),
-                    locale,
-                    seo: resolveSeoForPath(pathPattern, config),
+                    routeKey: contract.id,
+                    pathPattern: contract.path,
+                    path: materializeRoutePath(contract, target),
+                    locale: target.locale,
+                    seo: resolveSeoForPath(contract.canonicalPath, config),
                 });
             }
             continue;
@@ -153,40 +158,36 @@ export async function getFimoPaths(opts = {}) {
         if (!baseUrl) {
             continue;
         }
-        const paramEntries = Object.entries(routeConfig.params);
-        const schemas = [...new Set(paramEntries.map(([, p]) => p.schema))];
+        const schemas = [...new Set(contract.entryParams.map((param) => param.schema))];
         for (const schema of schemas) {
-            for (const locale of locales) {
-                const cacheKey = `${locale}:${schema}`;
+            for (const target of targets) {
+                const cacheKey = `${target.locale}:${schema}`;
                 if (!schemaCache.has(cacheKey)) {
-                    schemaCache.set(cacheKey, await fetchEntries(baseUrl, schema, rootDir, locale));
+                    schemaCache.set(cacheKey, await fetchEntries(baseUrl, schema, rootDir, target.locale));
                 }
             }
         }
-        for (const locale of locales) {
-            const entries = schemaCache.get(`${locale}:${paramEntries[0][1].schema}`) ?? [];
+        for (const target of targets) {
+            const entries = schemaCache.get(`${target.locale}:${contract.entryParams[0].schema}`) ?? [];
             for (const entry of entries) {
-                let expandedPath = pathPattern;
                 const params = {};
                 let valid = true;
-                for (const [paramName, paramInfo] of paramEntries) {
-                    const value = entry[paramInfo.queryField];
+                for (const param of contract.entryParams) {
+                    const value = entry[param.queryField];
                     if (value == null || value === '') {
                         valid = false;
                         break;
                     }
-                    const stringValue = String(value);
-                    params[paramName] = stringValue;
-                    expandedPath = expandedPath.replace(`:${paramName}`, encodeURIComponent(stringValue));
+                    params[param.name] = String(value);
                 }
                 if (valid) {
                     results.push({
-                        routeKey,
-                        pathPattern,
-                        path: localizeFimoPath(expandedPath, locale, config),
-                        locale,
+                        routeKey: contract.id,
+                        pathPattern: contract.path,
+                        path: materializeRoutePath(contract, { ...target, params }),
+                        locale: target.locale,
                         params,
-                        seo: resolveSeoForPath(expandedPath, config),
+                        seo: resolveSeoForPath(materializeRoutePath(contract, { locale: target.locale, prefixed: false, params }), config),
                     });
                 }
             }

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

@@ -7,7 +7,13 @@ 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;
+    navigationPath?: string;
+    /**
+     * The locale the app settled on for this location. The app owns locale
+     * detection, so Studio stores this value rather than deriving one from
+     * `path`, and the bridge re-sends it when only the locale changed.
+     */
+    locale: string;
 }
 export interface PreviewBrowserContext {
     readonly window: Pick<Window, 'location' | 'sessionStorage'>;
@@ -19,5 +25,16 @@ export declare function resolvePreviewParentOrigin(referrer: string | undefined,
 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;
+/**
+ * Build the `nav/locationChange` payload. `navigationPath` carries the app's
+ * own query and hash state, so it is withheld until a parent origin is
+ * established and the message can be addressed to it instead of broadcast.
+ */
+export declare function getPreviewLocationChange(location: PreviewLocationLike, locale: string, parentOrigin: string | null): PreviewLocationChange;
+/**
+ * The locale the rendered document declares. Every Fimo framework shell writes
+ * `<html lang>` once it has settled the locale for the page, which makes it the
+ * app's own answer rather than a guess made from the URL.
+ */
+export declare function getDocumentLocale(browserDocument: Pick<Document, 'documentElement'> | undefined, fallbackLocale: string): string;
 //# sourceMappingURL=location.d.ts.map

package/dist/runtime/preview/location.js

@@ -85,9 +85,23 @@ export function getPreviewLocationPath(location) {
     const query = search.toString();
     return `${location.pathname}${query ? `?${query}` : ''}${location.hash ?? ''}`;
 }
-export function getPreviewLocationChange(location) {
+/**
+ * Build the `nav/locationChange` payload. `navigationPath` carries the app's
+ * own query and hash state, so it is withheld until a parent origin is
+ * established and the message can be addressed to it instead of broadcast.
+ */
+export function getPreviewLocationChange(location, locale, parentOrigin) {
     return {
         path: location.pathname,
-        navigationPath: getPreviewLocationPath(location),
+        ...(parentOrigin ? { navigationPath: getPreviewLocationPath(location) } : {}),
+        locale,
     };
 }
+/**
+ * The locale the rendered document declares. Every Fimo framework shell writes
+ * `<html lang>` once it has settled the locale for the page, which makes it the
+ * app's own answer rather than a guess made from the URL.
+ */
+export function getDocumentLocale(browserDocument, fallbackLocale) {
+    return browserDocument?.documentElement?.lang?.trim() || fallbackLocale;
+}

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

@@ -2,6 +2,7 @@ export { Text } from '../react/primitives/editable/Text.js';
 export { Image, StaticImage } from '../vite/primitives/Images.js';
 export { Video } from '../react/primitives/editable/Video.js';
 export { Date } from '../react/primitives/editable/Date.js';
+export { DateTime } from '../react/primitives/editable/DateTime.js';
 export { Boolean } from '../react/primitives/editable/Boolean.js';
 export { Json } from '../react/primitives/editable/Json.js';
 export { RichText } from '../react/primitives/editable/RichText.js';

package/dist/runtime/primitives/index.js

@@ -5,6 +5,7 @@ export { Text } from '../react/primitives/editable/Text.js';
 export { Image, StaticImage } from '../vite/primitives/Images.js';
 export { Video } from '../react/primitives/editable/Video.js';
 export { Date } from '../react/primitives/editable/Date.js';
+export { DateTime } from '../react/primitives/editable/DateTime.js';
 export { Boolean } from '../react/primitives/editable/Boolean.js';
 export { Json } from '../react/primitives/editable/Json.js';
 export { RichText } from '../react/primitives/editable/RichText.js';

package/dist/runtime/react/primitives/editable/DateTime.d.ts

@@ -0,0 +1,4 @@
+import type { DateProps } from '../contracts.js';
+/** Renders a `datetime` field: the `dateTime` attribute keeps the whole instant. */
+export declare function DateTime({ value, ...props }: DateProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=DateTime.d.ts.map

package/dist/runtime/react/primitives/editable/DateTime.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FIMO_SOURCE } from '../../../primitives/lib/index.js';
+import { useFimoLiveValue } from '../../useFimoLiveValue.js';
+import { DateRenderer } from '../renderers/DateRenderer.js';
+/** Renders a `datetime` field: the `dateTime` attribute keeps the whole instant. */
+export function DateTime({ value, ...props }) {
+    const { value: liveValue, ref } = useFimoLiveValue(value ?? null);
+    if (!liveValue) {
+        return null;
+    }
+    const source = typeof value === 'object' && FIMO_SOURCE in value ? (value[FIMO_SOURCE] ?? undefined) : undefined;
+    return _jsx(DateRenderer, { ...props, value: liveValue, source: source, precision: "instant", elementRef: ref });
+}

package/dist/runtime/react/primitives/renderers/DateRenderer.d.ts

@@ -3,9 +3,15 @@ import type { FimoDate, FimoString } from '../../../primitives/lib/index.js';
 export interface DateRendererProps {
     value: FimoDate | FimoString | Date | string | number;
     source: string | undefined;
+    /**
+     * `day` emits the calendar day in `dateTime`; `instant` keeps the full ISO
+     * instant, which is the whole point of a `datetime` field. Defaults to `day`
+     * so `<Date>` renders exactly what it always has.
+     */
+    precision?: 'day' | 'instant';
     children?: (date: Date) => ReactNode;
     className?: string;
     elementRef?: Ref<HTMLTimeElement>;
 }
-export declare function DateRenderer({ value, source, children, className, elementRef }: DateRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function DateRenderer({ value, source, precision, children, className, elementRef }: DateRendererProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=DateRenderer.d.ts.map

package/dist/runtime/react/primitives/renderers/DateRenderer.js

@@ -1,14 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-export function DateRenderer({ value, source, children, className, elementRef }) {
+export function DateRenderer({ value, source, precision = 'day', children, className, elementRef }) {
     const rawValue = value instanceof String ? value.toString() : value;
     const dateValue = new globalThis.Date(rawValue);
-    const isoDate = dateValue.toISOString().split('T')[0];
+    const iso = dateValue.toISOString();
+    const dateTime = precision === 'instant' ? iso : iso.split('T')[0];
     const content = children
         ? children(dateValue)
-        : dateValue.toLocaleDateString(undefined, {
-            year: 'numeric',
-            month: 'short',
-            day: 'numeric',
-        });
-    return (_jsx("time", { ref: elementRef, dateTime: isoDate, className: className, "data-fimo-source": source, children: content }));
+        : precision === 'instant'
+            ? dateValue.toLocaleString(undefined, { dateStyle: 'medium', timeStyle: 'short' })
+            : dateValue.toLocaleDateString(undefined, {
+                year: 'numeric',
+                month: 'short',
+                day: 'numeric',
+            });
+    return (_jsx("time", { ref: elementRef, dateTime: dateTime, className: className, "data-fimo-source": source, children: content }));
 }

package/dist/runtime/react-router/{routes.d.ts → legacy/routes.d.ts}

@@ -1,4 +1,4 @@
-import type { FimoConfig } from '../shared/fimo-config.types.js';
+import type { FimoConfig } from '../../shared/fimo-config.types.js';
 export interface FimoReactRouterRoute {
     id?: string;
     path?: string;
@@ -25,6 +25,11 @@ export interface FimoRoutesOptions {
     config?: Pick<FimoConfig, 'i18n'>;
     rootDir?: string;
 }
+/**
+ * @deprecated New React Router projects should declare optional `:locale?`
+ * segments directly. This compatibility adapter may be removed in a future
+ * breaking release.
+ */
 export declare function fimoRoutes<T extends FimoRouteShape>(routes: readonly T[], options?: FimoRoutesOptions): T[];
 export {};
 //# sourceMappingURL=routes.d.ts.map

package/dist/runtime/react-router/{routes.js → legacy/routes.js}

@@ -1,5 +1,11 @@
-import { getFimoDefaultLocale, getFimoLocales } from '../i18n/locale.js';
-import { getConfigServer } from '../shared/fimo-config.server.js';
+import { getFimoDefaultLocale, getFimoLocales } from '../../i18n/locale.js';
+import { hasLocaleSegment } from '../../routes/contract.js';
+import { getConfigServer } from '../../shared/fimo-config.server.js';
+/**
+ * @deprecated New React Router projects should declare optional `:locale?`
+ * segments directly. This compatibility adapter may be removed in a future
+ * breaking release.
+ */
 export function fimoRoutes(routes, options = {}) {
     const config = options.config ?? getConfigServer(options.rootDir ?? process.cwd());
     const strategy = config.i18n?.routing?.strategy ?? 'path-prefix';
@@ -7,21 +13,30 @@ export function fimoRoutes(routes, options = {}) {
         return [...routes];
     }
     const defaultLocale = getFimoDefaultLocale(config);
-    const locales = getFimoLocales(config);
-    const prefixDefaultLocale = config.i18n?.routing?.prefixDefaultLocale === true;
-    const prefixedLocales = locales.filter((locale) => locale !== defaultLocale || prefixDefaultLocale);
-    if (prefixedLocales.length === 0) {
+    // The default locale renders at the canonical unprefixed path, so it never
+    // gets an alias.
+    const prefixedLocales = getFimoLocales(config).filter((locale) => locale !== defaultLocale);
+    // A route that declares its own `:locale` segment already carries the locale
+    // in its path; prefixing it again would produce `/es/:locale/...`.
+    const aliasable = routes.filter((route) => !declaresLocaleSegment(route));
+    if (prefixedLocales.length === 0 || aliasable.length === 0) {
         return [...routes];
     }
     return [
         ...routes,
-        ...prefixedLocales.flatMap((locale) => routes.map((route, index) => localizeRouteEntry(route, {
+        ...prefixedLocales.flatMap((locale) => aliasable.map((route, index) => localizeRouteEntry(route, {
             locale,
             prefixThisEntry: true,
             routeKey: String(index),
         }))),
     ];
 }
+function declaresLocaleSegment(route) {
+    if (route.path && hasLocaleSegment(route.path)) {
+        return true;
+    }
+    return (route.children ?? []).some(declaresLocaleSegment);
+}
 function localizeRouteEntry(route, options) {
     const clone = {
         ...route,

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

@@ -0,0 +1,116 @@
+import type { FimoConfig, FimoRouteConfig } from '../shared/fimo-config.types.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 declare const FIMO_LOCALE_PARAM = "locale";
+export interface FimoEntryParam {
+    type: 'entry';
+    name: string;
+    schema: string;
+    queryField: string;
+    displayField?: string;
+}
+export interface FimoLocaleParam {
+    type: 'locale';
+    name: string;
+    /**
+     * True (the default) means the default locale renders at the unprefixed
+     * path and only other locales carry a `/<locale>` prefix. False means every
+     * locale, the default included, renders behind the prefix.
+     */
+    optional: boolean;
+}
+export type FimoRouteParam = FimoEntryParam | FimoLocaleParam;
+export interface FimoRouteIssue {
+    /** The parameter the issue is about, when it is about one. */
+    param?: string;
+    message: string;
+    /** A concrete edit that resolves the issue. */
+    fix: string;
+}
+export interface FimoRouteContract {
+    id: string;
+    /** The declared route entry, kept so callers can reach `label` / `seo`. */
+    config: FimoRouteConfig;
+    /** The declared path, locale placeholder included (`/:locale/blog/:slug`). */
+    path: string;
+    /** The declared path without the locale placeholder (`/blog/:slug`). */
+    canonicalPath: string;
+    params: FimoRouteParam[];
+    entryParams: FimoEntryParam[];
+    localeParam: FimoLocaleParam | null;
+    /** Placeholders in the path that no usable descriptor resolves. */
+    unresolvedParams: string[];
+    issues: FimoRouteIssue[];
+}
+export interface FimoRouteMatch {
+    contract: FimoRouteContract;
+    /** Every resolved path parameter, the locale segment included. */
+    params: Record<string, string>;
+    /** Entry parameters only — the subset a content lookup may use. */
+    entryParams: Record<string, string>;
+    /** The locale this URL renders. The project default when the path omits it. */
+    locale: string;
+    /** True when the locale came from a path segment rather than the default. */
+    localeFromPath: boolean;
+    /** Static segments matched. Higher wins when several routes match. */
+    score: number;
+}
+/** One URL shape a route produces for one locale. */
+export interface FimoRouteLocaleTarget {
+    locale: string;
+    /** Whether this locale renders behind a `/<locale>` prefix. */
+    prefixed: boolean;
+}
+export declare function normalizeRoutePath(path: string): string;
+/**
+ * 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 declare function hasLocaleSegment(path: string): boolean;
+/**
+ * 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 declare function resolveRouteContract(id: string, route: FimoRouteConfig): FimoRouteContract;
+export declare function resolveRouteContracts(routes: Record<string, FimoRouteConfig> | undefined): FimoRouteContract[];
+/**
+ * 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 declare function matchFimoRoute(pathnameOrUrl: string, config: Pick<FimoConfig, 'routes' | 'i18n'>): FimoRouteMatch | null;
+/**
+ * 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 declare function routeLocaleTargets(contract: FimoRouteContract, config: Pick<FimoConfig, 'i18n'>): FimoRouteLocaleTarget[];
+/**
+ * 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 declare function materializeRoutePath(contract: FimoRouteContract, target: FimoRouteLocaleTarget & {
+    params?: Record<string, string>;
+}): string;
+//# sourceMappingURL=contract.d.ts.map