@firecms/core 3.4.0-canary.8635253 → 3.4.0-canary.d20cc85

package/src/components/common/useDataSourceTableController.tsx

@@ -7,18 +7,16 @@ import {
     DataType,
     Entity,
     EntityCollection,
-    EntityReference,
     EntityTableController,
     FilterValues,
     FireCMSContext,
     SelectedCellProps,
-    User,
-    WhereFilterOp
+    User
 } from "../../types";
 import { useDebouncedData } from "./useDebouncedData";
 import { ScrollRestorationController } from "./useScrollRestoration";
 import { isDataTypeFilterable } from "../../util";
-import { decodeEntityId, encodeEntityId } from "../../util/navigation_utils";
+import { encodeFilterAndSort, parseFilterAndSort } from "./table_url_params";
 
 const DEFAULT_PAGE_SIZE = 50;
 
@@ -27,6 +25,12 @@ export type DataSourceTableControllerProps<M extends Record<string, any> = any>
      * Full path where the data of this table is located
      */
     fullPath: string;
+    /**
+     * `fullPath` split at its real segment boundaries. Passed through to the datasource so
+     * a parent entity id containing "/" stays unambiguous. Defaults to splitting
+     * `fullPath`, which is correct for any backend whose ids cannot contain "/".
+     */
+    pathSegments?: string[];
     /**
      * The collection that is represented by this config.
      */
@@ -71,6 +75,7 @@ export type DataSourceTableControllerProps<M extends Record<string, any> = any>
 export function useDataSourceTableController<M extends Record<string, any> = any, USER extends User = User>(
     {
         fullPath,
+        pathSegments,
         collection,
         scrollRestoration,
         entitiesDisplayedFirst,
@@ -90,19 +95,20 @@ export function useDataSourceTableController<M extends Record<string, any> = any
     const navigation = useNavigationController();
     const dataSource = useDataSource(collection);
     const resolvedPath = useMemo(() => navigation.resolveIdsFrom(fullPath), [fullPath, navigation.resolveIdsFrom]);
+    // Passed through as-is; never derived from `resolvedPath` (see useEntityFetch).
+    const resolvedPathSegments = pathSegments;
 
     const forceFilter = forceFilterFromProps ?? forceFilterFromCollection;
     const paginationEnabled = collection.pagination === undefined || Boolean(collection.pagination);
     const pageSize = typeof collection.pagination === "number" ? collection.pagination : DEFAULT_PAGE_SIZE;
 
-    const [searchString, setSearchString] = React.useState<string | undefined>();
-
     const checkFilterCombination = useCallback((filterValues: FilterValues<any>,
         sortBy?: [string, "asc" | "desc"]) => {
         if (!dataSource.isFilterCombinationValid)
             return true;
         return dataSource.isFilterCombinationValid({
             path: resolvedPath,
+            pathSegments: resolvedPathSegments,
             collection,
             filterValues,
             sortBy
@@ -137,8 +143,9 @@ export function useDataSourceTableController<M extends Record<string, any> = any
     const {
         filterValues: initialFilterUrl,
         sortBy: initialSortUrl,
+        searchString: initialSearchUrl
     } = parseFilterAndSort(location.search);
-    
+
     const availableFilterKeys = collection.allowedFilters ?? Object.keys(collection.properties);
     const forcedFilterKeys = collection.forceFilter ? Object.keys(collection.forceFilter) : [];
 
@@ -174,6 +181,11 @@ export function useDataSourceTableController<M extends Record<string, any> = any
 
     const [filterValues, setFilterValues] = React.useState<FilterValues<Extract<keyof M, string>> | undefined>(removeUnallowedFilters(initFilters));
     const [sortBy, setSortBy] = React.useState<[Extract<keyof M, string>, "asc" | "desc"] | undefined>((updateUrl ? initialSortUrl : undefined) ?? initialSortInternal);
+    // Like the filters and the sort, the text search term is only restored from the URL when
+    // this controller owns the URL. Controllers rendered inside a dialog (e.g. a reference
+    // selection dialog) get `updateUrl: false` and must not inherit the state of the
+    // collection behind them. See https://github.com/firecmsco/firecms/issues/702
+    const [searchString, setSearchString] = React.useState<string | undefined>(updateUrl ? initialSearchUrl : undefined);
 
     useUpdateUrl(filterValues, sortBy, searchString, updateUrl);
 
@@ -223,6 +235,11 @@ export function useDataSourceTableController<M extends Record<string, any> = any
         setDataLoading(true);
 
         const onEntitiesUpdate = async (entities: Entity<M>[]) => {
+            // See useEntityFetch: entities carry the segments they were loaded with, so a
+            // reference or a delete derived from a table row stays resolvable.
+            if (resolvedPathSegments) {
+                entities = entities.map(e => e.pathSegments ? e : { ...e, pathSegments: resolvedPathSegments });
+            }
             if (collection.callbacks?.onFetch) {
                 try {
                     entities = await Promise.all(
@@ -253,32 +270,45 @@ export function useDataSourceTableController<M extends Record<string, any> = any
             setDataLoadingError(error);
         };
 
-        if (dataSource.listenCollection) {
-            return dataSource.listenCollection<M>({
-                path: resolvedPath,
-                collection,
-                onUpdate: onEntitiesUpdate,
-                onError,
-                searchString,
-                filter: filterValues,
-                limit: itemCount,
-                startAfter: undefined,
-                orderBy: sortByProperty,
-                order: currentSort
-            });
-        } else {
-            dataSource.fetchCollection<M>({
-                path: resolvedPath,
-                collection,
-                searchString,
-                filter: filterValues,
-                limit: itemCount,
-                startAfter: undefined,
-                orderBy: sortByProperty,
-                order: currentSort
-            })
-                .then(onEntitiesUpdate)
-                .catch(onError);
+        // Data sources may throw synchronously, e.g. when a text search is requested before
+        // the text search backend of the collection has been initialised. That can happen
+        // when the search term is restored from the URL instead of typed in the search bar,
+        // so it is reported as a data loading error rather than being left to blow up the
+        // whole view from inside this effect.
+        try {
+            if (dataSource.listenCollection) {
+                return dataSource.listenCollection<M>({
+                    path: resolvedPath,
+                    pathSegments: resolvedPathSegments,
+                    collection,
+                    onUpdate: onEntitiesUpdate,
+                    onError,
+                    searchString,
+                    filter: filterValues,
+                    limit: itemCount,
+                    startAfter: undefined,
+                    orderBy: sortByProperty,
+                    order: currentSort
+                });
+            } else {
+                dataSource.fetchCollection<M>({
+                    path: resolvedPath,
+                    pathSegments: resolvedPathSegments,
+                    collection,
+                    searchString,
+                    filter: filterValues,
+                    limit: itemCount,
+                    startAfter: undefined,
+                    orderBy: sortByProperty,
+                    order: currentSort
+                })
+                    .then(onEntitiesUpdate)
+                    .catch(onError);
+                return () => {
+                };
+            }
+        } catch (e: any) {
+            onError(e instanceof Error ? e : new Error(String(e)));
             return () => {
             };
         }
@@ -332,9 +362,7 @@ function useUpdateUrl<M extends Record<string, any> = any>(
 
     useEffect(() => {
         if (updateUrl) {
-            const newUrl = encodeFilterAndSort(filterValues, sortBy);
-            const search = searchString ? `&search=${encodeURIComponent(searchString)}` : "";
-            const state = `${newUrl}${search}`;
+            const state = encodeFilterAndSort(filterValues, sortBy, searchString);
             const hash = window.location.hash;
             if (state === "")
                 window.history.replaceState({}, "", `${window.location.pathname}${hash}`);
@@ -343,142 +371,3 @@ function useUpdateUrl<M extends Record<string, any> = any>(
         }
     }, [filterValues, sortBy, searchString, updateUrl]);
 }
-
-function encodeFilterAndSort(filterValues?: FilterValues<string>, sortBy?: [string, "asc" | "desc"] | undefined) {
-    const entries: Record<string, string> = {};
-    if (sortBy) {
-        entries["__sort"] = encodeURIComponent(sortBy[0]);
-        entries["__sort_order"] = encodeURIComponent(sortBy[1]);
-    }
-    if (filterValues) {
-        Object.entries(filterValues).forEach(([key, value]) => {
-            if (value) {
-                const [op, val] = value;
-                let encodedValue: any = val;
-                try {
-                    if (typeof val === "object") {
-                        if (val instanceof Date) {
-                            encodedValue = val.toISOString();
-                        } else if (Array.isArray(val)) {
-                            encodedValue = JSON.stringify(val, (key, value) => {
-                                if (value instanceof EntityReference) {
-                                    return encodeRef(value);
-                                }
-                                return value;
-                            });
-                        } else if (val instanceof EntityReference) {
-                            encodedValue = encodeRef(val);
-                        }
-                    } else if (typeof val === "string") {
-                        // JSON.stringify wraps the string in quotes (e.g. "4" → '"4"')
-                        // so that decodeString's JSON.parse restores the string type,
-                        // not a number. Without this, "4" round-trips as the number 4.
-                        encodedValue = JSON.stringify(val);
-                    }
-                } catch (e) {
-                    encodedValue = val;
-                }
-                if (encodedValue !== undefined) {
-                    entries[encodeURIComponent(`${key}_op`)] = encodeURIComponent(op);
-                    // Note: check for null/undefined explicitly instead of truthiness,
-                    // otherwise falsy-but-valid values (boolean `false`, number `0`)
-                    // would be serialized as "null" and round-trip back as `null`,
-                    // breaking filters like `archived == false`.
-                    entries[encodeURIComponent(`${key}_value`)] = encodedValue !== null && encodedValue !== undefined
-                        ? encodeURIComponent(encodedValue.toString())
-                        : "null";
-                }
-            }
-        });
-    }
-    if (!Object.keys(entries).length) {
-        return "";
-    }
-    return Object.entries(entries).map(([key, value]) => `${key}=${value}`).join("&");
-}
-
-function parseFilterAndSort<M>(search: string): {
-    filterValues: FilterValues<string> | undefined,
-    sortBy?: [Extract<keyof M, string>, "asc" | "desc"]
-} {
-    const entries = new URLSearchParams(search);
-    const filterValues: FilterValues<string> = {};
-    let sortBy: [string, "asc" | "desc"] | undefined = undefined;
-    entries.forEach((value, key) => {
-        if (key === "__sort") {
-            sortBy = [decodeURIComponent(value), entries.get("__sort_order") as "asc" | "desc"];
-        } else if (key.endsWith("_op")) {
-            const field = key.replace("_op", "");
-            const filterOp = decodeURIComponent(value) as WhereFilterOp;
-            const filterValStr = entries.get(`${field}_value`);
-            if (filterValStr !== null) {
-                filterValues[field] = [filterOp, decodeString(filterValStr)];
-            }
-        }
-    });
-
-    return {
-        filterValues: Object.keys(filterValues).length ? filterValues : undefined,
-        sortBy
-    }
-}
-
-function isDate(dateString: string): boolean {
-    // Define a regex pattern that matches the exact date format: 2025-01-07T23:00:00.000Z
-    const regexPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
-
-    // Test the dateString against the regex pattern
-    if (!regexPattern.test(dateString)) {
-        return false;
-    }
-
-    // If the regex matches, further validate if it is a valid UTC date
-    const date = new Date(dateString);
-    return date.toISOString() === dateString;
-}
-
-function encodeRef(val: EntityReference) {
-    return `ref::${val.path}/${encodeEntityId(val.id)}`;
-}
-
-/**
- * Split a "path/id" reference on its LAST separator: the path may itself be a
- * subcollection path with several segments, and the id is escaped so it is always exactly
- * one segment.
- */
-function decodeRef(encoded: string): EntityReference {
-    const separatorIndex = encoded.lastIndexOf("/");
-    if (separatorIndex < 0) return new EntityReference(encoded, "");
-    return new EntityReference(
-        decodeEntityId(encoded.substring(separatorIndex + 1)),
-        encoded.substring(0, separatorIndex)
-    );
-}
-
-function decodeString(val: string): EntityReference | Date | string {
-    let parsedFilterVal: any = val;
-    if (isDate(val)) {
-        try {
-            parsedFilterVal = new Date(val);
-        } catch (e) {
-            // ignore
-        }
-    }
-    if (typeof parsedFilterVal === "string") {
-        try {
-            parsedFilterVal = JSON.parse(parsedFilterVal, (key, value) => {
-                if (typeof value === "string" && value.startsWith("ref::")) {
-                    return decodeRef(value.substring(5));
-                }
-                return value;
-            });
-        } catch (e) {
-            // ignore
-        }
-    }
-
-    if (typeof parsedFilterVal === "string" && parsedFilterVal.startsWith("ref::")) {
-        return decodeRef(parsedFilterVal.substring(5));
-    }
-    return parsedFilterVal;
-}

package/src/components/common/useTableSearchHelper.ts

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 
 import { EntityCollection } from "../../types";
 import { useCustomizationController, useDataSource, useFireCMSContext } from "../../hooks";
@@ -7,12 +7,19 @@ export interface UseTableSearchHelperParams<M extends Record<string, any>> {
     collection: EntityCollection<M>;
     fullPath: string;
     parentCollectionIds?: string[];
+    /**
+     * Search term that is already being applied without the user having gone through the
+     * search bar, e.g. one restored from the URL query params. When set, text search is
+     * initialised automatically instead of waiting for a click on the search bar.
+     */
+    initialSearchString?: string;
 }
 
 export function useTableSearchHelper<M extends Record<string, any>>({
                                                                         collection,
                                                                         fullPath,
-                                                                        parentCollectionIds
+                                                                        parentCollectionIds,
+                                                                        initialSearchString
                                                                     }: UseTableSearchHelperParams<M>) {
 
     const context = useFireCMSContext();
@@ -21,6 +28,7 @@ export function useTableSearchHelper<M extends Record<string, any>>({
 
     const [textSearchLoading, setTextSearchLoading] = useState<boolean>(false);
     const [textSearchInitialised, setTextSearchInitialised] = useState<boolean>(false);
+    const autoInitialisedRef = useRef<boolean>(false);
 
     let onTextSearchClick: (() => void) | undefined;
     let textSearchEnabled = Boolean(collection.textSearchEnabled);
@@ -79,6 +87,17 @@ export function useTableSearchHelper<M extends Record<string, any>>({
                 }
         })
     }
+
+    // Only ever runs once, and only when a search term was restored from outside the search
+    // bar: otherwise the search bar would show a term the user can neither edit nor clear,
+    // because it stays read only until text search is initialised.
+    const shouldAutoInitialise = Boolean(initialSearchString) && textSearchEnabled && !textSearchInitialised && Boolean(onTextSearchClick);
+    useEffect(() => {
+        if (autoInitialisedRef.current || !shouldAutoInitialise) return;
+        autoInitialisedRef.current = true;
+        onTextSearchClick?.();
+    }, [shouldAutoInitialise]);
+
     return {
         textSearchLoading,
         textSearchInitialised,

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

@@ -71,6 +71,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 +107,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,
@@ -146,6 +153,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,
@@ -351,6 +359,17 @@ 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;
+        // The subcollection sits under this entity, so its segments are ours plus this
+        // entity's id (kept whole, slashes and all) plus the subcollection's own path.
+        // 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 = usedEntity && pathSegments
+            ? [
+                ...pathSegments,
+                usedEntity.id,
+                ...removeInitialAndTrailingSlashes(subcollection.path).split("/")
+            ]
+            : undefined;
 
         if (selectedTab !== subcollectionId) return null;
         return (
@@ -365,6 +384,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 +434,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/EntitySidePanel.tsx

@@ -25,6 +25,7 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
         path,
         entityId,
         fullIdPath,
+        pathSegments,
         formProps,
     } = props;
 
@@ -116,6 +117,7 @@ export function EntitySidePanel(props: EntitySidePanelProps) {
                 <EntityEditView
                     {...props}
                     fullIdPath={fullIdPath}
+                    pathSegments={pathSegments}
                     layout={"side_panel"}
                     collection={collection as EntityCollection}
                     parentCollectionIds={parentCollectionIds}

package/src/form/EntityForm.tsx

@@ -71,6 +71,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 +219,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,
@@ -292,7 +298,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;
@@ -388,7 +394,7 @@ export function EntityForm<M extends Record<string, any>>({
         },
         onValuesChangeDeferred: (values: M, controller: FormexController<M>) => {
             const key = (status === "new" || status === "copy") ? path + "#new" : path + "/" + entityId;
-            if (controller.dirty) {
+            if (controller.dirty && localChangesBackup !== false) {
                 const touchedValues = removeEmptyContainers(extractTouchedValues(values, controller.touched));
                 if (touchedValues && Object.keys(touchedValues).length > 0) {
                     saveEntityToCache(key, touchedValues);
@@ -692,7 +698,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

package/src/hooks/data/delete.ts

@@ -81,6 +81,8 @@ export async function deleteEntityWithCallbacks<M extends Record<string, any>, U
         }
     }
     return dataSource.deleteEntity({
+        // Carried by the entity from the fetch that produced it; undefined if unknown.
+        pathSegments: entity.pathSegments,
         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,
@@ -103,6 +104,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
     return dataSource.saveEntity({
         collection,
         path: resolvedPath,
+        pathSegments,
         entityId,
         values: updatedValues,
         previousValues,

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,
         collection,
         filterValues,
         sortBy,
@@ -91,6 +98,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(
@@ -124,6 +135,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 +149,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

@@ -9,6 +9,11 @@ import { useFireCMSContext } from "../useFireCMSContext";
  */
 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. Defaults to splitting the resolved path.
+     */
+    pathSegments?: string[];
     entityId?: string;
     databaseId?: string;
     collection: EntityCollection<M, USER>;
@@ -39,6 +44,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,
@@ -49,6 +55,10 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
     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 "/".
+    const pathSegments = inputPathSegments;
 
     const context: FireCMSContext<USER> = useFireCMSContext();
 
@@ -61,6 +71,12 @@ 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({
@@ -97,6 +113,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 +123,7 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
             } else {
                 dataSource.fetchEntity<M>({
                     path,
+                    pathSegments,
                     entityId,
                     databaseId,
                     collection

package/src/hooks/useResolvedNavigationFrom.tsx

@@ -86,6 +86,8 @@ export function resolveNavigationFrom<M extends Record<string, any>, USER extend
                 }
                 return dataSource.fetchEntity({
                     path: entry.path,
+                    // The navigation entry already knows the real segment boundaries.
+                    pathSegments: entry.pathSegments,
                     entityId: entry.entityId,
                     collection
                 })