@rebasepro/core 0.0.1-canary.0

package/src/hooks/useBackendStorageSource.ts

@@ -0,0 +1,276 @@
+/**
+ * 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 uploadFile = useCallback(async ({
+        file,
+        fileName,
+        path,
+        metadata,
+        bucket
+    }: UploadFileProps): Promise<UploadFileResult> => {
+        const formData = new FormData();
+        formData.append('file', file);
+
+        if (fileName) {
+            formData.append('fileName', fileName);
+        }
+        if (path) {
+            formData.append('path', path);
+        }
+        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 getDownloadURL = useCallback(async (
+        pathOrUrl: string,
+        bucket?: string
+    ): Promise<DownloadConfig> => {
+        // Check cache first
+        const cacheKey = bucket ? `${bucket}/${pathOrUrl}` : pathOrUrl;
+        const cached = urlsCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+
+        // Build the file path for the API
+        let filePath = pathOrUrl;
+
+        // Handle local:// and s3:// URLs
+        if (pathOrUrl.startsWith('local://') || pathOrUrl.startsWith('s3://')) {
+            const withoutProtocol = pathOrUrl.substring(pathOrUrl.indexOf('://') + 3);
+            filePath = withoutProtocol;
+        }
+
+        // If bucket is provided separately, prepend it
+        if (bucket && !filePath.startsWith(bucket)) {
+            filePath = `${bucket}/${filePath}`;
+        }
+
+        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();
+
+        // The URL should point to the storage file endpoint
+        const downloadConfig: DownloadConfig = {
+            url: `${storageBasePath}/file/${filePath}`,
+            metadata: result.data
+        };
+
+        // Cache the result
+        urlsCache.set(cacheKey, downloadConfig);
+
+        return downloadConfig;
+    }, [fetchWithAuth, storageBasePath, urlsCache]);
+
+    /**
+     * Get file as a File object
+     */
+    const getFile = useCallback(async (
+        path: string,
+        bucket?: string
+    ): Promise<File | null> => {
+        let filePath = path;
+
+        // Handle protocol URLs
+        if (path.startsWith('local://') || path.startsWith('s3://')) {
+            const withoutProtocol = path.substring(path.indexOf('://') + 3);
+            filePath = withoutProtocol;
+        }
+
+        if (bucket && !filePath.startsWith(bucket)) {
+            filePath = `${bucket}/${filePath}`;
+        }
+
+        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 deleteFile = useCallback(async (
+        path: string,
+        bucket?: string
+    ): Promise<void> => {
+        let filePath = path;
+
+        // Handle protocol URLs
+        if (path.startsWith('local://') || path.startsWith('s3://')) {
+            const withoutProtocol = path.substring(path.indexOf('://') + 3);
+            filePath = withoutProtocol;
+        }
+
+        if (bucket && !filePath.startsWith(bucket)) {
+            filePath = `${bucket}/${filePath}`;
+        }
+
+        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}/${path}` : path);
+    }, [fetchWithAuth, storageBasePath, urlsCache]);
+
+    /**
+     * List files in a path
+     */
+    const list = useCallback(async (
+        path: string,
+        options?: {
+            bucket?: string;
+            maxResults?: number;
+            pageToken?: string;
+        }
+    ): Promise<StorageListResult> => {
+        const params = new URLSearchParams();
+        if (path) params.set('path', path);
+        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>(() => ({
+        uploadFile,
+        getDownloadURL,
+        getFile,
+        deleteFile,
+        list
+    }), [uploadFile, getDownloadURL, getFile, deleteFile, list]);
+}

package/src/hooks/useBreadcrumbsController.tsx

@@ -0,0 +1,49 @@
+import { useContext } from "react";
+import { BreadcrumbContext } from "../contexts/BreacrumbsContext";
+
+/**
+ * @group Hooks and utilities
+ */
+export interface BreadcrumbsController {
+    breadcrumbs: BreadcrumbEntry[];
+    set: (props: {
+        breadcrumbs: BreadcrumbEntry[];
+    }) => void;
+    /**
+     * Update the count for a specific breadcrumb by ID.
+     */
+    updateCount: (id: string, count: number | null | undefined) => void;
+}
+
+
+/**
+ * @group Hooks and utilities
+ */
+export interface BreadcrumbEntry {
+    title: string;
+    url: string;
+    /**
+     * Optional entity count for collection breadcrumbs.
+     * - undefined: not applicable (e.g., entity breadcrumb, custom view)
+     * - null: loading
+     * - number: loaded count
+     */
+    count?: number | null;
+    /**
+     * Unique identifier for this breadcrumb (e.g., collection path).
+     * Used to update count without replacing entire breadcrumb array.
+     */
+    id?: string;
+}
+
+
+/**
+ * Hook to retrieve the BreadcrumbsController.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see BreadcrumbsController
+ * @group Hooks and utilities
+ */
+export const useBreadcrumbsController = (): BreadcrumbsController => useContext(BreadcrumbContext);

package/src/hooks/useBrowserTitleAndIcon.tsx

@@ -0,0 +1,25 @@
+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']");
+            if (!link) {
+                link = document.createElement("link");
+                // @ts-ignore
+                link.rel = "icon";
+                document.getElementsByTagName("head")[0].appendChild(link);
+            }
+            // @ts-ignore
+            link.href = logo ?? rebaseLogo;
+        }
+    }, [name, logo]);
+}

package/src/hooks/useBuildAdminModeController.tsx

@@ -0,0 +1,24 @@
+import { useCallback, 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 {
+        mode,
+        setMode: setModeInternal
+    };
+}

package/src/hooks/useBuildEffectiveRoleController.tsx

@@ -0,0 +1,30 @@
+import { useCallback, useState } from "react";
+import { EffectiveRoleController } from "@rebasepro/types";
+
+/**
+ * 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 {
+        effectiveRole,
+        setEffectiveRole: setRoleInternal
+    };
+}

package/src/hooks/useBuildLocalConfigurationPersistence.tsx

@@ -0,0 +1,65 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { PartialEntityCollection, UserConfigurationPersistence } from "@rebasepro/types";
+import { mergeDeep, stripCollectionPath } from "@rebasepro/common";
+
+export function useBuildLocalConfigurationPersistence(): UserConfigurationPersistence {
+
+    const configCache = useRef<Record<string, PartialEntityCollection>>({});
+
+    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): PartialEntityCollection<M> => {
+        const storageKey = `collection_config::${stripCollectionPath(path)}`;
+        if (configCache.current[storageKey]) {
+            return configCache.current[storageKey] as PartialEntityCollection<M>;
+        }
+        return getCollectionFromStorage(storageKey);
+    }, [getCollectionFromStorage]);
+
+    const onCollectionModified = useCallback(<M extends Record<string, any>>(path: string, data: PartialEntityCollection<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 {
+        onCollectionModified,
+        getCollectionConfig,
+        recentlyVisitedPaths,
+        setRecentlyVisitedPaths,
+        favouritePaths,
+        setFavouritePaths,
+        collapsedGroups,
+        setCollapsedGroups
+    }
+}

package/src/hooks/useBuildModeController.tsx

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useState } 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 {
+        mode,
+        setMode: setModeInternal
+    };
+}