@firecms/core 3.0.0-rc.1 → 3.0.0-rc.3

package/src/preview/components/UserPreview.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+import { PropertyPreviewProps } from "../PropertyPreviewProps";
+import { useInternalUserManagementController } from "../../hooks";
+import { UserDisplay } from "../../components/UserDisplay";
+import { EmptyValue } from "./EmptyValue";
+import { Typography } from "@firecms/ui";
+
+/**
+ * Preview component for displaying user information.
+ * This is a simple wrapper around UserDisplay.
+ *
+ * @group Preview components
+ */
+export function UserPreview({ value }: PropertyPreviewProps<string>) {
+    const { getUser } = useInternalUserManagementController();
+
+    if (!value) {
+        return <EmptyValue/>;
+    }
+
+    const user = getUser(value);
+    if (!user) {
+        return <Typography variant={"caption"} color={"secondary"}>User not found: {value}</Typography>;
+    }
+
+    return <UserDisplay user={user}/>;
+}

package/src/preview/index.ts

@@ -25,3 +25,4 @@ export * from "./components/EnumValuesChip";
 export * from "./components/EmptyValue";
 export * from "./components/ImagePreview";
 export * from "./components/ReferencePreview";
+export * from "./components/UserPreview";

package/src/preview/property_previews/ArrayPropertyPreview.tsx

@@ -42,7 +42,7 @@ export function ArrayPropertyPreview({
     const childSize: PreviewSize = size === "medium" ? "medium" : "small";
 
     return (
-        <div className="flex flex-col gap-2">
+        <div className="w-full flex flex-col gap-2">
             {values &&
                 values.map((value, index) => {
                         const of: ResolvedProperty = property.resolvedProperties[index] ??

package/src/preview/property_previews/MapPropertyPreview.tsx

@@ -68,7 +68,7 @@ export function MapPropertyPreview<T extends Record<string, any> = Record<string
                                 <div
                                     className="min-w-[140px] w-[25%] py-1">
                                     <Typography variant={"caption"}
-                                                className={"font-mono break-words"}
+                                                className={"break-words font-semibold"}
                                                 color={"secondary"}>
                                         {childProperty.name}
                                     </Typography>
@@ -121,7 +121,7 @@ export function KeyValuePreview({ value }: { value: any }) {
                             key={`table-cell-title-${key}-${key}`}
                             className="min-w-[140px] w-[25%] py-1">
                             <Typography variant={"caption"}
-                                        className={"font-mono break-words"}
+                                        className={"font-semibold break-words"}
                                         color={"secondary"}>
                                 {key}
                             </Typography>

package/src/preview/property_previews/NumberPropertyPreview.tsx

@@ -16,12 +16,12 @@ export function NumberPropertyPreview({
         const enumKey = value;
         const enumValues = enumToObjectEntries(property.enumValues);
         if (!enumValues)
-            return <>{value}</>;
+            return <span className={size === "small" ? "text-sm" : ""}>{value}</span>;
         return <EnumValuesChip
             enumKey={enumKey}
             enumValues={enumValues}
             size={size !== "medium" ? "small" : "medium"}/>;
     } else {
-        return <>{value}</>;
+        return <span className={size === "small" ? "text-sm" : ""}>{value}</span>;
     }
 }

package/src/types/collections.ts

@@ -69,6 +69,8 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * https://fonts.google.com/icons
      * e.g. 'account_tree' or 'person'.
      * Find all the icons in https://firecms.co/docs/icons
+     * You can also pass a React node if you want to render a custom icon.
+     * If not specified, a default icon will be used.
      */
     icon?: string | React.ReactNode;
 
@@ -350,6 +352,18 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * This prop has no effect if the history plugin is not enabled
      */
     history?: boolean;
+
+    /**
+     * Should local changes be backed up in local storage, to prevent data loss on
+     * accidental navigations.
+     * - `manual_apply`: When the user navigates back to an entity with local changes,
+     *   they will be prompted to restore the changes.
+     * - `auto_apply`: When the user navigates back to an entity with local changes,
+     *   the changes will be automatically applied.
+     * - `false`: Local changes will not be backed up.
+     * Defaults to `manual_apply`.
+     */
+    localChangesBackup?: "manual_apply" | "auto_apply" | false;
 }
 
 /**

package/src/types/entities.ts

@@ -50,9 +50,15 @@ export class EntityReference {
      */
     readonly path: string;
 
-    constructor(id: string, path: string) {
+    /**
+     * Optional database ID where the entity is stored (if multiple databases are used)
+     */
+    readonly databaseId?: string;
+
+    constructor(id: string, path: string, databaseId?: string) {
         this.id = id;
         this.path = path;
+        this.databaseId = databaseId;
     }
 
     get pathWithId() {

package/src/types/firecms.tsx

@@ -13,6 +13,7 @@ import { UserConfigurationPersistence } from "./local_config_persistence";
 import { FireCMSPlugin } from "./plugins";
 import { CMSAnalyticsEvent } from "./analytics";
 import { EntityAction } from "./entity_actions";
+import { InternalUserManagement } from "./internal_user_management";
 
 /**
  * Use this callback to build entity collections dynamically.
@@ -139,6 +140,7 @@ export type FireCMSProps<USER extends User> = {
      * Use plugins to modify the behaviour of the CMS.
      * DEPRECATED: use the `plugins` prop in the `useBuildNavigationController` instead.
      * This prop will work as a fallback for the `plugins` prop in the `useBuildNavigationController`.
+     * @deprecated
      */
     plugins?: FireCMSPlugin<any, any, any>[];
 
@@ -153,6 +155,20 @@ export type FireCMSProps<USER extends User> = {
      */
     entityLinkBuilder?: EntityLinkBuilder;
 
+    /**
+     * You can use this props to provide your own user management implementation.
+     * Note that this will not affect the UI, but it will be used to show user information
+     * in various places of the CMS, for example, to show who created or modified an entity,
+     * or to assign ownership of an entity.
+     *
+     * You can also use this data to be retrieved in your custom properties,
+     * for example, to show a list of users in a dropdown.
+     *
+     * If you are using the FireCMS user management plugin, this
+     * prop will be implemented automatically.
+     */
+    userManagement?: InternalUserManagement
+
     components?: {
 
         /**

package/src/types/firecms_context.tsx

@@ -10,6 +10,7 @@ import { SideDialogsController } from "./side_dialogs_controller";
 import { DialogsController } from "./dialogs_controller";
 import { CustomizationController } from "./customization_controller";
 import { AnalyticsController } from "./analytics_controller";
+import { InternalUserManagement } from "./internal_user_management";
 
 /**
  * Context that includes the internal controllers and contexts used by the app.
@@ -80,4 +81,20 @@ export type FireCMSContext<USER extends User = User, AuthControllerType extends
      */
     analyticsController?: AnalyticsController;
 
+    /**
+     * This section is used to manage users in the CMS.
+     * It is used to show user information in various places of the CMS,
+     * for example, to show who created or modified an entity,
+     * or to assign ownership of an entity.
+     *
+     * In the base CMS, this information is not used for access control.
+     * You can pass your own implementation of this section, to populate
+     * the dropdown of users when assigning ownership of an entity,
+     * or to show more information about the user.
+     *
+     * If you are using the FireCMS user management plugin, this
+     * section will be implemented automatically.
+     */
+    userManagement: InternalUserManagement<USER>
+
 };

package/src/types/index.ts

@@ -13,6 +13,7 @@ export * from "./fields";
 export * from "./property_config";
 export * from "./datasource";
 export * from "./entity_link_builder";
+export * from "./internal_user_management";
 export * from "./side_entity_controller";
 export * from "./side_dialogs_controller";
 export * from "./firecms_context";

package/src/types/internal_user_management.ts

@@ -0,0 +1,24 @@
+import { User } from "./user";
+
+export type InternalUserManagement<USER extends User = User> = {
+
+    /**
+     * List of users to be managed by the CMS.
+     */
+    users: USER[];
+
+    /**
+     * Function to get a user by its uid. This is used to show
+     * user information when assigning ownership of an entity.
+     *
+     * You can pass your own implementation if you want to show
+     * more information about the user.
+     *
+     * If you are using the FireCMS user management plugin, this
+     * function will be implemented automatically.
+     *
+     * @param uid
+     */
+    getUser: (uid: string) => USER | null;
+
+}

package/src/types/plugins.tsx

@@ -8,6 +8,7 @@ import { CMSType, Property } from "./properties";
 import { EntityStatus } from "./entities";
 import { ResolvedProperty } from "./resolved_entities";
 import { NavigationGroupMapping } from "./navigation";
+import { InternalUserManagement } from "./internal_user_management";
 
 /**
  * Interface used to define plugins for FireCMS.
@@ -43,6 +44,8 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         props?: PROPS;
     };
 
+    userManagement?: InternalUserManagement
+
     homePage?: {
 
         /**

package/src/types/properties.ts

@@ -155,6 +155,10 @@ export interface BaseProperty<T extends CMSType, CustomProps = any> {
     /**
      * Should this property be editable. If set to true, the user will be able to modify the property and
      * save the new config. The saved config will then become the source of truth.
+     * Defaults to `true.
+     * This props is only useful when you are using the collection editor to modify collection
+     * configurations from the CMS itself. You can also use the `editable` prop in the
+     * `EntityCollection` interface to disable the edition of all properties in a collection.
      */
     editable?: boolean;
 
@@ -388,6 +392,16 @@ export interface StringProperty extends BaseProperty<string> {
      */
     storage?: StorageConfig;
 
+    /**
+     * This property is used to indicate that the string is a user ID, and
+     * it will be rendered as a user picker.
+     * Note that the user ID needs to be the one used in your authentication
+     * provider, e.g. Firebase Auth.
+     * You can also use a property builder to specify the user path dynamically
+     * based on other values of the entity.
+     */
+    userSelect?: boolean;
+
     /**
      * If the value of this property is a URL, you can set this flag to true
      * to add a link, or one of the supported media types to render a preview
@@ -765,8 +779,16 @@ export type StorageConfig = {
     /**
      * Use client side image compression and resizing
      * Will only be applied to these MIME types: image/jpeg, image/png and image/webp
+     * @deprecated Use `imageResize` instead
      */
-    imageCompression?: ImageCompression;
+    imageCompression?: ImageResize;
+
+    /**
+     * Advanced image resizing and cropping configuration.
+     * Applied before upload to optimize storage and bandwidth.
+     * Only applies to image MIME types: image/jpeg, image/png, image/webp
+     */
+    imageResize?: ImageResize;
 
     /**
      * Specific metadata set in your uploaded file.
@@ -903,19 +925,36 @@ export type FileType =
     | "font/*"
     | string;
 
-export interface ImageCompression {
+export interface ImageResize {
+    /**
+     * Maximum width in pixels. Image will be scaled down proportionally if wider.
+     */
+    maxWidth?: number;
+
     /**
-     * New image max height (ratio is preserved)
+     * Maximum height in pixels. Image will be scaled down proportionally if taller.
      */
     maxHeight?: number;
 
     /**
-     * New image max width (ratio is preserved)
+     * Resize mode determines how the image fits within maxWidth/maxHeight bounds.
+     * - `contain`: Scale down to fit within bounds, preserving aspect ratio (default)
+     * - `cover`: Scale to fill bounds, preserving aspect ratio (may crop)
      */
-    maxWidth?: number;
+    mode?: 'contain' | 'cover';
+
+    /**
+     * Output format for the resized image.
+     * - `original`: Keep the original format (default)
+     * - `jpeg`: Convert to JPEG
+     * - `png`: Convert to PNG
+     * - `webp`: Convert to WebP
+     */
+    format?: 'original' | 'jpeg' | 'png' | 'webp';
 
     /**
-     * A number between 0 and 100. Used for the JPEG compression.(if no compress is needed, just set it to 100)
+     * Quality for lossy formats (JPEG, WebP). Number between 0 and 100.
+     * Higher is better quality but larger file size. Defaults to 80.
      */
     quality?: number;
 }

package/src/types/property_config.tsx

@@ -52,6 +52,7 @@ export type PropertyConfigId =
     "markdown" |
     "url" |
     "email" |
+    "user_select" |
     "select" |
     "multi_select" |
     "number_input" |

package/src/types/user.ts

@@ -37,7 +37,7 @@ export type User = {
     readonly isAnonymous: boolean;
 
     /**
-     *
+     * Custom roles assigned to the user.
      */
     roles?: Role[];
 

package/src/util/collections.ts

@@ -70,3 +70,11 @@ export const applyPermissionsFunctionIfEmpty = (collections: EntityCollection[],
         });
     });
 }
+
+export function getLocalChangesBackup(collection: EntityCollection) {
+    if (!collection.localChangesBackup) {
+        return "manual_apply";
+    }
+
+    return collection.localChangesBackup;
+}

package/src/util/createFormexStub.tsx

@@ -4,6 +4,7 @@ export function createFormexStub<T extends object>(values: T): FormexController<
     const errorMessage = "You are in a read-only context. You cannot modify the formex controller.";
 
     return {
+        debugId: "",
         values,
         initialValues: values,
         touched: {} as Record<string, boolean>,
@@ -19,6 +20,9 @@ export function createFormexStub<T extends object>(values: T): FormexController<
         setValues: () => {
             throw new Error(errorMessage);
         },
+        setTouched(touched: Record<string, boolean>): void {
+            throw new Error(errorMessage);
+        },
         setFieldValue: () => {
             throw new Error(errorMessage);
         },

package/src/util/entities.ts

@@ -142,7 +142,7 @@ 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);
+    return new EntityReference(entity.id, entity.path, entity.databaseId);
 }
 
 export function traverseValuesProperties<M extends Record<string, any>>(

package/src/util/entity_cache.ts

@@ -1,4 +1,5 @@
 import { EntityReference, GeoPoint, Vector } from "../types";
+import { isObject, isPlainObject } from "./objects";
 
 // Define a unique prefix for entity keys in localStorage to avoid key collisions
 const LOCAL_STORAGE_PREFIX = "entity_cache::";
@@ -18,25 +19,40 @@ function customReplacer(key: string): any {
     // Handle Date objects
     // @ts-ignore
     if (value instanceof Date) {
-        return { __type: "Date", value: value.toISOString() };
+        return {
+            __type: "Date",
+            value: value.toISOString()
+        };
     }
 
     // Handle EntityReference
     // @ts-ignore
     if (value instanceof EntityReference) {
-        return { __type: "EntityReference", id: value.id, path: value.path };
+        return {
+            __type: "EntityReference",
+            id: value.id,
+            path: value.path,
+            databaseId: value.databaseId
+        };
     }
 
     // Handle GeoPoint
     // @ts-ignore
     if (value instanceof GeoPoint) {
-        return { __type: "GeoPoint", latitude: value.latitude, longitude: value.longitude };
+        return {
+            __type: "GeoPoint",
+            latitude: value.latitude,
+            longitude: value.longitude
+        };
     }
 
     // Handle Vector
     // @ts-ignore
     if (value instanceof Vector) {
-        return { __type: "Vector", value: value.value };
+        return {
+            __type: "Vector",
+            value: value.value
+        };
     }
 
     return value;
@@ -49,7 +65,7 @@ function customReviver(key: string, value: any): any {
             case "Date":
                 return new Date(value.value);
             case "EntityReference":
-                return new EntityReference(value.id, value.path);
+                return new EntityReference(value.id, value.path, value.databaseId);
             case "GeoPoint":
                 return new GeoPoint(value.latitude, value.longitude);
             case "Vector":
@@ -61,47 +77,21 @@ function customReviver(key: string, value: any): any {
     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);
+            console.log("Saving entity to localStorage:", {
+                key,
+                entityString
+            });
             localStorage.setItem(key, entityString);
         } catch (error) {
             console.error(
@@ -112,19 +102,31 @@ export function saveEntityToCache(path: string, data: object): void {
     }
 }
 
+export function removeEntityFromMemoryCache(path: string): void {
+    entityCache.delete(path);
+}
+
+export function saveEntityToMemoryCache(path: string, data: object): void {
+    entityCache.set(path, data);
+}
+
+export function getEntityFromMemoryCache(path: string): object | undefined {
+    return entityCache.get(path);
+}
+
+export function hasEntityInCache(path: string): boolean {
+    return entityCache.has(path);
+}
+
 /**
  * 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.
+ * @param useLocalStorage
  * @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 {
@@ -132,7 +134,10 @@ export function getEntityFromCache(path: string): object | undefined {
             const entityString = localStorage.getItem(key);
             if (entityString) {
                 const entity: object = JSON.parse(entityString, customReviver);
-                entityCache.set(path, entity); // Update the cache
+                console.log("Loaded entity from localStorage:", {
+                    key,
+                    entity
+                });
                 return entity;
             }
         } catch (error) {
@@ -147,23 +152,11 @@ export function getEntityFromCache(path: string): object | undefined {
     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;
@@ -202,3 +195,29 @@ export function clearEntityCache(): void {
         }
     }
 }
+
+export function flattenKeys(obj: any, prefix = "", result: string[] = []): string[] {
+
+    if (isObject(obj) || Array.isArray(obj)) {
+        const plainObject = isPlainObject(obj);
+        if (!plainObject && prefix) {
+            result.push(prefix);
+        } else {
+            for (const key in obj) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    const newKey = prefix
+                        ? Array.isArray(obj)
+                            ? `${prefix}[${key}]`
+                            : `${prefix}.${key}`
+                        : key;
+                    if (isObject(obj[key]) || Array.isArray(obj[key])) {
+                        flattenKeys(obj[key], newKey, result);
+                    } else {
+                        result.push(newKey);
+                    }
+                }
+            }
+        }
+    }
+    return result;
+}

package/src/util/join_collections.ts

@@ -78,7 +78,6 @@ export function mergeCollection(target: EntityCollection,
                                 modifyCollection?: (props: ModifyCollectionProps) => EntityCollection | void
 ): EntityCollection {
 
-
     const subcollectionsMerged = joinCollectionLists(
         target?.subcollections ?? [],
         source?.subcollections ?? [],
@@ -132,8 +131,9 @@ function mergePropertyOrBuilder(target: PropertyOrBuilder, source: PropertyOrBui
         return target;
     } else {
         const mergedProperty = mergeDeep(target, source);
-        const targetEditable = Boolean(target.editable);
-        const sourceEditable = Boolean(source.editable);
+        const targetEditable = target.editable === undefined ? true : Boolean(target.editable);
+        const sourceEditable = source.editable === undefined ? true : Boolean(source.editable);
+
         if (source.dataType === "map" && source.properties) {
             const targetProperties = ("properties" in target ? target.properties : {}) as PropertiesOrBuilders;
             const sourceProperties = ("properties" in source ? source.properties : {}) as PropertiesOrBuilders;

package/src/util/make_properties_editable.ts

@@ -13,25 +13,3 @@ export function makePropertiesEditable(properties: Properties) {
     });
     return properties;
 }
-
-export function makePropertiesNonEditable(properties: PropertiesOrBuilders): PropertiesOrBuilders {
-    return Object.entries(properties).reduce((acc, [key, property]) => {
-        if (!isPropertyBuilder(property) && property.dataType === "map" && property.properties) {
-            const updated = {
-                ...property,
-                properties: makePropertiesNonEditable(property.properties as PropertiesOrBuilders)
-            };
-            acc[key] = updated;
-        }
-        if (isPropertyBuilder(property)) {
-            acc[key] = property;
-        } else {
-            acc[key] = {
-                ...property,
-                editable: false
-            };
-        }
-        return acc;
-    }, {} as PropertiesOrBuilders);
-
-}