@rebasepro/core 0.0.1-canary.0

package/src/hooks/useLargeLayout.tsx

@@ -0,0 +1,65 @@
+import { useEffect, useState } from "react";
+
+type LayoutListener = (isLargeLayout: boolean) => void;
+
+const breakpoints = {
+    xs: 0,
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    "2xl": 1536,
+    "3xl": 1920
+}
+
+// Global state and listeners array
+let isLargeLayoutGlobal = checkLargeLayout("lg"); // Default value
+const listeners: LayoutListener[] = [];
+
+// Utility to notify all listeners
+const notifyListeners = () => {
+    listeners.forEach(listener => listener(isLargeLayoutGlobal));
+};
+
+// Listen to resize events once, at a global level
+if (typeof window !== "undefined")
+    window.addEventListener("resize", () => {
+        const newIsLargeLayout = checkLargeLayout("lg");
+        if (newIsLargeLayout !== isLargeLayoutGlobal) {
+            isLargeLayoutGlobal = newIsLargeLayout;
+            notifyListeners();
+        }
+    });
+
+export const useLargeLayout = () => {
+    const [isLargeLayout, setIsLargeLayout] = useState(isLargeLayoutGlobal);
+
+    useEffect(() => {
+        // Listener function to update component state
+        const listener: LayoutListener = (newIsLargeLayout) => {
+            setIsLargeLayout(newIsLargeLayout);
+        };
+
+        // Register listener
+        listeners.push(listener);
+
+        // Initial state
+        setIsLargeLayout(isLargeLayoutGlobal);
+
+        // Clean up by removing the listener
+        return () => {
+            const index = listeners.indexOf(listener);
+            if (index > -1) {
+                listeners.splice(index, 1);
+            }
+        };
+    }, []);
+
+    return isLargeLayout;
+};
+
+function checkLargeLayout(breakpoint: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" = "lg"): boolean {
+    if (typeof window === "undefined")
+        return false;
+    return window.matchMedia(`(min-width: ${breakpoints[breakpoint] + 1}px)`).matches;
+}

package/src/hooks/useModeController.tsx

@@ -0,0 +1,23 @@
+import { ModeControllerContext } from "../contexts/ModeController";
+import { useContext } from "react";
+
+/**
+ * Use this controller to change color mode
+ * @group Hooks and utilities
+ */
+export interface ModeController {
+    mode: "light" | "dark";
+    setMode: (mode: "light" | "dark" | "system") => void;
+}
+
+/**
+ * Hook to retrieve the current mode ("light" | "dark"), and `setMode`
+ * or `toggle` functions to change it.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see ModeController
+ * @group Hooks and utilities
+ */
+export const useModeController = () => useContext(ModeControllerContext);

package/src/hooks/usePermissions.ts

@@ -0,0 +1,43 @@
+import { useAuthController } from "./useAuthController";
+import { EntityCollection, Entity } from "@rebasepro/types";
+import { canCreateEntity, canEditEntity, canDeleteEntity, canReadCollection } from "@rebasepro/common";
+import { useCallback } from "react";
+
+/**
+ * Hook to evaluate roles and permissions for the current user.
+ * It abstracts away the need to pass `authController` to permission evaluation functions.
+ */
+export function usePermissions() {
+    const authController = useAuthController();
+
+    const canCreate = useCallback(
+        (collection: EntityCollection<any>, path: string) =>
+            canCreateEntity(collection, authController, path, null),
+        [authController]
+    );
+
+    const canEdit = useCallback(
+        (collection: EntityCollection<any>, path: string, entity: Entity<any> | null) =>
+            canEditEntity(collection, authController, path, entity),
+        [authController]
+    );
+
+    const canDelete = useCallback(
+        (collection: EntityCollection<any>, path: string, entity: Entity<any> | null) =>
+            canDeleteEntity(collection, authController, path, entity),
+        [authController]
+    );
+
+    const canRead = useCallback(
+        (collection: EntityCollection<any>) =>
+            canReadCollection(collection, authController),
+        [authController]
+    );
+
+    return {
+        canCreate,
+        canEdit,
+        canDelete,
+        canRead
+    };
+}

package/src/hooks/useRebaseContext.tsx

@@ -0,0 +1,86 @@
+import { AuthController, RebaseContext, User } from "@rebasepro/types";
+import { useAuthController } from "./useAuthController";
+import { useSideDialogsController } from "./useSideDialogsController";
+import { useCollectionRegistryController, useNavigationStateController, useCMSUrlController } from "./navigation/contexts";
+import { useSideEntityController } from "./useSideEntityController";
+import { useDataSource } from "./data/useDataSource";
+import { useStorageSource } from "./useStorageSource";
+import { useSnackbarController } from "./useSnackbarController";
+import { useUserConfigurationPersistence } from "./useUserConfigurationPersistence";
+import { useDialogsController } from "./useDialogsController";
+import { useCustomizationController } from "./useCustomizationController";
+import { useAnalyticsController } from "./useAnalyticsController";
+import { useEffectiveRoleController } from "./useEffectiveRoleController";
+import React, { useEffect } from "react";
+import { useInternalUserManagementController } from "./useInternalUserManagementController";
+
+/**
+ * Hook to retrieve the {@link RebaseContext}.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase` component.
+ *
+ * @see RebaseContext
+ * @group Hooks and utilities
+ */
+export const useRebaseContext = <USER extends User = User, AuthControllerType extends AuthController<USER> = AuthController<USER>>(): RebaseContext<USER, AuthControllerType> => {
+
+    const authController = useAuthController<USER, AuthControllerType>();
+    const sideDialogsController = useSideDialogsController();
+    const sideEntityController = useSideEntityController();
+    const collectionRegistry = useCollectionRegistryController();
+    const navigationState = useNavigationStateController();
+    const cmsUrlController = useCMSUrlController();
+
+    const navigation = React.useMemo(() => ({
+        ...collectionRegistry,
+        ...navigationState,
+        ...cmsUrlController,
+        getCollectionBySlug: collectionRegistry.getCollection
+    }), [collectionRegistry, navigationState, cmsUrlController]);
+    const dataSource = useDataSource();
+    const storageSource = useStorageSource();
+    const snackbarController = useSnackbarController();
+    const userConfigPersistence = useUserConfigurationPersistence();
+    const dialogsController = useDialogsController();
+    const customizationController = useCustomizationController();
+    const analyticsController = useAnalyticsController();
+    const effectiveRoleController = useEffectiveRoleController();
+    const userManagement = useInternalUserManagementController<USER>();
+
+    const rebaseContextRef = React.useRef<RebaseContext<USER, AuthControllerType>>({
+        authController,
+        sideDialogsController,
+        sideEntityController,
+        navigation: navigation as any,
+        dataSource,
+        storageSource,
+        snackbarController,
+        userConfigPersistence,
+        dialogsController,
+        customizationController,
+        analyticsController,
+        userManagement,
+        effectiveRoleController
+    });
+
+    React.useEffect(() => {
+        rebaseContextRef.current = {
+            authController,
+            sideDialogsController,
+            sideEntityController,
+            navigation: navigation as any,
+            dataSource,
+            storageSource,
+            snackbarController,
+            userConfigPersistence,
+            dialogsController,
+            customizationController,
+            analyticsController,
+            userManagement,
+            effectiveRoleController
+        };
+    }, [authController, dialogsController, navigation, sideDialogsController, effectiveRoleController]);
+
+    return rebaseContextRef.current;
+}

package/src/hooks/useResolvedNavigationFrom.tsx

@@ -0,0 +1,158 @@
+import { Entity, EntityCollection, EntityCustomView, RebaseContext, User } from "@rebasepro/types";
+import { useEffect, useState } from "react";
+import { useRebaseContext } from "./useRebaseContext";
+import { getNavigationEntriesFromPath } from "@rebasepro/common";
+
+/**
+ * @see resolveNavigationFrom
+ * @group Hooks and utilities
+ */
+export type ResolvedNavigationEntry<M extends Record<string, any>> =
+    | ResolvedNavigationEntity<M>
+    | ResolvedNavigationCollection<M>
+    | ResolvedNavigationEntityCustom<M>;
+
+/**
+ * @see resolveNavigationFrom
+ * @group Hooks and utilities
+ */
+export interface ResolvedNavigationEntity<M extends Record<string, any>> {
+    type: "entity";
+    entity: Entity<M>;
+    entityId: string | number;
+    path: string;
+    parentCollection: EntityCollection<M>;
+}
+
+/**
+ * @see resolveNavigationFrom
+ * @group Hooks and utilities
+ */
+export interface ResolvedNavigationCollection<M extends Record<string, any>> {
+    type: "collection";
+    path: string;
+    collection: EntityCollection<M>;
+}
+
+/**
+ * @see resolveNavigationFrom
+ * @group Hooks and utilities
+ */
+interface ResolvedNavigationEntityCustom<M extends Record<string, any>> {
+    type: "custom_view";
+    path: string;
+    view: EntityCustomView<M>;
+}
+
+/**
+ * Use this function to retrieve an array of navigation entries (resolved
+ * collection, entity or entity custom_view) for the given path. You need to pass the app context
+ * that you receive in different callbacks, such as the save hooks.
+ *
+ * It will take into account the `navigation` provided at the `Rebase` level.
+ *
+ * @param path
+ * @param context
+ * @group Hooks and utilities
+ */
+export function resolveNavigationFrom<M extends Record<string, any>, USER extends User>({
+    path,
+    context
+}: {
+    path: string,
+    context: RebaseContext<USER>
+}): Promise<ResolvedNavigationEntry<M>[]> {
+
+    const dataSource = context.dataSource;
+    const navigation = context.navigation;
+
+    if (!navigation) {
+        throw Error("Calling resolveNavigationFrom, but main navigation has not yet been initialised");
+    }
+
+    const navigationEntries = getNavigationEntriesFromPath({
+        path,
+        collections: navigation.collections ?? []
+    });
+
+    const resultPromises: Promise<ResolvedNavigationEntry<any>>[] = navigationEntries
+        .map((entry) => {
+            if (entry.type === "collection") {
+                return Promise.resolve(entry);
+            } else if (entry.type === "entity") {
+                const collection = navigation.getCollection(entry.slug);
+                if (!collection) {
+                    throw Error(`No collection defined in the navigation for the entity with path ${entry.slug}`);
+                }
+                return dataSource.fetchEntity({
+                    path: entry.slug,
+                    entityId: entry.entityId,
+                    collection
+                })
+                    .then((entity) => {
+                        if (!entity) return undefined;
+                        return { ...entry, entity };
+                    });
+            } else if (entry.type === "custom_view") {
+                return Promise.resolve(entry);
+            } else {
+                throw Error("Unmapped element in useEntitiesFromPath");
+            }
+        })
+        .filter(v => Boolean(v)) as Promise<ResolvedNavigationEntry<any>>[];
+
+    return Promise.all(resultPromises);
+}
+
+/**
+ * @group Hooks and utilities
+ */
+export interface NavigationFromProps {
+    path: string;
+}
+
+/**
+ * @group Hooks and utilities
+ */
+export interface NavigationFrom<M extends Record<string, any>> {
+    data?: ResolvedNavigationEntry<M>[]
+    dataLoading: boolean,
+    dataLoadingError?: Error
+}
+
+/**
+ * Use this hook to retrieve an array of navigation entries (resolved
+ * collection or entity) for the given path. You can use this hook
+ * in any React component that lives under `Rebase`
+ * @group Hooks and utilities
+ */
+export function useResolvedNavigationFrom<M extends Record<string, any>, USER extends User>(
+    {
+        path
+    }: NavigationFromProps): NavigationFrom<M> {
+
+    const context: RebaseContext<USER> = useRebaseContext();
+
+    const [data, setData] = useState<ResolvedNavigationEntry<M>[] | undefined>();
+    const [dataLoading, setDataLoading] = useState<boolean>(false);
+    const [dataLoadingError, setDataLoadingError] = useState<Error | undefined>();
+
+    useEffect(() => {
+        const navigation = context.navigation;
+        if (navigation) {
+            setDataLoading(true);
+            setDataLoadingError(undefined);
+            resolveNavigationFrom<M, USER>({ path, context })
+                .then(setData)
+                .catch((e) => setDataLoadingError(e))
+                .finally(() => setDataLoading(false));
+        }
+
+    }, [path, context]);
+
+    if (!context.navigation) {
+        return { dataLoading: true };
+    }
+
+    return { data, dataLoading, dataLoadingError };
+}

package/src/hooks/useSideDialogsController.tsx

@@ -0,0 +1,21 @@
+import { SideDialogsController } from "@rebasepro/types";
+import { SideDialogsControllerContext } from "../contexts/SideDialogsControllerContext";
+import { useContext } from "react";
+
+/**
+ * Hook to retrieve the side dialogs' controller.
+ *
+ * This hook allows you to open and close side dialogs. This is the mechanism
+ * used when open a side entity dialog, or when selecting a reference.
+ *
+ * If you want to open a side entity dialog, you can use the {@link useSideEntityController}
+ * hook.
+ *
+ * If you want to select a reference, you can use the {@link useReferenceDialog}
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @group Hooks and utilities
+ */
+export const useSideDialogsController = (): SideDialogsController => useContext(SideDialogsControllerContext);

package/src/hooks/useSideEntityController.tsx

@@ -0,0 +1,15 @@
+import { SideEntityController } from "@rebasepro/types";
+import { useContext } from "react";
+import { SideEntityControllerContext } from "../contexts/SideEntityControllerContext";
+
+/**
+ * Use this hook to retrieve an entity controller that allows you to open
+ * a side dialog to edit an entity.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see SideEntityController
+ * @group Hooks and utilities
+ */
+export const useSideEntityController = (): SideEntityController => useContext(SideEntityControllerContext);

package/src/hooks/useSnackbarController.tsx

@@ -0,0 +1,52 @@
+import React, { useCallback, useMemo } from "react";
+import { useSnackbar } from "notistack";
+import { SnackbarMessageType } from "@rebasepro/types";
+
+
+/**
+ * Hook to retrieve the SnackbarContext.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see SnackbarController
+ * @group Hooks and utilities
+ */
+export const useSnackbarController = () => {
+
+    const {
+        enqueueSnackbar,
+        closeSnackbar
+    } = useSnackbar();
+
+    const open = useCallback((props: {
+        type: SnackbarMessageType;
+        title?: string;
+        message: React.ReactNode;
+        autoHideDuration?: number;
+    }) => {
+        const {
+            type,
+            message,
+            autoHideDuration
+        } = props;
+        enqueueSnackbar({
+            message: props.title ? <div className={"flex flex-col"}>
+                <strong>{props.title}</strong>
+                {message}
+            </div> : message,
+            variant: type,
+            autoHideDuration
+        })
+    }, []);
+
+    const close = useCallback(() => {
+        closeSnackbar();
+    }, []);
+
+    return useMemo(() => ({
+        open,
+        close
+    }), [open, close]);
+
+};

package/src/hooks/useStorageSource.tsx

@@ -0,0 +1,14 @@
+import { EntityCollection, StorageSource } from "@rebasepro/types";
+import { StorageSourceContext } from "../contexts/StorageSourceContext";
+import { useContext } from "react";
+
+/**
+ * Use this hook to get the storage source being used
+ * @group Hooks and utilities
+ */
+export const useStorageSource = (collection?: EntityCollection): StorageSource => {
+    const defaultStorageSource = useContext(StorageSourceContext);
+    if (collection?.overrides?.storageSource)
+        return collection.overrides.storageSource;
+    return defaultStorageSource;
+};

package/src/hooks/useUnsavedChangesDialog.tsx

@@ -0,0 +1,62 @@
+import { useCallback, useEffect, useState } from "react";
+import { useBlocker } from "react-router-dom";
+import { UnsavedChangesDialogProps } from "../components/UnsavedChangesDialog";
+
+/**
+ * A single, unified hook to prevent navigation when there are unsaved changes.
+ * 
+ * It automatically handles:
+ * 1. Internal React Router navigation using `useBlocker`.
+ * 2. External browser navigation (page refresh, tab close) using `beforeunload`.
+ */
+export function useUnsavedChangesDialog(
+    when: boolean,
+    onOk: () => void
+): {
+    dialogProps: UnsavedChangesDialogProps;
+    triggerDialog: () => void;
+} {
+    const [manualDialogOpen, setManualDialogOpen] = useState(false);
+
+    const blocker = useBlocker(
+        ({ currentLocation, nextLocation }) =>
+            when && currentLocation.pathname !== nextLocation.pathname
+    );
+
+    useEffect(() => {
+        if (!when) return;
+        
+        const handleBeforeUnload = (e: BeforeUnloadEvent) => {
+            e.preventDefault();
+            e.returnValue = ""; 
+        };
+        
+        window.addEventListener("beforeunload", handleBeforeUnload);
+        return () => window.removeEventListener("beforeunload", handleBeforeUnload);
+    }, [when]);
+
+    const handleOk = useCallback(() => {
+        onOk();
+        if (blocker.state === "blocked") {
+            blocker.proceed();
+        }
+        setManualDialogOpen(false);
+    }, [blocker, onOk]);
+
+    const handleCancel = useCallback(() => {
+        if (blocker.state === "blocked") {
+            blocker.reset();
+        }
+        setManualDialogOpen(false);
+    }, [blocker]);
+
+    return {
+        dialogProps: {
+            open: manualDialogOpen || blocker.state === "blocked",
+            handleOk,
+            handleCancel,
+            body: "There are unsaved changes in this collection"
+        },
+        triggerDialog: () => setManualDialogOpen(true)
+    };
+}

package/src/hooks/useUserConfigurationPersistence.tsx

@@ -0,0 +1,11 @@
+import { UserConfigurationPersistence } from "@rebasepro/types";
+import { useContext } from "react";
+import { UserConfigurationPersistenceContext } from "../contexts/UserConfigurationPersistenceContext";
+
+/**
+ * Use this controller to access the configuration that is stored externally,
+ * and not defined in code
+ *
+ * @group Hooks and utilities
+ */
+export const useUserConfigurationPersistence = (): UserConfigurationPersistence | undefined => useContext(UserConfigurationPersistenceContext);

package/src/hooks/useValidateAuthenticator.tsx

@@ -0,0 +1,115 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { deepEqual as equal } from "fast-equals";
+
+import { AuthController, Authenticator, DataSource, StorageSource, User } from "../index";
+
+/**
+ * This hook is used internally for validating an authenticator.
+ *
+ * @param authController
+ * @param authentication
+ * @param storageSource
+ * @param dataSource
+ */
+export function useValidateAuthenticator<USER extends User = any>
+({
+     disabled,
+     authController,
+     authenticator,
+     storageSource,
+     dataSource
+ }:
+ {
+     disabled?: boolean,
+     authController: AuthController<USER>,
+     authenticator?: boolean | Authenticator<USER>,
+     dataSource: DataSource;
+     storageSource: StorageSource;
+ }): {
+    canAccessMainView: boolean,
+    authLoading: boolean,
+    notAllowedError: any,
+    authVerified: boolean,
+} {
+
+    const authenticationEnabled = Boolean(authenticator);
+
+    const [authLoading, setAuthLoading] = useState<boolean>(authenticationEnabled);
+    const [notAllowedError, setNotAllowedError] = useState<any>(false);
+    const [authVerified, setAuthVerified] = useState<boolean>(!authenticationEnabled || Boolean(authController.loginSkipped));
+
+    const canAccessMainView = (authVerified) &&
+        (!authenticationEnabled || Boolean(authController.user) || Boolean(authController.loginSkipped)) &&
+        !notAllowedError;
+
+    useEffect(() => {
+        if (authController.loginSkipped)
+            setAuthVerified(true);
+    }, [authController.loginSkipped]);
+
+    /**
+     * We use this ref to check the authentication only if the user has
+     * changed.
+     */
+    const checkedUserRef = useRef<User | undefined>(undefined);
+
+    const checkAuthentication = useCallback(async () => {
+
+        if (disabled) {
+            return;
+        }
+
+        if (authController.initialLoading) {
+            return;
+        }
+
+        if (!authController.user && !authController.loginSkipped) {
+            checkedUserRef.current = undefined;
+            setAuthLoading(false);
+            setAuthVerified(false);
+            return;
+        }
+
+        const delegateUser = authController.user;
+
+        if (authenticator instanceof Function && delegateUser && !equal(checkedUserRef.current?.uid, delegateUser.uid)) {
+            setAuthLoading(true);
+            try {
+                const allowed = await authenticator({
+                    user: delegateUser,
+                    authController,
+                    dataSource,
+                    storageSource
+                });
+                if (!allowed) {
+                    authController.signOut();
+                    setNotAllowedError(true);
+                }
+            } catch (e) {
+                setNotAllowedError(e);
+                authController.signOut();
+            }
+            setAuthLoading(false);
+            setAuthVerified(true);
+            checkedUserRef.current = delegateUser;
+        } else {
+            setAuthLoading(false);
+        }
+
+        if (!authController.initialLoading && !delegateUser) {
+            setAuthVerified(true);
+        }
+
+    }, [disabled, authController, authenticator, dataSource, storageSource]);
+
+    useEffect(() => {
+        checkAuthentication();
+    }, [checkAuthentication]);
+
+    return {
+        canAccessMainView,
+        authLoading: authenticationEnabled && authLoading,
+        notAllowedError,
+        authVerified
+    }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./core";
+export * from "./app";
+export * from "@rebasepro/types";
+export * from "@rebasepro/common";
+// Note: EntityFormProps is exported from both @rebasepro/types and ./form
+// The local version from ./form has additional properties and takes precedence
+export * from "./form";
+export * from "./preview";
+export * from "./hooks";
+export * from "./components/admin";
+export * from "./components";
+export * from "./util";
+export * from "./contexts";
+export * from "./routes";
+export { useUnsavedChangesDialog } from "./hooks/useUnsavedChangesDialog";
+export type { UnsavedChangesDialogProps } from "./components/UnsavedChangesDialog";
+export { UnsavedChangesDialog } from "./components/UnsavedChangesDialog";