@rebasepro/core 0.0.1-canary.0

package/src/hooks/navigation/useTopLevelNavigation.ts

@@ -0,0 +1,265 @@
+import { useCallback, useMemo, useRef } from "react";
+import { deepEqual as equal } from "fast-equals";
+
+import {
+    CMSView,
+    CMSUrlController,
+    EntityCollection,
+    RebasePlugin,
+    NavigationEntry,
+    NavigationGroupMapping,
+    NavigationResult,
+    CollectionRegistryController
+} from "@rebasepro/types";
+import { CollectionRegistry } from "@rebasepro/common";
+
+import { computeNavigationGroups, getGroup, NAVIGATION_ADMIN_GROUP_NAME, NAVIGATION_DEFAULT_GROUP_NAME } from "./utils";
+
+export type UseTopLevelNavigationProps = {
+    collections: EntityCollection[];
+    views: CMSView[] | undefined;
+    adminViews: CMSView[] | undefined;
+    plugins?: RebasePlugin[];
+    navigationGroupMappings?: NavigationGroupMapping[];
+    viewsOrder?: string[];
+    cmsUrlController: CMSUrlController;
+    adminMode?: "content" | "studio" | "settings";
+    collectionRegistryController: CollectionRegistryController<any> & { collectionRegistryRef: React.MutableRefObject<CollectionRegistry> };
+};
+
+export type UseTopLevelNavigationResult = {
+    topLevelNavigation: NavigationResult | undefined;
+};
+
+/**
+ * Hook that computes the top-level NavigationResult from resolved collections,
+ * views, and admin views. Pure computation — no async, no effects.
+ *
+ * The `onNavigationEntriesUpdate` callback is embedded in the result for API
+ * compatibility, but its reference is stable via useCallback.
+ */
+export function useTopLevelNavigation(
+    props: UseTopLevelNavigationProps
+): UseTopLevelNavigationResult {
+
+    const {
+        collections,
+        views,
+        adminViews,
+        plugins,
+        navigationGroupMappings,
+        viewsOrder,
+        cmsUrlController,
+        adminMode,
+        collectionRegistryController
+    } = props;
+
+    const pluginGroups = useMemo(() => {
+        const allPluginGroups = plugins?.flatMap(plugin => plugin.homePage?.navigationEntries ? plugin.homePage.navigationEntries.map(e => e.name) : []) ?? [];
+        return [...new Set(allPluginGroups)];
+    }, [plugins]);
+
+    // Stable reference to the drag-and-drop update callback.
+    // We use a ref-based approach internally so the callback identity doesn't
+    // change when collections/views change (which would cause NavigationResult
+    // equality to always fail).
+    const onNavigationEntriesOrderUpdate = useCallback((entries: NavigationGroupMapping[]) => {
+        if (!plugins) {
+            return;
+        }
+        // remove all groups that have no entries
+        const filteredEntries = entries.filter(entry => entry.entries.length > 0);
+
+        // Persist to backend via plugins
+        if (plugins.some((plugin: RebasePlugin) => plugin.homePage?.onNavigationEntriesUpdate)) {
+            plugins.forEach((plugin: RebasePlugin) => {
+                if (plugin.homePage?.onNavigationEntriesUpdate) {
+                    plugin.homePage.onNavigationEntriesUpdate(filteredEntries);
+                }
+            });
+        }
+    }, [plugins]);
+
+    const topLevelNavigationRef = useRef<NavigationResult | undefined>(undefined);
+
+    const topLevelNavigation = useMemo(() => {
+        // Don't compute until we have collections and views resolved
+        if (!views && !adminViews && collections.length === 0) {
+            return undefined;
+        }
+
+        const finalNavigationGroupMappings: NavigationGroupMapping[] = computeNavigationGroups({
+            navigationGroupMappings,
+            collections,
+            views: views,
+            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: cmsUrlController.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;
+                        }
+                    }
+                }
+
+                const basePathKey = Array.isArray(pathKey) ? pathKey[0] : pathKey;
+                acc.push({
+                    id: `view:${pathKey}`,
+                    url: cmsUrlController.buildCMSUrlPath(basePathKey),
+                    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, adminView) => {
+                if (adminView.hideFromNavigation) return acc;
+
+                const pathKey = adminView.slug;
+                let groupName = adminView.group?.trim() || NAVIGATION_ADMIN_GROUP_NAME;
+
+                if (finalNavigationGroupMappings) {
+                    for (const pluginGroupDef of finalNavigationGroupMappings) {
+                        if (pluginGroupDef.entries.includes(pathKey)) {
+                            groupName = pluginGroupDef.name;
+                            break;
+                        }
+                    }
+                }
+
+                acc.push({
+                    id: `admin:${pathKey}`,
+                    url: cmsUrlController.buildCMSUrlPath(pathKey),
+                    name: adminView.name.trim(),
+                    type: "admin",
+                    slug: adminView.slug,
+                    view: adminView,
+                    description: adminView.description?.trim(),
+                    group: groupName
+                });
+                return acc;
+            }, [] as NavigationEntry[])
+        ];
+
+        const groupOrderValue = (groupName?: string): number => {
+            if (groupName === NAVIGATION_ADMIN_GROUP_NAME) return 1;
+            return 0;
+        };
+
+        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[];
+
+        const groupsFromMappings = finalNavigationGroupMappings.map(g => g.name);
+        const additionalGroups = collectedGroupsFromEntries.filter(g => !groupsFromMappings.includes(g));
+
+        const allDefinedGroups = [
+            ...(pluginGroups ?? []),
+            ...groupsFromMappings,
+            ...additionalGroups
+        ];
+
+        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[];
+
+        const computedTopLevelNav = {
+            allowDragAndDrop: plugins?.some((plugin: RebasePlugin) => plugin.homePage?.allowDragAndDrop) ?? false,
+            navigationEntries,
+            groups: uniqueGroups,
+            onNavigationEntriesUpdate: onNavigationEntriesOrderUpdate,
+        };
+
+        // Cache the newly computed navigation result and return the cached reference
+        // if it is deeply equal to the previous one, to prevent reference churn.
+        const isNavEqual = topLevelNavigationRef.current &&
+            equal(topLevelNavigationRef.current.navigationEntries, computedTopLevelNav.navigationEntries) &&
+            equal(topLevelNavigationRef.current.groups, computedTopLevelNav.groups) &&
+            topLevelNavigationRef.current.allowDragAndDrop === computedTopLevelNav.allowDragAndDrop;
+
+        if (isNavEqual) {
+            return topLevelNavigationRef.current;
+        }
+
+        topLevelNavigationRef.current = computedTopLevelNav;
+        return computedTopLevelNav;
+    }, [
+        collections,
+        views,
+        adminViews,
+        navigationGroupMappings,
+        cmsUrlController.buildCMSUrlPath,
+        cmsUrlController.buildUrlCollectionPath,
+        pluginGroups,
+        plugins,
+        adminMode,
+        viewsOrder,
+        onNavigationEntriesOrderUpdate
+    ]);
+
+    return {
+        topLevelNavigation
+    };
+}

package/src/hooks/navigation/utils.ts

@@ -0,0 +1,177 @@
+import { CMSView, EntityCollection, RebasePlugin, NavigationGroupMapping } from "@rebasepro/types";
+import { getSubcollections } from "@rebasepro/common";
+import { deepEqual as equal } from "fast-equals";
+
+export const NAVIGATION_DEFAULT_GROUP_NAME = "Views";
+export const NAVIGATION_ADMIN_GROUP_NAME = "Admin";
+
+export function getGroup(collectionOrView: EntityCollection<any, any> | CMSView) {
+    const trimmed = collectionOrView.group?.trim();
+    if (!trimmed || trimmed === "") {
+        return NAVIGATION_DEFAULT_GROUP_NAME;
+    }
+    return trimmed ?? NAVIGATION_DEFAULT_GROUP_NAME;
+}
+
+export function computeNavigationGroups({
+    navigationGroupMappings,
+    collections,
+    views,
+    plugins
+}: {
+    navigationGroupMappings?: NavigationGroupMapping[],
+    collections?: EntityCollection[],
+    views?: CMSView[],
+    plugins?: RebasePlugin[]
+}): NavigationGroupMapping[] {
+
+    let result = navigationGroupMappings;
+
+    // Merge plugin navigation entries
+    // IMPORTANT: Deep clone the groups to avoid mutating the original input
+    result = plugins ? plugins?.reduce((acc, plugin) => {
+        if (plugin.homePage?.navigationEntries) {
+            plugin.homePage.navigationEntries.forEach((entry) => {
+                const {
+                    name,
+                    entries
+                } = entry;
+                const existingGroup = acc.find(g => g.name === name);
+                if (existingGroup) {
+                    existingGroup.entries.push(...entries);
+                } else {
+                    acc.push({
+                        name,
+                        entries: [...entries]
+                    });
+                }
+            });
+
+        }
+        return acc;
+    }, (result ?? []).map(g => ({
+        name: g.name,
+        entries: [...g.entries]
+    }))) : result;
+
+    // Track all entries that are already assigned to groups
+    const assignedEntries = new Set<string>();
+    if (result) {
+        result.forEach(group => {
+            group.entries.forEach(entry => assignedEntries.add(entry));
+        });
+    }
+
+    // Find collections and views that are NOT in any persisted group
+    const unassignedGroupMap: Record<string, string[]> = {};
+
+    // Check collections
+    (collections ?? []).forEach(collection => {
+        const entry = collection.slug;
+        if (!assignedEntries.has(entry)) {
+            const groupName = getGroup(collection);
+            if (!unassignedGroupMap[groupName]) unassignedGroupMap[groupName] = [];
+            unassignedGroupMap[groupName].push(entry);
+        }
+    });
+
+    // Check views
+    (views ?? []).forEach(view => {
+        const entry = Array.isArray(view.slug) ? view.slug[0] : view.slug;
+        if (!assignedEntries.has(entry)) {
+            const groupName = getGroup(view);
+            if (!unassignedGroupMap[groupName]) unassignedGroupMap[groupName] = [];
+            unassignedGroupMap[groupName].push(entry);
+        }
+    });
+
+    // Merge unassigned entries into existing groups or create new groups
+    Object.entries(unassignedGroupMap).forEach(([groupName, entries]) => {
+        if (result) {
+            const existingGroup = result.find(g => g.name === groupName);
+            if (existingGroup) {
+                existingGroup.entries.push(...entries);
+            } else {
+                result.push({
+                    name: groupName,
+                    entries
+                });
+            }
+        }
+    });
+
+    if (!result) {
+        // No persisted data at all - create from scratch
+        result = [];
+        const groupMap: Record<string, string[]> = {};
+
+        // Add collections
+        (collections ?? []).forEach(collection => {
+            const name = getGroup(collection);
+            const entry = collection.slug;
+            if (!groupMap[name]) groupMap[name] = [];
+            groupMap[name].push(entry);
+        });
+
+        // Add views
+        (views ?? []).forEach(view => {
+            const name = getGroup(view);
+            const entry = Array.isArray(view.slug) ? view.slug[0] : view.slug;
+            if (!groupMap[name]) groupMap[name] = [];
+            groupMap[name].push(entry);
+        });
+
+        // Convert groupMap to result array
+        result = Object.entries(groupMap).map(([name, entries]) => ({
+            name,
+            entries
+        }));
+    }
+
+    // Remove duplicates in entries
+    result.forEach(group => {
+        group.entries = [...new Set(group.entries)];
+    });
+
+    return result;
+}
+
+export function areCollectionListsEqual(a: EntityCollection[], b: EntityCollection[], visitedSlugs: string[] = []) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    const aCopy = [...a];
+    const bCopy = [...b];
+    const aSorted = aCopy.sort((x, y) => x.slug.localeCompare(y.slug));
+    const bSorted = bCopy.sort((x, y) => x.slug.localeCompare(y.slug));
+    return aSorted.every((value, index) => areCollectionsEqual(value, bSorted[index], visitedSlugs));
+}
+
+export function areCollectionsEqual(a: EntityCollection, b: EntityCollection, visitedSlugs: string[] = []) {
+    if (a.slug !== b.slug) {
+        return false;
+    }
+    if (visitedSlugs.includes(a.slug)) {
+        return true;
+    }
+    const newVisited = [...visitedSlugs, a.slug];
+
+    const {
+        subcollections: subcollectionsA,
+        ...restA
+    } = a;
+    const {
+        subcollections: subcollectionsB,
+        ...restB
+    } = b;
+    if (!areCollectionListsEqual(getSubcollections(a), getSubcollections(b), newVisited)) {
+        return false;
+    }
+    const restAWithoutFunctions = Object.fromEntries(
+        Object.entries(restA).filter(([_, v]) => typeof v !== 'function')
+    );
+    const restBWithoutFunctions = Object.fromEntries(
+        Object.entries(restB).filter(([_, v]) => typeof v !== 'function')
+    );
+    return equal(restAWithoutFunctions, restBWithoutFunctions);
+}

package/src/hooks/useAdminModeController.tsx

@@ -0,0 +1,23 @@
+import { AdminModeControllerContext } from "../contexts/AdminModeController";
+import { useContext } from "react";
+
+/**
+ * Use this controller to change the admin mode (developer vs editor)
+ * @group Hooks and utilities
+ */
+export interface AdminModeController {
+    mode: "content" | "studio" | "settings";
+    setMode: (mode: "content" | "studio" | "settings") => void;
+}
+
+/**
+ * Hook to retrieve the current admin mode ("developer" | "editor"), and `setMode`
+ * to change it.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see AdminModeController
+ * @group Hooks and utilities
+ */
+export const useAdminModeController = () => useContext(AdminModeControllerContext);

package/src/hooks/useAnalyticsController.tsx

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+import { AnalyticsController } from "@rebasepro/types";
+import { AnalyticsContext } from "../contexts/AnalyticsContext";
+
+/**
+ * @group Hooks and utilities
+ */
+export const useAnalyticsController = (): AnalyticsController => useContext(AnalyticsContext);

package/src/hooks/useAuthController.tsx

@@ -0,0 +1,14 @@
+import { AuthController, User } from "@rebasepro/types";
+import { useContext } from "react";
+import { AuthControllerContext } from "../contexts/AuthControllerContext";
+
+/**
+ * Hook to retrieve the AuthContext.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see AuthController
+ * @group Hooks and utilities
+ */
+export const useAuthController = <USER extends User = User, AuthControllerType extends AuthController<USER> = AuthController<USER>>(): AuthControllerType => useContext(AuthControllerContext) as AuthControllerType;