@firecms/core 3.0.0-beta.13 → 3.0.0-beta.15

package/src/preview/property_previews/MapPropertyPreview.tsx

@@ -128,7 +128,7 @@ export function KeyValuePreview({ value }: { value: any }) {
                         </div>
                         <div
                             className="flex-grow max-w-[75%]">
-                            {childValue && <Typography>
+                            {childValue && typeof childValue !== "object" && <Typography>
                                 <ErrorBoundary>
                                     {childValue.toString()}
                                 </ErrorBoundary>

package/src/preview/property_previews/SkeletonPropertyComponent.tsx

@@ -46,7 +46,7 @@ export function SkeletonPropertyComponent({
                 content = <>{arrayProperty.of.map((p, i) => renderGenericArrayCell(p, i))} </>;
             } else {
                 if (arrayProperty.of.dataType === "map" && arrayProperty.of.properties) {
-                    content = renderArrayOfMaps(arrayProperty.of.properties, size, arrayProperty.of.previewProperties);
+                    content = renderArrayOfMaps(arrayProperty.of.properties, size, arrayProperty.of.previewKeys);
                 } else if (arrayProperty.of.dataType === "string") {
                     if (arrayProperty.of.enumValues) {
                         content = renderArrayEnumTableCell();

package/src/preview/property_previews/StringPropertyPreview.tsx

@@ -45,7 +45,7 @@ export function StringPropertyPreview({
         if (!value) return <></>;
         const lines = value.split("\n");
         return value && value.includes("\n")
-            ? <div className={cls("overflow-x-scroll", size === "small" ? "text-sm" : "")}>
+            ? <div className={cls("overflow-x-scroll overflow-hidden", size === "small" ? "text-sm" : "")}>
                 {lines.map((str, index) =>
                     <React.Fragment key={`string_preview_${index}`}>
                         <span>{str}</span>

package/src/routes/FireCMSRoute.tsx

@@ -79,7 +79,8 @@ export function FireCMSRoute() {
             key={`collection_view_${collection.id ?? collection.path}`}
             isSubCollection={false}
             parentCollectionIds={[]}
-            fullPath={collection.id}
+            fullPath={collection.path}
+            fullIdPath={collection.id}
             updateUrl={true}
             {...collection}
             Actions={toArray(collection.Actions)}/>
@@ -100,7 +101,7 @@ export function FireCMSRoute() {
                 fullIdPath={collection.id}
                 isSubCollection={false}
                 parentCollectionIds={[]}
-                fullPath={collection.id}
+                fullPath={collection.path}
                 updateUrl={true}
                 {...collection}
                 Actions={toArray(collection.Actions)}/>;
@@ -200,7 +201,6 @@ function EntityFullScreenRoute({
     const collection = isNew ? lastCollectionEntry!.collection : lastEntityEntry!.parentCollection;
     const fullIdPath = isNew ? lastCollectionEntry!.path : lastEntityEntry!.path;
     const collectionPath = navigation.resolveIdsFrom(fullIdPath);
-
     return <>
         <EntityEditView
             key={collection.id + "_" + (isNew ? "new" : (isCopy ? entityId + "_copy" : entityId))}

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

@@ -70,12 +70,15 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * e.g. 'account_tree' or 'person'.
      * Find all the icons in https://firecms.co/docs/icons
      */
-    icon?: string;
+    icon?: string | React.ReactNode;
 
     /**
      * 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;
 
@@ -112,7 +115,7 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * `hidden` in the property definition, will be ignored.
      * `propertiesOrder` has precedence over `hidden`.
      *     - For properties use the property key.
-     *     - For additional columns use the column id.
+     *     - For additional fields use the field key.
      *     - If you have subcollections, you get a column for each subcollection,
      *       with the path (or alias) as the subcollection, prefixed with
      *       `subcollection:`. e.g. `subcollection:orders`.
@@ -127,7 +130,8 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
 
     /**
      * If enabled, content is loaded in batches. If `false` all entities in the
-     * collection are loaded.
+     * collection are loaded. This means that when reaching the end of the
+     * collection, the CMS will load more entities.
      * You can specify a number to specify the pagination size (50 by default)
      * Defaults to `true`
      */
@@ -192,8 +196,11 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      *     }
      * }
      * ```
+     *
+     * You can also pass the action as a string that represents the `key`, in which case it will
+     * use the action defined in the main configuration under `entityActions`.
      */
-    entityActions?: EntityAction<M, USER>[];
+    entityActions?: (EntityAction<M, USER> | string)[];
 
     /**
      * Pass your own selection controller if you want to control selected
@@ -337,6 +344,12 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * If set to true, a tab including the JSON representation of the entity will be included.
      */
     includeJsonView?: boolean;
+
+    /**
+     * If set to true, changes to the entity will be saved in a subcollection.
+     * This prop has no effect if the history plugin is not enabled
+     */
+    history?: boolean;
 }
 
 /**
@@ -519,6 +532,11 @@ export type EntityCustomView<M extends Record<string, any> = any> =
          */
         name: string;
 
+        /**
+         * Render this custom view in the tab of the entity view, instead of the name
+         */
+        tabComponent?: React.ReactNode;
+
         /**
          * If set to true, the actions of the entity (save, discard,delete) will be
          * included in the view. By default the actions are located in the right or bottom,
@@ -531,6 +549,11 @@ export type EntityCustomView<M extends Record<string, any> = any> =
          * Builder for rendering the custom view
          */
         Builder?: React.ComponentType<EntityCustomViewParams<M>>;
+
+        /**
+         * Position of this tab in the entity view. Defaults to `end`.
+         */
+        position?: "start" | "end";
     };
 
 /**
@@ -561,6 +584,11 @@ export interface EntityCustomViewParams<M extends Record<string, any> = any> {
      * Use the form context to access the form state and methods
      */
     formContext: FormContext;
+
+    /**
+     * If this is a subcollection, this is the path of the parent collections
+     */
+    parentCollectionIds?: string[];
 }
 
 export type InferCollectionType<S extends EntityCollection> = S extends EntityCollection<infer M> ? M : never;

package/src/types/customization_controller.tsx

@@ -4,6 +4,7 @@ import { FireCMSPlugin } from "./plugins";
 import { EntityCustomView } from "./collections";
 import { Locale } from "./locales";
 import { PropertyConfig } from "./property_config";
+import { EntityAction } from "./entity_actions";
 
 export type CustomizationController = {
 
@@ -26,6 +27,14 @@ export type CustomizationController = {
      */
     entityViews?: EntityCustomView[];
 
+    /**
+     * List of actions that can be performed on entities.
+     * These actions are displayed in the entity view and in the collection view.
+     * You can later reuse these actions in the `entityActions` prop of a collection,
+     * by specifying the `key` of the action.
+     */
+    entityActions?: EntityAction<any, any>[];
+
     /**
      * Format of the dates in the CMS.
      * Defaults to 'MMMM dd, yyyy, HH:mm:ss'

package/src/types/entity_actions.tsx

@@ -4,6 +4,7 @@ import { Entity } from "./entities";
 import { EntityCollection, SelectionController } from "./collections";
 import { User } from "./user";
 import { SideEntityController } from "./side_entity_controller";
+import { FormContext } from "./fields";
 
 /**
  * An entity action is a custom action that can be performed on an entity.
@@ -17,7 +18,10 @@ export type EntityAction<M extends object = any, USER extends User = User> = {
 
     /**
      * Key of the action. You only need to provide this if you want to
-     * override the default actions.
+     * override the default actions, or if you are not passing the action
+     * directly to the `entityActions` prop of a collection.
+     * You can define your actions at the app level, in which case you
+     * must provide a key.
      * The default actions are:
      * - edit
      * - delete
@@ -36,6 +40,12 @@ export type EntityAction<M extends object = any, USER extends User = User> = {
      */
     onClick: (props: EntityActionClickProps<M, USER>) => Promise<void> | void;
 
+    /**
+     * Optional callback in case you want to disable the action
+     * @param props
+     */
+    isEnabled?: (props: EntityActionClickProps<M, USER>) => boolean;
+
     /**
      * Show this action collapsed in the menu of the collection view.
      * Defaults to true
@@ -51,18 +61,59 @@ export type EntityAction<M extends object = any, USER extends User = User> = {
 }
 
 export type EntityActionClickProps<M extends object, USER extends User = User> = {
-    entity: Entity<M>;
+    entity?: Entity<M>;
     context: FireCMSContext<USER>;
+
     fullPath?: string;
+    fullIdPath?: string;
     collection?: EntityCollection<M>;
+
+    /**
+     * Optional form context, present if the action is being called from a form.
+     * This allows you to access the form state and methods, including modifying the form values.
+     */
+    formContext?: FormContext;
+
+    /**
+     * Present if this actions is being called from a side dialog only
+     */
+    sideEntityController?: SideEntityController;
+
+    /**
+     * Is the action being called from the collection view or from the entity form view?
+     */
+    view: "collection" | "form";
+
+    /**
+     * If the action is rendered in the form, is it open in a side panel or full screen?
+     */
+    openEntityMode: "side_panel" | "full_screen";
+
+    /**
+     * Optional selection controller, present if the action is being called from a collection view
+     */
     selectionController?: SelectionController;
+
+    /**
+     * Optional highlight function to highlight the entity in the collection view
+     * @param entity
+     */
     highlightEntity?: (entity: Entity<any>) => void;
+
+    /**
+     * Optional unhighlight function to remove the highlight from the entity in the collection view
+     * @param entity
+     */
     unhighlightEntity?: (entity: Entity<any>) => void;
-    onCollectionChange?: () => void;
+
     /**
-     * If this actions is being called from a side dialog
+     * Optional function to navigate back (e.g. when deleting an entity or navigating from a form)
      */
-    sideEntityController?: SideEntityController;
+    navigateBack?: () => void;
+
+    /**
+     * Callback to be called when the collection changes, e.g. after an entity is deleted or created.
+     */
+    onCollectionChange?: () => void;
 
-    openEntityMode: "side_panel" | "full_screen";
 };

package/src/types/firecms.tsx

@@ -12,6 +12,7 @@ import { EntityLinkBuilder } from "./entity_link_builder";
 import { UserConfigurationPersistence } from "./local_config_persistence";
 import { FireCMSPlugin } from "./plugins";
 import { CMSAnalyticsEvent } from "./analytics";
+import { EntityAction } from "./entity_actions";
 
 /**
  * Use this callback to build entity collections dynamically.
@@ -92,9 +93,16 @@ export type FireCMSProps<USER extends User> = {
      *
      * You can also define an entity view from the UI.
      */
-
     entityViews?: EntityCustomView[];
 
+    /**
+     * List of actions that can be performed on entities.
+     * These actions are displayed in the entity view and in the collection view.
+     * You can later reuse these actions in the `entityActions` prop of a collection,
+     * by specifying the `key` of the action.
+     */
+    entityActions?: EntityAction[];
+
     /**
      * Format of the dates in the CMS.
      * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
@@ -129,7 +137,8 @@ export type FireCMSProps<USER extends User> = {
 
     /**
      * Use plugins to modify the behaviour of the CMS.
-     * Currently, in ALPHA, and likely subject to change.
+     * DEPRECATED: use the `plugins` prop in the `useBuildNavigationController` instead.
+     * This prop will work as a fallback for the `plugins` prop in the `useBuildNavigationController`.
      */
     plugins?: FireCMSPlugin<any, any, any>[];
 

package/src/types/navigation.ts

@@ -1,6 +1,7 @@
 import React from "react";
 import { EntityCollection } from "./collections";
 import { EntityReference } from "./entities";
+import { FireCMSPlugin } from "./plugins";
 
 /**
  * Controller that includes the resolved navigation and utility methods and
@@ -35,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
@@ -152,6 +153,11 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      */
     navigate: (to: string, options?: NavigateOptions) => void;
 
+    /**
+     * Plugin system allowing to extend the CMS functionality.
+     */
+    plugins?: FireCMSPlugin<any, any, any>[];
+
 }
 
 export interface NavigateOptions {
@@ -200,7 +206,7 @@ export interface CMSView {
      * e.g. 'account_tree' or 'person'
      * Find all the icons in https://firecms.co/docs/icons
      */
-    icon?: string;
+    icon?: string | React.ReactNode;
 
     /**
      * Should this view be hidden from the main navigation panel.
@@ -223,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;
@@ -234,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?: {
@@ -151,13 +166,37 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
             props?: FORM_PROPS;
         }
 
+        /**
+         * Add custom actions to the default ones ("Save", "Discard"...)
+         */
         Actions?: React.ComponentType<PluginFormActionProps<any, EC>>;
 
+        /**
+         * Add custom actions to the top of the form
+         */
+        ActionsTop?: React.ComponentType<PluginFormActionProps<any, EC>>;
+
         fieldBuilder?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T, any, EC>) => React.ComponentType<FieldProps<T>> | null;
 
         fieldBuilderEnabled?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T>) => boolean;
     }
 
+    collection?: {
+
+        /**
+         * Use this method to modify a single collection before it is rendered.
+         * @param collection
+         */
+        modifyCollection?: (collection: EntityCollection) => EntityCollection;
+
+        /**
+         * Use this method to modify, add or remove collections.
+         * @param collections
+         */
+        injectCollections?: (collections: EntityCollection[]) => EntityCollection[];
+
+    }
+
 }
 
 /**
@@ -190,12 +229,12 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
 export interface PluginFormActionProps<USER extends User = User, EC extends EntityCollection = EntityCollection> {
     entityId?: string;
     path: string;
+    parentCollectionIds: string[];
     status: EntityStatus;
     collection: EC;
     disabled: boolean;
     formContext?: FormContext<any>;
     context: FireCMSContext<USER>;
-    currentEntityId?: string;
     openEntityMode: "side_panel" | "full_screen";
 }
 

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/types/side_entity_controller.tsx

@@ -15,16 +15,16 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      */
     path: string;
 
+    /**
+     * Full CMS path of the entity, including the collection and sub-collections.
+     */
+    fullIdPath?: string;
+
     /**
      * ID of the entity, if not set, it means we are creating a new entity
      */
     entityId?: string;
 
-    // /**
-    //  * Navigation path with ids of the entity
-    //  */
-    // fullIdPath: string;
-
     /**
      * Set this flag to true if you want to make a copy of an existing entity
      */
@@ -76,6 +76,11 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      * Override some form properties
      */
     formProps?: Partial<EntityFormProps<M>>;
+
+    /**
+     * Allow the user to open the entity fullscreen
+     */
+    allowFullScreen?: boolean;
 }
 
 /**

package/src/util/callbacks.ts

@@ -0,0 +1,119 @@
+import { EntityCallbacks } from "../types";
+
+export const mergeCallbacks = (
+    baseCallbacks: EntityCallbacks = {},
+    pluginCallbacks: EntityCallbacks = {}
+): EntityCallbacks | undefined => {
+
+    if (!baseCallbacks && !pluginCallbacks) {
+        return undefined;
+    }
+
+    const mergedCallbacks: EntityCallbacks = {};
+
+    // Handle onFetch - returns Entity<M> or Promise<Entity<M>>
+    if (baseCallbacks.onFetch || pluginCallbacks.onFetch) {
+        mergedCallbacks.onFetch = async (props) => {
+            let entity = props.entity;
+            if (baseCallbacks.onFetch) {
+                entity = await Promise.resolve(baseCallbacks.onFetch(props));
+            }
+            if (pluginCallbacks.onFetch) {
+                entity = await Promise.resolve(pluginCallbacks.onFetch({
+                    ...props,
+                    entity
+                }));
+            }
+            return entity;
+        };
+    }
+
+    // Handle onSaveSuccess - returns void or Promise<void>
+    if (baseCallbacks.onSaveSuccess || pluginCallbacks.onSaveSuccess) {
+        mergedCallbacks.onSaveSuccess = async (props) => {
+            if (baseCallbacks.onSaveSuccess) {
+                await Promise.resolve(baseCallbacks.onSaveSuccess(props));
+            }
+            if (pluginCallbacks.onSaveSuccess) {
+                await Promise.resolve(pluginCallbacks.onSaveSuccess(props));
+            }
+        };
+    }
+
+    // Handle onSaveFailure - returns void or Promise<void>
+    if (baseCallbacks.onSaveFailure || pluginCallbacks.onSaveFailure) {
+        mergedCallbacks.onSaveFailure = async (props) => {
+            if (baseCallbacks.onSaveFailure) {
+                await Promise.resolve(baseCallbacks.onSaveFailure(props));
+            }
+            if (pluginCallbacks.onSaveFailure) {
+                await Promise.resolve(pluginCallbacks.onSaveFailure(props));
+            }
+        };
+    }
+
+    // Handle onPreSave - returns Partial<EntityValues<M>> or Promise<Partial<EntityValues<M>>>
+    if (baseCallbacks.onPreSave || pluginCallbacks.onPreSave) {
+        mergedCallbacks.onPreSave = async (props) => {
+            let values = { ...props.values };
+            if (baseCallbacks.onPreSave) {
+                const baseValues = await Promise.resolve(baseCallbacks.onPreSave(props));
+                values = { ...values, ...baseValues };
+            }
+            if (pluginCallbacks.onPreSave) {
+                const pluginValues = await Promise.resolve(pluginCallbacks.onPreSave({
+                    ...props,
+                    values
+                }));
+                values = { ...values, ...pluginValues };
+            }
+            return values;
+        };
+    }
+
+    // Handle onPreDelete - returns void
+    if (baseCallbacks.onPreDelete || pluginCallbacks.onPreDelete) {
+        mergedCallbacks.onPreDelete = (props) => {
+            if (baseCallbacks.onPreDelete) {
+                baseCallbacks.onPreDelete(props);
+            }
+            if (pluginCallbacks.onPreDelete) {
+                pluginCallbacks.onPreDelete(props);
+            }
+        };
+    }
+
+    // Handle onDelete - returns void
+    if (baseCallbacks.onDelete || pluginCallbacks.onDelete) {
+        mergedCallbacks.onDelete = (props) => {
+            if (baseCallbacks.onDelete) {
+                baseCallbacks.onDelete(props);
+            }
+            if (pluginCallbacks.onDelete) {
+                pluginCallbacks.onDelete(props);
+            }
+        };
+    }
+
+    // Handle onIdUpdate - returns string or Promise<string>
+    if (baseCallbacks.onIdUpdate || pluginCallbacks.onIdUpdate) {
+        mergedCallbacks.onIdUpdate = async (props) => {
+            let id = props.entityId || "";
+
+            if (baseCallbacks.onIdUpdate) {
+                id = await Promise.resolve(baseCallbacks.onIdUpdate(props));
+            }
+
+            if (pluginCallbacks.onIdUpdate) {
+                id = await Promise.resolve(pluginCallbacks.onIdUpdate({
+                    ...props,
+                    entityId: id
+                }));
+            }
+
+            return id;
+        };
+    }
+
+    return Object.keys(mergedCallbacks).length > 0 ? mergedCallbacks : undefined;
+};