@firecms/core 3.0.0-canary.99 → 3.0.0-rc.2

package/dist/types/entities.d.ts

@@ -7,7 +7,7 @@ export type EntityStatus = "new" | "existing" | "copy";
  * Representation of an entity fetched from the datasource
  * @group Models
  */
-export interface Entity<M extends object> {
+export interface Entity<M extends object = any> {
     /**
      * ID of the entity
      */
@@ -21,6 +21,7 @@ export interface Entity<M extends object> {
      * Current values
      */
     values: EntityValues<M>;
+    databaseId?: string;
 }
 /**
  * This type represents a record of key value pairs as described in an
@@ -41,7 +42,11 @@ export declare class EntityReference {
      * to the root of the database).
      */
     readonly path: string;
-    constructor(id: string, path: string);
+    /**
+     * Optional database ID where the entity is stored (if multiple databases are used)
+     */
+    readonly databaseId?: string;
+    constructor(id: string, path: string, databaseId?: string);
     get pathWithId(): string;
     isEntityReference(): boolean;
 }

package/dist/types/entity_actions.d.ts

@@ -4,15 +4,28 @@ import { Entity } from "./entities";
 import { EntityCollection, SelectionController } from "./collections";
 import { User } from "./user";
 import { SideEntityController } from "./side_entity_controller";
+import { FormContext } from "./fields";
 /**
  * An entity action is a custom action that can be performed on an entity.
  * They are displayed in the entity view and in the collection view.
  */
-export type EntityAction<M extends object = any, UserType extends User = User> = {
+export type EntityAction<M extends object = any, USER extends User = User> = {
     /**
      * Title of the action
      */
     name: string;
+    /**
+     * Key of the action. You only need to provide this if you want to
+     * override the default actions, or if you are not passing the action
+     * directly to the `entityActions` prop of a collection.
+     * You can define your actions at the app level, in which case you
+     * must provide a key.
+     * The default actions are:
+     * - edit
+     * - delete
+     * - copy
+     */
+    key?: string;
     /**
      * Icon of the action
      */
@@ -21,7 +34,12 @@ export type EntityAction<M extends object = any, UserType extends User = User> =
      * Callback when the action is clicked
      * @param props
      */
-    onClick: (props: EntityActionClickProps<M, UserType>) => Promise<void> | void;
+    onClick: (props: EntityActionClickProps<M, USER>) => Promise<void> | void;
+    /**
+     * Optional callback in case you want to disable the action
+     * @param props
+     */
+    isEnabled?: (props: EntityActionClickProps<M, USER>) => boolean;
     /**
      * Show this action collapsed in the menu of the collection view.
      * Defaults to true
@@ -33,17 +51,49 @@ export type EntityAction<M extends object = any, UserType extends User = User> =
      */
     includeInForm?: boolean;
 };
-export type EntityActionClickProps<M extends object, UserType extends User = User> = {
-    entity: Entity<M>;
-    context: FireCMSContext<UserType>;
+export type EntityActionClickProps<M extends object, USER extends User = User> = {
+    entity?: Entity<M>;
+    context: FireCMSContext<USER>;
     fullPath?: string;
+    fullIdPath?: string;
     collection?: EntityCollection<M>;
+    /**
+     * Optional form context, present if the action is being called from a form.
+     * This allows you to access the form state and methods, including modifying the form values.
+     */
+    formContext?: FormContext;
+    /**
+     * Present if this actions is being called from a side dialog only
+     */
+    sideEntityController?: SideEntityController;
+    /**
+     * Is the action being called from the collection view or from the entity form view?
+     */
+    view: "collection" | "form";
+    /**
+     * If the action is rendered in the form, is it open in a side panel or full screen?
+     */
+    openEntityMode: "side_panel" | "full_screen";
+    /**
+     * Optional selection controller, present if the action is being called from a collection view
+     */
     selectionController?: SelectionController;
+    /**
+     * Optional highlight function to highlight the entity in the collection view
+     * @param entity
+     */
     highlightEntity?: (entity: Entity<any>) => void;
+    /**
+     * Optional unhighlight function to remove the highlight from the entity in the collection view
+     * @param entity
+     */
     unhighlightEntity?: (entity: Entity<any>) => void;
-    onCollectionChange?: () => void;
     /**
-     * If this actions is being called from a side dialog
+     * Optional function to navigate back (e.g. when deleting an entity or navigating from a form)
      */
-    sideEntityController?: SideEntityController;
+    navigateBack?: () => void;
+    /**
+     * Callback to be called when the collection changes, e.g. after an entity is deleted or created.
+     */
+    onCollectionChange?: () => void;
 };

package/dist/types/entity_callbacks.d.ts

@@ -9,29 +9,29 @@ import { User } from "./user";
  * Useful for adding your own logic or blocking the execution of the operation.
  * @group Models
  */
-export type EntityCallbacks<M extends Record<string, any> = any, UserType extends User = User> = {
+export type EntityCallbacks<M extends Record<string, any> = any, USER extends User = User> = {
     /**
      * Callback used after fetching data
      * @param entityFetchProps
      */
-    onFetch?(entityFetchProps: EntityOnFetchProps<M, UserType>): Promise<Entity<M>> | Entity<M>;
+    onFetch?(entityFetchProps: EntityOnFetchProps<M, USER>): Promise<Entity<M>> | Entity<M>;
     /**
      * Callback used when save is successful
      * @param entitySaveProps
      */
-    onSaveSuccess?(entitySaveProps: EntityOnSaveProps<M, UserType>): Promise<void> | void;
+    onSaveSuccess?(entitySaveProps: EntityOnSaveProps<M, USER>): Promise<void> | void;
     /**
      * Callback used when saving fails
      * @param entitySaveProps
      */
-    onSaveFailure?(entitySaveProps: EntityOnSaveFailureProps<M, UserType>): Promise<void> | void;
+    onSaveFailure?(entitySaveProps: EntityOnSaveFailureProps<M, USER>): Promise<void> | void;
     /**
      * Callback used before saving, you need to return the values that will get
      * saved. If you throw an error in this method the process stops, and an
      * error snackbar gets displayed.
      * @param entitySaveProps
      */
-    onPreSave?(entitySaveProps: EntityOnPreSaveProps<M, UserType>): Promise<Partial<EntityValues<M>>> | Partial<EntityValues<M>>;
+    onPreSave?(entitySaveProps: EntityOnPreSaveProps<M, USER>): Promise<Partial<EntityValues<M>>> | Partial<EntityValues<M>>;
     /**
      * Callback used after the entity is deleted.
      * If you throw an error in this method the process stops, and an
@@ -39,13 +39,13 @@ export type EntityCallbacks<M extends Record<string, any> = any, UserType extend
      *
      * @param entityDeleteProps
      */
-    onPreDelete?(entityDeleteProps: EntityOnDeleteProps<M, UserType>): void;
+    onPreDelete?(entityDeleteProps: EntityOnDeleteProps<M, USER>): void;
     /**
      * Callback used after the entity is deleted.
      *
      * @param entityDeleteProps
      */
-    onDelete?(entityDeleteProps: EntityOnDeleteProps<M, UserType>): void;
+    onDelete?(entityDeleteProps: EntityOnDeleteProps<M, USER>): void;
     /**
      * Callback fired when any value in the form changes. You can use it
      * to define the ID of a `new` entity based on the current values.
@@ -59,11 +59,11 @@ export type EntityCallbacks<M extends Record<string, any> = any, UserType extend
  * Parameters passed to hooks when an entity is fetched
  * @group Models
  */
-export interface EntityOnFetchProps<M extends Record<string, any> = any, UserType extends User = User> {
+export interface EntityOnFetchProps<M extends Record<string, any> = any, USER extends User = User> {
     /**
      * Collection of the entity
      */
-    collection: EntityCollection<M, UserType>;
+    collection: EntityCollection<M, USER>;
     /**
      * Full path of the CMS where this collection is being fetched.
      * Might contain unresolved aliases.
@@ -76,27 +76,27 @@ export interface EntityOnFetchProps<M extends Record<string, any> = any, UserTyp
     /**
      * Context of the app status
      */
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 }
 /**
  * Parameters passed to hooks before an entity is saved
  * @group Models
  */
-export type EntityOnPreSaveProps<M extends Record<string, any> = any, UserType extends User = User> = Omit<EntityOnSaveProps<M, UserType>, "entityId"> & {
+export type EntityOnPreSaveProps<M extends Record<string, any> = any, USER extends User = User> = Omit<EntityOnSaveProps<M, USER>, "entityId"> & {
     entityId?: string;
 };
 /**
  * Parameters passed to hooks before an entity is saved
  * @group Models
  */
-export type EntityOnSaveFailureProps<M extends Record<string, any> = any, UserType extends User = User> = Omit<EntityOnSaveProps<M, UserType>, "entityId"> & {
+export type EntityOnSaveFailureProps<M extends Record<string, any> = any, USER extends User = User> = Omit<EntityOnSaveProps<M, USER>, "entityId"> & {
     entityId?: string;
 };
 /**
  * Parameters passed to hooks when an entity is saved
  * @group Models
  */
-export interface EntityOnSaveProps<M extends Record<string, any> = any, UserType extends User = User> {
+export interface EntityOnSaveProps<M extends Record<string, any> = any, USER extends User = User> {
     /**
      * Resolved collection of the entity
      */
@@ -129,13 +129,13 @@ export interface EntityOnSaveProps<M extends Record<string, any> = any, UserType
     /**
      * Context of the app status
      */
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 }
 /**
  * Parameters passed to hooks when an entity is deleted
  * @group Models
  */
-export interface EntityOnDeleteProps<M extends Record<string, any> = any, UserType extends User = User> {
+export interface EntityOnDeleteProps<M extends Record<string, any> = any, USER extends User = User> {
     /**
      * collection of the entity being deleted
      */
@@ -155,7 +155,7 @@ export interface EntityOnDeleteProps<M extends Record<string, any> = any, UserTy
     /**
      * Context of the app status
      */
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 }
 /**
  * Parameters passed to hooks when an entity is deleted

package/dist/types/entity_overrides.d.ts

@@ -1,6 +1,6 @@
-import { DataSource } from "./datasource";
+import { DataSourceDelegate } from "./datasource";
 import { StorageSource } from "./storage";
 export type EntityOverrides = {
-    dataSource?: DataSource;
+    dataSourceDelegate?: DataSourceDelegate;
     storageSource?: StorageSource;
 };

package/dist/types/export_import.d.ts

@@ -6,16 +6,16 @@ import { FireCMSContext } from "./firecms_context";
  * exports
  * @group Models
  */
-export interface ExportConfig<UserType extends User = User> {
-    additionalFields: ExportMappingFunction<UserType>[];
+export interface ExportConfig<USER extends User = User> {
+    additionalFields: ExportMappingFunction<USER>[];
 }
 /**
  * @group Models
  */
-export interface ExportMappingFunction<UserType extends User = User> {
+export interface ExportMappingFunction<USER extends User = User> {
     key: string;
     builder: ({ entity, context }: {
         entity: Entity<any>;
-        context: FireCMSContext<UserType>;
+        context: FireCMSContext<USER>;
     }) => Promise<string> | string;
 }

package/dist/types/fields.d.ts

@@ -1,6 +1,7 @@
-import { CMSType, PropertyOrBuilder } from "./properties";
+import { CMSType, Property, PropertyOrBuilder } from "./properties";
 import { ResolvedEntityCollection, ResolvedProperty } from "./resolved_entities";
 import { FormexController } from "@firecms/formex";
+import { Entity } from "./entities";
 /**
  * When building a custom field you need to create a React component that takes
  * this interface as props.
@@ -52,7 +53,7 @@ export interface FieldProps<T extends CMSType = any, CustomProps = any, M extend
     /**
      * Property related to this field
      */
-    property: ResolvedProperty<T>;
+    property: Property<T> | ResolvedProperty<T>;
     /**
      * Should this field include a description
      */
@@ -67,13 +68,10 @@ export interface FieldProps<T extends CMSType = any, CustomProps = any, M extend
      */
     partOfArray?: boolean;
     /**
-     * Is this field part of a block (oneOf array)
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel. Note that this will also hide the title of this property.
      */
-    partOfBlock?: boolean;
-    /**
-     * Is this field being rendered in the entity table popup
-     */
-    tableMode?: boolean;
+    minimalistView?: boolean;
     /**
      * Should this field autofocus on mount
      */
@@ -81,7 +79,7 @@ export interface FieldProps<T extends CMSType = any, CustomProps = any, M extend
     /**
      * Additional properties set by the developer
      */
-    customProps?: CustomProps;
+    customProps: CustomProps;
     /**
      * Additional values related to the state of the form or the entity
      */
@@ -90,6 +88,18 @@ export interface FieldProps<T extends CMSType = any, CustomProps = any, M extend
      * Flag to indicate if this field should be disabled
      */
     disabled?: boolean;
+    /**
+     * Size of the field
+     */
+    size?: "small" | "medium" | "large";
+    /**
+     * Some properties might change internal state (like expanding a panel).
+     * This function should be called when the internal state changes.
+     * This is used to preserve state in array containers.
+     *
+     * @param property
+     */
+    onPropertyChange?: (property: Partial<Property<any>>) => void;
 }
 /**
  * Context passed to custom fields
@@ -118,15 +128,22 @@ export interface FormContext<M extends Record<string, any> = any> {
     /**
      * Entity id, it can be null if it's a new entity
      */
-    entityId?: string;
+    entityId: string;
     /**
      * Path this entity is located at
      */
     path?: string;
+    status: "new" | "existing" | "copy";
+    entity?: Entity<M>;
+    savingError?: Error;
+    openEntityMode: "side_panel" | "full_screen";
     /**
-     * This is the underlying formex controller that powers the form
+     * This is the underlying formex controller that powers the form.
+     * If you are in a red only mode, the formex controller is there, but you can't
+     * operate with it
      */
     formex: FormexController<M>;
+    disabled: boolean;
 }
 /**
  * In case you need to render a field bound to a Property inside your
@@ -157,18 +174,15 @@ export interface PropertyFieldBindingProps<T extends CMSType, M extends Record<s
      * field is being edited
      */
     underlyingValueHasChanged?: boolean;
-    /**
-     * Is this field being rendered in a table
-     */
-    tableMode?: boolean;
     /**
      * Is this field part of an array
      */
     partOfArray?: boolean;
     /**
-     * Is this field part of a block (oneOf array)
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel. Note that this will also hide the title of this property.
      */
-    partOfBlock?: boolean;
+    minimalistView?: boolean;
     /**
      * Should the field take focus when rendered. When opening the popup view
      * in table mode, it makes sense to put the focus on the only field rendered.
@@ -183,4 +197,16 @@ export interface PropertyFieldBindingProps<T extends CMSType, M extends Record<s
      * Only used when the field is part of an array.
      */
     index?: number;
+    /**
+     * The size of the field
+     */
+    size?: "small" | "medium" | "large";
+    /**
+     * Some properties might change internal state (like expanding a panel).
+     * This function should be called when the internal state changes.
+     * This is used to preserve state in array containers.
+     *
+     * @param property
+     */
+    onPropertyChange?: (property: Partial<Property<any>>) => void;
 }

package/dist/types/firecms.d.ts

@@ -12,6 +12,8 @@ import { EntityLinkBuilder } from "./entity_link_builder";
 import { UserConfigurationPersistence } from "./local_config_persistence";
 import { FireCMSPlugin } from "./plugins";
 import { CMSAnalyticsEvent } from "./analytics";
+import { EntityAction } from "./entity_actions";
+import { InternalUserManagement } from "./internal_user_management";
 /**
  * Use this callback to build entity collections dynamically.
  * You can use the user to decide which collections to show.
@@ -44,7 +46,7 @@ export type CMSViewsBuilder = (params: {
 /**
  * @group Models
  */
-export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
+export type FireCMSProps<USER extends User> = {
     /**
      * Use this function to return the components you want to render under
      * FireCMS
@@ -62,6 +64,10 @@ export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
          */
         loading: boolean;
     }) => React.ReactNode;
+    /**
+     * If you have a custom API key, you can use it here.
+     */
+    apiKey?: string;
     /**
      * Record of custom form fields to be used in the CMS.
      * You can use the key to reference the custom field in
@@ -81,6 +87,13 @@ export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
      * You can also define an entity view from the UI.
      */
     entityViews?: EntityCustomView[];
+    /**
+     * List of actions that can be performed on entities.
+     * These actions are displayed in the entity view and in the collection view.
+     * You can later reuse these actions in the `entityActions` prop of a collection,
+     * by specifying the `key` of the action.
+     */
+    entityActions?: EntityAction[];
     /**
      * Format of the dates in the CMS.
      * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
@@ -101,7 +114,7 @@ export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
     /**
      * Delegate for implementing your auth operations.
      */
-    authController: AuthController<UserType>;
+    authController: AuthController<USER>;
     /**
      * Use this controller to access the configuration that is stored locally,
      * and not defined in code
@@ -109,7 +122,9 @@ export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
     userConfigPersistence?: UserConfigurationPersistence;
     /**
      * Use plugins to modify the behaviour of the CMS.
-     * Currently, in ALPHA, and likely subject to change.
+     * DEPRECATED: use the `plugins` prop in the `useBuildNavigationController` instead.
+     * This prop will work as a fallback for the `plugins` prop in the `useBuildNavigationController`.
+     * @deprecated
      */
     plugins?: FireCMSPlugin<any, any, any>[];
     /**
@@ -121,6 +136,19 @@ export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
      * The function must return a URL that gets opened when the button is clicked
      */
     entityLinkBuilder?: EntityLinkBuilder;
+    /**
+     * You can use this props to provide your own user management implementation.
+     * Note that this will not affect the UI, but it will be used to show user information
+     * in various places of the CMS, for example, to show who created or modified an entity,
+     * or to assign ownership of an entity.
+     *
+     * You can also use this data to be retrieved in your custom properties,
+     * for example, to show a list of users in a dropdown.
+     *
+     * If you are using the FireCMS user management plugin, this
+     * prop will be implemented automatically.
+     */
+    userManagement?: InternalUserManagement;
     components?: {
         /**
          * Component to render when a reference is missing

package/dist/types/firecms_context.d.ts

@@ -10,6 +10,7 @@ import { SideDialogsController } from "./side_dialogs_controller";
 import { DialogsController } from "./dialogs_controller";
 import { CustomizationController } from "./customization_controller";
 import { AnalyticsController } from "./analytics_controller";
+import { InternalUserManagement } from "./internal_user_management";
 /**
  * Context that includes the internal controllers and contexts used by the app.
  * Some controllers and context included in this context can be accessed
@@ -17,7 +18,7 @@ import { AnalyticsController } from "./analytics_controller";
  * @group Hooks and utilities
  * @see useFireCMSContext
  */
-export type FireCMSContext<UserType extends User = User, AuthControllerType extends AuthController<UserType> = AuthController<UserType>> = {
+export type FireCMSContext<USER extends User = User, AuthControllerType extends AuthController<USER> = AuthController<USER>> = {
     /**
      * Connector to your database, e.g. your Firestore database
      */
@@ -67,4 +68,19 @@ export type FireCMSContext<UserType extends User = User, AuthControllerType exte
      * Callback to send analytics events
      */
     analyticsController?: AnalyticsController;
+    /**
+     * This section is used to manage users in the CMS.
+     * It is used to show user information in various places of the CMS,
+     * for example, to show who created or modified an entity,
+     * or to assign ownership of an entity.
+     *
+     * In the base CMS, this information is not used for access control.
+     * You can pass your own implementation of this section, to populate
+     * the dropdown of users when assigning ownership of an entity,
+     * or to show more information about the user.
+     *
+     * If you are using the FireCMS user management plugin, this
+     * section will be implemented automatically.
+     */
+    userManagement: InternalUserManagement<USER>;
 };

package/dist/types/index.d.ts

@@ -13,6 +13,7 @@ export * from "./fields";
 export * from "./property_config";
 export * from "./datasource";
 export * from "./entity_link_builder";
+export * from "./internal_user_management";
 export * from "./side_entity_controller";
 export * from "./side_dialogs_controller";
 export * from "./firecms_context";

package/dist/types/internal_user_management.d.ts

@@ -0,0 +1,20 @@
+import { User } from "./user";
+export type InternalUserManagement<USER extends User = User> = {
+    /**
+     * List of users to be managed by the CMS.
+     */
+    users: USER[];
+    /**
+     * Function to get a user by its uid. This is used to show
+     * user information when assigning ownership of an entity.
+     *
+     * You can pass your own implementation if you want to show
+     * more information about the user.
+     *
+     * If you are using the FireCMS user management plugin, this
+     * function will be implemented automatically.
+     *
+     * @param uid
+     */
+    getUser: (uid: string) => USER | null;
+};