@firecms/entity_history 3.0.0-canary.237

package/dist/useEntityHistoryPlugin.d.ts

@@ -0,0 +1,17 @@
+import { FireCMSPlugin, User } from "@firecms/core";
+/**
+ *
+ */
+export declare function useEntityHistoryPlugin(props?: EntityHistoryPluginProps): FireCMSPlugin<any, any, any, EntityHistoryPluginProps>;
+export type EntityHistoryPluginProps = {
+    /**
+     * If true, the history view will be enabled to all collections by default.
+     * Each collection can override this value by setting the `history` property.
+     */
+    defaultEnabled?: boolean;
+    /**
+     * Function to get the user object from the uid.
+     * @param uid
+     */
+    getUser?: (uid: string) => User | null;
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@firecms/entity_history",
+  "type": "module",
+  "version": "3.0.0-canary.237",
+  "access": "public",
+  "main": "./dist/index.umd.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "source": "src/index.ts",
+  "dependencies": {
+    "@firecms/core": "^3.0.0-canary.237",
+    "@firecms/formex": "^3.0.0-canary.237",
+    "@firecms/ui": "^3.0.0-canary.237"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.umd.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "prepublishOnly": "run-s build",
+    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
+    "test": "jest"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "babel-jest": "^29.7.0",
+    "babel-plugin-react-compiler": "beta",
+    "eslint-plugin-react-compiler": "beta",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3",
+    "vite": "^5.4.14"
+  },
+  "jest": {
+    "transform": {
+      "^.+\\.tsx?$": "ts-jest"
+    },
+    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
+    "moduleFileExtensions": [
+      "ts",
+      "tsx",
+      "js",
+      "jsx",
+      "json",
+      "node"
+    ],
+    "moduleNameMapper": {
+      "\\.(css|less)$": "<rootDir>/test/__mocks__/styleMock.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "20e10b4e0cd4b6a2f2831b219ce43a6d09047a54"
+}

package/src/HistoryControllerProvider.tsx

@@ -0,0 +1,40 @@
+import React, { PropsWithChildren, useContext } from "react";
+import equal from "react-fast-compare"
+
+import { User } from "@firecms/core";
+
+export type HistoryConfigController = {
+    /**
+     * Function to get a user by uid.
+     * @param uid
+     */
+    getUser?: (uid: string) => User | null;
+}
+
+export const HistoryControllerContext = React.createContext<HistoryConfigController>({} as any);
+export const useHistoryController = (): HistoryConfigController => useContext(HistoryControllerContext);
+
+
+export interface HistoryControllerProviderProps {
+
+    getUser?: (uid: string) => User | null;
+
+}
+
+export const HistoryControllerProvider = React.memo(
+    function HistoryControllerProvider({
+                                           children,
+                                           getUser,
+                                       }: PropsWithChildren<HistoryControllerProviderProps>) {
+
+        return (
+            <HistoryControllerContext.Provider
+                value={{
+                    getUser,
+                }}>
+
+                {children}
+
+            </HistoryControllerContext.Provider>
+        );
+    }, equal);

package/src/components/EntityHistoryEntry.tsx

@@ -0,0 +1,161 @@
+import * as React from "react";
+
+import { Chip, cls, defaultBorderMixin, IconButton, KeyboardTabIcon, Tooltip, Typography } from "@firecms/ui";
+import {
+    Entity,
+    EntityCollection,
+    getPropertyInPath,
+    getValueInPath,
+    PreviewSize,
+    PropertyPreview,
+    resolveCollection,
+    ResolvedProperty,
+    SkeletonPropertyComponent,
+    useAuthController,
+    useCustomizationController,
+    useNavigationController,
+    useSideEntityController
+} from "@firecms/core";
+import { useHistoryController } from "../HistoryControllerProvider";
+import { UserChip } from "./UserChip";
+
+export type EntityPreviewProps = {
+    size: PreviewSize,
+    actions?: React.ReactNode,
+    collection?: EntityCollection,
+    hover?: boolean;
+    previewKeys?: string[],
+    disabled?: boolean,
+    entity: Entity<any>,
+    onClick?: (e: React.SyntheticEvent) => void;
+};
+
+/**
+ * This view is used to display a preview of an entity.
+ * It is used by default in reference fields and whenever a reference is displayed.
+ */
+export function EntityHistoryEntry({
+                                       actions,
+                                       disabled,
+                                       hover,
+                                       collection: collectionProp,
+                                       previewKeys,
+                                       onClick,
+                                       size,
+                                       entity
+                                   }: EntityPreviewProps) {
+
+    const authController = useAuthController();
+    const customizationController = useCustomizationController();
+
+    const navigationController = useNavigationController();
+    const sideEntityController = useSideEntityController();
+
+    const collection = collectionProp ?? navigationController.getCollection(entity.path);
+    const updatedOn = entity.values?.["__metadata"]?.["updated_on"];
+    if (!collection) {
+        throw Error(`Couldn't find the corresponding collection view for the path: ${entity.path}`);
+    }
+
+    const updatedBy = entity.values?.["__metadata"]?.["updated_by"];
+    const { getUser } = useHistoryController();
+    const user = getUser?.(updatedBy);
+
+    const resolvedCollection = React.useMemo(() => resolveCollection({
+        collection,
+        path: entity.path,
+        values: entity.values,
+        propertyConfigs: customizationController.propertyConfigs,
+        authController
+    }), [collection]);
+
+    return <div className={"w-full flex flex-col gap-2 mt-4"}>
+        <div className={"ml-4 flex items-center gap-4"}>
+            <Typography variant={"body2"} color={"secondary"}>{updatedOn.toLocaleString()}</Typography>
+            {!user && updatedBy && <Chip size={"small"}>{updatedBy}</Chip>}
+            {user && <UserChip user={user}/>}
+        </div>
+        <div
+            className={cls(
+                "bg-white dark:bg-surface-900",
+                "min-h-[42px]",
+                "w-full",
+                "items-center",
+                hover ? "hover:bg-surface-accent-50 dark:hover:bg-surface-800 group-hover:bg-surface-accent-50 dark:group-hover:bg-surface-800" : "",
+                size === "small" ? "p-1" : "px-2 py-1",
+                "flex border rounded-lg",
+                onClick ? "cursor-pointer" : "",
+                defaultBorderMixin
+            )}>
+
+
+            {actions}
+
+            {entity &&
+                <Tooltip title={"See details for this revision"}
+                         className={"my-2 grow-0 shrink-0 self-start"}>
+                    <IconButton
+                        color={"inherit"}
+                        className={""}
+                        onClick={(e) => {
+
+                            sideEntityController.open({
+                                entityId: entity.id,
+                                path: entity.path,
+                                allowFullScreen: false,
+                                collection: {
+                                    ...collection,
+                                    subcollections: undefined,
+                                    entityViews: undefined,
+                                    permissions: {
+                                        create: false,
+                                        delete: false,
+                                        edit: false,
+                                        read: true
+                                    }
+                                },
+                                updateUrl: true
+                            });
+                        }}>
+                        <KeyboardTabIcon/>
+                    </IconButton>
+                </Tooltip>}
+
+            <div className={"flex flex-col grow w-full m-1 shrink min-w-0"}>
+
+                {previewKeys && previewKeys.map((key) => {
+                    const childProperty = getPropertyInPath(resolvedCollection.properties, key);
+                    if (!childProperty) return null;
+
+                    const valueInPath = getValueInPath(entity.values, key);
+                    return (
+                        <div key={"ref_prev_" + key}
+                             className="flex w-full my-1 items-center">
+                            <Typography variant={"caption"}
+                                        color={"secondary"}
+                                        className="min-w-[140px] md:min-w-[200px] w-1/5 pr-8 overflow-hidden text-ellipsis text-right">
+                                {key}
+                            </Typography>
+                            <div className="w-4/5">
+                                {
+                                    entity
+                                        ? <PropertyPreview
+                                            propertyKey={key as string}
+                                            value={valueInPath}
+                                            property={childProperty as ResolvedProperty}
+                                            size={"small"}/>
+                                        : <SkeletonPropertyComponent
+                                            property={childProperty as ResolvedProperty}
+                                            size={"small"}/>
+                                }
+                            </div>
+                        </div>
+                    );
+                })}
+
+            </div>
+
+        </div>
+    </div>
+}
+

package/src/components/EntityHistoryView.tsx

@@ -0,0 +1,222 @@
+import { useEffect, useRef, useState } from "react";
+import {
+    ConfirmationDialog,
+    Entity,
+    EntityCustomViewParams,
+    useAuthController,
+    useDataSource,
+    useSnackbarController
+} from "@firecms/core";
+import { cls, HistoryIcon, IconButton, Label, Tooltip, Typography } from "@firecms/ui";
+import { EntityHistoryEntry } from "./EntityHistoryEntry";
+
+export function EntityHistoryView({
+                                      entity,
+                                      collection,
+                                      formContext
+                                  }: EntityCustomViewParams) {
+
+    const authController = useAuthController();
+    const snackbarController = useSnackbarController();
+    const dirty = formContext?.formex.dirty;
+
+    const dataSource = useDataSource();
+    const pathAndId = entity ? entity?.path + "/" + entity?.id : undefined;
+
+    const [revertVersion, setRevertVersion] = useState<Entity | undefined>(undefined);
+    const [revisions, setRevisions] = useState<Entity[]>([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [hasMore, setHasMore] = useState(true);
+
+    const PAGE_SIZE = 5;
+    const [limit, setLimit] = useState(PAGE_SIZE);
+
+    const containerRef = useRef<HTMLDivElement>(null);
+    const observerRef = useRef<IntersectionObserver | null>(null);
+    const loadMoreRef = useRef<HTMLDivElement>(null);
+
+    // Load revisions with the current limit
+    useEffect(() => {
+        if (!pathAndId) return;
+
+        setIsLoading(true); // Set loading true when fetching starts
+        const listener = dataSource.listenCollection?.({
+            path: pathAndId + "/__history",
+            order: "desc",
+            orderBy: "__metadata.updated_on",
+            limit: limit,
+            startAfter: undefined,
+            onUpdate: (entities) => {
+                setRevisions(entities);
+                setHasMore(entities.length === limit && entities.length >= PAGE_SIZE); // Ensure we fetched a full page to consider hasMore
+                setIsLoading(false);
+            },
+            onError: (error) => {
+                console.error("Error fetching history:", error);
+                setIsLoading(false);
+                setHasMore(false); // Stop trying if there's an error
+            }
+        });
+        return () => {
+            if (typeof listener === "function") {
+                listener();
+            }
+        };
+    }, [pathAndId, limit, dataSource]);
+
+    // Setup intersection observer for infinite scroll
+    useEffect(() => {
+        const currentContainer = containerRef.current;
+        const currentLoadMore = loadMoreRef.current;
+
+        // Conditions for active observation
+        if (!currentContainer || !currentLoadMore || !hasMore || isLoading) {
+            // If we shouldn't be observing, ensure any existing observer is disconnected
+            if (observerRef.current) {
+                observerRef.current.disconnect();
+                observerRef.current = null;
+            }
+            return;
+        }
+
+        // Options for the IntersectionObserver
+        const options = {
+            root: currentContainer,
+            rootMargin: "0px 0px 200px 0px", // Trigger 200px before the sentinel is at the bottom edge
+            threshold: 0.01 // Trigger if even a small part is visible within the rootMargin
+        };
+
+        // The callback for when the sentinel's intersection state changes
+        const handleObserver = (entries: IntersectionObserverEntry[]) => {
+            const target = entries[0];
+            if (target.isIntersecting && hasMore && !isLoading) {
+                // No need to setIsLoading(true) here, it's done in the data fetching useEffect
+                setLimit(prev => prev + PAGE_SIZE);
+            }
+        };
+
+        const observer = new IntersectionObserver(handleObserver, options);
+        observer.observe(currentLoadMore);
+        observerRef.current = observer; // Store the new observer
+
+        // Cleanup function for this effect instance
+        return () => {
+            observer.disconnect(); // Disconnect the observer created in *this* effect run
+            if (observerRef.current === observer) {
+                observerRef.current = null;
+            }
+        };
+        // Re-run if hasMore, isLoading changes, or if revisions.length changes (which might make loadMoreRef available/unavailable)
+    }, [hasMore, isLoading, revisions.length]);
+
+    if (!entity) {
+        return <div className="flex items-center justify-center h-full">
+            <Label>History is only available for existing entities</Label>
+        </div>
+    }
+
+    function doRevert(revertVersion: Entity) {
+        const revertValues = {
+            ...revertVersion.values,
+            __metadata: {
+                ...revertVersion.values?.["__metadata"],
+                reverted: true,
+                updated_on: new Date(),
+                updated_by: authController.user?.uid ?? null,
+            }
+        };
+        return dataSource.saveEntity({
+            path: revertVersion.path,
+            entityId: revertVersion.id,
+            values: revertValues,
+            collection,
+            status: "existing"
+        }).then(() => {
+            formContext.formex.resetForm({
+                values: revertVersion.values
+            });
+            setRevertVersion(undefined);
+            snackbarController.open({
+                message: "Reverted version",
+                type: "info"
+            });
+            }
+        ).catch((error) => {
+            console.error("Error reverting entity:", error);
+            snackbarController.open({
+                message: "Error reverting entity",
+                type: "error"
+            });
+        });
+
+    }
+
+    return <div
+        ref={containerRef}
+        className={cls("relative flex-1 h-full overflow-auto w-full flex flex-col gap-4 p-8")}>
+        <div className="flex flex-col gap-2 max-w-6xl mx-auto w-full">
+
+            <Typography variant={"h5"} className={"mt-24 ml-4"}>
+                History
+            </Typography>
+
+            {revisions.length === 0 && <>
+                <Label className={"ml-4 mt-8"}>
+                    No history available
+                </Label>
+                <Typography variant={"caption"} className={"ml-4"}>
+                    When you save an entity, a new version is created and stored in the history.
+                </Typography>
+            </>}
+
+            {revisions.map((revision, index) => {
+                const previewKeys = revision.values?.["__metadata"]?.["changed_fields"];
+                return <div key={index} className="flex flex-cols gap-2 w-full">
+                    <EntityHistoryEntry size={"large"}
+                                        entity={revision}
+                                        collection={collection}
+                                        previewKeys={previewKeys}
+                                        actions={
+                                            <Tooltip title={"Revert to this version"}
+                                                     className={"m-2 grow-0 self-start"}>
+                                                <IconButton
+                                                    onClick={() => {
+                                                        if (dirty) {
+                                                            snackbarController.open({
+                                                                message: "Please save or discard your changes before reverting",
+                                                                type: "warning"
+                                                            });
+                                                        } else {
+                                                            setRevertVersion(revision);
+                                                        }
+                                                    }}>
+                                                    <HistoryIcon/>
+                                                </IconButton>
+                                            </Tooltip>}
+                    />
+                </div>
+            })}
+
+            {/* Load more sentinel element */}
+            {revisions.length > 0 && (
+                <div
+                    ref={loadMoreRef}
+                    className="py-4 text-center"
+                >
+                    {isLoading && <Label>Loading more...</Label>}
+                    {!hasMore && revisions.length > PAGE_SIZE && <Label>No more history available</Label>}
+                </div>
+            )}
+        </div>
+
+        <ConfirmationDialog open={Boolean(revertVersion)}
+                            onAccept={function (): void {
+                                if (!revertVersion) return;
+                                doRevert(revertVersion);
+                            }}
+                            onCancel={function (): void {
+                                setRevertVersion(undefined);
+                            }}
+                            title={<Typography variant={"subtitle2"}>Revert data to this version?</Typography>}/>
+    </div>
+}

package/src/components/UserChip.tsx

@@ -0,0 +1,15 @@
+import { User } from "@firecms/core";
+import { Chip, Tooltip } from "@firecms/ui";
+
+export function UserChip({ user }: { user: User }) {
+    return (
+        <Tooltip title={user.email ?? user.uid}>
+            <Chip size={"small"} className={"flex items-center"}>
+                {user.photoURL && <img
+                    className={"rounded-full w-6 h-6 mr-2"}
+                    src={user.photoURL} alt={user.displayName ?? "User picture"}/>}
+                <span>{user.displayName ?? user.email ?? user.uid}</span>
+            </Chip>
+        </Tooltip>
+    );
+}

package/src/entity_history_callbacks.ts

@@ -0,0 +1,99 @@
+import { EntityCallbacks } from "@firecms/core";
+import equal from "react-fast-compare"
+
+export const entityHistoryCallbacks: EntityCallbacks = {
+    onSaveSuccess: async (props) => {
+
+        const changedFields = props.previousValues ? findChangedFields(props.previousValues, props.values) : null;
+        const uid = props.context.authController.user?.uid;
+        props.context.dataSource.saveEntity({
+            path: props.path + "/" + props.entityId + "/__history",
+            values: {
+                ...props.values,
+                __metadata: {
+                    changed_fields: changedFields,
+                    updated_on: new Date(),
+                    updated_by: uid,
+                }
+            },
+            status: "new"
+        }).then(() => {
+            console.debug("History saved for", props.path, props.entityId);
+        });
+    }
+}
+
+function findChangedFields<M extends object>(oldValues: M, newValues: M, prefix: string = ""): string[] {
+    const changedFields: string[] = [];
+
+    // Handle null/undefined cases
+    if (equal(oldValues, newValues)) return changedFields;
+    if (!oldValues || !newValues) return [prefix || "."];
+
+    // Get all unique keys from both objects
+    const allKeys = new Set([
+        ...Object.keys(oldValues),
+        ...Object.keys(newValues)
+    ]);
+
+    for (const key of allKeys) {
+        const oldValue = oldValues[key as keyof M];
+        const newValue = newValues[key as keyof M];
+        const currentPath = prefix ? `${prefix}.${key}` : key;
+
+        // If key exists only in one object
+        if ((key in oldValues) !== (key in newValues)) {
+            changedFields.push(currentPath);
+            continue;
+        }
+
+        // If values are identical (deep equality)
+        if (equal(oldValue, newValue)) continue;
+
+        // Handle arrays
+        if (Array.isArray(oldValue) && Array.isArray(newValue)) {
+            if (oldValue.length !== newValue.length) {
+                changedFields.push(currentPath);
+            } else {
+                // Check if any array element changed
+                for (let i = 0; i < oldValue.length; i++) {
+                    if (
+                        typeof oldValue[i] === "object" && oldValue[i] !== null &&
+                        typeof newValue[i] === "object" && newValue[i] !== null
+                    ) {
+                        const nestedChanges = findChangedFields(
+                            oldValue[i] as object,
+                            newValue[i] as object,
+                            `${currentPath}[${i}]`
+                        );
+                        if (nestedChanges.length > 0) {
+                            changedFields.push(currentPath);
+                            break;
+                        }
+                    } else if (!equal(oldValue[i], newValue[i])) {
+                        changedFields.push(currentPath);
+                        break;
+                    }
+                }
+            }
+        }
+        // Handle nested objects
+        else if (
+            typeof oldValue === "object" && oldValue !== null &&
+            typeof newValue === "object" && newValue !== null
+        ) {
+            const nestedChanges = findChangedFields(
+                oldValue as object,
+                newValue as object,
+                currentPath
+            );
+            changedFields.push(...nestedChanges);
+        }
+        // Handle primitives
+        else {
+            changedFields.push(currentPath);
+        }
+    }
+
+    return changedFields;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./useEntityHistoryPlugin";
+export * from "./HistoryControllerProvider";