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

package/src/types/dialogs_controller.tsx

@@ -0,0 +1,33 @@
+import React from "react";
+
+/**
+ * Controller to open the side dialog
+ * @group Hooks and utilities
+ */
+export interface DialogsController {
+
+    /**
+     * Close the last dialog
+     */
+    close: () => void;
+
+    /**
+     * Open a dialog
+     * @param props
+     */
+    open: (props: DialogControllerEntryProps) => { closeDialog: () => void };
+}
+
+/**
+ * Props used to open a side dialog
+ * @group Hooks and utilities
+ */
+export interface DialogControllerEntryProps {
+
+    key: string;
+    /**
+     * The component type that will be rendered
+     */
+    Component: React.ComponentType<{ open: boolean, closeDialog: () => void }>;
+
+}

package/src/types/entities.d.ts

@@ -0,0 +1,57 @@
+/**
+ * New or existing status
+ * @group Models
+ */
+export type EntityStatus = "new" | "existing" | "copy";
+/**
+ * Representation of an entity fetched from the datasource
+ * @group Models
+ */
+export interface Entity<M extends object> {
+    /**
+     * ID of the entity
+     */
+    id: string;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    path: string;
+    /**
+     * Current values
+     */
+    values: EntityValues<M>;
+}
+/**
+ * This type represents a record of key value pairs as described in an
+ * entity collection.
+ * @group Models
+ */
+export type EntityValues<M extends object> = M;
+/**
+ * Class used to create a reference to an entity in a different path
+ */
+export declare class EntityReference<M extends Record<string, any> = any> {
+    /**
+     * ID of the entity
+     */
+    readonly id: string;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    readonly path: string;
+    constructor(id: string, path: string);
+    get pathWithId(): string;
+}
+export declare class GeoPoint {
+    /**
+     * The latitude of this GeoPoint instance.
+     */
+    readonly latitude: number;
+    /**
+     * The longitude of this GeoPoint instance.
+     */
+    readonly longitude: number;
+    constructor(latitude: number, longitude: number);
+}

package/src/types/entities.ts

@@ -0,0 +1,76 @@
+/**
+ * New or existing status
+ * @group Models
+ */
+export type EntityStatus = "new" | "existing" | "copy";
+
+/**
+ * Representation of an entity fetched from the datasource
+ * @group Models
+ */
+export interface Entity<M extends object> {
+
+    /**
+     * ID of the entity
+     */
+    id: string;
+
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    path: string;
+
+    /**
+     * Current values
+     */
+    values: EntityValues<M>;
+}
+
+/**
+ * This type represents a record of key value pairs as described in an
+ * entity collection.
+ * @group Models
+ */
+export type EntityValues<M extends object> = M;
+
+/**
+ * Class used to create a reference to an entity in a different path
+ */
+export class EntityReference<M extends Record<string, any> = any> {
+    /**
+     * ID of the entity
+     */
+    readonly id: string;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    readonly path: string;
+
+    constructor(id: string, path: string) {
+        this.id = id;
+        this.path = path;
+    }
+
+    get pathWithId() {
+        return `${this.path}/${this.id}`;
+    }
+}
+
+export class GeoPoint {
+
+    /**
+     * The latitude of this GeoPoint instance.
+     */
+    readonly latitude: number;
+    /**
+     * The longitude of this GeoPoint instance.
+     */
+    readonly longitude: number;
+
+    constructor(latitude: number, longitude: number) {
+        this.latitude = latitude;
+        this.longitude = longitude;
+    }
+}

package/src/types/entity_actions.d.ts

@@ -0,0 +1,35 @@
+import React from "react";
+import { FireCMSContext } from "./firecms_context";
+import { Entity } from "./entities";
+import { EntityCollection, SelectionController } from "./collections";
+import { User } from "./user";
+import { SideEntityController } from "./side_entity_controller";
+export type EntityAction<M extends object = any, UserType extends User = User> = {
+    name: string;
+    icon?: React.ReactElement;
+    onClick: (props: EntityActionClickProps<M, UserType>) => Promise<void> | void;
+    /**
+     * Show this action collapsed in the menu of the collection view.
+     * Defaults to true
+     * If false, the action will be shown in the menu
+     */
+    collapsed?: boolean;
+    /**
+     * Show this action in the form, defaults to true
+     */
+    includeInForm?: boolean;
+};
+export type EntityActionClickProps<M extends object, UserType extends User = User> = {
+    entity: Entity<M>;
+    context: FireCMSContext<UserType>;
+    fullPath?: string;
+    collection?: EntityCollection<M>;
+    selectionController?: SelectionController;
+    highlightEntity?: (entity: Entity<any>) => void;
+    unhighlightEntity?: (entity: Entity<any>) => void;
+    onCollectionChange?: () => void;
+    /**
+     * If this actions is being called from a side dialog
+     */
+    sideEntityController?: SideEntityController;
+};

package/src/types/entity_actions.tsx

@@ -0,0 +1,39 @@
+import React from "react";
+import { FireCMSContext } from "./firecms_context";
+import { Entity } from "./entities";
+import { EntityCollection, SelectionController } from "./collections";
+import { User } from "./user";
+import { SideEntityController } from "./side_entity_controller";
+
+export type EntityAction<M extends object = any, UserType extends User = User> = {
+    name: string;
+    icon?: React.ReactElement;
+    onClick: (props: EntityActionClickProps<M, UserType>) => Promise<void> | void;
+
+    /**
+     * Show this action collapsed in the menu of the collection view.
+     * Defaults to true
+     * If false, the action will be shown in the menu
+     */
+    collapsed?: boolean;
+
+    /**
+     * Show this action in the form, defaults to true
+     */
+    includeInForm?: boolean;
+}
+
+export type EntityActionClickProps<M extends object, UserType extends User = User> = {
+    entity: Entity<M>;
+    context: FireCMSContext<UserType>;
+    fullPath?: string;
+    collection?: EntityCollection<M>;
+    selectionController?: SelectionController;
+    highlightEntity?: (entity: Entity<any>) => void;
+    unhighlightEntity?: (entity: Entity<any>) => void;
+    onCollectionChange?: () => void;
+    /**
+     * If this actions is being called from a side dialog
+     */
+    sideEntityController?: SideEntityController;
+};

package/src/types/entity_callbacks.d.ts

@@ -0,0 +1,171 @@
+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_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.d.ts

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

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.d.ts

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