@rebasepro/app 0.0.1-canary.4829d6e

package/src/hooks/data/useCollection.tsx

@@ -0,0 +1,176 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import { useEffect, useState, useMemo } from "react";
+import { Entity, FilterValues, User } from "@rebasepro/types";
+import { useData } from "./useData";
+import { isSchemaDriftError, useSchemaDriftContext } from "../../components/SchemaDriftBanner";
+/**
+ * @group Hooks and utilities
+ */
+export interface CollectionProps<M extends Record<string, any>> {
+
+    /**
+     * Absolute collection path
+     */
+    path: string;
+
+    /**
+     * collection of the entity displayed by this collection
+     */
+    collection: CollectionConfig<M>
+
+    /**
+     * Number of entities to fetch
+     */
+    itemCount?: number;
+
+    /**
+     * Number of items to skip
+     */
+    offset?: number;
+
+    /**
+     * Page number (1-indexed), alternative to offset
+     */
+    page?: number;
+
+    /**
+     * Filter the fetched data by the property
+     */
+    filterValues?: FilterValues<Extract<keyof M, string>>;
+
+    /**
+     * Sort the results by
+     */
+    sortBy?: [Extract<keyof M, string>, "asc" | "desc"];
+
+    /**
+     * Search string
+     */
+    searchString?: string;
+}
+
+/**
+ * @group Hooks and utilities
+ */
+export interface CollectionResult<M extends Record<string, any>> {
+    data: Entity<M>[];
+    dataLoading: boolean;
+    noMoreToLoad: boolean;
+    dataLoadingError?: Error;
+    totalCount?: number;
+}
+
+/**
+ * This hook is used to fetch collections using a given collection
+ * @param path
+ * @param collection
+ * @param filterValues
+ * @param sortBy
+ * @param itemCount
+ * @param offset
+ * @param page
+ * @param searchString
+ * @group Hooks and utilities
+ */
+export function useCollection<M extends Record<string, any>, USER extends User>(
+    {
+        path,
+        collection,
+        filterValues,
+        sortBy,
+        itemCount,
+        offset,
+        page,
+        searchString
+    }: CollectionProps<M>): CollectionResult<M> {
+    const dataClient = useData();
+    const { reportSchemaDrift } = useSchemaDriftContext();
+
+    const sortByProperty = sortBy ? sortBy[0] : undefined;
+    const currentSort = sortBy ? sortBy[1] : undefined;
+    // Map to PostgREST format for orderBy
+    const orderByParams: [string, "asc" | "desc"] | undefined = sortBy ? [String(sortBy[0]), sortBy[1]] : undefined;
+
+    // filterValues is already FilterValues — pass directly
+    const whereParams = filterValues && Object.keys(filterValues).length > 0 ? filterValues : undefined;
+
+    const [data, setData] = useState<Entity<M>[]>([]);
+
+    const [dataLoading, setDataLoading] = useState<boolean>(false);
+    const [dataLoadingError, setDataLoadingError] = useState<Error | undefined>();
+    const [noMoreToLoad, setNoMoreToLoad] = useState<boolean>(false);
+    const [totalCount, setTotalCount] = useState<number | undefined>();
+
+    useEffect(() => {
+
+        setDataLoading(true);
+
+        const onEntitiesUpdate = async (res: { data: Entity<M>[], meta: { hasMore: boolean; total?: number } }) => {
+            const entities = res.data;
+            setDataLoading(false);
+            setDataLoadingError(undefined);
+            setData(entities.map(e => ({
+                ...e
+            })));
+            setNoMoreToLoad(!res.meta.hasMore);
+            setTotalCount(res.meta.total);
+        };
+
+        const onError = (error: Error) => {
+            console.error("ERROR", error);
+            setDataLoading(false);
+            setData([]);
+            setDataLoadingError(error);
+            setTotalCount(undefined);
+            // Report schema drift to the global banner context
+            if (isSchemaDriftError(error)) {
+                reportSchemaDrift(error.message);
+            }
+        };
+
+        const accessor = dataClient.collection(path);
+
+        // Eagerly include relations to avoid N+1 fetches.
+        const hasRelations = collection.properties && Object.values(collection.properties).some(
+            (p) => p.type === "relation" || p.type === "reference"
+        );
+        const includeParams = hasRelations ? ["*"] : undefined;
+
+        if (accessor.listen) {
+            return accessor.listen({
+                where: whereParams,
+                limit: itemCount,
+                offset,
+                page,
+                orderBy: orderByParams,
+                searchString,
+                include: includeParams
+            }, (res) => onEntitiesUpdate({ data: res.data as Entity<M>[],
+meta: res.meta }), onError);
+        } else {
+            accessor.find({
+                where: whereParams,
+                limit: itemCount,
+                offset,
+                page,
+                orderBy: orderByParams,
+                searchString,
+                include: includeParams
+            })
+                .then((res) => onEntitiesUpdate({ data: res.data as Entity<M>[],
+meta: res.meta }))
+                .catch(onError);
+            return () => {
+            };
+        }
+    }, [path, itemCount, offset, page, currentSort, sortByProperty, filterValues, searchString, dataClient, collection]);
+
+    return useMemo(() => ({
+        data,
+        dataLoading,
+        dataLoadingError,
+        noMoreToLoad,
+        totalCount
+    }), [data, dataLoading, dataLoadingError, noMoreToLoad, totalCount]);
+
+}

package/src/hooks/data/useData.tsx

@@ -0,0 +1,18 @@
+import { useContext } from "react";
+import { RebaseData } from "@rebasepro/types";
+import { RebaseDataContext } from "../../contexts/RebaseDataContext";
+
+/**
+ * Use this hook to access the unified data API.
+ *
+ * ```ts
+ * const data = useData();
+ * const { data: products } = await data.products.find({ where: { status: ["==", "published"] } });
+ * await data.products.create({ name: "Camera", price: 299 });
+ * ```
+ *
+ * @group Hooks and utilities
+ */
+export const useData = (): RebaseData => {
+    return useContext(RebaseDataContext);
+};

package/src/hooks/data/useDataOrder.ts

@@ -0,0 +1,26 @@
+import { Entity } from "@rebasepro/types";
+
+export interface DataOrderProps<M extends Record<string, any>> {
+    data: Entity<M>[];
+    entitiesDisplayedFirst?: Entity<M>[];
+}
+
+/**
+ * This hook is used to have some entities at the beginning of data.
+ * @param path
+ * @param entitiesDisplayedFirst
+ * @group Hooks and utilities
+ */
+export function useDataOrder<M extends Record<string, any>>(
+    {
+        data,
+        entitiesDisplayedFirst
+    }: DataOrderProps<M>): Entity<M>[] {
+
+    if (!entitiesDisplayedFirst)
+        return data;
+
+    const displayedFirstId = new Set(entitiesDisplayedFirst.map((e) => e.id));
+    return [...entitiesDisplayedFirst, ...data.filter((e) => !displayedFirstId.has(e.id))];
+
+}

package/src/hooks/data/useFetch.tsx

@@ -0,0 +1,140 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import { useEffect, useState, useMemo } from "react";
+import { Entity, RebaseContext, User } from "@rebasepro/types";
+import { useData } from "./useData";
+import { useRebaseContext } from "../useRebaseContext";
+
+/**
+ * @group Hooks and utilities
+ */
+export interface FetchProps<M extends Record<string, any>, USER extends User = User> {
+    path: string;
+    entityId?: string | number;
+    databaseId?: string;
+    collection: CollectionConfig<M, USER>;
+    useCache?: boolean;
+}
+
+/**
+ * @group Hooks and utilities
+ */
+export interface FetchResult<M extends Record<string, any>> {
+    entity?: Entity<M>,
+    dataLoading: boolean,
+    dataLoadingError?: Error
+}
+
+const CACHE: Record<string, Entity<any> | undefined> = {};
+
+/**
+ * Pre-populate the entity fetch cache with entities loaded from a collection.
+ * This allows entity detail views to render instantly using cached data,
+ * while the background fetch/listener brings in fresh data.
+ * @param path - The collection path (e.g. "products")
+ * @param entities - Array of entities to cache
+ */
+export function populateFetchCache<M extends Record<string, any>>(path: string, entities: Entity<M>[]): void {
+    for (const entity of entities) {
+        CACHE[`${path}/${entity.id}`] = entity;
+    }
+}
+
+/**
+ * Clear the entity fetch cache. Call this on auth state changes (e.g. logout)
+ * to prevent stale data from a previous session leaking into the next.
+ */
+export function clearFetchCache(): void {
+    for (const key of Object.keys(CACHE)) {
+        delete CACHE[key];
+    }
+}
+
+/**
+ * This hook is used to fetch a entity.
+ * It gives real time updates if the driver supports it.
+ * @param path
+ * @param collection
+ * @param entityId
+ * @param useCache
+ * @group Hooks and utilities
+ */
+
+export function useFetch<M extends Record<string, any>, USER extends User = User>(
+    {
+        path,
+        entityId,
+        collection,
+        databaseId,
+        useCache = false
+    }: FetchProps<M, USER>): FetchResult<M> {
+
+    const dataClient = useData();
+
+    const context: RebaseContext<USER> = useRebaseContext();
+
+    // Seed initial state from the cache to avoid skeleton flashes.
+    // Even when useCache is false, we show cached data instantly while
+    // the background fetch/listener brings in fresh data.
+    const cacheKey = entityId ? `${path}/${entityId}` : undefined;
+    const cachedEntity = cacheKey ? CACHE[cacheKey] as Entity<M> | undefined : undefined;
+
+    const [entity, setEntity] = useState<Entity<M> | undefined>(cachedEntity);
+    const [dataLoading, setDataLoading] = useState<boolean>(!cachedEntity);
+    const [dataLoadingError, setDataLoadingError] = useState<Error | undefined>();
+
+    useEffect(() => {
+
+        // Only show loading state if we have no cached entity to display
+        if (!CACHE[`${path}/${entityId}`]) {
+            setDataLoading(true);
+        }
+
+        const onEntityUpdate = async (updatedEntity?: Entity<M> | null) => {
+            CACHE[`${path}/${entityId}`] = updatedEntity ?? undefined;
+            setEntity(updatedEntity ?? undefined);
+            setDataLoading(false);
+            setDataLoadingError(undefined);
+        };
+
+        const onError = (error: Error) => {
+            console.error("ERROR fetching entity", error);
+            setDataLoading(false);
+            setEntity(undefined);
+            setDataLoadingError(error);
+        };
+
+        if (entityId && useCache && CACHE[`${path}/${entityId}`]) {
+            setEntity(CACHE[`${path}/${entityId}`]);
+            setDataLoading(false);
+            setDataLoadingError(undefined);
+            // eslint-disable-next-line @typescript-eslint/no-empty-function
+            return () => {
+            };
+        } else if (entityId && path && collection) {
+            const accessor = dataClient.collection(path);
+
+            if (accessor.listenById) {
+                return accessor.listenById(entityId, (entity) => onEntityUpdate(entity as Entity<M> | undefined), onError);
+            } else {
+                accessor.findById(entityId)
+                    .then((entity) => onEntityUpdate(entity as Entity<M> | undefined))
+                    .catch(onError);
+                return () => {
+                };
+            }
+        }
+        // if no entityId is provided we do nothing
+        else {
+            onEntityUpdate(undefined);
+            return () => {
+            };
+        }
+    }, [entityId, path, dataClient, collection, useCache, databaseId]);
+
+    return useMemo(() => ({
+        entity,
+        dataLoading,
+        dataLoadingError
+    }), [entity, dataLoading, dataLoadingError]);
+
+}

package/src/hooks/data/useRelationSelector.tsx

@@ -0,0 +1,234 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+import { useData } from "./useData";
+import { Entity, EntityRelation, FilterValues } from "@rebasepro/types";
+export interface RelationItem {
+    id: string | number;
+    label: string;
+    description?: string;
+    data: Entity<any>;
+    relation: EntityRelation;
+}
+
+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: CollectionConfig<M>;
+    /**
+     * Force filter to be applied to the relation search
+     */
+    fixedFilter?: FilterValues<string>;
+    /**
+     * Page size for pagination
+     */
+    pageSize?: number;
+    /**
+     * Function to extract the label from a entity
+     */
+    getLabelFromEntity?: (entity: Entity<M>) => string;
+    /**
+     * Function to extract the description from a 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,
+        fixedFilter,
+        pageSize = DEFAULT_PAGE_SIZE,
+        getLabelFromEntity,
+        getDescriptionFromEntity,
+        descriptionProperty
+    }: UseRelationSelectorProps<M>
+): RelationSelectorController {
+
+    const dataClient = useData();
+
+    const [items, setItems] = useState<RelationItem[]>([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const isLoadingRef = useRef(false);
+    const [error, setError] = useState<Error | undefined>();
+    const [hasMore, setHasMore] = useState(true);
+    const [currentSearch, setCurrentSearch] = useState<string>("");
+    const [limit, setLimit] = useState<number>(pageSize);
+
+    const unsubscribeRef = useRef<(() => void) | null>(null);
+    const searchTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+    const setLoading = useCallback((loading: boolean) => {
+        isLoadingRef.current = loading;
+        setIsLoading(loading);
+    }, []);
+
+    // 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;
+        }
+    }, []);
+
+    const fetchData = useCallback(() => {
+        cleanupSubscription();
+        setError(undefined);
+        setLoading(true);
+
+        // fixedFilter is already FilterValues — pass directly
+        const whereParams = fixedFilter && Object.keys(fixedFilter).length > 0 ? fixedFilter : undefined;
+
+        const onEntitiesUpdate = (res: { data: Entity<M>[], meta: { hasMore: boolean } }) => {
+            const newItems = res.data.map((e) => entityToRelationItem(e));
+            setItems(newItems);
+            setHasMore(res.meta.hasMore);
+            setLoading(false);
+        };
+
+        const onErrorUpdate = (fetchError: Error) => {
+            console.error("useRelationSelector: Error fetching data:", fetchError);
+            setError(fetchError);
+            setLoading(false);
+        };
+
+        const accessor = dataClient.collection(path);
+
+        let unsubscribe: (() => void) | undefined;
+
+        if (accessor.listen) {
+            unsubscribe = accessor.listen({
+                where: whereParams,
+                limit: limit,
+                orderBy: undefined,
+                searchString: currentSearch
+            }, (res) => onEntitiesUpdate({ data: res.data as Entity<M>[],
+meta: res.meta }), onErrorUpdate);
+        } else {
+            accessor.find({
+                where: whereParams,
+                limit: limit,
+                offset: 0,
+                orderBy: undefined,
+                searchString: currentSearch
+            })
+                .then((res) => onEntitiesUpdate({ data: res.data as Entity<M>[],
+meta: res.meta }))
+                .catch(onErrorUpdate);
+            unsubscribe = () => {};
+        }
+
+        unsubscribeRef.current = unsubscribe || null;
+    }, [dataClient, path, fixedFilter, limit, currentSearch, entityToRelationItem, cleanupSubscription, setLoading]);
+
+    // Search function with debouncing
+    const search = useCallback((searchString: string) => {
+        // Clear existing timeout
+        if (searchTimeoutRef.current) {
+            clearTimeout(searchTimeoutRef.current);
+        }
+
+        // Debounce search
+        searchTimeoutRef.current = setTimeout(() => {
+            setLimit(pageSize);
+            setCurrentSearch(searchString);
+        }, searchString.trim() ? 300 : 0);
+    }, [pageSize]);
+
+    // Load more function
+    const loadMore = useCallback(() => {
+        if (!isLoadingRef.current && hasMore && items.length > 0) {
+            setLoading(true);
+            setLimit(prev => prev + pageSize);
+        }
+    }, [hasMore, items.length, pageSize, setLoading]);
+
+    // Load initial data and update upon changes
+    useEffect(() => {
+        fetchData();
+
+        return () => {
+            cleanupSubscription();
+        };
+    }, [fetchData]);
+
+    useEffect(() => {
+        return () => {
+            if (searchTimeoutRef.current) {
+                clearTimeout(searchTimeoutRef.current);
+            }
+        };
+    }, []);
+
+    return useMemo(() => ({
+        items,
+        isLoading,
+        error,
+        search,
+        loadMore,
+        hasMore,
+        entityToRelationItem
+    }), [items, isLoading, error, search, loadMore, hasMore, entityToRelationItem]);
+}

package/src/hooks/index.tsx

@@ -0,0 +1,45 @@
+export * from "./data/useData";
+export * from "./data/useCollection";
+export * from "./data/useFetch";
+export * from "./data/useRelationSelector";
+export * from "./data/save";
+export * from "./data/delete";
+
+
+export * from "./useUnsavedChangesDialog";
+
+export * from "./useStorageSource";
+export * from "./useAuthController";
+export * from "./useAuthSubscription";
+export * from "./useDialogsController";
+export * from "./useAdminModeController";
+export * from "./useBuildAdminModeController";
+export * from "./useEffectiveRoleController";
+export * from "./useBuildEffectiveRoleController";
+export * from "./useRebaseContext";
+export * from "./useSnackbarController";
+export * from "./useModeController";
+export * from "./useClipboard";
+export * from "./useLargeLayout";
+export * from "./useCollapsedGroups";
+
+export * from "./useBrowserTitleAndIcon";
+export * from "./useSlot";
+export * from "./useCustomizationController";
+
+export * from "./useBuildLocalConfigurationPersistence";
+export * from "./useBuildModeController";
+
+export * from "./useRebaseRegistry";
+export * from "./useBackendStorageSource";
+export * from "./usePermissions";
+
+export * from "./ApiConfigContext";
+
+export * from "./useTranslation";
+export * from "./useRebaseClient";
+
+export * from "./useAnalyticsController";
+export * from "./useUserConfigurationPersistence";
+export * from "./useResolvedComponent";
+export * from "./useComponentOverride";

package/src/hooks/useAdminModeController.tsx

@@ -0,0 +1,23 @@
+import { AdminModeControllerContext } from "../contexts/AdminModeController";
+import { useContext } from "react";
+
+/**
+ * Use this controller to change the admin mode (developer vs editor)
+ * @group Hooks and utilities
+ */
+export interface AdminModeController {
+    mode: "content" | "studio" | "settings";
+    setMode: (mode: "content" | "studio" | "settings") => void;
+}
+
+/**
+ * Hook to retrieve the current admin mode ("developer" | "editor"), and `setMode`
+ * to change it.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see AdminModeController
+ * @group Hooks and utilities
+ */
+export const useAdminModeController = () => useContext(AdminModeControllerContext);

package/src/hooks/useAnalyticsController.tsx

@@ -0,0 +1,8 @@
+import { useContext } from "react";
+import { AnalyticsController } from "@rebasepro/types";
+import { AnalyticsContext } from "../contexts/AnalyticsContext";
+
+/**
+ * @group Hooks and utilities
+ */
+export const useAnalyticsController = (): AnalyticsController => useContext(AnalyticsContext);

package/src/hooks/useAuthController.tsx

@@ -0,0 +1,14 @@
+import { AuthController, User } from "@rebasepro/types";
+import { useContext } from "react";
+import { AuthControllerContext } from "../contexts/AuthControllerContext";
+
+/**
+ * Hook to retrieve the AuthContext.
+ *
+ * Consider that in order to use this hook you need to have a parent
+ * `Rebase`
+ *
+ * @see AuthController
+ * @group Hooks and utilities
+ */
+export const useAuthController = <USER extends User = User, AuthControllerType extends AuthController<USER> = AuthController<USER>>(): AuthControllerType => useContext(AuthControllerContext) as AuthControllerType;