@firecms/core 3.1.0-canary.9e89e98 → 3.1.0

package/dist/internal/useRestoreScroll.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 export declare function useRestoreScroll(): {
-    containerRef: React.RefObject<HTMLDivElement>;
+    containerRef: React.RefObject<HTMLDivElement | null>;
     scroll: number;
     direction: "up" | "down";
 };

package/dist/types/analytics.d.ts

@@ -1 +1 @@
-export type CMSAnalyticsEvent = "entity_click" | "entity_click_from_reference" | "reference_selection_clear" | "reference_selection_toggle" | "reference_selected_single" | "reference_selection_new_entity" | "edit_entity_clicked" | "entity_edited" | "new_entity_click" | "new_entity_saved" | "copy_entity_click" | "entity_copied" | "single_delete_dialog_open" | "multiple_delete_dialog_open" | "single_entity_deleted" | "multiple_entities_deleted" | "drawer_navigate_to_home" | "drawer_navigate_to_collection" | "drawer_navigate_to_view" | "home_navigate_to_collection" | "home_favorite_navigate_to_collection" | "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" | "unmapped_event";
+export type CMSAnalyticsEvent = "entity_click" | "entity_click_from_reference" | "reference_selection_clear" | "reference_selection_toggle" | "reference_selected_single" | "reference_selection_new_entity" | "edit_entity_clicked" | "entity_edited" | "new_entity_click" | "new_entity_saved" | "copy_entity_click" | "entity_copied" | "single_delete_dialog_open" | "multiple_delete_dialog_open" | "single_entity_deleted" | "multiple_entities_deleted" | "drawer_navigate_to_home" | "drawer_navigate_to_collection" | "drawer_navigate_to_view" | "home_navigate_to_collection" | "home_favorite_navigate_to_collection" | "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" | "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/dist/types/plugins.d.ts

@@ -91,6 +91,18 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
         onNavigationEntriesUpdate?: (entries: NavigationGroupMapping[]) => void;
     };
     collectionView?: {
+        /**
+         * Custom component to render when a collection loading error occurs.
+         * If provided, this replaces the default error view in all collection view modes
+         * (table, card, kanban).
+         * Return `null` from the component to fall back to the default error view.
+         */
+        CollectionError?: React.ComponentType<{
+            path: string;
+            collection: EC;
+            parentCollectionIds?: string[];
+            error: Error;
+        }>;
         /**
          * Use this component to add custom actions to the entity collections
          * toolbar.
@@ -194,6 +206,10 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
          * Add custom actions to the top of the form
          */
         ActionsTop?: React.ComponentType<PluginFormActionProps<any, EC>>;
+        /**
+         * Add custom content above the entity title in the form view
+         */
+        BeforeTitle?: 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;
     };

package/dist/util/entities.d.ts

@@ -1,7 +1,7 @@
 import { CMSType, DataType, Entity, EntityReference, EntityStatus, EntityValues, PropertiesOrBuilders, Property, PropertyBuilder, PropertyOrBuilder, ResolvedProperties, ResolvedProperty } from "../types";
 export declare function isReadOnly(property: Property<any> | ResolvedProperty<any>): boolean;
 export declare function isHidden(property: Property | ResolvedProperty): boolean;
-export declare function isPropertyBuilder<T extends CMSType, M extends Record<string, any>>(propertyOrBuilder?: PropertyOrBuilder<T, M> | Property<T> | ResolvedProperty<T>): propertyOrBuilder is PropertyBuilder<T, M>;
+export declare function isPropertyBuilder<T extends CMSType = CMSType, M extends Record<string, any> = any>(propertyOrBuilder?: PropertyOrBuilder<T, M> | Property | ResolvedProperty): propertyOrBuilder is PropertyBuilder<T, M>;
 export declare function getDefaultValuesFor<M extends Record<string, any>>(properties: PropertiesOrBuilders<M> | ResolvedProperties<M>): Partial<EntityValues<M>>;
 export declare function getDefaultValueFor(property?: PropertyOrBuilder): {} | null | undefined;
 export declare function getDefaultValueForDataType(dataType: DataType): {} | null;

package/dist/util/resolutions.d.ts

@@ -1,4 +1,4 @@
-import { ArrayProperty, AuthController, CMSType, CustomizationController, EntityAction, EntityCollection, EntityCustomView, EntityValues, EnumValueConfig, EnumValues, NumberProperty, PropertiesOrBuilders, PropertyConfig, PropertyOrBuilder, ResolvedArrayProperty, ResolvedEntityCollection, ResolvedNumberProperty, ResolvedProperties, ResolvedProperty, ResolvedStringProperty, StringProperty, UserConfigurationPersistence } from "../types";
+import { ArrayProperty, AuthController, CMSType, CustomizationController, EntityAction, EntityCollection, EntityCustomView, EntityValues, EnumValueConfig, EnumValues, NumberProperty, PropertiesOrBuilders, Property, PropertyConfig, PropertyOrBuilder, ResolvedArrayProperty, ResolvedEntityCollection, ResolvedNumberProperty, ResolvedProperties, ResolvedProperty, ResolvedStringProperty, StringProperty, UserConfigurationPersistence } from "../types";
 export declare const resolveCollection: <M extends Record<string, any>>({ collection, path, entityId, values, previousValues, userConfigPersistence, propertyConfigs, ignoreMissingFields, authController }: {
     collection: EntityCollection<M> | ResolvedEntityCollection<M>;
     path: string;
@@ -17,7 +17,7 @@ export declare const resolveCollection: <M extends Record<string, any>>({ collec
  */
 export declare function resolveProperty<T extends CMSType = CMSType, M extends Record<string, any> = any>({ propertyOrBuilder, fromBuilder, ignoreMissingFields, ...props }: {
     propertyKey?: string;
-    propertyOrBuilder: PropertyOrBuilder<T, M> | ResolvedProperty<T>;
+    propertyOrBuilder: PropertyOrBuilder<T, M> | ResolvedProperty<T> | PropertyOrBuilder | Property | ResolvedProperty | undefined;
     values?: Partial<M>;
     previousValues?: Partial<M>;
     path?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firecms/core",
   "type": "module",
-  "version": "3.1.0-canary.9e89e98",
+  "version": "3.1.0",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/firecmsco"
@@ -53,9 +53,9 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
-    "@firecms/editor": "^3.1.0-canary.9e89e98",
-    "@firecms/formex": "^3.1.0-canary.9e89e98",
-    "@firecms/ui": "^3.1.0-canary.9e89e98",
+    "@firecms/editor": "^3.1.0",
+    "@firecms/formex": "^3.1.0",
+    "@firecms/ui": "^3.1.0",
     "@radix-ui/react-portal": "^1.1.10",
     "clsx": "^2.1.1",
     "compressorjs": "^1.2.1",
@@ -76,8 +76,8 @@
     "yup": "^1.7.1"
   },
   "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0",
+    "react": ">=18.3.1 || >=19.0.0",
+    "react-dom": ">=18.3.1 || >=19.0.0",
     "react-router": "^6.28.0",
     "react-router-dom": "^6.28.0"
   },
@@ -89,8 +89,8 @@
     "@types/json-logic-js": "^2.0.8",
     "@types/node": "^20.19.17",
     "@types/object-hash": "^3.0.6",
-    "@types/react": "^18.3.24",
-    "@types/react-dom": "^18.3.7",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
     "@types/react-measure": "^2.0.12",
     "@vitejs/plugin-react": "^4.7.0",
     "babel-plugin-react-compiler": "^19.0.0-beta-af1b7da-20250417",
@@ -111,7 +111,7 @@
     "dist",
     "src"
   ],
-  "gitHead": "7631fbfb6cde4415513e45c0557e18073ab359b8",
+  "gitHead": "40f8d9860cb2649c0a195ecebd1a92ccb37f33a6",
   "publishConfig": {
     "access": "public"
   },

package/src/components/EntityCollectionTable/internal/EntityTableCellActions.tsx

@@ -28,7 +28,7 @@ export function EntityTableCellActions({
         }
     }, []);
 
-    const iconRef = useRef<HTMLButtonElement>();
+    const iconRef = useRef<HTMLButtonElement>(undefined);
     useEffect(() => {
         if (iconRef.current && selected) {
             iconRef.current.focus({ preventScroll: true });

package/src/components/EntityCollectionTable/internal/popup_field/useDraggable.tsx

@@ -1,20 +1,20 @@
 import React, { useCallback, useEffect } from "react";
 
 interface DraggableProps {
-    containerRef: React.RefObject<HTMLDivElement>,
-    innerRef: React.RefObject<HTMLDivElement>,
+    containerRef: React.RefObject<HTMLDivElement | null>,
+    innerRef: React.RefObject<HTMLDivElement | null>,
     x?: number;
     y?: number;
     onMove: (params: { x: number, y: number }) => void,
 }
 
 export function useDraggable({
-                                 containerRef,
-                                 innerRef,
-                                 x,
-                                 y,
-                                 onMove
-                             }: DraggableProps) {
+    containerRef,
+    innerRef,
+    x,
+    y,
+    onMove
+}: DraggableProps) {
 
     let relX = 0;
     let relY = 0;
@@ -62,9 +62,9 @@ export function useDraggable({
         if (event.target.localName === "input" || !listeningRef.current)
             return;
         onMove({
-                x: event.screenX - relX,
-                y: event.screenY - relY
-            }
+            x: event.screenX - relX,
+            y: event.screenY - relY
+        }
         );
         event.stopPropagation();
     };

package/src/components/EntityCollectionView/EntityBoardCard.tsx

@@ -149,7 +149,7 @@ function EntityBoardCardInner<M extends Record<string, any> = any>({
                 {/* Content */}
                 <div className="flex-1 min-w-0">
                     {/* Title */}
-                    <div className="truncate text-sm font-medium">
+                    <div className="line-clamp-2 text-sm font-medium">
                         {titleProperty && titleValue ? (
                             <PropertyPreview
                                 propertyKey={titlePropertyKey as string}

package/src/components/EntityCollectionView/EntityCard.tsx

@@ -111,6 +111,10 @@ export function EntityCard<M extends Record<string, any> = any>({
             return;
         }
         if (onClick) {
+            analyticsController.onAnalyticsEvent?.("card_view_entity_click", {
+                path: entity.path,
+                entityId: entity.id
+            });
             onClick(entity);
         }
     };

package/src/components/EntityCollectionView/EntityCollectionBoardView.tsx

@@ -34,6 +34,7 @@ import {
     useFireCMSContext,
     useSideEntityController
 } from "../../hooks";
+import { useAnalyticsController } from "../../hooks/useAnalyticsController";
 import { SaveEntityProps } from "../../types/datasource";
 import { setIn } from "@firecms/formex";
 import { useBoardDataController } from "./useBoardDataController";
@@ -74,6 +75,7 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
     const context = useFireCMSContext();
     const dataSource = useDataSource(collection);
     const sideEntityController = useSideEntityController();
+    const analyticsController = useAnalyticsController();
     const plugins = customizationController.plugins ?? [];
 
     // State for backfill dialog
@@ -222,6 +224,10 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
     }, [plugins]);
 
     const handleColumnReorder = useCallback((newColumns: string[]) => {
+        analyticsController.onAnalyticsEvent?.("kanban_column_reorder", {
+            path: fullPath,
+            columnProperty
+        });
         setHasUserReordered(true);
         setLocalColumnsOrder(newColumns);
         plugins
@@ -235,7 +241,7 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
                     newColumnsOrder: newColumns
                 });
             });
-    }, [plugins, fullPath, parentCollectionIds, collection, columnProperty]);
+    }, [plugins, fullPath, parentCollectionIds, collection, columnProperty, analyticsController]);
 
     // Collection-level count queries to detect missing order property
     // Just TWO counts: total and ordered (for the entire collection, not per column)
@@ -393,6 +399,13 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
         const entity = items.find(item => item.id === moveInfo?.itemId)?.entity;
         if (!entity) return;
 
+        analyticsController.onAnalyticsEvent?.("kanban_card_moved", {
+            path: fullPath,
+            entityId: entity.id,
+            sourceColumn: moveInfo?.sourceColumn,
+            targetColumn: moveInfo?.targetColumn
+        });
+
         const isColumnChange = moveInfo && moveInfo.sourceColumn !== moveInfo.targetColumn;
 
         // If no orderProperty and not a column change, nothing to do
@@ -440,7 +453,7 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
         } catch (e) {
             console.error("Error saving entity:", e);
         }
-    }, [collection, columnProperty, orderProperty, context, dataSource, calculateNewOrder, boardDataController]);
+    }, [collection, columnProperty, orderProperty, context, dataSource, calculateNewOrder, boardDataController, analyticsController, fullPath]);
 
     // Backfill order values for all entities
     const handleBackfill = useCallback(async () => {
@@ -449,6 +462,9 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
             console.log("No orderProperty, returning");
             return;
         }
+        analyticsController.onAnalyticsEvent?.("kanban_backfill_order", {
+            path: fullPath
+        });
         setBackfillLoading(true);
 
         try {
@@ -514,7 +530,7 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
         } finally {
             setBackfillLoading(false);
         }
-    }, [orderProperty, fullPath, collection, dataSource, context, boardDataController]);
+    }, [orderProperty, fullPath, collection, dataSource, context, boardDataController, analyticsController]);
 
     const handleEntityClick = useCallback((entity: Entity<M>) => {
         onEntityClick?.(entity);
@@ -667,6 +683,10 @@ export function EntityCollectionBoardView<M extends Record<string, any> = any>({
                     columnLoadingState={columnLoadingState}
                     onLoadMoreColumn={(column) => boardDataController.loadMoreColumn(column)}
                     onAddItemToColumn={(column) => {
+                        analyticsController.onAnalyticsEvent?.("kanban_new_entity_in_column", {
+                            path: fullPath,
+                            column
+                        });
                         sideEntityController.open({
                             path: fullPath,
                             collection,

package/src/components/EntityCollectionView/EntityCollectionView.tsx

@@ -433,12 +433,17 @@ export const EntityCollectionView = React.memo(
 
         // View mode change: update URL + save to local persistence
         const onViewModeChange = useCallback((mode: ViewMode) => {
+            analyticsController.onAnalyticsEvent?.("view_mode_changed", {
+                path: fullPath,
+                from: viewMode,
+                to: mode
+            });
             setViewMode(mode);
             // Save to local persistence for next visit
             if (userConfigPersistence) {
                 onCollectionModifiedForUser(fullPath, { defaultViewMode: mode } as PartialEntityCollection<M>);
             }
-        }, [setViewMode, userConfigPersistence, onCollectionModifiedForUser, fullPath]);
+        }, [setViewMode, userConfigPersistence, onCollectionModifiedForUser, fullPath, analyticsController, viewMode]);
 
         const createEnabled = canCreateEntity(collection, authController, fullPath, null);
 
@@ -568,12 +573,16 @@ export const EntityCollectionView = React.memo(
 
         // Handle kanban property change
         const onKanbanPropertyChange = useCallback((property: string) => {
+            analyticsController.onAnalyticsEvent?.("kanban_property_changed", {
+                path: fullPath,
+                property
+            });
             setSelectedKanbanProperty(property);
             // Save to local persistence
             if (userConfigPersistence) {
                 onCollectionModifiedForUser(fullPath, { kanbanColumnProperty: property } as any);
             }
-        }, [userConfigPersistence, onCollectionModifiedForUser, fullPath]);
+        }, [userConfigPersistence, onCollectionModifiedForUser, fullPath, analyticsController]);
 
         const getPropertyFor = useCallback(({
             propertyKey,
@@ -836,6 +845,24 @@ export const EntityCollectionView = React.memo(
             />
         );
 
+        // Compute plugin-provided error view for collection loading errors
+        const pluginErrorView = useMemo(() => {
+            const error = tableController.dataLoadingError;
+            if (!error || !customizationController.plugins) return null;
+            for (const plugin of customizationController.plugins) {
+                if (plugin.collectionView?.CollectionError) {
+                    const CollectionError = plugin.collectionView.CollectionError;
+                    return <CollectionError
+                        path={fullPath}
+                        collection={collection}
+                        parentCollectionIds={parentCollectionIds}
+                        error={error}
+                    />;
+                }
+            }
+            return null;
+        }, [tableController.dataLoadingError, customizationController.plugins, fullPath, collection, parentCollectionIds]);
+
         return (
             <div className={cls("overflow-hidden h-full w-full rounded-md flex flex-col", className)}
                 ref={containerRef}>
@@ -872,7 +899,9 @@ export const EntityCollectionView = React.memo(
                 />
 
                 {/* View content - only the view-specific content changes */}
-                {viewMode === "kanban" && enabledViews.includes("kanban") ? (
+                {tableController.dataLoadingError && pluginErrorView
+                    ? pluginErrorView
+                    : viewMode === "kanban" && enabledViews.includes("kanban") ? (
                     <EntityCollectionBoardView
                         key={`kanban-view-${fullPath}-${selectedKanbanProperty}`}
                         collection={collection}