@firecms/core 3.4.0-canary.0ef7442 → 3.4.0-canary.2575a08

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 "";
@@ -158,7 +346,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 +444,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,11 +1,26 @@
 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 {
@@ -13,8 +28,13 @@ export function getParentReferencesFromPath(props: {
         collections = [],
         currentFullPath,
         currentPathSegments = [],
+        pathSegments,
     } = props;
 
+    if (pathSegments) {
+        return getParentReferencesFromPathSegments(pathSegments, collections);
+    }
+
     const subpaths = removeInitialAndTrailingSlashes(path).split("/");
     const subpathCombinations = getCollectionPathsCombinations(subpaths);
 
@@ -64,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);
 }

package/src/util/permissions.ts

@@ -1,5 +1,5 @@
 import { AuthController, Entity, EntityCollection, Permissions, User } from "../types";
-import { fullPathToCollectionSegments } from "./paths";
+import { collectionSegmentsFrom, fullPathToCollectionSegments } from "./paths";
 
 const DEFAULT_PERMISSIONS = {
     read: true,
@@ -8,11 +8,18 @@ const DEFAULT_PERMISSIONS = {
     delete: true
 };
 
+/**
+ * `pathSegments` is `path` split at its real segment boundaries. It is forwarded so the
+ * collection chain handed to a permissions builder stays correct when an entity id contains
+ * "/" — splitting `path` positionally would keep the wrong elements. Optional everywhere:
+ * omitted, behaviour is exactly as before.
+ */
 export function resolvePermissions<M extends Record<string, any>, USER extends User>
 (collection: EntityCollection<M>,
  authController: AuthController<USER>,
  path: string,
- entity: Entity<M> | null): Permissions | undefined {
+ entity: Entity<M> | null,
+ pathSegments?: string[]): Permissions | undefined {
 
     const permission = collection.permissions;
     if (permission === undefined) {
@@ -20,14 +27,16 @@ export function resolvePermissions<M extends Record<string, any>, USER extends U
     } else if (typeof permission === "object") {
         return permission as Permissions;
     } else if (typeof permission === "function") {
-        const pathSegments = fullPathToCollectionSegments(path);
+        const collectionSegments = pathSegments
+            ? collectionSegmentsFrom(pathSegments)
+            : fullPathToCollectionSegments(path);
         return permission({
             entity,
             path,
             user: authController.user,
             authController,
             collection,
-            pathSegments
+            pathSegments: collectionSegments
         });
     }
     console.error("Permissions:", permission);
@@ -39,8 +48,9 @@ export function canEditEntity<M extends Record<string, any>, USER extends User>
     collection: EntityCollection<M>,
     authController: AuthController<USER>,
     path: string,
-    entity: Entity<M> | null): boolean {
-    return resolvePermissions(collection, authController, path, entity)?.edit ?? DEFAULT_PERMISSIONS.edit;
+    entity: Entity<M> | null,
+    pathSegments?: string[]): boolean {
+    return resolvePermissions(collection, authController, path, entity, pathSegments)?.edit ?? DEFAULT_PERMISSIONS.edit;
 }
 
 export function canCreateEntity<M extends Record<string, any>, USER extends User>
@@ -48,9 +58,10 @@ export function canCreateEntity<M extends Record<string, any>, USER extends User
     collection: EntityCollection<M>,
     authController: AuthController<USER>,
     path: string,
-    entity: Entity<M> | null): boolean {
+    entity: Entity<M> | null,
+    pathSegments?: string[]): boolean {
     if (collection.collectionGroup) return false;
-    return resolvePermissions(collection, authController, path, entity)?.create ?? DEFAULT_PERMISSIONS.create;
+    return resolvePermissions(collection, authController, path, entity, pathSegments)?.create ?? DEFAULT_PERMISSIONS.create;
 }
 
 export function canDeleteEntity<M extends Record<string, any>, USER extends User>
@@ -58,8 +69,9 @@ export function canDeleteEntity<M extends Record<string, any>, USER extends User
     collection: EntityCollection<M>,
     authController: AuthController<USER>,
     path: string,
-    entity: Entity<M> | null): boolean {
-    return resolvePermissions(collection, authController, path, entity)?.delete ?? DEFAULT_PERMISSIONS.delete;
+    entity: Entity<M> | null,
+    pathSegments?: string[]): boolean {
+    return resolvePermissions(collection, authController, path, entity, pathSegments)?.delete ?? DEFAULT_PERMISSIONS.delete;
 }
 
 // export function resolveCollectionsPermissions(roles: Role[]): Record<string, Permissions> {