@firecms/core 3.0.0-alpha.7 → 3.0.0-alpha.70

package/src/types/entity_callbacks.ts

@@ -0,0 +1,209 @@
+import { EntityCollection } from "./collections";
+import { Entity, EntityStatus, EntityValues, } from "./entities";
+import { FireCMSContext } from "./firecms_context";
+import { ResolvedEntityCollection } from "./resolved_entities";
+import { User } from "./user";
+
+/**
+ * This interface defines all the callbacks that can be used when an entity
+ * is being created, updated or deleted.
+ * 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> = {
+
+    /**
+     * Callback used after fetching data
+     * @param entityFetchProps
+     */
+    onFetch?(entityFetchProps: EntityOnFetchProps<M, UserType>)
+        : Promise<Entity<M>> | Entity<M>;
+
+    /**
+     * Callback used when save is successful
+     * @param entitySaveProps
+     */
+    onSaveSuccess?(entitySaveProps: EntityOnSaveProps<M, UserType>)
+        : Promise<void> | void;
+
+    /**
+     * Callback used when saving fails
+     * @param entitySaveProps
+     */
+    onSaveFailure?(entitySaveProps: EntityOnSaveProps<M, UserType>)
+        : 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: EntityOnSaveProps<M, UserType>)
+        : 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
+     * error snackbar gets displayed.
+     *
+     * @param entityDeleteProps
+     */
+    onPreDelete?(entityDeleteProps: EntityOnDeleteProps<M, UserType>): void;
+
+    /**
+     * Callback used after the entity is deleted.
+     *
+     * @param entityDeleteProps
+     */
+    onDelete?(entityDeleteProps: EntityOnDeleteProps<M, UserType>): 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.
+     * The returned string will be used as the ID of the entity.
+     *
+     * @param idUpdateProps
+     */
+    onIdUpdate?(idUpdateProps: EntityIdUpdateProps<M>): string;
+}
+
+/**
+ * Parameters passed to hooks when an entity is fetched
+ * @group Models
+ */
+export interface EntityOnFetchProps<M extends Record<string, any> = any, UserType extends User = User> {
+
+    /**
+     * Collection of the entity
+     */
+    collection: EntityCollection<M>;
+
+    /**
+     * Full path of the CMS where this collection is being fetched.
+     * Might contain unresolved aliases.
+     */
+    path: string;
+
+    /**
+     * Fetched entity
+     */
+    entity: Entity<M>
+
+    /**
+     * Context of the app status
+     */
+    context: FireCMSContext<UserType>;
+}
+
+/**
+ * Parameters passed to hooks when an entity is saved
+ * @group Models
+ */
+export interface EntityOnSaveProps<M extends Record<string, any> = any, UserType extends User = User> {
+
+    /**
+     * Resolved collection of the entity
+     */
+    collection: ResolvedEntityCollection<M>;
+
+    /**
+     * Full path of the CMS where this entity is being saved.
+     * Might contain unresolved aliases.
+     */
+    path: string;
+
+    /**
+     * Full path where this entity is being saved, with alias resolved
+     */
+    resolvedPath: string;
+
+    /**
+     * ID of the entity
+     */
+    entityId?: string;
+
+    /**
+     * Values being saved
+     */
+    values: Partial<EntityValues<M>>;
+
+    /**
+     * Previous values
+     */
+    previousValues?: Partial<EntityValues<M>>;
+
+    /**
+     * New or existing entity
+     */
+    status: EntityStatus;
+
+    /**
+     * Context of the app status
+     */
+    context: FireCMSContext<UserType>;
+}
+
+/**
+ * Parameters passed to hooks when an entity is deleted
+ * @group Models
+ */
+export interface EntityOnDeleteProps<M extends Record<string, any> = any, UserType extends User = User> {
+
+    /**
+     * collection of the entity being deleted
+     */
+    collection: ResolvedEntityCollection<M>;
+
+    /**
+     * Path of the parent collection
+     */
+    path: string;
+
+    /**
+     * Deleted entity id
+     */
+    entityId: string;
+
+    /**
+     * Deleted entity
+     */
+    entity: Entity<M>;
+
+    /**
+     * Context of the app status
+     */
+    context: FireCMSContext;
+}
+
+/**
+ * Parameters passed to hooks when an entity is deleted
+ * @group Models
+ */
+export interface EntityIdUpdateProps<M extends Record<string, any> = any> {
+
+    /**
+     * collection of the entity being deleted
+     */
+    collection: ResolvedEntityCollection<M>;
+
+    /**
+     * Path of the parent collection
+     */
+    path: string;
+
+    /**
+     * Current entity id
+     */
+    entityId?: string;
+
+    /**
+     * Entity values
+     */
+    values: EntityValues<M>;
+
+    /**
+     * Context of the app status
+     */
+    context: FireCMSContext;
+}

package/src/types/entity_link_builder.ts

@@ -0,0 +1,8 @@
+import { Entity } from "./entities";
+
+/**
+ * @group Models
+ */
+export type EntityLinkBuilder<M extends Record<string, any> = any> = ({ entity }: {
+    entity: Entity<M>
+}) => string;

package/src/types/export_import.ts

@@ -0,0 +1,26 @@
+import { User } from "./user";
+import { Entity } from "./entities";
+import { FireCMSContext } from "./firecms_context";
+
+/**
+ * You can use this configuration to add additional fields to the data
+ * exports
+ * @group Models
+ */
+export interface ExportConfig<UserType extends User = User> {
+    additionalFields: ExportMappingFunction<UserType> [];
+}
+
+/**
+ * @group Models
+ */
+export interface ExportMappingFunction<UserType extends User = User> {
+    key: string;
+    builder: ({
+                  entity,
+                  context
+              }: {
+        entity: Entity<any>,
+        context: FireCMSContext<UserType>
+    }) => Promise<string> | string;
+}

package/src/types/fields.tsx

@@ -0,0 +1,220 @@
+import { EntityValues } from "./entities";
+import { CMSType, PropertyOrBuilder } from "./properties";
+import { ResolvedEntityCollection, ResolvedProperty } from "./resolved_entities";
+
+/**
+ * When building a custom field you need to create a React component that takes
+ * this interface as props.
+ *
+ * @group Form custom fields
+ */
+export interface FieldProps<T extends CMSType = any, CustomProps = any, M extends Record<string, any> = any> {
+
+    /**
+     * Key of the property
+     * E.g. "user.name" for a property with path "user.name"
+     */
+    propertyKey: string;
+
+    /**
+     * Current value of this field
+     */
+    value: T;
+
+    /**
+     * Initial value of this field
+     */
+    initialValue: T | undefined;
+
+    /**
+     * Set value of field directly
+     */
+    setValue: (value: T | null, shouldValidate?: boolean) => void;
+
+    /**
+     * Set value of a different field directly
+     * @param propertyKey
+     * @param value
+     * @param shouldValidate
+     */
+    setFieldValue: (propertyKey: string, value: CMSType | null, shouldValidate?: boolean) => void;
+
+    /**
+     * Is the form currently submitting
+     */
+    isSubmitting: boolean;
+
+    /**
+     * Should this field show the error indicator.
+     * Note that there might be an error (like an empty field that should be
+     * filled) but we don't want to show the error until the user has tried
+     * saving.
+     */
+    showError: boolean;
+
+    /**
+     * Is there an error in this field. The error field has the same shape as
+     * the field, replacing values with a string containing the error.
+     * It takes the value `null` if there is no error
+     */
+    error: any | null;
+
+    /**
+     * Has this field been touched
+     */
+    touched: boolean;
+
+    /**
+     * Property related to this field
+     */
+    property: ResolvedProperty<T>;
+
+    /**
+     * Should this field include a description
+     */
+    includeDescription: boolean;
+
+    /**
+     * Flag to indicate that the underlying value has been updated in the
+     * datasource
+     */
+    underlyingValueHasChanged: boolean;
+
+    /**
+     * Is this field part of an array
+     */
+    partOfArray: boolean;
+
+    /**
+     * Is this field part of a block (oneOf array)
+     */
+    partOfBlock: boolean;
+
+    /**
+     * Is this field being rendered in the entity table popup
+     */
+    tableMode: boolean;
+
+    /**
+     * Should this field autofocus on mount
+     */
+    autoFocus: boolean;
+
+    /**
+     * Additional properties set by the developer
+     */
+    customProps: CustomProps
+
+    /**
+     * Additional values related to the state of the form or the entity
+     */
+    context: FormContext<M>;
+
+    /**
+     * Flag to indicate if this field should be disabled
+     */
+    disabled: boolean;
+
+}
+
+/**
+ * Context passed to custom fields
+ * @group Form custom fields
+ */
+export interface FormContext<M extends Record<string, any> = any> {
+
+    /**
+     * Collection of the entity being modified
+     */
+    collection: ResolvedEntityCollection<M>;
+
+    /**
+     * Current values of the entity
+     */
+    values: EntityValues<M>;
+
+    /**
+     * Entity id, it can be null if it's a new entity
+     */
+    entityId?: string;
+
+    /**
+     * Path this entity is located at
+     */
+    path: string;
+
+    /**
+     * Update the value of a field
+     * @param key
+     * @param value
+     * @param shouldValidate
+     */
+    setFieldValue: (key: string, value: any, shouldValidate?: boolean) => void;
+
+    /**
+     * Save the entity
+     */
+    save: (values: EntityValues<M>) => void;
+}
+
+/**
+ * In case you need to render a field bound to a Property inside your
+ * custom field you can use {@link PropertyFieldBinding} with these props.
+ * @group Form custom fields
+ */
+export interface PropertyFieldBindingProps<T extends CMSType, M extends Record<string, any> = any> {
+
+    /**
+     * The key/path of the property, such as `age`. You can use nested and array
+     * indexed such as `address.street` or `people[3]`
+     */
+    propertyKey: string;
+
+    /**
+     * The CMS property you are binding this field to
+     */
+    property: PropertyOrBuilder<T> | ResolvedProperty<T>;
+
+    /**
+     * The context where this field is being rendered. You get a context as a
+     * prop when creating a custom field.
+     */
+    context: FormContext<M>;
+
+    /**
+     * Should the description be included in this field
+     */
+    includeDescription?: boolean;
+
+    /**
+     * Has the value of this property been updated in the database while this
+     * 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)
+     */
+    partOfBlock?: 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.
+     */
+    autoFocus?: boolean;
+
+    /**
+     * Should this field be disabled
+     */
+    disabled?: boolean;
+}

package/src/types/firecms.tsx

@@ -0,0 +1,175 @@
+import React from "react";
+import { User } from "./user";
+import { AuthController } from "./auth";
+import { DataSourceDelegate } from "./datasource";
+import { EntityCollection, EntityCustomView } from "./collections";
+import { CMSView } from "./navigation";
+import { FireCMSContext } from "./firecms_context";
+import { PropertyConfig } from "./property_config";
+import { Locale } from "./locales";
+import { StorageSource } from "./storage";
+import { EntityLinkBuilder } from "./entity_link_builder";
+import { UserConfigurationPersistence } from "./local_config_persistence";
+import { FireCMSPlugin } from "./plugins";
+import { CMSAnalyticsEvent } from "./analytics";
+
+/**
+ * Use this callback to build entity collections dynamically.
+ * You can use the user to decide which collections to show.
+ * You can also use the data source to fetch additional data to build the
+ * collections.
+ * Note: you can use any type of synchronous or asynchronous code here,
+ * including fetching data from external sources, like using the Firestore
+ * APIs directly, or a REST API.
+ * @group Models
+ */
+export type EntityCollectionsBuilder<EC extends EntityCollection = EntityCollection> = (params: {
+    user: User | null,
+    authController: AuthController,
+    dataSource: DataSourceDelegate
+}) => EC[] | Promise<EC[]>;
+
+/**
+ * Use this callback to build custom views dynamically.
+ * You can use the user to decide which views to show.
+ * You can also use the data source to fetch additional data to build the
+ * views. Note: you can use any type of synchronous or asynchronous code here,
+ * including fetching data from external sources, like using the Firestore
+ * APIs directly, or a REST API.
+ * @group Models
+ */
+export type CMSViewsBuilder = (params: {
+    user: User | null,
+    authController: AuthController,
+    dataSource: DataSourceDelegate
+}) => CMSView[] | Promise<CMSView[]>;
+
+/**
+ * @group Models
+ */
+export type FireCMSProps<UserType extends User, EC extends EntityCollection> = {
+
+    /**
+     * Use this function to return the components you want to render under
+     * FireCMS
+     * @param props
+     */
+    children: (props: {
+        /**
+         * Context of the app
+         */
+        context: FireCMSContext;
+        /**
+         * Is one of the main processes, auth and navigation resolving, currently
+         * loading. If you are building your custom implementation, you probably
+         * want to show a loading indicator if this flag is `true`
+         */
+        loading: boolean;
+    }) => React.ReactNode;
+
+    /**
+     * List of the mapped collections in the CMS.
+     * Each entry relates to a collection in the root database.
+     * Each of the navigation entries in this field
+     * generates an entry in the main menu.
+     */
+    collections?: EC[] | EntityCollectionsBuilder<EC>;
+
+    /**
+     * Custom additional views created by the developer, added to the main
+     * navigation
+     */
+    views?: CMSView[] | CMSViewsBuilder;
+
+    /**
+     * Record of custom form fields to be used in the CMS.
+     * You can use the key to reference the custom field in
+     * the `propertyConfig` prop of a property in a collection.
+     */
+    propertyConfigs?: Record<string, PropertyConfig>;
+
+    /**
+     * List of additional custom views for entities.
+     * You can use the key to reference the custom view in
+     * the `entityViews` prop of a collection.
+     *
+     * You can also define an entity view from the UI.
+     */
+
+    entityViews?: EntityCustomView[];
+
+    /**
+     * Format of the dates in the CMS.
+     * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
+     */
+    dateTimeFormat?: string;
+
+    /**
+     * Locale of the CMS, currently only affecting dates
+     */
+    locale?: Locale;
+
+    /**
+     * Connector to your database
+     */
+    dataSourceDelegate: DataSourceDelegate;
+
+    /**
+     * Connector to your file upload/fetch implementation
+     */
+    storageSource: StorageSource;
+
+    /**
+     * Delegate for implementing your auth operations.
+     */
+    authController: AuthController<UserType>;
+
+    /**
+     * Path under the navigation routes of the CMS will be created. Defaults to `/`.
+     * Internally FireCMS uses `react-router` to create the routes, the base path is attached to the
+     * `BrowserRouter` component. If you are using FireCMS in a subpath of your website, you can use
+     * this prop to specify the base path.
+     */
+    basePath?: string;
+
+    /**
+     * Path under the collection routes of the CMS will be created.
+     * Defaults to `/c`.
+     */
+    baseCollectionPath?: string;
+
+    /**
+     * Use this controller to access the configuration that is stored locally,
+     * and not defined in code
+     */
+    userConfigPersistence?: UserConfigurationPersistence;
+
+    /**
+     * Use plugins to modify the behaviour of the CMS.
+     * Currently, in ALPHA, and likely subject to change.
+     */
+    plugins?: FireCMSPlugin<any, any, any>[];
+
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: CMSAnalyticsEvent, data?: object) => void;
+
+    /**
+     * Optional link builder you can add to generate a button in your entity forms.
+     * The function must return a URL that gets opened when the button is clicked
+     */
+    entityLinkBuilder?: EntityLinkBuilder;
+
+    components?: {
+
+        /**
+         * Component to render when a reference is missing
+         */
+        missingReference?: React.ComponentType<{
+            path: string,
+        }>;
+
+    }
+
+};