@firecms/core 3.0.0-beta.10 → 3.0.0-beta.12

package/src/types/navigation.ts

@@ -5,6 +5,7 @@ import { EntityReference } from "./entities";
 /**
  * Controller that includes the resolved navigation and utility methods and
  * attributes.
+ * This controller holds the state of the navigation including the collections.
  * @group Models
  */
 export type NavigationController<EC extends EntityCollection = EntityCollection<any>> = {
@@ -56,8 +57,8 @@ 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.
      */
-    getCollection: (pathOrId: string,
-                    includeUserOverride?: boolean) => EC | undefined;
+    getCollection: (pathOrId: string, includeUserOverride?: boolean) => EC | undefined;
+
     /**
      * Get the collection configuration from its parent ids.
      */
@@ -69,12 +70,14 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     getCollectionFromPaths: (pathSegments: string[]) => EC | undefined;
 
     /**
-     * Default path under the navigation routes of the CMS will be created
+     * Default path under the navigation routes of the CMS will be created.
+     * Defaults to '/'. You may want to change this `basepath` to 'admin' for example.
      */
     basePath: string;
 
     /**
-     * Default path under the collection routes of the CMS will be created
+     * Default path under the collection routes of the CMS will be created.
+     * It defaults to '/c'
      */
     baseCollectionPath: string;
 
@@ -87,16 +90,6 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      */
     urlPathToDataPath: (cmsPath: string) => string;
 
-    /**
-     * Convert a collection or entity path to a URL path
-     * @param path
-     */
-    buildCMSUrlPath: (path: string) => string;
-
-    buildUrlEditCollectionPath: (props: {
-        path: string
-    }) => string;
-
     /**
      * Base url path for the home screen
      */
@@ -117,10 +110,11 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     buildUrlCollectionPath: (path: string) => string;
 
     /**
-     * Turn a path with aliases into a resolved path
+     * 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)
      * @param pathWithAliases
      */
-    resolveAliasesFrom: (pathWithAliases: string) => string;
+    resolveIdsFrom: (pathWithAliases: string) => string;
 
     /**
      * Call this method to recalculate the navigation
@@ -144,8 +138,34 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      * @param ids
      */
     convertIdsToPaths: (ids: string[]) => string[];
+
+    /**
+     * A function to navigate to a specified route or URL.
+     *
+     * @param {string} to - The target route or URL to navigate to.
+     * @param {NavigateOptions} [options] - Optional configuration settings for navigation, such as replace behavior or state data.
+     */
+    navigate: (to: string, options?: NavigateOptions) => void;
+
 }
 
+export interface NavigateOptions {
+    replace?: boolean;
+    state?: any;
+    preventScrollReset?: boolean;
+    relative?: "route" | "path";
+    flushSync?: boolean;
+    viewTransition?: boolean;
+}
+
+// currently not used, in favor of a single blocker in `FireCMSRoute`
+export type NavigationBlocker = {
+    updateBlockListener: (path: string, block: boolean, basePath?: string) => () => void;
+    isBlocked: (path: string) => boolean;
+    proceed?: () => void;
+    reset?: () => void;
+};
+
 /**
  * Custom additional views created by the developer, added to the main
  * navigation.

package/src/types/permissions.ts

@@ -32,7 +32,7 @@ export interface Permissions {
  * Props passed to a {@link PermissionsBuilder}
  * @group Models
  */
-export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCollection, UserType extends User = User, M extends object = InferCollectionType<EC>> {
+export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCollection, USER extends User = User, M extends object = InferCollectionType<EC>> {
     /**
      * Entity being edited, might be null in some cases, when the operation
      * refers to the collection.
@@ -54,7 +54,7 @@ export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCol
     /**
      * Logged in user
      */
-    user: UserType | null;
+    user: USER | null;
 
     /**
      * Collection these permissions apply to
@@ -64,7 +64,7 @@ export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCol
     /**
      * Auth controller
      */
-    authController: AuthController<UserType>;
+    authController: AuthController<USER>;
 }
 
 /**
@@ -72,10 +72,10 @@ export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCol
  * based on the logged user or collection.
  * @group Models
  */
-export type PermissionsBuilder<EC extends EntityCollection = EntityCollection, UserType extends User = User, M extends object = InferCollectionType<EC>> =
+export type PermissionsBuilder<EC extends EntityCollection = EntityCollection, USER extends User = User, M extends object = InferCollectionType<EC>> =
     (({
           pathSegments,
           user,
           collection,
           authController
-      }: PermissionsBuilderProps<EC, UserType, M>) => Permissions | undefined);
+      }: PermissionsBuilderProps<EC, USER, M>) => Permissions | undefined);

package/src/types/plugins.tsx

@@ -166,7 +166,7 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
  *
  * @group Models
  */
-export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, any> = any, UserType extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
+export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, any> = any, USER extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
     /**
      * Collection path of this entity. This is the full path, like
      * `users/1234/addresses`
@@ -181,20 +181,21 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
     /**
      * Context of the app status
      */
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 
     extraProps?: EP;
 
 }
 
-export interface PluginFormActionProps<UserType extends User = User, EC extends EntityCollection = EntityCollection> {
+export interface PluginFormActionProps<USER extends User = User, EC extends EntityCollection = EntityCollection> {
     entityId?: string;
     path: string;
     status: EntityStatus;
     collection: EC;
     formContext?: FormContext<any>;
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
     currentEntityId?: string;
+    openEntityMode: "side_panel" | "full_screen";
 }
 
 export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Record<string, any> = any, EC extends EntityCollection<M> = EntityCollection<M>> = {
@@ -207,11 +208,11 @@ export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Reco
     collection?: EC;
 };
 
-export interface PluginGenericProps<UserType extends User = User> {
-    context: FireCMSContext<UserType>;
+export interface PluginGenericProps<USER extends User = User> {
+    context: FireCMSContext<USER>;
 }
 
-export interface PluginHomePageAdditionalCardsProps<UserType extends User = User> {
+export interface PluginHomePageAdditionalCardsProps<USER extends User = User> {
     group?: string;
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 }

package/src/types/properties.ts

@@ -156,6 +156,12 @@ export interface BaseProperty<T extends CMSType, CustomProps = any> {
      * save the new config. The saved config will then become the source of truth.
      */
     editable?: boolean;
+
+    /**
+     * A number between 0 and 100 that indicates the width of the field in the form view.
+     * It defaults to 100, but you can set it to 50 to have two fields in the same row.
+     */
+    widthPercentage?: number;
 }
 
 /**
@@ -285,14 +291,14 @@ export type PropertyBuilder<T extends CMSType = any, M extends Record<string, an
 /**
  * @group Entity properties
  */
-export type PropertyOrBuilder<T extends CMSType = CMSType, M extends Record<string, any> = Record<string, any>> =
+export type PropertyOrBuilder<T extends CMSType = CMSType, M extends Record<string, any> = any> =
     Property<T>
     | PropertyBuilder<T, M>;
 
 /**
  * @group Entity properties
  */
-export type PropertiesOrBuilders<M extends Record<string, any> = Record<string, any>> =
+export type PropertiesOrBuilders<M extends Record<string, any> = any> =
     {
         [k in keyof M]: PropertyOrBuilder<M[k], M>;
     };
@@ -371,7 +377,7 @@ export interface StringProperty extends BaseProperty<string> {
 
     /**
      * You can specify a `Storage` configuration. It is used to
-     * indicate that this string refers to a path in Google Cloud Storage.
+     * indicate that this string refers to a path in your storage provider.
      */
     storage?: StorageConfig;
 
@@ -469,6 +475,12 @@ export interface ArrayProperty<T extends ArrayT[] = any[], ArrayT extends CMSTyp
      */
     expanded?: boolean;
 
+    /**
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel.
+     */
+    minimalistView?: boolean;
+
 }
 
 /**
@@ -517,6 +529,12 @@ export interface MapProperty<T extends Record<string, CMSType> = Record<string,
      */
     spreadChildren?: boolean;
 
+    /**
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel. Note that this will also hide the title of this property.
+     */
+    minimalistView?: boolean;
+
     /**
      * Should the field be initially expanded. Defaults to `true`
      */

package/src/types/property_config.tsx

@@ -23,8 +23,6 @@ export type PropertyConfig<T extends CMSType = any> = {
      * Default config for the property.
      * This property or builder will be used as the base values for the resulting property.
      * You can also use a builder function to generate the base property.
-     * You can use a builder function to generate the property based on the values or the path.
-     * You can also define a custom Field as a React component to be used for this property.
      */
     property: PropertyOrBuilder<T>;
 

package/src/types/side_dialogs_controller.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { EntityFormProps } from "../form";
 
 /**
  * Controller to open the side dialog
@@ -78,4 +79,5 @@ export interface SideDialogPanelProps {
      * Use this prop to store additional data in the panel
      */
     additional?: any;
+
 }

package/src/types/side_entity_controller.tsx

@@ -2,6 +2,7 @@ import { EntityCollection } from "./collections";
 import { ResolvedEntityCollection } from "./resolved_entities";
 import { Entity } from "./entities";
 import { EntityOverrides } from "./entity_overrides";
+import { EntityFormProps } from "../form";
 
 /**
  * Props used to open a side dialog
@@ -28,7 +29,7 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      * Open the entity with a selected sub-collection view. If the panel for this
      * entity was already open, it is replaced.
      */
-    selectedSubPath?: string;
+    selectedTab?: string;
 
     /**
      * Use this prop to override the width of the form view.
@@ -66,6 +67,10 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      */
     closeOnSave?: boolean;
 
+    /**
+     * Override some form properties
+     */
+    formProps?: Partial<EntityFormProps<M>>;
 }
 
 /**

package/src/types/user.ts

@@ -41,4 +41,6 @@ export type User = {
      */
     roles?: Role[];
 
+    getIdToken?: (forceRefresh?: boolean) => Promise<string>;
+
 };

package/src/util/builders.ts

@@ -26,10 +26,12 @@ import {
  * @param collection
  * @group Builder
  */
-export function buildCollection<M extends Record<string, any> = any,
-    UserType extends User = User>(
-    collection: EntityCollection<M, UserType>
-): EntityCollection<M, UserType> {
+export function buildCollection<
+    M extends Record<string, any> = any,
+    USER extends User = User>
+(
+    collection: EntityCollection<M, USER>
+): EntityCollection<M, USER> {
     return collection;
 }
 
@@ -39,7 +41,7 @@ export function buildCollection<M extends Record<string, any> = any,
  * @param property
  * @group Builder
  */
-export function buildProperty<T extends CMSType = CMSType, P extends PropertyOrBuilder<T> = PropertyOrBuilder<T>, M extends Record<string, any> = Record<string, any>>(
+export function buildProperty<T extends CMSType = CMSType, P extends PropertyOrBuilder<T> = PropertyOrBuilder<T>, M extends Record<string, any> = any>(
     property: P
 ):
     P extends StringProperty ? StringProperty :
@@ -120,9 +122,9 @@ export function buildEntityCallbacks<M extends Record<string, any> = any>(
  * @param additionalFieldDelegate
  * @group Builder
  */
-export function buildAdditionalFieldDelegate<M extends Record<string, any>, UserType extends User = User>(
-    additionalFieldDelegate: AdditionalFieldDelegate<M, UserType>
-): AdditionalFieldDelegate<M, UserType> {
+export function buildAdditionalFieldDelegate<M extends Record<string, any>, USER extends User = User>(
+    additionalFieldDelegate: AdditionalFieldDelegate<M, USER>
+): AdditionalFieldDelegate<M, USER> {
     return additionalFieldDelegate;
 }
 

package/src/util/entities.ts

@@ -40,13 +40,15 @@ export function getDefaultValuesFor<M extends Record<string, any>>(properties: P
     if (!properties) return {};
     return Object.entries(properties)
         .map(([key, property]) => {
+            if (!property) return {};
             const value = getDefaultValueFor(property as PropertyOrBuilder);
             return value === undefined ? {} : { [key]: value };
         })
         .reduce((a, b) => ({ ...a, ...b }), {}) as EntityValues<M>;
 }
 
-export function getDefaultValueFor(property: PropertyOrBuilder) {
+export function getDefaultValueFor(property?: PropertyOrBuilder) {
+    if (!property) return undefined;
     if (isPropertyBuilder(property)) return undefined;
     if (property.defaultValue || property.defaultValue === null) {
         return property.defaultValue;

package/src/util/entity_actions.ts

@@ -0,0 +1,28 @@
+import { EntityAction } from "../types";
+
+const reservedKeys = ["edit", "copy", "delete"];
+
+export function mergeEntityActions(currentActions: EntityAction[], newActions: EntityAction[]): EntityAction[] {
+    // given the current actions, replace the ones with the same key
+    // and append the new ones
+    const updatedActions: EntityAction[] = [];
+    currentActions.forEach(action => {
+        const newAction = newActions.find(a => a.key === action.key);
+        if (newAction) {
+            const mergedAction = {
+                ...action,
+                ...newAction
+            }
+            updatedActions.push(mergedAction);
+        } else {
+            updatedActions.push(action);
+        }
+    });
+    newActions.forEach(action => {
+        if (!currentActions.find(a => a.key === action.key) && (!action.key || !reservedKeys.includes(action.key))) {
+            updatedActions.push(action);
+        }
+    });
+    return updatedActions;
+
+}

package/src/util/entity_cache.ts

@@ -0,0 +1,204 @@
+import { EntityReference, GeoPoint, Vector } from "../types";
+
+// Define a unique prefix for entity keys in localStorage to avoid key collisions
+const LOCAL_STORAGE_PREFIX = "entity_cache::";
+
+// In-memory cache to store entities for quick access
+const entityCache: Map<string, object> = new Map();
+
+// Check `localStorage` availability once during initialization
+const isLocalStorageAvailable = typeof localStorage !== "undefined";
+
+// Define custom replacer for JSON.stringify
+function customReplacer(key: string): any {
+
+    // @ts-ignore
+    const value = this[key];
+
+    // Handle Date objects
+    // @ts-ignore
+    if (value instanceof Date) {
+        return { __type: "Date", value: value.toISOString() };
+    }
+
+    // Handle EntityReference
+    // @ts-ignore
+    if (value instanceof EntityReference) {
+        return { __type: "EntityReference", id: value.id, path: value.path };
+    }
+
+    // Handle GeoPoint
+    // @ts-ignore
+    if (value instanceof GeoPoint) {
+        return { __type: "GeoPoint", latitude: value.latitude, longitude: value.longitude };
+    }
+
+    // Handle Vector
+    // @ts-ignore
+    if (value instanceof Vector) {
+        return { __type: "Vector", value: value.value };
+    }
+
+    return value;
+}
+
+// Define custom reviver for JSON.parse
+function customReviver(key: string, value: any): any {
+    if (value && typeof value === "object" && "__type" in value) {
+        switch (value.__type) {
+            case "Date":
+                return new Date(value.value);
+            case "EntityReference":
+                return new EntityReference(value.id, value.path);
+            case "GeoPoint":
+                return new GeoPoint(value.latitude, value.longitude);
+            case "Vector":
+                return new Vector(value.value);
+            default:
+                return value;
+        }
+    }
+    return value;
+}
+
+// Initialize the in-memory cache by loading entities from `localStorage`
+if (isLocalStorageAvailable) {
+    try {
+        // Iterate over all keys in localStorage to find those with the specified prefix
+        for (let i = 0; i < localStorage.length; i++) {
+            const fullKey = localStorage.key(i);
+            if (fullKey && fullKey.startsWith(LOCAL_STORAGE_PREFIX)) {
+                const path = fullKey.substring(LOCAL_STORAGE_PREFIX.length);
+                const entityString = localStorage.getItem(fullKey);
+                if (entityString) {
+                    try {
+                        const entity: object = JSON.parse(entityString, customReviver);
+                        entityCache.set(path, entity);
+                    } catch (parseError) {
+                        console.error(
+                            `Failed to parse entity for path "${path}" from localStorage:`,
+                            parseError
+                        );
+                    }
+                }
+            }
+        }
+    } catch (error) {
+        console.error("Error accessing localStorage during initialization:", error);
+    }
+}
+
+/**
+ * Saves data to the in-memory cache and persists it individually in `localStorage`.
+ * @param path - The unique path/key for the data.
+ * @param data - The data to cache and persist.
+ */
+export function saveEntityToCache(path: string, data: object): void {
+    // Update the in-memory cache
+    entityCache.set(path, data);
+
+    // Persist the data individually in localStorage
+    if (isLocalStorageAvailable) {
+        try {
+            const key = LOCAL_STORAGE_PREFIX + path;
+            const entityString = JSON.stringify(data, customReplacer);
+            localStorage.setItem(key, entityString);
+        } catch (error) {
+            console.error(
+                `Failed to save entity for path "${path}" to localStorage:`,
+                error
+            );
+        }
+    }
+}
+
+/**
+ * Retrieves an entity from the in-memory cache or `localStorage`.
+ * If the entity is not in the cache but exists in `localStorage`, it loads it into the cache.
+ * @param path - The unique path/key for the entity.
+ * @returns The cached entity or `undefined` if not found.
+ */
+export function getEntityFromCache(path: string): object | undefined {
+
+    // Attempt to retrieve the entity from the in-memory cache
+    if (entityCache.has(path)) {
+        return entityCache.get(path);
+    }
+
+    // If not in the cache, attempt to load it from localStorage
+    if (isLocalStorageAvailable) {
+        try {
+            const key = LOCAL_STORAGE_PREFIX + path;
+            const entityString = localStorage.getItem(key);
+            if (entityString) {
+                const entity: object = JSON.parse(entityString, customReviver);
+                entityCache.set(path, entity); // Update the cache
+                return entity;
+            }
+        } catch (error) {
+            console.error(
+                `Failed to load entity for path "${path}" from localStorage:`,
+                error
+            );
+        }
+    }
+
+    // Entity not found
+    return undefined;
+}
+
+export function hasEntityInCache(path: string): boolean {
+    return entityCache.has(path);
+}
+
+/**
+ * Removes an entity from both the in-memory cache and `localStorage`.
+ * @param path - The unique path/key for the entity to remove.
+ */
+export function removeEntityFromCache(path: string): void {
+
+
+    console.debug("Removing entity from cache", path);
+
+    // Remove from the in-memory cache
+    entityCache.delete(path);
+
+    // Remove from localStorage
+    if (isLocalStorageAvailable) {
+        try {
+            const key = LOCAL_STORAGE_PREFIX + path;
+            localStorage.removeItem(key);
+        } catch (error) {
+            console.error(
+                `Failed to remove entity for path "${path}" from localStorage:`,
+                error
+            );
+        }
+    }
+}
+
+/**
+ * Clears the entire in-memory cache and removes all related entities from `localStorage`.
+ */
+export function clearEntityCache(): void {
+    // Clear the in-memory cache
+    entityCache.clear();
+
+    // Remove all entities with the specified prefix from localStorage
+    if (isLocalStorageAvailable) {
+        try {
+            const keysToRemove: string[] = [];
+            for (let i = 0; i < localStorage.length; i++) {
+                const fullKey = localStorage.key(i);
+                if (fullKey && fullKey.startsWith(LOCAL_STORAGE_PREFIX)) {
+                    keysToRemove.push(fullKey);
+                }
+            }
+
+            // Remove the keys after collecting them to avoid issues while iterating
+            keysToRemove.forEach((key) => localStorage.removeItem(key));
+        } catch (error) {
+            console.error("Failed to clear entity cache from localStorage:", error);
+        }
+    }
+}

package/src/util/icon_list.ts

@@ -15,6 +15,7 @@ const map = iconKeys
 export const iconsSearch = new Fuse(map, {
     isCaseSensitive: false,
     shouldSort: true,
+    ignoreLocation: true,
     distance: 0,
     keys: ["key", "synonyms"]
 })

package/src/util/icon_synonyms.ts

@@ -1222,7 +1222,6 @@ export const iconSynonyms = {
     picture_in_picture_alt: "cropped overlap photo position shape",
     pie_chart: "analytics bars data diagram infographic measure metrics statistics tracking",
     pie_chart_outline: "analytics bars data diagram infographic measure metrics statistics tracking",
-    pie_chart_outlined: "graph",
     pin: "1 2 3 digit key login logout number password pattern security star symbol unlock",
     pinch: "arrows compress direction finger grasp hand navigation nip squeeze tweak",
     pin_drop: "destination direction gps location maps navigation place stop",

package/src/util/icons.tsx

@@ -1,16 +1,16 @@
 import React from "react";
 import { hashString } from "./hash";
-import { coolIconKeys, Icon, iconKeys } from "@firecms/ui";
+import { coolIconKeys, Icon, IconColor, iconKeys } from "@firecms/ui";
 import { slugify } from "./strings";
 import equal from "react-fast-compare"
 
-export function getIcon(iconKey?: string, className?: string): React.ReactElement | undefined {
+export function getIcon(iconKey?: string, className?: string, color?:IconColor): React.ReactElement | undefined {
     if (!iconKey) return undefined;
     iconKey = slugify(iconKey);
     if (!(iconKey in iconKeysMap)) {
         return undefined;
     }
-    return iconKey in iconKeysMap ? <Icon iconKey={iconKey} size={"medium"} className={className}/> : undefined;
+    return iconKey in iconKeysMap ? <Icon iconKey={iconKey} size={"medium"} className={className} color={color}/> : undefined;
 }
 
 export type IconViewProps = {
@@ -25,12 +25,16 @@ export const IconForView = React.memo(
     function IconForView({
                              collectionOrView,
                              className,
-                             size = "medium"
+                             color,
+                             size = "medium",
                          }: {
-        collectionOrView?: IconViewProps, className?: string, size?: "smallest" | "small" | "medium" | "large" | number,
+        collectionOrView?: IconViewProps,
+        color?: IconColor,
+        className?: string,
+        size?: "smallest" | "small" | "medium" | "large" | number,
     }): React.ReactElement {
         if (!collectionOrView) return <></>;
-        const icon = getIcon(collectionOrView.icon, className);
+        const icon = getIcon(collectionOrView.icon, className, color);
         if (collectionOrView?.icon && icon)
             return icon;
 
@@ -51,9 +55,9 @@ export const IconForView = React.memo(
         if (!key)
             key = coolIconKeys[hashString(collectionOrView.path) % iconsCount];
 
-        return <Icon iconKey={key} size={size} className={className}/>;
+        return <Icon iconKey={key} size={size} className={className} color={color}/>;
     }, (prevProps, nextProps) => {
-        return equal(prevProps.collectionOrView?.icon, nextProps.collectionOrView?.icon);
+        return equal(prevProps.collectionOrView?.icon, nextProps.collectionOrView?.icon) && equal(prevProps.color, nextProps.color);
     });
 
 const iconKeysMap: Record<string, string> = iconKeys.reduce((acc: Record<string, string>, key) => {