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

package/src/form/components/LocalChangesMenu.tsx

@@ -0,0 +1,144 @@
+import React, { useState } from "react";
+import {
+    Button,
+    CancelIcon,
+    CheckIcon,
+    defaultBorderMixin,
+    Dialog,
+    DialogActions,
+    DialogContent,
+    DialogTitle,
+    KeyboardArrowDownIcon,
+    Menu,
+    MenuItem,
+    Typography,
+    VisibilityIcon,
+    WarningIcon
+} from "@firecms/ui";
+import { FormexController } from "@firecms/formex";
+import { useSnackbarController } from "../../hooks";
+import { mergeDeep } from "../../util";
+import { flattenKeys, removeEntityFromCache } from "../../util/entity_cache";
+import { ResolvedProperties } from "../../types";
+import { PropertyCollectionView } from "../../components/PropertyCollectionView";
+
+interface LocalChangesMenuProps<M extends object> {
+    cacheKey: string;
+    localChangesData: Partial<M>;
+    formex: FormexController<M>;
+    onClearLocalChanges?: () => void;
+    properties: ResolvedProperties<M>;
+}
+
+export function LocalChangesMenu<M extends object>({
+                                                       localChangesData,
+                                                       formex,
+                                                       onClearLocalChanges,
+                                                       cacheKey,
+                                                       properties
+                                                   }: LocalChangesMenuProps<M>) {
+
+    const snackbarController = useSnackbarController();
+    const [previewDialogOpen, setPreviewDialogOpen] = useState(false);
+    const [open, setOpen] = useState(false);
+
+    const handleOpenMenu = () => setOpen(true);
+    const handleCloseMenu = () => setOpen(false);
+
+    const handlePreview = () => {
+        setPreviewDialogOpen(true);
+        handleCloseMenu();
+    };
+
+    const handleApply = () => {
+        const mergedValues = mergeDeep(formex.values, localChangesData);
+        const touched = { ...formex.touched };
+        const previewKeys = flattenKeys(localChangesData);
+        previewKeys.forEach((key) => {
+            touched[key] = true;
+        });
+
+        formex.setTouched(touched);
+        formex.setValues(mergedValues);
+        snackbarController.open({
+            type: "info",
+            message: "Local changes applied to the form"
+        });
+        handleCloseMenu();
+        onClearLocalChanges?.();
+    };
+
+    const handleDiscard = () => {
+        removeEntityFromCache(cacheKey);
+        snackbarController.open({
+            type: "info",
+            message: "Local changes discarded"
+        });
+        handleCloseMenu();
+        onClearLocalChanges?.();
+    };
+
+    return (
+        <>
+            <Menu
+                trigger={
+                    <Button
+                        size={"small"}
+                        className={
+                            "font-semibold text-xs rounded-full px-4 py-1 bg-yellow-200 dark:bg-yellow-900 hover:bg-yellow-300 dark:hover:bg-yellow-800 text-yellow-800 dark:text-yellow-200"
+                        }
+                        onClick={handleOpenMenu}
+                    >
+                        <WarningIcon size={"smallest"} className={"mr-1 text-yellow-600 dark:text-yellow-400"}/>
+                        Unsaved Local changes
+                        <KeyboardArrowDownIcon size={"smallest"}/>
+                    </Button>
+                }
+                open={open}
+                onOpenChange={setOpen}
+            >
+                <div className={"max-w-xs px-4 py-4 text-sm text-gray-700 dark:text-gray-300"}>
+                    This document was edited locally and has unsaved changes. These local changes will be lost if you
+                    don't apply them.
+                </div>
+                <MenuItem dense onClick={handlePreview}><VisibilityIcon size={"small"}/>Preview Changes</MenuItem>
+                <MenuItem dense onClick={handleApply}><CheckIcon size={"small"}/>Apply Changes</MenuItem>
+                <MenuItem dense onClick={handleDiscard}><CancelIcon size={"small"}/>Discard Local Changes</MenuItem>
+            </Menu>
+
+            <Dialog
+                open={previewDialogOpen}
+                onOpenChange={setPreviewDialogOpen}
+                maxWidth={"4xl"}
+            >
+                <DialogTitle variant={"h6"}>Preview Local Changes</DialogTitle>
+                <DialogContent className={"my-4"}>
+                    <Typography variant={"body2"} className={"mb-4"}>
+                        These are the local changes that will be applied to the form.
+                    </Typography>
+                    <div className={`border rounded-lg ${defaultBorderMixin}`} style={{
+                        maxHeight: 520,
+                        overflow: "auto"
+                    }}>
+                        <div className="p-4">
+                            <PropertyCollectionView data={localChangesData}
+                                                    properties={properties as ResolvedProperties}/>
+                        </div>
+                    </div>
+                </DialogContent>
+                <DialogActions>
+                    <Button onClick={() => setPreviewDialogOpen(false)}>Close</Button>
+                    <Button
+                        variant={"filled"}
+                        onClick={() => {
+                            handleApply();
+                            setPreviewDialogOpen(false);
+                        }}
+                    >
+                        Apply changes
+                    </Button>
+                </DialogActions>
+            </Dialog>
+        </>
+    );
+}

package/src/form/index.tsx

@@ -1,4 +1,8 @@
-export * from "./EntityForm";
+export {
+    EntityForm,
+    yupToFormErrors,
+} from "./EntityForm";
+export type { EntityFormProps } from "./EntityForm";
 
 export { SelectFieldBinding } from "./field_bindings/SelectFieldBinding";
 export { MultiSelectFieldBinding } from "./field_bindings/MultiSelectFieldBinding";

package/src/hooks/useBuildNavigationController.tsx

@@ -149,26 +149,10 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
     const allPluginGroups = plugins?.flatMap(plugin => plugin.homePage?.navigationEntries ? plugin.homePage.navigationEntries.map(e => e.name) : []) ?? [];
     const pluginGroups = [...new Set(allPluginGroups)];
 
-    const onNavigationEntriesOrderUpdate = useCallback((entries: NavigationGroupMapping[]) => {
-        if (!plugins) {
-            return;
-        }
-        // remove all groups that have no entries
-        const filteredEntries = entries.filter(entry => entry.entries.length > 0);
-        if (plugins.some(plugin => plugin.homePage?.onNavigationEntriesUpdate)) {
-            plugins.forEach(plugin => {
-                if (plugin.homePage?.onNavigationEntriesUpdate) {
-                    plugin.homePage.onNavigationEntriesUpdate(filteredEntries);
-                }
-            });
-        }
-
-    }, [plugins]);
-
-    const computeTopNavigation = useCallback((collections: EntityCollection[], views: CMSView[], adminViews: CMSView[], viewsOrder?: string[]): NavigationResult => {
+    const computeTopNavigation = useCallback((collections: EntityCollection[], views: CMSView[], adminViews: CMSView[], viewsOrder?: string[], navigationGroupMappingsOverride?: NavigationGroupMapping[], onNavigationEntriesUpdateCallback?: (entries: NavigationGroupMapping[]) => void): NavigationResult => {
 
         const finalNavigationGroupMappings: NavigationGroupMapping[] = computeNavigationGroups({
-            navigationGroupMappings: navigationGroupMappings,
+            navigationGroupMappings: navigationGroupMappingsOverride ?? navigationGroupMappings,
             collections,
             views,
             plugins: plugins
@@ -209,7 +193,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
             ...(views ?? []).reduce((acc, view) => {
                 if (view.hideFromNavigation) return acc;
 
-                const pathKey = Array.isArray(view.path) ? view.path[0] : view.path;
+                const pathKey = view.path;
                 let groupName = getGroup(view); // Initial group
 
                 if (finalNavigationGroupMappings) {
@@ -237,7 +221,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
             ...(adminViews ?? []).reduce((acc, view) => {
                 if (view.hideFromNavigation) return acc;
 
-                const pathKey = Array.isArray(view.path) ? view.path[0] : view.path;
+                const pathKey = view.path;
                 const groupName = NAVIGATION_ADMIN_GROUP_NAME;
 
                 acc.push({
@@ -280,21 +264,62 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
             .map(e => e.group)
             .filter(Boolean) as string[];
 
+        // Preserve order from finalNavigationGroupMappings (persisted order)
+        const groupsFromMappings = finalNavigationGroupMappings.map(g => g.name);
+
+        // Add any additional groups not in mappings
+        const additionalGroups = collectedGroupsFromEntries.filter(g => !groupsFromMappings.includes(g));
+
         const allDefinedGroups = [
             ...(pluginGroups ?? []),
-            ...collectedGroupsFromEntries
+            ...groupsFromMappings,
+            ...additionalGroups
         ];
 
-        const uniqueGroups = [...new Set(allDefinedGroups)]
-            .sort((a, b) => groupOrderValue(a) - groupOrderValue(b));
+        // Remove duplicates while preserving order, then separate admin to the end
+        const uniqueGroupsArray = [...new Set(allDefinedGroups)];
+        const adminGroups = uniqueGroupsArray.filter(g => g === NAVIGATION_ADMIN_GROUP_NAME);
+        const nonAdminGroups = uniqueGroupsArray.filter(g => g !== NAVIGATION_ADMIN_GROUP_NAME);
+        const uniqueGroups = [...nonAdminGroups, ...adminGroups];
 
         return {
             allowDragAndDrop: plugins?.some(plugin => plugin.homePage?.allowDragAndDrop) ?? false,
             navigationEntries,
             groups: uniqueGroups,
-            onNavigationEntriesUpdate: onNavigationEntriesOrderUpdate,
+            onNavigationEntriesUpdate: onNavigationEntriesUpdateCallback!,
         };
-    }, [navigationGroupMappings, buildCMSUrlPath, buildUrlCollectionPath, pluginGroups, onNavigationEntriesOrderUpdate]);
+    }, [navigationGroupMappings, buildCMSUrlPath, buildUrlCollectionPath, pluginGroups]);
+
+    const onNavigationEntriesOrderUpdate = useCallback((entries: NavigationGroupMapping[]) => {
+        if (!plugins) {
+            return;
+        }
+        // remove all groups that have no entries
+        const filteredEntries = entries.filter(entry => entry.entries.length > 0);
+
+        // Immediately update the local topLevelNavigation with new mappings
+        if (collectionsRef.current && viewsRef.current) {
+            const updatedNav = computeTopNavigation(
+                collectionsRef.current,
+                viewsRef.current,
+                adminViewsRef.current ?? [],
+                viewsOrder,
+                filteredEntries,
+                onNavigationEntriesOrderUpdate
+            );
+            setTopLevelNavigation(updatedNav);
+        }
+
+        // Then persist to backend
+        if (plugins.some(plugin => plugin.homePage?.onNavigationEntriesUpdate)) {
+            plugins.forEach(plugin => {
+                if (plugin.homePage?.onNavigationEntriesUpdate) {
+                    plugin.homePage.onNavigationEntriesUpdate(filteredEntries);
+                }
+            });
+        }
+
+    }, [plugins, computeTopNavigation, viewsOrder]);
 
     const refreshNavigation = useCallback(async () => {
 
@@ -312,7 +337,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
                 ]
             );
 
-            const computedTopLevelNav = computeTopNavigation(resolvedCollections, resolvedViews, resolvedAdminViews, viewsOrder);
+            const computedTopLevelNav = computeTopNavigation(resolvedCollections, resolvedViews, resolvedAdminViews, viewsOrder, undefined, onNavigationEntriesOrderUpdate);
 
             let shouldUpdateTopLevelNav = false;
             if (!areCollectionListsEqual(collectionsRef.current ?? [], resolvedCollections)) {
@@ -457,8 +482,9 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
         [fullCollectionPath]);
 
     const urlPathToDataPath = useCallback((path: string): string => {
-        if (path.startsWith(fullCollectionPath))
-            return path.replace(fullCollectionPath, "");
+        const decodedPath = decodeURIComponent(path);
+        if (decodedPath.startsWith(fullCollectionPath))
+            return decodedPath.replace(fullCollectionPath, "");
         throw Error("Expected path starting with " + fullCollectionPath);
     }, [fullCollectionPath]);
 
@@ -716,6 +742,7 @@ function computeNavigationGroups({
 
     let result = navigationGroupMappings;
 
+    // Merge plugin navigation entries
     result = plugins ? plugins?.reduce((acc, plugin) => {
         if (plugin.homePage?.navigationEntries) {
             plugin.homePage.navigationEntries.forEach((entry) => {
@@ -738,8 +765,54 @@ function computeNavigationGroups({
         return acc;
     }, [...(result ?? [])] as NavigationGroupMapping[]) : result;
 
+    // Track all entries that are already assigned to groups
+    const assignedEntries = new Set<string>();
+    if (result) {
+        result.forEach(group => {
+            group.entries.forEach(entry => assignedEntries.add(entry));
+        });
+    }
+
+    // Find collections and views that are NOT in any persisted group
+    const unassignedGroupMap: Record<string, string[]> = {};
+
+    // Check collections
+    (collections ?? []).forEach(collection => {
+        const entry = collection.id ?? collection.path;
+        if (!assignedEntries.has(entry)) {
+            const groupName = getGroup(collection);
+            if (!unassignedGroupMap[groupName]) unassignedGroupMap[groupName] = [];
+            unassignedGroupMap[groupName].push(entry);
+        }
+    });
+
+    // Check views
+    (views ?? []).forEach(view => {
+        const entry = view.path;
+        if (!assignedEntries.has(entry)) {
+            const groupName = getGroup(view);
+            if (!unassignedGroupMap[groupName]) unassignedGroupMap[groupName] = [];
+            unassignedGroupMap[groupName].push(entry);
+        }
+    });
+
+    // Merge unassigned entries into existing groups or create new groups
+    Object.entries(unassignedGroupMap).forEach(([groupName, entries]) => {
+        if (result) {
+            const existingGroup = result.find(g => g.name === groupName);
+            if (existingGroup) {
+                existingGroup.entries.push(...entries);
+            } else {
+                result.push({
+                    name: groupName,
+                    entries
+                });
+            }
+        }
+    });
+
     if (!result) {
-        // Convert views and collections to navigation group mappings, grouped by their group name
+        // No persisted data at all - create from scratch
         result = [];
         const groupMap: Record<string, string[]> = {};
 
@@ -754,12 +827,12 @@ function computeNavigationGroups({
         // Add views
         (views ?? []).forEach(view => {
             const name = getGroup(view);
-            const entry = Array.isArray(view.path) ? view.path[0] : view.path;
+            const entry = view.path;
             if (!groupMap[name]) groupMap[name] = [];
             groupMap[name].push(entry);
         });
 
-        // Convert groupMap to initialGroupMappings array
+        // Convert groupMap to result array
         result = Object.entries(groupMap).map(([name, entries]) => ({
             name,
             entries

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

@@ -352,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/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;
 
@@ -775,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.
@@ -913,19 +925,36 @@ export type FileType =
     | "font/*"
     | string;
 
-export interface ImageCompression {
+export interface ImageResize {
     /**
-     * New image max height (ratio is preserved)
+     * Maximum width in pixels. Image will be scaled down proportionally if wider.
+     */
+    maxWidth?: number;
+
+    /**
+     * 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/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);
         },