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

package/src/hooks/useBuildModeController.tsx

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useState } from "react";
+
+import { ModeController } from "./index";
+
+/**
+ * Use this hook to build a color mode controller that determines
+ * the theme of the CMS
+ */
+export function useBuildModeController(): ModeController {
+
+    const prefersDarkModeQuery = typeof window !== "undefined" &&
+        window.matchMedia("(prefers-color-scheme: dark)");
+    const prefersDarkModeStorage: boolean | null = localStorage.getItem("prefers-dark-mode") != null ? localStorage.getItem("prefers-dark-mode") === "true" : null;
+    const prefersDarkMode = prefersDarkModeStorage ?? prefersDarkModeQuery;
+    const [mode, setMode] = useState<"light" | "dark">(prefersDarkMode ? "dark" : "light");
+
+    useEffect(() => {
+        setMode(prefersDarkMode ? "dark" : "light");
+        setDocumentMode(prefersDarkMode ? "dark" : "light");
+    }, [prefersDarkMode]);
+
+    // color-scheme: dark;
+    const setDarkMode = useCallback(() => {
+        setMode("dark");
+        setDocumentMode("dark");
+    }, [prefersDarkModeQuery]);
+
+    const setLightMode = useCallback(() => {
+        setMode("light");
+        setDocumentMode("light");
+    }, []);
+
+    const setDocumentMode = (mode: "light" | "dark") => {
+        document.body.style.setProperty("color-scheme", mode);
+        document.documentElement.dataset.theme = mode;
+    };
+
+    const toggleMode = useCallback(() => {
+
+        if (mode === "light") {
+            if (!prefersDarkModeQuery)
+                localStorage.setItem("prefers-dark-mode", "true");
+            else
+                localStorage.removeItem("prefers-dark-mode");
+            setDarkMode();
+        } else {
+            if (prefersDarkModeQuery)
+                localStorage.setItem("prefers-dark-mode", "false");
+            else
+                localStorage.removeItem("prefers-dark-mode");
+            setLightMode();
+        }
+    }, [mode, prefersDarkModeQuery]);
+
+    return {
+        mode,
+        setMode,
+        toggleMode
+    };
+}

package/src/hooks/useBuildNavigationController.tsx

@@ -0,0 +1,433 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import equal from "react-fast-compare"
+
+import {
+    AuthController,
+    CMSView,
+    CMSViewsBuilder,
+    DataSourceDelegate,
+    EntityCollection,
+    EntityCollectionsBuilder,
+    EntityReference,
+    NavigationController,
+    PermissionsBuilder,
+    TopNavigationEntry,
+    TopNavigationResult,
+    User,
+    UserConfigurationPersistence
+} from "../types";
+import {
+    applyPermissionsFunctionIfEmpty,
+    getCollectionByPathOrId,
+    mergeDeep,
+    removeInitialAndTrailingSlashes,
+    resolveCollectionPathIds,
+    resolvePermissions
+} from "../util";
+import { getParentReferencesFromPath } from "../util/parent_references_from_path";
+
+const DEFAULT_BASE_PATH = "/";
+const DEFAULT_COLLECTION_PATH = "/c";
+
+type BuildNavigationContextProps<EC extends EntityCollection, UserType extends User> = {
+    basePath?: string,
+    baseCollectionPath?: string,
+    authController: AuthController<UserType>;
+    collections?: EC[] | EntityCollectionsBuilder<EC>;
+    collectionPermissions?: PermissionsBuilder;
+    views?: CMSView[] | CMSViewsBuilder;
+    adminViews?: CMSView[] | CMSViewsBuilder;
+    viewsOrder?: string[];
+    userConfigPersistence?: UserConfigurationPersistence;
+    dataSourceDelegate: DataSourceDelegate;
+    /**
+     * 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[];
+};
+
+export function useBuildNavigationController<EC extends EntityCollection, UserType extends User>(props: BuildNavigationContextProps<EC, UserType>): NavigationController {
+    const {
+        basePath = DEFAULT_BASE_PATH,
+        baseCollectionPath = DEFAULT_COLLECTION_PATH,
+        authController,
+        collections: collectionsProp,
+        collectionPermissions,
+        views: viewsProp,
+        adminViews: adminViewsProp,
+        viewsOrder,
+        userConfigPersistence,
+        dataSourceDelegate,
+        injectCollections
+    } = props;
+
+    const collectionsRef = useRef<EntityCollection[] | null>();
+    const [collections, setCollections] = useState<EntityCollection[] | undefined>();
+    const [views, setViews] = useState<CMSView[] | undefined>();
+    const [adminViews, setAdminViews] = useState<CMSView[] | undefined>();
+    const [initialised, setInitialised] = useState<boolean>(false);
+
+    const [topLevelNavigation, setTopLevelNavigation] = useState<TopNavigationResult | undefined>(undefined);
+    const [navigationLoading, setNavigationLoading] = useState<boolean>(true);
+    const [navigationLoadingError, setNavigationLoadingError] = useState<Error | undefined>(undefined);
+
+    const cleanBasePath = removeInitialAndTrailingSlashes(basePath);
+    const cleanBaseCollectionPath = removeInitialAndTrailingSlashes(baseCollectionPath);
+
+    const homeUrl = cleanBasePath ? `/${cleanBasePath}` : "/";
+
+    const fullCollectionPath = cleanBasePath ? `/${cleanBasePath}/${cleanBaseCollectionPath}` : `/${cleanBaseCollectionPath}`;
+
+    const buildCMSUrlPath = useCallback((path: string): string => cleanBasePath ? `/${cleanBasePath}/${encodePath(path)}` : `/${encodePath(path)}`,
+        [cleanBasePath]);
+
+    const buildUrlCollectionPath = useCallback((path: string): string => `${removeInitialAndTrailingSlashes(baseCollectionPath)}/${encodePath(path)}`,
+        [baseCollectionPath]);
+
+    const computeTopNavigation = useCallback((collections: EntityCollection[], views: CMSView[], adminViews: CMSView[], viewsOrder?: string[]): TopNavigationResult => {
+        let navigationEntries: TopNavigationEntry[] = [
+            ...(collections ?? []).map(collection => (!collection.hideFromNavigation
+                ? ({
+                    url: buildUrlCollectionPath(collection.id ?? collection.path),
+                    type: "collection",
+                    name: collection.name.trim(),
+                    path: collection.id ?? collection.path,
+                    collection,
+                    description: collection.description?.trim(),
+                    group: collection.group?.trim() ?? "Views"
+                } satisfies TopNavigationEntry)
+                : undefined))
+                .filter(Boolean) as TopNavigationEntry[],
+            ...(views ?? []).map(view =>
+                !view.hideFromNavigation
+                    ? ({
+                        url: buildCMSUrlPath(Array.isArray(view.path) ? view.path[0] : view.path),
+                        name: view.name.trim(),
+                        type: "view",
+                        path: view.path,
+                        view,
+                        description: view.description?.trim(),
+                        group: view.group?.trim() ?? "Views"
+                    }satisfies TopNavigationEntry)
+                    : undefined)
+                .filter(Boolean) as TopNavigationEntry[],
+            ...(adminViews ?? []).map(view =>
+                !view.hideFromNavigation
+                    ? ({
+                        url: buildCMSUrlPath(Array.isArray(view.path) ? view.path[0] : view.path),
+                        name: view.name.trim(),
+                        type: "admin",
+                        path: view.path,
+                        view,
+                        description: view.description?.trim(),
+                        group: "Admin"
+                    } satisfies TopNavigationEntry)
+                    : undefined)
+                .filter(Boolean) as TopNavigationEntry[]
+        ];
+
+        if (viewsOrder) {
+            navigationEntries = navigationEntries.sort((a, b) => {
+                const aIndex = viewsOrder.indexOf(a.path);
+                const bIndex = viewsOrder.indexOf(b.path);
+                if (aIndex === -1 && bIndex === -1) {
+                    return 0;
+                }
+                if (aIndex === -1) {
+                    return 1;
+                }
+                if (bIndex === -1) {
+                    return -1;
+                }
+                return aIndex - bIndex;
+            });
+        }
+
+        const groups: string[] = Object.values(navigationEntries)
+            .map(e => e.group)
+            .filter(Boolean)
+            .filter((value, index, array) => array.indexOf(value) === index) as string[];
+
+        return {
+            navigationEntries,
+            groups
+        };
+    }, [buildCMSUrlPath, buildUrlCollectionPath]);
+
+    const refreshNavigation = useCallback(async () => {
+
+        if (authController.initialLoading)
+            return;
+
+        try {
+            const [resolvedCollections = [], resolvedViews, resolvedAdminViews = []] = await Promise.all([
+                    resolveCollections(collectionsProp, collectionPermissions, authController, dataSourceDelegate, injectCollections),
+                    resolveCMSViews(viewsProp, authController, dataSourceDelegate),
+                    resolveCMSViews(adminViewsProp, authController, dataSourceDelegate)
+                ]
+            );
+            if (
+                !equal(collectionsRef.current, resolvedCollections) ||
+                !equal(views, resolvedViews) ||
+                !equal(adminViews, resolvedAdminViews) ||
+                !equal(topLevelNavigation, computeTopNavigation(resolvedCollections, resolvedViews, resolvedAdminViews, viewsOrder))
+            ) {
+                collectionsRef.current = resolvedCollections;
+                setCollections(resolvedCollections);
+                setViews(resolvedViews);
+                setAdminViews(resolvedAdminViews);
+                setTopLevelNavigation(computeTopNavigation(resolvedCollections ?? [], resolvedViews, resolvedAdminViews, viewsOrder));
+            }
+        } catch (e) {
+            console.error(e);
+            setNavigationLoadingError(e as any);
+        }
+
+        setNavigationLoading(false);
+        setInitialised(true);
+    }, [collectionsProp, collectionPermissions, authController.user, authController.initialLoading, viewsProp, adminViewsProp, computeTopNavigation, injectCollections]);
+
+    useEffect(() => {
+        refreshNavigation();
+    }, [refreshNavigation]);
+
+    const getCollection = useCallback(<EC extends EntityCollection>(
+        idOrPath: string,
+        entityId?: string,
+        includeUserOverride = false
+    ): EC | undefined => {
+
+        if (!collections)
+            return undefined;
+
+        const baseCollection = getCollectionByPathOrId(removeInitialAndTrailingSlashes(idOrPath), collections);
+
+        const userOverride = includeUserOverride ? userConfigPersistence?.getCollectionConfig(idOrPath) : undefined;
+
+        const overriddenCollection = baseCollection ? mergeDeep(baseCollection, userOverride) : undefined;
+
+        let result: Partial<EntityCollection> | undefined = overriddenCollection;
+
+        if (overriddenCollection) {
+            const subcollections = overriddenCollection.subcollections;
+            const callbacks = overriddenCollection.callbacks;
+            const permissions = overriddenCollection.permissions;
+            result = {
+                ...result,
+                subcollections: result?.subcollections ?? subcollections,
+                callbacks: result?.callbacks ?? callbacks,
+                permissions: result?.permissions ?? permissions
+            };
+        }
+
+        if (!result) return undefined;
+
+        return { ...overriddenCollection, ...result } as EC;
+
+    }, [
+        basePath,
+        baseCollectionPath,
+        collections
+    ]);
+
+    const getCollectionFromPaths = useCallback(<EC extends EntityCollection>(pathSegments: string[]): EC | undefined => {
+        let currentCollections = collections;
+        if (!currentCollections)
+            throw Error("Collections have not been initialised yet");
+
+        for (let i = 0; i < pathSegments.length; i++) {
+            const pathSegment = pathSegments[i];
+            const collection: EntityCollection | undefined = currentCollections!.find(c => c.id === pathSegment || c.path === pathSegment);
+            if (!collection)
+                return undefined;
+            currentCollections = collection.subcollections;
+            if (i === pathSegments.length - 1)
+                return collection as EC;
+        }
+
+        return undefined;
+
+    }, [collections]);
+
+    const getCollectionFromIds = useCallback(<EC extends EntityCollection>(ids: string[]): EC | undefined => {
+        let currentCollections = collections;
+        if (!currentCollections)
+            throw Error("Collections have not been initialised yet");
+
+        for (let i = 0; i < ids.length; i++) {
+            const id = ids[i];
+            const collection: EntityCollection | undefined = currentCollections!.find(c => c.id === id);
+            if (!collection)
+                return undefined;
+            currentCollections = collection.subcollections;
+            if (i === ids.length - 1)
+                return collection as EC;
+        }
+
+        return undefined;
+
+    }, [collections]);
+
+    const isUrlCollectionPath = useCallback(
+        (path: string): boolean => removeInitialAndTrailingSlashes(path + "/").startsWith(removeInitialAndTrailingSlashes(fullCollectionPath) + "/"),
+        [fullCollectionPath]);
+
+    const urlPathToDataPath = useCallback((path: string): string => {
+        if (path.startsWith(fullCollectionPath))
+            return path.replace(fullCollectionPath, "");
+        throw Error("Expected path starting with " + fullCollectionPath);
+    }, [fullCollectionPath]);
+
+    const buildUrlEditCollectionPath = useCallback(({
+                                                        path
+                                                    }: {
+            path: string
+        }): string => {
+            return `s/edit/${encodePath(path)}`;
+        },
+        []);
+
+    const resolveAliasesFrom = useCallback((path: string): string => {
+        if (!collections)
+            throw Error("Collections have not been initialised yet");
+        return resolveCollectionPathIds(path, collections);
+    }, [collections]);
+
+    const getAllParentReferencesForPath = useCallback((path: string): EntityReference[] => {
+        return getParentReferencesFromPath({
+            path,
+            collections
+        });
+    }, [collections]);
+
+    const getParentCollectionIds = useCallback((path: string): string[] => {
+
+        const strings = path.split("/");
+        const oddPathSegments = strings.filter((_, i) => i % 2 === 0);
+        oddPathSegments.pop();
+
+        const result: string[][] = [];
+
+        for (let i = 1; i <= oddPathSegments.length; i++) {
+            result.push(oddPathSegments.slice(0, i));
+        }
+
+        // for each odd path segment, get the collection
+        return result.map(r => getCollectionFromPaths(r)?.id).filter(Boolean) as string[];
+    }, [getAllParentReferencesForPath])
+
+    const convertIdsToPaths = useCallback((ids: string[]): string[] => {
+            let currentCollections = collections;
+            const paths: string[] = [];
+            for (let i = 0; i < ids.length; i++) {
+                const id = ids[i];
+                const collection: EntityCollection | undefined = currentCollections!.find(c => c.id === id);
+                if (!collection)
+                    throw Error(`Collection with id ${id} not found`);
+                paths.push(collection.path);
+                currentCollections = collection.subcollections;
+            }
+            return paths;
+        }
+        , [getCollectionFromIds]);
+
+    return {
+        collections,
+        views,
+        adminViews,
+        loading: !initialised || navigationLoading,
+        navigationLoadingError,
+        homeUrl,
+        basePath,
+        baseCollectionPath,
+        initialised,
+        getCollection,
+        getCollectionFromPaths,
+        getCollectionFromIds,
+        isUrlCollectionPath,
+        urlPathToDataPath,
+        buildUrlCollectionPath,
+        buildUrlEditCollectionPath,
+        buildCMSUrlPath,
+        resolveAliasesFrom,
+        topLevelNavigation,
+        refreshNavigation,
+        getParentReferencesFromPath: getAllParentReferencesForPath,
+        getParentCollectionIds,
+        convertIdsToPaths
+    };
+}
+
+export function getSidePanelKey(path: string, entityId?: string) {
+    if (entityId)
+        return `${removeInitialAndTrailingSlashes(path)}/${removeInitialAndTrailingSlashes(entityId)}`;
+    else
+        return removeInitialAndTrailingSlashes(path);
+}
+
+function encodePath(input: string) {
+    return encodeURIComponent(removeInitialAndTrailingSlashes(input))
+        .replaceAll("%2F", "/")
+        .replaceAll("%23", "#");
+}
+
+function filterOutNotAllowedCollections(resolvedCollections: EntityCollection[], authController: AuthController<User>): EntityCollection[] {
+    return resolvedCollections
+        .filter((c) => {
+            if (!c.permissions) return true;
+            const resolvedPermissions = resolvePermissions(c, authController, c.path, null)
+            return resolvedPermissions?.read !== false;
+        })
+        .map((c) => {
+            if (!c.subcollections) return c;
+            return {
+                ...c,
+                subcollections: filterOutNotAllowedCollections(c.subcollections, authController)
+            }
+        });
+}
+
+async function resolveCollections(collections: undefined | EntityCollection[] | EntityCollectionsBuilder<any>,
+                                  collectionPermissions: PermissionsBuilder | undefined,
+                                  authController: AuthController,
+                                  dataSource: DataSourceDelegate,
+                                  injectCollections?: (collections: EntityCollection[]) => EntityCollection[]) {
+    let resolvedCollections: EntityCollection[] = [];
+    if (typeof collections === "function") {
+        resolvedCollections = await collections({
+            user: authController.user,
+            authController,
+            dataSource
+        });
+    } else if (Array.isArray(collections)) {
+        resolvedCollections = collections;
+    }
+
+    resolvedCollections = applyPermissionsFunctionIfEmpty(resolvedCollections, collectionPermissions);
+
+    resolvedCollections = filterOutNotAllowedCollections(resolvedCollections, authController);
+
+    if (injectCollections) {
+        resolvedCollections = injectCollections(resolvedCollections ?? []);
+    }
+
+    return resolvedCollections;
+}
+
+async function resolveCMSViews(baseViews: CMSView[] | CMSViewsBuilder | undefined, authController: AuthController, dataSource: DataSourceDelegate) {
+    let resolvedViews: CMSView[] = [];
+    if (typeof baseViews === "function") {
+        resolvedViews = await baseViews({
+            user: authController.user,
+            authController,
+            dataSource
+        });
+    } else if (Array.isArray(baseViews)) {
+        resolvedViews = baseViews;
+    }
+    return resolvedViews;
+}

package/src/hooks/useClipboard.tsx

@@ -0,0 +1,158 @@
+// FORKED FROM https://github.com/fayeed/use-clipboard
+
+import { MutableRefObject, useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseClipboardProps {
+    /**
+     * It's callback function that is called after the `copy` command
+     * is executed.
+     *
+     * @param text: The selected clipboard text.
+     */
+    onSuccess?: (text: string) => void;
+
+    /**
+     * Triggers when the hook encounters an error.
+     * If passed hook won't throw an error.
+     *
+     * @param error: cause of the error
+     */
+    onError?: (error: string) => void;
+
+    /**
+     * Disables the new clipboard API `navigator.clipboard` even if
+     * it is supported.
+     */
+    disableClipboardAPI?: boolean;
+
+    /**
+     * revert back the isCopied flag to false again if a value is set.
+     */
+    copiedDuration?: number;
+}
+
+export interface useClipboardReturnType {
+    /**
+     * Use ref to pull the text content from.
+     */
+    ref: MutableRefObject<any>;
+
+    /**
+     * Use it to perform the copy operation
+     */
+    copy: (text?: string) => void;
+
+    /**
+     * Use it to perform the cut operation
+     */
+    cut: () => void;
+
+    /**
+     * Indicates wheater the content was successfully copied or not.
+     */
+    isCoppied: boolean;
+
+    /**
+     * Current selected clipboard content.
+     */
+    clipboard: string;
+
+    /**
+     * Clears the user clipboard.
+     */
+    clearClipboard: () => void;
+
+    /**
+     * Check to see if the browser supports the new `navigator.clipboard` API.
+     */
+    isSupported: () => boolean;
+}
+
+export const useClipboard = (
+    options?: UseClipboardProps
+): useClipboardReturnType => {
+    const { onSuccess, onError, disableClipboardAPI = false, copiedDuration } =
+    options || {};
+    const ref = useRef<any>(null);
+    const [isCoppied, setIsCoppied] = useState(false);
+    const [clipboard, setClipbaord] = useState("");
+
+    useEffect(() => {
+        if (copiedDuration) setTimeout(() => setIsCoppied(false), copiedDuration);
+    }, [isCoppied]);
+
+    const isSupported = () => navigator.clipboard !== undefined;
+
+    const handleError = useCallback((error: string) => {
+        if (onError) onError(error);
+        else throw new Error(error);
+    }, [onError]);
+
+    const handleSuccess = useCallback((text: string) => {
+        if (onSuccess) onSuccess(text);
+        setIsCoppied(true);
+        setClipbaord(text);
+    }, [onSuccess]);
+
+    const copyToClipboard = useCallback((text: string) => {
+        navigator.clipboard
+            .writeText(text)
+            .then(() => handleSuccess(text))
+            .catch((err) => {
+                handleError(err);
+                setIsCoppied(false);
+            });
+    }, [handleError, handleSuccess]);
+
+    const clearClipboard = () => {
+        if (isSupported()) {
+            navigator.clipboard.writeText("");
+        }
+    };
+
+    const copy = (text?: string) =>
+        action("copy", typeof text === "object" ? undefined : text);
+
+    const cut = () => action("cut");
+
+    const action = useCallback(
+        (operation = "copy", text?: string) => {
+            const element = ref.current as HTMLElement;
+
+            const isInput =
+                element &&
+                (element.tagName === "INPUT" || element.tagName === "TEXTAREA");
+
+            const input = ref.current as HTMLInputElement;
+
+            if (isSupported() && !disableClipboardAPI) {
+                if (text) {
+                    copyToClipboard(text);
+                } else if (element) {
+                    if (isInput) {
+                        copyToClipboard(input.value);
+
+                        if (operation === "cut") {
+                            input.value = "";
+                        }
+                    } else {
+                        copyToClipboard(element.innerText);
+                    }
+                } else {
+                    handleError("Both the ref & text were undefined");
+                }
+            }
+        },
+        [disableClipboardAPI, copyToClipboard, handleError]
+    );
+
+    return {
+        ref,
+        isCoppied,
+        clipboard,
+        clearClipboard,
+        isSupported,
+        copy,
+        cut
+    };
+};

package/src/hooks/useCustomizationController.tsx

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { CustomizationController } from "../types/customization_controller";
+import { CustomizationControllerContext } from "../contexts/CustomizationControllerContext";
+
+/**
+ * Use this hook to retrieve the customization controller.
+ * This hook includes all the customization options that can be used
+ * to customize the CMS.
+ *
+ * You will likely not need to use this hook directly.
+ *
+ * @group Hooks and utilities
+ */
+export const useCustomizationController = (): CustomizationController => useContext(CustomizationControllerContext);

package/src/hooks/useDialogsController.tsx

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { DialogsController } from "../types/dialogs_controller";
+import { DialogsControllerContext } from "../contexts/DialogsProvider";
+
+/**
+ * Use this hook to open a dialog imperatively.
+ * Alternatively, you can use dialogs declaratively using the `Dialog` component.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `FireCMS`
+ *
+ * @group Hooks and utilities
+ */
+export const useDialogsController = (): DialogsController => useContext(DialogsControllerContext);