@rebasepro/app 0.0.1-canary.4829d6e

package/src/hooks/useAuthSubscription.ts

@@ -0,0 +1,87 @@
+import { useState, useEffect, useMemo, useCallback } from "react";
+import { AuthClient, AuthController, User } from "@rebasepro/types";
+
+export function useAuthSubscription(authClient?: AuthClient): AuthController {
+
+    // Check initial state
+    const currentSession = authClient?.getSession();
+    const [user, setUser] = useState<User | null>(currentSession?.user ?? null);
+
+    const [initialLoading, setInitialLoading] = useState(!currentSession);
+    const [authLoading, setAuthLoading] = useState(false);
+    const [authError, setAuthError] = useState<Error>();
+    const [loginSkipped, setLoginSkipped] = useState(false);
+    const [extra, setExtra] = useState<any>();
+
+    useEffect(() => {
+        if (!authClient) return;
+        // If we don't have a session initially, try to get user which restores session if a persistent token exists
+        if (!currentSession) {
+            setInitialLoading(true);
+            authClient.getUser()
+                .then(user => {
+                    if (user) {
+                        setUser(user);
+                    }
+                })
+                .catch(e => {
+                    // Ignore, user just isn't logged in
+                })
+                .finally(() => {
+                    setInitialLoading(false);
+                });
+        }
+    }, [authClient, currentSession]);
+
+    useEffect(() => {
+        if (!authClient) return;
+        const unsubscribe = authClient.onAuthStateChange((event, session) => {
+            if (event === "SIGNED_IN" || event === "USER_UPDATED" || event === "TOKEN_REFRESHED") {
+                setUser(session?.user ?? null);
+            } else if (event === "SIGNED_OUT") {
+                setUser(null);
+            }
+        });
+        return unsubscribe;
+    }, [authClient]);
+
+    const signOut = useCallback(async () => {
+        if (!authClient) return;
+        setAuthLoading(true);
+        try {
+            await authClient.signOut();
+        } finally {
+            setAuthLoading(false);
+        }
+    }, [authClient]);
+
+    const getAuthToken = useCallback(async () => {
+        if (!authClient) return "";
+        const session = authClient.getSession();
+        if (!session) return "";
+        if (session.expiresAt < Date.now()) {
+            try {
+                const refreshed = await authClient.refreshSession();
+                return refreshed.accessToken;
+            } catch (e) {
+                return "";
+            }
+        }
+        return session.accessToken;
+    }, [authClient]);
+
+    return useMemo(() => ({
+        user,
+        initialLoading: authClient ? initialLoading : false,
+        authLoading,
+        signOut,
+        authError,
+        getAuthToken,
+        loginSkipped,
+        extra,
+        setExtra
+    } as AuthController), [
+        user, initialLoading, authLoading, signOut, authError,
+        getAuthToken, loginSkipped, extra, setExtra, authClient
+    ]);
+}

package/src/hooks/useBackendStorageSource.ts

@@ -0,0 +1,288 @@
+/**
+ * React hook for using backend storage API as a StorageSource
+ */
+
+import { useMemo, useCallback } from "react";
+import {
+    StorageSource,
+    UploadFileProps,
+    UploadFileResult,
+    DownloadConfig,
+    StorageListResult
+} from "@rebasepro/types";
+
+export interface BackendStorageSourceProps {
+    /**
+     * Backend API URL (e.g., 'http://localhost:3001')
+     */
+    apiUrl: string;
+    /**
+     * Function to get the current auth token
+     */
+    getAuthToken: () => Promise<string>;
+}
+
+/**
+ * Hook to create a StorageSource that uses the backend storage REST API.
+ * Use this for self-hosted Rebase with local or S3 storage.
+ *
+ * @example
+ * ```tsx
+ * const storageSource = useBackendStorageSource({
+ *     apiUrl: 'http://localhost:3001',
+ *     getAuthToken: authController.getAuthToken
+ * });
+ *
+ * // Then pass to Rebase:
+ * <Rebase storageSource={storageSource} ... />
+ * ```
+ */
+export function useBackendStorageSource({
+    apiUrl,
+    getAuthToken
+}: BackendStorageSourceProps): StorageSource {
+
+    const storageBasePath = `${apiUrl}/api/storage`;
+
+    // Cache for download URLs to avoid redundant API calls
+    const urlsCache = useMemo(() => new Map<string, DownloadConfig>(), []);
+
+    /**
+     * Make an authenticated request to the storage API
+     */
+    const fetchWithAuth = useCallback(async (
+        url: string,
+        options: RequestInit = {}
+    ): Promise<Response> => {
+        const token = await getAuthToken();
+        return fetch(url, {
+            ...options,
+            headers: {
+                ...options.headers,
+                "Authorization": `Bearer ${token}`
+            }
+        });
+    }, [getAuthToken]);
+
+    /**
+     * Upload a file to storage
+     */
+    const putObject = useCallback(async ({
+        file,
+        key,
+        metadata,
+        bucket
+    }: UploadFileProps): Promise<UploadFileResult> => {
+        const formData = new FormData();
+        formData.append("file", file);
+
+        if (key) {
+            formData.append("key", key);
+        }
+        if (bucket) {
+            formData.append("bucket", bucket);
+        }
+
+        // Add metadata fields with prefix
+        if (metadata) {
+            for (const [key, value] of Object.entries(metadata)) {
+                if (value !== undefined && value !== null) {
+                    formData.append(
+                        `metadata_${key}`,
+                        typeof value === "string" ? value : JSON.stringify(value)
+                    );
+                }
+            }
+        }
+
+        const response = await fetchWithAuth(`${storageBasePath}/upload`, {
+            method: "POST",
+            body: formData
+        });
+
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: "Upload failed" }));
+            throw new Error(error.error || "Upload failed");
+        }
+
+        const result = await response.json();
+        return result.data;
+    }, [fetchWithAuth, storageBasePath]);
+
+    /**
+     * Get download URL for a file
+     */
+    const getSignedUrl = useCallback(async (
+        keyOrUrl: string,
+        bucket?: string
+    ): Promise<DownloadConfig> => {
+        // Check cache first
+        const cacheKey = bucket ? `${bucket}/${keyOrUrl}` : keyOrUrl;
+        const cached = urlsCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+
+        // Build the file path for the API
+        let filePath = keyOrUrl;
+
+        // Handle local:// and s3:// URLs
+        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://"))) {
+            const withoutProtocol = filePath.substring(filePath.indexOf("://") + 3);
+            filePath = withoutProtocol;
+        }
+
+        // If bucket is provided separately, prepend it
+        if (bucket && filePath && !filePath.startsWith(bucket)) {
+            filePath = `${bucket}/${filePath}`;
+        }
+
+        if (!filePath || filePath.trim() === "" || filePath === "/") {
+            return { url: null,
+fileNotFound: true };
+        }
+
+        const response = await fetchWithAuth(`${storageBasePath}/metadata/${filePath}`);
+
+        if (response.status === 404) {
+            return {
+                url: null,
+                fileNotFound: true
+            };
+        }
+
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: "Failed to get download URL" }));
+            throw new Error(error.error || "Failed to get download URL");
+        }
+
+        const result = await response.json();
+
+        const token = await getAuthToken();
+        const tokenQuery = token ? `?token=${token}` : "";
+
+        // The URL should point to the storage file endpoint
+        const downloadConfig: DownloadConfig = {
+            url: `${storageBasePath}/file/${filePath}${tokenQuery}`,
+            metadata: result.data
+        };
+
+        // Cache the result
+        urlsCache.set(cacheKey, downloadConfig);
+
+        return downloadConfig;
+    }, [fetchWithAuth, storageBasePath, urlsCache]);
+
+    /**
+     * Get file as a File object
+     */
+    const getObject = useCallback(async (
+        key: string,
+        bucket?: string
+    ): Promise<File | null> => {
+        let filePath = key;
+
+        // Handle protocol URLs
+        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://"))) {
+            const withoutProtocol = filePath.substring(filePath.indexOf("://") + 3);
+            filePath = withoutProtocol;
+        }
+
+        if (bucket && filePath && !filePath.startsWith(bucket)) {
+            filePath = `${bucket}/${filePath}`;
+        }
+
+        if (!filePath || filePath.trim() === "" || filePath === "/") {
+            return null;
+        }
+
+        const response = await fetchWithAuth(`${storageBasePath}/file/${filePath}`);
+
+        if (response.status === 404) {
+            return null;
+        }
+
+        if (!response.ok) {
+            throw new Error("Failed to get file");
+        }
+
+        const blob = await response.blob();
+        const fileName = filePath.split("/").pop() || "file";
+        return new File([blob], fileName, { type: blob.type });
+    }, [fetchWithAuth, storageBasePath]);
+
+    /**
+     * Delete a file
+     */
+    const deleteObject = useCallback(async (
+        key: string,
+        bucket?: string
+    ): Promise<void> => {
+        let filePath = key;
+
+        // Handle protocol URLs
+        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://"))) {
+            const withoutProtocol = filePath.substring(filePath.indexOf("://") + 3);
+            filePath = withoutProtocol;
+        }
+
+        if (bucket && filePath && !filePath.startsWith(bucket)) {
+            filePath = `${bucket}/${filePath}`;
+        }
+
+        if (!filePath || filePath.trim() === "" || filePath === "/") {
+            return;
+        }
+
+        const response = await fetchWithAuth(`${storageBasePath}/file/${filePath}`, {
+            method: "DELETE"
+        });
+
+        if (!response.ok && response.status !== 404) {
+            const error = await response.json().catch(() => ({ error: "Failed to delete file" }));
+            throw new Error(error.error || "Failed to delete file");
+        }
+
+        // Clear from cache
+        urlsCache.delete(bucket ? `${bucket}/${key}` : key);
+    }, [fetchWithAuth, storageBasePath, urlsCache]);
+
+    /**
+     * List files in a path
+     */
+    const listObjects = useCallback(async (
+        prefix: string,
+        options?: {
+            bucket?: string;
+            maxResults?: number;
+            pageToken?: string;
+        }
+    ): Promise<StorageListResult> => {
+        const params = new URLSearchParams();
+        if (prefix) params.set("prefix", prefix);
+        if (options?.bucket) params.set("bucket", options.bucket);
+        if (options?.maxResults) params.set("maxResults", String(options.maxResults));
+        if (options?.pageToken) params.set("pageToken", options.pageToken);
+
+        const response = await fetchWithAuth(
+            `${storageBasePath}/list?${params.toString()}`
+        );
+
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: "Failed to list files" }));
+            throw new Error(error.error || "Failed to list files");
+        }
+
+        const result = await response.json();
+        return result.data;
+    }, [fetchWithAuth, storageBasePath]);
+
+    // Return memoized StorageSource
+    return useMemo<StorageSource>(() => ({
+        putObject,
+        getSignedUrl,
+        getObject,
+        deleteObject,
+        listObjects
+    }), [putObject, getSignedUrl, getObject, deleteObject, listObjects]);
+}

package/src/hooks/useBridgeRegistration.tsx

@@ -0,0 +1,32 @@
+import { useContext, useEffect } from "react";
+import type { StudioBridge } from "./useStudioBridge";
+import { StudioBridgeRegistryContext } from "./useStudioBridge";
+
+/**
+ * Registers a value into the self-assembling Studio bridge.
+ *
+ * Each controller (collectionRegistry, sidePanel, url, navigation, breadcrumbs)
+ * calls this hook on mount to inject its real implementation into the bridge.
+ * On unmount the slice is automatically removed, reverting to the noop default.
+ *
+ * Usage:
+ * ```tsx
+ * function SomeProvider({ children }) {
+ *     const controller = useBuildSomeController();
+ *     useBridgeRegistration("sidePanelController", controller);
+ *     return <SomeContext.Provider value={controller}>{children}</SomeContext.Provider>;
+ * }
+ * ```
+ */
+export function useBridgeRegistration<K extends keyof StudioBridge>(
+    key: K,
+    value: StudioBridge[K]
+): void {
+    const registry = useContext(StudioBridgeRegistryContext);
+
+    useEffect(() => {
+        if (!registry) return;
+        registry.register(key, value);
+        return () => registry.unregister(key);
+    }, [registry, key, value]);
+}

package/src/hooks/useBrowserTitleAndIcon.tsx

@@ -0,0 +1,23 @@
+import { useEffect } from "react";
+
+const rebaseLogo = "data:image/png;base64,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";
+
+/**
+ * Internal hook to handle the browser title and icon
+ * @param name
+ * @param logo
+ */
+export function useBrowserTitleAndIcon(name: string, logo?: string) {
+    useEffect(() => {
+        if (document) {
+            document.title = `${name} - Rebase`;
+            let link = document.querySelector("link[rel~='icon']") as HTMLLinkElement | null;
+            if (!link) {
+                link = document.createElement("link");
+                link.rel = "icon";
+                document.getElementsByTagName("head")[0].appendChild(link);
+            }
+            link.href = logo ?? rebaseLogo;
+        }
+    }, [name, logo]);
+}

package/src/hooks/useBuildAdminModeController.tsx

@@ -0,0 +1,24 @@
+import { useCallback, useMemo, useState } from "react";
+import { AdminModeController } from "./index";
+
+/**
+ * Use this hook to build an admin mode controller that determines
+ * whether the UI shows Developer or Editor tools.
+ */
+export function useBuildAdminModeController(): AdminModeController {
+
+    const savedMode = typeof window !== "undefined" ? localStorage.getItem("rebase-admin-mode") as "content" | "studio" | "settings" | null : null;
+    const [mode, setMode] = useState<"content" | "studio" | "settings">(savedMode ?? "content");
+
+    const setModeInternal = useCallback((newMode: "content" | "studio" | "settings") => {
+        if (typeof window !== "undefined") {
+            localStorage.setItem("rebase-admin-mode", newMode);
+        }
+        setMode(newMode);
+    }, []);
+
+    return useMemo(() => ({
+        mode,
+        setMode: setModeInternal
+    }), [mode, setModeInternal]);
+}

package/src/hooks/useBuildEffectiveRoleController.tsx

@@ -0,0 +1,31 @@
+import type { EffectiveRoleController } from "@rebasepro/types";
+import { useCallback, useState, useMemo } from "react";
+;
+
+/**
+ * Use this hook to build an effective role controller that determines
+ * what role is simulated in Editor mode when Dev mode is active.
+ *
+ * It uses localStorage to persist the simulated role across reloads.
+ */
+export function useBuildEffectiveRoleController(): EffectiveRoleController {
+
+    const savedRole = typeof window !== "undefined" ? localStorage.getItem("rebase-effective-role") : null;
+    const [effectiveRole, setEffectiveRole] = useState<string | null>(savedRole ?? null);
+
+    const setRoleInternal = useCallback((newRole: string | null) => {
+        if (typeof window !== "undefined") {
+            if (newRole) {
+                localStorage.setItem("rebase-effective-role", newRole);
+            } else {
+                localStorage.removeItem("rebase-effective-role");
+            }
+        }
+        setEffectiveRole(newRole);
+    }, []);
+
+    return useMemo(() => ({
+        effectiveRole,
+        setEffectiveRole: setRoleInternal
+    }), [effectiveRole, setRoleInternal]);
+}

package/src/hooks/useBuildLocalConfigurationPersistence.tsx

@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+import { PartialCollectionConfig, UserConfigurationPersistence } from "@rebasepro/types";
+import { stripCollectionPath } from "@rebasepro/common";
+import { mergeDeep } from "@rebasepro/utils";
+
+export function useBuildLocalConfigurationPersistence(): UserConfigurationPersistence {
+
+    const configCache = useRef<Record<string, PartialCollectionConfig>>({});
+
+    const getCollectionFromStorage = useCallback((storageKey: string) => {
+        const item = localStorage.getItem(storageKey);
+        return item ? JSON.parse(item) : {};
+    }, []);
+
+    const getCollectionConfig = useCallback(<M extends Record<string, any>>(path: string): PartialCollectionConfig<M> => {
+        const storageKey = `collection_config::${stripCollectionPath(path)}`;
+        if (configCache.current[storageKey]) {
+            return configCache.current[storageKey] as PartialCollectionConfig<M>;
+        }
+        return getCollectionFromStorage(storageKey);
+    }, [getCollectionFromStorage]);
+
+    const onCollectionModified = useCallback(<M extends Record<string, any>>(path: string, data: PartialCollectionConfig<M>) => {
+        const storageKey = `collection_config::${stripCollectionPath(path)}`;
+        localStorage.setItem(storageKey, JSON.stringify(data));
+        const cachedConfig = configCache.current[storageKey];
+        const newConfig = mergeDeep(cachedConfig ?? getCollectionFromStorage(path), data);
+        configCache.current[storageKey] = mergeDeep(configCache.current[storageKey], newConfig);
+    }, [getCollectionFromStorage]);
+
+    const [recentlyVisitedPaths, _setRecentlyVisitedPaths] = useState<string[]>([]);
+    const [favouritePaths, _setFavouritePaths] = useState<string[]>([]);
+    const [collapsedGroups, _setCollapsedGroups] = useState<string[]>([]);
+
+    useEffect(() => {
+        _setRecentlyVisitedPaths(localStorage.getItem("recently_visited_paths") ? JSON.parse(localStorage.getItem("recently_visited_paths")!) : []);
+        _setFavouritePaths(localStorage.getItem("favourite_paths") ? JSON.parse(localStorage.getItem("favourite_paths")!) : []);
+        _setCollapsedGroups(localStorage.getItem("collapsed_groups") ? JSON.parse(localStorage.getItem("collapsed_groups")!) : []);
+    }, []);
+
+    const setRecentlyVisitedPaths = useCallback((paths: string[]) => {
+        localStorage.setItem("recently_visited_paths", JSON.stringify(paths));
+        _setRecentlyVisitedPaths(paths);
+    }, []);
+
+    const setFavouritePaths = useCallback((paths: string[]) => {
+        localStorage.setItem("favourite_paths", JSON.stringify(paths));
+        _setFavouritePaths(paths);
+    }, []);
+
+    const setCollapsedGroups = useCallback((paths: string[]) => {
+        localStorage.setItem("collapsed_groups", JSON.stringify(paths));
+        _setCollapsedGroups(paths);
+    }, []);
+
+    return useMemo(() => ({
+        onCollectionModified,
+        getCollectionConfig,
+        recentlyVisitedPaths,
+        setRecentlyVisitedPaths,
+        favouritePaths,
+        setFavouritePaths,
+        collapsedGroups,
+        setCollapsedGroups
+    }), [
+        onCollectionModified,
+        getCollectionConfig,
+        recentlyVisitedPaths,
+        setRecentlyVisitedPaths,
+        favouritePaths,
+        setFavouritePaths,
+        collapsedGroups,
+        setCollapsedGroups
+    ]);
+}

package/src/hooks/useBuildModeController.tsx

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useState, useMemo } from "react";
+
+import { ModeController } from "./index";
+
+/**
+ * Use this hook to build a color mode controller that determines
+ * the theme of the CMS
+ */
+export function useBuildModeController(): ModeController {
+
+    const prefersDarkModeQuery = useCallback((): boolean => {
+        if (typeof window === "undefined")
+            return false;
+        const mediaQueryList = window.matchMedia("(prefers-color-scheme: dark)");
+        return mediaQueryList.matches;
+    }, []);
+
+    const [mode, setMode] = useState<"light" | "dark">(() => {
+        const prefersDarkModeStorage = typeof window !== "undefined" && localStorage.getItem("prefers-dark-mode") != null
+            ? localStorage.getItem("prefers-dark-mode") === "true"
+            : null;
+        const prefersDarkMode = prefersDarkModeStorage ?? prefersDarkModeQuery();
+        return prefersDarkMode ? "dark" : "light";
+    });
+
+    useEffect(() => {
+        const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+        const handleChange = (e: MediaQueryListEvent) => {
+            if (localStorage.getItem("prefers-dark-mode") == null) {
+                setMode(e.matches ? "dark" : "light");
+                setDocumentMode(e.matches ? "dark" : "light");
+            }
+        };
+
+        // Initial setup
+        setDocumentMode(mode);
+
+        mediaQuery.addEventListener("change", handleChange);
+        return () => mediaQuery.removeEventListener("change", handleChange);
+    }, []);
+
+    const setDocumentMode = (mode: "light" | "dark") => {
+        if (mode === "dark") {
+            document.documentElement.classList.add("dark");
+        } else {
+            document.documentElement.classList.remove("dark");
+        }
+    };
+
+    const setModeInternal = useCallback((mode: "light" | "dark" | "system") => {
+        if (mode === "light") {
+            setDocumentMode("light");
+            localStorage.setItem("prefers-dark-mode", "false");
+            setMode("light");
+        } else if (mode === "dark") {
+            setDocumentMode("dark");
+            localStorage.setItem("prefers-dark-mode", "true");
+            setMode("dark");
+        } else {
+            const preferredMode = prefersDarkModeQuery() ? "dark" : "light";
+            setDocumentMode(preferredMode);
+            localStorage.removeItem("prefers-dark-mode");
+            setMode(preferredMode);
+        }
+    }, [prefersDarkModeQuery]);
+
+    return useMemo(() => ({
+        mode,
+        setMode: setModeInternal
+    }), [mode, setModeInternal]);
+}