@firecms/core 3.0.0-canary.29 → 3.0.0-canary.290

package/src/components/common/useColumnsIds.tsx

@@ -3,12 +3,13 @@ import { EntityCollection, ResolvedEntityCollection, ResolvedProperty } from "..
 import { getSubcollectionColumnId } from "../EntityCollectionTable/internal/common";
 import { PropertyColumnConfig } from "../EntityCollectionTable/EntityCollectionTableProps";
 
-const COLLECTION_GROUP_PARENT_ID = "collectionGroupParent";
+export const COLLECTION_GROUP_PARENT_ID = "collectionGroupParent";
 
 export function useColumnIds<M extends Record<string, any>>(collection: ResolvedEntityCollection<M>, includeSubcollections: boolean): PropertyColumnConfig[] {
     return useMemo(() => {
-        if (collection.propertiesOrder)
+        if (collection.propertiesOrder) {
             return hideAndExpandKeys(collection, collection.propertiesOrder);
+        }
         return getDefaultColumnKeys(collection, includeSubcollections);
     }, [collection, includeSubcollections]);
 }
@@ -98,3 +99,16 @@ export function getColumnKeysForProperty(property: ResolvedProperty, key: string
         disabled: disabled || Boolean(property.disabled) || Boolean(property.readOnly)
     }];
 }
+
+export function getFormFieldKeys(collection: EntityCollection): string[] {
+    const propertyKeys = Object.keys(collection.properties);
+    const additionalFields = collection.additionalFields ?? [];
+    const allKeys = [
+        ...propertyKeys,
+        ...additionalFields.map((field) => field.key)
+    ];
+    if (collection.propertiesOrder) {
+        return collection.propertiesOrder.filter(key => allKeys.includes(key));
+    }
+    return allKeys;
+}

package/src/components/common/useDataSourceTableController.tsx

@@ -0,0 +1,420 @@
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+
+import { useDataSource, useFireCMSContext, useNavigationController } from "../../hooks";
+import { useDataOrder } from "../../hooks/data/useDataOrder";
+import {
+    Entity,
+    EntityCollection,
+    EntityReference,
+    EntityTableController,
+    FilterValues,
+    FireCMSContext,
+    SelectedCellProps,
+    User,
+    WhereFilterOp
+} from "../../types";
+import { useDebouncedData } from "./useDebouncedData";
+import { ScrollRestorationController } from "./useScrollRestoration";
+
+const DEFAULT_PAGE_SIZE = 50;
+
+export type DataSourceTableControllerProps<M extends Record<string, any> = any> = {
+    /**
+     * Full path where the data of this table is located
+     */
+    fullPath: string;
+    /**
+     * The collection that is represented by this config.
+     */
+    collection: EntityCollection<M>;
+    /**
+     * List of entities that will be displayed on top, no matter the ordering.
+     * This is used for reference fields selection
+     */
+    entitiesDisplayedFirst?: Entity<M>[];
+
+    lastDeleteTimestamp?: number;
+
+    /**
+     * Force filter to be applied to the table.
+     */
+    forceFilter?: FilterValues<string>;
+
+    scrollRestoration?: ScrollRestorationController;
+
+    /**
+     * When set to true the filters and sort will be updated in the URL
+     */
+    updateUrl?: boolean;
+
+}
+
+/**
+ * Use this hook to build a controller for the {@link EntityCollectionTable}.
+ * This controller is bound to data in a path in your specified datasource.
+ *
+ * Note that you can build your own hook returning a {@link EntityTableController}
+ * if you would like to display different data.
+ *
+ * @param fullPath
+ * @param collection
+ * @param scrollRestoration
+ * @param entitiesDisplayedFirst
+ * @param lastDeleteTimestamp
+ * @param forceFilterFromProps
+ * @param updateUrl
+ */
+export function useDataSourceTableController<M extends Record<string, any> = any, USER extends User = User>(
+    {
+        fullPath,
+        collection,
+        scrollRestoration,
+        entitiesDisplayedFirst,
+        lastDeleteTimestamp,
+        forceFilter: forceFilterFromProps,
+        updateUrl
+    }: DataSourceTableControllerProps<M>)
+    : EntityTableController<M> {
+
+    const {
+        initialFilter,
+        initialSort,
+        forceFilter: forceFilterFromCollection
+    } = collection;
+
+    const [popupCell, setPopupCell] = React.useState<SelectedCellProps<M> | undefined>(undefined);
+    const navigation = useNavigationController();
+    const dataSource = useDataSource(collection);
+    const resolvedPath = useMemo(() => navigation.resolveIdsFrom(fullPath), [fullPath, navigation.resolveIdsFrom]);
+
+    const forceFilter = forceFilterFromProps ?? forceFilterFromCollection;
+    const paginationEnabled = collection.pagination === undefined || Boolean(collection.pagination);
+    const pageSize = typeof collection.pagination === "number" ? collection.pagination : DEFAULT_PAGE_SIZE;
+
+    const [searchString, setSearchString] = React.useState<string | undefined>();
+
+    const checkFilterCombination = useCallback((filterValues: FilterValues<any>,
+                                                sortBy?: [string, "asc" | "desc"]) => {
+        if (!dataSource.isFilterCombinationValid)
+            return true;
+        return dataSource.isFilterCombinationValid({
+            path: resolvedPath,
+            collection,
+            filterValues,
+            sortBy
+        })
+    }, []);
+
+    const onScroll = ({
+                          scrollOffset
+                      }: {
+        scrollOffset: number
+    }) => {
+        if (scrollRestoration) {
+            scrollRestoration.updateCollectionScroll({
+                fullPath: resolvedPath,
+                scrollOffset,
+                data: rawData,
+                filters: filterValues
+            });
+        }
+    }
+
+    const initialSortInternal = useMemo(() => {
+        if (initialSort && forceFilter && !checkFilterCombination(forceFilter, initialSort)) {
+            console.warn("Initial sort is not compatible with the force filter. Ignoring initial sort");
+            return undefined;
+        }
+        return initialSort;
+    }, [initialSort, forceFilter]);
+
+    const {
+        filterValues: initialFilterUrl,
+        sortBy: initialSortUrl,
+    } = parseFilterAndSort(window.location.search);
+
+    const [filterValues, setFilterValues] = React.useState<FilterValues<Extract<keyof M, string>> | undefined>(forceFilter ?? (updateUrl ? initialFilterUrl : undefined) ?? initialFilter ?? undefined);
+    const [sortBy, setSortBy] = React.useState<[Extract<keyof M, string>, "asc" | "desc"] | undefined>((updateUrl ? initialSortUrl : undefined) ?? initialSortInternal);
+
+    useUpdateUrl(filterValues, sortBy, searchString, updateUrl);
+
+    const collectionScroll = scrollRestoration?.getCollectionScroll(fullPath, filterValues);
+    const initialItemCount = collectionScroll?.data.length ?? pageSize;
+
+    useEffect(() => {
+        if (scrollRestoration) {
+            scrollRestoration.updateCollectionScroll({
+                fullPath: resolvedPath,
+                scrollOffset: collectionScroll?.scrollOffset ?? 0,
+                data: rawData,
+                filters: filterValues
+            });
+        }
+    }, []);
+
+    const [itemCount, setItemCount] = React.useState<number | undefined>(paginationEnabled ? initialItemCount : undefined);
+
+    const sortByProperty = sortBy ? sortBy[0] : undefined;
+    const currentSort = sortBy ? sortBy[1] : undefined;
+
+    const context: FireCMSContext<USER> = useFireCMSContext();
+
+    const [rawData, setRawData] = useState<Entity<M>[]>(collectionScroll?.data ?? []);
+
+    const [dataLoading, setDataLoading] = useState<boolean>(false);
+    const [dataLoadingError, setDataLoadingError] = useState<Error | undefined>();
+    const [noMoreToLoad, setNoMoreToLoad] = useState<boolean>(false);
+
+    const clearFilter = useCallback(() => setFilterValues(forceFilter ?? undefined), [forceFilter]);
+
+    const updateFilterValues = useCallback((updatedFilter: FilterValues<Extract<keyof M, string>> | undefined) => {
+        if (forceFilter) {
+            console.warn("Filter is not compatible with the force filter. Ignoring filter");
+            return;
+        }
+        if (updatedFilter && Object.keys(updatedFilter).length === 0) {
+            setFilterValues(undefined);
+        } else {
+            setFilterValues(updatedFilter);
+        }
+    }, [forceFilter]);
+
+    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: resolvedPath,
+                                entity,
+                                context
+                            })));
+                } catch (e: any) {
+                    console.error(e);
+                }
+            }
+            setDataLoading(false);
+            setDataLoadingError(undefined);
+            setRawData(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);
+            setRawData([]);
+            setDataLoadingError(error);
+        };
+
+        if (dataSource.listenCollection) {
+            return dataSource.listenCollection<M>({
+                path: resolvedPath,
+                collection,
+                onUpdate: onEntitiesUpdate,
+                onError,
+                searchString,
+                filter: filterValues,
+                limit: itemCount,
+                startAfter: undefined,
+                orderBy: sortByProperty,
+                order: currentSort
+            });
+        } else {
+            dataSource.fetchCollection<M>({
+                path: resolvedPath,
+                collection,
+                searchString,
+                filter: filterValues,
+                limit: itemCount,
+                startAfter: undefined,
+                orderBy: sortByProperty,
+                order: currentSort
+            })
+                .then(onEntitiesUpdate)
+                .catch(onError);
+            return () => {
+            };
+        }
+    }, [resolvedPath, itemCount, currentSort, sortByProperty, filterValues, searchString]);
+
+    const orderedData = useDataOrder({
+        data: rawData,
+        entitiesDisplayedFirst
+    });
+
+    // hack to fix Firestore listeners firing with incomplete data
+    const data = useDebouncedData(orderedData, {
+        filterValues,
+        sortBy,
+        searchString,
+        lastDeleteTimestamp
+    });
+
+    return {
+        data,
+        dataLoading,
+        noMoreToLoad,
+        dataLoadingError,
+        filterValues,
+        setFilterValues: updateFilterValues,
+        sortBy,
+        setSortBy,
+        searchString,
+        setSearchString,
+        clearFilter,
+        itemCount,
+        setItemCount,
+        initialScroll: collectionScroll?.scrollOffset,
+        onScroll,
+        paginationEnabled,
+        pageSize,
+        checkFilterCombination,
+        popupCell,
+        setPopupCell
+    }
+}
+
+function useUpdateUrl<M extends Record<string, any> = any>(
+    filterValues: FilterValues<Extract<keyof M, string>> | undefined,
+    sortBy: [Extract<keyof M, string>, "asc" | "desc"] | undefined,
+    searchString: string | undefined,
+    updateUrl: boolean | undefined
+) {
+
+    useEffect(() => {
+        if (updateUrl) {
+            const newUrl = encodeFilterAndSort(filterValues, sortBy);
+            const search = searchString ? `&search=${encodeURIComponent(searchString)}` : "";
+            const state = `${newUrl}${search}`;
+            const hash = window.location.hash;
+            if (state === "")
+                window.history.replaceState({}, "", `${window.location.pathname}${hash}`);
+            else
+                window.history.replaceState({}, "", `?${state}${hash}`);
+        }
+    }, [filterValues, sortBy, searchString, updateUrl]);
+}
+
+function encodeFilterAndSort(filterValues?: FilterValues<string>, sortBy?: [string, "asc" | "desc"] | undefined) {
+    const entries: Record<string, string> = {};
+    if (sortBy) {
+        entries["__sort"] = encodeURIComponent(sortBy[0]);
+        entries["__sort_order"] = encodeURIComponent(sortBy[1]);
+    }
+    if (filterValues) {
+        Object.entries(filterValues).forEach(([key, value]) => {
+            if (value) {
+                const [op, val] = value;
+                let encodedValue: any = val;
+                try {
+                    if (typeof val === "object") {
+                        if (val instanceof Date) {
+                            encodedValue = val.toISOString();
+                        } else if (Array.isArray(val)) {
+                            encodedValue = JSON.stringify(val, (key, value) => {
+                                if (value instanceof EntityReference) {
+                                    return encodeRef(value);
+                                }
+                                return value;
+                            });
+                        } else if (val instanceof EntityReference) {
+                            encodedValue = encodeRef(val);
+                        }
+                    }
+                } catch (e) {
+                    encodedValue = val;
+                }
+                if (encodedValue !== undefined) {
+                    entries[encodeURIComponent(`${key}_op`)] = encodeURIComponent(op);
+                    entries[encodeURIComponent(`${key}_value`)] = encodedValue ? encodeURIComponent(encodedValue.toString()) : "null";
+                }
+            }
+        });
+    }
+    if (!Object.keys(entries).length) {
+        return "";
+    }
+    return Object.entries(entries).map(([key, value]) => `${key}=${value}`).join("&");
+}
+
+function parseFilterAndSort<M>(search: string): {
+    filterValues: FilterValues<string> | undefined,
+    sortBy?: [Extract<keyof M, string>, "asc" | "desc"]
+} {
+    const entries = new URLSearchParams(search);
+    const filterValues: FilterValues<string> = {};
+    let sortBy: [string, "asc" | "desc"] | undefined = undefined;
+    entries.forEach((value, key) => {
+        if (key === "__sort") {
+            sortBy = [decodeURIComponent(value), entries.get("__sort_order") as "asc" | "desc"];
+        } else if (key.endsWith("_op")) {
+            const field = key.replace("_op", "");
+            const filterOp = decodeURIComponent(value) as WhereFilterOp;
+            const filterValStr = entries.get(`${field}_value`);
+            if (filterValStr !== null) {
+                filterValues[field] = [filterOp, decodeString(filterValStr)];
+            }
+        }
+    });
+
+    return {
+        filterValues: Object.keys(filterValues).length ? filterValues : undefined,
+        sortBy
+    }
+}
+
+function isDate(dateString: string): boolean {
+    // Define a regex pattern that matches the exact date format: 2025-01-07T23:00:00.000Z
+    const regexPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+    // Test the dateString against the regex pattern
+    if (!regexPattern.test(dateString)) {
+        return false;
+    }
+
+    // If the regex matches, further validate if it is a valid UTC date
+    const date = new Date(dateString);
+    return date.toISOString() === dateString;
+}
+
+function encodeRef(val: EntityReference) {
+    return `ref::${val.path}/${val.id}`;
+}
+
+function decodeString(val: string): EntityReference | Date | string {
+    let parsedFilterVal: any = val;
+    if (isDate(val)) {
+        try {
+            parsedFilterVal = new Date(val);
+        } catch (e) {
+            // ignore
+        }
+    }
+    if (typeof parsedFilterVal === "string") {
+        try {
+            parsedFilterVal = JSON.parse(parsedFilterVal, (key, value) => {
+                if (typeof value === "string" && value.startsWith("ref::")) {
+                    const [path, id] = value.substring(5).split("/");
+                    return new EntityReference(id, path);
+                }
+                return value;
+            });
+        } catch (e) {
+            // ignore
+        }
+    }
+
+    if (typeof parsedFilterVal === "string" && parsedFilterVal.startsWith("ref::")) {
+        const [path, id] = parsedFilterVal.substring(5).split("/");
+        return new EntityReference(id, path);
+    }
+    return parsedFilterVal;
+}

package/src/components/common/useDebouncedCallback.tsx

@@ -0,0 +1,20 @@
+import { useCallback, useRef } from "react";
+
+export function useDebounceCallback<T extends (...args: any[]) => any>(
+    callback?: T,
+    delay?: number
+): T {
+    const timeoutRef = useRef<number | null>(null);
+
+    const debouncedCallback = useCallback((...args: Parameters<T>) => {
+        if (timeoutRef.current !== null) {
+            clearTimeout(timeoutRef.current);
+        }
+
+        timeoutRef.current = window.setTimeout(() => {
+            callback?.(...args);
+        }, delay ?? 200);
+    }, [callback, delay]);
+
+    return debouncedCallback as T;
+}

package/src/components/common/useScrollRestoration.tsx

@@ -0,0 +1,68 @@
+import { Entity, FilterValues } from "../../types";
+
+const collectionScrollCache = new Map<string, { scrollOffset: number, data: Entity<any>[] }>();
+
+export type ScrollRestorationController = {
+
+    getCollectionScroll: (fullPath: string,
+                          filters?: FilterValues<any>) => {
+        scrollOffset: number,
+        data: Entity<any>[]
+    } | undefined;
+
+    updateCollectionScroll: (props: {
+        fullPath: string,
+        scrollOffset: number,
+        filters?: FilterValues<any>;
+        data: Entity<any>[]
+    }) => void;
+
+}
+
+export function useScrollRestoration(): ScrollRestorationController {
+
+    const updateCollectionScroll = ({
+                                        fullPath,
+                                        filters,
+                                        scrollOffset,
+                                        data
+                                    }: {
+        fullPath: string;
+        filters?: FilterValues<any>;
+        sort?: [string, "asc" | "desc"];
+        scrollOffset: number;
+        data: Entity<any>[]
+    }) => {
+        collectionScrollCache.set(
+            createCacheKey(fullPath, filters),
+            {
+                scrollOffset,
+                data
+            })
+    }
+
+    const getCollectionScroll = (fullPath: string,
+                                 filters?: FilterValues<any>) => {
+        return collectionScrollCache.get(createCacheKey(fullPath, filters));
+    }
+
+    return {
+        getCollectionScroll,
+        updateCollectionScroll
+    }
+}
+
+function createCacheKey(fullPath: string, filters?: FilterValues<any>) {
+
+    if (!filters) {
+        return fullPath;
+    }
+
+    // codify the filters into a url friendly string
+    const filtersString = filters ? Object.keys(filters).map(key => {
+        const value = JSON.stringify(filters[key]);
+        return `${key}=${value}`;
+    }).join("&") : "";
+
+    return `${fullPath}?${filtersString}`;
+}

package/src/components/common/useTableSearchHelper.ts

@@ -1,7 +1,7 @@
 import { useState } from "react";
 
 import { EntityCollection } from "../../types";
-import { useCustomizationController, useFireCMSContext } from "../../hooks";
+import { useCustomizationController, useDataSource, useFireCMSContext } from "../../hooks";
 
 export interface UseTableSearchHelperParams<M extends Record<string, any>> {
     collection: EntityCollection<M>;
@@ -9,27 +9,58 @@ export interface UseTableSearchHelperParams<M extends Record<string, any>> {
     parentCollectionIds?: string[];
 }
 
-export function useTableSearchHelper<M extends Record<string, any>>({ collection, fullPath, parentCollectionIds }: UseTableSearchHelperParams<M>) {
+export function useTableSearchHelper<M extends Record<string, any>>({
+                                                                        collection,
+                                                                        fullPath,
+                                                                        parentCollectionIds
+                                                                    }: UseTableSearchHelperParams<M>) {
 
     const context = useFireCMSContext();
     const customizationController = useCustomizationController();
+    const dataSource = useDataSource();
 
     const [textSearchLoading, setTextSearchLoading] = useState<boolean>(false);
     const [textSearchInitialised, setTextSearchInitialised] = useState<boolean>(false);
+
     let onTextSearchClick: (() => void) | undefined;
     let textSearchEnabled = Boolean(collection.textSearchEnabled);
-    if (customizationController?.plugins) {
-        const addTextSearchClickListener = customizationController.plugins?.find(p => Boolean(p.collectionView?.onTextSearchClick));
+
+    const props = {
+        context,
+        path: fullPath,
+        databaseId: collection.databaseId,
+        collection,
+        parentCollectionIds
+    };
+
+    const searchBlocked = customizationController.plugins?.find(p => {
+        return p.collectionView?.blockSearch?.(props);
+    });
+
+    const addTextSearchClickListener = Boolean(dataSource?.initTextSearch) || customizationController.plugins?.find(p => Boolean(p.collectionView?.onTextSearchClick));
+
+    if (addTextSearchClickListener) {
 
         onTextSearchClick = addTextSearchClickListener
             ? () => {
                 setTextSearchLoading(true);
-                Promise.all(customizationController.plugins?.map(p => {
-                    if (p.collectionView?.onTextSearchClick)
-                        return p.collectionView.onTextSearchClick({ context, path: fullPath, collection, parentCollectionIds });
-                    return Promise.resolve(true);
-                }) as Promise<boolean>[])
-                    .then((res) => {
+                const promises: Promise<boolean>[] = [];
+                if (dataSource?.initTextSearch && !searchBlocked) {
+                    promises.push(dataSource.initTextSearch(props));
+                }
+                if (searchBlocked) {
+                    customizationController.plugins?.forEach(p => {
+                        if (p.collectionView?.onTextSearchClick)
+                            promises.push(p.collectionView.onTextSearchClick({
+                                context,
+                                path: fullPath,
+                                collection,
+                                parentCollectionIds
+                            }));
+                    })
+                }
+                return Promise.all(promises)
+                    .then((res: boolean[]) => {
                         if (res.every(Boolean)) setTextSearchInitialised(true);
                     })
                     .finally(() => setTextSearchLoading(false));
@@ -39,9 +70,19 @@ export function useTableSearchHelper<M extends Record<string, any>>({ collection
         customizationController.plugins?.forEach(p => {
             if (!textSearchEnabled)
                 if (p.collectionView?.showTextSearchBar) {
-                    textSearchEnabled = p.collectionView.showTextSearchBar({ context, path: fullPath, collection, parentCollectionIds });
+                    textSearchEnabled = p.collectionView.showTextSearchBar({
+                        context,
+                        path: fullPath,
+                        collection,
+                        parentCollectionIds
+                    });
                 }
         })
     }
-    return { textSearchLoading, textSearchInitialised, onTextSearchClick, textSearchEnabled };
+    return {
+        textSearchLoading,
+        textSearchInitialised,
+        onTextSearchClick,
+        textSearchEnabled
+    };
 }

package/src/components/index.tsx

@@ -13,24 +13,28 @@ export * from "./common";
 
 export * from "./HomePage";
 export * from "./SelectableTable/SelectableTable";
+export * from "./SelectableTable/SelectableTableContext";
 export * from "./EntityCollectionView/EntityCollectionView";
 export * from "./EntityCollectionView/EntityCollectionViewActions";
 export * from "./EntityCollectionView/useSelectionController";
 
 export * from "./PropertyConfigBadge";
+export * from "./PropertyIdCopyTooltip";
 
 export * from "./EntityCollectionTable";
 export * from "./NotFoundPage";
 
 export * from "./VirtualTable";
 export * from "./ErrorBoundary";
-export * from "./DeleteConfirmationDialog";
+export * from "./ConfirmationDialog";
 
 export * from "./FireCMSLogo";
 
-export * from "./FireCMSAppBar";
+export * from "../core/DefaultAppBar";
 
 export * from "./ArrayContainer";
 export * from "./ReferenceWidget";
 export * from "./SearchIconsView";
 export * from "./FieldCaption";
+
+export * from "./EntityPreview";