@firecms/core 3.4.0-canary.f6a889a → 3.4.0

package/src/contexts/SnackbarProvider.tsx

@@ -1,12 +1,25 @@
 "use client";
 
-import React, { PropsWithChildren } from "react";
+import React, { PropsWithChildren, useEffect, useState } from "react";
 import { SnackbarProvider as NotistackSnackbarProvider } from "notistack";
 
 export const SnackbarProvider: React.FC<PropsWithChildren<{}>> = ({ children }) => {
 
+    // Notistack renders the snackbars inline, right where this provider sits in the
+    // tree, unless it is given a `domRoot`. Dialogs and side dialogs, on the other
+    // hand, are portalled to the body, so any ancestor of this provider that creates
+    // a stacking context (a transform, a filter, an `isolate`, a positioned element
+    // with a z-index...) traps the snackbars underneath them. Portalling the
+    // snackbars to the body as well puts them in the same stacking context as the
+    // dialogs, where their z-index actually wins.
+    const [domRoot, setDomRoot] = useState<HTMLElement | undefined>(undefined);
+    useEffect(() => {
+        setDomRoot(document.body);
+    }, []);
+
     return (
         <NotistackSnackbarProvider maxSnack={3}
+                                   domRoot={domRoot}
                                    autoHideDuration={3500}>
             {children}
         </NotistackSnackbarProvider>

package/src/core/EntityEditView.tsx

@@ -12,6 +12,7 @@ import {
 
 import { CircularProgressCenter, EntityCollectionView, EntityView, ErrorBoundary } from "../components";
 import {
+    buildSubcollectionPathSegments,
     canEditEntity,
     encodeEntityId,
     removeInitialAndTrailingSlashes,
@@ -28,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";
@@ -42,6 +43,8 @@ export type OnUpdateParams = {
     entity: Entity<any>,
     status: EntityStatus,
     path: string,
+    /** `path` split at its real segment boundaries, when known. Never derived from `path`. */
+    pathSegments?: string[],
     entityId?: string;
     selectedTab?: string;
     collection: EntityCollection<any>
@@ -71,6 +74,12 @@ export interface EntityEditViewProps<M extends Record<string, any>> {
      * The navigation path to the entity.
      */
     fullIdPath?: string;
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     * Forwarded to the datasource, and extended for any subcollection rendered inside this
+     * view, so a parent entity id containing "/" stays unambiguous.
+     */
+    pathSegments?: string[];
     collection: EntityCollection<M>;
     entityId?: string;
     databaseId?: string;
@@ -101,6 +110,7 @@ export function EntityEditView<M extends Record<string, any>, USER extends User>
         dataLoadingError
     } = useEntityFetch<M, USER>({
         path: props.path,
+        pathSegments: props.pathSegments,
         entityId: entityId,
         collection: props.collection,
         databaseId: props.databaseId,
@@ -108,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();
@@ -120,7 +130,7 @@ export function EntityEditView<M extends Record<string, any>, USER extends User>
         if (status === "new" || status === "copy") {
             return true;
         } else {
-            return entity ? canEditEntity(props.collection, authController, props.path, entity ?? null) : undefined;
+            return entity ? canEditEntity(props.collection, authController, props.path, entity ?? null, props.pathSegments) : undefined;
         }
     }, [authController, entity, status]);
 
@@ -146,6 +156,7 @@ export function EntityEditView<M extends Record<string, any>, USER extends User>
 export function EntityEditViewInner<M extends Record<string, any>>({
     path,
     fullIdPath,
+    pathSegments,
     entityId,
     selectedTab: selectedTabProp,
     collection,
@@ -194,6 +205,7 @@ export function EntityEditViewInner<M extends Record<string, any>>({
             entityId,
             parentCollectionIds,
             path,
+            pathSegments,
             status,
             collection,
             context,
@@ -351,6 +363,9 @@ export function EntityEditViewInner<M extends Record<string, any>>({
         const newFullPath = usedEntity ? `${path}/${usedEntity?.id}/${removeInitialAndTrailingSlashes(subcollection.path)}` : undefined;
         // `newFullIdPath` is fed to buildUrlCollectionPath downstream, so it stays escaped.
         const newFullIdPath = fullIdPath && usedEntity ? `${fullIdPath}/${encodeEntityId(usedEntity.id)}/${removeInitialAndTrailingSlashes(subcollectionId)}` : undefined;
+        // Only extendable when we were given real segments — deriving the parent chain
+        // from the flattened `path` would drop the boundary of a slash-bearing parent id.
+        const newPathSegments = buildSubcollectionPathSegments(pathSegments, usedEntity?.id, subcollection.path);
 
         if (selectedTab !== subcollectionId) return null;
         return (
@@ -365,6 +380,7 @@ export function EntityEditViewInner<M extends Record<string, any>>({
                     (usedEntity && newFullPath
                         ? <EntityCollectionView
                             fullPath={newFullPath}
+                            pathSegments={newPathSegments}
                             fullIdPath={newFullIdPath}
                             parentCollectionIds={[...parentCollectionIds, collection.id]}
                             isSubCollection={true}
@@ -414,6 +430,7 @@ export function EntityEditViewInner<M extends Record<string, any>>({
         fullIdPath={fullIdPath}
         collection={collection}
         path={path}
+        pathSegments={pathSegments}
         entityId={entityId ?? usedEntity?.id}
         onValuesModified={onValuesModified}
         entity={entity}

package/src/core/EntityEditViewFormActions.tsx

@@ -39,6 +39,7 @@ import { ErrorTooltip } from "../components/ErrorTooltip";
 export function EntityEditViewFormActions({
                                               collection,
                                               path,
+                                              pathSegments,
                                               entity,
                                               layout,
                                               savingError,
@@ -63,8 +64,8 @@ export function EntityEditViewFormActions({
         const customEntityActions = (collection.entityActions ?? [])
             .map(action => resolveEntityAction(action, customizationController.entityActions))
             .filter(Boolean) as EntityAction[];
-        const createEnabled = canCreateEntity(collection, authController, path, null);
-        const deleteEnabled = entity ? canDeleteEntity(collection, authController, path, entity) : false;
+        const createEnabled = canCreateEntity(collection, authController, path, null, pathSegments);
+        const deleteEnabled = entity ? canDeleteEntity(collection, authController, path, entity, entity.pathSegments ?? pathSegments) : false;
         const actions: EntityAction[] = [];
         if (createEnabled)
             actions.push(copyEntityAction);

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
@@ -25,6 +25,7 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
         path,
         entityId,
         fullIdPath,
+        pathSegments,
         formProps,
     } = props;
 
@@ -59,6 +60,7 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
         if (params.status !== "existing") {
             sideEntityController.replace({
                 path: params.path,
+                pathSegments: params.pathSegments ?? pathSegments,
                 entityId: params.entityId,
                 fullIdPath: props.fullIdPath,
                 selectedTab: params.selectedTab,
@@ -75,10 +77,10 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
     }
 
     const parentCollectionIds = useMemo(() => {
-        return navigationController.getParentCollectionIds(path);
+        return navigationController.getParentCollectionIds(path, pathSegments);
     }, [navigationController, path]);
 
-    const collection = props.collection ?? navigationController.getCollection(fullIdPath ?? path);
+    const collection = props.collection ?? navigationController.getCollection(fullIdPath ?? path, false, pathSegments);
 
     useEffect(() => {
         function beforeunload(e: any) {
@@ -116,6 +118,7 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
                 <EntityEditView
                     {...props}
                     fullIdPath={fullIdPath}
+                    pathSegments={pathSegments}
                     layout={"side_panel"}
                     collection={collection as EntityCollection}
                     parentCollectionIds={parentCollectionIds}
@@ -135,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);
@@ -152,6 +155,7 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
                     }) => {
                         sideEntityController.replace({
                             path,
+                            pathSegments,
                             entityId,
                             fullIdPath: props.fullIdPath,
                             selectedTab,

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,
@@ -64,6 +65,8 @@ export type OnUpdateParams = {
     entity: Entity<any>,
     status: EntityStatus,
     path: string,
+    /** `path` split at its real segment boundaries, when known. Never derived from `path`. */
+    pathSegments?: string[],
     entityId?: string;
     selectedTab?: string;
     collection: EntityCollection<any>
@@ -71,6 +74,11 @@ export type OnUpdateParams = {
 
 export type EntityFormProps<M extends Record<string, any>> = {
     path: string;
+    /**
+     * `path` split at its real segment boundaries; forwarded to the datasource for
+     * generateEntityId and checkUniqueField. Never derived from `path`.
+     */
+    pathSegments?: string[];
     fullIdPath?: string;
     collection: EntityCollection<M>;
     entityId?: string;
@@ -214,6 +222,7 @@ export function getChanges<T extends object>(source: Partial<T>, comparison: Par
 
 export function EntityForm<M extends Record<string, any>>({
     path,
+    pathSegments,
     fullIdPath,
     entityId: entityIdProp,
     collection,
@@ -270,6 +279,7 @@ export function EntityForm<M extends Record<string, any>>({
                 entityId: entityIdProp,
                 collection,
                 path,
+                pathSegments,
                 values: valuesToBeSaved
             });
     }, false, 2000);
@@ -292,7 +302,7 @@ export function EntityForm<M extends Record<string, any>>({
             if (mustSetCustomId) {
                 return undefined;
             } else {
-                return dataSource.generateEntityId(path, collection);
+                return dataSource.generateEntityId(path, collection, pathSegments);
             }
         } else {
             return entityIdProp;
@@ -308,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);
@@ -387,8 +397,8 @@ 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;
-            if (controller.dirty) {
+            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) {
                     saveEntityToCache(key, touchedValues);
@@ -468,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));
         }
     }
 
@@ -491,6 +501,7 @@ export function EntityForm<M extends Record<string, any>>({
                 entity: updatedEntity,
                 status,
                 path,
+                pathSegments,
                 entityId: updatedEntity.id,
                 collection
             });
@@ -511,16 +522,20 @@ export function EntityForm<M extends Record<string, any>>({
         previousValues,
         entityId,
         collection,
-        path
+        path,
+        pathSegments
     }: {
         collection: EntityCollection<M>,
         path: string,
+        /** `path` split at its real segment boundaries, travelling with the `path` above. */
+        pathSegments?: string[],
         entityId: string | undefined,
         values: M,
         previousValues?: M,
     }) => {
         return saveEntityWithCallbacks({
             path,
+            pathSegments,
             entityId,
             values,
             previousValues,
@@ -538,6 +553,7 @@ export function EntityForm<M extends Record<string, any>>({
     type EntityFormSaveParams<M extends Record<string, any>> = {
         collection: ResolvedEntityCollection<M>,
         path: string,
+        pathSegments?: string[],
         entityId: string | undefined,
         values: EntityValues<M>,
         previousValues?: EntityValues<M>,
@@ -547,6 +563,7 @@ export function EntityForm<M extends Record<string, any>>({
     const onSaveEntityRequest = async ({
         collection,
         path,
+        pathSegments,
         entityId,
         values,
         previousValues,
@@ -560,6 +577,7 @@ export function EntityForm<M extends Record<string, any>>({
             return saveEntity({
                 collection,
                 path,
+                pathSegments,
                 entityId,
                 values,
                 previousValues
@@ -573,6 +591,7 @@ export function EntityForm<M extends Record<string, any>>({
         return onSaveEntityRequest({
             collection: resolvedCollection,
             path,
+            pathSegments,
             entityId,
             values,
             previousValues: entity?.values,
@@ -623,13 +642,14 @@ export function EntityForm<M extends Record<string, any>>({
     const plugins = customizationController.plugins;
 
     const actionsDisabled = disabled || formex.isSubmitting || (status === "existing" && !formex.dirty) || Boolean(disabledProp);
-    const parentCollectionIds = navigationController.getParentCollectionIds(path);
+    const parentCollectionIds = navigationController.getParentCollectionIds(path, pathSegments);
 
     if (plugins && collection) {
         const actionProps: PluginFormActionProps = {
             entityId,
             parentCollectionIds,
             path,
+            pathSegments,
             status,
             collection,
             context,
@@ -692,7 +712,7 @@ export function EntityForm<M extends Record<string, any>>({
     const uniqueFieldValidator: CustomFieldValidator = useCallback(({
         name,
         value
-    }) => dataSource.checkUniqueField(path, name, value, entityId, collection),
+    }) => dataSource.checkUniqueField(path, name, value, entityId, collection, pathSegments),
         [dataSource, path, entityId]);
 
     const validationSchema = useMemo(() => entityId
@@ -890,6 +910,7 @@ export function EntityForm<M extends Record<string, any>>({
     const dialogActions = <EntityFormActionsComponent
         collection={resolvedCollection}
         path={path}
+        pathSegments={pathSegments}
         fullPath={path}
         fullIdPath={fullIdPath}
         entity={entity}
@@ -924,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/form/EntityFormActions.tsx

@@ -26,6 +26,8 @@ export interface EntityFormActionsProps {
     fullIdPath?: string;
     collection: ResolvedEntityCollection;
     path: string;
+    /** `path` split at its real segment boundaries, when known. Never derived from `path`. */
+    pathSegments?: string[];
     entity?: Entity;
     layout: "bottom" | "side";
     savingError?: Error;

package/src/hooks/data/delete.ts

@@ -46,6 +46,7 @@ export type DeleteEntityWithCallbacksProps<M extends Record<string, any>, USER e
 export async function deleteEntityWithCallbacks<M extends Record<string, any>, USER extends User>({
                                                                                                           dataSource,
                                                                                                           entity,
+                                                                                                          pathSegments,
                                                                                                           collection,
                                                                                                           callbacks,
                                                                                                           onDeleteSuccess,
@@ -62,11 +63,17 @@ export async function deleteEntityWithCallbacks<M extends Record<string, any>, U
 
     console.debug("Deleting entity", entity.path, entity.id);
 
+    // An explicit `pathSegments` wins, then the ones the entity was loaded with. The prop
+    // used to be accepted and silently ignored, which is the same class of bug this field
+    // exists to prevent.
+    const resolvedPathSegments = pathSegments ?? entity.pathSegments;
+
     const entityDeleteProps: EntityOnDeleteProps<M, any> = {
         entity,
         collection,
         entityId: entity.id,
         path: entity.path,
+        pathSegments: resolvedPathSegments,
         context
     };
 
@@ -81,6 +88,7 @@ export async function deleteEntityWithCallbacks<M extends Record<string, any>, U
         }
     }
     return dataSource.deleteEntity({
+        pathSegments: resolvedPathSegments,
         entity,
         collection
     }).then(() => {

package/src/hooks/data/save.ts

@@ -43,6 +43,7 @@ export type SaveEntityWithCallbacksProps<M extends Record<string, any>> =
 export async function saveEntityWithCallbacks<M extends Record<string, any>, USER extends User>({
                                                                                                     collection,
                                                                                                     path,
+                                                                                                    pathSegments,
                                                                                                     entityId,
                                                                                                     values,
                                                                                                     previousValues,
@@ -67,7 +68,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
 
     const customizationController = context.customizationController;
 
-    const resolvedPath = context.navigation.resolveIdsFrom(path);
+    const resolvedPath = context.navigation.resolveIdsFrom(path, pathSegments);
 
     const callbacks = collection.callbacks;
     if (callbacks?.onPreSave) {
@@ -83,6 +84,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
             updatedValues = await callbacks.onPreSave({
                 collection: resolvedCollection,
                 path,
+                pathSegments,
                 resolvedPath,
                 entityId,
                 values,
@@ -103,6 +105,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
     return dataSource.saveEntity({
         collection,
         path: resolvedPath,
+        pathSegments,
         entityId,
         values: updatedValues,
         previousValues,
@@ -121,6 +124,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
                 callbacks.onSaveSuccess({
                     collection: resolvedCollection,
                     path,
+                    pathSegments,
                     resolvedPath,
                     entityId: entity.id,
                     values: updatedValues,
@@ -150,6 +154,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
                 callbacks.onSaveFailure({
                     collection: resolvedCollection,
                     path,
+                    pathSegments,
                     resolvedPath,
                     entityId,
                     values: updatedValues,

package/src/hooks/data/useCollectionFetch.tsx

@@ -13,6 +13,12 @@ export interface CollectionFetchProps<M extends Record<string, any>> {
      * Absolute collection path
      */
     path: string;
+    /**
+     * `path` split at its real segment boundaries. Forwarded to the datasource so a parent
+     * entity id containing "/" stays unambiguous. Never derived from `path` — see
+     * `pathSegments` on the datasource props.
+     */
+    pathSegments?: string[];
 
     /**
      * collection of the entity displayed by this collection
@@ -63,6 +69,7 @@ export interface CollectionFetchResult<M extends Record<string, any>> {
 export function useCollectionFetch<M extends Record<string, any>, USER extends User>(
     {
         path: inputPath,
+        pathSegments: inputPathSegments,
         collection,
         filterValues,
         sortBy,
@@ -73,7 +80,13 @@ export function useCollectionFetch<M extends Record<string, any>, USER extends U
     const dataSource = useDataSource(collection);
     const navigationController = useNavigationController();
 
-    const path = navigationController.resolveIdsFrom(inputPath);
+    // Resolved together so the two representations always describe the same chain.
+    // Segments are resolved, never derived: only collection ids are swapped for their
+    // real paths, and entity ids are carried through whole (see useEntityFetch).
+    const pathSegments = inputPathSegments
+        ? (navigationController.resolveSegmentsFrom?.(inputPathSegments) ?? inputPathSegments)
+        : undefined;
+    const path = navigationController.resolveIdsFrom(inputPath, inputPathSegments);
 
     const sortByProperty = sortBy ? sortBy[0] : undefined;
     const currentSort = sortBy ? sortBy[1] : undefined;
@@ -91,6 +104,10 @@ export function useCollectionFetch<M extends Record<string, any>, USER extends U
         setDataLoading(true);
 
         const onEntitiesUpdate = async (entities: Entity<M>[]) => {
+            // See useEntityFetch: entities carry the segments they were loaded with.
+            if (pathSegments) {
+                entities = entities.map(e => e.pathSegments ? e : { ...e, pathSegments });
+            }
             if (collection.callbacks?.onFetch) {
                 try {
                     entities = await Promise.all(
@@ -98,6 +115,7 @@ export function useCollectionFetch<M extends Record<string, any>, USER extends U
                             collection.callbacks!.onFetch!({
                                 collection,
                                 path,
+                                pathSegments,
                                 entity,
                                 context
                             })));
@@ -124,6 +142,7 @@ export function useCollectionFetch<M extends Record<string, any>, USER extends U
         if (dataSource.listenCollection) {
             return dataSource.listenCollection<M>({
                 path,
+                pathSegments,
                 collection,
                 onUpdate: onEntitiesUpdate,
                 onError,
@@ -137,6 +156,7 @@ export function useCollectionFetch<M extends Record<string, any>, USER extends U
         } else {
             dataSource.fetchCollection<M>({
                 path,
+                pathSegments,
                 collection,
                 searchString,
                 filter: filterValues,

package/src/hooks/data/useEntityFetch.tsx

@@ -3,12 +3,21 @@ 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
  */
 export interface EntityFetchProps<M extends Record<string, any>, USER extends User = User> {
     path: string;
+    /**
+     * `path` split at its real segment boundaries. Forwarded to the datasource so a parent
+     * entity id containing "/" stays unambiguous.
+     *
+     * Optional, and never derived by splitting `path` — a guess would be wrong in exactly
+     * the case the field exists for. Absent means "not known here", not "no slashes".
+     */
+    pathSegments?: string[];
     entityId?: string;
     databaseId?: string;
     collection: EntityCollection<M, USER>;
@@ -39,6 +48,7 @@ const CACHE: Record<string, Entity<any> | undefined> = {};
 export function useEntityFetch<M extends Record<string, any>, USER extends User>(
     {
         path: inputPath,
+        pathSegments: inputPathSegments,
         entityId,
         collection,
         databaseId,
@@ -48,7 +58,19 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
     const dataSource = useDataSource(collection);
     const navigationController = useNavigationController();
 
-    const path = navigationController.resolveIdsFrom(inputPath);
+    // Never fabricate segments. If the caller did not thread them, pass undefined so a
+    // delegate can tell "not provided" from a real answer — splitting `path` here would
+    // produce a confidently wrong array for any id containing "/".
+    //
+    // When they were threaded, both representations are resolved from them together, so
+    // `path` cannot end up describing a different chain than `pathSegments`.
+    // `resolveSegmentsFrom` is optional on the controller: a host app may be supplying one
+    // built against an earlier version. Falling back to the segments as given is what
+    // happened before it existed — they are used unresolved, never invented.
+    const pathSegments = inputPathSegments
+        ? (navigationController.resolveSegmentsFrom?.(inputPathSegments) ?? inputPathSegments)
+        : undefined;
+    const path = navigationController.resolveIdsFrom(inputPath, inputPathSegments);
 
     const context: FireCMSContext<USER> = useFireCMSContext();
 
@@ -61,11 +83,18 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
         setDataLoading(true);
 
         const onEntityUpdate = async (updatedEntity: Entity<M> | undefined) => {
+            // Attach the segments this entity was loaded with, so anything derived from it
+            // later — a reference, a delete — stays resolvable without re-deriving them
+            // from the flattened path. Delegates are not required to set this themselves.
+            if (updatedEntity && pathSegments && !updatedEntity.pathSegments) {
+                updatedEntity = { ...updatedEntity, pathSegments };
+            }
             if (collection.callbacks?.onFetch && updatedEntity) {
                 try {
                     updatedEntity = await collection.callbacks.onFetch({
                         collection,
                         path,
+                        pathSegments,
                         entity: updatedEntity,
                         context
                     });
@@ -73,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);
@@ -86,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
@@ -97,6 +126,7 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
             if (dataSource.listenEntity) {
                 return dataSource.listenEntity<M>({
                     path,
+                    pathSegments,
                     entityId,
                     databaseId,
                     collection,
@@ -106,6 +136,7 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
             } else {
                 dataSource.fetchEntity<M>({
                     path,
+                    pathSegments,
                     entityId,
                     databaseId,
                     collection