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

package/src/form/EntityForm.tsx

@@ -64,6 +64,8 @@ export type OnUpdateParams = {
     entity: Entity<any>,
     status: EntityStatus,
     path: string,
+    /** `path` split at its real segment boundaries, when known. Never derived from `path`. */
+    pathSegments?: string[],
     entityId?: string;
     selectedTab?: string;
     collection: EntityCollection<any>
@@ -276,6 +278,7 @@ export function EntityForm<M extends Record<string, any>>({
                 entityId: entityIdProp,
                 collection,
                 path,
+                pathSegments,
                 values: valuesToBeSaved
             });
     }, false, 2000);
@@ -497,6 +500,7 @@ export function EntityForm<M extends Record<string, any>>({
                 entity: updatedEntity,
                 status,
                 path,
+                pathSegments,
                 entityId: updatedEntity.id,
                 collection
             });
@@ -517,16 +521,20 @@ export function EntityForm<M extends Record<string, any>>({
         previousValues,
         entityId,
         collection,
-        path
+        path,
+        pathSegments
     }: {
         collection: EntityCollection<M>,
         path: string,
+        /** `path` split at its real segment boundaries, travelling with the `path` above. */
+        pathSegments?: string[],
         entityId: string | undefined,
         values: M,
         previousValues?: M,
     }) => {
         return saveEntityWithCallbacks({
             path,
+            pathSegments,
             entityId,
             values,
             previousValues,
@@ -544,6 +552,7 @@ export function EntityForm<M extends Record<string, any>>({
     type EntityFormSaveParams<M extends Record<string, any>> = {
         collection: ResolvedEntityCollection<M>,
         path: string,
+        pathSegments?: string[],
         entityId: string | undefined,
         values: EntityValues<M>,
         previousValues?: EntityValues<M>,
@@ -553,6 +562,7 @@ export function EntityForm<M extends Record<string, any>>({
     const onSaveEntityRequest = async ({
         collection,
         path,
+        pathSegments,
         entityId,
         values,
         previousValues,
@@ -566,6 +576,7 @@ export function EntityForm<M extends Record<string, any>>({
             return saveEntity({
                 collection,
                 path,
+                pathSegments,
                 entityId,
                 values,
                 previousValues
@@ -579,6 +590,7 @@ export function EntityForm<M extends Record<string, any>>({
         return onSaveEntityRequest({
             collection: resolvedCollection,
             path,
+            pathSegments,
             entityId,
             values,
             previousValues: entity?.values,
@@ -629,13 +641,14 @@ export function EntityForm<M extends Record<string, any>>({
     const plugins = customizationController.plugins;
 
     const actionsDisabled = disabled || formex.isSubmitting || (status === "existing" && !formex.dirty) || Boolean(disabledProp);
-    const parentCollectionIds = navigationController.getParentCollectionIds(path);
+    const parentCollectionIds = navigationController.getParentCollectionIds(path, pathSegments);
 
     if (plugins && collection) {
         const actionProps: PluginFormActionProps = {
             entityId,
             parentCollectionIds,
             path,
+            pathSegments,
             status,
             collection,
             context,
@@ -896,6 +909,7 @@ export function EntityForm<M extends Record<string, any>>({
     const dialogActions = <EntityFormActionsComponent
         collection={resolvedCollection}
         path={path}
+        pathSegments={pathSegments}
         fullPath={path}
         fullIdPath={fullIdPath}
         entity={entity}

package/src/form/EntityFormActions.tsx

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

package/src/hooks/data/delete.ts

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

package/src/hooks/data/save.ts

@@ -68,7 +68,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
 
     const customizationController = context.customizationController;
 
-    const resolvedPath = context.navigation.resolveIdsFrom(path);
+    const resolvedPath = context.navigation.resolveIdsFrom(path, pathSegments);
 
     const callbacks = collection.callbacks;
     if (callbacks?.onPreSave) {
@@ -84,6 +84,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
             updatedValues = await callbacks.onPreSave({
                 collection: resolvedCollection,
                 path,
+                pathSegments,
                 resolvedPath,
                 entityId,
                 values,
@@ -123,6 +124,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
                 callbacks.onSaveSuccess({
                     collection: resolvedCollection,
                     path,
+                    pathSegments,
                     resolvedPath,
                     entityId: entity.id,
                     values: updatedValues,
@@ -152,6 +154,7 @@ export async function saveEntityWithCallbacks<M extends Record<string, any>, USE
                 callbacks.onSaveFailure({
                     collection: resolvedCollection,
                     path,
+                    pathSegments,
                     resolvedPath,
                     entityId,
                     values: updatedValues,

package/src/hooks/data/useCollectionFetch.tsx

@@ -69,7 +69,7 @@ export interface CollectionFetchResult<M extends Record<string, any>> {
 export function useCollectionFetch<M extends Record<string, any>, USER extends User>(
     {
         path: inputPath,
-        pathSegments,
+        pathSegments: inputPathSegments,
         collection,
         filterValues,
         sortBy,
@@ -80,7 +80,13 @@ export function useCollectionFetch<M extends Record<string, any>, USER extends U
     const dataSource = useDataSource(collection);
     const navigationController = useNavigationController();
 
-    const path = navigationController.resolveIdsFrom(inputPath);
+    // Resolved together so the two representations always describe the same chain.
+    // Segments are resolved, never derived: only collection ids are swapped for their
+    // real paths, and entity ids are carried through whole (see useEntityFetch).
+    const pathSegments = inputPathSegments
+        ? (navigationController.resolveSegmentsFrom?.(inputPathSegments) ?? inputPathSegments)
+        : undefined;
+    const path = navigationController.resolveIdsFrom(inputPath, inputPathSegments);
 
     const sortByProperty = sortBy ? sortBy[0] : undefined;
     const currentSort = sortBy ? sortBy[1] : undefined;
@@ -109,6 +115,7 @@ export function useCollectionFetch<M extends Record<string, any>, USER extends U
                             collection.callbacks!.onFetch!({
                                 collection,
                                 path,
+                                pathSegments,
                                 entity,
                                 context
                             })));

package/src/hooks/data/useEntityFetch.tsx

@@ -11,7 +11,10 @@ export interface EntityFetchProps<M extends Record<string, any>, USER extends Us
     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.
+     * entity id containing "/" stays unambiguous.
+     *
+     * Optional, and never derived by splitting `path` — a guess would be wrong in exactly
+     * the case the field exists for. Absent means "not known here", not "no slashes".
      */
     pathSegments?: string[];
     entityId?: string;
@@ -54,11 +57,19 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
     const dataSource = useDataSource(collection);
     const navigationController = useNavigationController();
 
-    const path = navigationController.resolveIdsFrom(inputPath);
     // Never fabricate segments. If the caller did not thread them, pass undefined so a
     // delegate can tell "not provided" from a real answer — splitting `path` here would
     // produce a confidently wrong array for any id containing "/".
-    const pathSegments = inputPathSegments;
+    //
+    // When they were threaded, both representations are resolved from them together, so
+    // `path` cannot end up describing a different chain than `pathSegments`.
+    // `resolveSegmentsFrom` is optional on the controller: a host app may be supplying one
+    // built against an earlier version. Falling back to the segments as given is what
+    // happened before it existed — they are used unresolved, never invented.
+    const pathSegments = inputPathSegments
+        ? (navigationController.resolveSegmentsFrom?.(inputPathSegments) ?? inputPathSegments)
+        : undefined;
+    const path = navigationController.resolveIdsFrom(inputPath, inputPathSegments);
 
     const context: FireCMSContext<USER> = useFireCMSContext();
 
@@ -82,6 +93,7 @@ export function useEntityFetch<M extends Record<string, any>, USER extends User>
                     updatedEntity = await collection.callbacks.onFetch({
                         collection,
                         path,
+                        pathSegments,
                         entity: updatedEntity,
                         context
                     });

package/src/hooks/useBuildNavigationController.tsx

@@ -22,11 +22,14 @@ import {
 } from "../types";
 import {
     applyPermissionsFunctionIfEmpty,
+    collectionSegmentsFrom,
+    fullPathToCollectionSegments,
     getCollectionByPathOrId,
     mergeDeep,
     removeFunctions,
     removeInitialAndTrailingSlashes,
     resolveCollectionPathIds,
+    resolveCollectionPathSegments,
     resolvePermissions
 } from "../util";
 import { getParentReferencesFromPath } from "../util/parent_references_from_path";
@@ -405,13 +408,14 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
 
     const getCollection = useCallback((
         idOrPath: string,
-        includeUserOverride = false
+        includeUserOverride = false,
+        pathSegments?: string[]
     ): EC | undefined => {
         const collections = collectionsRef.current;
         if (!collections)
             return undefined;
 
-        const baseCollection = getCollectionByPathOrId(removeInitialAndTrailingSlashes(idOrPath), collections);
+        const baseCollection = getCollectionByPathOrId(removeInitialAndTrailingSlashes(idOrPath), collections, pathSegments);
 
         const userOverride = includeUserOverride ? userConfigPersistence?.getCollectionConfig(idOrPath) : undefined;
         let overriddenCollection = baseCollection;
@@ -505,23 +509,33 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
         throw Error("Expected path starting with " + fullCollectionPath);
     }, [fullCollectionPath]);
 
-    const resolveIdsFrom = useCallback((path: string): string => {
+    const resolveIdsFrom = useCallback((path: string, pathSegments?: string[]): string => {
         const collections = collectionsRef.current ?? [];
-        return resolveCollectionPathIds(path, collections);
+        return resolveCollectionPathIds(path, collections, pathSegments);
     }, []);
 
-    const getAllParentReferencesForPath = useCallback((path: string): EntityReference[] => {
+    const resolveSegmentsFrom = useCallback((pathSegments: string[]): string[] => {
+        const collections = collectionsRef.current ?? [];
+        return resolveCollectionPathSegments(pathSegments, collections);
+    }, []);
+
+    const getAllParentReferencesForPath = useCallback((path: string, pathSegments?: string[]): EntityReference[] => {
         const collections = collectionsRef.current ?? [];
         return getParentReferencesFromPath({
             path,
+            pathSegments,
             collections
         });
     }, []);
 
-    const getParentCollectionIds = useCallback((path: string): string[] => {
+    const getParentCollectionIds = useCallback((path: string, pathSegments?: string[]): string[] => {
 
-        const strings = path.split("/");
-        const oddPathSegments = strings.filter((_, i) => i % 2 === 0);
+        // Positional filtering only picks out the collection segments while no entity id
+        // contains "/"; with one, every following segment shifts. Given the real boundaries
+        // the same rule applies correctly; without them this is the historical reading.
+        const oddPathSegments = pathSegments
+            ? collectionSegmentsFrom(pathSegments)
+            : fullPathToCollectionSegments(path);
         oddPathSegments.pop();
 
         const result: string[][] = [];
@@ -567,6 +581,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
         urlPathToDataPath,
         buildUrlCollectionPath,
         resolveIdsFrom,
+        resolveSegmentsFrom,
         topLevelNavigation,
         refreshNavigation,
         getParentReferencesFromPath: getAllParentReferencesForPath,

package/src/hooks/useResolvedNavigationFrom.tsx

@@ -80,7 +80,7 @@ export function resolveNavigationFrom<M extends Record<string, any>, USER extend
             if (entry.type === "collection") {
                 return Promise.resolve(entry);
             } else if (entry.type === "entity") {
-                const collection = navigation.getCollection(entry.path);
+                const collection = navigation.getCollection(entry.path, false, entry.pathSegments);
                 if (!collection) {
                     throw Error(`No collection defined in the navigation for the entity with path ${entry.path}`);
                 }

package/src/internal/useBuildDataSource.ts

@@ -112,7 +112,7 @@ export function useBuildDataSource({
                 }: ListenCollectionProps<M>
             ): () => void => {
 
-                const collection = collectionProp ?? navigationController.getCollection(path);
+                const collection = collectionProp ?? navigationController.getCollection(path, false, pathSegments);
                 const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
 
                 if (!usedDelegate.listenCollection)
@@ -213,7 +213,7 @@ export function useBuildDataSource({
                 status
             }: SaveEntityProps<M>): Promise<Entity<M>> => {
 
-            const collection = collectionProp ?? navigationController.getCollection(path);
+            const collection = collectionProp ?? navigationController.getCollection(path, false, pathSegments);
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
 
             const resolvedCollection = collection
@@ -286,9 +286,15 @@ export function useBuildDataSource({
                 values: finalValues,
                 status
             }).then((res) => {
+                // Keep everything the delegate resolved — `databaseId`, and `pathSegments` in
+                // particular — so a just-saved entity is as resolvable as a fetched one.
+                // Only the values are re-mapped back to the CMS model.
                 return {
-                    id: res.id,
-                    path: res.path,
+                    ...res,
+                    // A delegate that predates `pathSegments` returns none; the segments we
+                    // just saved with describe exactly this entity's collection, so they are
+                    // the authoritative answer rather than a guess.
+                    pathSegments: res.pathSegments ?? pathSegments,
                     values: usedDelegate.delegateToCMSModel(finalValues)
                 } as Entity<M>;
             });
@@ -343,6 +349,8 @@ export function useBuildDataSource({
             return usedDelegate.generateEntityId(path, collection, pathSegments);
         }, [delegate.generateEntityId]),
 
+        // Typed with the declared props rather than an inline duplicate: the duplicate is
+        // free to drift from the interface, and a field it forgets is dropped in silence.
         countEntities: delegate.countEntities ? async ({
             path,
             pathSegments,
@@ -350,14 +358,7 @@ export function useBuildDataSource({
             filter,
             order,
             orderBy
-        }: {
-            path: string,
-            pathSegments?: string[],
-            collection: EntityCollection<any>,
-            filter?: FilterValues<Extract<keyof any, string>>,
-            orderBy?: string,
-            order?: "desc" | "asc",
-        }): Promise<number> => {
+        }: FetchCollectionProps<any>): Promise<number> => {
             const usedDelegate = collection?.overrides?.dataSourceDelegate ?? delegate;
             return usedDelegate.countEntities!({
                 path,

package/src/preview/components/ReferencePreview.tsx

@@ -53,7 +53,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,6 +99,9 @@ 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

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}>
@@ -114,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}>
@@ -186,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) {
@@ -250,14 +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={isNew ? lastCollectionEntry!.pathSegments : lastEntityEntry!.pathSegments}
+                pathSegments={pathSegments}
                 collection={collection}
                 layout={"full_screen"}
                 path={collectionPath}

package/src/types/collections.ts

@@ -497,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

@@ -283,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>;
@@ -453,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/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