@firecms/core 3.3.0 → 3.4.0-canary.2575a08

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

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