@firecms/core 3.4.0-canary.f6a889a → 3.5.0

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

@@ -142,7 +142,9 @@ export function getReferenceFrom<M extends Record<string, any>>(entity: Entity<M
     if (!entity) {
         throw new Error("getReferenceFrom: entity is null or undefined");
     }
-    return new EntityReference(entity.id, entity.path, entity.databaseId);
+    // 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>>(

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::";
@@ -7,8 +25,16 @@ const LOCAL_STORAGE_PREFIX = "entity_cache::";
 // In-memory cache to store entities for quick access
 const entityCache: Map<string, object> = new Map();
 
-// Check `localStorage` availability once during initialization
-const isLocalStorageAvailable = typeof localStorage !== "undefined";
+// Check `localStorage` availability once during initialization. Reading it
+// throws where the browser blocks site data, which would fail this module's
+// import and take the whole CMS down with it.
+const isLocalStorageAvailable = (() => {
+    try {
+        return typeof localStorage !== "undefined";
+    } catch {
+        return false;
+    }
+})();
 
 // Define custom replacer for JSON.stringify
 function customReplacer(key: string): any {

package/src/util/index.ts

@@ -6,6 +6,7 @@ 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";
@@ -27,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/local_storage.ts

@@ -0,0 +1,52 @@
+/**
+ * `localStorage` access that never throws.
+ *
+ * Merely reading `window.localStorage` throws a SecurityError when the browser
+ * blocks site data (all cookies blocked, some sandboxed iframes), and `setItem`
+ * throws when the quota is full. Nothing the CMS keeps there is worth failing a
+ * render over, so a failed read counts as "nothing stored" and a failed write
+ * is dropped.
+ *
+ * @internal
+ */
+export function getLocalStorageItem(key: string): string | null {
+    try {
+        return typeof window !== "undefined" ? window.localStorage.getItem(key) : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The stored JSON value for `key`, or `fallback` when there is none, it is not
+ * valid JSON, or storage cannot be read.
+ *
+ * @internal
+ */
+export function getLocalStorageJSON<T>(key: string, fallback: T): T {
+    const item = getLocalStorageItem(key);
+    if (!item) return fallback;
+    try {
+        return JSON.parse(item);
+    } catch {
+        return fallback;
+    }
+}
+
+/** @internal */
+export function setLocalStorageItem(key: string, value: string): void {
+    try {
+        if (typeof window !== "undefined") window.localStorage.setItem(key, value);
+    } catch {
+        // Blocked or full: the value lives only as long as the page.
+    }
+}
+
+/** @internal */
+export function removeLocalStorageItem(key: string): void {
+    try {
+        if (typeof window !== "undefined") window.localStorage.removeItem(key);
+    } catch {
+        // Blocked: nothing was stored to remove.
+    }
+}

package/src/util/navigation_from_path.ts

@@ -13,6 +13,8 @@ export interface NavigationViewEntityInternal<M extends Record<string, any>> {
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     parentCollection: EntityCollection<M>;
 }
 
@@ -22,6 +24,8 @@ export interface NavigationViewCollectionInternal<M extends Record<string, any>>
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     collection: EntityCollection<M>;
 }
 
@@ -30,6 +34,8 @@ export interface NavigationViewEntityCustomInternal<M extends Record<string, any
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     entityId: string;
     view: EntityCustomView<M>;
 }
@@ -49,6 +55,7 @@ export function getNavigationEntriesFromPath(props: {
     currentFullPath?: string,
     currentFullIdPath?: string,
     currentFullUrlPath?: string,
+    currentPathSegments?: string[],
     contextEntityViews?: EntityCustomView<any>[]
 }): NavigationViewInternal [] {
 
@@ -57,7 +64,8 @@ export function getNavigationEntriesFromPath(props: {
         collections = [],
         currentFullPath,
         currentFullIdPath,
-        currentFullUrlPath
+        currentFullUrlPath,
+        currentPathSegments = []
     } = props;
 
     const subpaths = removeInitialAndTrailingSlashes(path).split("/");
@@ -83,12 +91,16 @@ export function getNavigationEntriesFromPath(props: {
             const fullIdPath = currentFullIdPath && currentFullIdPath.length > 0
                 ? (currentFullIdPath + "/" + collection.id)
                 : collection.id;
+            // A collection `path` may itself span several segments (e.g. "users/uid/experiences"),
+            // and those are unambiguous, so they are spread rather than kept whole.
+            const collectionSegments = [...currentPathSegments, ...collection.path.split("/")];
             result.push({
                 type: "collection",
                 id: collection.id,
                 path: collectionPath,
                 fullPath: collectionUrlPath,
                 fullIdPath,
+                pathSegments: collectionSegments,
                 collection
             });
             const restOfThePath = removeInitialAndTrailingSlashes(removeInitialAndTrailingSlashes(path).replace(subpathCombination, ""));
@@ -98,12 +110,16 @@ export function getNavigationEntriesFromPath(props: {
                 const entityId = decodeEntityId(encodedEntityId);
                 const fullPath = collectionPath + "/" + entityId;
                 const fullUrlPath = collectionUrlPath + "/" + encodedEntityId;
+                // The id is ONE segment however many slashes it contains — that is the
+                // whole point of this array.
+                const entitySegments = [...collectionSegments, entityId];
                 result.push({
                     type: "entity",
                     entityId,
                     path: collectionPath,
                     fullIdPath,
                     fullPath: fullUrlPath,
+                    pathSegments: collectionSegments,
                     parentCollection: collection
                 });
                 if (nextSegments.length > 1) {
@@ -123,6 +139,7 @@ export function getNavigationEntriesFromPath(props: {
                             entityId: entityId,
                             fullIdPath,
                             fullPath: fullUrlPath + "/" + customView.key,
+                            pathSegments: collectionSegments,
                             view: customView
                         });
                     } else if (collection.subcollections) {
@@ -130,8 +147,14 @@ export function getNavigationEntriesFromPath(props: {
                             path: newPath,
                             collections: collection.subcollections,
                             currentFullPath: fullPath,
-                            currentFullIdPath: fullIdPath,
+                            // The entity id is a hop in the id chain exactly as it is in the
+                            // other two. Without it a nested `fullIdPath` was
+                            // "products/locales" rather than "products/pid/locales", so any
+                            // URL built from it pointed at a collection that does not exist.
+                            // Escaped, because `fullIdPath` is URL-facing.
+                            currentFullIdPath: fullIdPath + "/" + encodedEntityId,
                             currentFullUrlPath: fullUrlPath,
+                            currentPathSegments: entitySegments,
                             contextEntityViews: props.contextEntityViews
                         }));
                     }