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

package/src/i18n/FireCMSi18nProvider.tsx

@@ -1,17 +1,76 @@
-import React, { PropsWithChildren, useEffect, useRef } from "react";
+import React, { PropsWithChildren, useContext, useEffect, useMemo, useRef } from "react";
 import i18next, { i18n } from "i18next";
-import { I18nextProvider, initReactI18next } from "react-i18next";
+import { I18nContext, I18nextProvider, initReactI18next } from "react-i18next";
 import { en } from "../locales/en";
 import { es } from "../locales/es";
-import { de } from "../locales/de";
-import { fr } from "../locales/fr";
-import { it } from "../locales/it";
-import { hi } from "../locales/hi";
-import { pt } from "../locales/pt";
 import { FireCMSTranslations } from "../types/translations";
 
 const FIRECMS_NS = "firecms_core";
 
+/**
+ * Translations that are not part of the bundle every app downloads.
+ *
+ * All eight locales used to be imported statically, which put ~305KB of strings
+ * — every language, for every user — into `@firecms/core` and therefore onto the
+ * startup path of every FireCMS app. Only the active language is ever read.
+ *
+ * `en` and `es` stay static: `en` is the fallback language and the base every
+ * unknown locale is seeded from, and both are re-exported from the package root,
+ * so a consumer may be importing them by name.
+ *
+ * The specifiers are written out rather than built from a template so bundlers
+ * can see them and emit one chunk per locale.
+ */
+const localeLoaders: Record<string, () => Promise<FireCMSTranslations>> = {
+    de: () => import("../locales/de").then((m) => m.de),
+    fr: () => import("../locales/fr").then((m) => m.fr),
+    it: () => import("../locales/it").then((m) => m.it),
+    hi: () => import("../locales/hi").then((m) => m.hi),
+    pt: () => import("../locales/pt").then((m) => m.pt),
+    pl: () => import("../locales/pl").then((m) => m.pl)
+};
+
+/**
+ * Locale bundles available synchronously: the two static ones plus anything a
+ * previous provider already fetched. `buildResources` reads this, so a rebuild
+ * triggered by a changing `translations` prop cannot overwrite a lazily loaded
+ * language with the English base it would otherwise fall back to.
+ */
+const loadedLocales: Record<string, FireCMSTranslations> = {
+    en,
+    es
+};
+
+const inFlightLocales: Record<string, Promise<void>> = {};
+
+/**
+ * Fetch a locale bundle into `loadedLocales`.
+ *
+ * Returns undefined when the bundle is already in memory or there is nothing to
+ * fetch, so callers can stay synchronous in the common case.
+ */
+function loadLocale(locale?: string): Promise<void> | undefined {
+    if (!locale) return undefined;
+    const language = locale.split("-")[0];
+    if (loadedLocales[language]) return undefined;
+    const loader = localeLoaders[language];
+    if (!loader) return undefined;
+    if (!inFlightLocales[language]) {
+        inFlightLocales[language] = loader()
+            .then((bundle) => {
+                loadedLocales[language] = bundle;
+            })
+            .catch(() => {
+                // A locale that fails to load falls back to English, which is
+                // what an unknown locale has always done.
+            })
+            .finally(() => {
+                delete inFlightLocales[language];
+            });
+    }
+    return inFlightLocales[language];
+}
+
 export const FIRECMS_LOCALE_STORAGE_KEY = "firecms_locale";
 
 /** DeepPartial helper — allows partial overrides at any nesting level */
@@ -49,21 +108,44 @@ export function FireCMSi18nProvider({
     translations,
     children
 }: PropsWithChildren<FireCMSi18nProviderProps>) {
+
+    // A FireCMS i18next instance already in context means this provider is nested —
+    // e.g. FireCMSCloudApp mounts one inside the one the host app already mounted.
+    // A second instance built only from the defaults would shadow the parent's and
+    // silently drop every translation the host registered, leaving the host's own
+    // strings to render as raw keys.
+    //
+    // So the nested instance is *seeded* from the parent's resources rather than
+    // sharing them. Sharing one mutable instance was the obvious alternative and is
+    // wrong: bundles added by one provider outlive it, so opening one project's app
+    // and then switching to another left the first project's translations answering
+    // for keys the second never defined. Copying keeps each provider's strings to
+    // itself, which is also how this behaved before nesting was handled at all.
+    const parentI18n = useContext(I18nContext)?.i18n;
+    const parentInstance = parentI18n?.hasResourceBundle?.("en", FIRECMS_NS)
+        ? parentI18n
+        : undefined;
+
     const i18nRef = useRef<i18n | null>(null);
     const [ready, setReady] = React.useState(false);
 
     if (!i18nRef.current) {
         const instance = i18next.createInstance();
 
-        // Build the initial resources: English baseline + any consumer overrides
-        const resources = buildResources(translations);
+        // English baseline + this provider's overrides, with anything the parent
+        // already resolved layered in underneath the overrides.
+        const resources = buildResourcesWithParent(translations, parentInstance);
 
-        let initialLocale = locale;
+        let initialLocale = parentInstance?.language ?? locale;
         if (typeof window !== "undefined") {
             const stored = localStorage.getItem(FIRECMS_LOCALE_STORAGE_KEY);
             if (stored) initialLocale = stored;
         }
 
+        // Kicked off before init so the request is in flight while i18next sets
+        // itself up, rather than after it.
+        const pendingInitialLocale = loadLocale(initialLocale);
+
         instance
             .use(initReactI18next)
             .init({
@@ -76,19 +158,54 @@ export function FireCMSi18nProvider({
                     // React already escapes — don't double-escape
                     escapeValue: false,
                 },
+                react: {
+                    // Locale bundles now arrive after init, and a bundle landing
+                    // in the store raises an `added` event rather than
+                    // `languageChanged`. react-i18next binds only the latter by
+                    // default, so without this a language switched from the
+                    // toggle would fetch its strings, put them in the store, and
+                    // leave the UI sitting on the English fallback.
+                    bindI18nStore: "added"
+                },
             }, () => {
-                setReady(true);
+                if (!pendingInitialLocale) {
+                    setReady(true);
+                    return;
+                }
+                // Holding the first render until the active language has arrived
+                // keeps a non-English user from seeing English strings repaint.
+                // Only locales outside the static pair wait, and only on the
+                // first mount.
+                pendingInitialLocale.then(() => {
+                    applyLoadedLocale(instance, initialLocale, translations, parentInstance);
+                    setReady(true);
+                });
             });
 
         instance.on("languageChanged", (lng) => {
             if (typeof window !== "undefined") {
                 localStorage.setItem(FIRECMS_LOCALE_STORAGE_KEY, lng);
             }
+            // Switching to a language whose bundle has not been fetched yet
+            // renders the English fallback until it lands.
+            loadLocale(lng)?.then(() => applyLoadedLocale(instance, lng, translations, parentInstance));
         });
 
         i18nRef.current = instance;
     }
 
+    // Follow the parent's language, so a switch made outside this provider is not
+    // stranded on the other side of the boundary.
+    useEffect(() => {
+        if (!parentInstance || !i18nRef.current) return;
+        const instance = i18nRef.current;
+        const follow = (lng: string) => {
+            if (instance.language !== lng) instance.changeLanguage(lng);
+        };
+        parentInstance.on("languageChanged", follow);
+        return () => { parentInstance.off("languageChanged", follow); };
+    }, [parentInstance]);
+
     // When `locale` prop changes, switch language on the existing instance
     // ONLY if the user hasn't explicitly set a preference
     useEffect(() => {
@@ -100,10 +217,16 @@ export function FireCMSi18nProvider({
         }
     }, [locale]);
 
-    // When consumer translations prop changes, update the resource bundles
+    // When consumer translations prop changes, update the resource bundles.
+    //
+    // Built through the same layering as the initial instance, parent included.
+    // Rebuilding from the bare English baseline here would overwrite whatever the
+    // host registered — a nested provider without translations of its own would
+    // reset the host's overrides to the built-in strings. That was already true;
+    // it was simply invisible until `bindI18nStore` made a store write repaint.
     useEffect(() => {
         if (!i18nRef.current) return;
-        const resources = buildResources(translations);
+        const resources = buildResourcesWithParent(translations, parentInstance);
         for (const [lang, bundle] of Object.entries(resources)) {
             i18nRef.current.addResourceBundle(
                 lang,
@@ -113,7 +236,7 @@ export function FireCMSi18nProvider({
                 true   // overwrite existing keys
             );
         }
-    }, [translations]);
+    }, [translations, parentInstance]);
 
     if (!ready || !i18nRef.current) return null;
 
@@ -124,6 +247,64 @@ export function FireCMSi18nProvider({
     );
 }
 
+/**
+ * Push a lazily loaded locale bundle into a live i18next instance.
+ *
+ * Consumer overrides are re-applied on top, because the instance may already be
+ * holding a bundle that `buildResources` seeded from English for this language,
+ * and the real translations have to win over that seed while the overrides win
+ * over both.
+ */
+function applyLoadedLocale(
+    instance: i18n,
+    locale: string,
+    translations?: { [locale: string]: DeepPartial<FireCMSTranslations> },
+    parentInstance?: i18n
+) {
+    const language = locale.split("-")[0];
+    if (!loadedLocales[language]) return;
+    const bundle = buildResourcesWithParent(translations, parentInstance)[language]?.[FIRECMS_NS];
+    if (!bundle) return;
+    instance.addResourceBundle(
+        language,
+        FIRECMS_NS,
+        bundle,
+        true,  // deep merge
+        true   // overwrite the English seed
+    );
+}
+
+/**
+ * The full resource map for this provider: the locale bundles currently in
+ * memory, then anything the parent provider already resolved, then this
+ * provider's own overrides on top.
+ *
+ * Shared by every path that writes into the instance — initial construction, a
+ * changed `translations` prop, and a locale arriving late — so all three layer
+ * in the same order and none of them can undo another.
+ */
+function buildResourcesWithParent(
+    translations?: { [locale: string]: DeepPartial<FireCMSTranslations> },
+    parentInstance?: i18n
+): Record<string, Record<string, object>> {
+    const resources = buildResources(translations);
+    if (!parentInstance) return resources;
+
+    const inherited: Record<string, any> = parentInstance.services?.resourceStore?.data ?? {};
+    for (const [lang, namespaces] of Object.entries(inherited)) {
+        const bundle = (namespaces as any)?.[FIRECMS_NS];
+        if (!bundle) continue;
+        resources[lang] = {
+            [FIRECMS_NS]: {
+                ...(resources[lang]?.[FIRECMS_NS] ?? {}),
+                ...bundle,
+                ...(translations?.[lang] ?? {})
+            }
+        };
+    }
+    return resources;
+}
+
 /**
  * Build an i18next resources object from the English baseline plus any
  * consumer-provided overrides.
@@ -131,15 +312,10 @@ export function FireCMSi18nProvider({
 function buildResources(
     translations?: { [locale: string]: DeepPartial<FireCMSTranslations> }
 ): Record<string, Record<string, object>> {
-    const resources: Record<string, Record<string, object>> = {
-        en: { [FIRECMS_NS]: { ...en } },
-        es: { [FIRECMS_NS]: { ...es } },
-        de: { [FIRECMS_NS]: { ...de } },
-        fr: { [FIRECMS_NS]: { ...fr } },
-        it: { [FIRECMS_NS]: { ...it } },
-        hi: { [FIRECMS_NS]: { ...hi } },
-        pt: { [FIRECMS_NS]: { ...pt } },
-    };
+    const resources: Record<string, Record<string, object>> = {};
+    for (const [lang, bundle] of Object.entries(loadedLocales)) {
+        resources[lang] = { [FIRECMS_NS]: { ...bundle } };
+    }
 
     if (!translations) return resources;
 

package/src/i18n/__tests__/FireCMSi18nProvider.test.tsx

@@ -0,0 +1,91 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { useTranslation } from "react-i18next";
+import { FireCMSi18nProvider } from "../FireCMSi18nProvider";
+
+/** Reads a key through the same channel application code uses. */
+function Str({ k }: { k: string }) {
+    const { t } = useTranslation("firecms_core");
+    return <span data-testid={k}>{t(k)}</span>;
+}
+
+const HOST_TRANSLATIONS = {
+    en: {
+        host_only_key: "Explore your Firestore data",
+        save: "Publish"      // an override of a real core key
+    }
+} as any;
+
+describe("FireCMSi18nProvider", () => {
+
+    beforeEach(() => {
+        window.localStorage.clear();
+    });
+
+    it("resolves its own translations", () => {
+        render(
+            <FireCMSi18nProvider translations={HOST_TRANSLATIONS}>
+                <Str k={"host_only_key"}/>
+            </FireCMSi18nProvider>
+        );
+        expect(screen.getByTestId("host_only_key").textContent).toBe("Explore your Firestore data");
+    });
+
+    it("keeps the host's translations when a nested provider is mounted without any", () => {
+        // This is the FireCMSCloudApp case: it mounts its own provider with
+        // `translations={appConfig?.translations}`, which is undefined for every
+        // project that has not deployed custom code. A nested provider that built its
+        // own isolated instance would shadow the host's and render the raw key.
+        render(
+            <FireCMSi18nProvider translations={HOST_TRANSLATIONS}>
+                <FireCMSi18nProvider translations={undefined}>
+                    <Str k={"host_only_key"}/>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+        expect(screen.getByTestId("host_only_key").textContent).toBe("Explore your Firestore data");
+        expect(screen.getByTestId("host_only_key").textContent).not.toBe("host_only_key");
+    });
+
+    it("does not let a nested provider clobber a host override", () => {
+        render(
+            <FireCMSi18nProvider translations={HOST_TRANSLATIONS}>
+                <FireCMSi18nProvider translations={undefined}>
+                    <Str k={"save"}/>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+        expect(screen.getByTestId("save").textContent).toBe("Publish");
+    });
+
+    it("lets a nested provider add its own translations on top of the host's", () => {
+        render(
+            <FireCMSi18nProvider translations={HOST_TRANSLATIONS}>
+                <FireCMSi18nProvider translations={{ en: { nested_key: "From the nested provider" } } as any}>
+                    <>
+                        <Str k={"host_only_key"}/>
+                        <Str k={"nested_key"}/>
+                    </>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+        expect(screen.getByTestId("host_only_key").textContent).toBe("Explore your Firestore data");
+        expect(screen.getByTestId("nested_key").textContent).toBe("From the nested provider");
+    });
+
+    it("still serves the built-in core strings through a nested provider", () => {
+        render(
+            <FireCMSi18nProvider>
+                <FireCMSi18nProvider translations={undefined}>
+                    <Str k={"discard"}/>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+        const el = screen.getByTestId("discard");
+        expect(el.textContent).not.toBe("discard");
+        expect(el.textContent?.length).toBeGreaterThan(0);
+    });
+});

package/src/i18n/__tests__/nested_provider_lifecycle.test.tsx

@@ -0,0 +1,67 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { useTranslation } from "react-i18next";
+import { FireCMSi18nProvider } from "../FireCMSi18nProvider";
+
+function Str({ k }: { k: string }) {
+    const { t } = useTranslation("firecms_core");
+    return <span data-testid={k}>{t(k)}</span>;
+}
+
+const host = { en: { host_key: "Host" } } as any;
+const projectA = { en: { only_in_a: "From project A" } } as any;
+const projectB = { en: { only_in_b: "From project B" } } as any;
+
+describe("nested provider lifecycle", () => {
+    beforeEach(() => window.localStorage.clear());
+
+    it("does not carry one project's translations into the next", () => {
+        // The real shape of a project switch: App.tsx's provider stays mounted while
+        // FireCMSCloudApp's inner one is torn down and rebuilt with another project's
+        // translations. Both share the outer i18next instance now, so anything the
+        // first project added could outlive it.
+        const { rerender } = render(
+            <FireCMSi18nProvider translations={host}>
+                <FireCMSi18nProvider key={"a"} translations={projectA}>
+                    <Str k={"only_in_a"}/>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+        expect(screen.getByTestId("only_in_a").textContent).toBe("From project A");
+
+        rerender(
+            <FireCMSi18nProvider translations={host}>
+                <FireCMSi18nProvider key={"b"} translations={projectB}>
+                    <>
+                        <Str k={"only_in_b"}/>
+                        <Str k={"only_in_a"}/>
+                    </>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+
+        expect(screen.getByTestId("only_in_b").textContent).toBe("From project B");
+        expect(screen.getByTestId("only_in_a").textContent).toBe("only_in_a");
+    });
+
+    it("keeps the host's own translations across the switch", () => {
+        const { rerender } = render(
+            <FireCMSi18nProvider translations={host}>
+                <FireCMSi18nProvider key={"a"} translations={projectA}>
+                    <Str k={"host_key"}/>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+        rerender(
+            <FireCMSi18nProvider translations={host}>
+                <FireCMSi18nProvider key={"b"} translations={projectB}>
+                    <Str k={"host_key"}/>
+                </FireCMSi18nProvider>
+            </FireCMSi18nProvider>
+        );
+        expect(screen.getByTestId("host_key").textContent).toBe("Host");
+    });
+});

package/src/internal/useBuildDataSource.ts

@@ -55,6 +55,7 @@ export function useBuildDataSource({
          */
         fetchCollection: useCallback(<M extends Record<string, any>>({
             path,
+            pathSegments,
             collection,
             filter,
             limit,
@@ -67,6 +68,7 @@ export function useBuildDataSource({
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
             return usedDelegate.fetchCollection<M>({
                 path,
+                pathSegments,
                 filter,
                 limit,
                 startAfter,
@@ -97,6 +99,7 @@ export function useBuildDataSource({
             ? useCallback(<M extends Record<string, any>>(
                 {
                     path,
+                    pathSegments,
                     collection: collectionProp,
                     filter,
                     limit,
@@ -109,7 +112,7 @@ export function useBuildDataSource({
                 }: ListenCollectionProps<M>
             ): () => void => {
 
-                const collection = collectionProp ?? navigationController.getCollection(path);
+                const collection = collectionProp ?? navigationController.getCollection(path, false, pathSegments);
                 const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
 
                 if (!usedDelegate.listenCollection)
@@ -117,6 +120,7 @@ export function useBuildDataSource({
 
                 return usedDelegate.listenCollection<M>({
                     path,
+                    pathSegments,
                     filter,
                     limit,
                     startAfter,
@@ -139,6 +143,7 @@ export function useBuildDataSource({
          */
         fetchEntity: useCallback(<M extends Record<string, any>>({
             path,
+            pathSegments,
             entityId,
             collection
         }: FetchEntityProps<M>
@@ -146,6 +151,7 @@ export function useBuildDataSource({
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
             return usedDelegate.fetchEntity({
                 path,
+                pathSegments,
                 entityId,
                 collection
             });
@@ -165,6 +171,7 @@ export function useBuildDataSource({
             ? useCallback(<M extends Record<string, any>>(
                 {
                     path,
+                    pathSegments,
                     entityId,
                     collection,
                     onUpdate,
@@ -177,6 +184,7 @@ export function useBuildDataSource({
 
                 return usedDelegate.listenEntity<M>({
                     path,
+                    pathSegments,
                     entityId,
                     onUpdate,
                     onError,
@@ -198,13 +206,14 @@ export function useBuildDataSource({
         saveEntity: useCallback(async <M extends Record<string, any>>(
             {
                 path,
+                pathSegments,
                 entityId,
                 values,
                 collection: collectionProp,
                 status
             }: SaveEntityProps<M>): Promise<Entity<M>> => {
 
-            const collection = collectionProp ?? navigationController.getCollection(path);
+            const collection = collectionProp ?? navigationController.getCollection(path, false, pathSegments);
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
 
             const resolvedCollection = collection
@@ -244,6 +253,7 @@ export function useBuildDataSource({
                         try {
                             const entities = await usedDelegate.fetchCollection({
                                 path,
+                                pathSegments,
                                 orderBy: orderProperty,
                                 order: "asc",
                                 limit: 1,
@@ -270,14 +280,21 @@ export function useBuildDataSource({
 
             return usedDelegate.saveEntity({
                 path,
+                pathSegments,
                 collection,
                 entityId,
                 values: finalValues,
                 status
             }).then((res) => {
+                // Keep everything the delegate resolved — `databaseId`, and `pathSegments` in
+                // particular — so a just-saved entity is as resolvable as a fetched one.
+                // Only the values are re-mapped back to the CMS model.
                 return {
-                    id: res.id,
-                    path: res.path,
+                    ...res,
+                    // A delegate that predates `pathSegments` returns none; the segments we
+                    // just saved with describe exactly this entity's collection, so they are
+                    // the authoritative answer rather than a guess.
+                    pathSegments: res.pathSegments ?? pathSegments,
                     values: usedDelegate.delegateToCMSModel(finalValues)
                 } as Entity<M>;
             });
@@ -292,12 +309,15 @@ export function useBuildDataSource({
         deleteEntity: useCallback(<M extends Record<string, any>>(
             {
                 entity,
+                pathSegments,
                 collection
             }: DeleteEntityProps<M>
         ): Promise<void> => {
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
             return usedDelegate.deleteEntity({
                 entity,
+                // Falls back to what the entity carries from the fetch that produced it.
+                pathSegments: pathSegments ?? entity.pathSegments,
                 collection
             });
         }, [delegate.deleteEntity]),
@@ -317,33 +337,32 @@ export function useBuildDataSource({
             name: string,
             value: any,
             entityId?: string,
-            collection?: EntityCollection
+            collection?: EntityCollection,
+            pathSegments?: string[]
         ): Promise<boolean> => {
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
-            return usedDelegate.checkUniqueField(path, name, value, entityId, collection);
+            return usedDelegate.checkUniqueField(path, name, value, entityId, collection, pathSegments);
         }, [delegate.checkUniqueField]),
 
-        generateEntityId: useCallback((path: string, collection: EntityCollection): string => {
+        generateEntityId: useCallback((path: string, collection: EntityCollection, pathSegments?: string[]): string => {
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
-            return usedDelegate.generateEntityId(path, collection);
+            return usedDelegate.generateEntityId(path, collection, pathSegments);
         }, [delegate.generateEntityId]),
 
+        // Typed with the declared props rather than an inline duplicate: the duplicate is
+        // free to drift from the interface, and a field it forgets is dropped in silence.
         countEntities: delegate.countEntities ? async ({
             path,
+            pathSegments,
             collection,
             filter,
             order,
             orderBy
-        }: {
-            path: string,
-            collection: EntityCollection<any>,
-            filter?: FilterValues<Extract<keyof any, string>>,
-            orderBy?: string,
-            order?: "desc" | "asc",
-        }): Promise<number> => {
+        }: FetchCollectionProps<any>): Promise<number> => {
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
             return usedDelegate.countEntities!({
                 path,
+                pathSegments,
                 filter,
                 orderBy,
                 order,
@@ -353,11 +372,13 @@ export function useBuildDataSource({
 
         isFilterCombinationValid: useCallback(({
             path,
+            pathSegments,
             databaseId,
             filterValues,
             sortBy
         }: {
             path: string,
+            pathSegments?: string[],
             databaseId?: string,
             filterValues: FilterValues<any>,
             sortBy?: [string, "asc" | "desc"]
@@ -367,6 +388,7 @@ export function useBuildDataSource({
             return delegate.isFilterCombinationValid(
                 {
                     path,
+                    pathSegments,
                     databaseId,
                     filterValues,
                     sortBy