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

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.
@@ -94,6 +95,14 @@ export type FireCMSProps<USER extends User> = {
      */
     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'

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
@@ -206,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.
@@ -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?: {
@@ -151,8 +166,16 @@ 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;
@@ -206,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,6 +15,11 @@ 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
      */

package/src/util/icons.tsx

@@ -4,13 +4,28 @@ 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 | React.ReactNode,
+                        className?: string,
+                        color?: IconColor,
+                        size?: "smallest" | "small" | "medium" | "large" | number,): React.ReactElement | undefined {
+
+    if (React.isValidElement(iconKey)) {
+        return iconKey;
+    }
+
     if (!iconKey) return undefined;
-    iconKey = slugify(iconKey);
-    if (!(iconKey in iconKeysMap)) {
-        return undefined;
+    if (typeof iconKey === "string") {
+
+        const usedIconKey = slugify(iconKey);
+        if (!(usedIconKey in iconKeysMap)) {
+            return undefined;
+        }
+        return usedIconKey in iconKeysMap ?
+            <Icon iconKey={usedIconKey} size={size} className={className} color={color}/> : undefined;
     }
-    return iconKey in iconKeysMap ? <Icon iconKey={iconKey} size={"medium"} className={className} color={color}/> : undefined;
+
+    console.warn("Invalid icon key provided:", iconKey);
+    return undefined;
 }
 
 export type IconViewProps = {
@@ -18,7 +33,7 @@ export type IconViewProps = {
     name: string;
     singularName?: string;
     group?: string;
-    icon?: string;
+    icon?: string | React.ReactNode;
 }
 
 export const IconForView = React.memo(
@@ -34,7 +49,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;
 

package/src/util/join_collections.ts

@@ -100,13 +100,15 @@ export function mergeCollection(target: EntityCollection,
     const sourcePropertiesOrder = getCollectionKeys(source);
     const mergedPropertiesOrder = [...new Set([...sourcePropertiesOrder, ...targetPropertiesOrder])];
     const mergedEntityViews = [...new Set([...(target.entityViews ?? []), ...(source.entityViews ?? [])])];
+    const mergedEntityActions = [...new Set([...(target.entityActions ?? []), ...(source.entityActions ?? [])])];
 
     let resultCollection: EntityCollection = {
         ...mergedCollection,
         subcollections: subcollectionsMerged,
         properties: sortProperties(propertiesMerged, mergedPropertiesOrder),
         propertiesOrder: mergedPropertiesOrder,
-        entityViews: mergedEntityViews
+        entityViews: mergedEntityViews,
+        entityActions: mergedEntityActions,
     };
     if (modifyCollection) {
         const modifiedCollection = modifyCollection({

package/src/util/navigation_from_path.ts

@@ -11,6 +11,7 @@ export interface NavigationViewEntityInternal<M extends Record<string, any>> {
     type: "entity";
     entityId: string;
     path: string;
+    fullIdPath: string;
     fullPath: string;
     parentCollection: EntityCollection<M>;
 }
@@ -19,6 +20,7 @@ export interface NavigationViewCollectionInternal<M extends Record<string, any>>
     type: "collection";
     id: string;
     path: string;
+    fullIdPath: string;
     fullPath: string;
     collection: EntityCollection<M>;
 }
@@ -26,6 +28,7 @@ export interface NavigationViewCollectionInternal<M extends Record<string, any>>
 export interface NavigationViewEntityCustomInternal<M extends Record<string, any>> {
     type: "custom_view";
     path: string;
+    fullIdPath: string;
     fullPath: string;
     entityId: string;
     view: EntityCustomView<M>;
@@ -35,13 +38,15 @@ export function getNavigationEntriesFromPath(props: {
     path: string,
     collections: EntityCollection[] | undefined,
     currentFullPath?: string,
+    currentFullIdPath?: string,
     contextEntityViews?: EntityCustomView<any>[]
 }): NavigationViewInternal [] {
 
     const {
         path,
         collections = [],
-        currentFullPath
+        currentFullPath,
+        currentFullIdPath
     } = props;
 
     const subpaths = removeInitialAndTrailingSlashes(path).split("/");
@@ -58,16 +63,18 @@ export function getNavigationEntriesFromPath(props: {
         }
 
         if (collection) {
-            const pathOrAlias = collection.id ?? collection.path;
             const collectionPath = currentFullPath && currentFullPath.length > 0
-                ? (currentFullPath + "/" + pathOrAlias)
-                : pathOrAlias;
-
+                ? (currentFullPath + "/" + collection.path)
+                : collection.path;
+            const fullIdPath = currentFullIdPath && currentFullIdPath.length > 0
+                ? (currentFullIdPath + "/" + collection.id)
+                : collection.id;
             result.push({
                 type: "collection",
                 id: collection.id,
                 path: collectionPath,
                 fullPath: collectionPath,
+                fullIdPath,
                 collection
             });
             const restOfThePath = removeInitialAndTrailingSlashes(removeInitialAndTrailingSlashes(path).replace(subpathCombination, ""));
@@ -79,6 +86,7 @@ export function getNavigationEntriesFromPath(props: {
                     type: "entity",
                     entityId,
                     path: collectionPath,
+                    fullIdPath,
                     fullPath: fullPath,
                     parentCollection: collection
                 });
@@ -97,6 +105,7 @@ export function getNavigationEntriesFromPath(props: {
                             type: "custom_view",
                             path: collectionPath,
                             entityId: entityId,
+                            fullIdPath,
                             fullPath: fullPath + "/" + customView.key,
                             view: customView
                         });
@@ -105,6 +114,7 @@ export function getNavigationEntriesFromPath(props: {
                             path: newPath,
                             collections: collection.subcollections,
                             currentFullPath: fullPath,
+                            currentFullIdPath: fullIdPath,
                             contextEntityViews: props.contextEntityViews
                         }));
                     }

package/src/util/navigation_utils.ts

@@ -201,8 +201,8 @@ export function navigateToEntity({
 
         sideEntityController.open({
             entityId,
-            path: fullIdPath ?? path,
-            // fullIdPath,
+            path,
+            fullIdPath,
             copy,
             selectedTab,
             collection,

package/src/util/resolutions.ts

@@ -3,6 +3,7 @@ import {
     AuthController,
     CMSType,
     CustomizationController,
+    EntityAction,
     EntityCollection,
     EntityCustomView,
     EntityValues,
@@ -438,6 +439,17 @@ export function resolveEntityView(entityView: string | EntityCustomView<any>, co
     }
 }
 
+export function resolveEntityAction<M extends Record<string, any>>(
+    entityAction: string | EntityAction<M>,
+    contextEntityActions?: EntityAction<M>[]
+): EntityAction<M> | undefined {
+    if (typeof entityAction === "string") {
+        return contextEntityActions?.find((entry) => entry.key === entityAction);
+    } else {
+        return entityAction;
+    }
+}
+
 export function resolvedSelectedEntityView<M extends Record<string, any>>(
     customViews: (string | EntityCustomView<M>)[] | undefined,
     customizationController: CustomizationController,
@@ -447,7 +459,7 @@ export function resolvedSelectedEntityView<M extends Record<string, any>>(
     const resolvedEntityViews = customViews ? customViews
             .map(e => resolveEntityView(e, customizationController.entityViews))
             .filter((e): e is EntityCustomView<M> => Boolean(e))
-            // .filter((e) => canEdit || !e.includeActions)
+        // .filter((e) => canEdit || !e.includeActions)
         : [];
 
     const selectedEntityView = resolvedEntityViews.find(e => e.key === selectedTab);