@firecms/core 3.0.0-3.0.0-beta.4.pre.1.0

package/dist/types/fields.d.ts

@@ -0,0 +1,180 @@
+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
+     */
+    /**
+     * 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/dist/types/firecms.d.ts

@@ -0,0 +1,132 @@
+import React from "react";
+import { User } from "./user";
+import { AuthController } from "./auth";
+import { DataSourceDelegate } from "./datasource";
+import { EntityCollection, EntityCustomView } from "./collections";
+import { CMSView, NavigationController } 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;
+    /**
+     * 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>;
+    /**
+     * This controller is in charge of the navigation of the CMS.
+     * It is in charge of resolving the collection and entity paths.
+     */
+    navigationController: NavigationController;
+    /**
+     * 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>;
+    /**
+     * 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/dist/types/firecms_context.d.ts

@@ -0,0 +1,70 @@
+import { DataSource } from "./datasource";
+import { StorageSource } from "./storage";
+import { NavigationController } from "./navigation";
+import { SideEntityController } from "./side_entity_controller";
+import { AuthController } from "./auth";
+import { User } from "./user";
+import { SnackbarController } from "../hooks";
+import { UserConfigurationPersistence } from "./local_config_persistence";
+import { SideDialogsController } from "./side_dialogs_controller";
+import { DialogsController } from "./dialogs_controller";
+import { CustomizationController } from "./customization_controller";
+import { AnalyticsController } from "./analytics_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;
+    /**
+     * This controller holds the customization options for the CMS.
+     */
+    customizationController: CustomizationController;
+    /**
+     * Use this controller to display snackbars
+     */
+    snackbarController: SnackbarController;
+    /**
+     * Use this controller to access data stored in the browser for the user
+     */
+    userConfigPersistence?: UserConfigurationPersistence;
+    /**
+     * Callback to send analytics events
+     */
+    analyticsController?: AnalyticsController;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,29 @@
+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 "./entity_overrides";
+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";
+export * from "./analytics_controller";
+export * from "./customization_controller";

package/dist/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/dist/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/dist/types/modify_collections.d.ts

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

package/dist/types/navigation.d.ts

@@ -0,0 +1,179 @@
+import React from "react";
+import { EntityCollection } from "./collections";
+import { EntityReference } from "./entities";
+/**
+ * Controller that includes the resolved navigation and utility methods and
+ * attributes.
+ * @group Models
+ */
+export type NavigationController = {
+    /**
+     * 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?: EntityCollection[];
+    /**
+     * Custom additional views created by the developer, added to the main
+     * navigation
+     */
+    views?: CMSView[];
+    /**
+     * Custom additional views created by the developer, added to the admin
+     * navigation
+     */
+    adminViews?: CMSView[];
+    /**
+     * Configuration for the views that should be displayed at the top
+     * level of the navigation (e.g. in the home page or the navigation
+     * drawer)
+     */
+    topLevelNavigation?: TopNavigationResult;
+    /**
+     * Is the navigation loading (the configuration persistence has not
+     * loaded yet, or a specified navigation builder has not completed)
+     */
+    loading: boolean;
+    /**
+     * Was there an error while loading the navigation data
+     */
+    navigationLoadingError?: any;
+    /**
+     * Is the registry ready to be used
+     */
+    initialised: boolean;
+    /**
+     * Get the collection configuration for a given path.
+     * The collection is resolved from the given path or alias.
+     */
+    getCollection: <EC extends EntityCollection = EntityCollection<any>>(pathOrAlias: string, entityId?: string, includeUserOverride?: boolean) => EC | undefined;
+    /**
+     * Get the collection configuration from its parent path segments.
+     */
+    getCollectionFromIds: <EC extends EntityCollection = EntityCollection<any>>(ids: string[]) => EC | undefined;
+    /**
+     * Get the collection configuration from its parent path segments.
+     */
+    getCollectionFromPaths: <EC extends EntityCollection = EntityCollection<any>>(pathSegments: string[]) => EC | undefined;
+    /**
+     * Default path under the navigation routes of the CMS will be created
+     */
+    basePath: string;
+    /**
+     * Default path under the collection routes of the CMS will be created
+     */
+    baseCollectionPath: string;
+    /**
+     * Convert a URL path to a collection or entity path
+     * `/c/products` => `products`
+     * `/my_cms/c/products/B34SAP8Z` => `products/B34SAP8Z`
+     * `/my_cms/my_view` => `my_view`
+     * @param cmsPath
+     */
+    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
+     */
+    homeUrl: string;
+    /**
+     * Check if a url path belongs to a collection
+     * @param path
+     */
+    isUrlCollectionPath: (urlPath: string) => boolean;
+    /**
+     * Build a URL collection path from a data path
+     * `products` => `/c/products`
+     * `products/B34SAP8Z` => `/c/products/B34SAP8Z`
+     * @param path
+     */
+    buildUrlCollectionPath: (path: string) => string;
+    /**
+     * Turn a path with aliases into a resolved path
+     * @param pathWithAliases
+     */
+    resolveAliasesFrom: (pathWithAliases: string) => string;
+    /**
+     * Call this method to recalculate the navigation
+     */
+    refreshNavigation: () => void;
+    /**
+     * Retrieve all the related parent references for a given path
+     * @param path
+     */
+    getParentReferencesFromPath: (path: string) => EntityReference[];
+    /**
+     * Retrieve all the related parent collection ids for a given path
+     * @param path
+     */
+    getParentCollectionIds: (path: string) => string[];
+    /**
+     * Resolve paths from a list of ids
+     * @param ids
+     */
+    convertIdsToPaths: (ids: string[]) => string[];
+};
+/**
+ * Custom additional views created by the developer, added to the main
+ * navigation.
+ * @group Models
+ */
+export interface CMSView {
+    /**
+     * CMS Path you can reach this view from.
+     */
+    path: string;
+    /**
+     * Name of this view
+     */
+    name: string;
+    /**
+     * Optional description of this view. You can use Markdown
+     */
+    description?: string;
+    /**
+     * Icon key to use in this view.
+     * You can use any of the icons in the Material specs:
+     * https://fonts.google.com/icons
+     * e.g. 'account_tree' or 'person'
+     */
+    icon?: string;
+    /**
+     * Should this view be hidden from the main navigation panel.
+     * It will still be accessible if you reach the specified path
+     */
+    hideFromNavigation?: boolean;
+    /**
+     * Component to be rendered. This can be any React component, and can use
+     * any of the provided hooks
+     */
+    view: React.ReactNode;
+    /**
+     * Optional field used to group top level navigation entries under a
+     * navigation view.
+     * This prop is ignored for admin views.
+     */
+    group?: string;
+}
+export interface TopNavigationEntry {
+    url: string;
+    name: string;
+    path: string;
+    type: "collection" | "view" | "admin";
+    collection?: EntityCollection;
+    view?: CMSView;
+    description?: string;
+    group: string;
+}
+export type TopNavigationResult = {
+    navigationEntries: TopNavigationEntry[];
+    groups: string[];
+};

package/dist/types/permissions.d.ts

@@ -0,0 +1,67 @@
+import { User } from "./user";
+import { AuthController } from "./auth";
+import { EntityCollection, InferCollectionType } from "./collections";
+import { Entity } from "./entities";
+/**
+ * Define the operations that can be performed in a collection.
+ * @group Models
+ */
+export interface Permissions {
+    /**
+     * Can the user see this collection.
+     * If `false` it will not show in the user's navigation
+     * Defaults to `true`
+     */
+    read?: boolean;
+    /**
+     * Can the user add new entities. Defaults to `true`
+     */
+    create?: boolean;
+    /**
+     * Can the elements in this collection be edited. Defaults to `true`
+     */
+    edit?: boolean;
+    /**
+     * Can the user delete entities. Defaults to `true`
+     */
+    delete?: boolean;
+}
+/**
+ * Props passed to a {@link PermissionsBuilder}
+ * @group Models
+ */
+export interface PermissionsBuilderProps<EC extends EntityCollection = EntityCollection, UserType extends User = User, M extends object = InferCollectionType<EC>> {
+    /**
+     * Entity being edited, might be null in some cases, when the operation
+     * refers to the collection.
+     * For example, when deciding whether a user can create a new entity
+     * in a collection, the entity will be null.
+     */
+    entity: Entity<M> | null;
+    /**
+     * Path of the collection e.g. 'products/12345/locales'
+     */
+    path: string;
+    /**
+     * Path segments of the collection e.g. ['products', 'locales']
+     */
+    pathSegments: string[];
+    /**
+     * Logged in user
+     */
+    user: UserType | null;
+    /**
+     * Collection these permissions apply to
+     */
+    collection: EC;
+    /**
+     * Auth controller
+     */
+    authController: AuthController<UserType>;
+}
+/**
+ * Builder used to assign permissions to entities,
+ * based on the logged user or collection.
+ * @group Models
+ */
+export type PermissionsBuilder<EC extends EntityCollection = EntityCollection, UserType extends User = User, M extends object = InferCollectionType<EC>> = (({ pathSegments, user, collection, authController }: PermissionsBuilderProps<EC, UserType, M>) => Permissions | undefined);