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

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,
+        }>;
+
+    }
+
+};

package/src/types/firecms_context.d.ts

@@ -0,0 +1,110 @@
+import { Locale } from "./locales";
+import { DataSource } from "./datasource";
+import { StorageSource } from "./storage";
+import { NavigationController } from "./navigation";
+import { SideEntityController } from "./side_entity_controller";
+import { AuthController } from "./auth";
+import { EntityLinkBuilder } from "./entity_link_builder";
+import { User } from "./user";
+import { SnackbarController } from "../hooks";
+import { UserConfigurationPersistence } from "./local_config_persistence";
+import { SideDialogsController } from "./side_dialogs_controller";
+import { FireCMSPlugin } from "./plugins";
+import { CMSAnalyticsEvent } from "./analytics";
+import { PropertyConfig } from "./property_config";
+import { EntityCustomView } from "./collections";
+import { DialogsController } from "./dialogs_controller";
+/**
+ * Context that includes the internal controllers and contexts used by the app.
+ * Some controllers and context included in this context can be accessed
+ * directly from their respective hooks.
+ * @group Hooks and utilities
+ * @see useFireCMSContext
+ */
+export type FireCMSContext<UserType extends User = User, AuthControllerType extends AuthController<UserType> = AuthController<UserType>> = {
+    /**
+     * Connector to your database, e.g. your Firestore database
+     */
+    dataSource: DataSource;
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+    /**
+     * Context that includes the resolved navigation and utility methods and
+     * attributes.
+     * @see useNavigation
+     */
+    navigation: NavigationController;
+    /**
+     * Controller to open the side dialog displaying entity forms
+     * @see useSideEntityController
+     */
+    sideEntityController: SideEntityController;
+    /**
+     * Controller used to open side dialogs
+     * This is the controller used internally by side entity dialogs
+     * or reference dialogs.
+     */
+    sideDialogsController: SideDialogsController;
+    /**
+     * Controller used to open regular dialogs
+     */
+    dialogsController: DialogsController;
+    /**
+     * Used auth controller
+     */
+    authController: AuthControllerType;
+    /**
+     * Builder for generating utility links for entities
+     */
+    entityLinkBuilder?: EntityLinkBuilder;
+    /**
+     * Use this controller to display snackbars
+     */
+    snackbarController: SnackbarController;
+    /**
+     * Use this controller to access data stored in the browser for the user
+     */
+    userConfigPersistence?: UserConfigurationPersistence;
+    /**
+     * Use plugins to modify the behaviour of the CMS.
+     * Currently, in ALPHA, and likely subject to change.
+     */
+    plugins?: FireCMSPlugin[];
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: CMSAnalyticsEvent, data?: object) => void;
+    /**
+     * 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;
+    components?: {
+        /**
+         * Component to render when a reference is missing
+         */
+        missingReference?: React.ComponentType<{
+            path: string;
+        }>;
+    };
+};

package/src/types/firecms_context.tsx

@@ -0,0 +1,128 @@
+import { Locale } from "./locales";
+import { DataSource } from "./datasource";
+import { StorageSource } from "./storage";
+import { NavigationController } from "./navigation";
+import { SideEntityController } from "./side_entity_controller";
+import { AuthController } from "./auth";
+import { EntityLinkBuilder } from "./entity_link_builder";
+import { User } from "./user";
+import { SnackbarController } from "../hooks";
+import { UserConfigurationPersistence } from "./local_config_persistence";
+import { SideDialogsController } from "./side_dialogs_controller";
+import { FireCMSPlugin } from "./plugins";
+import { CMSAnalyticsEvent } from "./analytics";
+import { PropertyConfig } from "./property_config";
+import { EntityCustomView } from "./collections";
+import { DialogsController } from "./dialogs_controller";
+
+/**
+ * Context that includes the internal controllers and contexts used by the app.
+ * Some controllers and context included in this context can be accessed
+ * directly from their respective hooks.
+ * @group Hooks and utilities
+ * @see useFireCMSContext
+ */
+export type FireCMSContext<UserType extends User = User, AuthControllerType extends AuthController<UserType> = AuthController<UserType>> = {
+
+    /**
+     * Connector to your database, e.g. your Firestore database
+     */
+    dataSource: DataSource;
+
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+
+    /**
+     * Context that includes the resolved navigation and utility methods and
+     * attributes.
+     * @see useNavigation
+     */
+    navigation: NavigationController;
+
+    /**
+     * Controller to open the side dialog displaying entity forms
+     * @see useSideEntityController
+     */
+    sideEntityController: SideEntityController;
+
+    /**
+     * Controller used to open side dialogs
+     * This is the controller used internally by side entity dialogs
+     * or reference dialogs.
+     */
+    sideDialogsController: SideDialogsController;
+
+    /**
+     * Controller used to open regular dialogs
+     */
+    dialogsController: DialogsController;
+
+    /**
+     * Used auth controller
+     */
+    authController: AuthControllerType;
+
+    /**
+     * Builder for generating utility links for entities
+     */
+    entityLinkBuilder?: EntityLinkBuilder;
+
+    /**
+     * Use this controller to display snackbars
+     */
+    snackbarController: SnackbarController;
+
+    /**
+     * Use this controller to access data stored in the browser for the user
+     */
+    userConfigPersistence?: UserConfigurationPersistence;
+
+    /**
+     * Use plugins to modify the behaviour of the CMS.
+     * Currently, in ALPHA, and likely subject to change.
+     */
+    plugins?: FireCMSPlugin[];
+
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: CMSAnalyticsEvent, data?: object) => void;
+
+    /**
+     * 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;
+
+    components?: {
+
+        /**
+         * Component to render when a reference is missing
+         */
+        missingReference?: React.ComponentType<{ path: string }>;
+
+    }
+};

package/src/types/index.d.ts

@@ -0,0 +1,26 @@
+export * from "./auth";
+export * from "./entities";
+export * from "./entity_actions";
+export * from "./resolved_entities";
+export * from "./properties";
+export * from "./collections";
+export * from "./permissions";
+export * from "./navigation";
+export * from "./locales";
+export * from "./user";
+export * from "./storage";
+export * from "./fields";
+export * from "./property_config";
+export * from "./datasource";
+export * from "./entity_link_builder";
+export * from "./side_entity_controller";
+export * from "./side_dialogs_controller";
+export * from "./firecms_context";
+export * from "./entity_callbacks";
+export * from "./local_config_persistence";
+export * from "./plugins";
+export * from "./analytics";
+export * from "./firecms";
+export * from "./appcheck";
+export * from "./export_import";
+export * from "./modify_collections";

package/src/types/index.ts

@@ -0,0 +1,26 @@
+export * from "./auth";
+export * from "./entities";
+export * from "./entity_actions";
+export * from "./resolved_entities";
+export * from "./properties";
+export * from "./collections";
+export * from "./permissions";
+export * from "./navigation";
+export * from "./locales";
+export * from "./user";
+export * from "./storage";
+export * from "./fields";
+export * from "./property_config";
+export * from "./datasource";
+export * from "./entity_link_builder";
+export * from "./side_entity_controller";
+export * from "./side_dialogs_controller";
+export * from "./firecms_context";
+export * from "./entity_callbacks";
+export * from "./local_config_persistence";
+export * from "./plugins";
+export * from "./analytics";
+export * from "./firecms";
+export * from "./appcheck";
+export * from "./export_import";
+export * from "./modify_collections";

package/src/types/local_config_persistence.d.ts

@@ -0,0 +1,21 @@
+import { EntityCollection } from "./collections";
+/**
+ * Use to resolve the collection properties for specific path, entity id or values.
+ * @group Models
+ */
+export type PartialEntityCollection<M extends Record<string, any> = any> = Partial<EntityCollection<M>>;
+/**
+ * This interface is in charge of defining the controller that persists
+ * modifications to a collection or collection, and retrieves them back from
+ * a data source, such as local storage or Firestore.
+ */
+export interface UserConfigurationPersistence {
+    onCollectionModified: <M extends Record<string, any> = any>(path: string, partialCollection: PartialEntityCollection<M>) => void;
+    getCollectionConfig: <M extends Record<string, any> = any>(path: string) => PartialEntityCollection<M>;
+    recentlyVisitedPaths: string[];
+    setRecentlyVisitedPaths: (paths: string[]) => void;
+    favouritePaths: string[];
+    setFavouritePaths: (paths: string[]) => void;
+    collapsedGroups: string[];
+    setCollapsedGroups: (paths: string[]) => void;
+}

package/src/types/local_config_persistence.tsx

@@ -0,0 +1,23 @@
+import { EntityCollection } from "./collections";
+
+/**
+ * Use to resolve the collection properties for specific path, entity id or values.
+ * @group Models
+ */
+export type PartialEntityCollection<M extends Record<string, any> = any> = Partial<EntityCollection<M>>;
+
+/**
+ * This interface is in charge of defining the controller that persists
+ * modifications to a collection or collection, and retrieves them back from
+ * a data source, such as local storage or Firestore.
+ */
+export interface UserConfigurationPersistence {
+    onCollectionModified: <M extends Record<string, any> = any>(path: string, partialCollection: PartialEntityCollection<M>) => void;
+    getCollectionConfig: <M extends Record<string, any> = any>(path: string) => PartialEntityCollection<M>;
+    recentlyVisitedPaths: string[];
+    setRecentlyVisitedPaths: (paths: string[]) => void;
+    favouritePaths: string[];
+    setFavouritePaths: (paths: string[]) => void;
+    collapsedGroups: string[];
+    setCollapsedGroups: (paths: string[]) => void;
+}

package/src/types/locales.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @group Models
+ */
+export type Locale = "af" | "ar" | "arDZ" | "arMA" | "arSA" | "az" | "be" | "bg" | "bn" | "ca" | "cs" | "cy" | "da" | "de" | "el" | "enAU" | "enCA" | "enGB" | "enIN" | "enNZ" | "enUS" | "eo" | "es" | "et" | "eu" | "faIR" | "fi" | "fil" | "fr" | "frCA" | "frCH" | "gd" | "gl" | "gu" | "he" | "hi" | "hr" | "hu" | "hy" | "id" | "is" | "it" | "ja" | "ka" | "kk" | "kn" | "ko" | "lb" | "lt" | "lv" | "mk" | "ms" | "mt" | "nb" | "nl" | "nlBE" | "nn" | "pl" | "pt" | "ptBR" | "ro" | "ru" | "sk" | "sl" | "sr" | "srLatn" | "sv" | "ta" | "te" | "th" | "tr" | "ug" | "uk" | "uz" | "vi" | "zhCN" | "zhTW";

package/src/types/locales.ts

@@ -0,0 +1,81 @@
+/**
+ * @group Models
+ */
+export type Locale =
+    "af" |
+    "ar" |
+    "arDZ" |
+    "arMA" |
+    "arSA" |
+    "az" |
+    "be" |
+    "bg" |
+    "bn" |
+    "ca" |
+    "cs" |
+    "cy" |
+    "da" |
+    "de" |
+    "el" |
+    "enAU" |
+    "enCA" |
+    "enGB" |
+    "enIN" |
+    "enNZ" |
+    "enUS" |
+    "eo" |
+    "es" |
+    "et" |
+    "eu" |
+    "faIR" |
+    "fi" |
+    "fil" |
+    "fr" |
+    "frCA" |
+    "frCH" |
+    "gd" |
+    "gl" |
+    "gu" |
+    "he" |
+    "hi" |
+    "hr" |
+    "hu" |
+    "hy" |
+    "id" |
+    "is" |
+    "it" |
+    "ja" |
+    "ka" |
+    "kk" |
+    "kn" |
+    "ko" |
+    "lb" |
+    "lt" |
+    "lv" |
+    "mk" |
+    "ms" |
+    "mt" |
+    "nb" |
+    "nl" |
+    "nlBE" |
+    "nn" |
+    "pl" |
+    "pt" |
+    "ptBR" |
+    "ro" |
+    "ru" |
+    "sk" |
+    "sl" |
+    "sr" |
+    "srLatn" |
+    "sv" |
+    "ta" |
+    "te" |
+    "th" |
+    "tr" |
+    "ug" |
+    "uk" |
+    "uz" |
+    "vi" |
+    "zhCN" |
+    "zhTW";

package/src/types/modify_collections.d.ts

@@ -0,0 +1,5 @@
+import { EntityCollection } from "./collections";
+export type ModifyCollectionProps = {
+    collection: EntityCollection;
+    parentPaths: string[];
+};

package/src/types/modify_collections.tsx

@@ -0,0 +1,6 @@
+import { EntityCollection } from "./collections";
+
+export type ModifyCollectionProps = {
+    collection: EntityCollection,
+    parentPaths: string[],
+};