@rebasepro/admin 0.0.1-canary.09e5ec5

package/src/hooks/navigation/useResolvedCollections.ts

@@ -0,0 +1,133 @@
+import type { EntityCollection, RebasePlugin } from "@rebasepro/types";
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+
+import { AuthController, CollectionRegistryController, RebaseData, User } from "@rebasepro/types";
+import type { EntityCollectionsBuilder } from "@rebasepro/types";
+import { CollectionRegistry } from "@rebasepro/common";
+
+import { resolveCollections } from "./useNavigationResolution";
+import { areCollectionListsEqual } from "./utils";
+
+export type UseResolvedCollectionsProps<EC extends EntityCollection, USER extends User> = {
+    authController: AuthController<USER>;
+    collections?: EC[] | EntityCollectionsBuilder<EC>;
+    data: RebaseData;
+    plugins?: RebasePlugin[];
+    disabled?: boolean;
+    collectionRegistryController: CollectionRegistryController<EC> & { collectionRegistryRef: React.MutableRefObject<CollectionRegistry> };
+};
+
+export type UseResolvedCollectionsResult = {
+    collections: EntityCollection[];
+    loading: boolean;
+    error: Error | undefined;
+    refresh: () => void;
+};
+
+/**
+ * Hook that resolves collection props (which may be async builders or arrays)
+ * into concrete EntityCollection[], and registers them with the CollectionRegistry.
+ *
+ * Uses refs for potentially-unstable dependencies (driver, authController,
+ * plugins) to avoid re-triggering effects when their object identity changes.
+ */
+export function useResolvedCollections<EC extends EntityCollection, USER extends User>(
+    props: UseResolvedCollectionsProps<EC, USER>
+): UseResolvedCollectionsResult {
+
+    const {
+        authController,
+        collections: collectionsProp,
+        data,
+        plugins,
+        disabled,
+        collectionRegistryController
+    } = props;
+
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | undefined>(undefined);
+    const [resolvedCollections, setResolvedCollections] = useState<EntityCollection[]>([]);
+
+    // Track the trigger count to allow force-refresh
+    const [refreshTrigger, setRefreshTrigger] = useState(0);
+
+    const refresh = useCallback(() => {
+        setRefreshTrigger(prev => prev + 1);
+    }, []);
+
+    // Use refs for values that may be new objects each render but shouldn't
+    // re-trigger the effect. The effect reads them at execution time.
+    const dataRef = useRef(data);
+    dataRef.current = data;
+    const authControllerRef = useRef(authController);
+    authControllerRef.current = authController;
+    const pluginsRef = useRef(plugins);
+    pluginsRef.current = plugins;
+
+    // Ref for resolved collections change detection
+    const resolvedCollectionsRef = useRef<EntityCollection[]>([]);
+
+    const initialLoading = authController.initialLoading;
+    const user = authController.user;
+
+    useEffect(() => {
+        if (disabled || initialLoading) return;
+
+        let cancelled = false;
+
+        (async () => {
+            try {
+                const resolved = await resolveCollections(
+                    collectionsProp,
+                    authControllerRef.current,
+                    dataRef.current,
+                    pluginsRef.current
+                );
+
+                if (cancelled) return;
+
+                // Register with the CollectionRegistry; returns true if changed
+                const changed = collectionRegistryController.collectionRegistryRef.current.registerMultiple(resolved);
+
+                if (changed) {
+                    console.debug("Collections have changed", resolved);
+                }
+
+                // Only update state if collections actually changed
+                if (!areCollectionListsEqual(resolvedCollectionsRef.current, resolved)) {
+                    resolvedCollectionsRef.current = resolved;
+                    setResolvedCollections(resolved);
+                }
+
+                setError(undefined);
+            } catch (e) {
+                if (!cancelled) {
+                    console.error(e);
+                    setError(e as Error);
+                }
+            } finally {
+                if (!cancelled) {
+                    setLoading(false);
+                }
+            }
+        })();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        collectionsProp,
+        disabled,
+        collectionRegistryController.collectionRegistryRef,
+        refreshTrigger,
+        initialLoading,
+        user
+    ]);
+
+    return useMemo(() => ({
+        collections: resolvedCollections,
+        loading,
+        error,
+        refresh
+    }), [resolvedCollections, loading, error, refresh]);
+}

package/src/hooks/navigation/useResolvedViews.tsx

@@ -0,0 +1,216 @@
+
+import type { AppView, AppViewsBuilder, EffectiveRoleController, EntityCollection, RebasePlugin } from "@rebasepro/types";
+import React, { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+/**
+ * Compare two view arrays by their slug identity.
+ * Returns true when the sets of slugs are identical (same order, same values).
+ * This avoids deepEqual on React elements, which have unstable internal refs.
+ */
+function viewSlugsEqual(a: AppView[] | undefined, b: AppView[] | undefined): boolean {
+    if (a === b) return true;
+    if (!a || !b) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i].slug !== b[i].slug) return false;
+    }
+    return true;
+}
+
+import { AuthController, RebaseData, User } from "@rebasepro/types";
+import { UserManagementDelegate } from "@rebasepro/types";
+
+import { resolveAppViews } from "./useNavigationResolution";
+import { NAVIGATION_ADMIN_GROUP_NAME } from "./utils";
+
+// Lazy-load admin views — only rendered when navigation reaches /users or /roles
+const UsersView = lazy(() => import("../../components/admin/UsersView").then(m => ({ default: m.UsersView })));
+const RolesView = lazy(() => import("../../components/admin/RolesView").then(m => ({ default: m.RolesView })));
+
+export type UseResolvedViewsProps<USER extends User> = {
+    authController: AuthController<USER>;
+    views?: AppView[] | AppViewsBuilder;
+    adminViews?: AppView[] | AppViewsBuilder;
+    data: RebaseData;
+    plugins?: RebasePlugin[];
+    adminMode?: "content" | "studio" | "settings";
+    effectiveRoleController?: EffectiveRoleController;
+    userManagement?: UserManagementDelegate<USER>;
+};
+
+export type UseResolvedViewsResult = {
+    views: AppView[] | undefined;
+    adminViews: AppView[] | undefined;
+    loading: boolean;
+    error: Error | undefined;
+    refresh: () => void;
+};
+
+/**
+ * Hook that resolves view and admin view props (which may be async builders or arrays)
+ * into concrete AppView[]. Also injects Users/Roles admin views when userManagement
+ * is provided.
+ *
+ * Uses refs for potentially-unstable dependencies (driver, authController,
+ * plugins) to avoid re-triggering effects when their object identity changes.
+ */
+export function useResolvedViews<USER extends User>(
+    props: UseResolvedViewsProps<USER>
+): UseResolvedViewsResult {
+
+    const {
+        authController,
+        views: viewsProp,
+        adminViews: adminViewsProp,
+        data,
+        plugins,
+        adminMode = "content",
+        effectiveRoleController,
+        userManagement
+    } = props;
+
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | undefined>(undefined);
+    const [resolvedViews, setResolvedViews] = useState<AppView[] | undefined>(undefined);
+    const [resolvedAdminViews, setResolvedAdminViews] = useState<AppView[] | undefined>(undefined);
+
+    // Track the trigger count to allow force-refresh
+    const [refreshTrigger, setRefreshTrigger] = useState(0);
+
+    const refresh = useCallback(() => {
+        setRefreshTrigger(prev => prev + 1);
+    }, []);
+
+    // Refs for change-detection (avoids state updates when views haven't changed)
+    const viewsRef = useRef<AppView[] | undefined>(undefined);
+    const adminViewsRef = useRef<AppView[] | undefined>(undefined);
+
+    // Use refs for values that may be new objects each render but shouldn't
+    // re-trigger the effect. The effect reads them at execution time.
+    const dataRef = useRef(data);
+    dataRef.current = data;
+    const authControllerRef = useRef(authController);
+    authControllerRef.current = authController;
+    const pluginsRef = useRef(plugins);
+    pluginsRef.current = plugins;
+
+    // Build the resolved auth controller (with effective role override for studio mode)
+    const resolvedAuthController = useMemo(() => {
+        if (adminMode === "studio" && effectiveRoleController?.effectiveRole && authController.user) {
+            return {
+                ...authController,
+                user: {
+                    ...authController.user,
+                    roles: [effectiveRoleController.effectiveRole]
+                }
+            };
+        }
+        return authController;
+    }, [adminMode, effectiveRoleController?.effectiveRole, authController]);
+
+    // Store resolvedAuthController in a ref for effect access without re-triggering
+    const resolvedAuthControllerRef = useRef(resolvedAuthController);
+    resolvedAuthControllerRef.current = resolvedAuthController;
+
+    // Memoize JSX elements for injected admin views to ensure stable references.
+    const usersViewElement = useMemo(() =>
+        userManagement ? <Suspense fallback={null}><UsersView userManagement={userManagement as unknown as UserManagementDelegate<User>}/></Suspense> : null,
+        [userManagement]
+    );
+    const rolesViewElement = useMemo(() =>
+        userManagement?.roles ? <Suspense fallback={null}><RolesView userManagement={userManagement as unknown as UserManagementDelegate<User>}/></Suspense> : null,
+        [userManagement]
+    );
+
+    const injectedAdminViews: AppView[] = useMemo(() => {
+        const views: AppView[] = [];
+        if (userManagement && usersViewElement) {
+            views.push({
+                slug: "users",
+                name: "Users",
+                group: NAVIGATION_ADMIN_GROUP_NAME,
+                icon: "Headset",
+                view: usersViewElement
+            });
+            if (userManagement.roles && rolesViewElement) {
+                views.push({
+                    slug: "roles",
+                    name: "Roles",
+                    group: NAVIGATION_ADMIN_GROUP_NAME,
+                    icon: "Shield",
+                    view: rolesViewElement
+                });
+            }
+        }
+        return views;
+    }, [userManagement, usersViewElement, rolesViewElement]);
+
+    // Store injectedAdminViews in a ref for effect access
+    const injectedAdminViewsRef = useRef(injectedAdminViews);
+    injectedAdminViewsRef.current = injectedAdminViews;
+
+    const initialLoading = resolvedAuthController.initialLoading;
+    const user = resolvedAuthController.user;
+
+    useEffect(() => {
+        if (initialLoading) return;
+
+        let cancelled = false;
+
+        (async () => {
+            try {
+                const [newViews, newAdminViewsProp] = await Promise.all([
+                    resolveAppViews(viewsProp, resolvedAuthControllerRef.current, dataRef.current, pluginsRef.current),
+                    resolveAppViews(adminViewsProp, resolvedAuthControllerRef.current, dataRef.current)
+                ]);
+
+                if (cancelled) return;
+
+                const newAdminViews = [...newAdminViewsProp, ...injectedAdminViewsRef.current];
+
+                // Compare views by slug identity rather than deepEqual.
+                // Views contain React elements (JSX) whose internal properties
+                // change on every render, making deepEqual unreliable.
+                if (!viewSlugsEqual(viewsRef.current, newViews)) {
+                    viewsRef.current = newViews;
+                    setResolvedViews(newViews);
+                }
+
+                if (!viewSlugsEqual(adminViewsRef.current, newAdminViews)) {
+                    adminViewsRef.current = newAdminViews;
+                    setResolvedAdminViews(newAdminViews);
+                }
+
+                setError(undefined);
+            } catch (e) {
+                if (!cancelled) {
+                    console.error("Error resolving views:", e);
+                    setError(e as Error);
+                }
+            } finally {
+                if (!cancelled) {
+                    setLoading(false);
+                }
+            }
+        })();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        viewsProp,
+        adminViewsProp,
+        refreshTrigger,
+        adminMode,
+        initialLoading,
+        user
+    ]);
+
+    return useMemo(() => ({
+        views: resolvedViews,
+        adminViews: resolvedAdminViews,
+        loading,
+        error,
+        refresh
+    }), [resolvedViews, resolvedAdminViews, loading, error, refresh]);
+}

package/src/hooks/navigation/useTopLevelNavigation.ts

@@ -0,0 +1,257 @@
+import type { AppView, UrlController, EntityCollection, RebasePlugin, NavigationEntry, NavigationGroupMapping, NavigationResult } from "@rebasepro/types";
+import { useCallback, useMemo, useRef } from "react";
+import { deepEqual as equal } from "fast-equals";
+
+import { 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: AppView[] | undefined;
+    adminViews: AppView[] | undefined;
+    plugins?: RebasePlugin[];
+    navigationGroupMappings?: NavigationGroupMapping[];
+    viewsOrder?: string[];
+    urlController: UrlController;
+    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,
+        urlController,
+        adminMode,
+        collectionRegistryController
+    } = props;
+
+    const pluginGroups = useMemo(() => {
+        const allPluginGroups = plugins?.flatMap(plugin => plugin.hooks?.navigationEntries ? plugin.hooks.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.hooks?.onNavigationEntriesUpdate)) {
+            plugins.forEach((plugin: RebasePlugin) => {
+                if (plugin.hooks?.onNavigationEntriesUpdate) {
+                    plugin.hooks.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: urlController.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: urlController.buildAppUrlPath(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: urlController.buildAppUrlPath(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.hooks?.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,
+        urlController.buildAppUrlPath,
+        urlController.buildUrlCollectionPath,
+        pluginGroups,
+        plugins,
+        adminMode,
+        viewsOrder,
+        onNavigationEntriesOrderUpdate
+    ]);
+
+    return useMemo(() => ({
+        topLevelNavigation
+    }), [topLevelNavigation]);
+}