@firecms/core 3.4.0-canary.f6a889a → 3.4.0

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) {
@@ -212,6 +407,7 @@ export function navigateToEntity({
                                      copy,
                                      path,
                                      fullIdPath,
+                                     pathSegments,
                                      selectedTab,
                                      sideEntityController,
                                      onClose,
@@ -226,6 +422,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
@@ -237,6 +435,7 @@ export function navigateToEntity({
             entityId,
             path,
             fullIdPath,
+            pathSegments,
             copy,
             selectedTab,
             collection,
@@ -245,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,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);
 }

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> {

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

package/src/util/urls.ts

@@ -0,0 +1,52 @@
+import type { PreviewType } from "../types";
+
+const ABSOLUTE_HTTP_URL_REGEX = /^https?:\/\//i;
+
+const IMAGE_EXTENSIONS = ["jpg", "jpeg", "png", "gif", "webp", "avif", "bmp", "svg", "ico", "tif", "tiff", "heic", "heif"];
+const VIDEO_EXTENSIONS = ["mp4", "webm", "ogv", "mov", "m4v", "avi", "mkv", "mpeg", "mpg", "3gp"];
+const AUDIO_EXTENSIONS = ["mp3", "wav", "ogg", "oga", "m4a", "aac", "flac", "weba", "opus", "mid", "midi"];
+
+/**
+ * Is the given value an absolute `http(s)` URL, as opposed to a relative
+ * storage path such as `images/my_image.png`?
+ *
+ * Values saved in the datasource for storage properties can be either, e.g.
+ * when the property is configured with `storeUrl: true`, or when the value was
+ * written directly pointing to an externally hosted file.
+ */
+export function isAbsoluteHttpUrl(value?: string | null): boolean {
+    if (!value) return false;
+    return ABSOLUTE_HTTP_URL_REGEX.test(value);
+}
+
+/**
+ * Extract the lowercase file extension of a URL or path, ignoring any query
+ * string or hash fragment. Returns `undefined` when there is no extension.
+ */
+export function getFileExtensionFromUrl(urlOrPath?: string | null): string | undefined {
+    if (!urlOrPath) return undefined;
+    // Query strings and hash fragments are not part of the file name, and they
+    // are common in download URLs, e.g. `?alt=media&token=...`
+    const withoutQuery = urlOrPath.split(/[?#]/)[0];
+    const lastSegment = withoutQuery.split("/").pop();
+    if (!lastSegment) return undefined;
+    const lastDot = lastSegment.lastIndexOf(".");
+    // No dot, a leading dot (a dotfile), or a trailing dot means no extension
+    if (lastDot <= 0 || lastDot === lastSegment.length - 1) return undefined;
+    return lastSegment.substring(lastDot + 1).toLowerCase();
+}
+
+/**
+ * Best effort guess of the preview type of a URL or path, based on its file
+ * extension. Used when no storage metadata (and therefore no content type) is
+ * available, e.g. for externally hosted files.
+ * Returns `undefined` when the extension is missing or not recognised.
+ */
+export function getPreviewTypeFromUrl(urlOrPath?: string | null): PreviewType | undefined {
+    const extension = getFileExtensionFromUrl(urlOrPath);
+    if (!extension) return undefined;
+    if (IMAGE_EXTENSIONS.includes(extension)) return "image";
+    if (VIDEO_EXTENSIONS.includes(extension)) return "video";
+    if (AUDIO_EXTENSIONS.includes(extension)) return "audio";
+    return undefined;
+}