@firecms/core 3.0.0-canary.2 → 3.0.0-canary.200

package/src/routes/HomePageRoute.tsx

@@ -0,0 +1,17 @@
+import { useBreadcrumbsController } from "../hooks/useBreadcrumbsController";
+import { useEffect } from "react";
+
+export function HomePageRoute({ children }: {
+    children: React.ReactNode;
+}) {
+
+    const breadcrumbs = useBreadcrumbsController();
+
+    useEffect(() => {
+        breadcrumbs.set({
+            breadcrumbs: []
+        });
+    }, []);
+
+    return children;
+}

package/src/types/analytics.ts

@@ -26,6 +26,7 @@ export type CMSAnalyticsEvent =
     | "home_navigate_to_collection"
     | "home_favorite_navigate_to_collection"
     | "home_navigate_to_view"
+    | "home_navigate_to_admin_view"
     | "home_favorite_navigate_to_view"
 
     | "collection_inline_editing"

package/src/types/auth.tsx

@@ -1,4 +1,7 @@
 import { User } from "./user";
+import { Role } from "./roles";
+import { DataSourceDelegate } from "./datasource";
+import { StorageSource } from "./storage";
 
 /**
  * Controller for retrieving the logged user or performing auth related operations.
@@ -6,13 +9,13 @@ import { User } from "./user";
  * to do it as the result of a hook.
  * @group Hooks and utilities
  */
-export type AuthController<UserType extends User = User> = {
+export type AuthController<USER extends User = any, ExtraData = any> = {
 
     /**
      * The user currently logged in
      * The values can be: the user object, null if they skipped login
      */
-    user: UserType | null;
+    user: USER | null;
 
     /**
      * Initial loading flag. It is used not to display the login screen
@@ -21,10 +24,16 @@ export type AuthController<UserType extends User = User> = {
      */
     initialLoading?: boolean;
 
+    /**
+     * Loading flag. It is used to display a loading screen when the user is
+     * logging in or out.
+     */
+    authLoading: boolean;
+
     /**
      * Sign out
      */
-    signOut: () => void;
+    signOut: () => Promise<void>;
 
     /**
      * Error initializing the authentication
@@ -46,4 +55,40 @@ export type AuthController<UserType extends User = User> = {
      */
     loginSkipped: boolean;
 
+    extra: ExtraData;
+
+    setExtra: (extra: ExtraData) => void;
+
+    setUser?: (user: USER | null) => void;
+
+    setUserRoles?: (roles: Role[]) => void;
+
 };
+
+/**
+ * Implement this function to allow access to specific users.
+ * @group Hooks and utilities
+ */
+export type Authenticator<USER extends User = User> = (props: {
+
+    /**
+     * Logged-in user or null
+     */
+    user: USER | null;
+
+    /**
+     * AuthController
+     */
+    authController: AuthController<USER>;
+
+    /**
+     * Connector to your database, e.g. your Firestore database
+     */
+    dataSourceDelegate: DataSourceDelegate;
+
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+
+}) => boolean | Promise<boolean>;

package/src/types/collections.ts

@@ -8,6 +8,7 @@ import { EnumValues, PropertiesOrBuilders } from "./properties";
 import { FormContext } from "./fields";
 import { EntityAction } from "./entity_actions";
 import { ExportConfig } from "./export_import";
+import { EntityOverrides } from "./entity_overrides";
 
 /**
  * This interface represents a view that includes a collection of entities.
@@ -16,7 +17,7 @@ import { ExportConfig } from "./export_import";
  *
  * @group Models
  */
-export interface EntityCollection<M extends Record<string, any> = any, UserType extends User = User> {
+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`.
@@ -50,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.
@@ -60,7 +67,8 @@ 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
      */
     icon?: string;
 
@@ -77,11 +85,22 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
     properties: PropertiesOrBuilders<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.
+     * Default preview properties displayed when this collection is referenced to.
      */
-    editable?: boolean;
+    previewProperties?: string[];
+
+    /**
+     * Title property of the entity. This is the property that will be used
+     * as the title in entity related views and references.
+     * If not specified, the first property simple text property will be used.
+     */
+    titleProperty?: keyof M;
+
+    /**
+     * 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`.
+     */
+    openEntityMode?: "side_panel" | "full_screen";
 
     /**
      * Order in which the properties are displayed.
@@ -99,8 +118,12 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      *       `subcollection:`. e.g. `subcollection:orders`.
      *     - If you are using a collection group, you will also have an
      *       additional `collectionGroupParent` column.
+     * You can use this prop to hide some properties from the table view.
+     * Note that if you set this prop, other ways to hide fields, like
+     * `hidden` in the property definition,will be ignored.
+     * `propertiesOrder` has precedence over `hidden`.
      */
-    propertiesOrder?: Extract<keyof M, string>[];
+    propertiesOrder?: (Extract<keyof M, string> | string | `subcollection:${string}` | "collectionGroupParent")[];
 
     /**
      * If enabled, content is loaded in batches. If `false` all entities in the
@@ -120,7 +143,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`
@@ -139,7 +162,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>;
+    callbacks?: EntityCallbacks<M, USER>;
 
     /**
      * Builder for rendering additional components such as buttons in the
@@ -170,7 +193,7 @@ export interface EntityCollection<M extends Record<string, any> = any, UserType
      * }
      * ```
      */
-    entityActions?: EntityAction<M, UserType>[];
+    entityActions?: EntityAction<M, USER>[];
 
     /**
      * Pass your own selection controller if you want to control selected
@@ -222,7 +245,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
@@ -275,7 +298,31 @@ 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
+     * are writing custom code
+     */
+    ownerId?: string;
+
+    /**
+     * Overrides for the entity view, like the data source or the storage source.
+     */
+    overrides?: EntityOverrides;
+
+    /**
+     * 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;
 }
 
 /**
@@ -285,7 +332,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`
@@ -322,7 +369,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
@@ -334,19 +381,18 @@ export interface CollectionActionsProps<M extends Record<string, any> = any, Use
 /**
  * Use this controller to retrieve the selected entities or modify them in
  * an {@link EntityCollection}
- * If you want to pass a `SelectionController` to
  * @group Models
  */
 export type SelectionController<M extends Record<string, any> = any> = {
     selectedEntities: Entity<M>[];
     setSelectedEntities: Dispatch<SetStateAction<Entity<M>[]>>;
     isEntitySelected: (entity: Entity<M>) => boolean;
-    toggleEntitySelection: (entity: Entity<M>) => void;
+    toggleEntitySelection: (entity: Entity<M>, newSelectedState?: boolean) => void;
 }
 
 /**
  * Filter conditions in a `Query.where()` clause are specified using the
- * strings '<', '<=', '==', '>=', '>', 'array-contains', 'in', and 'array-contains-any'.
+ * strings `<`, `<=`, `==`, `>=`, `>`, `array-contains`, `in`, and `array-contains-any`.
  * @group Models
  */
 export type WhereFilterOp =
@@ -385,9 +431,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>
 };
 
 /**
@@ -396,7 +442,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
@@ -417,7 +463,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,
@@ -436,7 +482,10 @@ export interface AdditionalFieldDelegate<M extends Record<string, any> = any,
      * view.
      * @param entity
      */
-    value?: (props: { entity: Entity<M>, context: FireCMSContext }) => string | number | Promise<string | number> | undefined;
+    value?: (props: {
+        entity: Entity<M>,
+        context: FireCMSContext<any>
+    }) => string | number | Promise<string | number> | undefined;
 }
 
 /**
@@ -446,10 +495,29 @@ export interface AdditionalFieldDelegate<M extends Record<string, any> = any,
  */
 export type EntityCustomView<M extends Record<string, any> = any> =
     {
-        key: string,
-        name: string,
+        /**
+         * Key of this custom view.
+         */
+        key: string;
+
+        /**
+         * Name of this custom view.
+         */
+        name: string;
+
+        /**
+         * 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>>;
-    }
+    };
 
 /**
  * Parameters passed to the builder in charge of rendering a custom panel for
@@ -508,12 +576,18 @@ export type EntityTableController<M extends Record<string, any> = any> = {
     filterValues?: FilterValues<Extract<keyof M, string>>;
     setFilterValues?: (filterValues: FilterValues<Extract<keyof M, string>>) => void;
     sortBy?: [Extract<keyof M, string>, "asc" | "desc"];
-    setSortBy?: (sortBy: [Extract<keyof M, string>, "asc" | "desc"]) => void;
+    setSortBy?: (sortBy?: [Extract<keyof M, string>, "asc" | "desc"]) => void;
     searchString?: string;
     setSearchString?: (searchString?: string) => void;
     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>,
@@ -529,5 +603,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

@@ -24,7 +24,6 @@ export type CustomizationController = {
      *
      * You can also define an entity view from the UI.
      */
-
     entityViews?: EntityCustomView[];
 
     /**

package/src/types/datasource.ts

@@ -1,6 +1,7 @@
-import { Entity, EntityReference, EntityStatus, EntityValues, GeoPoint } from "./entities";
+import { Entity, EntityStatus, EntityValues } from "./entities";
 import { EntityCollection, FilterValues } from "./collections";
 import { ResolvedEntityCollection } from "./resolved_entities";
+import { FireCMSContext } from "./firecms_context";
 
 /**
  * @group Datasource
@@ -8,7 +9,8 @@ import { ResolvedEntityCollection } from "./resolved_entities";
 export interface FetchEntityProps<M extends Record<string, any> = any> {
     path: string;
     entityId: string;
-    collection?: EntityCollection<M>
+    databaseId?: string;
+    collection?: EntityCollection<M, any>
 }
 
 /**
@@ -62,12 +64,12 @@ 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>;
 }
 
 /**
- * Implement this interface and pass it to a {@link FireCMS}
- * to connect it to your data source.
- * A Firestore implementation of this interface can be found in {@link useFirestoreDataSource}
+ * Component in charge of communicating with the data source.
+ * Usually you won't need to implement this interface, but a {@link DataSourceDelegate} instead.
  * @group Datasource
  */
 export interface DataSource {
@@ -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
@@ -216,6 +221,19 @@ export interface DataSource {
      * @param props
      */
     isFilterCombinationValid?(props: FilterCombinationValidProps): boolean;
+
+    /**
+     * Called when the user clicks on the search bar in a collection view.
+     * Useful for initializing a text search index.
+     * @param props
+     */
+    initTextSearch?: (props: {
+        context: FireCMSContext,
+        path: string,
+        collection: EntityCollection,
+        parentCollectionIds?: string[]
+    }) => Promise<boolean>;
+
 }
 
 export type FilterCombinationValidProps = {
@@ -225,21 +243,24 @@ 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 {
+
+    /**
+     * Key that identifies this data source delegate
+     */
+    key: string;
+
+    /**
+     * If the data source has been initialised
+     */
+    initialised?: boolean;
+
     /**
      * Fetch data from a collection
      * @param path
@@ -297,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.
@@ -313,13 +334,13 @@ export interface DataSourceDelegate {
                                                            entityId,
                                                            onUpdate,
                                                            onError
-                                                       }: Omit<ListenEntityProps<M>, "collection">): () => void;
+                                                       }: ListenEntityProps<M>): () => void;
 
     /**
      * Save entity to the specified path
      * @param path
-     * @param id
-     * @param collection
+     * @param entityId
+     * @param values
      * @param status
      */
     saveEntity<M extends Record<string, any> = any>({
@@ -342,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
@@ -360,30 +382,26 @@ export interface DataSourceDelegate {
      * 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,
+    isFilterCombinationValid?(props: Omit<FilterCombinationValidProps, "collection"> & {
+        databaseId?: string
+    }): boolean;
 
     /**
      * Get the object to generate the current time in the datasource
      */
-    currentTime(): any;
-
-    buildDate: (date: Date) => any;
-
-    buildDeleteFieldValue: () => any;
+    currentTime?: () => any;
 
     delegateToCMSModel: (data: any) => any;
 
+    cmsToDelegateModel: (data: any) => any;
+
     setDateToMidnight: (input?: any) => any;
+
+    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;
 
 }