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

package/src/hooks/useBuildDataSource.ts

@@ -0,0 +1,351 @@
+import { useCallback } from "react";
+import {
+    DataSource,
+    DataSourceDelegate, DeleteEntityProps,
+    Entity,
+    EntityCollection,
+    EntityReference,
+    EntityValues,
+    FetchCollectionProps,
+    FetchEntityProps,
+    FilterValues,
+    GeoPoint,
+    ListenCollectionProps,
+    ListenEntityProps,
+    PropertyConfig,
+    ResolvedProperties,
+    SaveEntityProps
+} from "../types";
+import { resolveCollection, updateDateAutoValues } from "../core";
+
+/**
+ * Use this hook to build a {@link DataSource} based on Firestore
+ * @param firebaseApp
+ * @param textSearchController
+ * @param collectionRegistry
+ * @category Firebase
+ */
+export function useBuildDataSource({
+                                       delegate,
+                                       customFields
+                                   }: {
+    delegate: DataSourceDelegate,
+    customFields: Record<string, PropertyConfig>;
+}): DataSource {
+
+    return {
+
+        /**
+         * Fetch entities in a Firestore path
+         * @param path
+         * @param collection
+         * @param filter
+         * @param limit
+         * @param startAfter
+         * @param searchString
+         * @param orderBy
+         * @param order
+         * @return Function to cancel subscription
+         * @see useCollectionFetch if you need this functionality implemented as a hook
+         * @category Firestore
+         */
+        fetchCollection: useCallback(<M extends Record<string, any>>({
+                                                                         path,
+                                                                         collection,
+                                                                         filter,
+                                                                         limit,
+                                                                         startAfter,
+                                                                         searchString,
+                                                                         orderBy,
+                                                                         order
+                                                                     }: FetchCollectionProps<M>
+        ): Promise<Entity<M>[]> => {
+
+            return delegate.fetchCollection<M>({
+                path,
+                filter,
+                limit,
+                startAfter,
+                searchString,
+                orderBy,
+                order
+            });
+        }, [delegate]),
+
+        /**
+         * Listen to a entities in a given path
+         * @param path
+         * @param collection
+         * @param onError
+         * @param filter
+         * @param limit
+         * @param startAfter
+         * @param searchString
+         * @param orderBy
+         * @param order
+         * @param onUpdate
+         * @return Function to cancel subscription
+         * @see useCollectionFetch if you need this functionality implemented as a hook
+         * @category Firestore
+         */
+        listenCollection: delegate.listenCollection
+            // eslint-disable-next-line react-hooks/rules-of-hooks
+            ? useCallback(<M extends Record<string, any>>(
+                {
+                    path,
+                    collection,
+                    filter,
+                    limit,
+                    startAfter,
+                    searchString,
+                    orderBy,
+                    order,
+                    onUpdate,
+                    onError
+                }: ListenCollectionProps<M>
+            ): () => void => {
+
+                const isCollectionGroup = Boolean(collection.collectionGroup) ?? false;
+                if (!delegate.listenCollection)
+                    throw Error("useBuildDataSource delegate not initialised");
+
+                return delegate.listenCollection<M>({
+                    path,
+                    filter,
+                    limit,
+                    startAfter,
+                    searchString,
+                    orderBy,
+                    order,
+                    onUpdate,
+                    onError,
+                    isCollectionGroup
+                });
+            }, [delegate])
+            : undefined,
+
+        /**
+         * Retrieve an entity given a path and a collection
+         * @param path
+         * @param entityId
+         * @param collection
+         * @category Firestore
+         */
+        fetchEntity: useCallback(<M extends Record<string, any>>({
+                                                                     path,
+                                                                     entityId
+                                                                 }: FetchEntityProps<M>
+        ): Promise<Entity<M> | undefined> => delegate.fetchEntity({
+            path,
+            entityId
+        }), [delegate]),
+
+        /**
+         *
+         * @param path
+         * @param entityId
+         * @param collection
+         * @param onUpdate
+         * @param onError
+         * @return Function to cancel subscription
+         * @category Firestore
+         */
+        listenEntity: delegate.listenEntity
+            // eslint-disable-next-line react-hooks/rules-of-hooks
+            ? useCallback(<M extends Record<string, any>>(
+                {
+                    path,
+                    entityId,
+                    collection,
+                    onUpdate,
+                    onError
+                }: ListenEntityProps<M>): () => void => {
+                if (!delegate.listenEntity)
+                    throw Error("useBuildDataSource delegate not initialised");
+
+                return delegate.listenEntity<M>({
+                    path,
+                    entityId,
+                    onUpdate,
+                    onError
+                })
+            }, [delegate.listenEntity]) : undefined,
+
+        /**
+         * Save entity to the specified path. Note that Firestore does not allow
+         * undefined values.
+         * @param path
+         * @param entityId
+         * @param values
+         * @param schemaId
+         * @param collection
+         * @param status
+         * @category Firestore
+         */
+        saveEntity: useCallback(<M extends Record<string, any>>(
+            {
+                path,
+                entityId,
+                values,
+                collection,
+                status
+            }: SaveEntityProps<M>): Promise<Entity<M>> => {
+
+            const resolvedCollection = resolveCollection<M>({
+                collection,
+                path,
+                entityId,
+                fields: customFields
+            });
+
+            const properties: ResolvedProperties<M> = resolvedCollection.properties;
+
+            const firestoreValues = cmsToDelegateModel(
+                values,
+                delegate.buildReference,
+                delegate.buildGeoPoint,
+                delegate.buildDate,
+                delegate.buildDeleteFieldValue
+            );
+            const updatedFirestoreValues: EntityValues<M> = updateDateAutoValues(
+                {
+                    inputValues: firestoreValues,
+                    properties,
+                    status,
+                    timestampNowValue: delegate.currentTime(),
+                    setDateToMidnight: delegate.setDateToMidnight
+                });
+
+            console.debug("Saving entity", path, entityId, updatedFirestoreValues);
+
+            return delegate.saveEntity({
+                path,
+                entityId,
+                values: updatedFirestoreValues,
+                status
+            }).then((res) => {
+                return {
+                    id: res.id,
+                    path: res.path,
+                    values: delegate.delegateToCMSModel(updatedFirestoreValues)
+                } as Entity<M>;
+            });
+        }, [delegate.saveEntity]),
+
+        /**
+         * Delete an entity
+         * @param entity
+         * @param collection
+         * @category Firestore
+         */
+        deleteEntity: useCallback(<M extends Record<string, any>>(
+            {
+                entity
+            }: DeleteEntityProps<M>
+        ): Promise<void> => {
+            return delegate.deleteEntity({entity});
+        }, [delegate.deleteEntity]),
+
+        /**
+         * Check if the given property is unique in the given collection
+         * @param path Collection path
+         * @param name of the property
+         * @param value
+         * @param property
+         * @param entityId
+         * @return `true` if there are no other fields besides the given entity
+         * @category Firestore
+         */
+        checkUniqueField: useCallback((
+            path: string,
+            name: string,
+            value: any,
+            entityId?: string
+        ): Promise<boolean> => {
+            return delegate.checkUniqueField(path, name, value, entityId);
+        }, [delegate.checkUniqueField]),
+
+        generateEntityId: useCallback((path: string): string => {
+            return delegate.generateEntityId(path, );
+        }, [delegate.generateEntityId]),
+
+        countEntities: useCallback(async ({
+                                              path,
+                                              collection,
+                                              filter,
+                                              order,
+                                              orderBy
+                                          }: {
+            path: string,
+            collection: EntityCollection<any>,
+            filter?: FilterValues<Extract<keyof any, string>>,
+            orderBy?: string,
+            order?: "desc" | "asc",
+        }): Promise<number> => {
+            return delegate.countEntities({
+                path,
+                filter,
+                orderBy,
+                order,
+                isCollectionGroup: Boolean(collection.collectionGroup) ?? false
+            });
+        }, [delegate.countEntities]),
+
+        isFilterCombinationValid: useCallback(({
+                                                   path,
+                                                   filterValues,
+                                                   sortBy
+                                               }: {
+            path: string,
+            filterValues: FilterValues<any>,
+            sortBy?: [string, "asc" | "desc"]
+        }): boolean => {
+            if (!delegate.isFilterCombinationValid)
+                return true;
+            return delegate.isFilterCombinationValid(
+                {
+                    path,
+                    filterValues,
+                    sortBy
+                }
+            )
+        }, [delegate.isFilterCombinationValid])
+
+    };
+
+}
+
+/**
+ * Recursive function that converts Firestore data types into CMS or plain
+ * JS types.
+ * FireCMS uses Javascript dates internally instead of Firestore timestamps.
+ * This makes it easier to interact with the rest of the libraries and
+ * bindings.
+ * Also, Firestore references are replaced with {@link EntityReference}
+ * @param data
+ * @category Firestore
+ */
+export function cmsToDelegateModel(data: any,
+                                   buildReference: (reference: EntityReference) => any,
+                                   buildGeoPoint: (geoPoint: GeoPoint) => any,
+                                   buildDate: (date: Date) => any,
+                                   buildDelete: () => any
+): any {
+    if (data === undefined) {
+        return buildDelete();
+    } else if (Array.isArray(data)) {
+        return data.map(v => cmsToDelegateModel(v, buildReference, buildGeoPoint, buildDate, buildDelete));
+    } else if (data instanceof EntityReference) {
+        return buildReference(data);
+    } else if (data instanceof GeoPoint) {
+        return buildGeoPoint(data);
+    } else if (data instanceof Date) {
+        return buildDate(data);
+    } else if (data && typeof data === "object") {
+        return Object.entries(data)
+            .map(([key, v]) => ({ [key]: cmsToDelegateModel(v, buildReference, buildGeoPoint, buildDate, buildDelete) }))
+            .reduce((a, b) => ({ ...a, ...b }), {});
+    }
+    return data;
+}
+

package/src/hooks/useDialogsController.tsx

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { DialogsController } from "../types/dialogs_controller";
+import { DialogsControllerContext } from "../core/contexts/DialogsProvider";
+
+/**
+ * Use this hook to open a dialog imperatively.
+ * Alternatively, you can use dialogs declaratively using the `Dialog` component.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `FireCMS`
+ *
+ * @category Hooks and utilities
+ */
+export const useDialogsController = (): DialogsController => useContext(DialogsControllerContext);

package/src/hooks/useFireCMSContext.tsx

@@ -8,17 +8,9 @@ import { useDataSource } from "./data/useDataSource";
 import { useStorageSource } from "./useStorageSource";
 import { useSnackbarController } from "./useSnackbarController";
 import { useUserConfigurationPersistence } from "./useUserConfigurationPersistence";
+import { useDialogsController } from "./useDialogsController";
 
-export const FireCMSContextInstance = createContext<Partial<FireCMSContext>>({
-    sideDialogsController: {} as any,
-    sideEntityController: {} as any,
-    navigation: {} as any,
-    dataSource: {} as any,
-    storageSource: {} as any,
-    authController: {} as any,
-    snackbarController: {} as any,
-    fields: {}
-});
+export const FireCMSContextInstance = createContext<Partial<FireCMSContext>>({});
 
 /**
  * Hook to retrieve the {@link FireCMSContext}.
@@ -40,6 +32,7 @@ export const useFireCMSContext = <UserType extends User = User, AuthControllerTy
     const storageSource = useStorageSource();
     const snackbarController = useSnackbarController();
     const userConfigPersistence = useUserConfigurationPersistence();
+    const dialogsController = useDialogsController();
 
     return {
         ...partialContext,
@@ -50,7 +43,8 @@ export const useFireCMSContext = <UserType extends User = User, AuthControllerTy
         dataSource,
         storageSource,
         snackbarController,
-        userConfigPersistence
+        userConfigPersistence,
+        dialogsController
     }
 
 };

package/src/preview/property_previews/StringPropertyPreview.tsx

@@ -45,13 +45,15 @@ export function StringPropertyPreview({
         if (!value) return <></>;
         const lines = value.split("\n");
         return value && value.includes("\n")
-            ? <div>
+            ? <div className={"overflow-x-scroll"}>
                 {lines.map((str, index) =>
                     <React.Fragment key={`string_preview_${index}`}>
                         <span>{str}</span>
                         {index !== lines.length - 1 && <br/>}
                     </React.Fragment>)}
             </div>
-            : <>{value}</>;
+            : <>
+                {value}
+            </>;
     }
 }

package/src/styles.ts

@@ -1,4 +1,4 @@
-export const focusedMixin = "focus:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-opacity-75 focus-visible:ring-offset-2 focus-visible:ring-offset-transparent";
+export const focusedMixin = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-opacity-75 focus-visible:ring-offset-2 focus-visible:ring-offset-transparent";
 export const focusedInvisibleMixin = "focus:bg-opacity-70 focus:bg-gray-100 focus:dark:bg-gray-800 focus:dark:bg-opacity-60";
 export const focusedClasses = "z-30 outline-none ring-2 ring-primary ring-opacity-75 ring-offset-2 ring-offset-transparent ";
 export const fieldBackgroundMixin = "bg-opacity-70 bg-gray-100 dark:bg-gray-800 dark:bg-opacity-60 transition duration-150 ease-in-out";

package/src/types/collections.ts

@@ -6,6 +6,7 @@ import { EntityCallbacks } from "./entity_callbacks";
 import { Permissions, PermissionsBuilder } from "./permissions";
 import { EnumValues, PropertiesOrBuilders } from "./properties";
 import { FormContext } from "./fields";
+import { EntityAction } from "./entity_actions";
 
 /**
  * This interface represents a view that includes a collection of entities.
@@ -14,9 +15,7 @@ import { FormContext } from "./fields";
  *
  * @category Models
  */
-export interface EntityCollection<M extends Record<string, any> = any,
-    AdditionalKey extends string = string,
-    UserType extends User = User> {
+export interface EntityCollection<M extends Record<string, any> = any, UserType extends User = User> {
 
     /**
      * Name of the collection, typically plural.
@@ -58,9 +57,9 @@ export interface EntityCollection<M extends Record<string, any> = any,
 
     /**
      * Icon key to use in this collection.
-     * 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;
 
@@ -93,7 +92,7 @@ export interface EntityCollection<M extends Record<string, any> = any,
      *     - If you are using a collection group, you will also have an
      *       additional `collectionGroupParent` column.
      */
-    propertiesOrder?: Extract<keyof M | AdditionalKey, string>[];
+    propertiesOrder?: Extract<keyof M, string>[];
 
     /**
      * If enabled, content is loaded in batches. If `false` all entities in the
@@ -113,7 +112,7 @@ export interface EntityCollection<M extends Record<string, any> = any,
      * Permissions the logged-in user can perform on this collection.
      * If not specified everything defaults to `true`.
      */
-    permissions?: Permissions | PermissionsBuilder<EntityCollection<M>, UserType, M>;
+    permissions?: Permissions | PermissionsBuilder<any, UserType, M>;
 
     /**
      * Are the entities in this collection selectable. Defaults to `true`
@@ -140,6 +139,31 @@ export interface EntityCollection<M extends Record<string, any> = any,
      */
     Actions?: React.ComponentType<CollectionActionsProps> | React.ComponentType<CollectionActionsProps>[];
 
+    /**
+     * You can define additional actions that can be performed on the entities
+     * in this collection. These actions can be displayed in the collection
+     * view or in the entity view.
+     *
+     * You can use the `onClick` method to implement your own logic.
+     * In the `context` prop you can access all the controllers of FireCMS.
+     *
+     * ```
+     * const archiveEntityAction: EntityAction = {
+     *     icon: <ArchiveIcon/>,
+     *     name: "Archive",
+     *     onClick({
+     *                 entity,
+     *                 collection,
+     *                 context,
+     *             }): Promise<void> {
+     *         // Add your code here
+     *         return Promise.resolve(undefined);
+     *     }
+     * }
+     * ```
+     */
+    entityActions?: EntityAction<M, UserType>[];
+
     /**
      * Pass your own selection controller if you want to control selected
      * entities externally.
@@ -190,8 +214,7 @@ export interface EntityCollection<M extends Record<string, any> = any,
      * You can add additional fields to the collection view by implementing
      * an additional field delegate.
      */
-    additionalFields?: AdditionalFieldDelegate<M, AdditionalKey, UserType>[];
-
+    additionalFields?: AdditionalFieldDelegate<M, UserType>[];
 
     /**
      * Default size of the rendered collection
@@ -245,10 +268,8 @@ export interface EntityCollection<M extends Record<string, any> = any,
 
 /**
  * Parameter passed to the `Actions` prop in the collection configuration.
- * Note that actions are rendered in the collection toolbar, as well
- * as in the home page card.
- * If you don't want to render the actions in the home page card, you can
- * return `null` if mode is `home`.
+ * The component will receive this prop when it is rendered in the collection
+ * toolbar.
  *
  * @category Models
  */
@@ -349,7 +370,6 @@ 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> = {
     entity: Entity<M>,
     context: FireCMSContext<UserType>
@@ -361,14 +381,13 @@ export type AdditionalFieldDelegateProps<M extends Record<string, any> = any, Us
  * @category Models
  */
 export interface AdditionalFieldDelegate<M extends Record<string, any> = any,
-    AdditionalKey extends string = string,
     UserType extends User = User> {
 
     /**
      * ID of this column. You can use this id in the `properties` field of the
      * collection in any order you want
      */
-    id: AdditionalKey;
+    id: string;
 
     /**
      * Header of this column