@firecms/core 3.4.0-canary.f6a889a → 3.4.0

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/properties.ts

@@ -562,6 +562,22 @@ export type PropertyBuilderProps<M extends Record<string, any> = any> =
          * Current value of this property
          */
         propertyValue?: any;
+        /**
+         * Path of this property within the entity, in dot notation, e.g.
+         * `my_map.my_field` or `my_array.0.my_field`.
+         * Useful to look up sibling values in `values` with `getValueInPath`.
+         *
+         * When a property builder is used as the `of` prop of an array property,
+         * it is resolved twice: once per existing element, with an index
+         * qualified key (`my_array.0`), and once as the template for the element
+         * shape, with the array's own key (`my_array`). In the latter case
+         * `propertyValue` is the whole array, since the template is not bound to
+         * any element.
+         *
+         * It may be undefined if the property is resolved outside the context of
+         * an entity.
+         */
+        propertyKey?: string;
         /**
          * Index of this property (only for arrays)
          */
@@ -592,6 +608,7 @@ export type PropertyBuilder<T extends CMSType = any, M extends Record<string, an
         values,
         previousValues,
         propertyValue,
+        propertyKey,
         index,
         path,
         entityId,

package/src/types/side_entity_controller.tsx

@@ -19,6 +19,13 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      * Full CMS path of the entity, including the collection and sub-collections.
      */
     fullIdPath?: string;
+    /**
+     * `path` split at its real segment boundaries, e.g. `["nodes", "node/42", "edges"]`.
+     *
+     * 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[];
 
     /**
      * ID of the entity, if not set, it means we are creating a new entity

package/src/types/translations.ts

@@ -419,6 +419,8 @@ export interface FireCMSTranslations {
     download: string;
     large_number_of_documents: string;
     include_undefined_values: string;
+    /** Toggle in the export dialog, only shown when a filter or sort is active */
+    export_apply_filter_sort: string;
     submit: string;
 
     no_filterable_properties: string;
@@ -620,6 +622,10 @@ export interface FireCMSTranslations {
     order_property_not_found: string;
     no_number_properties: string;
     order_property_description: string;
+    image_property: string;
+    image_property_not_found: string;
+    no_image_properties: string;
+    image_property_description: string;
     display_settings: string;
     default_row_size: string;
     side_dialog_width: string;

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

@@ -0,0 +1,32 @@
+import { getLocalChangesBackup } from "../collections";
+import { EntityCollection } from "../../types";
+
+function collectionWith(localChangesBackup?: "manual_apply" | "auto_apply" | false): EntityCollection {
+    return {
+        id: "products",
+        name: "Products",
+        path: "products",
+        properties: {},
+        localChangesBackup
+    } as EntityCollection;
+}
+
+describe("getLocalChangesBackup", () => {
+
+    it("should default to manual_apply when not set", () => {
+        expect(getLocalChangesBackup(collectionWith(undefined))).toEqual("manual_apply");
+    });
+
+    it("should return manual_apply when explicitly set", () => {
+        expect(getLocalChangesBackup(collectionWith("manual_apply"))).toEqual("manual_apply");
+    });
+
+    it("should return auto_apply when explicitly set", () => {
+        expect(getLocalChangesBackup(collectionWith("auto_apply"))).toEqual("auto_apply");
+    });
+
+    it("should return false when explicitly disabled, and not fall back to the default", () => {
+        expect(getLocalChangesBackup(collectionWith(false))).toEqual(false);
+    });
+
+});

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

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

package/src/util/entity_cache.ts

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

package/src/util/index.ts

@@ -6,6 +6,7 @@ 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";

package/src/util/navigation_from_path.ts

@@ -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,6 +34,8 @@ 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>;
 }
@@ -49,6 +55,7 @@ export function getNavigationEntriesFromPath(props: {
     currentFullPath?: string,
     currentFullIdPath?: string,
     currentFullUrlPath?: string,
+    currentPathSegments?: string[],
     contextEntityViews?: EntityCustomView<any>[]
 }): NavigationViewInternal [] {
 
@@ -57,7 +64,8 @@ export function getNavigationEntriesFromPath(props: {
         collections = [],
         currentFullPath,
         currentFullIdPath,
-        currentFullUrlPath
+        currentFullUrlPath,
+        currentPathSegments = []
     } = props;
 
     const subpaths = removeInitialAndTrailingSlashes(path).split("/");
@@ -83,12 +91,16 @@ export function getNavigationEntriesFromPath(props: {
             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: collectionUrlPath,
                 fullIdPath,
+                pathSegments: collectionSegments,
                 collection
             });
             const restOfThePath = removeInitialAndTrailingSlashes(removeInitialAndTrailingSlashes(path).replace(subpathCombination, ""));
@@ -98,12 +110,16 @@ export function getNavigationEntriesFromPath(props: {
                 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: fullUrlPath,
+                    pathSegments: collectionSegments,
                     parentCollection: collection
                 });
                 if (nextSegments.length > 1) {
@@ -123,6 +139,7 @@ export function getNavigationEntriesFromPath(props: {
                             entityId: entityId,
                             fullIdPath,
                             fullPath: fullUrlPath + "/" + customView.key,
+                            pathSegments: collectionSegments,
                             view: customView
                         });
                     } else if (collection.subcollections) {
@@ -130,8 +147,14 @@ 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
                         }));
                     }