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

package/src/types/navigation.d.ts

@@ -0,0 +1,178 @@
+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[];
+    /**
+     * 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;
+    /**
+     * Location used as the base for routes.
+     * This is the location that will be used underneath, when the url changes while
+     * opening a side dialog
+     */
+    baseLocation: 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.
+     */
+    group?: string;
+}
+export interface TopNavigationEntry {
+    url: string;
+    name: string;
+    path: string;
+    type: "collection" | "view";
+    collection?: EntityCollection;
+    view: CMSView;
+    description?: string;
+    group?: string;
+}
+export type TopNavigationResult = {
+    navigationEntries: TopNavigationEntry[];
+    groups: string[];
+};

package/src/types/navigation.ts

@@ -0,0 +1,214 @@
+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[];
+
+    /**
+     * 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;
+
+    /**
+     * Location used as the base for routes.
+     * This is the location that will be used underneath, when the url changes while
+     * opening a side dialog
+     */
+    baseLocation: 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.
+     */
+    group?: string;
+
+}
+
+export interface TopNavigationEntry {
+    url: string;
+    name: string;
+    path: string;
+    type: "collection" | "view";
+    collection?: EntityCollection;
+    view: CMSView;
+    description?: string;
+    group?: string;
+}
+
+export type TopNavigationResult = {
+    navigationEntries: TopNavigationEntry[],
+    groups: string[]
+};

package/src/types/permissions.d.ts

@@ -0,0 +1,63 @@
+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 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);

package/src/types/permissions.ts

@@ -0,0 +1,76 @@
+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 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);

package/src/types/plugins.d.ts

@@ -0,0 +1,179 @@
+import React, { PropsWithChildren } from "react";
+import { FireCMSContext } from "./firecms_context";
+import { CollectionActionsProps, EntityCollection } from "./collections";
+import { User } from "./user";
+import { FieldProps, FormContext } from "./fields";
+import { CMSType, Property } from "./properties";
+import { EntityStatus } from "./entities";
+import { ResolvedProperty } from "./resolved_entities";
+/**
+ * Interface used to define plugins for FireCMS.
+ * NOTE: This is a work in progress and the API is not stable yet.
+ * @group Core
+ */
+export type FireCMSPlugin<PROPS = any, FORM_PROPS = any, EC extends EntityCollection = EntityCollection, COL_ACTIONS_PROPS = any> = {
+    /**
+     * Name of the plugin
+     */
+    name: string;
+    /**
+     * If this flag is set to true, no content will be shown in the CMS
+     * until the plugin is fully loaded.
+     */
+    loading?: boolean;
+    collections?: {
+        /**
+         * Use this method to inject collections to the CMS.
+         * You receive the current collections as a parameter, and you can return
+         * a new list of collections.
+         * @see {@link joinCollectionLists}
+         * @param collections
+         */
+        injectCollections?: (collections: EntityCollection[]) => EntityCollection[];
+        /**
+         * Use this component to add custom actions to the entity collections
+         * toolbar.
+         */
+        CollectionActions?: React.ComponentType<CollectionActionsProps<any, any, EC> & COL_ACTIONS_PROPS> | React.ComponentType<CollectionActionsProps<any, any, EC> & COL_ACTIONS_PROPS>[];
+        collectionActionsProps?: COL_ACTIONS_PROPS;
+    };
+    form?: {
+        provider?: {
+            Component: React.ComponentType<PropsWithChildren<FORM_PROPS & PluginFormActionProps<any, EC>>>;
+            props?: FORM_PROPS;
+        };
+        Actions?: React.ComponentType<PluginFormActionProps<any, EC>>;
+        fieldBuilder?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T, any, EC>) => React.ComponentType<FieldProps<T>> | null;
+        fieldBuilderEnabled?: <T extends CMSType = CMSType>(props: PluginFieldBuilderParams<T>) => boolean;
+    };
+    /**
+     * You can use this prop to add higher order components to the CMS.
+     * The components will be added to the root of the CMS, so any component
+     * rendered underneath by this plugin will have access to the context
+     * provided by this HOC.
+     * Anyhow, this is rendered below the {@link FireCMSContext} provider, so
+     * you can use the hooks provided by the CMS.
+     * @param props
+     */
+    provider?: {
+        Component: React.ComponentType<PropsWithChildren<PROPS & {
+            context: FireCMSContext;
+        }>>;
+        props?: PROPS;
+    };
+    homePage?: {
+        /**
+         * Additional actions to be rendered in the home page, close to the search bar.
+         */
+        additionalActions?: React.ReactNode;
+        /**
+         * Additional children to be rendered in the beginning of the home page.
+         */
+        additionalChildrenStart?: React.ReactNode;
+        /**
+         * Additional children to be rendered at the end of the home page.
+         */
+        additionalChildrenEnd?: React.ReactNode;
+        /**
+         * Use this component to add custom actions to the navigation card
+         * in the home page.
+         */
+        CollectionActions?: React.ComponentType<PluginHomePageActionsProps>;
+        /**
+         * Additional props passed to `CollectionActions`
+         */
+        extraProps?: any;
+        /**
+         * Add additional cards to each collection group in the home page.
+         */
+        AdditionalCards?: React.ComponentType<PluginHomePageAdditionalCardsProps> | React.ComponentType<PluginHomePageAdditionalCardsProps>[];
+        /**
+         * Include a section in the home page with a custom component and title.
+         * @param props
+         */
+        includeSection?: (props: PluginGenericProps) => {
+            title: string;
+            children: React.ReactNode;
+        };
+    };
+    collectionView?: {
+        showTextSearchBar?: (props: {
+            context: FireCMSContext;
+            path: string;
+            collection: EC;
+        }) => boolean;
+        onTextSearchClick?: (props: {
+            context: FireCMSContext;
+            path: string;
+            collection: EC;
+        }) => Promise<boolean>;
+        /**
+         * Use this method to inject widgets to the entity collections header
+         * @param props
+         */
+        HeaderAction?: React.ComponentType<{
+            property: ResolvedProperty;
+            propertyKey: string;
+            fullPath: string;
+            parentCollectionIds: string[];
+            onHover: boolean;
+            collection: EC;
+        }>;
+        /**
+         * If you add this callback to your plugin, an add button will be added to the collection table.
+         * TODO: Only the first plugin that defines this callback will be used, at the moment.
+         */
+        AddColumnComponent?: React.ComponentType<{
+            fullPath: string;
+            parentCollectionIds: string[];
+            collection: EC;
+        }>;
+    };
+};
+/**
+ * Props passed to the {@link FireCMSPlugin.homePage.CollectionActions} method.
+ * You can use it to add custom actions to the navigation card of each collection.
+ *
+ * @group Models
+ */
+export interface PluginHomePageActionsProps<EP extends object = object, M extends Record<string, any> = any, UserType extends User = User, EC extends EntityCollection<M> = EntityCollection<M>> {
+    /**
+     * Collection path of this entity. This is the full path, like
+     * `users/1234/addresses`
+     */
+    path: string;
+    /**
+     * The collection configuration
+     */
+    collection: EC;
+    /**
+     * Context of the app status
+     */
+    context: FireCMSContext<UserType>;
+    extraProps?: EP;
+}
+export interface PluginFormActionProps<UserType extends User = User, EC extends EntityCollection = EntityCollection> {
+    entityId?: string;
+    path: string;
+    status: EntityStatus;
+    collection: EC;
+    formContext?: FormContext<any>;
+    context: FireCMSContext<UserType>;
+    currentEntityId?: string;
+}
+export type PluginFieldBuilderParams<T extends CMSType = CMSType, M extends Record<string, any> = any, EC extends EntityCollection<M> = EntityCollection<M>> = {
+    fieldConfigId: string;
+    propertyKey: string;
+    property: Property<T> | ResolvedProperty<T>;
+    Field: React.ComponentType<FieldProps<T, any, M>>;
+    plugin: FireCMSPlugin;
+    path: string;
+    collection: EC;
+};
+export interface PluginGenericProps<UserType extends User = User> {
+    context: FireCMSContext<UserType>;
+}
+export interface PluginHomePageAdditionalCardsProps<UserType extends User = User> {
+    group?: string;
+    context: FireCMSContext<UserType>;
+}