@rebasepro/core 0.0.1-canary.0

package/src/hooks/navigation/useNavigationRegistry.ts

@@ -0,0 +1,142 @@
+import { useCallback, useRef } from "react";
+import { CollectionRegistry, getParentReferencesFromPath, getSubcollections, mergeDeep, removeInitialAndTrailingSlashes } from "@rebasepro/common";
+import { EntityCollection, EntityReference, UserConfigurationPersistence } from "@rebasepro/types";
+
+export function useNavigationRegistry(userConfigPersistence?: UserConfigurationPersistence) {
+    const collectionRegistryRef = useRef<CollectionRegistry>(new CollectionRegistry());
+
+    const getCollection = useCallback((
+        slugOrPath: string,
+        includeUserOverride = false
+    ): EntityCollection | undefined => {
+
+        const registry = collectionRegistryRef.current;
+
+        const cleanedPath = removeInitialAndTrailingSlashes(slugOrPath);
+        if (!cleanedPath) return undefined;
+
+        const pathSegments = cleanedPath.split("/");
+
+        let collectionPath = cleanedPath;
+        // If the path has an even number of segments, it points to an entity, so we get the parent collection
+        if (pathSegments.length > 0 && pathSegments.length % 2 === 0) {
+            collectionPath = pathSegments.slice(0, -1).join("/");
+        }
+
+        if (!collectionPath) return undefined;
+
+        let collection: EntityCollection | undefined;
+        try {
+            collection = registry.resolvePathToCollections(collectionPath).finalCollection;
+        } catch (e) {
+            console.debug(`Could not resolve path to collection: ${collectionPath}`, e);
+            return undefined;
+        }
+
+        if (!collection) {
+            return undefined;
+        }
+
+        const userOverride = includeUserOverride ? userConfigPersistence?.getCollectionConfig(slugOrPath) : undefined;
+        const overriddenCollection = collection ? mergeDeep(collection, userOverride ?? {}) : undefined;
+
+        if (!overriddenCollection) return undefined;
+
+        let result: Partial<EntityCollection> | undefined = overriddenCollection;
+        const subcollections = overriddenCollection.subcollections;
+        const callbacks = overriddenCollection.callbacks;
+        result = {
+            ...result,
+            subcollections: result?.subcollections ?? subcollections,
+            callbacks: result?.callbacks ?? callbacks
+        };
+
+        return { ...overriddenCollection, ...result } as EntityCollection;
+
+    }, [userConfigPersistence]);
+
+    const getRawCollection = useCallback((slugOrPath: string): EntityCollection | undefined => {
+        const registry = collectionRegistryRef.current;
+        if (registry === undefined) return undefined;
+
+        const cleanedPath = removeInitialAndTrailingSlashes(slugOrPath);
+        if (!cleanedPath) return undefined;
+
+        return registry.getRaw(cleanedPath) as EntityCollection | undefined;
+    }, []);
+
+    const getCollectionFromPaths = useCallback(<EC extends EntityCollection>(pathSegments: string[]): EC | undefined => {
+        const registry = collectionRegistryRef.current;
+        if (registry === undefined)
+            throw Error("getCollectionFromPaths: Collections have not been initialised yet");
+
+        if (!pathSegments?.length) {
+            return undefined;
+        }
+
+        const path = pathSegments.reduce((acc, segment, i) => {
+            if (i === 0) return segment;
+            return `${acc}/fake_id/${segment}`;
+        }, "");
+
+        try {
+            const { finalCollection } = registry.resolvePathToCollections(path);
+            return finalCollection as EC | undefined;
+        } catch (e) {
+            console.debug(`Could not resolve path segments to collection: ${pathSegments.join("/")}`, e);
+            return undefined;
+        }
+    }, []);
+
+    const getAllParentReferencesForPath = useCallback((path: string): EntityReference[] => {
+        const registry = collectionRegistryRef.current;
+        if (!registry) {
+            return [];
+        }
+        return getParentReferencesFromPath({
+            path,
+            collections: registry.getCollections()
+        });
+    }, []);
+
+    const getParentCollectionIds = useCallback((path: string): string[] => {
+        const strings = path.split("/");
+        const oddPathSegments = strings.filter((_, i) => i % 2 === 0);
+        oddPathSegments.pop();
+
+        const result: string[][] = [];
+
+        for (let i = 1; i <= oddPathSegments.length; i++) {
+            result.push(oddPathSegments.slice(0, i));
+        }
+
+        return result.map(r => getCollectionFromPaths(r)?.slug).filter(Boolean) as string[];
+    }, [getAllParentReferencesForPath, getCollectionFromPaths]);
+
+    const convertIdsToPaths = useCallback((ids: string[]): string[] => {
+        const registry = collectionRegistryRef.current;
+        if (!registry) {
+            throw new Error("convertIdsToPaths: collectionRegistryRef not initialised");
+        }
+        let currentCollections: EntityCollection[] = registry.getCollections();
+        const paths: string[] = [];
+        for (let i = 0; i < ids.length; i++) {
+            const id = ids[i];
+            const collection: EntityCollection | undefined = currentCollections.find(c => c.slug === id);
+            if (!collection)
+                throw Error(`Collection with id ${id} not found`);
+            paths.push(collection.dbPath);
+            currentCollections = getSubcollections(collection) ?? [];
+        }
+        return paths;
+    }, []);
+
+    return {
+        collectionRegistryRef,
+        getCollection,
+        getRawCollection,
+        getParentReferencesFromPath: getAllParentReferencesForPath,
+        getParentCollectionIds,
+        convertIdsToPaths
+    };
+}

package/src/hooks/navigation/useNavigationResolution.ts

@@ -0,0 +1,98 @@
+import {
+    AuthController,
+    CMSView,
+    CMSViewsBuilder,
+    DataSource,
+    EntityCollection,
+    EntityCollectionsBuilder,
+    RebasePlugin,
+    User
+} from "@rebasepro/types";
+import { canReadCollection } from "@rebasepro/common";
+
+export function filterOutNotAllowedCollections(resolvedCollections: EntityCollection[], authController: AuthController<User>): EntityCollection[] {
+    return resolvedCollections
+        .filter((c) => canReadCollection(c, authController))
+        .map((c) => {
+            if (!c.subcollections) return c;
+            return {
+                ...c,
+                subcollections: () => filterOutNotAllowedCollections(c.subcollections?.() ?? [], authController)
+            }
+        });
+}
+
+export function applyPluginModifyCollection(resolvedCollections: EntityCollection[], modifyCollection: (collection: EntityCollection) => EntityCollection) {
+    return resolvedCollections.map((collection: EntityCollection): EntityCollection => {
+        const modifiedCollection = modifyCollection(collection);
+        if (modifiedCollection.subcollections) {
+            return {
+                ...modifiedCollection,
+                subcollections: () => applyPluginModifyCollection(modifiedCollection.subcollections?.() ?? [], modifyCollection)
+            } satisfies EntityCollection;
+        }
+        return modifiedCollection;
+    });
+}
+
+export async function resolveCollections(
+    collections: undefined | EntityCollection[] | EntityCollectionsBuilder<any>,
+    authController: AuthController,
+    dataSource: DataSource,
+    plugins: RebasePlugin[] | undefined
+): Promise<EntityCollection[]> {
+    let resolvedCollections: EntityCollection[] = [];
+    if (typeof collections === "function") {
+        resolvedCollections = await collections({
+            user: authController.user,
+            authController,
+            dataSource
+        });
+    } else if (Array.isArray(collections)) {
+        resolvedCollections = collections;
+    }
+
+    if (plugins) {
+        for (const plugin of plugins) {
+            if (plugin.collection?.modifyCollection) {
+                resolvedCollections = applyPluginModifyCollection(resolvedCollections, plugin.collection.modifyCollection);
+            }
+
+            if (plugin.collection?.injectCollections) {
+                resolvedCollections = plugin.collection.injectCollections(resolvedCollections ?? []);
+            }
+        }
+    }
+
+    resolvedCollections = filterOutNotAllowedCollections(resolvedCollections, authController);
+    return resolvedCollections;
+}
+
+export async function resolveCMSViews(
+    baseViews: CMSView[] | CMSViewsBuilder | undefined,
+    authController: AuthController,
+    dataSource: DataSource,
+    plugins?: RebasePlugin[]
+) {
+    let resolvedViews: CMSView[] = [];
+    if (typeof baseViews === "function") {
+        resolvedViews = await baseViews({
+            user: authController.user,
+            authController,
+            dataSource
+        });
+    } else if (Array.isArray(baseViews)) {
+        resolvedViews = baseViews;
+    }
+
+    // Inject views from plugins
+    if (plugins) {
+        for (const plugin of plugins) {
+            if (plugin.views && plugin.views.length > 0) {
+                resolvedViews = [...resolvedViews, ...plugin.views];
+            }
+        }
+    }
+
+    return resolvedViews;
+}

package/src/hooks/navigation/useNavigationURLs.ts

@@ -0,0 +1,56 @@
+import { useCallback } from "react";
+import { removeInitialAndTrailingSlashes, resolveCollectionPathIds } from "@rebasepro/common";
+import { CollectionRegistry } from "@rebasepro/common";
+
+export function encodePath(input: string) {
+    return encodeURIComponent(removeInitialAndTrailingSlashes(input))
+        .replaceAll("%2F", "/")
+        .replaceAll("%23", "#");
+}
+
+export function useNavigationURLs(basePath: string, baseCollectionPath: string, collectionRegistryRef: React.MutableRefObject<CollectionRegistry>) {
+
+    const cleanBasePath = removeInitialAndTrailingSlashes(basePath);
+    const cleanBaseCollectionPath = removeInitialAndTrailingSlashes(baseCollectionPath);
+
+    const homeUrl = cleanBasePath ? `/${cleanBasePath}` : "/";
+    const fullCollectionPath = cleanBasePath ? `/${cleanBasePath}/${cleanBaseCollectionPath}` : `/${cleanBaseCollectionPath}`;
+
+    const buildCMSUrlPath = useCallback((path: string): string => {
+        // Strip trailing /* wildcard from paths (used for nested routes in React Router)
+        const cleanPath = path.replace(/\/\*$/, "");
+        return cleanBasePath ? `/${cleanBasePath}/${encodePath(cleanPath)}` : `/${encodePath(cleanPath)}`;
+    }, [cleanBasePath]);
+
+    const buildUrlCollectionPath = useCallback((path: string): string => `${removeInitialAndTrailingSlashes(baseCollectionPath)}/${encodePath(path)}`,
+        [baseCollectionPath]);
+
+    const isUrlCollectionPath = useCallback(
+        (path: string): boolean => removeInitialAndTrailingSlashes(path + "/").startsWith(removeInitialAndTrailingSlashes(fullCollectionPath) + "/"),
+        [fullCollectionPath]);
+
+    const urlPathToDataPath = useCallback((path: string): string => {
+        const decodedPath = decodeURIComponent(path);
+        if (decodedPath.startsWith(fullCollectionPath))
+            return decodedPath.replace(fullCollectionPath, "");
+        throw Error("Expected path starting with " + fullCollectionPath);
+    }, [fullCollectionPath]);
+
+    const resolveDatabasePathsFrom = useCallback((path: string): string => {
+        const registry = collectionRegistryRef.current;
+        if (!registry) {
+            return resolveCollectionPathIds(path, []);
+        }
+        return resolveCollectionPathIds(path, registry.getCollections());
+    }, [collectionRegistryRef]);
+
+    return {
+        homeUrl,
+        fullCollectionPath,
+        buildCMSUrlPath,
+        buildUrlCollectionPath,
+        isUrlCollectionPath,
+        urlPathToDataPath,
+        resolveDatabasePathsFrom
+    };
+}

package/src/hooks/navigation/useResolvedCollections.ts

@@ -0,0 +1,139 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import {
+    AuthController,
+    CollectionRegistryController,
+    DataSource,
+    EntityCollection,
+    EntityCollectionsBuilder,
+    RebasePlugin,
+    User
+} 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>;
+    dataSource: DataSource;
+    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 (dataSource, 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,
+        dataSource,
+        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 dataSourceRef = useRef(dataSource);
+    dataSourceRef.current = dataSource;
+    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,
+                    dataSourceRef.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 {
+        collections: resolvedCollections,
+        loading,
+        error,
+        refresh
+    };
+}

package/src/hooks/navigation/useResolvedViews.tsx

@@ -0,0 +1,204 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { deepEqual as equal } from "fast-equals";
+
+import {
+    AuthController,
+    CMSView,
+    CMSViewsBuilder,
+    DataSource,
+    EffectiveRoleController,
+    EntityCollection,
+    RebasePlugin,
+    User
+} from "@rebasepro/types";
+import { UserManagementDelegate } from "@rebasepro/types";
+
+import { resolveCMSViews } from "./useNavigationResolution";
+import { NAVIGATION_ADMIN_GROUP_NAME } from "./utils";
+import { UsersView, RolesView } from "../../components/admin";
+
+export type UseResolvedViewsProps<USER extends User> = {
+    authController: AuthController<USER>;
+    views?: CMSView[] | CMSViewsBuilder;
+    adminViews?: CMSView[] | CMSViewsBuilder;
+    dataSource: DataSource;
+    plugins?: RebasePlugin[];
+    adminMode?: "content" | "studio" | "settings";
+    effectiveRoleController?: EffectiveRoleController;
+    userManagement?: UserManagementDelegate<USER>;
+};
+
+export type UseResolvedViewsResult = {
+    views: CMSView[] | undefined;
+    adminViews: CMSView[] | 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 CMSView[]. Also injects Users/Roles admin views when userManagement
+ * is provided.
+ *
+ * Uses refs for potentially-unstable dependencies (dataSource, 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,
+        dataSource,
+        plugins,
+        adminMode = "content",
+        effectiveRoleController,
+        userManagement
+    } = props;
+
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | undefined>(undefined);
+    const [resolvedViews, setResolvedViews] = useState<CMSView[] | undefined>(undefined);
+    const [resolvedAdminViews, setResolvedAdminViews] = useState<CMSView[] | 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<CMSView[] | undefined>(undefined);
+    const adminViewsRef = useRef<CMSView[] | 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 dataSourceRef = useRef(dataSource);
+    dataSourceRef.current = dataSource;
+    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 ? <UsersView userManagement={userManagement as unknown as UserManagementDelegate<User>} /> : null,
+        [userManagement]
+    );
+    const rolesViewElement = useMemo(() =>
+        userManagement?.roles ? <RolesView userManagement={userManagement as unknown as UserManagementDelegate<User>} /> : null,
+        [userManagement]
+    );
+
+    const injectedAdminViews: CMSView[] = useMemo(() => {
+        const views: CMSView[] = [];
+        if (userManagement && usersViewElement) {
+            views.push({
+                slug: "users",
+                name: "Users",
+                group: NAVIGATION_ADMIN_GROUP_NAME,
+                icon: "support_agent",
+                view: usersViewElement
+            });
+            if (userManagement.roles && rolesViewElement) {
+                views.push({
+                    slug: "roles",
+                    name: "Roles",
+                    group: NAVIGATION_ADMIN_GROUP_NAME,
+                    icon: "admin_panel_settings",
+                    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([
+                    resolveCMSViews(viewsProp, resolvedAuthControllerRef.current, dataSourceRef.current, pluginsRef.current),
+                    resolveCMSViews(adminViewsProp, resolvedAuthControllerRef.current, dataSourceRef.current)
+                ]);
+
+                if (cancelled) return;
+
+                const newAdminViews = [...newAdminViewsProp, ...injectedAdminViewsRef.current];
+
+                // Only update state if views actually changed
+                if (!equal(viewsRef.current, newViews)) {
+                    viewsRef.current = newViews;
+                    setResolvedViews(newViews);
+                }
+
+                if (!equal(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 {
+        views: resolvedViews,
+        adminViews: resolvedAdminViews,
+        loading,
+        error,
+        refresh
+    };
+}