@firecms/core 3.3.0 → 3.4.0-canary.2575a08

package/src/locales/pt.ts

@@ -151,8 +151,8 @@ export const pt: FireCMSTranslations = {
     // ─── Error states ─────────────────────────────────────────────
     error: "Erro",
     error_uploading_file: "Erro ao carregar ficheiro",
-    error_deleting: "Erro ao eliminar",
-    error_before_delete: "Erro antes de eliminar",
+    error_deleting: "Erro ao eliminar: {{message}}",
+    error_before_delete: "Erro antes de eliminar: {{message}}",
     error_updating_asset: "Erro ao atualizar recurso",
     error_deleting_asset: "Erro ao eliminar recurso",
     error_firestore_index: "É necessário um índice Firestore para esta consulta.",
@@ -394,6 +394,7 @@ export const pt: FireCMSTranslations = {
     download: "Descarregar",
     large_number_of_documents: "Esta coleção tem um grande número de documentos ({{count}}).",
     include_undefined_values: "Incluir valores indefinidos",
+    export_apply_filter_sort: "Exportar apenas os resultados que correspondem ao filtro/ordenação atual",
     submit: "Submeter",
 
     no_filterable_properties: "Não há propriedades filtráveis disponíveis",
@@ -595,6 +596,10 @@ export const pt: FireCMSTranslations = {
     order_property_not_found: "A propriedade \"{{property}}\" não existe ou não é uma propriedade numérica. Selecione uma propriedade válida ou limpe a seleção.",
     no_number_properties: "Nenhuma propriedade numérica encontrada. Adicione uma propriedade numérica para habilitar a ordenação.",
     order_property_description: "Selecione uma propriedade numérica para manter a ordem dos itens",
+    image_property: "Propriedade de imagem",
+    image_property_not_found: "A propriedade \"{{property}}\" não existe ou não é uma propriedade de imagem. Selecione uma propriedade válida ou limpe a seleção.",
+    no_image_properties: "Nenhuma propriedade de imagem encontrada. Adicione uma propriedade de armazenamento ou URL de imagem para usar como miniatura.",
+    image_property_description: "Selecione a propriedade usada como miniatura nas visualizações de Cartões e Kanban. Se não for definida, a primeira propriedade de imagem correspondente será usada automaticamente.",
     display_settings: "Configurações de exibição",
     default_row_size: "Tamanho de linha padrão",
     side_dialog_width: "Largura do diálogo lateral",

package/src/preview/PropertyPreview.tsx

@@ -4,6 +4,7 @@ import equal from "react-fast-compare"
 import {
     CMSType,
     EntityReference,
+    GeoPoint,
     ResolvedArrayProperty,
     ResolvedMapProperty,
     ResolvedNumberProperty,
@@ -27,12 +28,14 @@ import { ArrayPropertyEnumPreview } from "./property_previews/ArrayPropertyEnumP
 import { ArrayOfStringsPreview } from "./property_previews/ArrayOfStringsPreview";
 import { ArrayOneOfPreview } from "./property_previews/ArrayOneOfPreview";
 import { MapPropertyPreview } from "./property_previews/MapPropertyPreview";
+import { GeopointPropertyPreview } from "./property_previews/GeopointPropertyPreview";
 import { ReferencePreview } from "./components/ReferencePreview";
 import { DatePreview } from "./components/DatePreview";
 import { BooleanPreview } from "./components/BooleanPreview";
 import { NumberPropertyPreview } from "./property_previews/NumberPropertyPreview";
 import { ErrorView } from "../components";
 import { UserPreview } from "./components/UserPreview";
+import { getGeoPointCoordinates } from "../util";
 
 /**
  * @group Preview components
@@ -202,6 +205,15 @@ export const PropertyPreview = React.memo(function PropertyPreview<T extends CMS
         } else {
             content = buildWrongValueType(propertyKey, property.dataType, value);
         }
+    } else if (property.dataType === "geopoint") {
+        const coordinates = getGeoPointCoordinates(value as GeoPoint);
+        if (coordinates) {
+            content = <GeopointPropertyPreview {...props}
+                                               property={property}
+                                               value={value as GeoPoint}/>;
+        } else {
+            content = buildWrongValueType(propertyKey, property.dataType, value);
+        }
     } else if (property.dataType === "reference") {
         if (typeof property.path === "string") {
             if (typeof value === "object" && "isEntityReference" in value && value.isEntityReference()) {

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;
@@ -53,7 +54,7 @@ function ReferencePreviewInternal({
 
     const navigationController = useNavigationController();
 
-    const collection = navigationController.getCollection(reference.path);
+    const collection = navigationController.getCollection(reference.path, false, reference.pathSegments);
     if (!collection) {
         if (customizationController.components?.missingReference) {
             return <customizationController.components.missingReference path={reference.path}/>;
@@ -99,16 +100,19 @@ function ReferencePreviewExisting<M extends Record<string, any> = any>({
         dataLoadingError
     } = useEntityFetch({
         path: reference.path,
+        // References carry the segments of the collection they point at, when the code that
+        // built them knew them (see getReferenceFrom).
+        pathSegments: reference.pathSegments,
         entityId: reference.id,
         collection,
         useCache: true
     });
 
     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/preview/components/StorageThumbnail.tsx

@@ -6,6 +6,7 @@ import { useStorageSource } from "../../hooks";
 import { DownloadConfig, FileType } from "../../types";
 import { PreviewSize } from "../PropertyPreviewProps";
 import { ErrorView } from "../../components";
+import { getPreviewTypeFromUrl, isAbsoluteHttpUrl } from "../../util/urls";
 
 type StorageThumbnailProps = {
     storagePathOrDownloadUrl: string;
@@ -41,10 +42,20 @@ export function StorageThumbnailInternal({
     const [error, setError] = React.useState<Error | undefined>(undefined);
     const storage = useStorageSource();
 
+    /**
+     * The saved value may already be a resolved download URL instead of a
+     * storage path: either because the property is configured with
+     * `storeUrl: true`, or because the value was written directly in the
+     * datasource pointing to an externally hosted file. Such values can be
+     * previewed as they are, and must not be handed over to the storage source,
+     * which can only resolve paths of its own bucket.
+     */
+    const valueIsUrl = storeUrl || isAbsoluteHttpUrl(storagePathOrDownloadUrl);
+
     const [downloadConfig, setDownloadConfig] = React.useState<DownloadConfig>(URL_CACHE[storagePathOrDownloadUrl]);
 
     useEffect(() => {
-        if (!storagePathOrDownloadUrl)
+        if (!storagePathOrDownloadUrl || valueIsUrl)
             return;
         let unmounted = false;
         storage.getDownloadURL(storagePathOrDownloadUrl)
@@ -57,10 +68,21 @@ export function StorageThumbnailInternal({
         return () => {
             unmounted = true;
         };
-    }, [storagePathOrDownloadUrl]);
+    }, [storagePathOrDownloadUrl, valueIsUrl]);
 
     if (!storagePathOrDownloadUrl) return null;
 
+    if (valueIsUrl) {
+        // There is no storage metadata for a value that is already a URL, so the
+        // preview type is inferred from its file extension when possible.
+        return <UrlComponentPreview previewType={getPreviewTypeFromUrl(storagePathOrDownloadUrl) ?? "file"}
+            url={storagePathOrDownloadUrl}
+            interactive={interactive}
+            size={size}
+            fill={fill}
+            hint={storagePathOrDownloadUrl} />;
+    }
+
     const filetype = downloadConfig?.metadata ? getFiletype(downloadConfig?.metadata.contentType) : undefined;
     const previewType = filetype?.startsWith("image")
         ? "image"

package/src/preview/index.ts

@@ -7,6 +7,7 @@ export * from "./property_previews/ArrayOfStringsPreview";
 export * from "./property_previews/ArrayPropertyEnumPreview";
 export * from "./property_previews/ArrayOfMapsPreview";
 export * from "./property_previews/NumberPropertyPreview";
+export * from "./property_previews/GeopointPropertyPreview";
 export * from "./property_previews/StringPropertyPreview";
 export * from "./property_previews/ArrayOfStorageComponentsPreview";
 export * from "./property_previews/ArrayOfReferencesPreview";

package/src/preview/property_previews/GeopointPropertyPreview.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+
+import { GeoPoint } from "../../types";
+import { PropertyPreviewProps } from "../PropertyPreviewProps";
+import { formatGeoPoint, getGeoPointCoordinates } from "../../util";
+
+export function GeopointPropertyPreview({
+                                             value,
+                                             size
+                                         }: PropertyPreviewProps<GeoPoint>): React.ReactElement {
+
+    const coordinates = getGeoPointCoordinates(value);
+
+    if (!coordinates) {
+        return <span className={size === "small" ? "text-sm text-text-secondary dark:text-text-secondary-dark" : "text-text-secondary dark:text-text-secondary-dark"}>—</span>;
+    }
+
+    return (
+        <span className={size === "small" ? "text-sm font-mono" : "font-mono"}>
+            {formatGeoPoint(coordinates)}
+        </span>
+    );
+}

package/src/routes/FireCMSRoute.tsx

@@ -10,6 +10,8 @@ import {
 } from "../util/navigation_from_path";
 import { useBreadcrumbsController } from "../hooks/useBreadcrumbsController";
 import { toArray } from "../util/arrays";
+import { addInitialSlash, encodeEntityId } from "../util/navigation_utils";
+import { shouldBlockEntityNavigation } from "../util/navigation_blocking";
 import { NotFoundPage } from "../components";
 import { lazyEager } from "../util/lazy_eager";
 
@@ -88,7 +90,7 @@ export function FireCMSRoute() {
         let collection: EntityCollection<any> | undefined;
         collection = navigation.getCollectionById(navigationEntries[0].id);
         if (!collection)
-            collection = navigation.getCollection(navigationEntries[0].path);
+            collection = navigation.getCollection(navigationEntries[0].path, false, navigationEntries[0].pathSegments);
         if (!collection)
             return null;
         return <React.Suspense fallback={null}>
@@ -97,6 +99,7 @@ export function FireCMSRoute() {
                 isSubCollection={false}
                 parentCollectionIds={[]}
                 fullPath={collection.path}
+                pathSegments={navigationEntries[0].pathSegments}
                 fullIdPath={collection.id}
                 updateUrl={true}
                 {...collection}
@@ -111,7 +114,7 @@ export function FireCMSRoute() {
             const firstEntry = navigationEntries[0] as NavigationViewCollectionInternal<any>;
             collection = navigation.getCollectionById(firstEntry.id);
             if (!collection)
-                collection = navigation.getCollection(firstEntry.path);
+                collection = navigation.getCollection(firstEntry.path, false, firstEntry.pathSegments);
             if (!collection)
                 return null;
             return <React.Suspense fallback={null}>
@@ -121,6 +124,7 @@ export function FireCMSRoute() {
                     isSubCollection={false}
                     parentCollectionIds={[]}
                     fullPath={collection.path}
+                    pathSegments={firstEntry.pathSegments}
                     updateUrl={true}
                     {...collection}
                     Actions={toArray(collection.Actions)} />
@@ -182,6 +186,8 @@ function EntityFullScreenRoute({
     const urlTab = getSelectedTabFromUrl(isNew, lastCustomView);
     const [selectedTab, setSelectedTab] = useState<string | undefined>(urlTab);
 
+    // `navigationPath` comes from the URL, where entity ids are still escaped (see
+    // encodeEntityId), so splitting it on "/" inside is correct and no segments are needed.
     const parentCollectionIds = navigation.getParentCollectionIds(navigationPath);
     useEffect(() => {
         if (urlTab !== selectedTab) {
@@ -189,27 +195,51 @@ function EntityFullScreenRoute({
         }
     }, [urlTab]);
 
-    const basePath = !entityId || isNew
+    const lastCollectionEntry = navigationEntries.findLast((entry) => entry.type === "collection");
+
+    // The entity id reaches the URL escaped AND percent-encoded, so it cannot be located by
+    // searching `pathname` for the raw id — that misses for any id needing encoding (a "/",
+    // but equally a space or a non-ASCII character). Rebuild the URLs from the navigation
+    // entries instead, which already carry the escaped chain in `fullPath`.
+    const entityEntryIndex = lastEntityEntry ? navigationEntries.indexOf(lastEntityEntry) : -1;
+    const parentCollectionEntry = entityEntryIndex > 0
+        ? navigationEntries[entityEntryIndex - 1] as NavigationViewCollectionInternal<any>
+        : undefined;
+
+    const buildUrl = (escapedPath: string) => addInitialSlash(navigation.buildUrlCollectionPath(escapedPath));
+
+    const basePath = !entityId || isNew || !parentCollectionEntry
         ? pathname
-        : pathname.substring(0, pathname.lastIndexOf(`/${entityId}`));
+        : buildUrl(parentCollectionEntry.fullPath);
+
+    const entityPath = lastEntityEntry ? buildUrl(lastEntityEntry.fullPath) : basePath;
 
-    const entityPath = basePath + `/${entityId}`;
+    /**
+     * Build the URL of an entity in the current collection. `id` is raw, so it is escaped
+     * before being joined; `buildUrlCollectionPath` then percent-encodes the whole path.
+     */
+    const buildEntityUrl = (id: string, tab?: string) => {
+        const parentPath = parentCollectionEntry?.fullPath ?? lastCollectionEntry?.fullPath;
+        if (!parentPath) return pathname;
+        return buildUrl(`${parentPath}/${encodeEntityId(id)}${tab ? "/" + tab : ""}`);
+    };
 
     let blocker: Blocker | undefined = undefined;
     try {
         blocker = useBlocker(({
+            currentLocation,
             nextLocation
-        }) => {
-            if (nextLocation.pathname.startsWith(entityPath))
-                return false;
-            return blocked.current;
-        });
+        }) => shouldBlockEntityNavigation({
+            currentLocation,
+            nextLocation,
+            entityPath,
+            basePath,
+            blocked: blocked.current
+        }));
     } catch (e) {
         // console.warn("Blocker not available, navigation will not be blocked");
     }
 
-    const lastCollectionEntry = navigationEntries.findLast((entry) => entry.type === "collection");
-
     if (isNew && !lastCollectionEntry) {
         throw new Error("INTERNAL: No collection found in the navigation");
     }
@@ -219,14 +249,20 @@ function EntityFullScreenRoute({
     }
 
     const collection = isNew ? lastCollectionEntry!.collection : lastEntityEntry!.parentCollection;
-    const fullIdPath = isNew ? lastCollectionEntry!.path : lastEntityEntry!.path;
-    const collectionPath = navigation.resolveIdsFrom(fullIdPath);
+    // `fullIdPath` is used downstream to build URLs, so it carries the escaped chain;
+    // `collectionPath` addresses the datasource, so it is resolved from the raw one.
+    const fullIdPath = isNew ? lastCollectionEntry!.fullPath : (parentCollectionEntry?.fullPath ?? lastEntityEntry!.fullPath);
+    // The navigation entries know the real segment boundaries, so the path is resolved
+    // from them rather than re-parsed out of the flattened string.
+    const pathSegments = isNew ? lastCollectionEntry!.pathSegments : lastEntityEntry!.pathSegments;
+    const collectionPath = navigation.resolveIdsFrom(isNew ? lastCollectionEntry!.path : lastEntityEntry!.path, pathSegments);
     return <>
         <React.Suspense fallback={null}>
             <EntityEditView
                 key={collection.id + "_" + (isNew ? "new" : (isCopy ? entityId + "_copy" : entityId))}
                 entityId={isNew ? undefined : entityId}
                 fullIdPath={fullIdPath}
+                pathSegments={pathSegments}
                 collection={collection}
                 layout={"full_screen"}
                 path={collectionPath}
@@ -234,25 +270,16 @@ function EntityFullScreenRoute({
                 selectedTab={selectedTab ?? undefined}
                 onValuesModified={(modified) => blocked.current = modified}
                 onSaved={(params) => {
-                    const newSelectedTab = params.selectedTab;
                     const newEntityId = params.entityId;
-                    if (newSelectedTab) {
-                        navigate(`${basePath}/${newEntityId}/${newSelectedTab}`, { replace: true });
-                    } else {
-                        navigate(`${basePath}/${newEntityId}`, { replace: true });
-                    }
+                    if (!newEntityId) return;
+                    navigate(buildEntityUrl(newEntityId, params.selectedTab), { replace: true });
                 }}
                 onTabChange={(params) => {
                     setSelectedTab(params.selectedTab);
-                    if (isNew) {
+                    if (isNew || !entityId) {
                         return;
                     }
-                    const newSelectedTab = params.selectedTab;
-                    if (newSelectedTab) {
-                        navigate(`${basePath}/${entityId}/${newSelectedTab}`, { replace: true });
-                    } else {
-                        navigate(`${basePath}/${entityId}`, { replace: true });
-                    }
+                    navigate(buildEntityUrl(entityId, params.selectedTab), { replace: true });
                 }}
                 parentCollectionIds={parentCollectionIds}
             />

package/src/types/collections.ts

@@ -101,6 +101,14 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      */
     titleProperty?: keyof M;
 
+    /**
+     * Property used as the image thumbnail in Cards and Kanban view modes.
+     * Must reference a storage/image property (or an array of them), or a
+     * string property with `url: "image"`.
+     * If not specified, the first matching image property will be used.
+     */
+    imageProperty?: keyof M;
+
     /**
      * When editing an entity, you can choose to open the entity in a side dialog
      * or in a full screen dialog. Defaults to `full_screen`.
@@ -261,6 +269,22 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      */
     initialFilter?: FilterValues<Extract<keyof M, string>>; // setting FilterValues<M> can break defining collections by code
 
+    /**
+     * Array of property keys that are allowed for filtering. Allowed filters will be displayed in the collection view, table row headers 
+     * and will be used to filter data.
+     * 
+     * If not specified, all properties that are filterable will be allowed.
+     * 
+     * If you specify this prop, the filters will be displayed in the collection view if they are filterable.
+     * 
+     * If you set it as an empty array, no filters will be displayed.
+     * 
+     * e.g. `allowedFilters: ["name", "category"]`
+     * 
+     * e.g. `allowedFilters: []`
+     */
+    allowedFilters?: (keyof M)[];
+
     /**
      * Default sort applied to this collection.
      * When setting this prop, entities will have a default order
@@ -473,6 +497,14 @@ export interface CollectionActionsProps<M extends Record<string, any> = any, USE
      */
     path: string;
 
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * Optional, and never derived by splitting `path` — a parent entity id may itself
+     * contain "/". Absent means "not known here", not "no slashes".
+     */
+    pathSegments?: string[];
+
     /**
      * Path of the last collection, like `addresses`
      */
@@ -725,6 +757,8 @@ export type EntityTableController<M extends Record<string, any> = any> = {
     dataLoadingError?: Error;
     filterValues?: FilterValues<Extract<keyof M, string>>;
     setFilterValues?: (filterValues: FilterValues<Extract<keyof M, string>>) => void;
+    allowedFilters?: (keyof M)[];
+    forcedFilters?: (keyof M)[];
     sortBy?: [Extract<keyof M, string>, "asc" | "desc"];
     setSortBy?: (sortBy?: [Extract<keyof M, string>, "asc" | "desc"]) => void;
     searchString?: string;

package/src/types/datasource.ts

@@ -8,6 +8,20 @@ import { FireCMSContext } from "./firecms_context";
  */
 export interface FetchEntityProps<M extends Record<string, any> = any> {
     path: string;
+    /**
+     * The path split at its real segment boundaries, e.g.
+     * `["nodes", "node/42", "edges"]`.
+     *
+     * `path` is a single flattened string, so a parent entity id containing "/" cannot be
+     * recovered from it — `"nodes/node/42/edges"` is indistinguishable from a three-level
+     * nesting. This is the unambiguous form: one array element per segment, entity ids
+     * kept whole however many slashes they contain.
+     *
+     * For any backend whose ids cannot contain "/" this is exactly `path.split("/")`, so
+     * delegates that do not care can keep using `path`. Delegates that do should prefer
+     * `pathSegments ?? path.split("/")`.
+     */
+    pathSegments?: string[];
     entityId: string;
     databaseId?: string;
     collection?: EntityCollection<M, any>
@@ -28,6 +42,20 @@ export type ListenEntityProps<M extends Record<string, any> = any> =
  */
 export interface FetchCollectionProps<M extends Record<string, any> = any> {
     path: string;
+    /**
+     * The path split at its real segment boundaries, e.g.
+     * `["nodes", "node/42", "edges"]`.
+     *
+     * `path` is a single flattened string, so a parent entity id containing "/" cannot be
+     * recovered from it — `"nodes/node/42/edges"` is indistinguishable from a three-level
+     * nesting. This is the unambiguous form: one array element per segment, entity ids
+     * kept whole however many slashes they contain.
+     *
+     * For any backend whose ids cannot contain "/" this is exactly `path.split("/")`, so
+     * delegates that do not care can keep using `path`. Delegates that do should prefer
+     * `pathSegments ?? path.split("/")`.
+     */
+    pathSegments?: string[];
     collection?: EntityCollection<M> | ResolvedEntityCollection<M>;
     filter?: FilterValues<Extract<keyof M, string>>,
     limit?: number;
@@ -52,6 +80,20 @@ export type ListenCollectionProps<M extends Record<string, any> = any> =
  */
 export interface SaveEntityProps<M extends Record<string, any> = any> {
     path: string;
+    /**
+     * The path split at its real segment boundaries, e.g.
+     * `["nodes", "node/42", "edges"]`.
+     *
+     * `path` is a single flattened string, so a parent entity id containing "/" cannot be
+     * recovered from it — `"nodes/node/42/edges"` is indistinguishable from a three-level
+     * nesting. This is the unambiguous form: one array element per segment, entity ids
+     * kept whole however many slashes they contain.
+     *
+     * For any backend whose ids cannot contain "/" this is exactly `path.split("/")`, so
+     * delegates that do not care can keep using `path`. Delegates that do should prefer
+     * `pathSegments ?? path.split("/")`.
+     */
+    pathSegments?: string[];
     values: Partial<EntityValues<M>>;
     entityId?: string; // can be empty for new entities
     previousValues?: Partial<EntityValues<M>>;
@@ -64,6 +106,11 @@ export interface SaveEntityProps<M extends Record<string, any> = any> {
  */
 export interface DeleteEntityProps<M extends Record<string, any> = any> {
     entity: Entity<M>;
+    /**
+     * `entity.path` split at its real segment boundaries, when the caller knows them.
+     * Never derived from `entity.path` — see `pathSegments` on FetchCollectionProps.
+     */
+    pathSegments?: string[];
     collection?: EntityCollection<M> | ResolvedEntityCollection<M>;
 }
 
@@ -203,13 +250,19 @@ export interface DataSource {
         name: string,
         value: any,
         entityId?: string,
-        collection?: EntityCollection
+        collection?: EntityCollection,
+        /**
+         * Appended last, and optional, so existing implementations and callers keep
+         * working unchanged — a function declaring fewer parameters stays assignable.
+         * See `pathSegments` on FetchCollectionProps.
+         */
+        pathSegments?: string[]
     ): Promise<boolean>;
 
     /**
      * Generate an id for a new entity
      */
-    generateEntityId(path: string, collection: EntityCollection): string;
+    generateEntityId(path: string, collection: EntityCollection, pathSegments?: string[]): string;
 
     /**
      * Count the number of entities in a collection
@@ -230,6 +283,10 @@ export interface DataSource {
     initTextSearch?: (props: {
         context: FireCMSContext,
         path: string,
+    /**
+     * `path` split at its real segment boundaries, when known. Never derived from `path`.
+     */
+    pathSegments?: string[],
         collection: EntityCollection,
         parentCollectionIds?: string[]
     }) => Promise<boolean>;
@@ -237,6 +294,8 @@ export interface DataSource {
 }
 
 export type FilterCombinationValidProps = {
+    /** `path` split at its real segment boundaries — see `pathSegments` on FetchCollectionProps. */
+    pathSegments?: string[];
     path: string;
     collection: EntityCollection<any>;
     filterValues: FilterValues<any>;
@@ -366,12 +425,12 @@ export interface DataSourceDelegate {
      * @param collection
      * @return `true` if there are no other fields besides the given entity
      */
-    checkUniqueField(path: string, name: string, value: any, entityId?: string, collection?: EntityCollection): Promise<boolean>;
+    checkUniqueField(path: string, name: string, value: any, entityId?: string, collection?: EntityCollection, pathSegments?: string[]): Promise<boolean>;
 
     /**
      * Generate an id for a new entity
      */
-    generateEntityId(path: string, collection?: EntityCollection): string;
+    generateEntityId(path: string, collection?: EntityCollection, pathSegments?: string[]): string;
 
     /**
      * Count the number of entities in a collection
@@ -398,6 +457,10 @@ export interface DataSourceDelegate {
     initTextSearch?: (props: {
         context: FireCMSContext,
         path: string,
+    /**
+     * `path` split at its real segment boundaries, when known. Never derived from `path`.
+     */
+    pathSegments?: string[],
         databaseId?: string,
         collection: EntityCollection,
         parentCollectionIds?: string[]

package/src/types/entities.ts

@@ -21,6 +21,17 @@ export interface Entity<M extends object = any> {
      */
     path: string;
 
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * `path` is a single flattened string, so a parent entity id containing "/" cannot be
+     * recovered from it. This keeps each segment whole.
+     *
+     * 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[];
+
     /**
      * Current values
      */
@@ -55,10 +66,22 @@ export class EntityReference {
      */
     readonly databaseId?: string;
 
-    constructor(id: string, path: string, databaseId?: string) {
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * `path` is a single flattened string, so a parent entity id containing "/" cannot be
+     * recovered from it. This keeps each segment whole.
+     *
+     * 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".
+     */
+    readonly pathSegments?: string[];
+
+    constructor(id: string, path: string, databaseId?: string, pathSegments?: string[]) {
         this.id = id;
         this.path = path;
         this.databaseId = databaseId;
+        this.pathSegments = pathSegments;
     }
 
     get pathWithId() {

package/src/types/entity_actions.tsx

@@ -65,6 +65,12 @@ export type EntityActionClickProps<M extends object, USER extends User = User> =
     context: FireCMSContext<USER>;
 
     fullPath?: string;
+    /**
+     * `fullPath` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`,
+     * when the caller knows them. Absent means "not known here" — never derived from
+     * `fullPath`, since a parent id may itself contain "/".
+     */
+    pathSegments?: string[];
     fullIdPath?: string;
     collection?: EntityCollection<M>;
 

package/src/types/entity_callbacks.ts

@@ -86,6 +86,14 @@ export interface EntityOnFetchProps<M extends Record<string, any> = any, USER ex
      */
     path: string;
 
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * Optional, and never derived by splitting `path` — a parent entity id may itself
+     * contain "/". Absent means "not known here", not "no slashes".
+     */
+    pathSegments?: string[];
+
     /**
      * Fetched entity
      */
@@ -133,6 +141,14 @@ export interface EntityOnSaveProps<M extends Record<string, any> = any, USER ext
      */
     path: string;
 
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * Optional, and never derived by splitting `path` — a parent entity id may itself
+     * contain "/". Absent means "not known here", not "no slashes".
+     */
+    pathSegments?: string[];
+
     /**
      * Full path where this entity is being saved, with alias resolved
      */
@@ -180,6 +196,14 @@ export interface EntityOnDeleteProps<M extends Record<string, any> = any, USER e
      */
     path: string;
 
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * Optional, and never derived by splitting `path` — a parent entity id may itself
+     * contain "/". Absent means "not known here", not "no slashes".
+     */
+    pathSegments?: string[];
+
     /**
      * Deleted entity id
      */