@firecms/core 3.1.0-canary.1df3b2c → 3.1.0-canary.8958c1b

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/collections.d.ts

@@ -326,6 +326,14 @@ export interface EntityCollection<M extends Record<string, any> = any, USER exte
      * 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.

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.1df3b2c",
+  "version": "3.1.0-canary.8958c1b",
   "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.1df3b2c",
-    "@firecms/formex": "^3.1.0-canary.1df3b2c",
-    "@firecms/ui": "^3.1.0-canary.1df3b2c",
+    "@firecms/editor": "^3.1.0-canary.8958c1b",
+    "@firecms/formex": "^3.1.0-canary.8958c1b",
+    "@firecms/ui": "^3.1.0-canary.8958c1b",
     "@radix-ui/react-portal": "^1.1.10",
     "clsx": "^2.1.1",
     "compressorjs": "^1.2.1",
@@ -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.1.0",
+    "@types/react-dom": "^19.1.0",
     "@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": "5074584b15be0d0507a4dadc148f03d82e9fe495",
+  "gitHead": "c415ea47be324c74539718a2c108ea89fa78e3a1",
   "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);
 
@@ -501,18 +506,24 @@ export const EntityCollectionView = React.memo(
             authController,
         }), [collection, fullPath]);
 
-        // Check if Kanban view is available (needs kanban.columnProperty with enumValues)
-        const kanbanEnabled = useMemo(() => {
-            if (!collection.kanban?.columnProperty) return false;
-            const property = getPropertyInPath(resolvedCollection.properties, collection.kanban.columnProperty);
-            if (!property || !("dataType" in property) || property.dataType !== "string") return false;
-            return Boolean(property.enumValues);
-        }, [collection.kanban?.columnProperty, resolvedCollection.properties]);
+        // Check if Kanban view is possible (collection has at least one string enum property)
+        const hasEnumProperty = useMemo(() => {
+            const properties = resolvedCollection.properties;
+            return Object.values(properties).some((prop: any) =>
+                prop && prop.dataType === "string" && prop.enumValues
+            );
+        }, [resolvedCollection.properties]);
 
-        // Check if a plugin can configure Kanban (has KanbanSetupComponent)
-        const hasKanbanConfigPlugin = useMemo(() => {
-            return customizationController.plugins?.some(plugin => plugin.collectionView?.KanbanSetupComponent) ?? false;
-        }, [customizationController.plugins]);
+        // Compute the effective enabled views:
+        // - Start from collection.enabledViews (defaults to all three)
+        // - Filter out kanban if no enum properties exist
+        const enabledViews: ViewMode[] = useMemo(() => {
+            const configured = collection.enabledViews ?? ["table", "cards", "kanban"];
+            if (!hasEnumProperty) {
+                return configured.filter(v => v !== "kanban");
+            }
+            return configured;
+        }, [collection.enabledViews, hasEnumProperty]);
 
         // Compute available enum properties for kanban column selection
         const kanbanPropertyOptions: KanbanPropertyOption[] = useMemo(() => {
@@ -562,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,
@@ -819,8 +834,7 @@ export const EntityCollectionView = React.memo(
             <ViewModeToggle
                 viewMode={viewMode}
                 onViewModeChange={onViewModeChange}
-                kanbanEnabled={kanbanEnabled}
-                hasKanbanConfigPlugin={hasKanbanConfigPlugin}
+                enabledViews={enabledViews}
                 size={viewMode === "table" ? tableSize : viewMode === "cards" ? cardSize : undefined}
                 onSizeChanged={viewMode === "table" ? onTableSizeChanged : viewMode === "cards" ? setCardSize : undefined}
                 open={viewModePopoverOpen}
@@ -831,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}>
@@ -867,7 +899,9 @@ export const EntityCollectionView = React.memo(
                 />
 
                 {/* View content - only the view-specific content changes */}
-                {viewMode === "kanban" && (kanbanEnabled || hasKanbanConfigPlugin) ? (
+                {tableController.dataLoadingError && pluginErrorView
+                    ? pluginErrorView
+                    : viewMode === "kanban" && enabledViews.includes("kanban") ? (
                     <EntityCollectionBoardView
                         key={`kanban-view-${fullPath}-${selectedKanbanProperty}`}
                         collection={collection}

package/src/components/EntityCollectionView/ViewModeToggle.tsx

@@ -22,16 +22,11 @@ export type ViewModeToggleProps = {
     viewMode?: ViewMode;
     onViewModeChange?: (mode: ViewMode) => void;
     /**
-     * Whether Kanban view mode is available for this collection.
-     * Should be true when collection.kanban is set with a valid enum property.
+     * Which view modes are enabled for this collection.
+     * Only these modes will appear in the toggle.
+     * Defaults to all three: ["table", "cards", "kanban"].
      */
-    kanbanEnabled?: boolean;
-    /**
-     * Whether a plugin exists that can configure Kanban (e.g., collection editor).
-     * When true, Kanban option is always shown (enabled or not based on kanbanEnabled).
-     * When false, Kanban option is shown but disabled.
-     */
-    hasKanbanConfigPlugin?: boolean;
+    enabledViews?: ViewMode[];
     /**
      * Current size for card/table views
      */
@@ -62,11 +57,12 @@ export type ViewModeToggleProps = {
     onKanbanPropertyChange?: (property: string) => void;
 }
 
+const ALL_VIEW_MODES: ViewMode[] = ["table", "cards", "kanban"];
+
 export function ViewModeToggle({
     viewMode = "table",
     onViewModeChange,
-    kanbanEnabled = false,
-    hasKanbanConfigPlugin = false,
+    enabledViews = ALL_VIEW_MODES,
     size,
     onSizeChanged,
     open,
@@ -93,16 +89,15 @@ export function ViewModeToggle({
         return "List";
     };
 
-    const showKanban = kanbanEnabled || hasKanbanConfigPlugin;
     const showSizeSelector = size && onSizeChanged && (viewMode === "table" || viewMode === "cards");
     const showKanbanPropertySelector = viewMode === "kanban" &&
         kanbanPropertyOptions &&
         kanbanPropertyOptions.length > 0 &&
         onKanbanPropertyChange;
 
-    // Build toggle options dynamically based on kanban availability
+    // Build toggle options based on enabledViews
     const viewModeOptions: ToggleButtonOption<ViewMode>[] = useMemo(() => {
-        const options: ToggleButtonOption<ViewMode>[] = [
+        const allOptions: ToggleButtonOption<ViewMode>[] = [
             {
                 value: "table",
                 label: "List",
@@ -112,20 +107,21 @@ export function ViewModeToggle({
                 value: "cards",
                 label: "Cards",
                 icon: <AppsIcon size="small" />
+            },
+            {
+                value: "kanban",
+                label: "Board",
+                icon: <ViewKanbanIcon size="small" />
             }
         ];
 
-        if (showKanban) {
-            options.push({
-                value: "kanban",
-                label: "Board",
-                icon: <ViewKanbanIcon size="small" />,
-                disabled: !kanbanEnabled && !hasKanbanConfigPlugin
-            });
-        }
+        return allOptions.filter(option => enabledViews.includes(option.value));
+    }, [enabledViews]);
 
-        return options;
-    }, [showKanban, kanbanEnabled, hasKanbanConfigPlugin]);
+    // Don't render if only one view is enabled
+    if (viewModeOptions.length <= 1 && !showSizeSelector) {
+        return null;
+    }
 
     return (
         <Popover
@@ -141,11 +137,13 @@ export function ViewModeToggle({
         >
             <div className="p-3 flex flex-col gap-3 min-w-[240px]">
                 {/* View mode toggle using ToggleButtonGroup */}
-                <ToggleButtonGroup
-                    value={viewMode}
-                    onValueChange={onViewModeChange}
-                    options={viewModeOptions}
-                />
+                {viewModeOptions.length > 1 && (
+                    <ToggleButtonGroup
+                        value={viewMode}
+                        onValueChange={onViewModeChange}
+                        options={viewModeOptions}
+                    />
+                )}
 
                 {/* Size selector */}
                 {showSizeSelector && (
@@ -199,4 +197,3 @@ export function ViewModeToggle({
         </Popover>
     );
 }
-