@firecms/core 3.4.0-canary.63041d0 → 3.4.0-canary.cfeed0b

package/src/types/datasource.ts

@@ -106,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>;
 }
 
@@ -245,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
@@ -272,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>;
@@ -279,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>;
@@ -408,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
@@ -440,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

package/src/types/plugins.tsx

@@ -146,6 +146,8 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         blockSearch?: (props: {
             context: FireCMSContext,
             path: string,
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[],
             collection: EC,
             parentCollectionIds?: string[]
         }) => boolean;
@@ -153,6 +155,8 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         showTextSearchBar?: (props: {
             context: FireCMSContext,
             path: string,
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[],
             collection: EC,
             parentCollectionIds?: string[]
         }) => boolean;
@@ -160,6 +164,8 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         onTextSearchClick?: (props: {
             context: FireCMSContext,
             path: string,
+            /** `path` split at its real segment boundaries, when known. */
+            pathSegments?: string[],
             collection: EC,
             parentCollectionIds?: string[]
         }) => Promise<boolean>;
@@ -308,6 +314,13 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
 export interface PluginFormActionProps<USER extends User = User, EC extends EntityCollection = EntityCollection> {
     entityId?: string;
     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[];
     parentCollectionIds: string[];
     status: EntityStatus;
     collection: EC;

package/src/types/side_entity_controller.tsx

@@ -21,8 +21,9 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
     fullIdPath?: string;
     /**
      * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
-     * Optional: when omitted the panel falls back to splitting `path`, which is correct for
-     * any backend whose entity ids cannot contain "/".
+     *
+     * 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[];
 

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/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 "";
@@ -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}`;