@firecms/core 3.0.0-canary.248 → 3.0.0-canary.249

package/src/hooks/useBuildNavigationController.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import equal from "react-fast-compare"
+import { useBlocker, useNavigate } from "react-router-dom";
 
 import {
     AuthController,
@@ -12,9 +13,10 @@ import {
     FireCMSPlugin,
     NavigationBlocker,
     NavigationController,
+    NavigationEntry,
+    NavigationGroupMapping,
+    NavigationResult,
     PermissionsBuilder,
-    TopNavigationEntry,
-    TopNavigationResult,
     User,
     UserConfigurationPersistence
 } from "../types";
@@ -28,27 +30,77 @@ import {
     resolvePermissions
 } from "../util";
 import { getParentReferencesFromPath } from "../util/parent_references_from_path";
-import { useBlocker, useNavigate } from "react-router-dom";
 
 const DEFAULT_BASE_PATH = "/";
 const DEFAULT_COLLECTION_PATH = "/c";
 
+export const NAVIGATION_DEFAULT_GROUP_NAME = "Views";
+export const NAVIGATION_ADMIN_GROUP_NAME = "Admin";
+
 export type BuildNavigationContextProps<EC extends EntityCollection, USER extends User> = {
+    /**
+     * Base path for the CMS, used to build the all the URLs.
+     * Defaults to "/".
+     */
     basePath?: string,
+    /**
+     * Base path for the collections, used to build the collection URLs.
+     * Defaults to "c" (e.g. "/c/products").
+     */
     baseCollectionPath?: string,
+    /**
+     * The auth controller used to manage the user authentication and permissions.
+     */
     authController: AuthController<USER>;
+    /**
+     * The collections to be used in the CMS.
+     * This can be a static array of collections or a function that returns a promise
+     * resolving to an array of collections.
+     */
     collections?: EC[] | EntityCollectionsBuilder<EC>;
+    /**
+     * Optional permissions builder to be applied to the collections.
+     * If not provided, the permissions will be resolved from the collection configuration.
+     */
     collectionPermissions?: PermissionsBuilder;
+    /**
+     * Custom views to be added to the CMS, these will be available in the main navigation.
+     * This can be a static array of views or a function that returns a promise
+     * resolving to an array of views.
+     */
     views?: CMSView[] | CMSViewsBuilder;
+    /**
+     * Custom views to be added to the CMS admin navigation.
+     * This can be a static array of views or a function that returns a promise
+     * resolving to an array of views.
+     */
     adminViews?: CMSView[] | CMSViewsBuilder;
-    viewsOrder?: string[];
+    /**
+     * Controller for storing user preferences.
+     */
     userConfigPersistence?: UserConfigurationPersistence;
+    /**
+     * Delegate for data source operations, used to resolve collections and views.
+     */
     dataSourceDelegate: DataSourceDelegate;
+    /**
+     * Plugins to be used in the CMS.
+     */
     plugins?: FireCMSPlugin[];
+    /**
+     * Used to define the name of groups and order of the navigation entries.
+     */
+    navigationGroupMappings?: NavigationGroupMapping[];
     /**
      * If true, the navigation logic will not be updated until this flag is false
      */
     disabled?: boolean;
+
+    /**
+     * @deprecated
+     * Use `navigationGroupMappings` instead.
+     */
+    viewsOrder?: string[];
 };
 
 export function useBuildNavigationController<EC extends EntityCollection, USER extends User>(props: BuildNavigationContextProps<EC, USER>): NavigationController {
@@ -64,7 +116,8 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
         plugins,
         userConfigPersistence,
         dataSourceDelegate,
-        disabled
+        disabled,
+        navigationGroupMappings
     } = props;
 
     const navigate = useNavigate();
@@ -72,10 +125,11 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
     const collectionsRef = useRef<EntityCollection[] | undefined>();
     const viewsRef = useRef<CMSView[] | undefined>();
     const adminViewsRef = useRef<CMSView[] | undefined>();
+    const navigationEntriesOrderRef = useRef<string[] | undefined>();
 
     const [initialised, setInitialised] = useState<boolean>(false);
 
-    const [topLevelNavigation, setTopLevelNavigation] = useState<TopNavigationResult | undefined>(undefined);
+    const [topLevelNavigation, setTopLevelNavigation] = useState<NavigationResult | undefined>(undefined);
     const [navigationLoading, setNavigationLoading] = useState<boolean>(true);
     const [navigationLoadingError, setNavigationLoadingError] = useState<Error | undefined>(undefined);
 
@@ -92,99 +146,155 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
     const buildUrlCollectionPath = useCallback((path: string): string => `${removeInitialAndTrailingSlashes(baseCollectionPath)}/${encodePath(path)}`,
         [baseCollectionPath]);
 
-    const computeTopNavigation = useCallback((collections: EntityCollection[], views: CMSView[], adminViews: CMSView[], viewsOrder?: string[]): TopNavigationResult => {
-        let navigationEntries: TopNavigationEntry[] = [
-            ...(collections ?? []).map(collection => (!collection.hideFromNavigation
-                ? ({
-                    url: buildUrlCollectionPath(collection.id ?? collection.path),
+    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 finalNavigationGroupMappings: NavigationGroupMapping[] = computeNavigationGroups({
+            navigationGroupMappings: navigationGroupMappings,
+            collections,
+            views,
+            plugins: plugins
+        });
+
+        const allPluginNavigationEntries = finalNavigationGroupMappings.map((g) => g.entries).flat() ?? [];
+        const navigationEntriesOrder = ([...new Set(allPluginNavigationEntries)]);
+
+        let navigationEntries: NavigationEntry[] = [
+            ...(collections ?? []).reduce((acc, collection) => {
+                if (collection.hideFromNavigation) return acc;
+
+                const pathKey = collection.id ?? collection.path;
+                let groupName = getGroup(collection); // Initial group
+
+                if (finalNavigationGroupMappings) {
+                    for (const pluginGroupDef of finalNavigationGroupMappings) {
+                        if (pluginGroupDef.entries.includes(pathKey)) {
+                            groupName = pluginGroupDef.name;
+                            break;
+                        }
+                    }
+                }
+
+                acc.push({
+                    id: `collection:${pathKey}`,
+                    url: buildUrlCollectionPath(pathKey),
                     type: "collection",
                     name: collection.name.trim(),
-                    path: collection.id ?? collection.path,
+                    path: pathKey,
                     collection,
                     description: collection.description?.trim(),
-                    group: getGroup(collection)
-                } satisfies TopNavigationEntry)
-                : undefined))
-                .filter(Boolean) as TopNavigationEntry[],
-            ...(views ?? []).map(view =>
-                !view.hideFromNavigation
-                    ? ({
-                        url: buildCMSUrlPath(Array.isArray(view.path) ? view.path[0] : view.path),
-                        name: view.name.trim(),
-                        type: "view",
-                        path: view.path,
-                        view,
-                        description: view.description?.trim(),
-                        group: getGroup(view)
-                    } satisfies TopNavigationEntry)
-                    : undefined)
-                .filter(Boolean) as TopNavigationEntry[],
-            ...(adminViews ?? []).map(view =>
-                !view.hideFromNavigation
-                    ? ({
-                        url: buildCMSUrlPath(Array.isArray(view.path) ? view.path[0] : view.path),
-                        name: view.name.trim(),
-                        type: "admin",
-                        path: view.path,
-                        view,
-                        description: view.description?.trim(),
-                        group: "Admin"
-                    } satisfies TopNavigationEntry)
-                    : undefined)
-                .filter(Boolean) as TopNavigationEntry[]
+                    group: groupName ?? NAVIGATION_DEFAULT_GROUP_NAME
+                });
+                return acc;
+            }, [] as NavigationEntry[]),
+
+            ...(views ?? []).reduce((acc, view) => {
+                if (view.hideFromNavigation) return acc;
+
+                const pathKey = Array.isArray(view.path) ? view.path[0] : view.path;
+                let groupName = getGroup(view); // Initial group
+
+                if (finalNavigationGroupMappings) {
+                    for (const pluginGroupDef of finalNavigationGroupMappings) {
+                        if (pluginGroupDef.entries.includes(pathKey)) {
+                            groupName = pluginGroupDef.name;
+                            break;
+                        }
+                    }
+                }
+
+                acc.push({
+                    id: `view:${pathKey}`,
+                    url: buildCMSUrlPath(pathKey),
+                    name: view.name.trim(),
+                    type: "view",
+                    path: view.path,
+                    view,
+                    description: view.description?.trim(),
+                    group: groupName ?? NAVIGATION_DEFAULT_GROUP_NAME
+                });
+                return acc;
+            }, [] as NavigationEntry[]),
+
+            ...(adminViews ?? []).reduce((acc, view) => {
+                if (view.hideFromNavigation) return acc;
+
+                const pathKey = Array.isArray(view.path) ? view.path[0] : view.path;
+                const groupName = NAVIGATION_ADMIN_GROUP_NAME;
+
+                acc.push({
+                    id: `admin:${pathKey}`,
+                    url: buildCMSUrlPath(pathKey),
+                    name: view.name.trim(),
+                    type: "admin",
+                    path: view.path,
+                    view,
+                    description: view.description?.trim(),
+                    group: groupName
+                });
+                return acc;
+            }, [] as NavigationEntry[])
         ];
 
-        // Sort by group, entries with group "Admin" will go last, and second to last will be the group "Views"
-        navigationEntries = navigationEntries.sort((a, b) => {
-            if (a.group !== "Views" && a.group !== "Admin" && (b.group === "Views" || b.group === "Admin")) {
-                return -1;
-            }
-            if (b.group !== "Views" && b.group !== "Admin" && (a.group === "Views" || a.group === "Admin")) {
-                return 1;
-            }
-            if (a.group === "Admin" && b.group !== "Admin") {
-                return 1;
-            }
-            if (a.group !== "Admin" && b.group === "Admin") {
-                return -1;
-            }
-            if (a.group === "Views" && b.group !== "Views") {
-                return -1;
-            }
-            if (a.group !== "Views" && b.group === "Views") {
-                return 1;
-            }
-            return 0;
+        const groupOrderValue = (groupName?: string): number => {
+            if (groupName === NAVIGATION_ADMIN_GROUP_NAME) return 1;
+            return 0; // Other groups
+        };
 
+        navigationEntries = navigationEntries.sort((a, b) => {
+            return groupOrderValue(a.group) - groupOrderValue(b.group);
         });
 
-        if (viewsOrder) {
+        const usedViewsOrder = viewsOrder ?? navigationEntriesOrder;
+        if (usedViewsOrder) {
             navigationEntries = navigationEntries.sort((a, b) => {
-                const aIndex = viewsOrder.indexOf(a.path);
-                const bIndex = viewsOrder.indexOf(b.path);
-                if (aIndex === -1 && bIndex === -1) {
-                    return 0;
-                }
-                if (aIndex === -1) {
-                    return 1;
-                }
-                if (bIndex === -1) {
-                    return -1;
-                }
+                const getSortPath = (navEntry: NavigationEntry) => typeof navEntry.path === "string" ? navEntry.path : navEntry.path[0];
+                const aIndex = usedViewsOrder.indexOf(getSortPath(a));
+                const bIndex = usedViewsOrder.indexOf(getSortPath(b));
+                if (aIndex === -1 && bIndex === -1) return 0;
+                if (aIndex === -1) return 1;
+                if (bIndex === -1) return -1;
                 return aIndex - bIndex;
             });
         }
 
-        const groups: string[] = Object.values(navigationEntries)
+        const collectedGroupsFromEntries = navigationEntries
             .map(e => e.group)
-            .filter(Boolean)
-            .filter((value, index, array) => array.indexOf(value) === index) as string[];
+            .filter(Boolean) as string[];
+
+        const allDefinedGroups = [
+            ...(pluginGroups ?? []),
+            ...collectedGroupsFromEntries
+        ];
+
+        const uniqueGroups = [...new Set(allDefinedGroups)]
+            .sort((a, b) => groupOrderValue(a) - groupOrderValue(b));
 
         return {
+            allowDragAndDrop: plugins?.some(plugin => plugin.homePage?.allowDragAndDrop) ?? false,
             navigationEntries,
-            groups
+            groups: uniqueGroups,
+            onNavigationEntriesUpdate: onNavigationEntriesOrderUpdate,
         };
-    }, [buildCMSUrlPath, buildUrlCollectionPath]);
+    }, [navigationGroupMappings, buildCMSUrlPath, buildUrlCollectionPath, pluginGroups, onNavigationEntriesOrderUpdate]);
 
     const refreshNavigation = useCallback(async () => {
 
@@ -202,6 +312,8 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
                 ]
             );
 
+            const computedTopLevelNav = computeTopNavigation(resolvedCollections, resolvedViews, resolvedAdminViews, viewsOrder);
+
             let shouldUpdateTopLevelNav = false;
             if (!areCollectionListsEqual(collectionsRef.current ?? [], resolvedCollections)) {
                 collectionsRef.current = resolvedCollections;
@@ -221,7 +333,12 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
                 shouldUpdateTopLevelNav = true;
             }
 
-            const computedTopLevelNav = computeTopNavigation(resolvedCollections, resolvedViews, resolvedAdminViews, viewsOrder);
+            const navigationEntriesOrder = computedTopLevelNav.navigationEntries.map(e => e.id);
+            if (!equal(navigationEntriesOrderRef.current, navigationEntriesOrder)) {
+                navigationEntriesOrderRef.current = navigationEntriesOrder;
+                shouldUpdateTopLevelNav = true;
+            }
+
             if (shouldUpdateTopLevelNav && !equal(topLevelNavigation, computedTopLevelNav)) {
                 setTopLevelNavigation(computedTopLevelNav);
             }
@@ -243,7 +360,7 @@ export function useBuildNavigationController<EC extends EntityCollection, USER e
         disabled,
         viewsProp,
         adminViewsProp,
-        computeTopNavigation
+        computeTopNavigation,
     ]);
 
     useEffect(() => {
@@ -503,9 +620,9 @@ async function resolveCMSViews(baseViews: CMSView[] | CMSViewsBuilder | undefine
 function getGroup(collectionOrView: EntityCollection<any, any> | CMSView) {
     const trimmed = collectionOrView.group?.trim();
     if (!trimmed || trimmed === "") {
-        return "Views";
+        return NAVIGATION_DEFAULT_GROUP_NAME;
     }
-    return trimmed ?? "Views";
+    return trimmed ?? NAVIGATION_DEFAULT_GROUP_NAME;
 }
 
 function areCollectionListsEqual(a: EntityCollection[], b: EntityCollection[]) {
@@ -584,3 +701,75 @@ function useCustomBlocker(): NavigationBlocker {
         reset: blocker?.reset
     }
 }
+
+function computeNavigationGroups({
+                                     navigationGroupMappings,
+                                     collections,
+                                     views,
+                                     plugins
+                                 }: {
+    navigationGroupMappings?: NavigationGroupMapping[],
+    collections?: EntityCollection[],
+    views?: CMSView[],
+    plugins?: FireCMSPlugin[]
+}): NavigationGroupMapping[] {
+
+    let result = navigationGroupMappings;
+
+    result = plugins ? plugins?.reduce((acc, plugin) => {
+        if (plugin.homePage?.navigationEntries) {
+            plugin.homePage.navigationEntries.forEach((entry) => {
+                const {
+                    name,
+                    entries
+                } = entry;
+                const existingGroup = acc.find(entry => entry.name === name);
+                if (existingGroup) {
+                    existingGroup.entries.push(...entries);
+                } else {
+                    acc.push({
+                        name,
+                        entries: [...entries]
+                    });
+                }
+            });
+
+        }
+        return acc;
+    }, [...(result ?? [])] as NavigationGroupMapping[]) : result;
+
+    if (!result) {
+        // Convert views and collections to navigation group mappings, grouped by their group name
+        result = [];
+        const groupMap: Record<string, string[]> = {};
+
+        // Add collections
+        (collections ?? []).forEach(collection => {
+            const name = getGroup(collection);
+            const entry = collection.id ?? collection.path;
+            if (!groupMap[name]) groupMap[name] = [];
+            groupMap[name].push(entry);
+        });
+
+        // Add views
+        (views ?? []).forEach(view => {
+            const name = getGroup(view);
+            const entry = Array.isArray(view.path) ? view.path[0] : view.path;
+            if (!groupMap[name]) groupMap[name] = [];
+            groupMap[name].push(entry);
+        });
+
+        // Convert groupMap to initialGroupMappings array
+        result = Object.entries(groupMap).map(([name, entries]) => ({
+            name,
+            entries
+        }));
+    }
+
+    // Remove duplicates in entries
+    result.forEach(group => {
+        group.entries = [...new Set(group.entries)];
+    });
+
+    return result;
+}

package/src/preview/PropertyPreview.tsx

@@ -97,6 +97,20 @@ export const PropertyPreview = React.memo(function PropertyPreview<T extends CMS
                                              previewType={stringProperty.url}/>;
             } else if (stringProperty.markdown) {
                 content = <Markdown source={value} size={"small"}/>;
+            } else if (stringProperty.reference) {
+                if (typeof stringProperty.reference.path === "string") {
+                    content = <ReferencePreview
+                        disabled={!stringProperty.reference.path}
+                        previewProperties={stringProperty.reference.previewProperties}
+                        includeId={stringProperty.reference.includeId}
+                        includeEntityLink={stringProperty.reference.includeEntityLink}
+                        size={props.size}
+                        reference={new EntityReference(value, stringProperty.reference.path)}
+                    />;
+                } else {
+                    content = <EmptyValue/>;
+                }
+
             } else {
                 content = <StringPropertyPreview {...props}
                                                  property={stringProperty}

package/src/types/analytics.ts

@@ -28,6 +28,9 @@ export type CMSAnalyticsEvent =
     | "home_navigate_to_view"
     | "home_navigate_to_admin_view"
     | "home_favorite_navigate_to_view"
+    | "home_move_card"
+    | "home_move_group"
+    | "home_drop_new_group"
 
     | "collection_inline_editing"
 

package/src/types/collections.ts

@@ -76,6 +76,9 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * Optional field used to group top level navigation entries under a~
      * navigation view. If you set this value in a subcollection it has no
      * effect.
+     * @deprecated This prop is deprecated and will be removed in the future.
+     * You can apply grouping by using the `navigationGroupMappings` prop in the
+     * {@link useBuildNavigationController} hook instead.
      */
     group?: string;
 

package/src/types/navigation.ts

@@ -36,7 +36,7 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      * level of the navigation (e.g. in the home page or the navigation
      * drawer)
      */
-    topLevelNavigation?: TopNavigationResult;
+    topLevelNavigation?: NavigationResult;
 
     /**
      * Is the navigation loading (the configuration persistence has not
@@ -229,7 +229,22 @@ export interface CMSView {
 
 }
 
-export interface TopNavigationEntry {
+/**
+ * Used to group navigation entries in the main navigation.
+ */
+export interface NavigationGroupMapping {
+    /**
+     * Name of the group, used to display the group header in the UI
+     */
+    name: string;
+    /**
+     * List of collection ids or view paths that belong to this group.
+     */
+    entries: string[];
+}
+
+export interface NavigationEntry {
+    id: string;
     url: string;
     name: string;
     path: string;
@@ -240,7 +255,14 @@ export interface TopNavigationEntry {
     group: string;
 }
 
-export type TopNavigationResult = {
-    navigationEntries: TopNavigationEntry[],
-    groups: string[]
+export type NavigationResult = {
+
+    allowDragAndDrop: boolean;
+
+    navigationEntries: NavigationEntry[],
+
+    groups: string[],
+
+    onNavigationEntriesUpdate: (entries: NavigationGroupMapping[]) => void;
 };
+

package/src/types/plugins.tsx

@@ -7,6 +7,7 @@ import { FieldProps, FormContext } from "./fields";
 import { CMSType, Property } from "./properties";
 import { EntityStatus } from "./entities";
 import { ResolvedProperty } from "./resolved_entities";
+import { NavigationGroupMapping } from "./navigation";
 
 /**
  * Interface used to define plugins for FireCMS.
@@ -84,6 +85,20 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
             children: React.ReactNode;
         }
 
+        /**
+         * Allow reordering with drag and drop of the collections in the home page.
+         */
+        allowDragAndDrop?: boolean;
+
+        navigationEntries?: NavigationGroupMapping[];
+
+        /**
+         * This method will be called when the entries are updated in the home page.
+         * group => navigationEntriesOrder (path)
+         * @param entries
+         */
+        onNavigationEntriesUpdate?: (entries: NavigationGroupMapping[]) => void;
+
     }
 
     collectionView?: {

package/src/types/properties.ts

@@ -413,6 +413,14 @@ export interface StringProperty extends BaseProperty<string> {
      * Add an icon to clear the value and set it to `null`. Defaults to `false`
      */
     clearable?: boolean;
+
+    /**
+     * You can use this property (a string) to behave as a reference to another
+     * collection. The stored value is the ID of the entity in the
+     * collection, and the `path` prop is used to
+     * define the collection this reference points to.
+     */
+    reference?: ReferenceProperty;
 }
 
 /**

package/src/types/property_config.tsx

@@ -62,6 +62,7 @@ export type PropertyConfigId =
     "group" |
     "key_value" |
     "reference" |
+    "reference_as_string" |
     "multi_references" |
     "switch" |
     "date_time" |

package/src/util/icons.tsx

@@ -4,13 +4,17 @@ 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, color?:IconColor): React.ReactElement | undefined {
+export function getIcon(iconKey?: string,
+                        className?: string,
+                        color?: IconColor,
+                        size?: "smallest" | "small" | "medium" | "large" | number,): 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} color={color}/> : undefined;
+    return iconKey in iconKeysMap ?
+        <Icon iconKey={iconKey} size={size} className={className} color={color}/> : undefined;
 }
 
 export type IconViewProps = {
@@ -34,7 +38,7 @@ export const IconForView = React.memo(
         size?: "smallest" | "small" | "medium" | "large" | number,
     }): React.ReactElement {
         if (!collectionOrView) return <></>;
-        const icon = getIcon(collectionOrView.icon, className, color);
+        const icon = getIcon(collectionOrView.icon, className, color, size);
         if (collectionOrView?.icon && icon)
             return icon;