@rebasepro/core 0.0.1-canary.0

package/src/hooks/data/useRelationSelector.tsx

@@ -0,0 +1,205 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDataSource } from "../../hooks";
+import { Entity, EntityCollection, EntityRelation, FilterValues } from "@rebasepro/types";
+import { RelationItem } from "../../components/RelationSelector";
+
+export interface UseRelationSelectorProps<M extends Record<string, any> = any> {
+    /**
+     * Full path where the relation data is located
+     */
+    path: string;
+    /**
+     * The collection that represents the relation entities
+     */
+    collection: EntityCollection<M>;
+    /**
+     * Force filter to be applied to the relation search
+     */
+    forceFilter?: FilterValues<string>;
+    /**
+     * Page size for pagination
+     */
+    pageSize?: number;
+    /**
+     * Function to extract the label from an entity
+     */
+    getLabelFromEntity?: (entity: Entity<M>) => string;
+    /**
+     * Function to extract the description from an entity
+     */
+    getDescriptionFromEntity?: (entity: Entity<M>) => string | undefined;
+    /**
+     * Property name to use as the secondary display field
+     */
+    descriptionProperty?: keyof M;
+}
+
+export interface RelationSelectorController {
+    items: RelationItem[];
+    isLoading: boolean;
+    error: Error | undefined;
+    search: (searchString: string) => void;
+    loadMore: () => void;
+    hasMore: boolean;
+    entityToRelationItem: (entity: Entity<any>, relation: EntityRelation) => RelationItem;
+}
+
+const DEFAULT_PAGE_SIZE = 10;
+
+/**
+ * Hook to manage relation selection with data fetching from Rebase data source
+ */
+export function useRelationSelector<M extends Record<string, any> = any>(
+    {
+        path,
+        collection,
+        forceFilter,
+        pageSize = DEFAULT_PAGE_SIZE,
+        getLabelFromEntity,
+        getDescriptionFromEntity,
+        descriptionProperty
+    }: UseRelationSelectorProps<M>
+): RelationSelectorController {
+
+    const dataSource = useDataSource(collection);
+
+    const [items, setItems] = useState<RelationItem[]>([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState<Error | undefined>();
+    const [hasMore, setHasMore] = useState(true);
+    const [currentSearch, setCurrentSearch] = useState<string>("");
+    const [lastEntity, setLastEntity] = useState<Entity<M> | undefined>(undefined);
+
+    const unsubscribeRef = useRef<(() => void) | null>(null);
+    const searchTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+    // Function to convert entity to RelationItem
+    const entityToRelationItem = useCallback((entity: Entity<M>, relation?: EntityRelation): RelationItem => {
+        let label: string;
+        let description: string | undefined;
+
+        if (getLabelFromEntity) {
+            label = getLabelFromEntity(entity);
+        } else {
+            // Fallback: try common label properties
+            const commonLabelProps = ["name", "title", "label", "displayName"];
+            let foundProp: string | undefined;
+
+            if (entity.values) {
+                foundProp = commonLabelProps.find(prop => entity.values[prop] != null && entity.values[prop] !== "");
+            }
+
+            if (foundProp && entity.values[foundProp]) {
+                label = String(entity.values[foundProp]);
+            } else {
+                // Ultimate fallback: use entity ID
+                label = String(entity.id);
+            }
+        }
+
+        if (getDescriptionFromEntity) {
+            description = getDescriptionFromEntity(entity);
+        } else if (descriptionProperty && entity.values && entity.values[descriptionProperty]) {
+            description = String(entity.values[descriptionProperty]);
+        }
+
+        return {
+            id: entity.id,
+            label,
+            description,
+            data: entity,
+            relation: relation ? relation : new EntityRelation(entity.id, path)
+        };
+    }, [getLabelFromEntity, getDescriptionFromEntity, descriptionProperty]);
+
+    // Clean up any existing subscription
+    const cleanupSubscription = useCallback(() => {
+        if (unsubscribeRef.current) {
+            unsubscribeRef.current();
+            unsubscribeRef.current = null;
+        }
+    }, []);
+
+    // Perform data fetch
+    const fetchData = useCallback((searchString: string | undefined, loadMore: boolean = false) => {
+        cleanupSubscription();
+        setError(undefined);
+        setIsLoading(true);
+
+        const unsubscribe = dataSource.listenCollection!<M>({
+            path,
+            collection,
+            onUpdate: (entities) => {
+                const newItems = entities.map((e) => entityToRelationItem(e));
+
+                if (loadMore) {
+                    setItems(prev => [...prev, ...newItems]);
+                } else {
+                    setItems(newItems);
+                }
+
+                // Set hasMore based on whether we got a full page of results
+                setHasMore(entities.length === pageSize);
+                setLastEntity(entities[entities.length - 1]);
+                setIsLoading(false);
+            },
+            onError: (fetchError) => {
+                console.error("useRelationSelector: Error fetching data:", fetchError);
+                setError(fetchError);
+                setIsLoading(false);
+            },
+            searchString,
+            filter: forceFilter,
+            limit: pageSize,
+            startAfter: loadMore ? lastEntity : undefined,
+            order: "asc"
+        });
+
+        unsubscribeRef.current = unsubscribe;
+    }, [dataSource, path, collection, forceFilter, pageSize, entityToRelationItem, cleanupSubscription, lastEntity]);
+
+    // Search function with debouncing
+    const search = useCallback((searchString: string) => {
+        setCurrentSearch(searchString);
+
+        // Clear existing timeout
+        if (searchTimeoutRef.current) {
+            clearTimeout(searchTimeoutRef.current);
+        }
+
+        // Debounce search
+        searchTimeoutRef.current = setTimeout(() => {
+            setLastEntity(undefined);
+            fetchData(searchString, false);
+        }, searchString.trim() ? 300 : 0);
+    }, [fetchData]);
+
+    // Load more function
+    const loadMore = useCallback(() => {
+        if (!isLoading && hasMore && items.length > 0) {
+            fetchData(currentSearch, true);
+        }
+    }, [isLoading, hasMore, items.length, fetchData, currentSearch]);
+
+    // Load initial data
+    useEffect(() => {
+        fetchData(undefined, false);
+
+        return () => {
+            cleanupSubscription();
+            if (searchTimeoutRef.current) {
+                clearTimeout(searchTimeoutRef.current);
+            }
+        };
+    }, [path, collection.slug, forceFilter]);
+
+    return {
+        items,
+        isLoading,
+        error,
+        search,
+        loadMore,
+        hasMore,
+        entityToRelationItem,
+    };
+}

package/src/hooks/index.tsx

@@ -0,0 +1,51 @@
+export * from "./data/useDataSource";
+export * from "./data/useCollectionFetch";
+export * from "./data/useEntityFetch";
+export * from "./data/useRelationSelector";
+export * from "./data/save";
+export * from "./data/delete";
+
+
+export * from "./navigation/contexts";
+export * from "./navigation/useBuildCollectionRegistryController";
+export * from "./navigation/useBuildCMSUrlController";
+export * from "./navigation/useBuildNavigationStateController";
+export * from "./navigation/useResolvedCollections";
+export * from "./navigation/useResolvedViews";
+export * from "./navigation/useTopLevelNavigation";
+
+export * from "./useUnsavedChangesDialog";
+export * from "./useResolvedNavigationFrom";
+
+export * from "./useStorageSource";
+export * from "./useAuthController";
+export * from "./useDialogsController";
+export * from "./useSideDialogsController";
+export * from "./useAdminModeController";
+export * from "./useBuildAdminModeController";
+export * from "./useEffectiveRoleController";
+export * from "./useBuildEffectiveRoleController";
+export * from "./useSideEntityController";
+export * from "./useRebaseContext";
+export * from "./useSnackbarController";
+export * from "./useModeController";
+export * from "./useClipboard";
+export * from "./useLargeLayout";
+export * from "./useCollapsedGroups";
+
+export * from "./useInternalUserManagementController";
+
+export * from "./useEntitySelectionDialog";
+export * from "./useBrowserTitleAndIcon";
+export * from "./useCustomizationController";
+export * from "./useBuildNavigationController";
+
+export * from "./useBuildLocalConfigurationPersistence";
+export * from "./useBuildModeController";
+
+export * from "./useValidateAuthenticator";
+
+export * from "./useBackendStorageSource";
+export * from "./usePermissions";
+
+export * from "./ApiConfigContext";

package/src/hooks/navigation/contexts/CMSUrlContext.tsx

@@ -0,0 +1,24 @@
+import React, { createContext } from "react";
+import { NavigateOptions } from "react-router-dom";
+
+import { CMSUrlController } from "@rebasepro/types";
+
+export const CMSUrlContext = createContext<CMSUrlController>({
+    basePath: "/",
+    baseCollectionPath: "/c",
+    urlPathToDataPath: () => "",
+    homeUrl: "/",
+    isUrlCollectionPath: () => false,
+    buildUrlCollectionPath: () => "",
+    buildCMSUrlPath: () => "",
+    resolveDatabasePathsFrom: () => "",
+    navigate: () => { }
+});
+
+export function useCMSUrlController(): CMSUrlController {
+    const context = React.useContext(CMSUrlContext);
+    if (context === undefined) {
+        throw new Error("useCMSUrlController must be used within a CMSUrlContext.Provider");
+    }
+    return context;
+}

package/src/hooks/navigation/contexts/CollectionRegistryContext.tsx

@@ -0,0 +1,19 @@
+import React, { createContext } from "react";
+import { CollectionRegistryController, EntityCollection, EntityReference } from "@rebasepro/types";
+
+export const CollectionRegistryContext = createContext<CollectionRegistryController>({
+    getCollection: () => undefined,
+    getRawCollection: () => undefined,
+    getParentReferencesFromPath: () => [],
+    getParentCollectionIds: () => [],
+    convertIdsToPaths: () => [],
+    initialised: false
+});
+
+export function useCollectionRegistryController<EC extends EntityCollection = EntityCollection<any>>(): CollectionRegistryController<EC> {
+    const context = React.useContext(CollectionRegistryContext);
+    if (context === undefined) {
+        throw new Error("useCollectionRegistryController must be used within a CollectionRegistryContext.Provider");
+    }
+    return context as CollectionRegistryController<EC>;
+}

package/src/hooks/navigation/contexts/NavigationStateContext.tsx

@@ -0,0 +1,15 @@
+import React, { createContext } from "react";
+import { NavigationStateController, CMSView, NavigationResult, RebasePlugin } from "@rebasepro/types";
+
+export const NavigationStateContext = createContext<NavigationStateController>({
+    loading: true,
+    refreshNavigation: () => { }
+});
+
+export function useNavigationStateController(): NavigationStateController {
+    const context = React.useContext(NavigationStateContext);
+    if (context === undefined) {
+        throw new Error("useNavigationStateController must be used within a NavigationStateContext.Provider");
+    }
+    return context;
+}

package/src/hooks/navigation/contexts/index.ts

@@ -0,0 +1,14 @@
+export {
+    CollectionRegistryContext,
+    useCollectionRegistryController
+} from "./CollectionRegistryContext";
+
+export {
+    NavigationStateContext,
+    useNavigationStateController
+} from "./NavigationStateContext";
+
+export {
+    CMSUrlContext,
+    useCMSUrlController
+} from "./CMSUrlContext";

package/src/hooks/navigation/useBuildCMSUrlController.tsx

@@ -0,0 +1,68 @@
+import { useCallback, useMemo } from "react";
+import { removeInitialAndTrailingSlashes } from "@rebasepro/common";
+import { CMSUrlController, NavigateOptions, CollectionRegistryController } from "@rebasepro/types";
+import { useNavigate } from "react-router-dom";
+
+export function useBuildCMSUrlController(props: {
+    basePath: string,
+    baseCollectionPath: string,
+    collectionRegistryController: CollectionRegistryController
+}): CMSUrlController {
+
+    const { basePath, baseCollectionPath, collectionRegistryController } = props;
+    const navigate = useNavigate();
+
+    const homeUrl = basePath === "/" ? "/" : `/${removeInitialAndTrailingSlashes(basePath)}`;
+
+    const buildUrlCollectionPath = useCallback((path: string): string => {
+        const fullPath = basePath === "/" ? `${baseCollectionPath}/${path}` : `${basePath}${baseCollectionPath}/${path}`;
+        return fullPath.replace(/\/\//g, "/");
+    }, [basePath, baseCollectionPath]);
+
+    const buildCMSUrlPath = useCallback((path: string): string => {
+        const fullPath = basePath === "/" ? `/${path}` : `${basePath}/${path}`;
+        return fullPath.replace(/\/\//g, "/");
+    }, [basePath]);
+
+    const urlPathToDataPath = useCallback((cmsPath: string): string => {
+        let path = cmsPath;
+        if (basePath !== "/" && path.startsWith(basePath)) {
+            path = path.replace(basePath, "");
+        }
+        if (path.startsWith(baseCollectionPath)) {
+            path = path.replace(baseCollectionPath, "");
+        }
+        return removeInitialAndTrailingSlashes(path);
+    }, [basePath, baseCollectionPath]);
+
+    const isUrlCollectionPath = useCallback((urlPath: string): boolean => {
+        let path = urlPath;
+        if (basePath !== "/" && path.startsWith(basePath)) {
+            path = path.replace(basePath, "");
+        }
+        return path.startsWith(baseCollectionPath);
+    }, [basePath, baseCollectionPath]);
+
+    const resolveDatabasePathsFrom = useCallback((path: string): string => {
+        const pathSegments = removeInitialAndTrailingSlashes(path).split("/");
+        const resolvedPaths = collectionRegistryController.convertIdsToPaths(pathSegments);
+        return resolvedPaths.join("/");
+
+    }, [collectionRegistryController]);
+
+    const navigateTo = useCallback((to: string, options?: NavigateOptions) => {
+        navigate(to, options);
+    }, [navigate]);
+
+    return useMemo(() => ({
+        basePath,
+        baseCollectionPath,
+        urlPathToDataPath,
+        homeUrl,
+        isUrlCollectionPath,
+        buildUrlCollectionPath,
+        buildCMSUrlPath,
+        resolveDatabasePathsFrom,
+        navigate: navigateTo
+    }), [basePath, baseCollectionPath, urlPathToDataPath, homeUrl, isUrlCollectionPath, buildUrlCollectionPath, buildCMSUrlPath, resolveDatabasePathsFrom, navigateTo]);
+}

package/src/hooks/navigation/useBuildCollectionRegistryController.tsx

@@ -0,0 +1,150 @@
+import { useCallback, useRef, useState } from "react";
+import { CollectionRegistry, getParentReferencesFromPath as commonGetParentReferencesFromPath, removeInitialAndTrailingSlashes, mergeDeep, getSubcollections } from "@rebasepro/common";
+import { EntityCollection, EntityReference, UserConfigurationPersistence, CollectionRegistryController } from "@rebasepro/types";
+
+export function useBuildCollectionRegistryController(props: {
+    userConfigPersistence?: UserConfigurationPersistence
+}): CollectionRegistryController & {
+    collectionRegistryRef: React.MutableRefObject<CollectionRegistry>;
+} {
+    const { userConfigPersistence } = props;
+    const collectionRegistryRef = useRef<CollectionRegistry>(new CollectionRegistry());
+    const [initialised, setInitialised] = useState(false);
+
+    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 getParentReferencesFromPath = useCallback((path: string): EntityReference[] => {
+        const registry = collectionRegistryRef.current;
+        if (!registry) {
+            return [];
+        }
+        return commonGetParentReferencesFromPath({
+            path,
+            collections: registry.getCollections()
+        });
+    }, []);
+
+    const getParentCollectionIds = useCallback((path: string): string[] => {
+        const registry = collectionRegistryRef.current;
+        if (!registry) {
+            return [];
+        }
+        const strings = path.split("/");
+        const oddPathSegments = strings.filter((_: any, i: number) => i % 2 === 0);
+        oddPathSegments.pop();
+
+        const result: string[][] = [];
+
+        for (let i = 1; i <= oddPathSegments.length; i++) {
+            result.push(oddPathSegments.slice(0, i));
+        }
+
+        const getCollectionFromPaths = (pathSegments: string[]): EntityCollection | undefined => {
+            if (!pathSegments?.length) return undefined;
+            const testPath = pathSegments.reduce((acc, segment, idx) => {
+                if (idx === 0) return segment;
+                return `${acc}/fake_id/${segment}`;
+            }, "");
+            try {
+                return registry.resolvePathToCollections(testPath).finalCollection;
+            } catch (e) {
+                return undefined;
+            }
+        };
+
+        return result.map(r => getCollectionFromPaths(r)?.slug).filter(Boolean) as string[];
+    }, []);
+
+    const convertIdsToPaths = useCallback((ids: string[]): string[] => {
+        const registry = collectionRegistryRef.current;
+        if (!registry) return [];
+        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.slug ?? collection.dbPath); // Fallback to dbPath if slug doesn't exist? Wait, slug is correct.
+            currentCollections = getSubcollections(collection) ?? [];
+        }
+        return paths;
+    }, []);
+
+    const collections = collectionRegistryRef.current.getCollections();
+
+    // Determine initialised automatically based on whether collections exist,
+    // though the NavigationStateController also plays a role in overall init
+    if (!initialised && collections.length > 0) {
+        setInitialised(true);
+    }
+
+    return {
+        collections,
+        initialised,
+        getCollection,
+        getRawCollection,
+        getParentReferencesFromPath,
+        getParentCollectionIds,
+        convertIdsToPaths,
+        collectionRegistryRef
+    };
+}

package/src/hooks/navigation/useBuildNavigationStateController.tsx

@@ -0,0 +1,135 @@
+import { useCallback } from "react";
+
+import {
+    CMSView,
+    EntityCollection,
+    NavigationResult,
+    RebasePlugin,
+    AuthController,
+    EntityCollectionsBuilder,
+    CMSViewsBuilder,
+    NavigationStateController,
+    DataSource,
+    CollectionRegistryController,
+    CMSUrlController,
+    NavigationGroupMapping,
+    User
+} from "@rebasepro/types";
+import { CollectionRegistry } from "@rebasepro/common";
+
+import { EffectiveRoleController, UserManagementDelegate } from "@rebasepro/types";
+
+import { useResolvedCollections } from "./useResolvedCollections";
+import { useResolvedViews } from "./useResolvedViews";
+import { useTopLevelNavigation } from "./useTopLevelNavigation";
+
+export type BuildNavigationStateProps<EC extends EntityCollection, USER extends User> = {
+    authController: AuthController<USER>;
+    collections?: EC[] | EntityCollectionsBuilder<EC>;
+    views?: CMSView[] | CMSViewsBuilder;
+    adminViews?: CMSView[] | CMSViewsBuilder;
+    dataSource: DataSource;
+    plugins?: RebasePlugin[];
+    navigationGroupMappings?: NavigationGroupMapping[];
+    disabled?: boolean;
+    viewsOrder?: string[];
+    collectionRegistryController: CollectionRegistryController<EC> & { collectionRegistryRef: React.MutableRefObject<CollectionRegistry> };
+    cmsUrlController: CMSUrlController;
+    adminMode?: "content" | "studio" | "settings";
+    effectiveRoleController?: EffectiveRoleController;
+    userManagement?: UserManagementDelegate<USER>;
+};
+
+/**
+ * Main hook that resolves collections, views, and admin views into a
+ * NavigationStateController. This is a thin composition of three focused hooks:
+ *
+ * - useResolvedCollections: resolves collection props and registers with CollectionRegistry
+ * - useResolvedViews: resolves view/admin view props and injects Users/Roles views
+ * - useTopLevelNavigation: computes the NavigationResult from resolved data
+ *
+ * The NavigationStateController type is preserved as a public API.
+ */
+export function useBuildNavigationStateController<EC extends EntityCollection, USER extends User>(
+    props: BuildNavigationStateProps<EC, USER>
+): NavigationStateController {
+
+    const {
+        authController,
+        collections: collectionsProp,
+        views: viewsProp,
+        adminViews: adminViewsProp,
+        viewsOrder,
+        plugins,
+        dataSource,
+        disabled,
+        navigationGroupMappings,
+        collectionRegistryController,
+        cmsUrlController,
+        adminMode = "content",
+        effectiveRoleController,
+        userManagement
+    } = props;
+
+    // Step 1: Resolve collections
+    const {
+        collections,
+        loading: collectionsLoading,
+        error: collectionsError,
+        refresh: refreshCollections
+    } = useResolvedCollections({
+        authController,
+        collections: collectionsProp,
+        dataSource,
+        plugins,
+        disabled,
+        collectionRegistryController
+    });
+
+    // Step 2: Resolve views and admin views
+    const {
+        views,
+        adminViews,
+        loading: viewsLoading,
+        error: viewsError,
+        refresh: refreshViews
+    } = useResolvedViews({
+        authController,
+        views: viewsProp,
+        adminViews: adminViewsProp,
+        dataSource,
+        plugins,
+        adminMode,
+        effectiveRoleController,
+        userManagement
+    });
+
+    // Step 3: Compute top-level navigation (pure derived state)
+    const { topLevelNavigation } = useTopLevelNavigation({
+        collections,
+        views,
+        adminViews,
+        plugins,
+        navigationGroupMappings,
+        viewsOrder,
+        cmsUrlController,
+        adminMode,
+        collectionRegistryController
+    });
+
+    // Expose a combined refresh function
+    const refreshNavigation = useCallback(() => {
+        refreshCollections();
+        refreshViews();
+    }, [refreshCollections, refreshViews]);
+
+    return {
+        views,
+        adminViews,
+        topLevelNavigation,
+        loading: collectionsLoading || viewsLoading,
+        navigationLoadingError: collectionsError ?? viewsError,
+        refreshNavigation,
+        plugins
+    };
+}