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

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,20 @@ 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
+     * You can also pass a React node if you want to render a custom icon.
+     * If not specified, a default icon will be used.
      */
-    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 +89,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 +102,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 +117,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 +128,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 +149,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 +168,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 +198,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 +224,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 +232,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 +256,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 +309,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 +326,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 +361,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 +398,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 +460,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 +471,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 +492,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 +527,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 +586,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 +626,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 +647,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'

package/src/types/datasource.ts

@@ -9,6 +9,7 @@ import { FireCMSContext } from "./firecms_context";
 export interface FetchEntityProps<M extends Record<string, any> = any> {
     path: string;
     entityId: string;
+    databaseId?: string;
     collection?: EntityCollection<M, any>
 }
 
@@ -63,6 +64,7 @@ export interface SaveEntityProps<M extends Record<string, any> = any> {
  */
 export interface DeleteEntityProps<M extends Record<string, any> = any> {
     entity: Entity<M>;
+    collection?: EntityCollection<M> | ResolvedEntityCollection<M>;
 }
 
 /**
@@ -137,6 +139,7 @@ export interface DataSource {
     fetchEntity<M extends Record<string, any> = any>({
                                                          path,
                                                          entityId,
+                                                         databaseId,
                                                          collection
                                                      }: FetchEntityProps<M>
     ): Promise<Entity<M> | undefined>;
@@ -181,7 +184,8 @@ export interface DataSource {
      */
     deleteEntity<M extends Record<string, any> = any>(
         {
-            entity
+            entity,
+            collection
         }: DeleteEntityProps<M>
     ): Promise<void>;
 
@@ -190,7 +194,7 @@ export interface DataSource {
      * @param path Collection path
      * @param name of the property
      * @param value
-     * @param property
+     * @param collection
      * @param entityId
      * @return `true` if there are no other fields besides the given entity
      */
@@ -198,13 +202,14 @@ export interface DataSource {
         path: string,
         name: string,
         value: any,
-        entityId?: string
+        entityId?: string,
+        collection?: EntityCollection
     ): Promise<boolean>;
 
     /**
      * Generate an id for a new entity
      */
-    generateEntityId(path: string): string;
+    generateEntityId(path: string, collection: EntityCollection): string;
 
     /**
      * Count the number of entities in a collection
@@ -238,19 +243,11 @@ export type FilterCombinationValidProps = {
     sortBy?: [string, "asc" | "desc"];
 };
 
-export type SaveEntityDelegateProps<M extends Record<string, any> = any> = Omit<SaveEntityProps<M>, "collection">;
+export type SaveEntityDelegateProps<M extends Record<string, any> = any> = SaveEntityProps<M>;
 
-export type FetchCollectionDelegateProps<M extends Record<string, any> = any> =
-    Omit<FetchCollectionProps<M>, "collection">
-    & {
-    isCollectionGroup?: boolean
-};
+export type FetchCollectionDelegateProps<M extends Record<string, any> = any> = FetchCollectionProps<M>;
 
-export type ListenCollectionDelegateProps<M extends Record<string, any> = any> =
-    ListenCollectionProps<M>
-    & {
-    isCollectionGroup?: boolean;
-};
+export type ListenCollectionDelegateProps<M extends Record<string, any> = any> = ListenCollectionProps<M>;
 
 export interface DataSourceDelegate {
 
@@ -321,7 +318,7 @@ export interface DataSourceDelegate {
     fetchEntity<M extends Record<string, any> = any>({
                                                          path,
                                                          entityId,
-                                                     }: Omit<FetchEntityProps<M>, "collection">): Promise<Entity<M> | undefined>;
+                                                     }: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
 
     /**
      * Get realtime updates on one entity.
@@ -337,7 +334,7 @@ export interface DataSourceDelegate {
                                                            entityId,
                                                            onUpdate,
                                                            onError
-                                                       }: Omit<ListenEntityProps<M>, "collection">): () => void;
+                                                       }: ListenEntityProps<M>): () => void;
 
     /**
      * Save entity to the specified path
@@ -366,14 +363,15 @@ export interface DataSourceDelegate {
      * @param name of the property
      * @param value
      * @param entityId
+     * @param collection
      * @return `true` if there are no other fields besides the given entity
      */
-    checkUniqueField(path: string, name: string, value: any, entityId?: string): Promise<boolean>;
+    checkUniqueField(path: string, name: string, value: any, entityId?: string, collection?: EntityCollection): Promise<boolean>;
 
     /**
      * Generate an id for a new entity
      */
-    generateEntityId(path: string): string;
+    generateEntityId(path: string, collection?: EntityCollection): string;
 
     /**
      * Count the number of entities in a collection
@@ -384,7 +382,9 @@ export interface DataSourceDelegate {
      * Check if the given filter combination is valid
      * @param props
      */
-    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, "collection">): boolean;
+    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, "collection"> & {
+        databaseId?: string
+    }): boolean;
 
     /**
      * Get the object to generate the current time in the datasource
@@ -400,6 +400,7 @@ export interface DataSourceDelegate {
     initTextSearch?: (props: {
         context: FireCMSContext,
         path: string,
+        databaseId?: string,
         collection: EntityCollection,
         parentCollectionIds?: string[]
     }) => Promise<boolean>;

package/src/types/dialogs_controller.tsx

@@ -15,19 +15,23 @@ export interface DialogsController {
      * Open a dialog
      * @param props
      */
-    open: (props: DialogControllerEntryProps) => { closeDialog: () => void };
+    open: <T extends object = object>(props: DialogControllerEntryProps<T>) => { closeDialog: () => void };
 }
 
 /**
  * Props used to open a side dialog
  * @group Hooks and utilities
  */
-export interface DialogControllerEntryProps {
+export interface DialogControllerEntryProps<T extends object = object> {
 
     key: string;
     /**
      * The component type that will be rendered
      */
-    Component: React.ComponentType<{ open: boolean, closeDialog: () => void }>;
+    Component: React.ComponentType<{ open: boolean, closeDialog: () => void } & T>;
+    /**
+     * Props to pass to the dialog component
+     */
+    props?: T;
 
 }

package/src/types/entities.ts

@@ -8,7 +8,7 @@ export type EntityStatus = "new" | "existing" | "copy";
  * Representation of an entity fetched from the datasource
  * @group Models
  */
-export interface Entity<M extends object> {
+export interface Entity<M extends object = any> {
 
     /**
      * ID of the entity
@@ -25,6 +25,8 @@ export interface Entity<M extends object> {
      * Current values
      */
     values: EntityValues<M>;
+
+    databaseId?: string;
 }
 
 /**
@@ -48,9 +50,15 @@ export class EntityReference {
      */
     readonly path: string;
 
-    constructor(id: string, path: string) {
+    /**
+     * Optional database ID where the entity is stored (if multiple databases are used)
+     */
+    readonly databaseId?: string;
+
+    constructor(id: string, path: string, databaseId?: string) {
         this.id = id;
         this.path = path;
+        this.databaseId = databaseId;
     }
 
     get pathWithId() {

package/src/types/entity_actions.tsx

@@ -4,17 +4,31 @@ import { Entity } from "./entities";
 import { EntityCollection, SelectionController } from "./collections";
 import { User } from "./user";
 import { SideEntityController } from "./side_entity_controller";
+import { FormContext } from "./fields";
 
 /**
  * An entity action is a custom action that can be performed on an entity.
  * They are displayed in the entity view and in the collection view.
  */
-export type EntityAction<M extends object = any, UserType extends User = User> = {
+export type EntityAction<M extends object = any, USER extends User = User> = {
     /**
      * Title of the action
      */
     name: string;
 
+    /**
+     * Key of the action. You only need to provide this if you want to
+     * override the default actions, or if you are not passing the action
+     * directly to the `entityActions` prop of a collection.
+     * You can define your actions at the app level, in which case you
+     * must provide a key.
+     * The default actions are:
+     * - edit
+     * - delete
+     * - copy
+     */
+    key?: string;
+
     /**
      * Icon of the action
      */
@@ -24,7 +38,13 @@ export type EntityAction<M extends object = any, UserType extends User = User> =
      * Callback when the action is clicked
      * @param props
      */
-    onClick: (props: EntityActionClickProps<M, UserType>) => Promise<void> | void;
+    onClick: (props: EntityActionClickProps<M, USER>) => Promise<void> | void;
+
+    /**
+     * Optional callback in case you want to disable the action
+     * @param props
+     */
+    isEnabled?: (props: EntityActionClickProps<M, USER>) => boolean;
 
     /**
      * Show this action collapsed in the menu of the collection view.
@@ -40,17 +60,60 @@ export type EntityAction<M extends object = any, UserType extends User = User> =
 
 }
 
-export type EntityActionClickProps<M extends object, UserType extends User = User> = {
-    entity: Entity<M>;
-    context: FireCMSContext<UserType>;
+export type EntityActionClickProps<M extends object, USER extends User = User> = {
+    entity?: Entity<M>;
+    context: FireCMSContext<USER>;
+
     fullPath?: string;
+    fullIdPath?: string;
     collection?: EntityCollection<M>;
+
+    /**
+     * Optional form context, present if the action is being called from a form.
+     * This allows you to access the form state and methods, including modifying the form values.
+     */
+    formContext?: FormContext;
+
+    /**
+     * Present if this actions is being called from a side dialog only
+     */
+    sideEntityController?: SideEntityController;
+
+    /**
+     * Is the action being called from the collection view or from the entity form view?
+     */
+    view: "collection" | "form";
+
+    /**
+     * If the action is rendered in the form, is it open in a side panel or full screen?
+     */
+    openEntityMode: "side_panel" | "full_screen";
+
+    /**
+     * Optional selection controller, present if the action is being called from a collection view
+     */
     selectionController?: SelectionController;
+
+    /**
+     * Optional highlight function to highlight the entity in the collection view
+     * @param entity
+     */
     highlightEntity?: (entity: Entity<any>) => void;
+
+    /**
+     * Optional unhighlight function to remove the highlight from the entity in the collection view
+     * @param entity
+     */
     unhighlightEntity?: (entity: Entity<any>) => void;
-    onCollectionChange?: () => void;
+
     /**
-     * If this actions is being called from a side dialog
+     * Optional function to navigate back (e.g. when deleting an entity or navigating from a form)
      */
-    sideEntityController?: SideEntityController;
+    navigateBack?: () => void;
+
+    /**
+     * Callback to be called when the collection changes, e.g. after an entity is deleted or created.
+     */
+    onCollectionChange?: () => void;
+
 };