@firecms/collection_editor 3.0.0 → 3.1.0-canary.1df3b2c

package/src/ConfigControllerProvider.tsx

@@ -17,6 +17,7 @@ import { CollectionEditorPermissionsBuilder } from "./types/config_permissions";
 import { CollectionInference } from "./types/collection_inference";
 import { PropertyFormDialog } from "./ui/collection_editor/PropertyEditView";
 import { PersistedCollection } from "./types/persisted_collection";
+import { CollectionGenerationCallback } from "./api/generateCollectionApi";
 
 export const ConfigControllerContext = React.createContext<CollectionsConfigController>({} as any);
 export const CollectionEditorContext = React.createContext<CollectionEditorController>({} as any);
@@ -57,21 +58,28 @@ export interface ConfigControllerProviderProps {
 
     onAnalyticsEvent?: (event: string, params?: object) => void;
 
+    /**
+     * Callback function for generating/modifying collections.
+     * The plugin is API-agnostic - the consumer provides the implementation.
+     */
+    generateCollection?: CollectionGenerationCallback;
+
 }
 
 export const ConfigControllerProvider = React.memo(
     function ConfigControllerProvider({
-                                          children,
-                                          collectionConfigController,
-                                          configPermissions,
-                                          reservedGroups,
-                                          collectionInference,
-                                          extraView,
-                                          getUser,
-                                          getData,
-                                          onAnalyticsEvent,
-                                          pathSuggestions
-                                      }: PropsWithChildren<ConfigControllerProviderProps>) {
+        children,
+        collectionConfigController,
+        configPermissions,
+        reservedGroups,
+        collectionInference,
+        extraView,
+        getUser,
+        getData,
+        onAnalyticsEvent,
+        pathSuggestions,
+        generateCollection
+    }: PropsWithChildren<ConfigControllerProviderProps>) {
 
         const navigation = useNavigationController();
         const navigate = useNavigate();
@@ -89,9 +97,12 @@ export const ConfigControllerProvider = React.memo(
                 group?: string,
                 name?: string
             },
+            copyFrom?: PersistedCollection,
             redirect: boolean,
             existingEntities?: Entity<any>[],
             pathSuggestions?: string[];
+            initialView?: "general" | "display" | "properties";
+            expandKanban?: boolean;
         }>();
 
         const [currentPropertyDialog, setCurrentPropertyDialog] = React.useState<{
@@ -104,7 +115,8 @@ export const ConfigControllerProvider = React.memo(
             fullPath?: string,
             parentCollectionIds: string[],
             collectionEditable: boolean;
-            existingEntities?: Entity<any>[]
+            existingEntities?: Entity<any>[];
+            collection?: PersistedCollection;
         }>();
 
         const defaultConfigPermissions: CollectionEditorPermissionsBuilder = useCallback(() => ({
@@ -114,17 +126,21 @@ export const ConfigControllerProvider = React.memo(
         }), []);
 
         const editCollection = ({
-                                    id,
-                                    fullPath,
-                                    parentCollectionIds,
-                                    parentCollection,
-                                    existingEntities
-                                }: {
+            id,
+            fullPath,
+            parentCollectionIds,
+            parentCollection,
+            existingEntities,
+            initialView,
+            expandKanban
+        }: {
             id?: string,
             fullPath?: string,
             parentCollectionIds: string[],
             parentCollection?: PersistedCollection,
-            existingEntities?: Entity<any>[]
+            existingEntities?: Entity<any>[],
+            initialView?: "general" | "display" | "properties",
+            expandKanban?: boolean
         }) => {
             console.debug("Edit collection", id, fullPath, parentCollectionIds, parentCollection);
             onAnalyticsEvent?.("edit_collection", {
@@ -139,19 +155,21 @@ export const ConfigControllerProvider = React.memo(
                 parentCollection,
                 redirect: false,
                 existingEntities,
-                pathSuggestions
+                pathSuggestions,
+                initialView,
+                expandKanban
             });
         };
 
         const editProperty = ({
-                                  propertyKey,
-                                  property,
-                                  editedCollectionId,
-                                  currentPropertiesOrder,
-                                  parentCollectionIds,
-                                  collection,
-                                  existingEntities
-                              }: {
+            propertyKey,
+            property,
+            editedCollectionId,
+            currentPropertiesOrder,
+            parentCollectionIds,
+            collection,
+            existingEntities
+        }: {
             propertyKey?: string,
             property?: Property,
             currentPropertiesOrder?: string[],
@@ -180,17 +198,19 @@ export const ConfigControllerProvider = React.memo(
                 editedCollectionId,
                 parentCollectionIds,
                 collectionEditable: collection?.editable === undefined || collection?.editable === true,
-                existingEntities
+                existingEntities,
+                collection
             });
         };
 
         const createCollection = ({
-                                      parentCollectionIds,
-                                      parentCollection,
-                                      initialValues,
-                                      redirect,
-                                      sourceClick
-                                  }: {
+            parentCollectionIds,
+            parentCollection,
+            initialValues,
+            copyFrom,
+            redirect,
+            sourceClick
+        }: {
             parentCollectionIds: string[],
             parentCollection?: PersistedCollection
             initialValues?: {
@@ -198,6 +218,7 @@ export const ConfigControllerProvider = React.memo(
                 path?: string,
                 name?: string
             },
+            copyFrom?: PersistedCollection,
             redirect: boolean,
             sourceClick?: string
         }) => {
@@ -205,10 +226,11 @@ export const ConfigControllerProvider = React.memo(
                 parentCollectionIds,
                 parentCollection,
                 initialValues,
+                copyFrom,
                 redirect,
                 sourceClick
             });
-            onAnalyticsEvent?.("create_collection", {
+            onAnalyticsEvent?.(copyFrom ? "duplicate_collection" : "create_collection", {
                 parentCollectionIds,
                 parentCollection,
                 initialValues,
@@ -220,6 +242,7 @@ export const ConfigControllerProvider = React.memo(
                 parentCollectionIds,
                 parentCollection,
                 initialValues,
+                copyFrom,
                 redirect,
                 pathSuggestions
             });
@@ -248,6 +271,7 @@ export const ConfigControllerProvider = React.memo(
                         reservedGroups={reservedGroups}
                         extraView={extraView}
                         getUser={getUser}
+                        generateCollection={generateCollection}
                         handleClose={(collection) => {
                             if (currentDialog?.redirect) {
                                 if (collection && currentDialog?.isNewCollection && !currentDialog.parentCollectionIds.length) {
@@ -256,7 +280,7 @@ export const ConfigControllerProvider = React.memo(
                                 }
                             }
                             setCurrentDialog(undefined);
-                        }}/>
+                        }} />
 
                     {/* Used for editing properties*/}
                     <PropertyFormDialog
@@ -267,17 +291,27 @@ export const ConfigControllerProvider = React.memo(
                         autoOpenTypeSelect={!currentPropertyDialog ? false : !currentPropertyDialog?.propertyKey}
                         inArray={false}
                         collectionEditable={currentPropertyDialog?.collectionEditable ?? false}
-                        getData={getData && currentPropertyDialog?.editedCollectionId
-                            ? () => {
-                                console.debug("get data for property", currentPropertyDialog?.editedCollectionId);
-                                const resolvedPath = navigation.resolveIdsFrom(currentPropertyDialog.editedCollectionId!)
-                                return getData(resolvedPath, []);
+                        getData={currentPropertyDialog?.existingEntities || (getData && currentPropertyDialog?.editedCollectionId)
+                            ? async () => {
+                                let data: object[] = [];
+                                // First, use existing entities if available (already loaded in table)
+                                if (currentPropertyDialog?.existingEntities) {
+                                    data = currentPropertyDialog.existingEntities.map(e => e.values);
+                                }
+                                // If getData is available and we have a path, also fetch from database
+                                if (getData && currentPropertyDialog?.editedCollectionId) {
+                                    console.debug("Get data for property, path:", currentPropertyDialog?.editedCollectionId);
+                                    const resolvedPath = navigation.resolveIdsFrom(currentPropertyDialog.editedCollectionId!);
+                                    const fetchedData = await getData(resolvedPath, []);
+                                    data.push(...fetchedData);
+                                }
+                                return data;
                             }
                             : undefined}
                         onPropertyChanged={({
-                                                id,
-                                                property
-                                            }) => {
+                            id,
+                            property
+                        }) => {
                             if (!currentPropertyDialog) return;
                             if (!id) return;
                             const newProperty = !(currentPropertyDialog.propertyKey);
@@ -330,11 +364,11 @@ export const ConfigControllerProvider = React.memo(
                         }}
                         initialErrors={{}}
                         forceShowErrors={false}
-                        existingPropertyKeys={[]}
+                        existingPropertyKeys={currentPropertyDialog?.collection?.properties ? Object.keys(currentPropertyDialog.collection.properties) : []}
                         allowDataInference={true}
                         propertyConfigs={propertyConfigs}
                         property={currentPropertyDialog?.property}
-                        propertyKey={currentPropertyDialog?.propertyKey}/>
+                        propertyKey={currentPropertyDialog?.propertyKey} />
 
                 </CollectionEditorContext.Provider>
 

package/src/api/generateCollectionApi.ts

@@ -0,0 +1,119 @@
+import { EntityCollection } from "@firecms/core";
+
+export interface GenerateCollectionRequest {
+    /** User's natural language description of what they want */
+    prompt: string;
+
+    /** Other collections in the project (for context/relationships). Limit to 30. */
+    existingCollections: Partial<EntityCollection>[];
+
+    /** Optional for generate, required for modifications. If provided, modifies this collection */
+    existingCollection?: Partial<EntityCollection>;
+}
+
+/** Operation types for modifying a collection */
+export type CollectionOperationType = "add" | "modify" | "delete";
+
+/** A single operation describing what changed */
+export interface CollectionOperation {
+    op: CollectionOperationType;
+    path: string;
+    value?: any;
+}
+
+/** Result from collection generation, including optional delta operations */
+export interface GenerateCollectionResult {
+    collection: EntityCollection;
+    operations?: CollectionOperation[];
+}
+
+/**
+ * Callback type for generating or modifying a collection.
+ * The plugin is API-agnostic - consumers implement the actual API call.
+ */
+export type CollectionGenerationCallback = (
+    request: GenerateCollectionRequest
+) => Promise<GenerateCollectionResult>;
+
+export class CollectionGenerationApiError extends Error {
+    public code?: string;
+
+    constructor(message: string, code?: string) {
+        super(message);
+        this.code = code;
+        this.name = "CollectionGenerationApiError";
+    }
+}
+
+/**
+ * Default endpoint for AI collection generation
+ */
+export const DEFAULT_COLLECTION_GENERATION_ENDPOINT = "https://api.firecms.co/collections/generate";
+
+/**
+ * Props for building a collection generation callback
+ */
+export interface BuildCollectionGenerationCallbackProps {
+    /**
+     * Function to get the auth token (e.g., from Firebase Auth)
+     * This is typically `authController.getAuthToken` from `@firecms/firebase`
+     */
+    getAuthToken: () => Promise<string>;
+
+    /**
+     * Optional custom API endpoint for collection generation.
+     * Defaults to the FireCMS SaaS API endpoint.
+     */
+    apiEndpoint?: string;
+}
+
+/**
+ * Build a callback for AI collection generation.
+ * This helper allows self-hosted FireCMS users to enable the AI collection
+ * generation feature.
+ *
+ * @example
+ * ```typescript
+ * import { useCollectionEditorPlugin, buildCollectionGenerationCallback } from "@firecms/collection_editor";
+ * import { useFirebaseAuthController } from "@firecms/firebase";
+ *
+ * const authController = useFirebaseAuthController({ firebaseApp });
+ *
+ * const collectionEditorPlugin = useCollectionEditorPlugin({
+ *     // ... other props
+ *     generateCollection: buildCollectionGenerationCallback({
+ *         getAuthToken: authController.getAuthToken
+ *     })
+ * });
+ * ```
+ */
+export function buildCollectionGenerationCallback({
+    getAuthToken,
+    apiEndpoint = DEFAULT_COLLECTION_GENERATION_ENDPOINT
+}: BuildCollectionGenerationCallbackProps): CollectionGenerationCallback {
+    return async (request) => {
+        const token = await getAuthToken();
+        const response = await fetch(apiEndpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`
+            },
+            body: JSON.stringify(request)
+        });
+
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new CollectionGenerationApiError(
+                errorData.error || "Failed to generate collection",
+                errorData.code
+            );
+        }
+
+        const data = await response.json();
+        return {
+            collection: data.data.collection,
+            operations: data.data.operations
+        };
+    };
+}

package/src/api/index.ts

@@ -0,0 +1 @@
+export * from "./generateCollectionApi";

package/src/index.ts

@@ -13,9 +13,14 @@ export {
     editableProperty, removeNonEditableProperties
 } from "./utils/entities";
 export * from "./utils/collections";
+export {
+    validateCollectionJson,
+    type CollectionValidationError,
+    type CollectionValidationResult
+} from "./utils/validateCollectionJson";
 
 export type {
-    CollectionsConfigController, DeleteCollectionParams, SaveCollectionParams, UpdateCollectionParams
+    CollectionsConfigController, DeleteCollectionParams, SaveCollectionParams, UpdateCollectionParams, CollectionsSetupInfo, UpdatePropertiesOrderParams, UpdateKanbanColumnsOrderParams
 } from "./types/config_controller";
 export type {
     CollectionEditorController
@@ -31,6 +36,28 @@ export type {
     CollectionInference
 } from "./types/collection_inference";
 
+export {
+    buildCollectionGenerationCallback,
+    CollectionGenerationApiError,
+    DEFAULT_COLLECTION_GENERATION_ENDPOINT
+} from "./api/generateCollectionApi";
+
+export type {
+    CollectionGenerationCallback,
+    GenerateCollectionRequest,
+    GenerateCollectionResult,
+    CollectionOperation,
+    CollectionOperationType,
+    BuildCollectionGenerationCallbackProps
+} from "./api/generateCollectionApi";
+
 export { MissingReferenceWidget } from "./ui/MissingReferenceWidget";
 
 export * from "./ui/collection_editor/util";
+
+export {
+    PropertyForm,
+    PropertyFormDialog,
+    type PropertyFormProps,
+    type OnPropertyChangedParams
+} from "./ui/collection_editor/PropertyEditView";

package/src/types/collection_editor_controller.tsx

@@ -1,4 +1,3 @@
-import React from "react";
 import { CollectionEditorPermissionsBuilder } from "./config_permissions";
 import { Entity, Property } from "@firecms/core";
 import { PersistedCollection } from "./persisted_collection";
@@ -14,15 +13,29 @@ export interface CollectionEditorController {
         fullPath?: string,
         parentCollectionIds: string[],
         parentCollection?: PersistedCollection,
-        existingEntities?: Entity<any>[]
+        existingEntities?: Entity<any>[],
+        /**
+         * Initial view to open: "general", "display", or "properties"
+         */
+        initialView?: "general" | "display" | "properties",
+        /**
+         * If true, expand the Kanban configuration section
+         */
+        expandKanban?: boolean
     }) => void;
 
     createCollection: (props: {
         initialValues?: {
             group?: string,
             path?: string,
-            name?: string
+            name?: string,
+            databaseId?: string
         },
+        /**
+         * A collection to duplicate from. If provided, the new collection will be
+         * pre-populated with the same properties (but with empty name, path, and id).
+         */
+        copyFrom?: PersistedCollection,
         parentCollectionIds: string[],
         parentCollection?: PersistedCollection,
         redirect: boolean,

package/src/types/collection_inference.ts

@@ -1,6 +1,19 @@
-import { EntityCollection } from "@firecms/core";
+import { EntityCollection, FilterValues } from "@firecms/core";
 
 /**
  * This function is used to infer the configuration of a collection given its path.
+ * @param path - The path of the collection
+ * @param collectionGroup - Whether this is a collection group query
+ * @param parentCollectionPaths - Array of parent collection paths for subcollections
+ * @param databaseId - Optional database ID for multi-database setups
+ * @param initialFilter - Optional filter values from the collection configuration
+ * @param initialSort - Optional sort configuration from the collection
  */
-export type CollectionInference = (path: string, collectionGroup: boolean, parentCollectionPaths: string[], databaseId?:string) => Promise<Partial<EntityCollection> | null>;
+export type CollectionInference = (
+    path: string,
+    collectionGroup: boolean,
+    parentCollectionPaths: string[],
+    databaseId?: string,
+    initialFilter?: FilterValues<string>,
+    initialSort?: [string, "asc" | "desc"]
+) => Promise<Partial<EntityCollection> | null>;

package/src/types/config_controller.tsx

@@ -1,6 +1,11 @@
-import { CMSType, NavigationGroupMapping, Property } from "@firecms/core";
+import { CMSType, EntityCollection, NavigationGroupMapping, Property } from "@firecms/core";
 import { PersistedCollection } from "./persisted_collection";
 
+export interface CollectionsSetupInfo {
+    status: "ongoing" | "complete" | "error";
+    error: string | null;
+}
+
 /**
  * Use this controller to access the configuration that is stored externally,
  * and not defined in code.
@@ -11,6 +16,12 @@ export interface CollectionsConfigController {
 
     collections?: PersistedCollection[];
 
+    /**
+     * Status information about the automatic collections setup process.
+     * Stored in the project config document at `collectionsSetup`.
+     */
+    collectionsSetup?: CollectionsSetupInfo;
+
     getCollection: (id: string) => PersistedCollection;
 
     saveCollection: <M extends { [Key: string]: CMSType }>(params: SaveCollectionParams<M>) => Promise<void>;
@@ -21,6 +32,16 @@ export interface CollectionsConfigController {
 
     deleteCollection: (props: DeleteCollectionParams) => Promise<void>;
 
+    /**
+     * Update the properties order of a collection (used for column reordering).
+     */
+    updatePropertiesOrder: (params: UpdatePropertiesOrderParams) => Promise<void>;
+
+    /**
+     * Update the Kanban columns order for a collection.
+     */
+    updateKanbanColumnsOrder: (params: UpdateKanbanColumnsOrderParams) => Promise<void>;
+
     navigationEntries: NavigationGroupMapping[];
     saveNavigationEntries: (entries: NavigationGroupMapping[]) => Promise<void>;
 
@@ -61,3 +82,18 @@ export type DeleteCollectionParams = {
     id: string,
     parentCollectionIds?: string[]
 }
+
+export type UpdatePropertiesOrderParams = {
+    fullPath: string;
+    parentCollectionIds: string[];
+    collection: EntityCollection<any>;
+    newPropertiesOrder: string[];
+}
+
+export type UpdateKanbanColumnsOrderParams = {
+    fullPath: string;
+    parentCollectionIds: string[];
+    collection: EntityCollection<any>;
+    kanbanColumnProperty: string;
+    newColumnsOrder: string[];
+}