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

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,6 +139,9 @@ export function sanitizeData<M extends Record<string, any>>
 }
 
 export function getReferenceFrom<M extends Record<string, any>>(entity: Entity<M>): EntityReference {
+    if (!entity) {
+        throw new Error("getReferenceFrom: entity is null or undefined");
+    }
     return new EntityReference(entity.id, entity.path, entity.databaseId);
 }
 
@@ -196,3 +201,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,5 +1,5 @@
 import { EntityCollection, EntityReference } from "../types";
-import { getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
+import { decodeEntityId, getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
 
 export function getParentReferencesFromPath(props: {
     path: string,
@@ -31,7 +31,9 @@ export function getParentReferencesFromPath(props: {
             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));
                 if (nextSegments.length > 1) {

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