@rebasepro/admin 0.0.1-canary.eae7889 → 0.0.1-canary.eb08332

package/src/hooks/navigation/useResolvedCollections.ts

@@ -1,24 +1,27 @@
-import type { EntityCollection, RebasePlugin } from "@rebasepro/types";
-import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+import type { CollectionConfig, RebasePlugin } from "@rebasepro/types";
+import { useRef, useMemo } from "react";
 
 import { AuthController, CollectionRegistryController, RebaseData, User } from "@rebasepro/types";
-import type { EntityCollectionsBuilder } from "@rebasepro/types";
+import type { CollectionConfigsBuilder } from "@rebasepro/types";
 import { CollectionRegistry } from "@rebasepro/common";
 
+
 import { resolveCollections } from "./useNavigationResolution";
 import { areCollectionListsEqual } from "./utils";
+import { useAsyncResolver } from "./useAsyncResolver";
 
-export type UseResolvedCollectionsProps<EC extends EntityCollection, USER extends User> = {
+export type UseResolvedCollectionsProps<EC extends CollectionConfig, USER extends User> = {
     authController: AuthController<USER>;
-    collections?: EC[] | EntityCollectionsBuilder<EC>;
+    collections?: EC[] | CollectionConfigsBuilder<EC>;
     data: RebaseData;
     plugins?: RebasePlugin[];
     disabled?: boolean;
     collectionRegistryController: CollectionRegistryController<EC> & { collectionRegistryRef: React.MutableRefObject<CollectionRegistry> };
+
 };
 
 export type UseResolvedCollectionsResult = {
-    collections: EntityCollection[];
+    collections: CollectionConfig[];
     loading: boolean;
     error: Error | undefined;
     refresh: () => void;
@@ -26,12 +29,16 @@ export type UseResolvedCollectionsResult = {
 
 /**
  * Hook that resolves collection props (which may be async builders or arrays)
- * into concrete EntityCollection[], and registers them with the CollectionRegistry.
+ * into concrete CollectionConfig[], and registers them with the CollectionRegistry.
+ *
+ * When userManagement is provided, the default users collection is always
+ * prepended. Developer collections override via generic slug-based dedup
+ * (Map keyed by slug, last-write-wins). No hardcoded string checks.
  *
  * 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>(
+export function useResolvedCollections<EC extends CollectionConfig, USER extends User>(
     props: UseResolvedCollectionsProps<EC, USER>
 ): UseResolvedCollectionsResult {
 
@@ -44,16 +51,11 @@ export function useResolvedCollections<EC extends EntityCollection, USER extends
         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);
-    }, []);
+    // Stable identity string for the user — avoids re-triggering when the
+    // authController object reference changes but uid/roles are the same.
+    const userIdentity = authController.user
+        ? `${authController.user.uid}:${(authController.user.roles ?? []).sort().join(',')}`
+        : null;
 
     // 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.
@@ -64,70 +66,36 @@ export function useResolvedCollections<EC extends EntityCollection, USER extends
     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);
-                }
+    const { data: collections, loading, error, refresh } = useAsyncResolver<CollectionConfig[]>({
+        resolver: async () => {
+            const resolved = await resolveCollections(
+                collectionsProp,
+                authControllerRef.current,
+                dataRef.current,
+                pluginsRef.current
+            );
+
+            const deduped = [...resolved];
+
+            // Register with the CollectionRegistry; returns true if changed
+            const changed = collectionRegistryController.collectionRegistryRef.current.registerMultiple(deduped);
+
+            if (changed) {
+                console.debug("Collections have changed", deduped);
             }
-        })();
 
-        return () => {
-            cancelled = true;
-        };
-    }, [
-        collectionsProp,
-        disabled,
-        collectionRegistryController.collectionRegistryRef,
-        refreshTrigger,
-        initialLoading,
-        user
-    ]);
+            return deduped;
+        },
+        initialValue: [],
+        isEqual: areCollectionListsEqual,
+        deps: [collectionsProp, userIdentity, disabled],
+        disabled: disabled || authController.initialLoading,
+    });
 
     return useMemo(() => ({
-        collections: resolvedCollections,
+        collections,
         loading,
         error,
         refresh
-    }), [resolvedCollections, loading, error, refresh]);
+    }), [collections, loading, error, refresh]);
 }

package/src/hooks/navigation/useResolvedViews.tsx

@@ -1,6 +1,6 @@
 
-import type { AppView, AppViewsBuilder, EffectiveRoleController, EntityCollection, RebasePlugin } from "@rebasepro/types";
-import React, { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { AppView, AppViewsBuilder, EffectiveRoleController, RebasePlugin } from "@rebasepro/types";
+import { useMemo, useRef } from "react";
 
 /**
  * Compare two view arrays by their slug identity.
@@ -17,15 +17,10 @@ function viewSlugsEqual(a: AppView[] | undefined, b: AppView[] | undefined): boo
     return true;
 }
 
-import { AuthController, RebaseData, User } from "@rebasepro/types";
-import { UserManagementDelegate } from "@rebasepro/types";
+import type { AuthController, RebaseData, User } 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 })));
+import { useAsyncResolver } from "./useAsyncResolver";
 
 export type UseResolvedViewsProps<USER extends User> = {
     authController: AuthController<USER>;
@@ -35,7 +30,6 @@ export type UseResolvedViewsProps<USER extends User> = {
     plugins?: RebasePlugin[];
     adminMode?: "content" | "studio" | "settings";
     effectiveRoleController?: EffectiveRoleController;
-    userManagement?: UserManagementDelegate<USER>;
 };
 
 export type UseResolvedViewsResult = {
@@ -46,10 +40,26 @@ export type UseResolvedViewsResult = {
     refresh: () => void;
 };
 
+/**
+ * Combined result type for the async resolver — holds both views and
+ * adminViews so they can be resolved together in a single async call.
+ */
+type ResolvedViewsData = {
+    views: AppView[] | undefined;
+    adminViews: AppView[] | undefined;
+};
+
+/**
+ * Equality check for the combined views data.
+ * Compares both views and adminViews by slug identity.
+ */
+function areResolvedViewsEqual(a: ResolvedViewsData, b: ResolvedViewsData): boolean {
+    return viewSlugsEqual(a.views, b.views) && viewSlugsEqual(a.adminViews, b.adminViews);
+}
+
 /**
  * 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.
+ * into concrete AppView[].
  *
  * Uses refs for potentially-unstable dependencies (driver, authController,
  * plugins) to avoid re-triggering effects when their object identity changes.
@@ -65,25 +75,14 @@ export function useResolvedViews<USER extends User>(
         data,
         plugins,
         adminMode = "content",
-        effectiveRoleController,
-        userManagement
+        effectiveRoleController
     } = 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);
+    // Stable identity string for the user — avoids re-triggering when the
+    // authController object reference changes but uid/roles are the same.
+    const userIdentity = authController.user
+        ? `${authController.user.uid}:${(authController.user.roles ?? []).sort().join(',')}`
+        : null;
 
     // 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.
@@ -112,105 +111,27 @@ export function useResolvedViews<USER extends User>(
     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
-    ]);
+    const { data: resolvedData, loading, error, refresh } = useAsyncResolver<ResolvedViewsData>({
+        resolver: async () => {
+            const [newViews, newAdminViews] = await Promise.all([
+                resolveAppViews(viewsProp, resolvedAuthControllerRef.current, dataRef.current, pluginsRef.current),
+                resolveAppViews(adminViewsProp, resolvedAuthControllerRef.current, dataRef.current)
+            ]);
+            return { views: newViews, adminViews: newAdminViews };
+        },
+        initialValue: { views: undefined, adminViews: undefined },
+        isEqual: areResolvedViewsEqual,
+        deps: [viewsProp, adminViewsProp, adminMode, userIdentity],
+        disabled: initialLoading,
+    });
 
     return useMemo(() => ({
-        views: resolvedViews,
-        adminViews: resolvedAdminViews,
+        views: resolvedData.views,
+        adminViews: resolvedData.adminViews,
         loading,
         error,
         refresh
-    }), [resolvedViews, resolvedAdminViews, loading, error, refresh]);
+    }), [resolvedData, loading, error, refresh]);
 }

package/src/hooks/navigation/useTopLevelNavigation.ts

@@ -1,4 +1,4 @@
-import type { AppView, UrlController, EntityCollection, RebasePlugin, NavigationEntry, NavigationGroupMapping, NavigationResult } from "@rebasepro/types";
+import type { AppView, UrlController, CollectionConfig, RebasePlugin, NavigationEntry, NavigationGroupMapping, NavigationResult } from "@rebasepro/types";
 import { useCallback, useMemo, useRef } from "react";
 import { deepEqual as equal } from "fast-equals";
 
@@ -8,7 +8,7 @@ import { CollectionRegistry } from "@rebasepro/common";
 import { computeNavigationGroups, getGroup, NAVIGATION_ADMIN_GROUP_NAME, NAVIGATION_DEFAULT_GROUP_NAME } from "./utils";
 
 export type UseTopLevelNavigationProps = {
-    collections: EntityCollection[];
+    collections: CollectionConfig[];
     views: AppView[] | undefined;
     adminViews: AppView[] | undefined;
     plugins?: RebasePlugin[];
@@ -16,7 +16,7 @@ export type UseTopLevelNavigationProps = {
     viewsOrder?: string[];
     urlController: UrlController;
     adminMode?: "content" | "studio" | "settings";
-    collectionRegistryController: CollectionRegistryController<any> & { collectionRegistryRef: React.MutableRefObject<CollectionRegistry> };
+    collectionRegistryController: CollectionRegistryController & { collectionRegistryRef: React.MutableRefObject<CollectionRegistry> };
 };
 
 export type UseTopLevelNavigationResult = {
@@ -178,26 +178,30 @@ export function useTopLevelNavigation(
         ];
 
         const groupOrderValue = (groupName?: string): number => {
-            if (groupName === NAVIGATION_ADMIN_GROUP_NAME) return 1;
+            if (groupName === NAVIGATION_ADMIN_GROUP_NAME || groupName === "Settings" || groupName === "Admin") return 1;
             return 0;
         };
 
+        const usedViewsOrder = viewsOrder ?? navigationEntriesOrder;
         navigationEntries = navigationEntries.sort((a, b) => {
-            return groupOrderValue(a.group) - groupOrderValue(b.group);
-        });
+            // Primary: group priority (admin/settings last)
+            const groupDiff = groupOrderValue(a.group) - groupOrderValue(b.group);
+            if (groupDiff !== 0) return groupDiff;
 
-        const usedViewsOrder = viewsOrder ?? navigationEntriesOrder;
-        if (usedViewsOrder) {
-            navigationEntries = navigationEntries.sort((a, b) => {
+            // Secondary: explicit view order (if provided)
+            if (usedViewsOrder) {
                 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;
-            });
-        }
+                if (aIndex !== -1 || bIndex !== -1) {
+                    if (aIndex === -1) return 1;
+                    if (bIndex === -1) return -1;
+                    return aIndex - bIndex;
+                }
+            }
+
+            return 0;
+        });
 
         const collectedGroupsFromEntries = navigationEntries
             .map(e => e.group)
@@ -213,9 +217,9 @@ export function useTopLevelNavigation(
         ];
 
         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 lastGroups = uniqueGroupsArray.filter(g => g === NAVIGATION_ADMIN_GROUP_NAME || g === "Settings" || g === "Admin");
+        const otherGroups = uniqueGroupsArray.filter(g => g !== NAVIGATION_ADMIN_GROUP_NAME && g !== "Settings" && g !== "Admin");
+        const uniqueGroups = [...otherGroups, ...lastGroups] as string[];
 
         const computedTopLevelNav = {
             allowDragAndDrop: plugins?.some((plugin: RebasePlugin) => plugin.hooks?.allowDragAndDrop) ?? false,

package/src/hooks/navigation/utils.ts

@@ -1,17 +1,17 @@
-import type { AppView, EntityCollection, RebasePlugin, NavigationGroupMapping } from "@rebasepro/types";
-;
+import type { AppView, CollectionConfig, 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> | AppView) {
+export function getGroup(collectionOrView: CollectionConfig | AppView) {
     const trimmed = collectionOrView.group?.trim();
     if (!trimmed || trimmed === "") {
         return NAVIGATION_DEFAULT_GROUP_NAME;
     }
-    return trimmed ?? NAVIGATION_DEFAULT_GROUP_NAME;
+    return trimmed;
 }
 
 export function computeNavigationGroups({
@@ -21,15 +21,18 @@ export function computeNavigationGroups({
     plugins
 }: {
     navigationGroupMappings?: NavigationGroupMapping[],
-    collections?: EntityCollection[],
+    collections?: CollectionConfig[],
     views?: AppView[],
     plugins?: RebasePlugin[]
 }): NavigationGroupMapping[] {
 
     // Deep clone the input groups upfront to avoid mutating the caller's data
     let result = navigationGroupMappings
-        ? navigationGroupMappings.map(g => ({ name: g.name,
-entries: [...g.entries] }))
+        ? navigationGroupMappings.map(g => ({
+            name: g.name,
+            entries: [...g.entries],
+            ...(g.collapsedByDefault !== undefined && { collapsedByDefault: g.collapsedByDefault })
+        }))
         : navigationGroupMappings;
 
     // Merge plugin navigation entries
@@ -143,7 +146,7 @@ entries: [...g.entries] }))
     return result;
 }
 
-export function areCollectionListsEqual(a: EntityCollection[], b: EntityCollection[], visitedSlugs: string[] = []) {
+export function areCollectionListsEqual(a: CollectionConfig[], b: CollectionConfig[], visitedSlugs: string[] = []) {
     if (a.length !== b.length) {
         return false;
     }
@@ -154,7 +157,7 @@ export function areCollectionListsEqual(a: EntityCollection[], b: EntityCollecti
     return aSorted.every((value, index) => areCollectionsEqual(value, bSorted[index], visitedSlugs));
 }
 
-export function areCollectionsEqual(a: EntityCollection, b: EntityCollection, visitedSlugs: string[] = []) {
+export function areCollectionsEqual(a: CollectionConfig, b: CollectionConfig, visitedSlugs: string[] = []) {
     if (a.slug !== b.slug) {
         return false;
     }

package/src/hooks/useBreadcrumbsController.tsx

@@ -1,40 +1,8 @@
 import { useContext } from "react";
 import { BreadcrumbContext } from "../contexts/BreacrumbsContext";
+import { BreadcrumbEntry, BreadcrumbsController } from "@rebasepro/types";
 
-/**
- * @group Hooks and utilities
- */
-export interface BreadcrumbsController {
-    breadcrumbs: BreadcrumbEntry[];
-    set: (props: {
-        breadcrumbs: BreadcrumbEntry[];
-    }) => void;
-    /**
-     * Update the count for a specific breadcrumb by ID.
-     */
-    updateCount: (id: string, count: number | null | undefined) => void;
-}
-
-
-/**
- * @group Hooks and utilities
- */
-export interface BreadcrumbEntry {
-    title: string;
-    url: string;
-    /**
-     * Optional entity count for collection breadcrumbs.
-     * - undefined: not applicable (e.g., entity breadcrumb, custom view)
-     * - null: loading
-     * - number: loaded count
-     */
-    count?: number | null;
-    /**
-     * Unique identifier for this breadcrumb (e.g., collection path).
-     * Used to update count without replacing entire breadcrumb array.
-     */
-    id?: string;
-}
+export type { BreadcrumbEntry, BreadcrumbsController };
 
 
 /**