@firecms/core 3.0.0-beta.11 → 3.0.0-beta.13

package/src/types/dialogs_controller.tsx

@@ -15,19 +15,23 @@ export interface DialogsController {
      * Open a dialog
      * @param props
      */
-    open: (props: DialogControllerEntryProps) => { closeDialog: () => void };
+    open: <T extends object = object>(props: DialogControllerEntryProps<T>) => { closeDialog: () => void };
 }
 
 /**
  * Props used to open a side dialog
  * @group Hooks and utilities
  */
-export interface DialogControllerEntryProps {
+export interface DialogControllerEntryProps<T extends object = object> {
 
     key: string;
     /**
      * The component type that will be rendered
      */
-    Component: React.ComponentType<{ open: boolean, closeDialog: () => void }>;
+    Component: React.ComponentType<{ open: boolean, closeDialog: () => void } & T>;
+    /**
+     * Props to pass to the dialog component
+     */
+    props?: T;
 
 }

package/src/types/entities.ts

@@ -8,7 +8,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

package/src/types/entity_actions.tsx

@@ -15,6 +15,16 @@ export type EntityAction<M extends object = any, USER extends User = User> = {
      */
     name: string;
 
+    /**
+     * Key of the action. You only need to provide this if you want to
+     * override the default actions.
+     * The default actions are:
+     * - edit
+     * - delete
+     * - copy
+     */
+    key?: string;
+
     /**
      * Icon of the action
      */
@@ -53,4 +63,6 @@ export type EntityActionClickProps<M extends object, USER extends User = User> =
      * If this actions is being called from a side dialog
      */
     sideEntityController?: SideEntityController;
+
+    openEntityMode: "side_panel" | "full_screen";
 };

package/src/types/fields.tsx

@@ -1,6 +1,7 @@
 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
@@ -81,7 +82,8 @@ export interface FieldProps<T extends CMSType = any, CustomProps = any, M extend
     partOfArray?: boolean;
 
     /**
-     * Should this field render with the minimal amount of UI elements
+     * 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;
 
@@ -160,10 +162,22 @@ export interface FormContext<M extends Record<string, any> = any> {
      */
     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;
 }
 
 /**
@@ -207,7 +221,8 @@ export interface PropertyFieldBindingProps<T extends CMSType, M extends Record<s
     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.
      */
     minimalistView?: boolean;
 

package/src/types/firecms.tsx

@@ -47,7 +47,7 @@ export type CMSViewsBuilder = (params: {
 /**
  * @group Models
  */
-export type FireCMSProps<USER extends User, EC extends EntityCollection> = {
+export type FireCMSProps<USER extends User> = {
 
     /**
      * Use this function to return the components you want to render under

package/src/types/navigation.ts

@@ -5,6 +5,7 @@ import { EntityReference } from "./entities";
 /**
  * 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>> = {
@@ -56,8 +57,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 +75,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 +95,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 +115,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 +143,34 @@ 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;
+
 }
 
+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.

package/src/types/plugins.tsx

@@ -192,9 +192,11 @@ export interface PluginFormActionProps<USER extends User = User, EC extends Enti
     path: string;
     status: EntityStatus;
     collection: EC;
+    disabled: boolean;
     formContext?: FormContext<any>;
     context: FireCMSContext<USER>;
     currentEntityId?: string;
+    openEntityMode: "side_panel" | "full_screen";
 }
 
 export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Record<string, any> = any, EC extends EntityCollection<M> = EntityCollection<M>> = {

package/src/types/properties.ts

@@ -5,6 +5,7 @@ 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
@@ -156,6 +157,12 @@ export interface BaseProperty<T extends CMSType, CustomProps = any> {
      * 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;
 }
 
 /**
@@ -264,6 +271,11 @@ export type PropertyBuilderProps<M extends Record<string, any> = any> =
          * Entity ID
          */
         entityId?: string;
+
+        /**
+         * Controller to manage authentication
+         */
+        authController: AuthController;
     };
 
 /**
@@ -279,20 +291,21 @@ export type PropertyBuilder<T extends CMSType = any, M extends Record<string, an
          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>;
     };
@@ -371,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;
 
@@ -469,6 +482,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;
+
 }
 
 /**
@@ -517,6 +548,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`
      */
@@ -778,6 +815,13 @@ 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.

package/src/types/side_dialogs_controller.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { EntityFormProps } from "../form";
 
 /**
  * Controller to open the side dialog
@@ -78,4 +79,5 @@ export interface SideDialogPanelProps {
      * 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
@@ -19,6 +20,11 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      */
     entityId?: string;
 
+    // /**
+    //  * Navigation path with ids of the entity
+    //  */
+    // fullIdPath: string;
+
     /**
      * Set this flag to true if you want to make a copy of an existing 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,10 @@ export interface EntitySidePanelProps<M extends Record<string, any> = any> {
      */
     closeOnSave?: boolean;
 
+    /**
+     * Override some form properties
+     */
+    formProps?: Partial<EntityFormProps<M>>;
 }
 
 /**

package/src/util/builders.ts

@@ -26,8 +26,10 @@ import {
  * @param collection
  * @group Builder
  */
-export function buildCollection<M extends Record<string, any> = any,
-    USER extends User = User>(
+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 :

package/src/util/createFormexStub.tsx

@@ -0,0 +1,62 @@
+import { FormexController } from "@firecms/formex";
+
+export function createFormexStub<T extends object>(values: T): FormexController<T> {
+    const errorMessage = "You are in a read-only context. You cannot modify the formex controller.";
+
+    return {
+        values,
+        initialValues: values,
+        touched: {} as Record<string, boolean>,
+        dirty: false,
+        errors: {} as Record<string, string>,
+        submitCount: 0,
+        isSubmitting: false,
+        isValidating: false,
+        version: 0,
+        canUndo: false,
+        canRedo: false,
+
+        setValues: () => {
+            throw new Error(errorMessage);
+        },
+        setFieldValue: () => {
+            throw new Error(errorMessage);
+        },
+        setFieldTouched: () => {
+            throw new Error(errorMessage);
+        },
+        setDirty: () => {
+            throw new Error(errorMessage);
+        },
+        setSubmitCount: () => {
+            throw new Error(errorMessage);
+        },
+        setFieldError: () => {
+            throw new Error(errorMessage);
+        },
+        handleChange: () => {
+            throw new Error(errorMessage);
+        },
+        handleBlur: () => {
+            throw new Error(errorMessage);
+        },
+        handleSubmit: () => {
+            throw new Error(errorMessage);
+        },
+        validate: () => {
+            throw new Error(errorMessage);
+        },
+        resetForm: () => {
+            throw new Error(errorMessage);
+        },
+        setSubmitting: () => {
+            throw new Error(errorMessage);
+        },
+        undo: () => {
+            throw new Error(errorMessage);
+        },
+        redo: () => {
+            throw new Error(errorMessage);
+        }
+    };
+}

package/src/util/entity_actions.ts

@@ -0,0 +1,28 @@
+import { EntityAction } from "../types";
+
+const reservedKeys = ["edit", "copy", "delete"];
+
+export function mergeEntityActions(currentActions: EntityAction[], newActions: EntityAction[]): EntityAction[] {
+    // given the current actions, replace the ones with the same key
+    // and append the new ones
+    const updatedActions: EntityAction[] = [];
+    currentActions.forEach(action => {
+        const newAction = newActions.find(a => a.key === action.key);
+        if (newAction) {
+            const mergedAction = {
+                ...action,
+                ...newAction
+            }
+            updatedActions.push(mergedAction);
+        } else {
+            updatedActions.push(action);
+        }
+    });
+    newActions.forEach(action => {
+        if (!currentActions.find(a => a.key === action.key) && (!action.key || !reservedKeys.includes(action.key))) {
+            updatedActions.push(action);
+        }
+    });
+    return updatedActions;
+
+}