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

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/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;
 };

package/src/types/plugins.tsx

@@ -7,7 +7,7 @@ import { FieldProps, FormContext } from "./fields";
 import { CMSType, Property } from "./properties";
 import { EntityStatus } from "./entities";
 import { ResolvedProperty } from "./resolved_entities";
-import { NavigationGroupMapping } from "./navigation";
+import { NavigationGroupMapping, CMSView } from "./navigation";
 import { InternalUserManagement } from "./internal_user_management";
 
 /**
@@ -28,6 +28,14 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
      */
     loading?: boolean;
 
+    /**
+     * Override any FireCMS UI string, or provide translations for additional
+     * locales, specific for this plugin.
+     * Keys can be existing `FireCMSTranslations` keys, or new keys if using
+     * module augmentation.
+     */
+    i18n?: Record<string, Record<string, string>>;
+
     /**
      * You can use this prop to add higher order components to the CMS.
      * The components will be added to the root of the CMS, so any component
@@ -46,6 +54,12 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
 
     userManagement?: InternalUserManagement
 
+    /**
+     * Views to be automatically added to the navigation.
+     * These views will be merged with the views provided to useBuildNavigationController.
+     */
+    views?: CMSView[];
+
     homePage?: {
 
         /**
@@ -106,6 +120,19 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
 
     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.
@@ -161,6 +188,50 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
             collection: EC;
             tableController: EntityTableController;
         }>;
+
+        /**
+         * Callback called when columns are reordered via drag and drop.
+         * Used by plugins to persist the new column order.
+         */
+        onColumnsReorder?: (props: {
+            fullPath: string;
+            parentCollectionIds: string[];
+            collection: EC;
+            newPropertiesOrder: string[];
+        }) => void;
+
+        /**
+         * Callback called when Kanban board columns are reordered via drag and drop.
+         * Used by plugins to persist the new Kanban column order.
+         */
+        onKanbanColumnsReorder?: (props: {
+            fullPath: string;
+            parentCollectionIds: string[];
+            collection: EC;
+            kanbanColumnProperty: string;
+            newColumnsOrder: string[];
+        }) => void;
+
+        /**
+         * Component to render when Kanban view is missing configuration.
+         * Used to provide a CTA to open the collection editor to configure Kanban.
+         */
+        KanbanSetupComponent?: React.ComponentType<{
+            collection: EC;
+            fullPath: string;
+            parentCollectionIds: string[];
+        }>;
+
+        /**
+         * Component to render an "Add Column" button at the end of the Kanban board.
+         * Used to allow adding new enum values to the column property.
+         */
+        AddKanbanColumnComponent?: React.ComponentType<{
+            collection: EC;
+            fullPath: string;
+            parentCollectionIds: string[];
+            columnProperty: string;
+        }>;
     }
 
     form?: {
@@ -179,6 +250,11 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
          */
         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;