@firecms/core 3.3.0-canary.d3242eb → 3.4.0-canary.00f9be5

package/src/util/__tests__/collections.test.ts

@@ -0,0 +1,32 @@
+import { getLocalChangesBackup } from "../collections";
+import { EntityCollection } from "../../types";
+
+function collectionWith(localChangesBackup?: "manual_apply" | "auto_apply" | false): EntityCollection {
+    return {
+        id: "products",
+        name: "Products",
+        path: "products",
+        properties: {},
+        localChangesBackup
+    } as EntityCollection;
+}
+
+describe("getLocalChangesBackup", () => {
+
+    it("should default to manual_apply when not set", () => {
+        expect(getLocalChangesBackup(collectionWith(undefined))).toEqual("manual_apply");
+    });
+
+    it("should return manual_apply when explicitly set", () => {
+        expect(getLocalChangesBackup(collectionWith("manual_apply"))).toEqual("manual_apply");
+    });
+
+    it("should return auto_apply when explicitly set", () => {
+        expect(getLocalChangesBackup(collectionWith("auto_apply"))).toEqual("auto_apply");
+    });
+
+    it("should return false when explicitly disabled, and not fall back to the default", () => {
+        expect(getLocalChangesBackup(collectionWith(false))).toEqual(false);
+    });
+
+});

package/src/util/__tests__/urls.test.ts

@@ -0,0 +1,131 @@
+import { getFileExtensionFromUrl, getPreviewTypeFromUrl, isAbsoluteHttpUrl } from "../urls";
+
+describe("url utilities", () => {
+
+    describe("isAbsoluteHttpUrl", () => {
+
+        it("should detect absolute http and https URLs", () => {
+            expect(isAbsoluteHttpUrl("https://abc.com/abc.png")).toBe(true);
+            expect(isAbsoluteHttpUrl("http://abc.com/abc.png")).toBe(true);
+            expect(isAbsoluteHttpUrl("HTTPS://ABC.COM/ABC.PNG")).toBe(true);
+        });
+
+        it("should detect Firebase Storage download URLs as absolute URLs", () => {
+            expect(isAbsoluteHttpUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.png?alt=media&token=abc")).toBe(true);
+            expect(isAbsoluteHttpUrl("https://storage.googleapis.com/demo.appspot.com/images/cat.png")).toBe(true);
+        });
+
+        it("should not consider storage paths absolute URLs", () => {
+            expect(isAbsoluteHttpUrl("images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("/images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("cat.png")).toBe(false);
+        });
+
+        it("should not consider other protocols absolute http URLs", () => {
+            expect(isAbsoluteHttpUrl("gs://demo.appspot.com/images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("data:image/png;base64,AAAA")).toBe(false);
+            expect(isAbsoluteHttpUrl("//abc.com/abc.png")).toBe(false);
+        });
+
+        it("should handle empty values", () => {
+            expect(isAbsoluteHttpUrl("")).toBe(false);
+            expect(isAbsoluteHttpUrl(undefined)).toBe(false);
+            expect(isAbsoluteHttpUrl(null)).toBe(false);
+        });
+
+        it("should not match http appearing later in the value", () => {
+            expect(isAbsoluteHttpUrl("images/https://abc.com/abc.png")).toBe(false);
+        });
+
+    });
+
+    describe("getFileExtensionFromUrl", () => {
+
+        it("should extract the extension of a plain URL", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png")).toBe("png");
+        });
+
+        it("should lowercase the extension", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/ABC.PNG")).toBe("png");
+        });
+
+        it("should ignore query strings and hash fragments", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png?width=200")).toBe("png");
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png#anchor")).toBe("png");
+            expect(getFileExtensionFromUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.jpeg?alt=media&token=abc")).toBe("jpeg");
+        });
+
+        it("should work with storage paths", () => {
+            expect(getFileExtensionFromUrl("images/cat.webp")).toBe("webp");
+        });
+
+        it("should use the last dot of the file name", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/archive.tar.gz")).toBe("gz");
+        });
+
+        it("should return undefined when there is no extension", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/")).toBeUndefined();
+            expect(getFileExtensionFromUrl("images/cat")).toBeUndefined();
+        });
+
+        it("should not take dots of the host or the path as extensions", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/images/cat")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png/download")).toBeUndefined();
+        });
+
+        it("should return undefined for dotfiles and trailing dots", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/.gitignore")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/abc.")).toBeUndefined();
+        });
+
+        it("should handle empty values", () => {
+            expect(getFileExtensionFromUrl("")).toBeUndefined();
+            expect(getFileExtensionFromUrl(undefined)).toBeUndefined();
+            expect(getFileExtensionFromUrl(null)).toBeUndefined();
+        });
+
+    });
+
+    describe("getPreviewTypeFromUrl", () => {
+
+        it("should infer image previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.png")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.jpg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.jpeg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.gif")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.webp")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.svg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.avif")).toBe("image");
+        });
+
+        it("should infer video previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mp4")).toBe("video");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.webm")).toBe("video");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mov")).toBe("video");
+        });
+
+        it("should infer audio previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mp3")).toBe("audio");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.wav")).toBe("audio");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.m4a")).toBe("audio");
+        });
+
+        it("should infer the type of Firebase Storage download URLs", () => {
+            expect(getPreviewTypeFromUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.png?alt=media&token=abc")).toBe("image");
+        });
+
+        it("should be case insensitive", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/ABC.PNG")).toBe("image");
+        });
+
+        it("should return undefined for unknown or missing extensions", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.pdf")).toBeUndefined();
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.zip")).toBeUndefined();
+            expect(getPreviewTypeFromUrl("https://abc.com/abc")).toBeUndefined();
+            expect(getPreviewTypeFromUrl(undefined)).toBeUndefined();
+        });
+
+    });
+
+});

package/src/util/collections.ts

@@ -117,7 +117,7 @@ export const applyPermissionsFunctionIfEmpty = (collections: EntityCollection[],
 }
 
 export function getLocalChangesBackup(collection: EntityCollection) {
-    if (!collection.localChangesBackup) {
+    if (collection.localChangesBackup === undefined) {
         return "manual_apply";
     }
 

package/src/util/date_fns_locales.ts

@@ -0,0 +1,168 @@
+import { useEffect, useReducer } from "react";
+import type { Locale as DateFnsLocale } from "date-fns";
+import { Locale } from "../types";
+
+/**
+ * On-demand loading of date-fns locales.
+ *
+ * `import * as locales from "date-fns/locale"` pulls in every locale date-fns
+ * ships — 625KB of parsed JavaScript, loaded on every single page view, to
+ * support a `locale` setting that is unset for almost every project. Worse, it
+ * sat on the critical path: `@firecms/core` imported it statically, so the
+ * browser could not render anything until it had come down.
+ *
+ * Each locale now has its own dynamic import, so exactly one small chunk is
+ * fetched, and only when a project actually configures a locale. Projects that
+ * do not configure one (the default) pay nothing at all.
+ *
+ * The map is written out rather than built from a template literal because Vite
+ * and webpack both need the specifier to be statically analysable to emit the
+ * chunks.
+ */
+const loaders: Partial<Record<Locale, () => Promise<DateFnsLocale>>> = {
+    af: () => import("date-fns/locale/af").then(m => m.af),
+    ar: () => import("date-fns/locale/ar").then(m => m.ar),
+    arDZ: () => import("date-fns/locale/ar-DZ").then(m => m.arDZ),
+    arMA: () => import("date-fns/locale/ar-MA").then(m => m.arMA),
+    arSA: () => import("date-fns/locale/ar-SA").then(m => m.arSA),
+    az: () => import("date-fns/locale/az").then(m => m.az),
+    be: () => import("date-fns/locale/be").then(m => m.be),
+    bg: () => import("date-fns/locale/bg").then(m => m.bg),
+    bn: () => import("date-fns/locale/bn").then(m => m.bn),
+    ca: () => import("date-fns/locale/ca").then(m => m.ca),
+    cs: () => import("date-fns/locale/cs").then(m => m.cs),
+    cy: () => import("date-fns/locale/cy").then(m => m.cy),
+    da: () => import("date-fns/locale/da").then(m => m.da),
+    de: () => import("date-fns/locale/de").then(m => m.de),
+    el: () => import("date-fns/locale/el").then(m => m.el),
+    enAU: () => import("date-fns/locale/en-AU").then(m => m.enAU),
+    enCA: () => import("date-fns/locale/en-CA").then(m => m.enCA),
+    enGB: () => import("date-fns/locale/en-GB").then(m => m.enGB),
+    enIN: () => import("date-fns/locale/en-IN").then(m => m.enIN),
+    enNZ: () => import("date-fns/locale/en-NZ").then(m => m.enNZ),
+    enUS: () => import("date-fns/locale/en-US").then(m => m.enUS),
+    eo: () => import("date-fns/locale/eo").then(m => m.eo),
+    es: () => import("date-fns/locale/es").then(m => m.es),
+    et: () => import("date-fns/locale/et").then(m => m.et),
+    eu: () => import("date-fns/locale/eu").then(m => m.eu),
+    faIR: () => import("date-fns/locale/fa-IR").then(m => m.faIR),
+    fi: () => import("date-fns/locale/fi").then(m => m.fi),
+    fr: () => import("date-fns/locale/fr").then(m => m.fr),
+    frCA: () => import("date-fns/locale/fr-CA").then(m => m.frCA),
+    frCH: () => import("date-fns/locale/fr-CH").then(m => m.frCH),
+    gd: () => import("date-fns/locale/gd").then(m => m.gd),
+    gl: () => import("date-fns/locale/gl").then(m => m.gl),
+    gu: () => import("date-fns/locale/gu").then(m => m.gu),
+    he: () => import("date-fns/locale/he").then(m => m.he),
+    hi: () => import("date-fns/locale/hi").then(m => m.hi),
+    hr: () => import("date-fns/locale/hr").then(m => m.hr),
+    hu: () => import("date-fns/locale/hu").then(m => m.hu),
+    hy: () => import("date-fns/locale/hy").then(m => m.hy),
+    id: () => import("date-fns/locale/id").then(m => m.id),
+    is: () => import("date-fns/locale/is").then(m => m.is),
+    it: () => import("date-fns/locale/it").then(m => m.it),
+    ja: () => import("date-fns/locale/ja").then(m => m.ja),
+    ka: () => import("date-fns/locale/ka").then(m => m.ka),
+    kk: () => import("date-fns/locale/kk").then(m => m.kk),
+    kn: () => import("date-fns/locale/kn").then(m => m.kn),
+    ko: () => import("date-fns/locale/ko").then(m => m.ko),
+    lb: () => import("date-fns/locale/lb").then(m => m.lb),
+    lt: () => import("date-fns/locale/lt").then(m => m.lt),
+    lv: () => import("date-fns/locale/lv").then(m => m.lv),
+    mk: () => import("date-fns/locale/mk").then(m => m.mk),
+    ms: () => import("date-fns/locale/ms").then(m => m.ms),
+    mt: () => import("date-fns/locale/mt").then(m => m.mt),
+    nb: () => import("date-fns/locale/nb").then(m => m.nb),
+    nl: () => import("date-fns/locale/nl").then(m => m.nl),
+    nlBE: () => import("date-fns/locale/nl-BE").then(m => m.nlBE),
+    nn: () => import("date-fns/locale/nn").then(m => m.nn),
+    pl: () => import("date-fns/locale/pl").then(m => m.pl),
+    pt: () => import("date-fns/locale/pt").then(m => m.pt),
+    ptBR: () => import("date-fns/locale/pt-BR").then(m => m.ptBR),
+    ro: () => import("date-fns/locale/ro").then(m => m.ro),
+    ru: () => import("date-fns/locale/ru").then(m => m.ru),
+    sk: () => import("date-fns/locale/sk").then(m => m.sk),
+    sl: () => import("date-fns/locale/sl").then(m => m.sl),
+    sr: () => import("date-fns/locale/sr").then(m => m.sr),
+    srLatn: () => import("date-fns/locale/sr-Latn").then(m => m.srLatn),
+    sv: () => import("date-fns/locale/sv").then(m => m.sv),
+    ta: () => import("date-fns/locale/ta").then(m => m.ta),
+    te: () => import("date-fns/locale/te").then(m => m.te),
+    th: () => import("date-fns/locale/th").then(m => m.th),
+    tr: () => import("date-fns/locale/tr").then(m => m.tr),
+    ug: () => import("date-fns/locale/ug").then(m => m.ug),
+    uk: () => import("date-fns/locale/uk").then(m => m.uk),
+    uz: () => import("date-fns/locale/uz").then(m => m.uz),
+    vi: () => import("date-fns/locale/vi").then(m => m.vi),
+    zhCN: () => import("date-fns/locale/zh-CN").then(m => m.zhCN),
+    zhTW: () => import("date-fns/locale/zh-TW").then(m => m.zhTW),
+};
+
+const cache = new Map<Locale, DateFnsLocale>();
+const inFlight = new Map<Locale, Promise<DateFnsLocale | undefined>>();
+
+/**
+ * Load a date-fns locale, resolving from cache when it is already in memory.
+ * Concurrent callers for the same locale share one request.
+ */
+export function loadDateFnsLocale(locale: Locale): Promise<DateFnsLocale | undefined> {
+    const cached = cache.get(locale);
+    if (cached) {
+        return Promise.resolve(cached);
+    }
+    const pending = inFlight.get(locale);
+    if (pending) {
+        return pending;
+    }
+    const loader = loaders[locale];
+    if (!loader) {
+        // An unknown key behaves as it did when the whole barrel was imported:
+        // the lookup missed and date-fns fell back to its built-in English.
+        return Promise.resolve(undefined);
+    }
+    const promise = loader()
+        .then((loaded) => {
+            cache.set(locale, loaded);
+            return loaded;
+        })
+        .catch(() => undefined)
+        .finally(() => {
+            inFlight.delete(locale);
+        });
+    inFlight.set(locale, promise);
+    return promise;
+}
+
+/** The locale if it is already loaded, otherwise undefined. Never suspends. */
+export function getLoadedDateFnsLocale(locale?: Locale): DateFnsLocale | undefined {
+    return locale ? cache.get(locale) : undefined;
+}
+
+/**
+ * The date-fns locale for `locale`, loading it in the background on first use.
+ *
+ * Returns undefined until the chunk arrives, which formats the first paint with
+ * date-fns' built-in English and then re-renders. That is a change only for
+ * projects that set a locale, and only for the few hundred milliseconds before
+ * the chunk lands — in exchange for every project no longer waiting on 625KB.
+ */
+export function useDateFnsLocale(locale?: Locale): DateFnsLocale | undefined {
+    const [, forceUpdate] = useReducer((count: number) => count + 1, 0);
+
+    useEffect(() => {
+        if (!locale || cache.has(locale)) {
+            return;
+        }
+        let active = true;
+        loadDateFnsLocale(locale).then((loaded) => {
+            if (active && loaded) {
+                forceUpdate();
+            }
+        });
+        return () => {
+            active = false;
+        };
+    }, [locale]);
+
+    return locale ? cache.get(locale) : undefined;
+}

package/src/util/entities.ts

@@ -75,6 +75,8 @@ export function getDefaultValueForDataType(dataType: DataType) {
         return [];
     } else if (dataType === "map") {
         return {};
+    } else if (dataType === "geopoint") {
+        return null;
     } else {
         return null;
     }
@@ -137,7 +139,12 @@ export function sanitizeData<M extends Record<string, any>>
 }
 
 export function getReferenceFrom<M extends Record<string, any>>(entity: Entity<M>): EntityReference {
-    return new EntityReference(entity.id, entity.path, entity.databaseId);
+    if (!entity) {
+        throw new Error("getReferenceFrom: entity is null or undefined");
+    }
+    // Carry the segments the entity was loaded with, so a reference to an entity under a
+    // slash-bearing parent stays resolvable. Undefined when the entity does not have them.
+    return new EntityReference(entity.id, entity.path, entity.databaseId, entity.pathSegments);
 }
 
 export function traverseValuesProperties<M extends Record<string, any>>(
@@ -196,3 +203,11 @@ export function traverseValueProperty(inputValue: any,
 
     return value;
 }
+
+export function isDataTypeFilterable(dataType: DataType, isPartOfArray = false) {
+    if (isPartOfArray) {
+        return ["string", "number", "date", "reference"].includes(dataType);
+    }
+    
+    return ["string", "number", "boolean", "date", "reference", "array"].includes(dataType);
+}

package/src/util/entity_cache.ts

@@ -1,5 +1,23 @@
 import { EntityReference, GeoPoint, Vector } from "../types";
 import { isObject, isPlainObject } from "./objects";
+import { encodeEntityId } from "./navigation_utils";
+
+/**
+ * Key identifying one entity in a cache.
+ *
+ * The id is escaped so that a `(path, entityId)` pair maps to exactly one key. Without it
+ * `("a", "b/c")` and `("a/b", "c")` both flatten to `"a/b/c"`, and one entity's cached
+ * values are served for the other.
+ *
+ * `encodeEntityId` is the identity for any id without "/", "?", "#" or "%", so this changes
+ * no key in an app whose ids cannot contain them.
+ */
+export function entityCacheKey(path: string | undefined, entityId: string | undefined): string {
+    // Either part may be undefined at a call site that used to build the key by string
+    // concatenation; both are stringified exactly as `path + "/" + entityId` did, so such a
+    // caller keeps the key it had.
+    return `${path}/${entityId === undefined ? entityId : encodeEntityId(entityId)}`;
+}
 
 // Define a unique prefix for entity keys in localStorage to avoid key collisions
 const LOCAL_STORAGE_PREFIX = "entity_cache::";

package/src/util/geopoint.ts

@@ -0,0 +1,81 @@
+import { GeoPoint } from "../types";
+
+export type GeoPointLike = GeoPoint | {
+    latitude?: number;
+    longitude?: number;
+    lat?: number;
+    lng?: number;
+    _lat?: number;
+    _long?: number;
+} | null | undefined;
+
+export interface GeoPointCoordinates {
+    latitude: number;
+    longitude: number;
+}
+
+function toNumber(value: any): number | undefined {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function getGeoPointCoordinates(value: GeoPointLike): GeoPointCoordinates | undefined {
+    if (!value) return undefined;
+    if (value instanceof GeoPoint) {
+        return { latitude: value.latitude, longitude: value.longitude };
+    }
+    if (typeof value !== "object") return undefined;
+
+    const latitude = toNumber((value as any).latitude ?? (value as any).lat ?? (value as any)._lat);
+    const longitude = toNumber((value as any).longitude ?? (value as any).lng ?? (value as any)._long);
+
+    if (latitude === undefined || longitude === undefined) return undefined;
+
+    return { latitude, longitude };
+}
+
+export function normalizeGeoPoint(value: GeoPointLike): GeoPoint | undefined {
+    const coordinates = getGeoPointCoordinates(value);
+    if (!coordinates) return undefined;
+    if (value instanceof GeoPoint) return value;
+    return new GeoPoint(coordinates.latitude, coordinates.longitude);
+}
+
+export function formatGeoPoint(value: GeoPointLike, options?: { maximumFractionDigits?: number }): string {
+    const coordinates = getGeoPointCoordinates(value);
+    if (!coordinates) return "";
+
+    const maximumFractionDigits = options?.maximumFractionDigits ?? 6;
+    // Coordinates are always formatted with a dot as decimal separator, independently of the
+    // user locale. Locale-aware formatting would use a comma in locales such as de or fr,
+    // making the "lat, lng" output ambiguous and impossible to parse back.
+    const formatter = new Intl.NumberFormat("en-US", {
+        maximumFractionDigits,
+        minimumFractionDigits: Math.min(2, maximumFractionDigits),
+        useGrouping: false
+    });
+
+    return `${formatter.format(coordinates.latitude)}, ${formatter.format(coordinates.longitude)}`;
+}
+
+export function parseGeoPoint(input: string): { point: GeoPoint | null; error?: string } {
+    const trimmed = input.trim();
+    if (!trimmed) return { point: null };
+
+    const parts = trimmed.split(",").map((part) => part.trim()).filter((part) => part !== "");
+    if (parts.length !== 2) return { point: null, error: "Use \"lat, lng\" format" };
+
+    const latitude = parseFloat(parts[0]);
+    const longitude = parseFloat(parts[1]);
+
+    if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+        return { point: null, error: "Latitude and longitude must be numbers" };
+    }
+    if (latitude < -90 || latitude > 90) {
+        return { point: null, error: "Latitude must be between -90 and 90" };
+    }
+    if (longitude < -180 || longitude > 180) {
+        return { point: null, error: "Longitude must be between -180 and 180" };
+    }
+
+    return { point: new GeoPoint(latitude, longitude) };
+}

package/src/util/index.ts

@@ -6,12 +6,14 @@ export * from "./enums";
 export * from "./objects";
 export * from "./paths";
 export * from "./regexp";
+export * from "./urls";
 export * from "./navigation_utils";
 export * from "./entity_actions";
 export * from "./useDebouncedCallback";
 export * from "./property_utils";
 export * from "./resolutions";
 export * from "./permissions";
+export * from "./geopoint";
 export * from "./icon_list";
 export * from "./icon_synonyms";
 export * from "./icons";
@@ -26,3 +28,4 @@ export * from "./storage";
 export * from "./callbacks";
 export * from "./conditions";
 export * from "./lazy_eager";
+export * from "./date_fns_locales";

package/src/util/lazy_eager.tsx

@@ -1,9 +1,35 @@
 import React from "react";
 
 /**
- * Returns a React.lazy component that is also preloaded immediately using
- * requestIdleCallback or setTimeout.
- * This ensures that chunks are split, but fetched in the background before they are actually needed.
+ * Prefetch after the page has loaded, never during it.
+ *
+ * An idle callback scheduled at module evaluation time fires in the gaps between
+ * the tasks of the initial load — which is exactly when the critical chunks are
+ * still in flight. With a dozen route components each queueing one, the
+ * background prefetch was competing with the render path for connections and
+ * bandwidth. Waiting for the load event costs the prefetch nothing that matters:
+ * it exists to be ready before a navigation, not before first paint.
+ */
+function schedulePrefetch(load: () => void) {
+    const whenIdle = () => {
+        if ("requestIdleCallback" in window) {
+            (window as any).requestIdleCallback(load);
+        } else {
+            setTimeout(load, 500);
+        }
+    };
+
+    if (document.readyState === "complete") {
+        whenIdle();
+    } else {
+        window.addEventListener("load", whenIdle, { once: true });
+    }
+}
+
+/**
+ * Returns a React.lazy component that is also preloaded in the background, once
+ * the page has finished loading.
+ * This ensures that chunks are split, but fetched before they are actually needed.
  */
 export function lazyEager<T extends React.ComponentType<any>>(
     factory: () => Promise<any>,
@@ -22,11 +48,7 @@ export function lazyEager<T extends React.ComponentType<any>>(
     };
 
     if (typeof window !== "undefined") {
-        if ("requestIdleCallback" in window) {
-            (window as any).requestIdleCallback(load);
-        } else {
-            setTimeout(load, 500);
-        }
+        schedulePrefetch(load);
     }
 
     return React.lazy(load);

package/src/util/navigation_blocking.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure predicate deciding whether an in-progress navigation away from an open
+ * entity form should be blocked (to warn about unsaved changes).
+ *
+ * Extracted from FireCMSRoute so the branching can be unit-tested without
+ * mounting the router. This is an internal helper — it is intentionally not
+ * re-exported from the package index.
+ */
+export interface NavigationBlockLocation {
+    pathname: string;
+    hash: string;
+}
+
+const SIDE_PANEL_HASHES = ["#side", "#new_side"];
+
+export function shouldBlockEntityNavigation(params: {
+    currentLocation: NavigationBlockLocation;
+    nextLocation: NavigationBlockLocation;
+    /** Path of the currently open entity (basePath + "/" + entityId). */
+    entityPath: string;
+    /** Collection path the entity form lives under. */
+    basePath: string;
+    /** Whether the form currently has unsaved modifications. */
+    blocked: boolean;
+}): boolean {
+    const { currentLocation, nextLocation, entityPath, basePath, blocked } = params;
+
+    // Navigating deeper within the same entity — never block.
+    if (nextLocation.pathname.startsWith(entityPath))
+        return false;
+
+    // Side panel overlay navigations preserve the underlying form via
+    // base_location in router state — no data is lost in either direction.
+
+    // Opening a side panel (e.g. clicking a relation/reference arrow).
+    if (SIDE_PANEL_HASHES.includes(nextLocation.hash))
+        return false;
+
+    // Closing a side panel (navigate(-1) back to the form's own path).
+    if (SIDE_PANEL_HASHES.includes(currentLocation.hash) &&
+        nextLocation.pathname === basePath)
+        return false;
+
+    return blocked;
+}