@firecms/core 3.0.0-alpha.27 → 3.0.0-alpha.29

package/src/types/datasource.ts

@@ -1,6 +1,6 @@
-import { Entity, EntityStatus, EntityValues } from "./entities";
+import { Entity, EntityReference, EntityStatus, EntityValues, GeoPoint } from "./entities";
 import { EntityCollection, FilterValues } from "./collections";
-import { ResolvedEntityCollection, ResolvedProperty } from "./resolved_entities";
+import { ResolvedEntityCollection } from "./resolved_entities";
 
 /**
  * @category Datasource
@@ -198,7 +198,6 @@ export interface DataSource {
         path: string,
         name: string,
         value: any,
-        property: ResolvedProperty,
         entityId?: string
     ): Promise<boolean>;
 
@@ -214,12 +213,177 @@ export interface DataSource {
 
     /**
      * Check if the given filter combination is valid
-     * @param params
+     * @param props
      */
-    isFilterCombinationValid?(params: {
-        path: string,
-        collection: EntityCollection<any>,
-        filterValues: FilterValues<any>,
-        sortBy?: [string, "asc" | "desc"]
-    }): boolean;
+    isFilterCombinationValid?(props: FilterCombinationValidProps): boolean;
+}
+
+export type FilterCombinationValidProps = {
+    path: string;
+    collection: EntityCollection<any>;
+    filterValues: FilterValues<any>;
+    sortBy?: [string, "asc" | "desc"];
+};
+
+export type SaveEntityDelegateProps<M extends Record<string, any> = any> = Omit<SaveEntityProps<M>, "collection">;
+
+export type FetchCollectionDelegateProps<M extends Record<string, any> = any> =
+    Omit<FetchCollectionProps<M>, "collection">
+    & {
+    isCollectionGroup?: boolean
+};
+
+export type ListenCollectionDelegateProps<M extends Record<string, any> = any> =
+    Omit<ListenCollectionProps<M>, "collection">
+    & {
+    isCollectionGroup?: boolean
+};
+
+export interface DataSourceDelegate {
+    /**
+     * Fetch data from a collection
+     * @param path
+     * @param filter
+     * @param limit
+     * @param startAfter
+     * @param orderBy
+     * @param order
+     * @param searchString
+     * @return Function to cancel subscription
+     * @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>[]>;
+
+    /**
+     * Listen to a collection in a given path. If you don't implement this method
+     * `fetchCollection` will be used instead, with no real time updates.
+     * @param path
+     * @param onUpdate
+     * @param onError
+     * @param filter
+     * @param limit
+     * @param startAfter
+     * @param orderBy
+     * @param order
+     * @param searchString
+     * @return Function to cancel subscription
+     * @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;
+
+    /**
+     * Retrieve an entity given a path and a collection
+     * @param path
+     * @param entityId
+     */
+    fetchEntity<M extends Record<string, any> = any>({
+                                                         path,
+                                                         entityId,
+                                                     }: Omit<FetchEntityProps<M>, "collection">): Promise<Entity<M> | undefined>;
+
+    /**
+     * Get realtime updates on one entity.
+     * @param path
+     * @param entityId
+     * @param collection
+     * @param onUpdate
+     * @param onError
+     * @return Function to cancel subscription
+     */
+    listenEntity?<M extends Record<string, any> = any>({
+                                                           path,
+                                                           entityId,
+                                                           onUpdate,
+                                                           onError
+                                                       }: Omit<ListenEntityProps<M>, "collection">): () => void;
+
+    /**
+     * Save entity to the specified path
+     * @param path
+     * @param id
+     * @param collection
+     * @param status
+     */
+    saveEntity<M extends Record<string, any> = any>({
+                                                        path,
+                                                        entityId,
+                                                        values,
+                                                        status
+                                                    }: SaveEntityDelegateProps<M>): Promise<Entity<M>>;
+
+    /**
+     * Delete an entity
+     * @param entity
+     * @return was the whole deletion flow successful
+     */
+    deleteEntity<M extends Record<string, any> = any>({ entity }: DeleteEntityProps<M>): Promise<void>;
+
+    /**
+     * Check if the given property is unique in the given collection
+     * @param path Collection path
+     * @param name of the property
+     * @param value
+     * @param entityId
+     * @return `true` if there are no other fields besides the given entity
+     */
+    checkUniqueField(path: string, name: string, value: any, entityId?: string): Promise<boolean>;
+
+    /**
+     * Generate an id for a new entity
+     */
+    generateEntityId(path: string): string;
+
+    /**
+     * Count the number of entities in a collection
+     */
+    countEntities<M extends Record<string, any> = any>(props: FetchCollectionDelegateProps<M>): Promise<number>;
+
+    /**
+     * Check if the given filter combination is valid
+     * @param props
+     */
+    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, "collection">): boolean;
+
+    /**
+     * Convert a FireCMS reference to a reference that can be used by the datasource
+     * @param reference
+     */
+    buildReference: (reference: EntityReference) => any,
+
+    /**
+     * Convert a FireCMS GeoPoint to a GeoPoint that can be used by the datasource
+     * @param geoPoint
+     */
+    buildGeoPoint: (geoPoint: GeoPoint) => any,
+
+    /**
+     * Get the object to generate the current time in the datasource
+     */
+    currentTime(): any;
+
+    buildDate: (date: Date) => any;
+
+    buildDeleteFieldValue: () => any;
+
+    delegateToCMSModel: (data: any) => any;
+
+    setDateToMidnight: (input?: any) => any;
 }

package/src/types/dialogs_controller.tsx

@@ -0,0 +1,31 @@
+/**
+ * Controller to open the side dialog
+ * @category Hooks and utilities
+ */
+export interface DialogsController {
+
+    /**
+     * Close the last dialog
+     */
+    close: () => void;
+
+    /**
+     * Open a dialog
+     * @param props
+     */
+    open: (props: DialogControllerEntryProps) => { closeDialog: () => void };
+}
+
+/**
+ * Props used to open a side dialog
+ * @category Hooks and utilities
+ */
+export interface DialogControllerEntryProps {
+
+    key: string;
+    /**
+     * The component type that will be rendered
+     */
+    Component: React.ComponentType<{ open: boolean }>;
+
+}

package/src/types/entity_actions.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+import { FireCMSContext } from "./firecms_context";
+import { Entity } from "./entities";
+import { EntityCollection, SelectionController } from "./collections";
+import { User } from "./user";
+import { SideEntityController } from "./side_entity_controller";
+
+export type EntityAction<M extends object = any, UserType extends User = User> = {
+    name: string;
+    icon?: React.ReactElement;
+    onClick: (props: EntityActionClickProps<M, UserType>) => Promise<void>;
+    /**
+     * Show this action in the menu, defaults to true
+     */
+    collapsed?: boolean;
+
+    /**
+     * Show this action in the form, defaults to true
+     */
+    includeInForm?: boolean;
+}
+
+export type EntityActionClickProps<M extends object, UserType extends User = User> = {
+    entity: Entity<M>;
+    context: FireCMSContext<UserType>;
+    fullPath?: string;
+    collection?: EntityCollection<M>;
+    selectionController?: SelectionController;
+    highlightEntity?: (entity: Entity<any>) => void;
+    unhighlightEntity?: (entity: Entity<any>) => void;
+    onCollectionChange?: () => void;
+    /**
+     * If this actions is being called from a side dialog
+     */
+    sideEntityController?: SideEntityController;
+};

package/src/types/fields.tsx

@@ -8,7 +8,7 @@ import { ResolvedEntityCollection, ResolvedProperty } from "./resolved_entities"
  *
  * @category Form custom fields
  */
-export interface FieldProps<T extends CMSType = CMSType, CustomProps = any, M extends Record<string, any> = any> {
+export interface FieldProps<T extends CMSType = any, CustomProps = any, M extends Record<string, any> = any> {
 
     /**
      * Key of the property

package/src/types/firecms.tsx

@@ -5,7 +5,7 @@ import { DataSource } from "./datasource";
 import { EntityCollection, EntityCustomView } from "./collections";
 import { CMSView } from "./navigation";
 import { FireCMSContext } from "./firecms_context";
-import { FieldConfig } from "./field_config";
+import { PropertyConfig } from "./property_config";
 import { Locale } from "./locales";
 import { StorageSource } from "./storage";
 import { EntityLinkBuilder } from "./entity_link_builder";
@@ -23,11 +23,11 @@ import { CMSAnalyticsEvent } from "./analytics";
  * APIs directly, or a REST API.
  * @category Models
  */
-export type EntityCollectionsBuilder = (params: {
+export type EntityCollectionsBuilder<EC extends EntityCollection> = (params: {
     user: User | null,
     authController: AuthController,
     dataSource: DataSource
-}) => EntityCollection[] | Promise<EntityCollection[]>;
+}) => EC[] | Promise<EC[]>;
 
 /**
  * Use this callback to build custom views dynamically.
@@ -47,7 +47,7 @@ export type CMSViewsBuilder = (params: {
 /**
  * @category Models
  */
-export type FireCMSProps<UserType extends User> = {
+export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
 
     /**
      * Use this function to return the components you want to render under
@@ -73,7 +73,7 @@ export type FireCMSProps<UserType extends User> = {
      * Each of the navigation entries in this field
      * generates an entry in the main menu.
      */
-    collections?: EntityCollection[] | EntityCollectionsBuilder;
+    collections?: EC[] | EntityCollectionsBuilder<EC>;
 
     /**
      * Custom additional views created by the developer, added to the main
@@ -84,9 +84,9 @@ export type FireCMSProps<UserType extends User> = {
     /**
      * Record of custom form fields to be used in the CMS.
      * You can use the key to reference the custom field in
-     * the `fieldConfig` prop of a property in a collection.
+     * the `propertyConfig` prop of a property in a collection.
      */
-    fields?: Record<string, FieldConfig>;
+    fields?: Record<string, PropertyConfig>;
 
     /**
      * List of additional custom views for entities.
@@ -148,7 +148,7 @@ export type FireCMSProps<UserType extends User> = {
      * Use plugins to modify the behaviour of the CMS.
      * Currently, in ALPHA, and likely subject to change.
      */
-    plugins?: FireCMSPlugin[];
+    plugins?: FireCMSPlugin<any, any, any>[];
 
     /**
      * Callback used to get analytics events from the CMS

package/src/types/firecms_context.tsx

@@ -11,8 +11,9 @@ import { UserConfigurationPersistence } from "./local_config_persistence";
 import { SideDialogsController } from "./side_dialogs_controller";
 import { FireCMSPlugin } from "./plugins";
 import { CMSAnalyticsEvent } from "./analytics";
-import { FieldConfig } from "./field_config";
+import { PropertyConfig } from "./property_config";
 import { EntityCustomView } from "./collections";
+import { DialogsController } from "./dialogs_controller";
 
 /**
  * Context that includes the internal controllers and contexts used by the app.
@@ -59,9 +60,16 @@ export type FireCMSContext<UserType extends User = User, AuthControllerType exte
 
     /**
      * Controller used to open side dialogs
+     * This is the controller used internally by side entity dialogs
+     * or reference dialogs.
      */
     sideDialogsController: SideDialogsController;
 
+    /**
+     * Controller used to open regular dialogs
+     */
+    dialogsController: DialogsController;
+
     /**
      * Used auth controller
      */
@@ -96,9 +104,9 @@ export type FireCMSContext<UserType extends User = User, AuthControllerType exte
     /**
      * Record of custom form fields to be used in the CMS.
      * You can use the key to reference the custom field in
-     * the `fieldConfig` prop of a property in a collection.
+     * the `propertyConfig` prop of a property in a collection.
      */
-    fields: Record<string, FieldConfig>;
+    fields: Record<string, PropertyConfig>;
 
     /**
      * List of additional custom views for entities.

package/src/types/index.ts

@@ -1,5 +1,6 @@
 export * from "./auth";
 export * from "./entities";
+export * from "./entity_actions";
 export * from "./resolved_entities";
 export * from "./properties";
 export * from "./collections";
@@ -10,7 +11,7 @@ export * from "./user";
 export * from "./colors";
 export * from "./storage";
 export * from "./fields";
-export * from "./field_config";
+export * from "./property_config";
 export * from "./datasource";
 export * from "./entity_link_builder";
 export * from "./side_entity_controller";

package/src/types/navigation.ts

@@ -154,9 +154,9 @@ export interface CMSView {
 
     /**
      * Icon key to use in this view.
-     * You can use any of the icons in the MUI specs:
-     * https://mui.com/material-ui/material-icons/
-     * e.g. 'AccountTree' or 'Person'
+     * You can use any of the icons in the Material specs:
+     * https://fonts.google.com/icons
+     * e.g. 'account_tree' or 'person'
      */
     icon?: string;
 

package/src/types/plugins.tsx

@@ -13,7 +13,7 @@ import { ResolvedProperty } from "./resolved_entities";
  * NOTE: This is a work in progress and the API is not stable yet.
  * @category Core
  */
-export type FireCMSPlugin<PROPS = any, FORM_PROPS = any> = {
+export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollection = EntityCollection> = {
 
     /**
      * Name of the plugin
@@ -41,19 +41,19 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any> = {
          * Use this component to add custom actions to the entity collections
          * toolbar.
          */
-        CollectionActions?: React.ComponentType<CollectionActionsProps> | React.ComponentType<CollectionActionsProps>[];
+        CollectionActions?: React.ComponentType<CollectionActionsProps<any, any, EC>> | React.ComponentType<CollectionActionsProps<any, any, EC>>[];
 
     }
 
     form?: {
         provider?: {
-            Component: React.ComponentType<PropsWithChildren<FORM_PROPS & PluginFormActionProps<any>>>;
+            Component: React.ComponentType<PropsWithChildren<FORM_PROPS & PluginFormActionProps<any, EC>>>;
             props?: FORM_PROPS;
         }
 
-        Actions?: React.ComponentType<PluginFormActionProps>;
+        Actions?: React.ComponentType<PluginFormActionProps<any, EC>>;
 
-        fieldBuilder?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T>) => React.ComponentType<FieldProps<T>> | null;
+        fieldBuilder?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T, any, EC>) => React.ComponentType<FieldProps<T>> | null;
 
         fieldBuilderEnabled?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T>) => boolean;
     }
@@ -115,6 +115,7 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any> = {
             fullPath: string,
             parentPathSegments: string[],
             onHover: boolean,
+            collection: EC;
         }>;
 
         /**
@@ -124,7 +125,7 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any> = {
         AddColumnComponent?: React.ComponentType<{
             fullPath: string,
             parentPathSegments: string[],
-            collection: EntityCollection;
+            collection: EC;
         }>;
     }
 
@@ -157,24 +158,24 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
 
 }
 
-export interface PluginFormActionProps<UserType extends User = User> {
+export interface PluginFormActionProps<UserType extends User = User, EC extends EntityCollection = EntityCollection> {
     entityId?: string;
     path: string;
     status: EntityStatus;
-    collection: EntityCollection;
+    collection: EC;
     formContext?: FormContext<any>;
     context: FireCMSContext<UserType>;
     currentEntityId?: string;
 }
 
-export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Record<string, any> = any> = {
+export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Record<string, any> = any, EC extends EntityCollection<M> = EntityCollection<M>> = {
     fieldConfigId: string;
     propertyKey: string;
     property: Property<T> | ResolvedProperty<T>;
     Field: React.ComponentType<FieldProps<T, any, M>>;
     plugin: FireCMSPlugin;
     path: string;
-    collection: EntityCollection<M>;
+    collection: EC;
 };
 
 export interface PluginGenericProps<UserType extends User = User> {

package/src/types/properties.ts

@@ -85,7 +85,7 @@ export interface BaseProperty<T extends CMSType, CustomProps = any> {
      * All the configuration will be taken from the inherited config, and
      * overwritten by the current property config.
      */
-    fieldConfig?: string;
+    propertyConfig?: string;
 
     /**
      * Longer description of a field, displayed under a popover

package/src/types/{field_config.tsx → property_config.tsx}

@@ -2,15 +2,14 @@ import React from "react";
 import { CMSType, PropertyOrBuilder } from "./properties";
 
 /**
- * This is the configuration object for the field component generated for a
- * property.
+ * This is the configuration object for a property.
  * These configs are generated by default for the properties defined in your
  * collections' configuration, but you can define your own to be used.
  */
-export type FieldConfig<T extends CMSType = any> = {
+export type PropertyConfig<T extends CMSType = any> = {
 
     /**
-     * Key used to identify this field type.
+     * Key used to identify this property config.
      */
     key: string,