@rebasepro/core 0.0.1-canary.0

package/src/hooks/useBuildNavigationController.tsx

@@ -0,0 +1,341 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { deepEqual as equal } from "fast-equals";
+
+import {
+    EntityCollection,
+    CMSView,
+    User,
+    NavigationController,
+    NavigationEntry,
+    NavigationGroupMapping,
+    NavigationResult,
+    RebasePlugin,
+    AuthController,
+    EntityCollectionsBuilder,
+    CMSViewsBuilder,
+    UserConfigurationPersistence,
+    DataSource
+} from "@rebasepro/types";
+
+import { useNavigationURLs } from "./navigation/useNavigationURLs";
+import { useNavigationRegistry } from "./navigation/useNavigationRegistry";
+import { resolveCollections, resolveCMSViews } from "./navigation/useNavigationResolution";
+
+import { computeNavigationGroups, getGroup, NAVIGATION_ADMIN_GROUP_NAME, NAVIGATION_DEFAULT_GROUP_NAME } from "./navigation/utils";
+
+export type BuildNavigationContextProps<EC extends EntityCollection, USER extends User> = {
+    basePath?: string;
+    baseCollectionPath?: string;
+    authController: AuthController<USER>;
+    collections?: EC[] | EntityCollectionsBuilder<EC>;
+    views?: CMSView[] | CMSViewsBuilder;
+    adminViews?: CMSView[] | CMSViewsBuilder;
+    userConfigPersistence?: UserConfigurationPersistence;
+    dataSource: DataSource;
+    plugins?: RebasePlugin[];
+    navigationGroupMappings?: NavigationGroupMapping[];
+    disabled?: boolean;
+    viewsOrder?: string[];
+};
+
+const DEFAULT_BASE_PATH = "/";
+const DEFAULT_COLLECTION_PATH = "/c";
+
+export function useBuildNavigationController<EC extends EntityCollection, USER extends User>(props: BuildNavigationContextProps<EC, USER>): NavigationController {
+
+    const {
+        basePath = DEFAULT_BASE_PATH,
+        baseCollectionPath = DEFAULT_COLLECTION_PATH,
+        authController,
+        collections: collectionsProp,
+        views: viewsProp,
+        adminViews: adminViewsProp,
+        viewsOrder,
+        plugins,
+        userConfigPersistence,
+        dataSource,
+        disabled,
+        navigationGroupMappings
+    } = props;
+
+    const navigate = useNavigate();
+
+    const registryHook = useNavigationRegistry(userConfigPersistence);
+    const { collectionRegistryRef } = registryHook;
+
+    const urlsHook = useNavigationURLs(basePath, baseCollectionPath, collectionRegistryRef);
+
+    const viewsRef = useRef<CMSView[] | undefined>(undefined);
+    const adminViewsRef = useRef<CMSView[] | undefined>(undefined);
+    const navigationEntriesOrderRef = useRef<string[] | undefined>(undefined);
+
+    const [initialised, setInitialised] = useState<boolean>(false);
+
+    const [topLevelNavigation, setTopLevelNavigation] = useState<NavigationResult | undefined>(undefined);
+    const [navigationLoading, setNavigationLoading] = useState<boolean>(true);
+    const [navigationLoadingError, setNavigationLoadingError] = useState<Error | undefined>(undefined);
+
+    const allPluginGroups = plugins?.flatMap(plugin => plugin.homePage?.navigationEntries ? plugin.homePage.navigationEntries.map(e => e.name) : []) ?? [];
+    const pluginGroups = [...new Set(allPluginGroups)];
+
+    const computeTopNavigation = useCallback((collections: EntityCollection[], views: CMSView[], adminViews: CMSView[], viewsOrder?: string[], navigationGroupMappingsOverride?: NavigationGroupMapping[], onNavigationEntriesUpdateCallback?: (entries: NavigationGroupMapping[]) => void): NavigationResult => {
+
+        const finalNavigationGroupMappings: NavigationGroupMapping[] = computeNavigationGroups({
+            navigationGroupMappings: navigationGroupMappingsOverride ?? navigationGroupMappings,
+            collections,
+            views,
+            plugins: plugins
+        });
+
+        const allPluginNavigationEntries = finalNavigationGroupMappings.map((g) => g.entries).flat() ?? [];
+        const navigationEntriesOrder = ([...new Set(allPluginNavigationEntries)]);
+
+        let navigationEntries: NavigationEntry[] = [
+            ...(collections ?? []).reduce((acc, collection) => {
+                if (collection.hideFromNavigation) return acc;
+
+                const pathKey = collection.slug;
+                let groupName = getGroup(collection);
+
+                if (finalNavigationGroupMappings) {
+                    for (const pluginGroupDef of finalNavigationGroupMappings) {
+                        if (pluginGroupDef.entries.includes(pathKey)) {
+                            groupName = pluginGroupDef.name;
+                            break;
+                        }
+                    }
+                }
+
+                acc.push({
+                    id: `collection:${pathKey}`,
+                    url: urlsHook.buildUrlCollectionPath(pathKey),
+                    type: "collection",
+                    name: collection.name.trim(),
+                    slug: pathKey,
+                    collection,
+                    description: collection.description?.trim(),
+                    group: groupName ?? NAVIGATION_DEFAULT_GROUP_NAME
+                });
+                return acc;
+            }, [] as NavigationEntry[]),
+
+            ...(views ?? []).reduce((acc, view) => {
+                if (view.hideFromNavigation) return acc;
+
+                const pathKey = view.slug;
+                let groupName = getGroup(view);
+
+                if (finalNavigationGroupMappings) {
+                    for (const pluginGroupDef of finalNavigationGroupMappings) {
+                        if (pluginGroupDef.entries.includes(pathKey)) {
+                            groupName = pluginGroupDef.name;
+                            break;
+                        }
+                    }
+                }
+
+                acc.push({
+                    id: `view:${pathKey}`,
+                    url: urlsHook.buildCMSUrlPath(pathKey),
+                    name: view.name.trim(),
+                    type: "view",
+                    slug: view.slug,
+                    view,
+                    description: view.description?.trim(),
+                    group: groupName ?? NAVIGATION_DEFAULT_GROUP_NAME
+                });
+                return acc;
+            }, [] as NavigationEntry[]),
+
+            ...(adminViews ?? []).reduce((acc, view) => {
+                if (view.hideFromNavigation) return acc;
+
+                const pathKey = view.slug;
+                const groupName = NAVIGATION_ADMIN_GROUP_NAME;
+
+                acc.push({
+                    id: `admin:${pathKey}`,
+                    url: urlsHook.buildCMSUrlPath(pathKey),
+                    name: view.name.trim(),
+                    type: "admin",
+                    slug: view.slug,
+                    view,
+                    description: view.description?.trim(),
+                    group: groupName
+                });
+                return acc;
+            }, [] as NavigationEntry[])
+        ];
+
+        const groupOrderValue = (groupName?: string): number => {
+            if (groupName === NAVIGATION_ADMIN_GROUP_NAME) return 1;
+            return 0; // Other groups
+        };
+
+        navigationEntries = navigationEntries.sort((a, b) => {
+            return groupOrderValue(a.group) - groupOrderValue(b.group);
+        });
+
+        const usedViewsOrder = viewsOrder ?? navigationEntriesOrder;
+        if (usedViewsOrder) {
+            navigationEntries = navigationEntries.sort((a, b) => {
+                const getSortPath = (navEntry: NavigationEntry) => typeof navEntry.slug === "string" ? navEntry.slug : navEntry.slug[0];
+                const aIndex = usedViewsOrder.indexOf(getSortPath(a));
+                const bIndex = usedViewsOrder.indexOf(getSortPath(b));
+                if (aIndex === -1 && bIndex === -1) return 0;
+                if (aIndex === -1) return 1;
+                if (bIndex === -1) return -1;
+                return aIndex - bIndex;
+            });
+        }
+
+        const collectedGroupsFromEntries = navigationEntries
+            .map(e => e.group)
+            .filter(Boolean) as string[];
+
+        // Preserve order from finalNavigationGroupMappings (persisted order)
+        const groupsFromMappings = finalNavigationGroupMappings.map(g => g.name);
+
+        // Add any additional groups not in mappings
+        const additionalGroups = collectedGroupsFromEntries.filter(g => !groupsFromMappings.includes(g));
+
+        const allDefinedGroups = [
+            ...(pluginGroups ?? []),
+            ...groupsFromMappings,
+            ...additionalGroups
+        ];
+
+        // Remove duplicates while preserving order, then separate admin to the end
+        const uniqueGroupsArray = [...new Set(allDefinedGroups)];
+        const adminGroups = uniqueGroupsArray.filter(g => g === NAVIGATION_ADMIN_GROUP_NAME);
+        const nonAdminGroups = uniqueGroupsArray.filter(g => g !== NAVIGATION_ADMIN_GROUP_NAME);
+        const uniqueGroups = [...nonAdminGroups, ...adminGroups] as string[];
+
+        return {
+            allowDragAndDrop: plugins?.some((plugin: RebasePlugin) => plugin.homePage?.allowDragAndDrop) ?? false,
+            navigationEntries,
+            groups: uniqueGroups,
+            onNavigationEntriesUpdate: onNavigationEntriesUpdateCallback!,
+        };
+    }, [navigationGroupMappings, urlsHook.buildCMSUrlPath, urlsHook.buildUrlCollectionPath, pluginGroups]);
+
+    const onNavigationEntriesOrderUpdate = useCallback((entries: NavigationGroupMapping[]) => {
+        if (!plugins) {
+            return;
+        }
+        // remove all groups that have no entries
+        const filteredEntries = entries.filter(entry => entry.entries.length > 0);
+
+        // Immediately update the local topLevelNavigation with new mappings
+        if (collectionRegistryRef.current && viewsRef.current) {
+            const updatedNav = computeTopNavigation(
+                collectionRegistryRef.current.getCollections(),
+                viewsRef.current,
+                adminViewsRef.current ?? [],
+                viewsOrder,
+                filteredEntries,
+                onNavigationEntriesOrderUpdate
+            );
+            setTopLevelNavigation(updatedNav);
+        }
+
+        // Then persist to backend
+        if (plugins.some((plugin: RebasePlugin) => plugin.homePage?.onNavigationEntriesUpdate)) {
+            plugins.forEach((plugin: RebasePlugin) => {
+                if (plugin.homePage?.onNavigationEntriesUpdate) {
+                    plugin.homePage.onNavigationEntriesUpdate(filteredEntries);
+                }
+            });
+        }
+
+    }, [plugins, computeTopNavigation, viewsOrder]);
+
+    const refreshNavigation = useCallback(async () => {
+
+        if (disabled || authController.initialLoading)
+            return;
+
+        console.debug("Refreshing navigation");
+
+        try {
+
+            const [resolvedCollections = [], resolvedViews, resolvedAdminViews = []] = await Promise.all(
+                [
+                    resolveCollections(collectionsProp, authController, dataSource, plugins),
+                    resolveCMSViews(viewsProp, authController, dataSource, plugins),
+                    resolveCMSViews(adminViewsProp, authController, dataSource)
+                ]
+            );
+
+            const computedTopLevelNav = computeTopNavigation(resolvedCollections, resolvedViews, resolvedAdminViews, viewsOrder, undefined, onNavigationEntriesOrderUpdate);
+
+            let shouldUpdateTopLevelNav = false;
+            let collectionsChanged = collectionRegistryRef.current.registerMultiple(resolvedCollections);
+            ;
+
+            if (collectionsChanged) {
+                console.debug("Collections have changed", resolvedCollections);
+                shouldUpdateTopLevelNav = true;
+            }
+
+            if (!equal(viewsRef.current, resolvedViews)) {
+                viewsRef.current = resolvedViews;
+                shouldUpdateTopLevelNav = true;
+            }
+            if (!equal(adminViewsRef.current, resolvedAdminViews)) {
+                adminViewsRef.current = resolvedAdminViews;
+                shouldUpdateTopLevelNav = true;
+            }
+
+            const navigationEntriesOrder = computedTopLevelNav.navigationEntries.map(e => e.id);
+            if (!equal(navigationEntriesOrderRef.current, navigationEntriesOrder)) {
+                navigationEntriesOrderRef.current = navigationEntriesOrder;
+                shouldUpdateTopLevelNav = true;
+            }
+
+            if (shouldUpdateTopLevelNav && !equal(topLevelNavigation, computedTopLevelNav)) {
+                setTopLevelNavigation(computedTopLevelNav);
+            }
+        } catch (e) {
+            console.error(e);
+            setNavigationLoadingError(e as any);
+        }
+
+        if (navigationLoading)
+            setNavigationLoading(false);
+        if (!initialised)
+            setInitialised(true);
+
+    }, [
+        collectionsProp,
+        authController.user,
+        authController.initialLoading,
+        disabled,
+        viewsProp,
+        adminViewsProp,
+        computeTopNavigation,
+    ]);
+
+    useEffect(() => {
+        refreshNavigation();
+    }, [refreshNavigation]);
+
+    // Omit getCollection and registry methods from returned shape to just use registryHook's getters directly
+    return {
+        ...registryHook,
+        ...urlsHook,
+        collections: collectionRegistryRef.current.getCollections(),
+        views: viewsRef.current,
+        adminViews: adminViewsRef.current,
+        loading: !initialised || navigationLoading,
+        navigationLoadingError,
+        basePath,
+        baseCollectionPath,
+        initialised,
+        topLevelNavigation,
+        refreshNavigation,
+        navigate,
+        plugins
+    };
+}

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/useCollapsedGroups.ts

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useState } from "react";
+
+const STORAGE_KEY_PREFIX = "rebase-collapsed-groups";
+
+/**
+ * Custom hook for managing collapsed/expanded state of navigation groups
+ * with localStorage persistence. Automatically cleans up stale group entries
+ * when groups are removed from the navigation.
+ * 
+ * @param groupNames - Array of group names to track
+ * @param namespace - Namespace for localStorage key (e.g., "home", "drawer") to allow independent state
+ */
+export function useCollapsedGroups(groupNames: string[], namespace: string = "default") {
+    const storageKey = `${STORAGE_KEY_PREFIX}-${namespace}`;
+
+    // Load collapsed groups from localStorage on mount
+    const [collapsedGroups, setCollapsedGroups] = useState<Record<string, boolean>>(() => {
+        try {
+            const stored = localStorage.getItem(storageKey);
+            return stored ? JSON.parse(stored) : {};
+        } catch {
+            return {};
+        }
+    });
+
+    // Save to localStorage whenever collapsedGroups changes
+    useEffect(() => {
+        try {
+            localStorage.setItem(storageKey, JSON.stringify(collapsedGroups));
+        } catch {
+            // Silently fail if localStorage is not available
+        }
+    }, [collapsedGroups, storageKey]);
+
+    // Clean up collapsed groups state when groups change - remove entries for groups that no longer exist
+    useEffect(() => {
+        // Only clean up if we have actual groups loaded (avoid cleaning up during initial load)
+        if (groupNames.length === 0) return;
+
+        const currentGroupNames = new Set(groupNames);
+
+        setCollapsedGroups(prev => {
+            const cleaned = Object.fromEntries(
+                Object.entries(prev).filter(([groupName]) => currentGroupNames.has(groupName))
+            );
+
+            // Only update if something actually changed
+            const prevKeys = Object.keys(prev);
+            const cleanedKeys = Object.keys(cleaned);
+
+            if (prevKeys.length === cleanedKeys.length && prevKeys.every(key => cleanedKeys.includes(key))) {
+                return prev;
+            }
+
+            return cleaned;
+        });
+    }, [groupNames]);
+
+    const isGroupCollapsed = useCallback((name: string) => {
+        return !!collapsedGroups[name];
+    }, [collapsedGroups]);
+
+    const toggleGroupCollapsed = useCallback((name: string) => {
+        setCollapsedGroups(prev => ({ ...prev, [name]: !prev[name] }));
+    }, []);
+
+    return {
+        isGroupCollapsed,
+        toggleGroupCollapsed
+    };
+}
+

package/src/hooks/useCustomizationController.tsx

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { CustomizationController } from "@rebasepro/types";
+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 { DialogsControllerContext } from "../contexts/DialogsProvider";
+import { DialogsController } from "@rebasepro/types";
+
+/**
+ * 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
+ * `Rebase`
+ *
+ * @group Hooks and utilities
+ */
+export const useDialogsController = (): DialogsController => useContext(DialogsControllerContext);

package/src/hooks/useEffectiveRoleController.tsx

@@ -0,0 +1,10 @@
+import { useContext } from "react";
+import { EffectiveRoleControllerContext } from "../contexts/EffectiveRoleController";
+
+/**
+ * Hook to retrieve the {@link EffectiveRoleController}
+ *
+ * @see EffectiveRoleController
+ * @category Hooks and utilities
+ */
+export const useEffectiveRoleController = () => useContext(EffectiveRoleControllerContext);

package/src/hooks/useEntitySelectionDialog.tsx

@@ -0,0 +1,56 @@
+import { useSideDialogsController } from "./useSideDialogsController";
+import { EntitySelectionProps, EntitySelectionTable } from "../components";
+import { useCallback } from "react";
+import { useCollectionRegistryController } from "./navigation/contexts";
+
+/**
+ * This hook is used to open a side dialog that allows the selection
+ * of entities under a given path.
+ * You can use it in custom views for selecting entities.
+ * You need to specify the path of the target collection at least.
+ * If your collection is not defined in your  top collection configuration
+ * (in your `Rebase` component), you need to specify explicitly.
+ * This is the same hook used internally when a reference property is defined.
+ * @group Hooks and utilities
+ */
+export function useEntitySelectionDialog<M extends Record<string, any>>(referenceDialogProps: Omit<EntitySelectionProps<M>, "path"> & {
+    path?: string | false;
+    onClose?: () => void;
+}): { open: () => void; close: () => void } {
+
+    const navigation = useCollectionRegistryController();
+    const sideDialogsController = useSideDialogsController();
+
+    const open = useCallback(() => {
+        if (referenceDialogProps.path) {
+            let usedCollection = referenceDialogProps.collection;
+            if (!usedCollection)
+                usedCollection = navigation.getCollection(referenceDialogProps.path);
+            if (!usedCollection)
+                throw Error("Not able to resolve the collection in useEntitySelectionDialog. Make sure a collection is registered in path " + referenceDialogProps.path);
+            sideDialogsController.open({
+                key: `reference_${referenceDialogProps.path}`,
+                component:
+                    <EntitySelectionTable
+                        collection={usedCollection}
+                        {...referenceDialogProps as EntitySelectionProps<M>} />,
+                width: "90vw",
+                onClose: () => {
+                    referenceDialogProps.onClose?.();
+                }
+            });
+        } else {
+            throw Error("useReferenceDialog: You are trying to open a reference dialog, but have not declared the `path`")
+        }
+    }, [navigation, referenceDialogProps, sideDialogsController]);
+
+    const close = useCallback(() => {
+        sideDialogsController.close();
+    }, [sideDialogsController]);
+
+    return {
+        open,
+        close
+    }
+
+}

package/src/hooks/useInternalUserManagementController.tsx

@@ -0,0 +1,17 @@
+import { useContext } from "react";
+import { InternalUserManagementContext } from "../contexts/InternalUserManagementContext";
+import { User, UserManagementDelegate } from "@rebasepro/types";
+
+/**
+ * Use this hook to get the internal user management of the app.
+ * Note that this is different from the user management plugin controller.
+ * This controller will be eventually replaced by the one provided
+ * by the user management plugin.
+ *
+ * Use at your own risk!
+ *
+ * @group Hooks and utilities
+ */
+export function useInternalUserManagementController<USER extends User>(): UserManagementDelegate<USER> | undefined {
+    return useContext(InternalUserManagementContext);
+}