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

package/src/types/entity_callbacks.ts

@@ -10,27 +10,27 @@ 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>)
+    onFetch?(entityFetchProps: EntityOnFetchProps<M, USER>)
         : Promise<Entity<M>> | Entity<M>;
 
     /**
      * Callback used when save is successful
      * @param entitySaveProps
      */
-    onSaveSuccess?(entitySaveProps: EntityOnSaveProps<M, UserType>)
+    onSaveSuccess?(entitySaveProps: EntityOnSaveProps<M, USER>)
         : Promise<void> | void;
 
     /**
      * Callback used when saving fails
      * @param entitySaveProps
      */
-    onSaveFailure?(entitySaveProps: EntityOnSaveFailureProps<M, UserType>)
+    onSaveFailure?(entitySaveProps: EntityOnSaveFailureProps<M, USER>)
         : Promise<void> | void;
 
     /**
@@ -39,7 +39,7 @@ export type EntityCallbacks<M extends Record<string, any> = any, UserType extend
      * error snackbar gets displayed.
      * @param entitySaveProps
      */
-    onPreSave?(entitySaveProps: EntityOnPreSaveProps<M, UserType>)
+    onPreSave?(entitySaveProps: EntityOnPreSaveProps<M, USER>)
         : Promise<Partial<EntityValues<M>>> | Partial<EntityValues<M>>;
 
     /**
@@ -49,14 +49,14 @@ 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
@@ -73,12 +73,12 @@ 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.
@@ -94,15 +94,15 @@ 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;
 }
@@ -110,8 +110,8 @@ export type EntityOnPreSaveProps<M extends Record<string, any> = any, UserType e
  * 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;
 }
@@ -120,7 +120,7 @@ export type EntityOnSaveFailureProps<M extends Record<string, any> = any, UserTy
  * 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
@@ -161,14 +161,14 @@ 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
@@ -193,7 +193,7 @@ export interface EntityOnDeleteProps<M extends Record<string, any> = any, UserTy
     /**
      * Context of the app status
      */
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 }
 
 /**

package/src/types/entity_overrides.tsx

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

package/src/types/export_import.ts

@@ -7,20 +7,20 @@ 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/src/types/fields.tsx

@@ -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
@@ -62,7 +63,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
@@ -81,14 +82,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
@@ -98,7 +95,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
@@ -110,6 +107,20 @@ export interface FieldProps<T extends CMSType = any, CustomProps = any, M extend
      */
     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;
+
 }
 
 /**
@@ -144,17 +155,29 @@ 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;
 }
 
 /**
@@ -192,20 +215,16 @@ export interface PropertyFieldBindingProps<T extends CMSType, M extends Record<s
      */
     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
@@ -223,4 +242,18 @@ 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/src/types/firecms.tsx

@@ -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.
@@ -47,7 +49,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
@@ -67,6 +69,11 @@ 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
@@ -87,9 +94,16 @@ 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'
@@ -114,7 +128,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,
@@ -124,7 +138,9 @@ export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
 
     /**
      * 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>[];
 
@@ -139,6 +155,20 @@ export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
      */
     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?: {
 
         /**

package/src/types/firecms_context.tsx

@@ -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.
@@ -18,7 +19,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
@@ -80,4 +81,20 @@ export type FireCMSContext<UserType extends User = User, AuthControllerType exte
      */
     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/src/types/index.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/src/types/internal_user_management.ts

@@ -0,0 +1,24 @@
+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;
+
+}

package/src/types/navigation.ts

@@ -1,10 +1,12 @@
 import React from "react";
 import { EntityCollection } from "./collections";
 import { EntityReference } from "./entities";
+import { FireCMSPlugin } from "./plugins";
 
 /**
  * Controller that includes the resolved navigation and utility methods and
  * attributes.
+ * This controller holds the state of the navigation including the collections.
  * @group Models
  */
 export type NavigationController<EC extends EntityCollection = EntityCollection<any>> = {
@@ -34,7 +36,7 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      * level of the navigation (e.g. in the home page or the navigation
      * drawer)
      */
-    topLevelNavigation?: TopNavigationResult;
+    topLevelNavigation?: NavigationResult;
 
     /**
      * Is the navigation loading (the configuration persistence has not
@@ -56,8 +58,13 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      * Get the collection configuration for a given path.
      * The collection is resolved from the given path or alias.
      */
-    getCollection: (pathOrId: string,
-                    includeUserOverride?: boolean) => EC | undefined;
+    getCollection: (pathOrId: string, includeUserOverride?: boolean) => EC | undefined;
+
+    /**
+     * Get the top level collection configuration for a given id
+     */
+    getCollectionById: (id: string) => EC | undefined;
+
     /**
      * Get the collection configuration from its parent ids.
      */
@@ -69,12 +76,14 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     getCollectionFromPaths: (pathSegments: string[]) => EC | undefined;
 
     /**
-     * Default path under the navigation routes of the CMS will be created
+     * Default path under the navigation routes of the CMS will be created.
+     * Defaults to '/'. You may want to change this `basepath` to 'admin' for example.
      */
     basePath: string;
 
     /**
-     * Default path under the collection routes of the CMS will be created
+     * Default path under the collection routes of the CMS will be created.
+     * It defaults to '/c'
      */
     baseCollectionPath: string;
 
@@ -87,16 +96,6 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      */
     urlPathToDataPath: (cmsPath: string) => string;
 
-    /**
-     * Convert a collection or entity path to a URL path
-     * @param path
-     */
-    buildCMSUrlPath: (path: string) => string;
-
-    buildUrlEditCollectionPath: (props: {
-        path: string
-    }) => string;
-
     /**
      * Base url path for the home screen
      */
@@ -117,10 +116,11 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
     buildUrlCollectionPath: (path: string) => string;
 
     /**
-     * Turn a path with aliases into a resolved path
+     * Turn a path with collection ids into a resolved path.
+     * The ids (typically used in urls) will be replaced with relative paths (typically used in database paths)
      * @param pathWithAliases
      */
-    resolveAliasesFrom: (pathWithAliases: string) => string;
+    resolveIdsFrom: (pathWithAliases: string) => string;
 
     /**
      * Call this method to recalculate the navigation
@@ -144,8 +144,39 @@ export type NavigationController<EC extends EntityCollection = EntityCollection<
      * @param ids
      */
     convertIdsToPaths: (ids: string[]) => string[];
+
+    /**
+     * A function to navigate to a specified route or URL.
+     *
+     * @param {string} to - The target route or URL to navigate to.
+     * @param {NavigateOptions} [options] - Optional configuration settings for navigation, such as replace behavior or state data.
+     */
+    navigate: (to: string, options?: NavigateOptions) => void;
+
+    /**
+     * Plugin system allowing to extend the CMS functionality.
+     */
+    plugins?: FireCMSPlugin<any, any, any>[];
+
+}
+
+export interface NavigateOptions {
+    replace?: boolean;
+    state?: any;
+    preventScrollReset?: boolean;
+    relative?: "route" | "path";
+    flushSync?: boolean;
+    viewTransition?: boolean;
 }
 
+// currently not used, in favor of a single blocker in `FireCMSRoute`
+export type NavigationBlocker = {
+    updateBlockListener: (path: string, block: boolean, basePath?: string) => () => void;
+    isBlocked: (path: string) => boolean;
+    proceed?: () => void;
+    reset?: () => void;
+};
+
 /**
  * Custom additional views created by the developer, added to the main
  * navigation.
@@ -173,8 +204,9 @@ export interface CMSView {
      * You can use any of the icons in the Material specs:
      * https://fonts.google.com/icons
      * e.g. 'account_tree' or 'person'
+     * Find all the icons in https://firecms.co/docs/icons
      */
-    icon?: string;
+    icon?: string | React.ReactNode;
 
     /**
      * Should this view be hidden from the main navigation panel.
@@ -197,7 +229,22 @@ export interface CMSView {
 
 }
 
-export interface TopNavigationEntry {
+/**
+ * Used to group navigation entries in the main navigation.
+ */
+export interface NavigationGroupMapping {
+    /**
+     * Name of the group, used to display the group header in the UI
+     */
+    name: string;
+    /**
+     * List of collection ids or view paths that belong to this group.
+     */
+    entries: string[];
+}
+
+export interface NavigationEntry {
+    id: string;
     url: string;
     name: string;
     path: string;
@@ -208,7 +255,14 @@ export interface TopNavigationEntry {
     group: string;
 }
 
-export type TopNavigationResult = {
-    navigationEntries: TopNavigationEntry[],
-    groups: string[]
+export type NavigationResult = {
+
+    allowDragAndDrop: boolean;
+
+    navigationEntries: NavigationEntry[],
+
+    groups: string[],
+
+    onNavigationEntriesUpdate: (entries: NavigationGroupMapping[]) => void;
 };
+

package/src/types/permissions.ts

@@ -32,7 +32,7 @@ export interface Permissions {
  * Props passed to a {@link PermissionsBuilder}
  * @group Models
  */
-export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCollection, UserType extends User = User, M extends object = InferCollectionType<EC>> {
+export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCollection, USER extends User = User, M extends object = InferCollectionType<EC>> {
     /**
      * Entity being edited, might be null in some cases, when the operation
      * refers to the collection.
@@ -54,7 +54,7 @@ export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCol
     /**
      * Logged in user
      */
-    user: UserType | null;
+    user: USER | null;
 
     /**
      * Collection these permissions apply to
@@ -64,7 +64,7 @@ export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCol
     /**
      * Auth controller
      */
-    authController: AuthController<UserType>;
+    authController: AuthController<USER>;
 }
 
 /**
@@ -72,10 +72,10 @@ export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCol
  * based on the logged user or collection.
  * @group Models
  */
-export type PermissionsBuilder<EC extends EntityCollection = EntityCollection, UserType extends User = User, M extends object = InferCollectionType<EC>> =
+export type PermissionsBuilder<EC extends EntityCollection = EntityCollection, USER extends User = User, M extends object = InferCollectionType<EC>> =
     (({
           pathSegments,
           user,
           collection,
           authController
-      }: PermissionsBuilderProps<EC, UserType, M>) => Permissions | undefined);
+      }: PermissionsBuilderProps<EC, USER, M>) => Permissions | undefined);