@firecms/core 3.4.0-canary.f6a889a → 3.4.0

package/src/locales/es.ts

@@ -397,6 +397,7 @@ export const es: FireCMSTranslations = {
     download: "Descargar",
     large_number_of_documents: "Esta colección posee un gran número de documentos ({{count}}).",
     include_undefined_values: "Incluir valores omitidos (undefined)",
+    export_apply_filter_sort: "Exportar solo los resultados que coinciden con el filtro/orden actual",
     submit: "Enviar",
 
     no_filterable_properties: "No hay propiedades filtrables disponibles",
@@ -598,6 +599,10 @@ export const es: FireCMSTranslations = {
     order_property_not_found: "La propiedad \"{{property}}\" no existe o no es una propiedad numérica. Selecciona una propiedad válida o borra la selección.",
     no_number_properties: "No se encontraron propiedades numéricas. Agrega una propiedad numérica para habilitar el ordenamiento.",
     order_property_description: "Selecciona una propiedad numérica para mantener el orden de los elementos",
+    image_property: "Propiedad de imagen",
+    image_property_not_found: "La propiedad \"{{property}}\" no existe o no es una propiedad de imagen. Selecciona una propiedad válida o borra la selección.",
+    no_image_properties: "No se encontraron propiedades de imagen. Agrega una propiedad de almacenamiento o URL de imagen para usarla como miniatura.",
+    image_property_description: "Selecciona la propiedad usada como miniatura en las vistas de Tarjetas y Kanban. Si no se establece, se usará automáticamente la primera propiedad de imagen que coincida.",
     display_settings: "Configuración de visualización",
     default_row_size: "Tamaño de fila predeterminado",
     side_dialog_width: "Ancho del diálogo lateral",

package/src/locales/fr.ts

@@ -389,6 +389,7 @@ export const fr: FireCMSTranslations = {
     download: "Télécharger",
     large_number_of_documents: "Cette collection contient un grand nombre de documents ({{count}}).",
     include_undefined_values: "Inclure les valeurs non définies",
+    export_apply_filter_sort: "N'exporter que les résultats correspondant au filtre/tri actuel",
     submit: "Soumettre",
 
     no_filterable_properties: "Aucune propriété filtrable disponible",
@@ -586,6 +587,10 @@ export const fr: FireCMSTranslations = {
     order_property_not_found: "La propriété \"{{property}}\" n'existe pas ou n'est pas une propriété numérique. Veuillez sélectionner une propriété valide ou effacer la sélection.",
     no_number_properties: "Aucune propriété numérique trouvée. Ajoutez une propriété numérique pour activer le tri.",
     order_property_description: "Sélectionnez une propriété numérique pour conserver l'ordre des éléments",
+    image_property: "Propriété d'image",
+    image_property_not_found: "La propriété \"{{property}}\" n'existe pas ou n'est pas une propriété d'image. Veuillez sélectionner une propriété valide ou effacer la sélection.",
+    no_image_properties: "Aucune propriété d'image trouvée. Ajoutez une propriété de stockage ou d'URL d'image à utiliser comme miniature.",
+    image_property_description: "Sélectionnez la propriété utilisée comme miniature dans les vues Cartes et Kanban. Si elle n'est pas définie, la première propriété d'image correspondante sera utilisée automatiquement.",
     display_settings: "Paramètres d'affichage",
     default_row_size: "Taille de ligne par défaut",
     side_dialog_width: "Largeur du dialogue latéral",

package/src/locales/hi.ts

@@ -389,6 +389,7 @@ export const hi: FireCMSTranslations = {
     download: "डाउनलोड",
     large_number_of_documents: "इस संग्रह में बड़ी संख्या में दस्तावेज़ हैं ({{count}})।",
     include_undefined_values: "अपरिभाषित (undefined) मान शामिल करें",
+    export_apply_filter_sort: "केवल वर्तमान फ़िल्टर/सॉर्ट से मेल खाने वाले परिणाम निर्यात करें",
     submit: "सबमिट करें",
 
     no_filterable_properties: "कोई फ़िल्टर करने योग्य गुण उपलब्ध नहीं हैं",
@@ -586,6 +587,10 @@ export const hi: FireCMSTranslations = {
     order_property_not_found: "प्रॉपर्टी \"{{property}}\" मौजूद नहीं है या एक संख्या प्रॉपर्टी नहीं है। कृपया एक वैध प्रॉपर्टी चुनें या चयन साफ़ करें।",
     no_number_properties: "कोई संख्या प्रॉपर्टी नहीं मिली। क्रम सक्षम करने के लिए एक संख्या प्रॉपर्टी जोड़ें।",
     order_property_description: "आइटम का क्रम बनाए रखने के लिए एक संख्या प्रॉपर्टी चुनें",
+    image_property: "इमेज प्रॉपर्टी",
+    image_property_not_found: "प्रॉपर्टी \"{{property}}\" मौजूद नहीं है या एक इमेज प्रॉपर्टी नहीं है। कृपया एक वैध प्रॉपर्टी चुनें या चयन साफ़ करें।",
+    no_image_properties: "कोई इमेज प्रॉपर्टी नहीं मिली। थंबनेल के रूप में उपयोग करने के लिए एक स्टोरेज या URL इमेज प्रॉपर्टी जोड़ें।",
+    image_property_description: "कार्ड्स और कानबन व्यू मोड में थंबनेल इमेज के रूप में उपयोग की जाने वाली प्रॉपर्टी चुनें। यदि सेट नहीं किया गया है, तो पहली मिलान वाली इमेज प्रॉपर्टी स्वचालित रूप से उपयोग की जाएगी।",
     display_settings: "प्रदर्शन सेटिंग्स",
     default_row_size: "डिफ़ॉल्ट पंक्ति आकार",
     side_dialog_width: "साइड डायलॉग चौड़ाई",

package/src/locales/it.ts

@@ -389,6 +389,7 @@ export const it: FireCMSTranslations = {
     download: "Scarica",
     large_number_of_documents: "Questa collezione contiene un numero elevato di documenti ({{count}})",
     include_undefined_values: "Includi valori non definiti",
+    export_apply_filter_sort: "Esporta solo i risultati che corrispondono al filtro/ordinamento attuale",
     submit: "Invia",
 
     no_filterable_properties: "Nessuna proprietà filtrabile disponibile",
@@ -586,6 +587,10 @@ export const it: FireCMSTranslations = {
     order_property_not_found: "La proprietà \"{{property}}\" non esiste o non è una proprietà numerica. Seleziona una proprietà valida o cancella la selezione.",
     no_number_properties: "Nessuna proprietà numerica trovata. Aggiungi una proprietà numerica per abilitare l'ordinamento.",
     order_property_description: "Seleziona una proprietà numerica per mantenere l'ordine degli elementi",
+    image_property: "Proprietà immagine",
+    image_property_not_found: "La proprietà \"{{property}}\" non esiste o non è una proprietà immagine. Seleziona una proprietà valida o cancella la selezione.",
+    no_image_properties: "Nessuna proprietà immagine trovata. Aggiungi una proprietà di archiviazione o URL immagine da usare come miniatura.",
+    image_property_description: "Seleziona la proprietà utilizzata come miniatura nelle viste Schede e Kanban. Se non impostata, verrà utilizzata automaticamente la prima proprietà immagine corrispondente.",
     display_settings: "Impostazioni di visualizzazione",
     default_row_size: "Dimensione riga predefinita",
     side_dialog_width: "Larghezza del dialogo laterale",

package/src/locales/pl.ts

@@ -389,6 +389,7 @@ export const pl: FireCMSTranslations = {
     download: "Pobierz",
     large_number_of_documents: "Ta kolekcja zawiera dużą liczbę dokumentów ({{count}}).",
     include_undefined_values: "Uwzględnij niezdefiniowane wartości",
+    export_apply_filter_sort: "Eksportuj tylko wyniki zgodne z aktualnym filtrem/sortowaniem",
     submit: "Wyślij",
 
     no_filterable_properties: "Brak dostępnych właściwości do filtrowania",
@@ -590,6 +591,10 @@ export const pl: FireCMSTranslations = {
     order_property_not_found: "Właściwość „{{property}}” nie istnieje lub nie jest właściwością liczbową. Wybierz prawidłową właściwość lub wyczyść wybór.",
     no_number_properties: "Nie znaleziono właściwości liczbowych. Dodaj właściwość liczbową, aby włączyć sortowanie.",
     order_property_description: "Wybierz właściwość liczbową, aby zachować kolejność elementów",
+    image_property: "Właściwość obrazu",
+    image_property_not_found: "Właściwość „{{property}}” nie istnieje lub nie jest właściwością obrazu. Wybierz prawidłową właściwość lub wyczyść wybór.",
+    no_image_properties: "Nie znaleziono właściwości obrazu. Dodaj właściwość przechowywania lub adresu URL obrazu, aby użyć jej jako miniatury.",
+    image_property_description: "Wybierz właściwość używaną jako miniatura w widokach Karty i Kanban. Jeśli nie zostanie ustawiona, automatycznie zostanie użyta pierwsza pasująca właściwość obrazu.",
     display_settings: "Ustawienia wyświetlania",
     default_row_size: "Domyślny rozmiar wiersza",
     side_dialog_width: "Szerokość okna bocznego",

package/src/locales/pt.ts

@@ -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/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/routes/FireCMSRoute.tsx

@@ -90,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}>
@@ -99,6 +99,7 @@ export function FireCMSRoute() {
                 isSubCollection={false}
                 parentCollectionIds={[]}
                 fullPath={collection.path}
+                pathSegments={navigationEntries[0].pathSegments}
                 fullIdPath={collection.id}
                 updateUrl={true}
                 {...collection}
@@ -113,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}>
@@ -123,6 +124,7 @@ export function FireCMSRoute() {
                     isSubCollection={false}
                     parentCollectionIds={[]}
                     fullPath={collection.path}
+                    pathSegments={firstEntry.pathSegments}
                     updateUrl={true}
                     {...collection}
                     Actions={toArray(collection.Actions)} />
@@ -184,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) {
@@ -248,13 +252,17 @@ function EntityFullScreenRoute({
     // `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);
-    const collectionPath = navigation.resolveIdsFrom(isNew ? lastCollectionEntry!.path : lastEntityEntry!.path);
+    // 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}

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`.
@@ -489,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`
      */

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
      */

package/src/types/navigation.ts

@@ -57,8 +57,12 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     /**
      * Get the collection configuration for a given path.
      * The collection is resolved from the given path or alias.
+     *
+     * Pass `pathSegments` when you have them: without them the path is split on "/" and
+     * asserted to have an odd number of parts, which a chain containing a slash-bearing
+     * entity id fails — it throws instead of resolving.
      */
-    getCollection: (pathOrId: string, includeUserOverride?: boolean) => EC | undefined;
+    getCollection: (pathOrId: string, includeUserOverride?: boolean, pathSegments?: string[]) => EC | undefined;
 
     /**
      * Get the top level collection configuration for a given id
@@ -118,9 +122,30 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     /**
      * Turn a path with collection ids into a resolved path.
      * The ids (typically used in urls) will be replaced with relative paths (typically used in database paths)
+     *
+     * Pass `pathSegments` whenever you have them. Without them this has to find the entity
+     * ids inside the flattened string by reading up to the next "/", which is wrong for any
+     * id that contains one — the chain then shifts by a segment and resolution fails.
+     *
      * @param pathWithAliases
+     * @param pathSegments `pathWithAliases` split at its real segment boundaries, if known
      */
-    resolveIdsFrom: (pathWithAliases: string) => string;
+    resolveIdsFrom: (pathWithAliases: string, pathSegments?: string[]) => string;
+
+    /**
+     * The segment-wise counterpart of {@link resolveIdsFrom}: replaces collection ids with
+     * their real paths while carrying every entity id through whole, slashes included.
+     *
+     * Idempotent — segments that are already resolved pass through unchanged.
+     *
+     * Optional so that a `navigationController` built against an earlier version keeps
+     * working: callers fall back to using the segments as given, which is what happened
+     * before this method existed. Controllers built by `useBuildNavigationController`
+     * always provide it.
+     *
+     * @param pathSegments
+     */
+    resolveSegmentsFrom?: (pathSegments: string[]) => string[];
 
     /**
      * Call this method to recalculate the navigation
@@ -128,16 +153,21 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     refreshNavigation: () => void;
 
     /**
-     * Retrieve all the related parent references for a given path
+     * Retrieve all the related parent references for a given path.
+     *
+     * `path` is expected escaped, as it comes from the URL. Pass `pathSegments` when the
+     * path at hand is a raw datasource path, whose ids may contain a bare "/".
+     *
      * @param path
+     * @param pathSegments `path` split at its real segment boundaries, with raw ids
      */
-    getParentReferencesFromPath: (path: string) => EntityReference[];
+    getParentReferencesFromPath: (path: string, pathSegments?: string[]) => EntityReference[];
 
     /**
      * Retrieve all the related parent collection ids for a given path
      * @param path
      */
-    getParentCollectionIds: (path: string) => string[];
+    getParentCollectionIds: (path: string, pathSegments?: string[]) => string[];
 
     /**
      * Resolve paths from a list of ids