@firecms/core 3.0.0 → 3.1.0-canary.02232f4

package/src/routes/FireCMSRoute.tsx

@@ -1,7 +1,6 @@
 import { Blocker, useBlocker, useLocation } from "react-router";
-import { EntityEditView } from "../core/EntityEditView";
+import React, { useEffect, useRef, useState } from "react";
 import { useNavigationController } from "../hooks";
-import { useEffect, useRef, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import {
     getNavigationEntriesFromPath,
@@ -11,7 +10,11 @@ import {
 } from "../util/navigation_from_path";
 import { useBreadcrumbsController } from "../hooks/useBreadcrumbsController";
 import { toArray } from "../util/arrays";
-import { EntityCollectionView, NotFoundPage } from "../components";
+import { NotFoundPage } from "../components";
+import { lazyEager } from "../util/lazy_eager";
+
+const EntityEditView = lazyEager<typeof import("../core/EntityEditView")["EntityEditView"]>(() => import("../core/EntityEditView"), "EntityEditView");
+const EntityCollectionView = lazyEager<typeof import("../components/EntityCollectionView/EntityCollectionView")["EntityCollectionView"]>(() => import("../components/EntityCollectionView/EntityCollectionView"), "EntityCollectionView");
 import { UnsavedChangesDialog } from "../components/UnsavedChangesDialog";
 import { EntityCollection } from "../types";
 
@@ -35,22 +38,34 @@ export function FireCMSRoute() {
     });
 
     useEffect(() => {
+        const lastEntry = navigationEntries[navigationEntries.length - 1];
+        const isViewingCollection = lastEntry?.type === "collection";
+
         breadcrumbs.set({
-            breadcrumbs: navigationEntries.map(entry => {
+            breadcrumbs: navigationEntries.map((entry, index) => {
+                const isLastEntry = index === navigationEntries.length - 1;
+
                 if (entry.type === "entity") {
                     return ({
                         title: entry.entityId,
                         url: navigation.buildUrlCollectionPath(entry.fullPath)
+                        // count: undefined (not applicable for entities)
                     });
                 } else if (entry.type === "custom_view") {
                     return ({
                         title: entry.view.name,
                         url: navigation.buildUrlCollectionPath(entry.fullPath)
+                        // count: undefined (not applicable for custom views)
                     });
                 } else if (entry.type === "collection") {
+                    // Only show count badge (loading state) when viewing this collection directly
+                    // Don't show count for parent collections when viewing an entity
+                    const showCount = isLastEntry && isViewingCollection;
                     return ({
                         title: entry.collection.name,
-                        url: navigation.buildUrlCollectionPath(entry.fullPath)
+                        url: navigation.buildUrlCollectionPath(entry.fullPath),
+                        id: entry.fullPath,
+                        ...(showCount ? { count: null } : {}) // null = loading, undefined = no badge
                     });
                 } else {
                     throw new Error("Unexpected navigation entry type");
@@ -59,6 +74,7 @@ export function FireCMSRoute() {
         });
     }, [navigationEntries.map(entry => entry.path).join(",")]);
 
+
     if (isNew) {
         return <EntityFullScreenRoute
             pathname={pathname}
@@ -75,15 +91,17 @@ export function FireCMSRoute() {
             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)}/>
+        return <React.Suspense fallback={null}>
+            <EntityCollectionView
+                key={`collection_view_${collection.id ?? collection.path}`}
+                isSubCollection={false}
+                parentCollectionIds={[]}
+                fullPath={collection.path}
+                fullIdPath={collection.id}
+                updateUrl={true}
+                {...collection}
+                Actions={toArray(collection.Actions)} />
+        </React.Suspense>;
     }
 
     if (isSidePanel) {
@@ -96,15 +114,17 @@ export function FireCMSRoute() {
                 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 <React.Suspense fallback={null}>
+                <EntityCollectionView
+                    key={`collection_view_${collection.id ?? collection.path}`}
+                    fullIdPath={collection.id}
+                    isSubCollection={false}
+                    parentCollectionIds={[]}
+                    fullPath={collection.path}
+                    updateUrl={true}
+                    {...collection}
+                    Actions={toArray(collection.Actions)} />
+            </React.Suspense>;
         }
     }
 
@@ -131,11 +151,11 @@ function getSelectedTabFromUrl(isNew: boolean, lastCustomView: NavigationViewCol
 }
 
 function EntityFullScreenRoute({
-                                   pathname,
-                                   navigationEntries,
-                                   isNew,
-                                   isCopy
-                               }: {
+    pathname,
+    navigationEntries,
+    isNew,
+    isCopy
+}: {
     pathname: string;
     navigationEntries: NavigationViewInternal[],
     isNew: boolean,
@@ -178,8 +198,8 @@ function EntityFullScreenRoute({
     let blocker: Blocker | undefined = undefined;
     try {
         blocker = useBlocker(({
-                                  nextLocation
-                              }) => {
+            nextLocation
+        }) => {
             if (nextLocation.pathname.startsWith(entityPath))
                 return false;
             return blocked.current;
@@ -195,52 +215,54 @@ function EntityFullScreenRoute({
     }
 
     if (!isNew && !lastEntityEntry) {
-        return <NotFoundPage/>;
+        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}
-        />
+        <React.Suspense fallback={null}>
+            <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}
+            />
+        </React.Suspense>
 
         <UnsavedChangesDialog
             open={blocker?.state === "blocked"}
             handleOk={() => blocker?.proceed?.()}
             handleCancel={() => blocker?.reset?.()}
-            body={"You have unsaved changes in this entity."}/>
+            body={"You have unsaved changes in this entity."} />
 
     </>;
 }

package/src/types/analytics.ts

@@ -34,5 +34,15 @@ export type CMSAnalyticsEvent =
 
     | "collection_inline_editing"
 
+    | "view_mode_changed"
+
+    | "kanban_card_moved"
+    | "kanban_column_reorder"
+    | "kanban_property_changed"
+    | "kanban_new_entity_in_column"
+    | "kanban_backfill_order"
+
+    | "card_view_entity_click"
+
     | "unmapped_event"
     ;

package/src/types/collections.ts

@@ -163,6 +163,31 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      */
     subcollections?: EntityCollection<any, any>[];
 
+    /**
+     * You can group subcollections and custom views into dropdown menus
+     * in the entity view tabs. Views listed in a group will be removed
+     * from the top-level tabs and shown under a single dropdown instead.
+     *
+     * @example
+     * ```tsx
+     * const productsCollection = buildCollection({
+     *     id: "products",
+     *     path: "products",
+     *     name: "Products",
+     *     properties: { ... },
+     *     subcollections: [localesCollection, reviewsCollection],
+     *     entityViews: [sampleView],
+     *     viewGroups: [
+     *         {
+     *             name: "Related data",
+     *             views: ["locales", "reviews", "sample_view"]
+     *         }
+     *     ]
+     * });
+     * ```
+     */
+    viewGroups?: ViewGroup[];
+
     /**
      * This interface defines all the callbacks that can be used when an entity
      * is being created, updated or deleted.
@@ -364,8 +389,76 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * Defaults to `manual_apply`.
      */
     localChangesBackup?: "manual_apply" | "auto_apply" | false;
+
+    /**
+     * Default view mode for displaying this collection.
+     * - "table": Display entities in a spreadsheet-like table (default)
+     * - "cards": Display entities as a grid of cards with thumbnails
+     * - "kanban": Display entities in a Kanban board grouped by a property
+     * Defaults to "table".
+     */
+    defaultViewMode?: ViewMode;
+
+    /**
+     * Which view modes are available for this collection.
+     * Possible values: "table", "cards", "kanban".
+     * Defaults to all three: ["table", "cards", "kanban"].
+     * Note: "kanban" will only be available if the collection has at least
+     * one string property with enumValues defined, regardless of this setting.
+     */
+    enabledViews?: ViewMode[];
+
+    /**
+     * Configuration for Kanban board view mode.
+     * When set, the Kanban view mode becomes available.
+     */
+    kanban?: KanbanConfig<M>;
+
+    /**
+     * Property key to use for ordering items.
+     * Must reference a number property. When items are reordered,
+     * this property will be updated to reflect the new order using
+     * fractional indexing. Used by Kanban view for ordering within columns
+     * and can be used for general ordering purposes.
+     */
+    orderProperty?: Extract<keyof M, string>;
 }
 
+/**
+ * Configuration for Kanban board view mode.
+ * @group Collections
+ */
+export interface KanbanConfig<M extends Record<string, any> = any> {
+    /**
+     * Property key to use for Kanban board columns.
+     * Must reference a string property with enumValues defined.
+     * Entities will be grouped into columns based on this property's value.
+     * The column order is determined by the order of enumValues in the property.
+     */
+    columnProperty: Extract<keyof M, string>;
+}
+
+/**
+ * You can group subcollections and custom views into dropdown menus in the entity view tabs.
+ * @group Collections
+ */
+export interface ViewGroup {
+    /**
+     * Name of the group
+     */
+    name: string;
+    /**
+     * Array of subcollection paths/ids or custom view keys
+     */
+    views: string[];
+}
+
+/**
+ * View mode for displaying a collection.
+ * @group Collections
+ */
+export type ViewMode = "table" | "cards" | "kanban";
+
 /**
  * Parameter passed to the `Actions` prop in the collection configuration.
  * The component will receive this prop when it is rendered in the collection
@@ -413,9 +506,10 @@ export interface CollectionActionsProps<M extends Record<string, any> = any, USE
     context: FireCMSContext<USER>;
 
     /**
-     * Count of the entities in this collection
+     * Count of the entities in this collection.
+     * undefined means the count is still loading.
      */
-    collectionEntitiesCount: number;
+    collectionEntitiesCount?: number;
 
 }
 
@@ -647,7 +741,7 @@ export type EntityTableController<M extends Record<string, any> = any> = {
     paginationEnabled?: boolean;
     pageSize?: number;
     checkFilterCombination?: (filterValues: FilterValues<any>,
-                              sortBy?: [string, "asc" | "desc"]) => boolean;
+        sortBy?: [string, "asc" | "desc"]) => boolean;
     popupCell?: SelectedCellProps<M>;
     setPopupCell?: (popupCell?: SelectedCellProps<M>) => void;
 

package/src/types/customization_controller.tsx

@@ -42,7 +42,8 @@ export type CustomizationController = {
     dateTimeFormat?: string;
 
     /**
-     * Locale of the CMS, currently only affecting dates
+     * Locale of the CMS.
+     * Affects date formatting.
      */
     locale?: Locale;
 

package/src/types/datasource.ts

@@ -19,9 +19,9 @@ export interface FetchEntityProps<M extends Record<string, any> = any> {
 export type ListenEntityProps<M extends Record<string, any> = any> =
     FetchEntityProps<M>
     & {
-    onUpdate: (entity: Entity<M>) => void,
-    onError?: (error: Error) => void,
-}
+        onUpdate: (entity: Entity<M>) => void,
+        onError?: (error: Error) => void,
+    }
 
 /**
  * @group Datasource
@@ -88,15 +88,15 @@ export interface DataSource {
      * @see useCollectionFetch if you need this functionality implemented as a hook
      */
     fetchCollection<M extends Record<string, any> = any>({
-                                                             path,
-                                                             collection,
-                                                             filter,
-                                                             limit,
-                                                             startAfter,
-                                                             orderBy,
-                                                             order,
-                                                             searchString
-                                                         }: FetchCollectionProps<M>
+        path,
+        collection,
+        filter,
+        limit,
+        startAfter,
+        orderBy,
+        order,
+        searchString
+    }: FetchCollectionProps<M>
     ): Promise<Entity<M>[]>;
 
     /**
@@ -137,11 +137,11 @@ export interface DataSource {
      * @param collection
      */
     fetchEntity<M extends Record<string, any> = any>({
-                                                         path,
-                                                         entityId,
-                                                         databaseId,
-                                                         collection
-                                                     }: FetchEntityProps<M>
+        path,
+        entityId,
+        databaseId,
+        collection
+    }: FetchEntityProps<M>
     ): Promise<Entity<M> | undefined>;
 
     /**
@@ -154,12 +154,12 @@ export interface DataSource {
      * @return Function to cancel subscription
      */
     listenEntity?<M extends Record<string, any> = any>({
-                                                           path,
-                                                           entityId,
-                                                           collection,
-                                                           onUpdate,
-                                                           onError
-                                                       }: ListenEntityProps<M>): () => void;
+        path,
+        entityId,
+        collection,
+        onUpdate,
+        onError
+    }: ListenEntityProps<M>): () => void;
 
     /**
      * Save entity to the specified path
@@ -274,14 +274,14 @@ export interface DataSourceDelegate {
      * @see useCollectionFetch if you need this functionality implemented as a hook
      */
     fetchCollection<M extends Record<string, any> = any>({
-                                                             path,
-                                                             filter,
-                                                             limit,
-                                                             startAfter,
-                                                             orderBy,
-                                                             order,
-                                                             searchString
-                                                         }: FetchCollectionDelegateProps<M>): Promise<Entity<M>[]>;
+        path,
+        filter,
+        limit,
+        startAfter,
+        orderBy,
+        order,
+        searchString
+    }: FetchCollectionDelegateProps<M>): Promise<Entity<M>[]>;
 
     /**
      * Listen to a collection in a given path. If you don't implement this method
@@ -299,16 +299,16 @@ export interface DataSourceDelegate {
      * @see useCollectionFetch if you need this functionality implemented as a hook
      */
     listenCollection?<M extends Record<string, any> = any>({
-                                                               path,
-                                                               filter,
-                                                               limit,
-                                                               startAfter,
-                                                               searchString,
-                                                               orderBy,
-                                                               order,
-                                                               onUpdate,
-                                                               onError
-                                                           }: ListenCollectionDelegateProps<M>): () => void;
+        path,
+        filter,
+        limit,
+        startAfter,
+        searchString,
+        orderBy,
+        order,
+        onUpdate,
+        onError
+    }: ListenCollectionDelegateProps<M>): () => void;
 
     /**
      * Retrieve an entity given a path and a collection
@@ -316,9 +316,9 @@ export interface DataSourceDelegate {
      * @param entityId
      */
     fetchEntity<M extends Record<string, any> = any>({
-                                                         path,
-                                                         entityId,
-                                                     }: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
+        path,
+        entityId,
+    }: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
 
     /**
      * Get realtime updates on one entity.
@@ -330,11 +330,11 @@ export interface DataSourceDelegate {
      * @return Function to cancel subscription
      */
     listenEntity?<M extends Record<string, any> = any>({
-                                                           path,
-                                                           entityId,
-                                                           onUpdate,
-                                                           onError
-                                                       }: ListenEntityProps<M>): () => void;
+        path,
+        entityId,
+        onUpdate,
+        onError
+    }: ListenEntityProps<M>): () => void;
 
     /**
      * Save entity to the specified path
@@ -344,11 +344,11 @@ export interface DataSourceDelegate {
      * @param status
      */
     saveEntity<M extends Record<string, any> = any>({
-                                                        path,
-                                                        entityId,
-                                                        values,
-                                                        status
-                                                    }: SaveEntityDelegateProps<M>): Promise<Entity<M>>;
+        path,
+        entityId,
+        values,
+        status
+    }: SaveEntityDelegateProps<M>): Promise<Entity<M>>;
 
     /**
      * Delete an entity
@@ -395,8 +395,6 @@ export interface DataSourceDelegate {
 
     cmsToDelegateModel: (data: any) => any;
 
-    setDateToMidnight: (input?: any) => any;
-
     initTextSearch?: (props: {
         context: FireCMSContext,
         path: string,

package/src/types/entities.ts

@@ -65,6 +65,16 @@ export class EntityReference {
         return `${this.path}/${this.id}`;
     }
 
+    get pathWithIdAndDatabase() {
+        if (this.databaseId) {
+            if (this.databaseId === "(default)") {
+                return this.pathWithId;
+            }
+            return `${this.databaseId}:::${this.path}/${this.id}`;
+        }
+        return this.pathWithId;
+    }
+
     isEntityReference() {
         return true;
     }

package/src/types/firecms.tsx

@@ -111,7 +111,8 @@ export type FireCMSProps<USER extends User> = {
     dateTimeFormat?: string;
 
     /**
-     * Locale of the CMS, currently only affecting dates
+     * Locale of the CMS.
+     * Affects date formatting.
      */
     locale?: Locale;
 

package/src/types/index.ts

@@ -28,3 +28,4 @@ export * from "./export_import";
 export * from "./modify_collections";
 export * from "./analytics_controller";
 export * from "./customization_controller";
+export * from "./translations";

package/src/types/navigation.ts

@@ -252,7 +252,7 @@ export interface NavigationEntry {
     collection?: EntityCollection;
     view?: CMSView;
     description?: string;
-    group: string;
+    group: string | null;
 }
 
 export type NavigationResult = {
@@ -261,7 +261,7 @@ export type NavigationResult = {
 
     navigationEntries: NavigationEntry[],
 
-    groups: string[],
+    groups: (string | null)[],
 
     onNavigationEntriesUpdate: (entries: NavigationGroupMapping[]) => void;
 };