@firecms/core 3.4.0-canary.63041d0 → 3.4.0-canary.9408c41

package/src/util/date_fns_locales.ts

@@ -0,0 +1,168 @@
+import { useEffect, useReducer } from "react";
+import type { Locale as DateFnsLocale } from "date-fns";
+import { Locale } from "../types";
+
+/**
+ * On-demand loading of date-fns locales.
+ *
+ * `import * as locales from "date-fns/locale"` pulls in every locale date-fns
+ * ships — 625KB of parsed JavaScript, loaded on every single page view, to
+ * support a `locale` setting that is unset for almost every project. Worse, it
+ * sat on the critical path: `@firecms/core` imported it statically, so the
+ * browser could not render anything until it had come down.
+ *
+ * Each locale now has its own dynamic import, so exactly one small chunk is
+ * fetched, and only when a project actually configures a locale. Projects that
+ * do not configure one (the default) pay nothing at all.
+ *
+ * The map is written out rather than built from a template literal because Vite
+ * and webpack both need the specifier to be statically analysable to emit the
+ * chunks.
+ */
+const loaders: Partial<Record<Locale, () => Promise<DateFnsLocale>>> = {
+    af: () => import("date-fns/locale/af").then(m => m.af),
+    ar: () => import("date-fns/locale/ar").then(m => m.ar),
+    arDZ: () => import("date-fns/locale/ar-DZ").then(m => m.arDZ),
+    arMA: () => import("date-fns/locale/ar-MA").then(m => m.arMA),
+    arSA: () => import("date-fns/locale/ar-SA").then(m => m.arSA),
+    az: () => import("date-fns/locale/az").then(m => m.az),
+    be: () => import("date-fns/locale/be").then(m => m.be),
+    bg: () => import("date-fns/locale/bg").then(m => m.bg),
+    bn: () => import("date-fns/locale/bn").then(m => m.bn),
+    ca: () => import("date-fns/locale/ca").then(m => m.ca),
+    cs: () => import("date-fns/locale/cs").then(m => m.cs),
+    cy: () => import("date-fns/locale/cy").then(m => m.cy),
+    da: () => import("date-fns/locale/da").then(m => m.da),
+    de: () => import("date-fns/locale/de").then(m => m.de),
+    el: () => import("date-fns/locale/el").then(m => m.el),
+    enAU: () => import("date-fns/locale/en-AU").then(m => m.enAU),
+    enCA: () => import("date-fns/locale/en-CA").then(m => m.enCA),
+    enGB: () => import("date-fns/locale/en-GB").then(m => m.enGB),
+    enIN: () => import("date-fns/locale/en-IN").then(m => m.enIN),
+    enNZ: () => import("date-fns/locale/en-NZ").then(m => m.enNZ),
+    enUS: () => import("date-fns/locale/en-US").then(m => m.enUS),
+    eo: () => import("date-fns/locale/eo").then(m => m.eo),
+    es: () => import("date-fns/locale/es").then(m => m.es),
+    et: () => import("date-fns/locale/et").then(m => m.et),
+    eu: () => import("date-fns/locale/eu").then(m => m.eu),
+    faIR: () => import("date-fns/locale/fa-IR").then(m => m.faIR),
+    fi: () => import("date-fns/locale/fi").then(m => m.fi),
+    fr: () => import("date-fns/locale/fr").then(m => m.fr),
+    frCA: () => import("date-fns/locale/fr-CA").then(m => m.frCA),
+    frCH: () => import("date-fns/locale/fr-CH").then(m => m.frCH),
+    gd: () => import("date-fns/locale/gd").then(m => m.gd),
+    gl: () => import("date-fns/locale/gl").then(m => m.gl),
+    gu: () => import("date-fns/locale/gu").then(m => m.gu),
+    he: () => import("date-fns/locale/he").then(m => m.he),
+    hi: () => import("date-fns/locale/hi").then(m => m.hi),
+    hr: () => import("date-fns/locale/hr").then(m => m.hr),
+    hu: () => import("date-fns/locale/hu").then(m => m.hu),
+    hy: () => import("date-fns/locale/hy").then(m => m.hy),
+    id: () => import("date-fns/locale/id").then(m => m.id),
+    is: () => import("date-fns/locale/is").then(m => m.is),
+    it: () => import("date-fns/locale/it").then(m => m.it),
+    ja: () => import("date-fns/locale/ja").then(m => m.ja),
+    ka: () => import("date-fns/locale/ka").then(m => m.ka),
+    kk: () => import("date-fns/locale/kk").then(m => m.kk),
+    kn: () => import("date-fns/locale/kn").then(m => m.kn),
+    ko: () => import("date-fns/locale/ko").then(m => m.ko),
+    lb: () => import("date-fns/locale/lb").then(m => m.lb),
+    lt: () => import("date-fns/locale/lt").then(m => m.lt),
+    lv: () => import("date-fns/locale/lv").then(m => m.lv),
+    mk: () => import("date-fns/locale/mk").then(m => m.mk),
+    ms: () => import("date-fns/locale/ms").then(m => m.ms),
+    mt: () => import("date-fns/locale/mt").then(m => m.mt),
+    nb: () => import("date-fns/locale/nb").then(m => m.nb),
+    nl: () => import("date-fns/locale/nl").then(m => m.nl),
+    nlBE: () => import("date-fns/locale/nl-BE").then(m => m.nlBE),
+    nn: () => import("date-fns/locale/nn").then(m => m.nn),
+    pl: () => import("date-fns/locale/pl").then(m => m.pl),
+    pt: () => import("date-fns/locale/pt").then(m => m.pt),
+    ptBR: () => import("date-fns/locale/pt-BR").then(m => m.ptBR),
+    ro: () => import("date-fns/locale/ro").then(m => m.ro),
+    ru: () => import("date-fns/locale/ru").then(m => m.ru),
+    sk: () => import("date-fns/locale/sk").then(m => m.sk),
+    sl: () => import("date-fns/locale/sl").then(m => m.sl),
+    sr: () => import("date-fns/locale/sr").then(m => m.sr),
+    srLatn: () => import("date-fns/locale/sr-Latn").then(m => m.srLatn),
+    sv: () => import("date-fns/locale/sv").then(m => m.sv),
+    ta: () => import("date-fns/locale/ta").then(m => m.ta),
+    te: () => import("date-fns/locale/te").then(m => m.te),
+    th: () => import("date-fns/locale/th").then(m => m.th),
+    tr: () => import("date-fns/locale/tr").then(m => m.tr),
+    ug: () => import("date-fns/locale/ug").then(m => m.ug),
+    uk: () => import("date-fns/locale/uk").then(m => m.uk),
+    uz: () => import("date-fns/locale/uz").then(m => m.uz),
+    vi: () => import("date-fns/locale/vi").then(m => m.vi),
+    zhCN: () => import("date-fns/locale/zh-CN").then(m => m.zhCN),
+    zhTW: () => import("date-fns/locale/zh-TW").then(m => m.zhTW),
+};
+
+const cache = new Map<Locale, DateFnsLocale>();
+const inFlight = new Map<Locale, Promise<DateFnsLocale | undefined>>();
+
+/**
+ * Load a date-fns locale, resolving from cache when it is already in memory.
+ * Concurrent callers for the same locale share one request.
+ */
+export function loadDateFnsLocale(locale: Locale): Promise<DateFnsLocale | undefined> {
+    const cached = cache.get(locale);
+    if (cached) {
+        return Promise.resolve(cached);
+    }
+    const pending = inFlight.get(locale);
+    if (pending) {
+        return pending;
+    }
+    const loader = loaders[locale];
+    if (!loader) {
+        // An unknown key behaves as it did when the whole barrel was imported:
+        // the lookup missed and date-fns fell back to its built-in English.
+        return Promise.resolve(undefined);
+    }
+    const promise = loader()
+        .then((loaded) => {
+            cache.set(locale, loaded);
+            return loaded;
+        })
+        .catch(() => undefined)
+        .finally(() => {
+            inFlight.delete(locale);
+        });
+    inFlight.set(locale, promise);
+    return promise;
+}
+
+/** The locale if it is already loaded, otherwise undefined. Never suspends. */
+export function getLoadedDateFnsLocale(locale?: Locale): DateFnsLocale | undefined {
+    return locale ? cache.get(locale) : undefined;
+}
+
+/**
+ * The date-fns locale for `locale`, loading it in the background on first use.
+ *
+ * Returns undefined until the chunk arrives, which formats the first paint with
+ * date-fns' built-in English and then re-renders. That is a change only for
+ * projects that set a locale, and only for the few hundred milliseconds before
+ * the chunk lands — in exchange for every project no longer waiting on 625KB.
+ */
+export function useDateFnsLocale(locale?: Locale): DateFnsLocale | undefined {
+    const [, forceUpdate] = useReducer((count: number) => count + 1, 0);
+
+    useEffect(() => {
+        if (!locale || cache.has(locale)) {
+            return;
+        }
+        let active = true;
+        loadDateFnsLocale(locale).then((loaded) => {
+            if (active && loaded) {
+                forceUpdate();
+            }
+        });
+        return () => {
+            active = false;
+        };
+    }, [locale]);
+
+    return locale ? cache.get(locale) : undefined;
+}

package/src/util/entities.ts

@@ -142,7 +142,9 @@ export function getReferenceFrom<M extends Record<string, any>>(entity: Entity<M
     if (!entity) {
         throw new Error("getReferenceFrom: entity is null or undefined");
     }
-    return new EntityReference(entity.id, entity.path, entity.databaseId);
+    // Carry the segments the entity was loaded with, so a reference to an entity under a
+    // slash-bearing parent stays resolvable. Undefined when the entity does not have them.
+    return new EntityReference(entity.id, entity.path, entity.databaseId, entity.pathSegments);
 }
 
 export function traverseValuesProperties<M extends Record<string, any>>(

package/src/util/entity_cache.ts

@@ -1,5 +1,23 @@
 import { EntityReference, GeoPoint, Vector } from "../types";
 import { isObject, isPlainObject } from "./objects";
+import { encodeEntityId } from "./navigation_utils";
+
+/**
+ * Key identifying one entity in a cache.
+ *
+ * The id is escaped so that a `(path, entityId)` pair maps to exactly one key. Without it
+ * `("a", "b/c")` and `("a/b", "c")` both flatten to `"a/b/c"`, and one entity's cached
+ * values are served for the other.
+ *
+ * `encodeEntityId` is the identity for any id without "/", "?", "#" or "%", so this changes
+ * no key in an app whose ids cannot contain them.
+ */
+export function entityCacheKey(path: string | undefined, entityId: string | undefined): string {
+    // Either part may be undefined at a call site that used to build the key by string
+    // concatenation; both are stringified exactly as `path + "/" + entityId` did, so such a
+    // caller keeps the key it had.
+    return `${path}/${entityId === undefined ? entityId : encodeEntityId(entityId)}`;
+}
 
 // Define a unique prefix for entity keys in localStorage to avoid key collisions
 const LOCAL_STORAGE_PREFIX = "entity_cache::";

package/src/util/index.ts

@@ -28,3 +28,4 @@ export * from "./storage";
 export * from "./callbacks";
 export * from "./conditions";
 export * from "./lazy_eager";
+export * from "./date_fns_locales";

package/src/util/lazy_eager.tsx

@@ -1,9 +1,35 @@
 import React from "react";
 
 /**
- * Returns a React.lazy component that is also preloaded immediately using
- * requestIdleCallback or setTimeout.
- * This ensures that chunks are split, but fetched in the background before they are actually needed.
+ * Prefetch after the page has loaded, never during it.
+ *
+ * An idle callback scheduled at module evaluation time fires in the gaps between
+ * the tasks of the initial load — which is exactly when the critical chunks are
+ * still in flight. With a dozen route components each queueing one, the
+ * background prefetch was competing with the render path for connections and
+ * bandwidth. Waiting for the load event costs the prefetch nothing that matters:
+ * it exists to be ready before a navigation, not before first paint.
+ */
+function schedulePrefetch(load: () => void) {
+    const whenIdle = () => {
+        if ("requestIdleCallback" in window) {
+            (window as any).requestIdleCallback(load);
+        } else {
+            setTimeout(load, 500);
+        }
+    };
+
+    if (document.readyState === "complete") {
+        whenIdle();
+    } else {
+        window.addEventListener("load", whenIdle, { once: true });
+    }
+}
+
+/**
+ * Returns a React.lazy component that is also preloaded in the background, once
+ * the page has finished loading.
+ * This ensures that chunks are split, but fetched before they are actually needed.
  */
 export function lazyEager<T extends React.ComponentType<any>>(
     factory: () => Promise<any>,
@@ -22,11 +48,7 @@ export function lazyEager<T extends React.ComponentType<any>>(
     };
 
     if (typeof window !== "undefined") {
-        if ("requestIdleCallback" in window) {
-            (window as any).requestIdleCallback(load);
-        } else {
-            setTimeout(load, 500);
-        }
+        schedulePrefetch(load);
     }
 
     return React.lazy(load);

package/src/util/navigation_from_path.ts

@@ -147,7 +147,12 @@ export function getNavigationEntriesFromPath(props: {
                             path: newPath,
                             collections: collection.subcollections,
                             currentFullPath: fullPath,
-                            currentFullIdPath: fullIdPath,
+                            // The entity id is a hop in the id chain exactly as it is in the
+                            // other two. Without it a nested `fullIdPath` was
+                            // "products/locales" rather than "products/pid/locales", so any
+                            // URL built from it pointed at a collection that does not exist.
+                            // Escaped, because `fullIdPath` is URL-facing.
+                            currentFullIdPath: fullIdPath + "/" + encodedEntityId,
                             currentFullUrlPath: fullUrlPath,
                             currentPathSegments: entitySegments,
                             contextEntityViews: props.contextEntityViews

package/src/util/navigation_utils.ts

@@ -56,6 +56,30 @@ export function decodeEntityId(encodedEntityId: string): string {
         .replaceAll("%25", "%");
 }
 
+/**
+ * Segments of a subcollection sitting under the entity `entityId` of `parentPathSegments`.
+ *
+ * The parent entity id is kept whole however many slashes it contains, while the
+ * subcollection's own configured path is spread — a collection path never contains an
+ * entity id, so splitting that one is unambiguous.
+ *
+ * So `["test"] + "test/test" + "accommodation"` yields three segments,
+ * `["test", "test/test", "accommodation"]`, where splitting the flattened path
+ * `"test/test/test/accommodation"` would wrongly yield four.
+ *
+ * Returns undefined when the parent segments are unknown: the parent chain cannot be
+ * recovered from a flattened path, so there is nothing honest to build on.
+ *
+ * @group Hooks and utilities
+ */
+export function buildSubcollectionPathSegments(parentPathSegments: string[] | undefined,
+                                               entityId: string | undefined,
+                                               subcollectionPath: string): string[] | undefined {
+    if (!parentPathSegments || !entityId) return undefined;
+    const ownSegments = removeInitialAndTrailingSlashes(subcollectionPath).split("/");
+    return [...parentPathSegments, entityId, ...ownSegments];
+}
+
 export function getLastSegment(path: string) {
     const cleanPath = removeInitialAndTrailingSlashes(path);
     if (cleanPath.includes("/")) {
@@ -65,7 +89,171 @@ export function getLastSegment(path: string) {
     return cleanPath;
 }
 
-export function resolveCollectionPathIds(path: string, allCollections: EntityCollection[]): string {
+/**
+ * The outcome of walking a segment chain against a collection tree.
+ * @group Hooks and utilities
+ */
+export type PathSegmentsWalkStep = {
+    collection: EntityCollection;
+    /** Resolved path of this collection, e.g. `"products/pid/locales"`. */
+    collectionPath: string;
+    /** `collectionPath` split at its real segment boundaries. */
+    collectionSegments: string[];
+    /** The entity addressed inside it, when the chain continues past the collection. */
+    entityId?: string;
+};
+
+export type PathSegmentsWalk = {
+    /** Segments with every collection id replaced by the collection's real `path`. */
+    resolved: string[];
+    /** The collection the chain ends in, if the whole chain matched. */
+    collection?: EntityCollection;
+    /** One entry per collection level traversed, outermost first. */
+    steps: PathSegmentsWalkStep[];
+    /** The first segment that could not be matched, if the walk stopped early. */
+    unmatched?: string;
+};
+
+/**
+ * Walk a segment chain against a collection tree, matching a collection by either its
+ * `path` or its `id` and treating exactly one segment as each entity id.
+ *
+ * This is the primitive the string-based helpers cannot have: working on the flattened
+ * path they must *guess* where an entity id ends by reading up to the next "/", which is
+ * wrong for any id that contains one. Here the boundaries are given.
+ *
+ * Stops at the first segment it cannot match and reports it, rather than throwing.
+ *
+ * @group Hooks and utilities
+ */
+export function walkPathSegments(pathSegments: string[], allCollections: EntityCollection[]): PathSegmentsWalk {
+
+    const resolved: string[] = [];
+    const steps: PathSegmentsWalkStep[] = [];
+    let currentCollections: EntityCollection[] | undefined = allCollections;
+    let index = 0;
+
+    while (index < pathSegments.length) {
+
+        const remaining = pathSegments.slice(index);
+
+        if (!currentCollections || currentCollections.length === 0) {
+            resolved.push(...remaining);
+            return {
+                resolved,
+                steps,
+                unmatched: remaining[0]
+            };
+        }
+
+        // A collection's own `path` may span several segments ("users/uid/experiences"), so
+        // candidates are matched segment by segment and the longest match wins.
+        let match: { collection: EntityCollection, length: number } | undefined;
+        for (const collection of currentCollections) {
+            for (const candidate of [collection.path, collection.id]) {
+                if (!candidate) continue;
+                const parts = removeInitialAndTrailingSlashes(candidate).split("/");
+                if (parts.length > remaining.length) continue;
+                if (parts.some((part, i) => part !== remaining[i])) continue;
+                if (!match || parts.length > match.length) match = { collection, length: parts.length };
+            }
+        }
+
+        if (!match) {
+            resolved.push(...remaining);
+            return {
+                resolved,
+                steps,
+                unmatched: remaining[0]
+            };
+        }
+
+        resolved.push(...removeInitialAndTrailingSlashes(match.collection.path).split("/"));
+        index += match.length;
+
+        const step: PathSegmentsWalkStep = {
+            collection: match.collection,
+            collectionPath: resolved.join("/"),
+            collectionSegments: [...resolved]
+        };
+        steps.push(step);
+
+        // The chain ends on a collection, which is the one being addressed.
+        if (index >= pathSegments.length) {
+            return {
+                resolved,
+                steps,
+                collection: match.collection
+            };
+        }
+
+        // Exactly one segment is the entity id, however many slashes it contains.
+        step.entityId = pathSegments[index];
+        resolved.push(pathSegments[index]);
+        index += 1;
+
+        // The chain ends on an entity, which lives in the collection just matched.
+        if (index >= pathSegments.length) {
+            return {
+                resolved,
+                steps,
+                collection: match.collection
+            };
+        }
+
+        currentCollections = match.collection.subcollections;
+    }
+
+    return { resolved, steps };
+}
+
+/**
+ * Resolve collection aliases in a segment array: every collection id is replaced by the
+ * collection's real `path`, and every entity id is carried through untouched.
+ *
+ * The segment-wise counterpart of {@link resolveCollectionPathIds}, and the reason it
+ * exists: that one works on the flattened string, so an entity id containing "/" shifts
+ * the rest of the chain by a segment and resolution fails with
+ * "Collection definition not found for segment starting with …".
+ *
+ * Matching accepts either a collection's `path` or its `id`, so already-resolved segments
+ * pass through unchanged — the function is idempotent.
+ *
+ * Mirrors the string version when a chain cannot be matched: it warns and carries the
+ * remainder through unresolved, rather than throwing.
+ *
+ * @group Hooks and utilities
+ */
+export function resolveCollectionPathSegments(pathSegments: string[], allCollections: EntityCollection[]): string[] {
+    const walk = walkPathSegments(pathSegments, allCollections);
+    if (walk.unmatched !== undefined) {
+        console.warn(`resolveCollectionPathSegments: Collection definition not found for segment "${walk.unmatched}" in [${pathSegments.join(", ")}]. Carrying the remaining segments through unresolved.`);
+    }
+    return walk.resolved;
+}
+
+/**
+ * Find the collection a segment chain addresses, whether it ends on the collection itself
+ * or on one of its entities.
+ *
+ * The segment-wise counterpart of {@link getCollectionByPathOrId}, which asserts an odd
+ * number of "/"-separated parts — an assertion a slash-bearing entity id fails, throwing
+ * where it should simply have resolved.
+ *
+ * @group Hooks and utilities
+ */
+export function getCollectionByPathSegments(pathSegments: string[], collections: EntityCollection[]): EntityCollection | undefined {
+    return walkPathSegments(pathSegments, collections).collection;
+}
+
+export function resolveCollectionPathIds(path: string, allCollections: EntityCollection[], pathSegments?: string[]): string {
+
+    // When the caller knows the real segment boundaries there is nothing to parse: the
+    // ambiguity the string walk below has to guess its way through simply is not present.
+    if (pathSegments) {
+        return resolveCollectionPathSegments(pathSegments, allCollections).join("/");
+    }
+
     let remainingPath = removeInitialAndTrailingSlashes(path);
     if (!remainingPath) {
         return "";
@@ -93,7 +281,12 @@ export function resolveCollectionPathIds(path: string, allCollections: EntityCol
                 col,
                 match: col.id
             }])
-            .filter(p => p.match && remainingPath.startsWith(p.match))
+            // A match has to end where a path segment ends. Matching any prefix made
+            // "products-test" resolve to the "products" collection with an entity called
+            // "-test" (FirebaseError: Invalid document reference), and any collection whose
+            // path merely starts with another's — "products_archive", which the collection
+            // editor generates from "Products archive" — resolve to the wrong one.
+            .filter(p => p.match && (remainingPath === p.match || remainingPath.startsWith(p.match + "/")))
             .sort((a, b) => b.match.length - a.match.length);
 
         if (potentialMatches.length > 0) {
@@ -158,7 +351,14 @@ export function resolveCollectionPathIds(path: string, allCollections: EntityCol
  * @param pathOrId
  * @param collections
  */
-export function getCollectionByPathOrId(pathOrId: string, collections: EntityCollection[]): EntityCollection | undefined {
+export function getCollectionByPathOrId(pathOrId: string, collections: EntityCollection[], pathSegments?: string[]): EntityCollection | undefined {
+
+    // Given the real boundaries there is nothing to parse, and no parity to assert: a chain
+    // whose entity id contains "/" splits into an even number of parts below and would be
+    // rejected outright, even though it is perfectly valid.
+    if (pathSegments) {
+        return getCollectionByPathSegments(pathSegments, collections);
+    }
 
     const subpaths = removeInitialAndTrailingSlashes(pathOrId).split("/");
     if (subpaths.length % 2 === 0) {
@@ -249,6 +449,13 @@ export function navigateToEntity({
         });
 
     } else {
+        // A URL must be built from the ESCAPED chain. `fullIdPath` is that chain; `path` is
+        // the raw datasource one, and falling back to it is only safe while no id in it
+        // contains "/". When the segments show that it does, the resulting URL would address
+        // a different entity, so say so instead of navigating somewhere wrong in silence.
+        if (!fullIdPath && pathSegments?.some(segment => segment.includes("/"))) {
+            console.warn(`navigateToEntity: no "fullIdPath" was given and "${path}" contains an entity id with a "/", so no unambiguous URL can be built for it. The link will point at a different location. Pass "fullIdPath" — the escaped chain — alongside "path".`);
+        }
         let to = navigation.buildUrlCollectionPath(entityId ? `${fullIdPath ?? path}/${encodeEntityId(entityId)}` : fullIdPath ?? path);
         if (entityId && selectedTab) {
             to += `/${selectedTab}`;

package/src/util/parent_references_from_path.ts

@@ -1,18 +1,40 @@
 import { EntityCollection, EntityReference } from "../types";
-import { decodeEntityId, getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
+import {
+    decodeEntityId,
+    getCollectionPathsCombinations,
+    removeInitialAndTrailingSlashes,
+    walkPathSegments
+} from "./navigation_utils";
 
+/**
+ * References to every parent entity in a path.
+ *
+ * NOTE on encoding: `path` is expected ESCAPED, because it comes from the URL — the entity
+ * ids in it are decoded on the way out. Pass `pathSegments` instead whenever the path at
+ * hand is a raw datasource path (`entity.path`), which is not escaped and whose ids may
+ * therefore contain a bare "/": splitting that would silently produce the wrong references.
+ */
 export function getParentReferencesFromPath(props: {
     path: string,
     collections: EntityCollection[] | undefined,
     currentFullPath?: string,
+    currentPathSegments?: string[],
+    /** `path` split at its real segment boundaries, with RAW ids. Takes precedence. */
+    pathSegments?: string[],
 }): EntityReference [] {
 
     const {
         path,
         collections = [],
         currentFullPath,
+        currentPathSegments = [],
+        pathSegments,
     } = props;
 
+    if (pathSegments) {
+        return getParentReferencesFromPathSegments(pathSegments, collections);
+    }
+
     const subpaths = removeInitialAndTrailingSlashes(path).split("/");
     const subpathCombinations = getCollectionPathsCombinations(subpaths);
 
@@ -27,6 +49,9 @@ export function getParentReferencesFromPath(props: {
             const collectionPath = currentFullPath && currentFullPath.length > 0
                 ? (currentFullPath + "/" + collection.path)
                 : collection.path;
+            // A collection's own path may span several segments, and those are
+            // unambiguous, so they are spread rather than kept whole.
+            const collectionSegments = [...currentPathSegments, ...collection.path.split("/")];
 
             const restOfThePath = removeInitialAndTrailingSlashes(removeInitialAndTrailingSlashes(path).replace(subpathCombination, ""));
             const nextSegments = restOfThePath.length > 0 ? restOfThePath.split("/") : [];
@@ -35,7 +60,9 @@ export function getParentReferencesFromPath(props: {
                 // datasource-facing, so they carry the raw id.
                 const entityId = decodeEntityId(nextSegments[0]);
                 const fullPath = collectionPath + "/" + entityId;
-                result.push(new EntityReference(entityId, collectionPath));
+                // The id is ONE segment however many slashes it contains.
+                const entitySegments = [...collectionSegments, entityId];
+                result.push(new EntityReference(entityId, collectionPath, undefined, collectionSegments));
                 if (nextSegments.length > 1) {
                     const newPath = nextSegments.slice(1).join("/");
                     if (!collection) {
@@ -45,7 +72,8 @@ export function getParentReferencesFromPath(props: {
                         result.push(...getParentReferencesFromPath({
                             path: newPath,
                             collections: collection.subcollections,
-                            currentFullPath: fullPath
+                            currentFullPath: fullPath,
+                            currentPathSegments: entitySegments
                         }));
                     }
                 }
@@ -56,3 +84,14 @@ export function getParentReferencesFromPath(props: {
     }
     return result;
 }
+
+/**
+ * The segment-wise counterpart: the boundaries are given, so an entity id keeps its
+ * slashes and nothing has to be decoded.
+ */
+export function getParentReferencesFromPathSegments(pathSegments: string[],
+                                                    collections: EntityCollection[]): EntityReference[] {
+    return walkPathSegments(pathSegments, collections).steps
+        .filter(step => step.entityId !== undefined)
+        .map(step => new EntityReference(step.entityId!, step.collectionPath, undefined, step.collectionSegments));
+}

package/src/util/paths.ts

@@ -18,10 +18,47 @@ export function segmentsToStrippedPath(paths: string[]) {
 /**
  * Extract the collection path routes
  * `products/B44RG6APH/locales` => [`products`, `locales`]
+ *
+ * Finds the entity ids by position, which only works while no id contains "/" — with one,
+ * every following segment shifts and the wrong elements are kept. Use
+ * {@link collectionSegmentsFrom} when the real boundaries are known.
+ *
  * @param path
  */
 export function fullPathToCollectionSegments(path: string): string[] {
-    return path
-        .split("/")
-        .filter((e, i) => i % 2 === 0);
+    return positionalCollectionSegments(path);
+}
+
+/**
+ * The collection chain of an already-segmented path:
+ * `['products', 'B44RG6APH', 'locales']` => [`products`, `locales`]
+ *
+ * The counterpart of {@link fullPathToCollectionSegments} for callers that know the real
+ * segment boundaries. Kept as a separate function rather than an extra parameter on that
+ * one: these helpers are small enough to be passed point-free, and `paths.map(fn)` would
+ * then hand the array index in as the new argument.
+ */
+export function collectionSegmentsFrom(pathSegments: string[]): string[] {
+    return keepCollectionPositions(pathSegments);
+}
+
+/**
+ * The historical, positional reading of a flattened path:
+ * `products/B44RG6APH/locales` => [`products`, `locales`]
+ *
+ * This produces a **collection chain**, not a datasource `pathSegments` value, and must
+ * never be used as one — see `path_segments_no_fabrication.test.ts`. It is only correct
+ * while no entity id contains "/", which is why every caller prefers real segments when
+ * they are available, and why it is named for what it assumes.
+ *
+ * It is still the right reading for a path that came from a URL, where entity ids arrive
+ * escaped and so cannot contain a bare "/".
+ */
+export function positionalCollectionSegments(path: string): string[] {
+    return keepCollectionPositions(path.split("/"));
+}
+
+/** Keep the even positions of an alternating collection/entity-id chain. */
+function keepCollectionPositions(segments: string[]): string[] {
+    return segments.filter((e, i) => i % 2 === 0);
 }