@firecms/core 3.4.0-canary.e2466ba → 3.4.0

package/dist/util/entity_cache.d.ts

@@ -1,3 +1,14 @@
+/**
+ * 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 declare function entityCacheKey(path: string | undefined, entityId: string | undefined): string;
 /**
  * Saves data to the in-memory cache and persists it individually in `localStorage`.
  * @param path - The unique path/key for the data.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firecms/core",
   "type": "module",
-  "version": "3.4.0-canary.e2466ba",
+  "version": "3.4.0",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/firecmsco"
@@ -53,8 +53,8 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
-    "@firecms/formex": "3.4.0-canary.e2466ba",
-    "@firecms/ui": "3.4.0-canary.e2466ba",
+    "@firecms/formex": "3.4.0",
+    "@firecms/ui": "3.4.0",
     "@floating-ui/dom": "^1.7.4",
     "@radix-ui/react-portal": "^1.1.10",
     "@radix-ui/react-slot": "^1.2.4",

package/src/components/EntityCollectionTable/EntityCollectionRowActions.tsx

@@ -3,7 +3,7 @@ import React, { MouseEvent, useCallback } from "react";
 import { CollectionSize, Entity, EntityAction, EntityCollection, SelectionController } from "../../types";
 import { Badge, Checkbox, cls, IconButton, Menu, MenuItem, MoreVertIcon, Skeleton, Tooltip } from "@firecms/ui";
 import { useFireCMSContext, useLargeLayout } from "../../hooks";
-import { getEntityFromCache } from "../../util/entity_cache";
+import { entityCacheKey, getEntityFromCache } from "../../util/entity_cache";
 import { getLocalChangesBackup } from "../../util";
 import { getChanges } from "../../form/EntityForm";
 
@@ -82,7 +82,7 @@ export const EntityCollectionRowActions = function EntityCollectionRowActions({
     const collapsedActions = actions.filter(a => a.collapsed || a.collapsed === undefined);
     const uncollapsedActions = actions.filter(a => a.collapsed === false);
     const enableLocalChangesBackup = collection ? getLocalChangesBackup(collection) : false;
-    const cachedData = enableLocalChangesBackup ? getEntityFromCache(fullPath + "/" + entity.id) : undefined;
+    const cachedData = enableLocalChangesBackup ? getEntityFromCache(entityCacheKey(fullPath, entity.id)) : undefined;
     const hasDraft = (() => {
         if (!cachedData || typeof cachedData !== "object" || Object.keys(cachedData).length === 0) return false;
         const realChanges = getChanges(cachedData as any, (entity?.values ?? {}) as any);

package/src/components/EntityCollectionView/EntityCollectionView.tsx

@@ -90,6 +90,7 @@ import { useSelectionController } from "./useSelectionController";
 import { EntityCollectionViewStartActions } from "./EntityCollectionViewStartActions";
 import { addRecentId, getRecentIds } from "./utils";
 import { useScrollRestoration } from "../common/useScrollRestoration";
+import { entityCacheKey } from "../../util/entity_cache";
 
 const DEFAULT_ENTITY_OPEN_MODE: "side_panel" | "full_screen" = "side_panel";
 
@@ -693,7 +694,7 @@ export const EntityCollectionView = React.memo(
                                 {collectionsWithPath.map((reference) => {
                                     return (
                                         <ReferencePreview
-                                            key={reference.path + "/" + reference.id}
+                                            key={entityCacheKey(reference.path, reference.id)}
                                             reference={reference}
                                             size={"small"} />
                                     );

package/src/components/ErrorBoundary.tsx

@@ -4,17 +4,16 @@ import { useTranslation } from "../hooks/useTranslation";
 import { ErrorIcon, Typography } from "@firecms/ui";
 
 export class ErrorBoundary extends React.Component<PropsWithChildren<Record<string, unknown>>, {
-    hasError: boolean,
-    error?: Error
+    error: Error | null
 }> {
     constructor(props: any) {
         super(props);
-        this.state = { hasError: false };
+        this.state = { error: null };
     }
 
     // eslint-disable-next-line n/handle-callback-err
     static getDerivedStateFromError(error: Error) {
-        return { hasError: true, error };
+        return { error };
     }
 
     componentDidCatch(error: Error, errorInfo: ErrorInfo) {
@@ -23,9 +22,8 @@ export class ErrorBoundary extends React.Component<PropsWithChildren<Record<stri
     }
 
     render() {
-        if (this.state.hasError) {
-            // You can render any custom fallback UI
-            return <FallbackView message={this.state.error?.message}/>;
+        if (this.state.error) {
+            return <FallbackView message={this.state.error.message}/>;
         }
 
         return this.props.children;
@@ -35,18 +33,14 @@ export class ErrorBoundary extends React.Component<PropsWithChildren<Record<stri
 function FallbackView({ message }: { message?: string }) {
     const { t } = useTranslation();
     return (
-        <div className="h-full w-full bg-slate-100 dark:bg-surface-900 flex items-center justify-center p-4">
-            <div
-                className="flex flex-col items-center justify-center m-4 bg-white dark:bg-surface-800 p-8 rounded-lg shadow-sm border border-gray-200 dark:border-surface-700">
-                <div className="flex items-center mb-4 text-red-500 dark:text-red-400">
-                    <ErrorIcon/>
-                    <div className="ml-4">{t("error")}</div>
-                </div>
-                <div className="flex justify-center text-gray-500 dark:text-gray-400">
-                    {/* Error message is purposely removed since it's hard to access state here, but typical ErrorBoundary fallback doesn't always show the raw message */}
-                    {t("see_console_details")}
-                </div>
+        <div className="flex flex-col m-2">
+            <div className="flex items-center m-2">
+                <ErrorIcon color={"error"} size={"small"}/>
+                <div className="ml-4">{t("error")}</div>
             </div>
+            <Typography variant={"caption"}>
+                {message ?? t("see_console_details")}
+            </Typography>
         </div>
     );
 }

package/src/components/common/default_entity_actions.tsx

@@ -84,6 +84,7 @@ export const copyEntityAction: EntityAction = {
                 context,
                 fullPath,
                 pathSegments,
+                fullIdPath,
                 highlightEntity,
                 unhighlightEntity,
                 openEntityMode
@@ -104,14 +105,17 @@ export const copyEntityAction: EntityAction = {
         const resolvedPathSegments = collection?.collectionGroup
             ? undefined
             : (pathSegments ?? entity.pathSegments);
-        const fullIdPath = collection?.collectionGroup ? collection.id : (fullPath ?? collection?.id ?? entity.path);
+        // `fullIdPath` is the ESCAPED chain and is what becomes the URL; `fullPath` is the raw
+        // datasource path, whose parent ids may contain "/". Using the latter here wrote a URL
+        // that read back as a different entity. Mirrors editEntityAction.
+        const newFullIdPath = collection?.collectionGroup ? collection.id : (fullIdPath ?? collection?.id);
         navigateToEntity({
             openEntityMode,
             collection,
             entityId: entity.id,
             path,
             pathSegments: resolvedPathSegments,
-            fullIdPath,
+            fullIdPath: newFullIdPath,
             copy: true,
             sideEntityController: context.sideEntityController,
             onClose: () => unhighlightEntity?.(entity),

package/src/components/common/useDataSourceTableController.tsx

@@ -194,11 +194,23 @@ export function useDataSourceTableController<M extends Record<string, any> = any
 
     useUpdateUrl(filterValues, sortBy, searchString, updateUrl);
 
-    const collectionScroll = scrollRestoration?.getCollectionScroll(fullPath, filterValues);
-    const initialItemCount = collectionScroll?.data.length ?? pageSize;
+    // Keyed by `resolvedPath`, not `fullPath`, so the read agrees with the two writes below
+    // and in `onScroll`. What the cache holds is a slice of a dataset plus the offset into
+    // it, and the dataset is identified by what the datasource was actually queried with:
+    // `resolvedPath` + filters. Reading with the unresolved `fullPath` meant that for every
+    // collection reached through an id alias, or a subcollection whose parent ids need
+    // resolving, the entry was written under one key and looked up under another, so scroll
+    // restoration silently did nothing there.
+    const collectionScroll = scrollRestoration?.getCollectionScroll(resolvedPath, filterValues);
+    const initialItemCount = collectionScroll?.data.length || pageSize;
 
     useEffect(() => {
-        if (scrollRestoration) {
+        // Only re-seed an entry we actually have something to restore for. Writing an empty
+        // `data` array here poisoned the cache: this is a module level Map that outlives the
+        // mount, so the next mount of the same collection read `data.length === 0` back as the
+        // initial item count and called the datasource with `limit: 0`. Custom datasources
+        // treat that as falsy and drop the limit altogether, loading the whole collection.
+        if (scrollRestoration && rawData.length > 0) {
             scrollRestoration.updateCollectionScroll({
                 fullPath: resolvedPath,
                 scrollOffset: collectionScroll?.scrollOffset ?? 0,

package/src/core/EntityEditView.tsx

@@ -29,7 +29,7 @@ import {
     useLargeLayout
 } from "../hooks";
 import { CircularProgress, cls, CodeIcon, defaultBorderMixin, Tab, Tabs, Typography, Menu, MenuItem, ExpandMoreIcon } from "@firecms/ui";
-import { getEntityFromMemoryCache } from "../util/entity_cache";
+import { entityCacheKey, getEntityFromMemoryCache } from "../util/entity_cache";
 import { EntityForm, EntityFormProps } from "../form";
 import { EntityEditViewFormActions } from "./EntityEditViewFormActions";
 import { EntityJsonPreview } from "../components/EntityJsonPreview";
@@ -118,7 +118,7 @@ export function EntityEditView<M extends Record<string, any>, USER extends User>
     });
 
     const initialDirtyValues = entityId
-        ? getEntityFromMemoryCache(props.path + "/" + entityId)
+        ? getEntityFromMemoryCache(entityCacheKey(props.path, entityId))
         : getEntityFromMemoryCache(props.path + "#new");
 
     const authController = useAuthController();

package/src/core/EntitySidePanel.tsx

@@ -8,7 +8,7 @@ import { EntityEditView, OnUpdateParams } from "./EntityEditView";
 import { useSideDialogContext } from "./SideDialogs";
 import { CloseIcon, IconButton, OpenInFullIcon } from "@firecms/ui";
 import { useLocation, useNavigate } from "react-router-dom";
-import { saveEntityToMemoryCache } from "../util/entity_cache";
+import { entityCacheKey, saveEntityToMemoryCache } from "../util/entity_cache";
 
 /**
  * This is the component in charge of rendering the side dialog used
@@ -138,7 +138,7 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
                                 className="self-center"
                                 size={"smallest"}
                                 onClick={() => {
-                                    const key = (status === "new" || status === "copy") ? path + "#new" : path + "/" + entityId;
+                                    const key = (status === "new" || status === "copy") ? path + "#new" : entityCacheKey(path, entityId);
                                     saveEntityToMemoryCache(key, values);
                                     if (entityId)
                                         navigate(location.pathname + location.search);

package/src/form/EntityForm.tsx

@@ -48,6 +48,7 @@ import { useAnalyticsController } from "../hooks/useAnalyticsController";
 import { FormEntry, FormLayout, LabelWithIconAndTooltip, PropertyFieldBinding } from "../form";
 import { ValidationError } from "yup";
 import {
+    entityCacheKey,
     flattenKeys,
     getEntityFromCache,
     removeEntityFromCache,
@@ -317,7 +318,7 @@ export function EntityForm<M extends Record<string, any>>({
     const baseInitialValues = useMemo(() => getInitialEntityValues(authController, collection, path, status, entity, customizationController.propertyConfigs), [authController, collection, path, status, entity, customizationController.propertyConfigs]);
 
     const localChangesDataRaw = useMemo(() => entityId
-        ? getEntityFromCache(path + "/" + entityId)
+        ? getEntityFromCache(entityCacheKey(path, entityId))
         : getEntityFromCache(path + "#new"), [entityId, path]);
 
     const [localChangesCleared, setLocalChangesCleared] = useState<boolean>(false);
@@ -396,7 +397,7 @@ export function EntityForm<M extends Record<string, any>>({
             onValuesModified?.(false, initialValues as M);
         },
         onValuesChangeDeferred: (values: M, controller: FormexController<M>) => {
-            const key = (status === "new" || status === "copy") ? path + "#new" : path + "/" + entityId;
+            const key = (status === "new" || status === "copy") ? path + "#new" : entityCacheKey(path, entityId);
             if (controller.dirty && localChangesBackup !== false) {
                 const touchedValues = removeEmptyContainers(extractTouchedValues(values, controller.touched));
                 if (touchedValues && Object.keys(touchedValues).length > 0) {
@@ -477,8 +478,8 @@ export function EntityForm<M extends Record<string, any>>({
             removeEntityFromMemoryCache(path + "#new");
             removeEntityFromCache(path + "#new");
         } else {
-            removeEntityFromMemoryCache(path + "/" + entityId);
-            removeEntityFromCache(path + "/" + entityId);
+            removeEntityFromMemoryCache(entityCacheKey(path, entityId));
+            removeEntityFromCache(entityCacheKey(path, entityId));
         }
     }
 
@@ -944,7 +945,7 @@ export function EntityForm<M extends Record<string, any>>({
 
                             {manualApplyLocalChanges && hasLocalChanges &&
                                 <LocalChangesMenu
-                                    cacheKey={status === "new" || status === "copy" ? path + "#new" : path + "/" + entityId}
+                                    cacheKey={status === "new" || status === "copy" ? path + "#new" : entityCacheKey(path, entityId)}
                                     properties={resolvedCollection.properties}
                                     cachedData={localChangesDataRaw as Partial<M>}
                                     formex={formex}

package/src/hooks/data/useEntityFetch.tsx

@@ -3,6 +3,7 @@ import { Entity, EntityCollection, FireCMSContext, User } from "../../types";
 import { useDataSource } from "./useDataSource";
 import { useNavigationController } from "../useNavigationController";
 import { useFireCMSContext } from "../useFireCMSContext";
+import { entityCacheKey } from "../../util/entity_cache";
 
 /**
  * @group Hooks and utilities
@@ -101,7 +102,7 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
                     console.error(e);
                 }
             }
-            CACHE[`${path}/${entityId}`] = updatedEntity;
+            CACHE[entityCacheKey(path, entityId)] = updatedEntity;
             setEntity(updatedEntity);
             setDataLoading(false);
             setDataLoadingError(undefined);
@@ -114,8 +115,8 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
             setDataLoadingError(error);
         };
 
-        if (entityId && useCache && CACHE[`${path}/${entityId}`]) {
-            setEntity(CACHE[`${path}/${entityId}`]);
+        if (entityId && useCache && CACHE[entityCacheKey(path, entityId)]) {
+            setEntity(CACHE[entityCacheKey(path, entityId)]);
             setDataLoading(false);
             setDataLoadingError(undefined);
             // eslint-disable-next-line @typescript-eslint/no-empty-function

package/src/i18n/FireCMSi18nProvider.tsx

@@ -1,6 +1,6 @@
-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";
@@ -50,16 +50,48 @@ 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
+        // English baseline + this provider's overrides, with anything the parent
+        // already resolved layered in underneath the overrides.
         const resources = buildResources(translations);
+        if (parentInstance) {
+            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]: {
+                        ...bundle,
+                        ...(translations?.[lang] ?? {})
+                    }
+                };
+            }
+        }
 
-        let initialLocale = locale;
+        let initialLocale = parentInstance?.language ?? locale;
         if (typeof window !== "undefined") {
             const stored = localStorage.getItem(FIRECMS_LOCALE_STORAGE_KEY);
             if (stored) initialLocale = stored;
@@ -90,6 +122,18 @@ export function FireCMSi18nProvider({
         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(() => {

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/useBuildSideEntityController.tsx

@@ -281,11 +281,17 @@ const propsToSidePanel = (props: EntitySidePanelProps,
     locationSearch: string
 ): SideDialogPanelProps => {
 
-    const collectionPath = removeInitialAndTrailingSlashes(props.path);
+    // The URL is the ESCAPED representation of the chain — it is what `buildSidePanelsFromUrl`
+    // and `FireCMSRoute` parse back on reload, on a deep link, and on every pathname change.
+    // `props.path` is the RAW datasource path, so a parent entity id containing "/" reads back
+    // there as extra collection/entity hops and resolves to a different entity entirely.
+    // `fullIdPath` carries the same chain with its ids already escaped, which is what it is
+    // threaded alongside `path` for.
+    const urlChain = removeInitialAndTrailingSlashes(props.fullIdPath ?? props.path);
 
     const urlPath = props.entityId
-        ? buildUrlCollectionPath(`${collectionPath}/${encodeEntityId(props.entityId)}${props.selectedTab ? "/" + props.selectedTab : ""}${locationSearch}#${SIDE_URL_HASH}`)
-        : buildUrlCollectionPath(`${collectionPath}${locationSearch}#${NEW_URL_HASH}`);
+        ? buildUrlCollectionPath(`${urlChain}/${encodeEntityId(props.entityId)}${props.selectedTab ? "/" + props.selectedTab : ""}${locationSearch}#${SIDE_URL_HASH}`)
+        : buildUrlCollectionPath(`${urlChain}${locationSearch}#${NEW_URL_HASH}`);
 
     const resolvedPanelProps: EntitySidePanelProps<any> = {
         ...props,
@@ -294,10 +300,12 @@ const propsToSidePanel = (props: EntitySidePanelProps,
 
     const entityViewWidth = getEntityViewWidth(props, smallLayout, customizationController, authController);
     return {
-        key: `${props.path}/${props.entityId}`,
+        // Built from the escaped chain so that two different chains which happen to flatten
+        // to the same raw string are still two different panels.
+        key: `${urlChain}/${props.entityId ? encodeEntityId(props.entityId) : ""}`,
         component: undefined, // Lazy render in SideDialogs for better performance
         urlPath: urlPath,
-        parentUrlPath: buildUrlCollectionPath(collectionPath),
+        parentUrlPath: buildUrlCollectionPath(urlChain),
         width: entityViewWidth,
         onClose: props.onClose,
         additional: resolvedPanelProps

package/src/preview/components/ReferencePreview.tsx

@@ -7,6 +7,7 @@ import { Skeleton } from "@firecms/ui";
 import { ErrorBoundary, ErrorView } from "../../components";
 import { EntityPreview, EntityPreviewContainer } from "../../components/EntityPreview";
 import { jsonStringifyReplacer } from "../../util/objects";
+import { entityCacheKey } from "../../util/entity_cache";
 
 export type ReferencePreviewProps = {
     disabled?: boolean;
@@ -108,10 +109,10 @@ function ReferencePreviewExisting<M extends Record<string, any> = any>({
     });
 
     if (entity) {
-        referencesCache.set(reference.pathWithId, entity);
+        referencesCache.set(entityCacheKey(reference.path, reference.id), entity);
     }
 
-    const usedEntity = entity ?? referencesCache.get(reference.pathWithId);
+    const usedEntity = entity ?? referencesCache.get(entityCacheKey(reference.path, reference.id));
 
     let body: React.ReactNode;
 

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/navigation_from_path.ts

@@ -147,7 +147,12 @@ 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