@firecms/core 3.0.0-alpha.7 → 3.0.0-alpha.71

package/src/hooks/data/save.d.ts

@@ -0,0 +1,42 @@
+import { DataSource, Entity, EntityCallbacks, EntityCollection, FireCMSContext, SaveEntityProps, User } from "../../types";
+/**
+ * @group Hooks and utilities
+ */
+export type SaveEntityWithCallbacksProps<M extends Record<string, any>> = SaveEntityProps<M> & {
+    callbacks?: EntityCallbacks<M>;
+    onSaveSuccess?: (updatedEntity: Entity<M>) => void;
+    onSaveFailure?: (e: Error) => void;
+    onPreSaveHookError?: (e: Error) => void;
+    onSaveSuccessHookError?: (e: Error) => void;
+};
+/**
+ * This function is in charge of saving an entity to the datasource.
+ * It will run all the save callbacks specified in the collection.
+ * It is also possible to attach callbacks on save success or error, and callback
+ * errors.
+ *
+ * If you just want to save the data without running the `onSaveSuccess`,
+ * `onSaveFailure` and `onPreSave` callbacks, you can use the `saveEntity` method
+ * in the datasource ({@link useDataSource}).
+ *
+ * @param collection
+ * @param path
+ * @param entityId
+ * @param callbacks
+ * @param values
+ * @param previousValues
+ * @param status
+ * @param dataSource
+ * @param context
+ * @param onSaveSuccess
+ * @param onSaveFailure
+ * @param onPreSaveHookError
+ * @param onSaveSuccessHookError
+ * @see useDataSource
+ * @group Hooks and utilities
+ */
+export declare function saveEntityWithCallbacks<M extends Record<string, any>, UserType extends User>({ collection, path, entityId, values, previousValues, status, dataSource, context, onSaveSuccess, onSaveFailure, onPreSaveHookError, onSaveSuccessHookError }: SaveEntityWithCallbacksProps<M> & {
+    collection: EntityCollection<M>;
+    dataSource: DataSource;
+    context: FireCMSContext<UserType>;
+}): Promise<void>;

package/src/hooks/data/save.ts

@@ -0,0 +1,165 @@
+import {
+    DataSource,
+    Entity,
+    EntityCallbacks,
+    EntityCollection,
+    EntityValues,
+    FireCMSContext,
+    SaveEntityProps,
+    User
+} from "../../types";
+import { useDataSource } from "./useDataSource";
+import { resolveCollection } from "../../util";
+
+/**
+ * @group Hooks and utilities
+ */
+export type SaveEntityWithCallbacksProps<M extends Record<string, any>> =
+    SaveEntityProps<M> &
+    {
+        callbacks?: EntityCallbacks<M>;
+        onSaveSuccess?: (updatedEntity: Entity<M>) => void,
+        onSaveFailure?: (e: Error) => void,
+        onPreSaveHookError?: (e: Error) => void,
+        onSaveSuccessHookError?: (e: Error) => void
+    }
+
+/**
+ * This function is in charge of saving an entity to the datasource.
+ * It will run all the save callbacks specified in the collection.
+ * It is also possible to attach callbacks on save success or error, and callback
+ * errors.
+ *
+ * If you just want to save the data without running the `onSaveSuccess`,
+ * `onSaveFailure` and `onPreSave` callbacks, you can use the `saveEntity` method
+ * in the datasource ({@link useDataSource}).
+ *
+ * @param collection
+ * @param path
+ * @param entityId
+ * @param callbacks
+ * @param values
+ * @param previousValues
+ * @param status
+ * @param dataSource
+ * @param context
+ * @param onSaveSuccess
+ * @param onSaveFailure
+ * @param onPreSaveHookError
+ * @param onSaveSuccessHookError
+ * @see useDataSource
+ * @group Hooks and utilities
+ */
+export async function saveEntityWithCallbacks<M extends Record<string, any>, UserType extends User>({
+                                                                                                        collection,
+                                                                                                        path,
+                                                                                                        entityId,
+                                                                                                        values,
+                                                                                                        previousValues,
+                                                                                                        status,
+                                                                                                        dataSource,
+                                                                                                        context,
+                                                                                                        onSaveSuccess,
+                                                                                                        onSaveFailure,
+                                                                                                        onPreSaveHookError,
+                                                                                                        onSaveSuccessHookError
+                                                                                                    }: SaveEntityWithCallbacksProps<M> & {
+                                                                                                        collection: EntityCollection<M>,
+                                                                                                        dataSource: DataSource,
+                                                                                                        context: FireCMSContext<UserType>,
+                                                                                                    }
+): Promise<void> {
+
+    let updatedValues: Partial<EntityValues<M>>;
+
+    const resolvedPath = context.navigation.resolveAliasesFrom(path);
+
+    const callbacks = collection.callbacks;
+    if (callbacks?.onPreSave) {
+        try {
+            const resolvedCollection = resolveCollection<M>({
+                collection,
+                path,
+                values: previousValues as EntityValues<M>,
+                entityId,
+                fields: context.propertyConfigs
+            });
+            updatedValues = await callbacks.onPreSave({
+                collection: resolvedCollection,
+                path,
+                resolvedPath,
+                entityId,
+                values,
+                previousValues,
+                status,
+                context
+            });
+        } catch (e: any) {
+            console.error(e);
+            if (onPreSaveHookError)
+                onPreSaveHookError(e);
+            return;
+        }
+    } else {
+        updatedValues = values;
+    }
+
+    return dataSource.saveEntity({
+        collection,
+        path: resolvedPath,
+        entityId,
+        values: updatedValues,
+        previousValues,
+        status
+    }).then((entity) => {
+        try {
+            if (callbacks?.onSaveSuccess) {
+                const resolvedCollection = resolveCollection<M>({
+                    collection,
+                    path,
+                    values: updatedValues as EntityValues<M>,
+                    entityId,
+                    fields: context.propertyConfigs
+                });
+                callbacks.onSaveSuccess({
+                    collection: resolvedCollection,
+                    path,
+                    resolvedPath,
+                    entityId: entity.id,
+                    values: updatedValues,
+                    previousValues,
+                    status,
+                    context
+                });
+            }
+        } catch (e: any) {
+            if (onSaveSuccessHookError)
+                onSaveSuccessHookError(e);
+        }
+        if (onSaveSuccess)
+            onSaveSuccess(entity);
+    })
+        .catch((e) => {
+            if (callbacks?.onSaveFailure) {
+
+                const resolvedCollection = resolveCollection<M>({
+                    collection,
+                    path,
+                    values: updatedValues as EntityValues<M>,
+                    entityId,
+                    fields: context.propertyConfigs
+                });
+                callbacks.onSaveFailure({
+                    collection: resolvedCollection,
+                    path,
+                    resolvedPath,
+                    entityId,
+                    values: updatedValues,
+                    previousValues,
+                    status,
+                    context
+                });
+            }
+            if (onSaveFailure) onSaveFailure(e);
+        });
+}

package/src/hooks/data/useCollectionFetch.d.ts

@@ -0,0 +1,50 @@
+import { Entity, EntityCollection, FilterValues, User } from "../../types";
+/**
+ * @group Hooks and utilities
+ */
+export interface CollectionFetchProps<M extends Record<string, any>> {
+    /**
+     * Absolute collection path
+     */
+    path: string;
+    /**
+     * collection of the entity displayed by this collection
+     */
+    collection: EntityCollection<M>;
+    /**
+     * Number of entities to fetch
+     */
+    itemCount?: number;
+    /**
+     * Filter the fetched data by the property
+     */
+    filterValues?: FilterValues<Extract<keyof M, string>>;
+    /**
+     * Sort the results by
+     */
+    sortBy?: [Extract<keyof M, string>, "asc" | "desc"];
+    /**
+     * Search string
+     */
+    searchString?: string;
+}
+/**
+ * @group Hooks and utilities
+ */
+export interface CollectionFetchResult<M extends Record<string, any>> {
+    data: Entity<M>[];
+    dataLoading: boolean;
+    noMoreToLoad: boolean;
+    dataLoadingError?: Error;
+}
+/**
+ * This hook is used to fetch collections using a given collection
+ * @param path
+ * @param collection
+ * @param filterValues
+ * @param sortBy
+ * @param itemCount
+ * @param searchString
+ * @group Hooks and utilities
+ */
+export declare function useCollectionFetch<M extends Record<string, any>, UserType extends User>({ path: inputPath, collection, filterValues, sortBy, itemCount, searchString }: CollectionFetchProps<M>): CollectionFetchResult<M>;

package/src/hooks/data/useCollectionFetch.tsx

@@ -0,0 +1,162 @@
+import { useEffect, useState } from "react";
+import { Entity, EntityCollection, FilterValues, FireCMSContext, User } from "../../types";
+import { useDataSource } from "./useDataSource";
+import { useNavigationController } from "../useNavigationController";
+import { useFireCMSContext } from "../useFireCMSContext";
+
+/**
+ * @group Hooks and utilities
+ */
+export interface CollectionFetchProps<M extends Record<string, any>> {
+
+    /**
+     * Absolute collection path
+     */
+    path: string;
+
+    /**
+     * collection of the entity displayed by this collection
+     */
+    collection: EntityCollection<M>
+
+    /**
+     * Number of entities to fetch
+     */
+    itemCount?: number;
+
+    /**
+     * Filter the fetched data by the property
+     */
+    filterValues?: FilterValues<Extract<keyof M, string>>;
+
+    /**
+     * Sort the results by
+     */
+    sortBy?: [Extract<keyof M, string>, "asc" | "desc"];
+
+    /**
+     * Search string
+     */
+    searchString?: string;
+}
+
+/**
+ * @group Hooks and utilities
+ */
+export interface CollectionFetchResult<M extends Record<string, any>> {
+    data: Entity<M>[];
+    dataLoading: boolean;
+    noMoreToLoad: boolean;
+    dataLoadingError?: Error;
+}
+
+/**
+ * This hook is used to fetch collections using a given collection
+ * @param path
+ * @param collection
+ * @param filterValues
+ * @param sortBy
+ * @param itemCount
+ * @param searchString
+ * @group Hooks and utilities
+ */
+export function useCollectionFetch<M extends Record<string, any>, UserType extends User>(
+    {
+        path: inputPath,
+        collection,
+        filterValues,
+        sortBy,
+        itemCount,
+        searchString
+    }: CollectionFetchProps<M>): CollectionFetchResult<M> {
+
+    const dataSource = useDataSource();
+    const navigationController = useNavigationController();
+
+    const path = navigationController.resolveAliasesFrom(inputPath);
+
+    const sortByProperty = sortBy ? sortBy[0] : undefined;
+    const currentSort = sortBy ? sortBy[1] : undefined;
+
+    const context: FireCMSContext<UserType> = useFireCMSContext();
+
+    const [data, setData] = useState<Entity<M>[]>([]);
+
+    const [dataLoading, setDataLoading] = useState<boolean>(false);
+    const [dataLoadingError, setDataLoadingError] = useState<Error | undefined>();
+    const [noMoreToLoad, setNoMoreToLoad] = useState<boolean>(false);
+
+    useEffect(() => {
+
+        setDataLoading(true);
+
+        const onEntitiesUpdate = async (entities: Entity<M>[]) => {
+            if (collection.callbacks?.onFetch) {
+                try {
+                    entities = await Promise.all(
+                        entities.map((entity) =>
+                            collection.callbacks!.onFetch!({
+                                collection,
+                                path,
+                                entity,
+                                context
+                            })));
+                } catch (e: any) {
+                    console.error(e);
+                }
+            }
+            setDataLoading(false);
+            setDataLoadingError(undefined);
+            setData(entities.map(e => ({
+                ...e,
+                // values: sanitizeData(e.values, resolvedCollection.properties)
+            })));
+            setNoMoreToLoad(!itemCount || entities.length < itemCount);
+        };
+
+        const onError = (error: Error) => {
+            console.error("ERROR", error);
+            setDataLoading(false);
+            setData([]);
+            setDataLoadingError(error);
+        };
+
+        if (dataSource.listenCollection) {
+            return dataSource.listenCollection<M>({
+                path,
+                collection,
+                onUpdate: onEntitiesUpdate,
+                onError,
+                searchString,
+                filter: filterValues,
+                limit: itemCount,
+                startAfter: undefined,
+                orderBy: sortByProperty,
+                order: currentSort
+            });
+        } else {
+            dataSource.fetchCollection<M>({
+                path,
+                collection,
+                searchString,
+                filter: filterValues,
+                limit: itemCount,
+                startAfter: undefined,
+                orderBy: sortByProperty,
+                order: currentSort
+            })
+                .then(onEntitiesUpdate)
+                .catch(onError);
+            return () => {
+            };
+        }
+    }, [path, itemCount, currentSort, sortByProperty, filterValues, searchString]);
+
+    return {
+        data,
+        dataLoading,
+        dataLoadingError,
+        noMoreToLoad
+    };
+
+}

package/src/hooks/data/useDataOrder.d.ts

@@ -0,0 +1,12 @@
+import { Entity } from "../../types";
+export interface DataOrderProps<M extends Record<string, any>> {
+    data: Entity<M>[];
+    entitiesDisplayedFirst?: Entity<M>[];
+}
+/**
+ * This hook is used to have some entities at the beginning of data.
+ * @param path
+ * @param entitiesDisplayedFirst
+ * @group Hooks and utilities
+ */
+export declare function useDataOrder<M extends Record<string, any>>({ data, entitiesDisplayedFirst }: DataOrderProps<M>): Entity<M>[];

package/src/hooks/data/useDataOrder.ts

@@ -0,0 +1,26 @@
+import { Entity } from "../../types";
+
+export interface DataOrderProps<M extends Record<string, any>> {
+    data: Entity<M>[];
+    entitiesDisplayedFirst?: Entity<M>[];
+}
+
+/**
+ * This hook is used to have some entities at the beginning of data.
+ * @param path
+ * @param entitiesDisplayedFirst
+ * @group Hooks and utilities
+ */
+export function useDataOrder<M extends Record<string, any>>(
+    {
+        data,
+        entitiesDisplayedFirst
+    }: DataOrderProps<M>): Entity<M>[] {
+
+    if (!entitiesDisplayedFirst)
+        return data;
+
+    const displayedFirstId = new Set(entitiesDisplayedFirst.map((e) => e.id));
+    return [...entitiesDisplayedFirst, ...data.filter((e) => !displayedFirstId.has(e.id))];
+
+}

package/src/hooks/data/useDataSource.d.ts

@@ -0,0 +1,6 @@
+import { DataSource } from "../../types";
+/**
+ * Use this hook to get the datasource being used
+ * @group Hooks and utilities
+ */
+export declare const useDataSource: () => DataSource;

package/src/hooks/data/useDataSource.tsx

@@ -0,0 +1,9 @@
+import { useContext } from "react";
+import { DataSource } from "../../types";
+import { DataSourceContext } from "../../contexts/DataSourceContext";
+
+/**
+ * Use this hook to get the datasource being used
+ * @group Hooks and utilities
+ */
+export const useDataSource = (): DataSource => useContext(DataSourceContext);

package/src/hooks/data/useEntityFetch.d.ts

@@ -0,0 +1,28 @@
+import { Entity, EntityCollection, User } from "../../types";
+/**
+ * @group Hooks and utilities
+ */
+export interface EntityFetchProps<M extends Record<string, any>> {
+    path: string;
+    entityId?: string;
+    collection: EntityCollection<M>;
+    useCache?: boolean;
+}
+/**
+ * @group Hooks and utilities
+ */
+export interface EntityFetchResult<M extends Record<string, any>> {
+    entity?: Entity<M>;
+    dataLoading: boolean;
+    dataLoadingError?: Error;
+}
+/**
+ * This hook is used to fetch an entity.
+ * It gives real time updates if the datasource supports it.
+ * @param path
+ * @param collection
+ * @param entityId
+ * @param useCache
+ * @group Hooks and utilities
+ */
+export declare function useEntityFetch<M extends Record<string, any>, UserType extends User>({ path: inputPath, entityId, collection, useCache }: EntityFetchProps<M>): EntityFetchResult<M>;

package/src/hooks/data/useEntityFetch.tsx

@@ -0,0 +1,129 @@
+import { useEffect, useState } from "react";
+import { Entity, EntityCollection, FireCMSContext, User } from "../../types";
+import { useDataSource } from "./useDataSource";
+import { useNavigationController } from "../useNavigationController";
+import { useFireCMSContext } from "../useFireCMSContext";
+
+/**
+ * @group Hooks and utilities
+ */
+export interface EntityFetchProps<M extends Record<string, any>> {
+    path: string;
+    entityId?: string;
+    collection: EntityCollection<M>;
+    useCache?: boolean;
+}
+
+/**
+ * @group Hooks and utilities
+ */
+export interface EntityFetchResult<M extends Record<string, any>> {
+    entity?: Entity<M>,
+    dataLoading: boolean,
+    dataLoadingError?: Error
+}
+
+const CACHE: Record<string, Entity<any> | undefined> = {};
+
+/**
+ * This hook is used to fetch an entity.
+ * It gives real time updates if the datasource supports it.
+ * @param path
+ * @param collection
+ * @param entityId
+ * @param useCache
+ * @group Hooks and utilities
+ */
+
+export function useEntityFetch<M extends Record<string, any>, UserType extends User>(
+    {
+        path: inputPath,
+        entityId,
+        collection,
+        useCache = false
+    }: EntityFetchProps<M>): EntityFetchResult<M> {
+
+    const dataSource = useDataSource();
+    const navigationController = useNavigationController();
+
+    const path = navigationController.resolveAliasesFrom(inputPath);
+
+    const context: FireCMSContext<UserType> = useFireCMSContext();
+
+    const [entity, setEntity] = useState<Entity<M> | undefined>();
+    const [dataLoading, setDataLoading] = useState<boolean>(true);
+    const [dataLoadingError, setDataLoadingError] = useState<Error | undefined>();
+
+    useEffect(() => {
+
+        setDataLoading(true);
+
+        const onEntityUpdate = async (updatedEntity: Entity<M> | undefined) => {
+            if (collection.callbacks?.onFetch && updatedEntity) {
+                try {
+                    updatedEntity = await collection.callbacks.onFetch({
+                        collection,
+                        path,
+                        entity: updatedEntity,
+                        context
+                    });
+                } catch (e: any) {
+                    console.error(e);
+                }
+            }
+            CACHE[`${path}/${entityId}`] = updatedEntity;
+            setEntity(updatedEntity);
+            setDataLoading(false);
+            setDataLoadingError(undefined);
+        };
+
+        const onError = (error: Error) => {
+            console.error("ERROR fetching entity", error);
+            setDataLoading(false);
+            setEntity(undefined);
+            setDataLoadingError(error);
+        };
+
+        if (entityId && useCache && CACHE[`${path}/${entityId}`]) {
+            setEntity(CACHE[`${path}/${entityId}`]);
+            setDataLoading(false);
+            setDataLoadingError(undefined);
+            // eslint-disable-next-line @typescript-eslint/no-empty-function
+            return () => {
+            };
+        } else if (entityId && path && collection) {
+            if (dataSource.listenEntity) {
+                return dataSource.listenEntity<M>({
+                    path,
+                    entityId,
+                    collection,
+                    onUpdate: onEntityUpdate,
+                    onError
+                });
+            } else {
+                dataSource.fetchEntity<M>({
+                    path,
+                    entityId,
+                    collection
+                })
+                    .then(onEntityUpdate)
+                    .catch(onError);
+                return () => {
+                };
+            }
+        }
+        // if no entityId is provided we do nothing
+        else {
+            onEntityUpdate(undefined);
+            return () => {
+            };
+        }
+    }, [entityId, path]);
+
+    return {
+        entity,
+        dataLoading,
+        dataLoadingError
+    };
+
+}

package/src/hooks/index.d.ts

@@ -0,0 +1,19 @@
+export * from "./data/useDataSource";
+export * from "./data/useCollectionFetch";
+export * from "./data/useEntityFetch";
+export * from "./data/save";
+export * from "./data/delete";
+export * from "../form/useClearRestoreValue";
+export * from "./useNavigationController";
+export * from "./useResolvedNavigationFrom";
+export * from "./useStorageSource";
+export * from "./useAuthController";
+export * from "./useSideDialogsController";
+export * from "./useSideEntityController";
+export * from "./useFireCMSContext";
+export * from "./useSnackbarController";
+export * from "./useModeController";
+export * from "./useClipboard";
+export * from "./useLargeLayout";
+export * from "./useReferenceDialog";
+export * from "./useBrowserTitleAndIcon";

package/src/hooks/index.tsx

@@ -0,0 +1,23 @@
+export * from "./data/useDataSource";
+export * from "./data/useCollectionFetch";
+export * from "./data/useEntityFetch";
+export * from "./data/save";
+export * from "./data/delete";
+
+export * from "../form/useClearRestoreValue";
+export * from "./useNavigationController";
+
+export * from "./useResolvedNavigationFrom";
+
+export * from "./useStorageSource";
+export * from "./useAuthController";
+export * from "./useSideDialogsController";
+export * from "./useSideEntityController";
+export * from "./useFireCMSContext";
+export * from "./useSnackbarController";
+export * from "./useModeController";
+export * from "./useClipboard";
+export * from "./useLargeLayout";
+
+export * from "./useReferenceDialog";
+export * from "./useBrowserTitleAndIcon";