@firecms/core 3.0.0-canary.26 → 3.0.0-canary.261

package/src/types/plugins.tsx

@@ -1,20 +1,20 @@
 import React, { PropsWithChildren } from "react";
 
 import { FireCMSContext } from "./firecms_context";
-import { CollectionActionsProps, EntityCollection } from "./collections";
+import { CollectionActionsProps, EntityCollection, EntityTableController } from "./collections";
 import { User } from "./user";
 import { FieldProps, FormContext } from "./fields";
 import { CMSType, Property } from "./properties";
 import { EntityStatus } from "./entities";
 import { ResolvedProperty } from "./resolved_entities";
-import { CMSView } from "./navigation";
+import { NavigationGroupMapping } from "./navigation";
 
 /**
  * Interface used to define plugins for FireCMS.
  * NOTE: This is a work in progress and the API is not stable yet.
  * @group Core
  */
-export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollection = EntityCollection, COL_ACTIONS_PROPS = any> = {
+export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollection = EntityCollection, COL_ACTIONS_PROPS = any, COL_ACTIONS_START__PROPS = any> = {
 
     /**
      * Key of the plugin. This is used to identify the plugin in the CMS.
@@ -85,6 +85,20 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
             children: React.ReactNode;
         }
 
+        /**
+         * Allow reordering with drag and drop of the collections in the home page.
+         */
+        allowDragAndDrop?: boolean;
+
+        navigationEntries?: NavigationGroupMapping[];
+
+        /**
+         * This method will be called when the entries are updated in the home page.
+         * group => navigationEntriesOrder (path)
+         * @param entries
+         */
+        onNavigationEntriesUpdate?: (entries: NavigationGroupMapping[]) => void;
+
     }
 
     collectionView?: {
@@ -94,9 +108,18 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
          * toolbar.
          */
         CollectionActions?: React.ComponentType<CollectionActionsProps<any, any, EC> & COL_ACTIONS_PROPS> | React.ComponentType<CollectionActionsProps<any, any, EC> & COL_ACTIONS_PROPS>[];
-
         collectionActionsProps?: COL_ACTIONS_PROPS;
 
+        CollectionActionsStart?: React.ComponentType<CollectionActionsProps<any, any, EC> & COL_ACTIONS_START__PROPS> | React.ComponentType<CollectionActionsProps<any, any, EC> & COL_ACTIONS_START__PROPS>[];
+        collectionActionsStartProps?: COL_ACTIONS_START__PROPS;
+
+        blockSearch?: (props: {
+            context: FireCMSContext,
+            path: string,
+            collection: EC,
+            parentCollectionIds?: string[]
+        }) => boolean;
+
         showTextSearchBar?: (props: {
             context: FireCMSContext,
             path: string,
@@ -122,6 +145,7 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
             parentCollectionIds: string[],
             onHover: boolean,
             collection: EC;
+            tableController: EntityTableController;
         }>;
 
         /**
@@ -132,6 +156,7 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
             fullPath: string,
             parentCollectionIds: string[],
             collection: EC;
+            tableController: EntityTableController;
         }>;
     }
 
@@ -141,13 +166,37 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
             props?: FORM_PROPS;
         }
 
+        /**
+         * Add custom actions to the default ones ("Save", "Discard"...)
+         */
         Actions?: React.ComponentType<PluginFormActionProps<any, EC>>;
 
+        /**
+         * Add custom actions to the top of the form
+         */
+        ActionsTop?: React.ComponentType<PluginFormActionProps<any, EC>>;
+
         fieldBuilder?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T, any, EC>) => React.ComponentType<FieldProps<T>> | null;
 
         fieldBuilderEnabled?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T>) => boolean;
     }
 
+    collection?: {
+
+        /**
+         * Use this method to modify a single collection before it is rendered.
+         * @param collection
+         */
+        modifyCollection?: (collection: EntityCollection) => EntityCollection;
+
+        /**
+         * Use this method to modify, add or remove collections.
+         * @param collections
+         */
+        injectCollections?: (collections: EntityCollection[]) => EntityCollection[];
+
+    }
+
 }
 
 /**
@@ -156,7 +205,7 @@ export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollec
  *
  * @group Models
  */
-export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, any> = any, UserType extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
+export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, any> = any, USER extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
     /**
      * Collection path of this entity. This is the full path, like
      * `users/1234/addresses`
@@ -171,20 +220,22 @@ export interface PluginHomePageActionsProps<EP extends object = object, M extend
     /**
      * Context of the app status
      */
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 
     extraProps?: EP;
 
 }
 
-export interface PluginFormActionProps<UserType extends User = User, EC extends EntityCollection = EntityCollection> {
+export interface PluginFormActionProps<USER extends User = User, EC extends EntityCollection = EntityCollection> {
     entityId?: string;
     path: string;
+    parentCollectionIds: string[];
     status: EntityStatus;
     collection: EC;
+    disabled: boolean;
     formContext?: FormContext<any>;
-    context: FireCMSContext<UserType>;
-    currentEntityId?: string;
+    context: FireCMSContext<USER>;
+    openEntityMode: "side_panel" | "full_screen";
 }
 
 export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Record<string, any> = any, EC extends EntityCollection<M> = EntityCollection<M>> = {
@@ -193,15 +244,15 @@ export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Reco
     property: Property<T> | ResolvedProperty<T>;
     Field: React.ComponentType<FieldProps<T, any, M>>;
     plugin: FireCMSPlugin;
-    path: string;
-    collection: EC;
+    path?: string;
+    collection?: EC;
 };
 
-export interface PluginGenericProps<UserType extends User = User> {
-    context: FireCMSContext<UserType>;
+export interface PluginGenericProps<USER extends User = User> {
+    context: FireCMSContext<USER>;
 }
 
-export interface PluginHomePageAdditionalCardsProps<UserType extends User = User> {
+export interface PluginHomePageAdditionalCardsProps<USER extends User = User> {
     group?: string;
-    context: FireCMSContext<UserType>;
+    context: FireCMSContext<USER>;
 }

package/src/types/properties.ts

@@ -1,10 +1,11 @@
 import React from "react";
 import { FieldProps } from "./fields";
 import { PropertyPreviewProps } from "../preview";
-import { EntityReference, EntityValues, GeoPoint } from "./entities";
+import { EntityReference, EntityValues, GeoPoint, Vector } from "./entities";
 import { ResolvedArrayProperty, ResolvedStringProperty } from "./resolved_entities";
 import { FilterValues } from "./collections";
 import { ChipColorKey, ChipColorScheme } from "@firecms/ui";
+import { AuthController } from "./auth";
 
 /**
  * @group Entity properties
@@ -15,9 +16,10 @@ export type DataType<T extends CMSType = CMSType> =
             T extends boolean ? "boolean" :
                 T extends Date ? "date" :
                     T extends GeoPoint ? "geopoint" :
-                        T extends EntityReference ? "reference" :
-                            T extends Array<CMSType> ? "array" :
-                                T extends Record<string, any> ? "map" : never;
+                        T extends Vector ? "vector" :
+                            T extends EntityReference ? "reference" :
+                                T extends Array<any> ? "array" :
+                                    T extends Record<string, any> ? "map" : never;
 
 /**
  * @group Entity properties
@@ -48,7 +50,7 @@ export type AnyProperty =
 /**
  * @group Entity properties
  */
-export type Property<T extends CMSType = CMSType> =
+export type Property<T extends CMSType = any> =
     T extends string ? StringProperty :
         T extends number ? NumberProperty :
             T extends boolean ? BooleanProperty :
@@ -148,13 +150,19 @@ export interface BaseProperty<T extends CMSType, CustomProps = any> {
     /**
      * This value will be set by default for new entities.
      */
-    defaultValue?: T;
+    defaultValue?: T | null;
 
     /**
      * Should this property be editable. If set to true, the user will be able to modify the property and
      * save the new config. The saved config will then become the source of truth.
      */
     editable?: boolean;
+
+    /**
+     * A number between 0 and 100 that indicates the width of the field in the form view.
+     * It defaults to 100, but you can set it to 50 to have two fields in the same row.
+     */
+    widthPercentage?: number;
 }
 
 /**
@@ -263,6 +271,11 @@ export type PropertyBuilderProps<M extends Record<string, any> = any> =
          * Entity ID
          */
         entityId?: string;
+
+        /**
+         * Controller to manage authentication
+         */
+        authController: AuthController;
     };
 
 /**
@@ -276,21 +289,23 @@ export type PropertyBuilder<T extends CMSType = any, M extends Record<string, an
          values,
          previousValues,
          propertyValue,
+         index,
          path,
-         entityId
+         entityId,
+         authController
      }: PropertyBuilderProps<M>) => Property<T> | null;
 
 /**
  * @group Entity properties
  */
-export type PropertyOrBuilder<T extends CMSType = CMSType, M extends Record<string, any> = Record<string, any>> =
+export type PropertyOrBuilder<T extends CMSType = CMSType, M extends Record<string, any> = any> =
     Property<T>
     | PropertyBuilder<T, M>;
 
 /**
  * @group Entity properties
  */
-export type PropertiesOrBuilders<M extends Record<string, any> = Record<string, any>> =
+export type PropertiesOrBuilders<M extends Record<string, any> = any> =
     {
         [k in keyof M]: PropertyOrBuilder<M[k], M>;
     };
@@ -369,7 +384,7 @@ export interface StringProperty extends BaseProperty<string> {
 
     /**
      * You can specify a `Storage` configuration. It is used to
-     * indicate that this string refers to a path in Google Cloud Storage.
+     * indicate that this string refers to a path in your storage provider.
      */
     storage?: StorageConfig;
 
@@ -398,12 +413,20 @@ export interface StringProperty extends BaseProperty<string> {
      * Add an icon to clear the value and set it to `null`. Defaults to `false`
      */
     clearable?: boolean;
+
+    /**
+     * You can use this property (a string) to behave as a reference to another
+     * collection. The stored value is the ID of the entity in the
+     * collection, and the `path` prop is used to
+     * define the collection this reference points to.
+     */
+    reference?: ReferenceProperty;
 }
 
 /**
  * @group Entity properties
  */
-export interface ArrayProperty<T extends ArrayT[] = any[], ArrayT extends CMSType = CMSType> extends BaseProperty<T> {
+export interface ArrayProperty<T extends ArrayT[] = any[], ArrayT extends CMSType = any> extends BaseProperty<T> {
 
     dataType: "array";
 
@@ -467,6 +490,24 @@ export interface ArrayProperty<T extends ArrayT[] = any[], ArrayT extends CMSTyp
      */
     expanded?: boolean;
 
+    /**
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel.
+     */
+    minimalistView?: boolean;
+
+    /**
+     * Can the elements in this array be reordered. Defaults to `true`.
+     * This prop has no effect if `disabled` is set to true.
+     */
+    sortable?: boolean;
+
+    /**
+     * Can the elements in this array be added. Defaults to `true`
+     * This prop has no effect if `disabled` is set to true.
+     */
+    canAddElements?: boolean;
+
 }
 
 /**
@@ -515,6 +556,12 @@ export interface MapProperty<T extends Record<string, CMSType> = Record<string,
      */
     spreadChildren?: boolean;
 
+    /**
+     * Display the child properties directly, without being wrapped in an
+     * extendable panel. Note that this will also hide the title of this property.
+     */
+    minimalistView?: boolean;
+
     /**
      * Should the field be initially expanded. Defaults to `true`
      */
@@ -608,6 +655,16 @@ export interface ReferenceProperty extends BaseProperty<EntityReference> {
      */
     previewProperties?: string[];
 
+    /**
+     * Should the reference include the ID of the entity. Defaults to `true`
+     */
+    includeId?: boolean;
+
+    /**
+     * Should the reference include a link to the entity (open the entity details). Defaults to `true`
+     */
+    includeEntityLink?: boolean;
+
 }
 
 /**
@@ -722,13 +779,13 @@ export type StorageConfig = {
      * You can use this prop to customize the uploaded filename.
      * You can use a function as a callback or a string where you
      * specify some placeholders that get replaced with the corresponding values.
-     * - {file} - Full file name
-     * - {file.name} - Name of the file without extension
-     * - {file.ext} - Extension of the file
-     * - {rand} - Random value used to avoid name collisions
-     * - {entityId} - ID of the entity
-     * - {propertyKey} - ID of this property
-     * - {path} - Path of this entity
+     * - `{file}` - Full file name
+     * - `{file.name}` - Name of the file without extension
+     * - `{file.ext}` - Extension of the file
+     * - `{rand}` - Random value used to avoid name collisions
+     * - `{entityId}` - ID of the entity
+     * - `{propertyKey}` - ID of this property
+     * - `{path}` - Path of this entity
      *
      * @param context
      */
@@ -739,13 +796,13 @@ export type StorageConfig = {
      *
      * You can use a function as a callback or a string where you
      * specify some placeholders that get replaced with the corresponding values.
-     * - {file} - Full file name
-     * - {file.name} - Name of the file without extension
-     * - {file.ext} - Extension of the file
-     * - {rand} - Random value used to avoid name collisions
-     * - {entityId} - ID of the entity
-     * - {propertyKey} - ID of this property
-     * - {path} - Path of this entity
+     * - `{file}` - Full file name
+     * - `{file.name}` - Name of the file without extension
+     * - `{file.ext}` - Extension of the file
+     * - `{rand}` - Random value used to avoid name collisions
+     * - `{entityId}` - ID of the entity
+     * - `{propertyKey}` - ID of this property
+     * - `{path}` - Path of this entity
      */
     storagePath: string | ((context: UploadedFileContext) => string);
 
@@ -766,12 +823,24 @@ export type StorageConfig = {
      */
     maxSize?: number,
 
+    /**
+     * Use this callback to process the file before uploading it to the storage.
+     * If nothing is returned, the file is uploaded as it is.
+     * @param file
+     */
+    processFile?: (file: File) => Promise<File> | undefined;
+
     /**
      * Postprocess the saved value (storage path or URL)
      * after it has been resolved.
      */
     postProcess?: (pathOrUrl: string) => Promise<string>;
 
+    /**
+     * You can use this prop in order to provide a custom preview URL.
+     * Useful when the file's path is different from the original field value
+     */
+    previewUrl?: (fileName: string) => string;
 }
 
 /**
@@ -801,7 +870,7 @@ export interface UploadedFileContext {
     /**
      * Entity path. E.g. `products/PID/locales`
      */
-    path: string;
+    path?: string;
 
     /**
      * Values of the current entity

package/src/types/property_config.tsx

@@ -23,8 +23,6 @@ export type PropertyConfig<T extends CMSType = any> = {
      * Default config for the property.
      * This property or builder will be used as the base values for the resulting property.
      * You can also use a builder function to generate the base property.
-     * You can use a builder function to generate the property based on the values or the path.
-     * You can also define a custom Field as a React component to be used for this property.
      */
     property: PropertyOrBuilder<T>;
 
@@ -64,6 +62,7 @@ export type PropertyConfigId =
     "group" |
     "key_value" |
     "reference" |
+    "reference_as_string" |
     "multi_references" |
     "switch" |
     "date_time" |

package/src/types/roles.ts

@@ -30,6 +30,9 @@ export type Role = {
      */
     collectionPermissions?: Record<string, Permissions>;
 
+    /**
+     * Permissions related to editing the collections
+     */
     config?: {
 
         createCollections?: boolean;

package/src/types/side_dialogs_controller.tsx

@@ -1,3 +1,6 @@
+import React from "react";
+import { EntityFormProps } from "../form";
+
 /**
  * Controller to open the side dialog
  * @group Hooks and utilities
@@ -14,6 +17,12 @@ export interface SideDialogsController {
      */
     sidePanels: SideDialogPanelProps[];
 
+    /**
+     * Override the current side panels
+     * @param panels
+     */
+    setSidePanels: (panels: SideDialogPanelProps[]) => void;
+
     /**
      * Open one or multiple side panels
      * @param props
@@ -65,4 +74,10 @@ export interface SideDialogPanelProps {
      * Callback when the panel is closed
      */
     onClose?: () => void;
+
+    /**
+     * Use this prop to store additional data in the panel
+     */
+    additional?: any;
+
 }

package/src/types/side_entity_controller.tsx

@@ -2,6 +2,7 @@ import { EntityCollection } from "./collections";
 import { ResolvedEntityCollection } from "./resolved_entities";
 import { Entity } from "./entities";
 import { EntityOverrides } from "./entity_overrides";
+import { EntityFormProps } from "../form";
 
 /**
  * Props used to open a side dialog
@@ -14,6 +15,11 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      */
     path: string;
 
+    /**
+     * Full CMS path of the entity, including the collection and sub-collections.
+     */
+    fullIdPath?: string;
+
     /**
      * ID of the entity, if not set, it means we are creating a new entity
      */
@@ -28,7 +34,7 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      * Open the entity with a selected sub-collection view. If the panel for this
      * entity was already open, it is replaced.
      */
-    selectedSubPath?: string;
+    selectedTab?: string;
 
     /**
      * Use this prop to override the width of the form view.
@@ -66,6 +72,15 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      */
     closeOnSave?: boolean;
 
+    /**
+     * Override some form properties
+     */
+    formProps?: Partial<EntityFormProps<M>>;
+
+    /**
+     * Allow the user to open the entity fullscreen
+     */
+    allowFullScreen?: boolean;
 }
 
 /**

package/src/types/storage.ts

@@ -101,5 +101,87 @@ export interface StorageSource {
      * @param props
      * @param bucket
      */
-    getFile: (path:string, bucket?: string) => Promise<File | null>;
+    getFile: (path: string, bucket?: string) => Promise<File | null>;
+
+    /**
+     * Delete a file.
+     * @param path
+     * @param bucket
+     */
+    deleteFile: (path: string, bucket?: string) => Promise<void>;
+
+    /**
+     * List the contents of a path.
+     * @param path
+     * @param options
+     */
+    list: (path: string, options?: {
+        bucket?: string,
+        maxResults?: number,
+        pageToken?: string
+    }) => Promise<StorageListResult>;
+
+}
+
+/**
+ * Result returned by list().
+ * @public
+ */
+export declare interface StorageListResult {
+    /**
+     * References to prefixes (sub-folders). You can call list() on them to
+     * get its contents.
+     *
+     * Folders are implicit based on '/' in the object paths.
+     * For example, if a bucket has two objects '/a/b/1' and '/a/b/2', list('/a')
+     * will return '/a/b' as a prefix.
+     */
+    prefixes: StorageReference[];
+    /**
+     * Objects in this directory.
+     * You can call getMetadata() and getDownloadUrl() on them.
+     */
+    items: StorageReference[];
+    /**
+     * If set, there might be more results for this list. Use this token to resume the list.
+     */
+    nextPageToken?: string;
+}
+
+/**
+ * Represents a reference to a Google Cloud Storage object. Developers can
+ * upload, download, and delete objects, as well as get/set object metadata.
+ * @public
+ */
+export declare interface StorageReference {
+    /**
+     * Returns a gs:// URL for this object in the form
+     *   `gs://<bucket>/<path>/<to>/<object>`
+     * @returns The gs:// URL.
+     */
+    toString(): string;
+
+    /**
+     * A reference to the root of this object's bucket.
+     */
+    root: StorageReference;
+    /**
+     * The name of the bucket containing this reference's object.
+     */
+    bucket: string;
+    /**
+     * The full path of this object.
+     */
+    fullPath: string;
+    /**
+     * The short name of this object, which is the last component of the full path.
+     * For example, if fullPath is 'full/path/image.png', name is 'image.png'.
+     */
+    name: string;
+
+    /**
+     * A reference pointing to the parent location of this reference, or null if
+     * this reference is the root.
+     */
+    parent: StorageReference | null;
 }

package/src/types/user.ts

@@ -41,4 +41,6 @@ export type User = {
      */
     roles?: Role[];
 
+    getIdToken?: (forceRefresh?: boolean) => Promise<string>;
+
 };

package/src/util/builders.ts

@@ -26,10 +26,12 @@ import {
  * @param collection
  * @group Builder
  */
-export function buildCollection<M extends Record<string, any> = any,
-    UserType extends User = User>(
-    collection: EntityCollection<M, UserType>
-): EntityCollection<M, UserType> {
+export function buildCollection<
+    M extends Record<string, any> = any,
+    USER extends User = User>
+(
+    collection: EntityCollection<M, USER>
+): EntityCollection<M, USER> {
     return collection;
 }
 
@@ -39,7 +41,7 @@ export function buildCollection<M extends Record<string, any> = any,
  * @param property
  * @group Builder
  */
-export function buildProperty<T extends CMSType = CMSType, P extends PropertyOrBuilder<T> = PropertyOrBuilder<T>, M extends Record<string, any> = Record<string, any>>(
+export function buildProperty<T extends CMSType = CMSType, P extends PropertyOrBuilder<T> = PropertyOrBuilder<T>, M extends Record<string, any> = any>(
     property: P
 ):
     P extends StringProperty ? StringProperty :
@@ -120,9 +122,9 @@ export function buildEntityCallbacks<M extends Record<string, any> = any>(
  * @param additionalFieldDelegate
  * @group Builder
  */
-export function buildAdditionalFieldDelegate<M extends Record<string, any>, UserType extends User = User>(
-    additionalFieldDelegate: AdditionalFieldDelegate<M, UserType>
-): AdditionalFieldDelegate<M, UserType> {
+export function buildAdditionalFieldDelegate<M extends Record<string, any>, USER extends User = User>(
+    additionalFieldDelegate: AdditionalFieldDelegate<M, USER>
+): AdditionalFieldDelegate<M, USER> {
     return additionalFieldDelegate;
 }