@firecms/core 3.0.0-canary.99 → 3.0.0-rc.1

package/src/routes/FireCMSRoute.tsx

@@ -0,0 +1,246 @@
+import { Blocker, useBlocker, useLocation } from "react-router";
+import { EntityEditView } from "../core/EntityEditView";
+import { useNavigationController } from "../hooks";
+import { useEffect, useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import {
+    getNavigationEntriesFromPath,
+    NavigationViewCollectionInternal,
+    NavigationViewEntityCustomInternal,
+    NavigationViewInternal
+} from "../util/navigation_from_path";
+import { useBreadcrumbsController } from "../hooks/useBreadcrumbsController";
+import { toArray } from "../util/arrays";
+import { EntityCollectionView, NotFoundPage } from "../components";
+import { UnsavedChangesDialog } from "../components/UnsavedChangesDialog";
+import { EntityCollection } from "../types";
+
+export function FireCMSRoute() {
+
+    const location = useLocation();
+    const navigation = useNavigationController();
+    const breadcrumbs = useBreadcrumbsController();
+
+    const hash = location.hash;
+    const isSidePanel = hash.includes("#side");
+    const isNew = hash.includes("#new") || hash.includes("#new_side");
+    const isCopy = hash.includes("#copy");
+
+    const pathname = location.pathname;
+    const navigationPath = navigation.urlPathToDataPath(pathname);
+
+    const navigationEntries = getNavigationEntriesFromPath({
+        path: navigationPath,
+        collections: navigation.collections ?? []
+    });
+
+    useEffect(() => {
+        breadcrumbs.set({
+            breadcrumbs: navigationEntries.map(entry => {
+                if (entry.type === "entity") {
+                    return ({
+                        title: entry.entityId,
+                        url: navigation.buildUrlCollectionPath(entry.fullPath)
+                    });
+                } else if (entry.type === "custom_view") {
+                    return ({
+                        title: entry.view.name,
+                        url: navigation.buildUrlCollectionPath(entry.fullPath)
+                    });
+                } else if (entry.type === "collection") {
+                    return ({
+                        title: entry.collection.name,
+                        url: navigation.buildUrlCollectionPath(entry.fullPath)
+                    });
+                } else {
+                    throw new Error("Unexpected navigation entry type");
+                }
+            })
+        });
+    }, [navigationEntries.map(entry => entry.path).join(",")]);
+
+    if (isNew) {
+        return <EntityFullScreenRoute
+            pathname={pathname}
+            navigationEntries={navigationEntries}
+            isNew={true}
+            isCopy={false}
+        />;
+    }
+
+    if (navigationEntries.length === 1 && navigationEntries[0].type === "collection") {
+        let collection: EntityCollection<any> | undefined;
+        collection = navigation.getCollectionById(navigationEntries[0].id);
+        if (!collection)
+            collection = navigation.getCollection(navigationEntries[0].path);
+        if (!collection)
+            return null;
+        return <EntityCollectionView
+            key={`collection_view_${collection.id ?? collection.path}`}
+            isSubCollection={false}
+            parentCollectionIds={[]}
+            fullPath={collection.path}
+            fullIdPath={collection.id}
+            updateUrl={true}
+            {...collection}
+            Actions={toArray(collection.Actions)}/>
+    }
+
+    if (isSidePanel) {
+        const lastCollectionEntry = navigationEntries.findLast((entry) => entry.type === "collection");
+        if (lastCollectionEntry) {
+            let collection: EntityCollection<any> | undefined;
+            const firstEntry = navigationEntries[0] as NavigationViewCollectionInternal<any>;
+            collection = navigation.getCollectionById(firstEntry.id);
+            if (!collection)
+                collection = navigation.getCollection(firstEntry.path);
+            if (!collection)
+                return null;
+            return <EntityCollectionView
+                key={`collection_view_${collection.id ?? collection.path}`}
+                fullIdPath={collection.id}
+                isSubCollection={false}
+                parentCollectionIds={[]}
+                fullPath={collection.path}
+                updateUrl={true}
+                {...collection}
+                Actions={toArray(collection.Actions)}/>;
+        }
+    }
+
+    return <EntityFullScreenRoute
+        pathname={pathname}
+        navigationEntries={navigationEntries}
+        isNew={isNew}
+        isCopy={isCopy}
+    />;
+
+}
+
+function getSelectedTabFromUrl(isNew: boolean, lastCustomView: NavigationViewCollectionInternal<any> | NavigationViewEntityCustomInternal<any> | undefined) {
+    if (isNew) {
+        return undefined;
+    } else if (lastCustomView) {
+        if (lastCustomView.type === "custom_view") {
+            return lastCustomView.view.key;
+        } else if (lastCustomView.type === "collection") {
+            return lastCustomView.id ?? lastCustomView.path;
+        }
+    }
+    return undefined;
+}
+
+function EntityFullScreenRoute({
+                                   pathname,
+                                   navigationEntries,
+                                   isNew,
+                                   isCopy
+                               }: {
+    pathname: string;
+    navigationEntries: NavigationViewInternal[],
+    isNew: boolean,
+    isCopy: boolean
+}) {
+
+    const navigation = useNavigationController();
+    const navigate = useNavigate();
+
+    const navigationPath = navigation.urlPathToDataPath(pathname);
+
+    // is navigating away blocked
+    const blocked = useRef(false);
+
+    const lastEntityEntry = navigationEntries.findLast((entry) => entry.type === "entity");
+    const navigationEntriesAfterEntity = lastEntityEntry ? navigationEntries.slice(navigationEntries.indexOf(lastEntityEntry) + 1) : [];
+
+    const lastCustomView = navigationEntriesAfterEntity.findLast(
+        (entry) => entry.type === "custom_view" || entry.type === "collection"
+    ) as NavigationViewCollectionInternal<any> | NavigationViewEntityCustomInternal<any> | undefined;
+
+    const entityId = lastEntityEntry?.entityId;
+
+    const urlTab = getSelectedTabFromUrl(isNew, lastCustomView);
+    const [selectedTab, setSelectedTab] = useState<string | undefined>(urlTab);
+
+    const parentCollectionIds = navigation.getParentCollectionIds(navigationPath);
+    useEffect(() => {
+        if (urlTab !== selectedTab) {
+            setSelectedTab(urlTab);
+        }
+    }, [urlTab]);
+
+    const basePath = !entityId || isNew
+        ? pathname
+        : pathname.substring(0, pathname.lastIndexOf(`/${entityId}`));
+
+    const entityPath = basePath + `/${entityId}`;
+
+    let blocker: Blocker | undefined = undefined;
+    try {
+        blocker = useBlocker(({
+                                  nextLocation
+                              }) => {
+            if (nextLocation.pathname.startsWith(entityPath))
+                return false;
+            return blocked.current;
+        });
+    } catch (e) {
+        // console.warn("Blocker not available, navigation will not be blocked");
+    }
+
+    const lastCollectionEntry = navigationEntries.findLast((entry) => entry.type === "collection");
+
+    if (isNew && !lastCollectionEntry) {
+        throw new Error("INTERNAL: No collection found in the navigation");
+    }
+
+    if (!isNew && !lastEntityEntry) {
+        return <NotFoundPage/>;
+    }
+
+    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))}
+            entityId={isNew ? undefined : entityId}
+            fullIdPath={fullIdPath}
+            collection={collection}
+            layout={"full_screen"}
+            path={collectionPath}
+            copy={isCopy}
+            selectedTab={selectedTab ?? undefined}
+            onValuesModified={(modified) => blocked.current = modified}
+            onSaved={(params) => {
+                const newSelectedTab = params.selectedTab;
+                const newEntityId = params.entityId;
+                if (newSelectedTab) {
+                    navigate(`${basePath}/${newEntityId}/${newSelectedTab}`, { replace: true });
+                } else {
+                    navigate(`${basePath}/${newEntityId}`, { replace: true });
+                }
+            }}
+            onTabChange={(params) => {
+                setSelectedTab(params.selectedTab);
+                if (isNew) {
+                    return;
+                }
+                const newSelectedTab = params.selectedTab;
+                if (newSelectedTab) {
+                    navigate(`${basePath}/${entityId}/${newSelectedTab}`, { replace: true });
+                } else {
+                    navigate(`${basePath}/${entityId}`, { replace: true });
+                }
+            }}
+            parentCollectionIds={parentCollectionIds}
+        />
+
+        <UnsavedChangesDialog
+            open={blocker?.state === "blocked"}
+            handleOk={() => blocker?.proceed?.()}
+            handleCancel={() => blocker?.reset?.()}
+            body={"You have unsaved changes in this entity."}/>
+
+    </>;
+}

package/src/routes/HomePageRoute.tsx

@@ -0,0 +1,17 @@
+import { useBreadcrumbsController } from "../hooks/useBreadcrumbsController";
+import { useEffect } from "react";
+
+export function HomePageRoute({ children }: {
+    children: React.ReactNode;
+}) {
+
+    const breadcrumbs = useBreadcrumbsController();
+
+    useEffect(() => {
+        breadcrumbs.set({
+            breadcrumbs: []
+        });
+    }, []);
+
+    return children;
+}

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/auth.tsx

@@ -9,18 +9,13 @@ import { StorageSource } from "./storage";
  * to do it as the result of a hook.
  * @group Hooks and utilities
  */
-export type AuthController<UserType extends User = any, ExtraData = any> = {
+export type AuthController<USER extends User = any, ExtraData = any> = {
 
     /**
      * The user currently logged in
      * The values can be: the user object, null if they skipped login
      */
-    user: UserType | null;
-
-    /**
-     * Roles related to the logged user
-     */
-    roles?: Role[];
+    user: USER | null;
 
     /**
      * Initial loading flag. It is used not to display the login screen
@@ -64,26 +59,27 @@ export type AuthController<UserType extends User = any, ExtraData = any> = {
 
     setExtra: (extra: ExtraData) => void;
 
-    // setUser?: (user: UserType | null) => void;
+    setUser?: (user: USER | null) => void;
+
+    setUserRoles?: (roles: Role[]) => void;
 
-    // setRoles?: (roles: Role[]) => void;
 };
 
 /**
  * Implement this function to allow access to specific users.
  * @group Hooks and utilities
  */
-export type Authenticator<UserType extends User = User, Controller extends AuthController<UserType> = AuthController<UserType>> = (props: {
+export type Authenticator<USER extends User = User> = (props: {
 
     /**
      * Logged-in user or null
      */
-    user: UserType | null;
+    user: USER | null;
 
     /**
      * AuthController
      */
-    authController: Controller;
+    authController: AuthController<USER>;
 
     /**
      * Connector to your database, e.g. your Firestore database

package/src/types/collections.ts

@@ -17,7 +17,7 @@ import { EntityOverrides } from "./entity_overrides";
  *
  * @group Models
  */
-export interface EntityCollection<M extends Record<string, any> = any, UserType extends User = any> {
+export interface EntityCollection<M extends Record<string, any> = any, USER extends User = any> {
 
     /**
      * You can set an alias that will be used internally instead of the `path`.
@@ -51,6 +51,12 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      */
     path: string;
 
+    /**
+     * Optional database id of this collection. If not specified, the default
+     * database id will be used.
+     */
+    databaseId?: string;
+
     /**
      * If this collection is a top level navigation entry, you can set this
      * property to `true` to indicate that this collection is a collection group.
@@ -61,14 +67,18 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * Icon key to use in this collection.
      * You can use any of the icons in the Material specs:
      * https://fonts.google.com/icons
-     * e.g. 'account_tree' or 'person'
+     * 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;
 
@@ -77,6 +87,11 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      */
     properties: PropertiesOrBuilders<M>;
 
+    /**
+     * Default preview properties displayed when this collection is referenced to.
+     */
+    previewProperties?: string[];
+
     /**
      * Title property of the entity. This is the property that will be used
      * as the title in entity related views and references.
@@ -85,11 +100,10 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
     titleProperty?: keyof M;
 
     /**
-     * Can this collection be edited by the end user.
-     * Defaults to `true`.
-     * Keep in mind that you can also set this prop to individual properties.
+     * When editing an entity, you can choose to open the entity in a side dialog
+     * or in a full screen dialog. Defaults to `full_screen`.
      */
-    editable?: boolean;
+    openEntityMode?: "side_panel" | "full_screen";
 
     /**
      * Order in which the properties are displayed.
@@ -101,7 +115,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * `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`.
@@ -112,11 +126,12 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * `hidden` in the property definition,will be ignored.
      * `propertiesOrder` has precedence over `hidden`.
      */
-    propertiesOrder?: (Extract<keyof M, string> | `subcollection:${string}`)[];
+    propertiesOrder?: (Extract<keyof M, string> | string | `subcollection:${string}` | "collectionGroupParent")[];
 
     /**
      * 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`
      */
@@ -132,7 +147,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * Permissions the logged-in user can perform on this collection.
      * If not specified everything defaults to `true`.
      */
-    permissions?: Permissions | PermissionsBuilder<EntityCollection, UserType, M>;
+    permissions?: Permissions | PermissionsBuilder<EntityCollection, USER, M>;
 
     /**
      * Are the entities in this collection selectable. Defaults to `true`
@@ -151,7 +166,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * is being created, updated or deleted.
      * Useful for adding your own logic or blocking the execution of the operation.
      */
-    callbacks?: EntityCallbacks<M, UserType>;
+    callbacks?: EntityCallbacks<M, USER>;
 
     /**
      * Builder for rendering additional components such as buttons in the
@@ -181,8 +196,11 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      *     }
      * }
      * ```
+     *
+     * 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, UserType>[];
+    entityActions?: (EntityAction<M, USER> | string)[];
 
     /**
      * Pass your own selection controller if you want to control selected
@@ -204,6 +222,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * Force a filter in this view. If applied, the rest of the filters will
      * be disabled. Filters applied with this prop cannot be changed.
      * e.g. `forceFilter: { age: [">=", 18] }`
+     * e.g. `forceFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
      */
     forceFilter?: FilterValues<Extract<keyof M, string>>;
 
@@ -211,6 +230,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * Initial filters applied to the collection this collection is related to.
      * Defaults to none. Filters applied with this prop can be changed.
      * e.g. `initialFilter: { age: [">=", 18] }`
+     * e.g. `initialFilter: { related_user: ["==", new EntityReference("sdc43dsw2", "users")] }`
      */
     initialFilter?: FilterValues<Extract<keyof M, string>>; // setting FilterValues<M> can break defining collections by code
 
@@ -234,7 +254,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * You can add additional fields to the collection view by implementing
      * an additional field delegate.
      */
-    additionalFields?: AdditionalFieldDelegate<M, UserType>[];
+    additionalFields?: AdditionalFieldDelegate<M, USER>[];
 
     /**
      * Default size of the rendered collection
@@ -287,7 +307,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
     /**
      *
      */
-    exportable?: boolean | ExportConfig<UserType>;
+    exportable?: boolean | ExportConfig<USER>;
 
     /**
      * User id of the owner of this collection. This is used only by plugins, or if you
@@ -304,6 +324,32 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * Width of the side dialog (in pixels) when opening an entity in this collection.
      */
     sideDialogWidth?: number | string;
+
+    /**
+     * Can this collection configuration be edited by the end user.
+     * Defaults to `true`.
+     * Keep in mind that you can also set this prop to individual properties.
+     * This prop has only effect if you are using the collection editor.
+     */
+    editable?: boolean;
+
+    /**
+     * If set to true, the default values of the properties will be applied
+     * to the entity every time the entity is updated (not only when created).
+     * Defaults to false.
+     */
+    alwaysApplyDefaultValues?: boolean;
+
+    /**
+     * 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;
 }
 
 /**
@@ -313,7 +359,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
  *
  * @group Models
  */
-export interface CollectionActionsProps<M extends Record<string, any> = any, UserType extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
+export interface CollectionActionsProps<M extends Record<string, any> = any, USER extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
     /**
      * Full collection path of this entity. This is the full path, like
      * `users/1234/addresses`
@@ -350,7 +396,7 @@ export interface CollectionActionsProps<M extends Record<string, any> = any, Use
     /**
      * Context of the app status
      */
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 
     /**
      * Count of the entities in this collection
@@ -412,9 +458,9 @@ export type FilterCombination<Key extends string> = Partial<Record<Key, "asc" |
  */
 export type CollectionSize = "xs" | "s" | "m" | "l" | "xl";
 
-export type AdditionalFieldDelegateProps<M extends Record<string, any> = any, UserType extends User = User> = {
+export type AdditionalFieldDelegateProps<M extends Record<string, any> = any, USER extends User = User> = {
     entity: Entity<M>,
-    context: FireCMSContext<UserType>
+    context: FireCMSContext<USER>
 };
 
 /**
@@ -423,7 +469,7 @@ export type AdditionalFieldDelegateProps<M extends Record<string, any> = any, Us
  * @group Models
  */
 export interface AdditionalFieldDelegate<M extends Record<string, any> = any,
-    UserType extends User = User> {
+    USER extends User = User> {
 
     /**
      * ID of this column. You can use this id in the `properties` field of the
@@ -444,7 +490,7 @@ export interface AdditionalFieldDelegate<M extends Record<string, any> = any,
     /**
      * Builder for the content of the cell for this column
      */
-    Builder?: React.ComponentType<AdditionalFieldDelegateProps<M, UserType>>;
+    Builder?: React.ComponentType<AdditionalFieldDelegateProps<M, USER>>;
 
     /**
      * If this column needs to update dynamically based on other properties,
@@ -479,21 +525,36 @@ export type EntityCustomView<M extends Record<string, any> = any> =
         /**
          * Key of this custom view.
          */
-        key: string,
+        key: string;
+
         /**
          * Name of this custom view.
          */
-        name: string,
+        name: string;
+
         /**
-         * If set to true, the actions of the entity will be included in the
-         * bottom of the panel (save buttons, delete buttons, etc.)
+         * Render this custom view in the tab of the entity view, instead of the name
          */
-        includeActions?: boolean;
+        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,
+         * based on the screen size. You can force the actions to be located at the bottom
+         * by setting this prop to "bottom".
+         */
+        includeActions?: boolean | "bottom";
+
         /**
          * 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";
+    };
 
 /**
  * Parameters passed to the builder in charge of rendering a custom panel for
@@ -523,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;
@@ -558,6 +624,12 @@ export type EntityTableController<M extends Record<string, any> = any> = {
     clearFilter?: () => void;
     itemCount?: number;
     setItemCount?: (itemCount: number) => void;
+    initialScroll?: number;
+    onScroll?: (props: {
+        scrollDirection: "forward" | "backward",
+        scrollOffset: number,
+        scrollUpdateWasRequested: boolean
+    }) => void;
     paginationEnabled?: boolean;
     pageSize?: number;
     checkFilterCombination?: (filterValues: FilterValues<any>,
@@ -573,5 +645,6 @@ export type SelectedCellProps<M extends Record<string, any>> = {
     cellRect: DOMRect;
     width: number;
     height: number;
-    entity: Entity<M>;
+    entityPath: string;
+    entityId: string;
 };

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'