@firecms/core 3.3.0 → 3.4.0-canary.0ef7442

package/src/util/__tests__/urls.test.ts

@@ -0,0 +1,131 @@
+import { getFileExtensionFromUrl, getPreviewTypeFromUrl, isAbsoluteHttpUrl } from "../urls";
+
+describe("url utilities", () => {
+
+    describe("isAbsoluteHttpUrl", () => {
+
+        it("should detect absolute http and https URLs", () => {
+            expect(isAbsoluteHttpUrl("https://abc.com/abc.png")).toBe(true);
+            expect(isAbsoluteHttpUrl("http://abc.com/abc.png")).toBe(true);
+            expect(isAbsoluteHttpUrl("HTTPS://ABC.COM/ABC.PNG")).toBe(true);
+        });
+
+        it("should detect Firebase Storage download URLs as absolute URLs", () => {
+            expect(isAbsoluteHttpUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.png?alt=media&token=abc")).toBe(true);
+            expect(isAbsoluteHttpUrl("https://storage.googleapis.com/demo.appspot.com/images/cat.png")).toBe(true);
+        });
+
+        it("should not consider storage paths absolute URLs", () => {
+            expect(isAbsoluteHttpUrl("images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("/images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("cat.png")).toBe(false);
+        });
+
+        it("should not consider other protocols absolute http URLs", () => {
+            expect(isAbsoluteHttpUrl("gs://demo.appspot.com/images/cat.png")).toBe(false);
+            expect(isAbsoluteHttpUrl("data:image/png;base64,AAAA")).toBe(false);
+            expect(isAbsoluteHttpUrl("//abc.com/abc.png")).toBe(false);
+        });
+
+        it("should handle empty values", () => {
+            expect(isAbsoluteHttpUrl("")).toBe(false);
+            expect(isAbsoluteHttpUrl(undefined)).toBe(false);
+            expect(isAbsoluteHttpUrl(null)).toBe(false);
+        });
+
+        it("should not match http appearing later in the value", () => {
+            expect(isAbsoluteHttpUrl("images/https://abc.com/abc.png")).toBe(false);
+        });
+
+    });
+
+    describe("getFileExtensionFromUrl", () => {
+
+        it("should extract the extension of a plain URL", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png")).toBe("png");
+        });
+
+        it("should lowercase the extension", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/ABC.PNG")).toBe("png");
+        });
+
+        it("should ignore query strings and hash fragments", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png?width=200")).toBe("png");
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png#anchor")).toBe("png");
+            expect(getFileExtensionFromUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.jpeg?alt=media&token=abc")).toBe("jpeg");
+        });
+
+        it("should work with storage paths", () => {
+            expect(getFileExtensionFromUrl("images/cat.webp")).toBe("webp");
+        });
+
+        it("should use the last dot of the file name", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/archive.tar.gz")).toBe("gz");
+        });
+
+        it("should return undefined when there is no extension", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/abc")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/")).toBeUndefined();
+            expect(getFileExtensionFromUrl("images/cat")).toBeUndefined();
+        });
+
+        it("should not take dots of the host or the path as extensions", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/images/cat")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/abc.png/download")).toBeUndefined();
+        });
+
+        it("should return undefined for dotfiles and trailing dots", () => {
+            expect(getFileExtensionFromUrl("https://abc.com/.gitignore")).toBeUndefined();
+            expect(getFileExtensionFromUrl("https://abc.com/abc.")).toBeUndefined();
+        });
+
+        it("should handle empty values", () => {
+            expect(getFileExtensionFromUrl("")).toBeUndefined();
+            expect(getFileExtensionFromUrl(undefined)).toBeUndefined();
+            expect(getFileExtensionFromUrl(null)).toBeUndefined();
+        });
+
+    });
+
+    describe("getPreviewTypeFromUrl", () => {
+
+        it("should infer image previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.png")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.jpg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.jpeg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.gif")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.webp")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.svg")).toBe("image");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.avif")).toBe("image");
+        });
+
+        it("should infer video previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mp4")).toBe("video");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.webm")).toBe("video");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mov")).toBe("video");
+        });
+
+        it("should infer audio previews", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.mp3")).toBe("audio");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.wav")).toBe("audio");
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.m4a")).toBe("audio");
+        });
+
+        it("should infer the type of Firebase Storage download URLs", () => {
+            expect(getPreviewTypeFromUrl("https://firebasestorage.googleapis.com/v0/b/demo.appspot.com/o/images%2Fcat.png?alt=media&token=abc")).toBe("image");
+        });
+
+        it("should be case insensitive", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/ABC.PNG")).toBe("image");
+        });
+
+        it("should return undefined for unknown or missing extensions", () => {
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.pdf")).toBeUndefined();
+            expect(getPreviewTypeFromUrl("https://abc.com/abc.zip")).toBeUndefined();
+            expect(getPreviewTypeFromUrl("https://abc.com/abc")).toBeUndefined();
+            expect(getPreviewTypeFromUrl(undefined)).toBeUndefined();
+        });
+
+    });
+
+});

package/src/util/collections.ts

@@ -117,7 +117,7 @@ export const applyPermissionsFunctionIfEmpty = (collections: EntityCollection[],
 }
 
 export function getLocalChangesBackup(collection: EntityCollection) {
-    if (!collection.localChangesBackup) {
+    if (collection.localChangesBackup === undefined) {
         return "manual_apply";
     }
 

package/src/util/entities.ts

@@ -75,6 +75,8 @@ export function getDefaultValueForDataType(dataType: DataType) {
         return [];
     } else if (dataType === "map") {
         return {};
+    } else if (dataType === "geopoint") {
+        return null;
     } else {
         return null;
     }
@@ -137,7 +139,12 @@ export function sanitizeData<M extends Record<string, any>>
 }
 
 export function getReferenceFrom<M extends Record<string, any>>(entity: Entity<M>): EntityReference {
-    return new EntityReference(entity.id, entity.path, entity.databaseId);
+    if (!entity) {
+        throw new Error("getReferenceFrom: entity is null or undefined");
+    }
+    // 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>>(
@@ -196,3 +203,11 @@ export function traverseValueProperty(inputValue: any,
 
     return value;
 }
+
+export function isDataTypeFilterable(dataType: DataType, isPartOfArray = false) {
+    if (isPartOfArray) {
+        return ["string", "number", "date", "reference"].includes(dataType);
+    }
+    
+    return ["string", "number", "boolean", "date", "reference", "array"].includes(dataType);
+}

package/src/util/geopoint.ts

@@ -0,0 +1,81 @@
+import { GeoPoint } from "../types";
+
+export type GeoPointLike = GeoPoint | {
+    latitude?: number;
+    longitude?: number;
+    lat?: number;
+    lng?: number;
+    _lat?: number;
+    _long?: number;
+} | null | undefined;
+
+export interface GeoPointCoordinates {
+    latitude: number;
+    longitude: number;
+}
+
+function toNumber(value: any): number | undefined {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function getGeoPointCoordinates(value: GeoPointLike): GeoPointCoordinates | undefined {
+    if (!value) return undefined;
+    if (value instanceof GeoPoint) {
+        return { latitude: value.latitude, longitude: value.longitude };
+    }
+    if (typeof value !== "object") return undefined;
+
+    const latitude = toNumber((value as any).latitude ?? (value as any).lat ?? (value as any)._lat);
+    const longitude = toNumber((value as any).longitude ?? (value as any).lng ?? (value as any)._long);
+
+    if (latitude === undefined || longitude === undefined) return undefined;
+
+    return { latitude, longitude };
+}
+
+export function normalizeGeoPoint(value: GeoPointLike): GeoPoint | undefined {
+    const coordinates = getGeoPointCoordinates(value);
+    if (!coordinates) return undefined;
+    if (value instanceof GeoPoint) return value;
+    return new GeoPoint(coordinates.latitude, coordinates.longitude);
+}
+
+export function formatGeoPoint(value: GeoPointLike, options?: { maximumFractionDigits?: number }): string {
+    const coordinates = getGeoPointCoordinates(value);
+    if (!coordinates) return "";
+
+    const maximumFractionDigits = options?.maximumFractionDigits ?? 6;
+    // Coordinates are always formatted with a dot as decimal separator, independently of the
+    // user locale. Locale-aware formatting would use a comma in locales such as de or fr,
+    // making the "lat, lng" output ambiguous and impossible to parse back.
+    const formatter = new Intl.NumberFormat("en-US", {
+        maximumFractionDigits,
+        minimumFractionDigits: Math.min(2, maximumFractionDigits),
+        useGrouping: false
+    });
+
+    return `${formatter.format(coordinates.latitude)}, ${formatter.format(coordinates.longitude)}`;
+}
+
+export function parseGeoPoint(input: string): { point: GeoPoint | null; error?: string } {
+    const trimmed = input.trim();
+    if (!trimmed) return { point: null };
+
+    const parts = trimmed.split(",").map((part) => part.trim()).filter((part) => part !== "");
+    if (parts.length !== 2) return { point: null, error: "Use \"lat, lng\" format" };
+
+    const latitude = parseFloat(parts[0]);
+    const longitude = parseFloat(parts[1]);
+
+    if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+        return { point: null, error: "Latitude and longitude must be numbers" };
+    }
+    if (latitude < -90 || latitude > 90) {
+        return { point: null, error: "Latitude must be between -90 and 90" };
+    }
+    if (longitude < -180 || longitude > 180) {
+        return { point: null, error: "Longitude must be between -180 and 180" };
+    }
+
+    return { point: new GeoPoint(latitude, longitude) };
+}

package/src/util/index.ts

@@ -6,12 +6,14 @@ export * from "./enums";
 export * from "./objects";
 export * from "./paths";
 export * from "./regexp";
+export * from "./urls";
 export * from "./navigation_utils";
 export * from "./entity_actions";
 export * from "./useDebouncedCallback";
 export * from "./property_utils";
 export * from "./resolutions";
 export * from "./permissions";
+export * from "./geopoint";
 export * from "./icon_list";
 export * from "./icon_synonyms";
 export * from "./icons";

package/src/util/navigation_blocking.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure predicate deciding whether an in-progress navigation away from an open
+ * entity form should be blocked (to warn about unsaved changes).
+ *
+ * Extracted from FireCMSRoute so the branching can be unit-tested without
+ * mounting the router. This is an internal helper — it is intentionally not
+ * re-exported from the package index.
+ */
+export interface NavigationBlockLocation {
+    pathname: string;
+    hash: string;
+}
+
+const SIDE_PANEL_HASHES = ["#side", "#new_side"];
+
+export function shouldBlockEntityNavigation(params: {
+    currentLocation: NavigationBlockLocation;
+    nextLocation: NavigationBlockLocation;
+    /** Path of the currently open entity (basePath + "/" + entityId). */
+    entityPath: string;
+    /** Collection path the entity form lives under. */
+    basePath: string;
+    /** Whether the form currently has unsaved modifications. */
+    blocked: boolean;
+}): boolean {
+    const { currentLocation, nextLocation, entityPath, basePath, blocked } = params;
+
+    // Navigating deeper within the same entity — never block.
+    if (nextLocation.pathname.startsWith(entityPath))
+        return false;
+
+    // Side panel overlay navigations preserve the underlying form via
+    // base_location in router state — no data is lost in either direction.
+
+    // Opening a side panel (e.g. clicking a relation/reference arrow).
+    if (SIDE_PANEL_HASHES.includes(nextLocation.hash))
+        return false;
+
+    // Closing a side panel (navigate(-1) back to the form's own path).
+    if (SIDE_PANEL_HASHES.includes(currentLocation.hash) &&
+        nextLocation.pathname === basePath)
+        return false;
+
+    return blocked;
+}

package/src/util/navigation_from_path.ts

@@ -1,5 +1,5 @@
 import { EntityCollection, EntityCustomView } from "../types";
-import { getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
+import { decodeEntityId, getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
 import { resolveEntityView } from "./resolutions";
 
 export type NavigationViewInternal<M extends Record<string, any> = any> =
@@ -13,6 +13,8 @@ export interface NavigationViewEntityInternal<M extends Record<string, any>> {
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     parentCollection: EntityCollection<M>;
 }
 
@@ -22,6 +24,8 @@ export interface NavigationViewCollectionInternal<M extends Record<string, any>>
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     collection: EntityCollection<M>;
 }
 
@@ -30,15 +34,28 @@ export interface NavigationViewEntityCustomInternal<M extends Record<string, any
     path: string;
     fullIdPath: string;
     fullPath: string;
+    /** `path` split at its real boundaries — see `pathSegments` on the datasource props. */
+    pathSegments: string[];
     entityId: string;
     view: EntityCustomView<M>;
 }
 
+/**
+ * Note on encoding: `path` arrives from the URL, so any entity id in it is escaped (see
+ * `encodeEntityId`). Two chains are threaded through the recursion:
+ *
+ *  - `currentFullPath` carries RAW ids and feeds the `path` / `fullPath` used to address
+ *    the datasource.
+ *  - `currentFullUrlPath` carries ESCAPED ids and feeds `fullPath`, which is handed back
+ *    to `buildUrlCollectionPath` for breadcrumbs and links.
+ */
 export function getNavigationEntriesFromPath(props: {
     path: string,
     collections: EntityCollection[] | undefined,
     currentFullPath?: string,
     currentFullIdPath?: string,
+    currentFullUrlPath?: string,
+    currentPathSegments?: string[],
     contextEntityViews?: EntityCustomView<any>[]
 }): NavigationViewInternal [] {
 
@@ -46,7 +63,9 @@ export function getNavigationEntriesFromPath(props: {
         path,
         collections = [],
         currentFullPath,
-        currentFullIdPath
+        currentFullIdPath,
+        currentFullUrlPath,
+        currentPathSegments = []
     } = props;
 
     const subpaths = removeInitialAndTrailingSlashes(path).split("/");
@@ -66,28 +85,41 @@ export function getNavigationEntriesFromPath(props: {
             const collectionPath = currentFullPath && currentFullPath.length > 0
                 ? (currentFullPath + "/" + collection.path)
                 : collection.path;
+            const collectionUrlPath = currentFullUrlPath && currentFullUrlPath.length > 0
+                ? (currentFullUrlPath + "/" + collection.path)
+                : collection.path;
             const fullIdPath = currentFullIdPath && currentFullIdPath.length > 0
                 ? (currentFullIdPath + "/" + collection.id)
                 : collection.id;
+            // A collection `path` may itself span several segments (e.g. "users/uid/experiences"),
+            // and those are unambiguous, so they are spread rather than kept whole.
+            const collectionSegments = [...currentPathSegments, ...collection.path.split("/")];
             result.push({
                 type: "collection",
                 id: collection.id,
                 path: collectionPath,
-                fullPath: collectionPath,
+                fullPath: collectionUrlPath,
                 fullIdPath,
+                pathSegments: collectionSegments,
                 collection
             });
             const restOfThePath = removeInitialAndTrailingSlashes(removeInitialAndTrailingSlashes(path).replace(subpathCombination, ""));
             const nextSegments = restOfThePath.length > 0 ? restOfThePath.split("/") : [];
             if (nextSegments.length > 0) {
-                const entityId = nextSegments[0];
+                const encodedEntityId = nextSegments[0];
+                const entityId = decodeEntityId(encodedEntityId);
                 const fullPath = collectionPath + "/" + entityId;
+                const fullUrlPath = collectionUrlPath + "/" + encodedEntityId;
+                // The id is ONE segment however many slashes it contains — that is the
+                // whole point of this array.
+                const entitySegments = [...collectionSegments, entityId];
                 result.push({
                     type: "entity",
                     entityId,
                     path: collectionPath,
                     fullIdPath,
-                    fullPath: fullPath,
+                    fullPath: fullUrlPath,
+                    pathSegments: collectionSegments,
                     parentCollection: collection
                 });
                 if (nextSegments.length > 1) {
@@ -106,7 +138,8 @@ export function getNavigationEntriesFromPath(props: {
                             path: collectionPath,
                             entityId: entityId,
                             fullIdPath,
-                            fullPath: fullPath + "/" + customView.key,
+                            fullPath: fullUrlPath + "/" + customView.key,
+                            pathSegments: collectionSegments,
                             view: customView
                         });
                     } else if (collection.subcollections) {
@@ -115,6 +148,8 @@ export function getNavigationEntriesFromPath(props: {
                             collections: collection.subcollections,
                             currentFullPath: fullPath,
                             currentFullIdPath: fullIdPath,
+                            currentFullUrlPath: fullUrlPath,
+                            currentPathSegments: entitySegments,
                             contextEntityViews: props.contextEntityViews
                         }));
                     }

package/src/util/navigation_utils.ts

@@ -22,6 +22,40 @@ export function addInitialSlash(s: string) {
     else return `/${s}`;
 }
 
+/**
+ * Characters that would otherwise be read as structure once an entity id is joined into a
+ * path: "/" separates segments, "?" and "#" start the query and hash in a URL, and "%"
+ * has to be escaped first so that no escape sequence we introduce can be misread as one
+ * that was already part of the id.
+ *
+ * Entity ids are escaped ONLY inside URL-facing strings — anything handed to
+ * `buildUrlCollectionPath` or `navigate`. Every other path string (the `path` field of a
+ * navigation entry, datasource paths, `EntityReference.path`) carries raw ids.
+ *
+ * @group Hooks and utilities
+ */
+export function encodeEntityId(entityId: string): string {
+    return entityId
+        .replaceAll("%", "%25")
+        .replaceAll("/", "%2F")
+        .replaceAll("#", "%23")
+        .replaceAll("?", "%3F");
+}
+
+/**
+ * Inverse of {@link encodeEntityId}. "%25" is undone last, mirroring the encoder, so an id
+ * that legitimately contains the text "%2F" survives the round trip.
+ *
+ * @group Hooks and utilities
+ */
+export function decodeEntityId(encodedEntityId: string): string {
+    return encodedEntityId
+        .replaceAll("%2F", "/")
+        .replaceAll("%23", "#")
+        .replaceAll("%3F", "?")
+        .replaceAll("%25", "%");
+}
+
 export function getLastSegment(path: string) {
     const cleanPath = removeInitialAndTrailingSlashes(path);
     if (cleanPath.includes("/")) {
@@ -160,7 +194,7 @@ export function getCollectionByPathOrId(pathOrId: string, collections: EntityCol
  * @param subpaths
  */
 export function getCollectionPathsCombinations(subpaths: string[]): string[] {
-    const entries = subpaths.length > 0 && subpaths.length % 2 === 0 ? subpaths.splice(0, subpaths.length - 1) : subpaths;
+    const entries = subpaths.length > 0 && subpaths.length % 2 === 0 ? subpaths.slice(0, subpaths.length - 1) : subpaths;
 
     const length = entries.length;
     const result: string[] = [];
@@ -178,6 +212,7 @@ export function navigateToEntity({
                                      copy,
                                      path,
                                      fullIdPath,
+                                     pathSegments,
                                      selectedTab,
                                      sideEntityController,
                                      onClose,
@@ -192,6 +227,8 @@ export function navigateToEntity({
                                      copy?: boolean;
                                      path: string;
                                      fullIdPath?: string;
+                                     /** `path` split at its real segment boundaries. */
+                                     pathSegments?: string[];
                                      sideEntityController: SideEntityController;
                                      onClose?: () => void;
                                      navigation: NavigationController
@@ -203,6 +240,7 @@ export function navigateToEntity({
             entityId,
             path,
             fullIdPath,
+            pathSegments,
             copy,
             selectedTab,
             collection,
@@ -211,7 +249,7 @@ export function navigateToEntity({
         });
 
     } else {
-        let to = navigation.buildUrlCollectionPath(entityId ? `${fullIdPath ?? path}/${entityId}` : fullIdPath ?? 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,16 +1,18 @@
 import { EntityCollection, EntityReference } from "../types";
-import { getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
+import { decodeEntityId, getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
 
 export function getParentReferencesFromPath(props: {
     path: string,
     collections: EntityCollection[] | undefined,
     currentFullPath?: string,
+    currentPathSegments?: string[],
 }): EntityReference [] {
 
     const {
         path,
         collections = [],
         currentFullPath,
+        currentPathSegments = [],
     } = props;
 
     const subpaths = removeInitialAndTrailingSlashes(path).split("/");
@@ -27,13 +29,20 @@ 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("/") : [];
             if (nextSegments.length > 0) {
-                const entityId = nextSegments[0];
+                // `path` comes from the URL, so the id segment is escaped. References are
+                // 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) {
@@ -43,7 +52,8 @@ export function getParentReferencesFromPath(props: {
                         result.push(...getParentReferencesFromPath({
                             path: newPath,
                             collections: collection.subcollections,
-                            currentFullPath: fullPath
+                            currentFullPath: fullPath,
+                            currentPathSegments: entitySegments
                         }));
                     }
                 }

package/src/util/previews.ts

@@ -1,4 +1,4 @@
-import { AuthController, EntityCollection, Property, PropertyConfig, ResolvedEntityCollection } from "../types";
+import { AuthController, EntityCollection, Property, PropertyConfig, ResolvedEntityCollection, ResolvedProperties } from "../types";
 import { isReferenceProperty } from "./property_utils";
 import { isPropertyBuilder } from "./entities";
 import { getFieldConfig } from "../core";
@@ -44,6 +44,13 @@ export function getEntityTitlePropertyKey<M extends Record<string, any>>(collect
 
 export function getEntityImagePreviewPropertyKey<M extends object>(collection: ResolvedEntityCollection<M>): string | undefined {
 
+    if (collection.imageProperty) {
+        const imagePropertyKey = collection.imageProperty as keyof ResolvedProperties<M>;
+        if (collection.properties[imagePropertyKey]) {
+            return collection.imageProperty as string;
+        }
+    }
+
     // find first storage property of type image
     for (const key in collection.properties) {
         const property = collection.properties[key];

package/src/util/resolutions.ts

@@ -305,7 +305,15 @@ export function resolveArrayProperty<T extends any[], M>({
                 ignoreMissingFields,
                 ...props
             });
+            // `of` describes the shape of any element of the array, not one
+            // specific element, so there is no index to qualify the key with.
+            // We pass the array's own key, mirroring what the `oneOf` branch
+            // below does for `oneOf.properties`. Without this, a property
+            // builder used as `of` (or nested inside it) would be invoked with
+            // `propertyKey: undefined`, while the per-index resolutions above
+            // receive `${propertyKey}.${index}`.
             const ofProperty = resolveProperty({
+                propertyKey,
                 propertyOrBuilder: of,
                 ignoreMissingFields,
                 ...props