@firecms/entity_history 3.0.0-canary.237

package/LICENSE

@@ -0,0 +1,114 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Firecms S.L.
+Licensed Work:        Firecms CMS packages:
+                      cli
+                      collection_editor
+                      collection_editor_firebase
+                      data_enhancement
+                      data_export
+                      data_export
+                      editor
+                      firecms_cloud
+                      schema_inference
+                      user_management
+
+                      The Licensed Work is (c) 2024 Firecms S.L
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you may not use the Licensed Work for a CMS Data Enhancement
+                      Service.
+
+                      A “CMS package” is a commercial offering that
+                      allows third parties (other than your employees and
+                      contractors) to access the functionality of the
+                      Licensed Work by using software to extend the base features of
+                      content management system controlled by such third parties.
+
+Change Date:         Four years from the date the Licensed Work is published.
+
+Change License:      MIT
+
+For information about alternative licensing arrangements for the Software,
+please visit: https://firecms.co
+
+Notice
+
+The Business Source License (this document, or the “License”) is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+“Business Source License” is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,124 @@
+# FireCMS Entity History Plugin
+
+This plugin adds a history view to your entities in FireCMS. It allows you to track changes made to entities over time,
+showing who made the change and when.
+
+The document history will be stored in a subcollection called `__history` within the entity's document.
+Each change will be recorded as a new document in this subcollection. 
+
+## Installation
+
+```bash
+npm install @firecms/entity_history
+# or
+yarn add @firecms/entity_history
+```
+
+## Features
+
+- Adds a "History" tab to entity detail views.
+- Displays a log of changes for each entity.
+- Can be enabled globally or on a per-collection basis.
+- Allows customization of user display in the history log.
+
+## Basic Usage
+
+To use the plugin, import `useEntityHistoryPlugin` and add it to your `FirebaseCMSApp` plugins array.
+
+```tsx
+import React from "react";
+import { FirebaseCMSApp } from "@firecms/core";
+import { useEntityHistoryPlugin } from "@firecms/entity_history";
+
+
+export default function App() {
+
+    // Basic setup with default options
+    const entityHistoryPlugin = useEntityHistoryPlugin();
+
+    return <FirebaseCMSApp
+        name={"My Online Shop"}
+        plugins={[entityHistoryPlugin]}
+        authentication={myAuthenticator}
+        collections={myCollections}
+        firebaseConfig={firebaseConfig}
+    />;
+}
+```
+
+By default, the history feature is not enabled for any collection. You need to enable it explicitly in your collection
+configuration:
+
+```tsx
+import { buildCollection } from "@firecms/core";
+
+const productsCollection = buildCollection({
+    name: "Products",
+    path: "products",
+    properties: {
+        name: {
+            name: "Name",
+            dataType: "string"
+        }
+        // ...other properties
+    },
+    history: true // Enable history for this collection
+});
+```
+
+## Advanced Configuration
+
+You can customize the plugin's behavior by passing props to `useEntityHistoryPlugin`.
+If you are using the user management plugin, you can provide a function to resolve user details from a UID.
+You can also pass your own custom `getUser` function to fetch user details.
+
+```tsx
+import { useEntityHistoryPlugin } from "@firecms/entity_history";
+import { User } from "@firecms/core";
+
+export function App() {
+
+    // ...
+
+    const userManagement = useBuildUserManagement({
+        dataSourceDelegate: firestoreDelegate,
+        authController: authController
+    });
+
+    const entityHistoryPlugin = useEntityHistoryPlugin({
+        // Enable history for all collections by default
+        // This can be overridden by setting `history: false` in a specific collection
+        defaultEnabled: true,
+    
+        // Provide a function to resolve user details from a UID
+        getUser: userManagement.getUser
+    });
+    
+    // ...
+}
+```
+
+## Configuration Options
+
+| Option           | Type                            | Description                                                                                                                                      |
+|------------------|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `defaultEnabled` | `boolean`                       | If `true`, the history view will be enabled for all collections by default. Each collection can override this by setting its `history` property. |
+| `getUser`        | `(uid: string) => User \| null` | Optional function to get the user object (display name, photo, etc.) from a user ID to display in the history log.                               |
+
+## Collection Configuration
+
+To enable or disable history for a specific collection, set the `history` property in the collection configuration:
+
+```tsx
+const sampleCollection = buildCollection({
+    // ...
+    history: true // or false
+});
+```
+
+## Additional Notes
+
+- The plugin relies on callbacks to record entity changes. Ensure that your data persistence logic correctly triggers
+  these callbacks.
+- The `getUser` function is crucial for displaying meaningful user information in the history log. If not provided, only
+  user IDs might be shown.

package/dist/HistoryControllerProvider.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+import { User } from "@firecms/core";
+export type HistoryConfigController = {
+    /**
+     * Function to get a user by uid.
+     * @param uid
+     */
+    getUser?: (uid: string) => User | null;
+};
+export declare const HistoryControllerContext: React.Context<HistoryConfigController>;
+export declare const useHistoryController: () => HistoryConfigController;
+export interface HistoryControllerProviderProps {
+    getUser?: (uid: string) => User | null;
+}
+export declare const HistoryControllerProvider: React.NamedExoticComponent<React.PropsWithChildren<HistoryControllerProviderProps>>;

package/dist/components/EntityHistoryEntry.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import { Entity, EntityCollection, PreviewSize } from "@firecms/core";
+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 declare function EntityHistoryEntry({ actions, disabled, hover, collection: collectionProp, previewKeys, onClick, size, entity }: EntityPreviewProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/EntityHistoryView.d.ts

@@ -0,0 +1,2 @@
+import { EntityCustomViewParams } from "@firecms/core";
+export declare function EntityHistoryView({ entity, collection, formContext }: EntityCustomViewParams): import("react/jsx-runtime").JSX.Element;

package/dist/components/UserChip.d.ts

@@ -0,0 +1,4 @@
+import { User } from "@firecms/core";
+export declare function UserChip({ user }: {
+    user: User;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/entity_history_callbacks.d.ts

@@ -0,0 +1,2 @@
+import { EntityCallbacks } from "@firecms/core";
+export declare const entityHistoryCallbacks: EntityCallbacks;

package/dist/index.d.ts

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