@rebasepro/app 0.0.1-canary.4829d6e

package/src/hooks/useRebaseRegistry.tsx

@@ -0,0 +1,91 @@
+import React, { createContext, useContext, useState, useCallback, useMemo, useRef } from "react";
+import type { RebaseRegistryController, RebaseAdminConfig, RebaseStudioConfig, RebaseAuthConfig } from "@rebasepro/types";
+
+/**
+ * Split into two contexts to prevent infinite re-render loops:
+ * - DispatchContext: stable register/unregister functions (never changes identity)
+ * - StateContext: the current config values (changes when modules register)
+ *
+ * Feature components (RebaseAuth, RebaseAdmin, RebaseStudio) only consume
+ * the dispatch context, so registering does NOT cause them to re-render.
+ * RebaseShell consumes state context to read the collected configs.
+ */
+
+interface RegistryDispatch {
+    registerCMS: (config: RebaseAdminConfig) => void;
+    unregisterCMS: () => void;
+    registerStudio: (config: RebaseStudioConfig) => void;
+    unregisterStudio: () => void;
+    registerAuth: (config: RebaseAuthConfig) => void;
+    unregisterAuth: () => void;
+}
+
+interface RegistryState {
+    cmsConfig: RebaseAdminConfig | null;
+    studioConfig: RebaseStudioConfig | null;
+    authConfig: RebaseAuthConfig | null;
+}
+
+const RegistryDispatchContext = createContext<RegistryDispatch | undefined>(undefined);
+const RegistryStateContext = createContext<RegistryState>({
+    cmsConfig: null,
+    studioConfig: null,
+    authConfig: null
+});
+
+export function RebaseRegistryProvider({ children }: { children: React.ReactNode }) {
+    const [cmsConfig, setCmsConfig] = useState<RebaseAdminConfig | null>(null);
+    const [studioConfig, setStudioConfig] = useState<RebaseStudioConfig | null>(null);
+    const [authConfig, setAuthConfig] = useState<RebaseAuthConfig | null>(null);
+
+    // Dispatch functions are stable — never change identity
+    const dispatch = useMemo<RegistryDispatch>(() => ({
+        registerCMS: (config: RebaseAdminConfig) => setCmsConfig(config),
+        unregisterCMS: () => setCmsConfig(null),
+        registerStudio: (config: RebaseStudioConfig) => setStudioConfig(config),
+        unregisterStudio: () => setStudioConfig(null),
+        registerAuth: (config: RebaseAuthConfig) => setAuthConfig(config),
+        unregisterAuth: () => setAuthConfig(null)
+    }), []);
+
+    const state = useMemo<RegistryState>(() => ({
+        cmsConfig,
+studioConfig,
+authConfig
+    }), [cmsConfig, studioConfig, authConfig]);
+
+    return (
+        <RegistryDispatchContext.Provider value={dispatch}>
+            <RegistryStateContext.Provider value={state}>
+                {children}
+            </RegistryStateContext.Provider>
+        </RegistryDispatchContext.Provider>
+    );
+}
+
+/**
+ * Returns the full registry (state + dispatch).
+ * Use this in RebaseShell where you need to read configs.
+ */
+export function useRebaseRegistry(): RebaseRegistryController {
+    const dispatch = useContext(RegistryDispatchContext);
+    const state = useContext(RegistryStateContext);
+    if (!dispatch) {
+        throw new Error("useRebaseRegistry must be used within RebaseRegistryProvider");
+    }
+    return useMemo(() => ({ ...state,
+...dispatch }), [state, dispatch]);
+}
+
+/**
+ * Returns only the stable dispatch functions.
+ * Use this in feature components (RebaseAuth, RebaseAdmin, RebaseStudio)
+ * to avoid re-render loops.
+ */
+export function useRebaseRegistryDispatch(): RegistryDispatch {
+    const dispatch = useContext(RegistryDispatchContext);
+    if (!dispatch) {
+        throw new Error("useRebaseRegistryDispatch must be used within RebaseRegistryProvider");
+    }
+    return dispatch;
+}

package/src/hooks/useResolvedComponent.tsx

@@ -0,0 +1,159 @@
+import React, { lazy, useMemo } from "react";
+import type { ComponentRef, LazyComponentRef } from "@rebasepro/types";
+import { isLazyComponentRef } from "@rebasepro/types";
+
+/**
+ * Internal cache for resolved lazy components.
+ *
+ * `React.lazy()` must return the SAME wrapper across renders — if we call
+ * `lazy(loader)` on every render, React will treat each result as a new
+ * component type and unmount/remount on each render cycle.
+ *
+ * This WeakMap keeps a stable mapping from a `ComponentRef` (object/function)
+ * to the `React.lazy()` wrapper it produced. Strings are keyed by a separate
+ * plain Map since they can't be WeakMap keys.
+ */
+
+const lazyCache = new WeakMap<object | ((...args: any[]) => any), React.ComponentType<any>>();
+
+/**
+ * Resolves a `ComponentRef` into a renderable `React.ComponentType`.
+ *
+ * This hook handles all three forms of `ComponentRef`:
+ *
+ * 1. **`LazyComponentRef`** (produced by the Vite plugin from string paths):
+ *    Wraps the lazy loader with `React.lazy()` for automatic code-splitting.
+ *
+ * 2. **`() => Promise<{ default: ComponentType }>`** (manual lazy import):
+ *    Also wraps with `React.lazy()`. Distinguished from regular components
+ *    by checking that the function has no parameters and is not a known
+ *    React internal (no `$$typeof`).
+ *
+ * 3. **Direct `React.ComponentType`**:
+ *    Returned as-is.
+ *
+ * If the ref is `undefined` or a raw string (which should never happen at
+ * runtime in the browser since the Vite plugin transforms strings), returns `undefined`.
+ *
+ * The returned component is stable across re-renders as long as the `ref`
+ * is referentially stable.
+ *
+ * **Usage:** Wrap the rendered component in `<Suspense>` to handle the
+ * loading state of lazy components.
+ *
+ * @example
+ * ```tsx
+ * const ResolvedField = useResolvedComponent(property.ui?.Field);
+ * if (!ResolvedField) return null;
+ * return (
+ *     <Suspense fallback={<CircularProgress />}>
+ *         <ResolvedField {...fieldProps} />
+ *     </Suspense>
+ * );
+ * ```
+ * */
+export function useResolvedComponent<P = unknown>(
+    ref: ComponentRef<P> | undefined
+): React.ComponentType<P> | undefined {
+    return useMemo(() => resolveComponentRef(ref), [ref]);
+}
+
+/**
+ * Wraps a loader function with `React.lazy()`, caching the result so the
+ * same loader always returns the same lazy component identity.
+ */
+function getOrCreateLazy<P>(
+    key: object | ((...args: any[]) => any),
+    loader: () => Promise<{ default: React.ComponentType<P> }>
+): React.ComponentType<P> {
+    const cached = lazyCache.get(key);
+    if (cached) return cached as React.ComponentType<P>;
+
+    // SAFETY: React.lazy returns LazyExoticComponent which is structurally compatible with ComponentType<P>
+    const LazyComponent = lazy(loader) as React.ComponentType<P>;
+    lazyCache.set(key, LazyComponent);
+    return LazyComponent;
+}
+
+/**
+ * Pure function version of the resolver, for use outside React components.
+ * Same resolution logic as `useResolvedComponent`.
+ *
+ * Results are cached per reference identity — calling this multiple times
+ * with the same `ref` object returns the same `React.ComponentType`.
+ */
+export function resolveComponentRef<P = unknown>(
+    ref: ComponentRef<P> | undefined
+): React.ComponentType<P> | undefined {
+    if (ref == null) return undefined;
+
+    // 1. String — should not happen at runtime (Vite transforms them).
+    //    Log a warning and bail out.
+    if (typeof ref === "string") {
+        console.warn(
+            `[Rebase] Encountered a raw string ComponentRef ("${ref}") at runtime. ` +
+            "This usually means the Vite transform plugin did not process this file. " +
+            "Ensure the file is inside the configured collectionsDir."
+        );
+        return undefined;
+    }
+
+    // 2. LazyComponentRef — produced by the Vite plugin from string paths.
+    //    The object has { __rebaseLazy: true, load: () => import(...) }.
+    if (isLazyComponentRef(ref)) {
+        return getOrCreateLazy<P>(
+            ref as object,
+            () => (ref as LazyComponentRef<P>).load()
+        );
+    }
+
+    // 3. Function — either a React component or a lazy import loader.
+    if (typeof ref === "function") {
+        const fn = ref as (...args: any[]) => any;
+
+        // Class components (React.Component / PureComponent) have this flag
+        if (fn.prototype?.isReactComponent) {
+            return ref as React.ComponentType<P>;
+        }
+
+        // React internals (forwardRef, memo, etc.) carry $$typeof
+        if ("$$typeof" in fn) {
+            return ref as React.ComponentType<P>;
+        }
+
+        // A function with declared parameters (fn.length > 0) is a regular
+        // component that accepts props — return as-is.
+        if (fn.length > 0) {
+            return ref as React.ComponentType<P>;
+        }
+
+        // Zero-parameter function — could be a React component with no props
+        // OR a lazy loader `() => import(...)`. We distinguish by checking
+        // if `fn.name` looks like a component (starts with uppercase) or is
+        // an anonymous arrow.
+        //
+        // Convention: named function components always start with an
+        // uppercase letter. Dynamic import wrappers are typically anonymous
+        // arrows or have lowercase names.
+        const name = fn.name;
+        if (name && /^[A-Z]/.test(name)) {
+            // Named component (e.g. `function MyField() { ... }`) — return as-is
+            return ref as React.ComponentType<P>;
+        }
+
+        // Treat as a lazy loader — wrap with React.lazy, cached by identity.
+        return getOrCreateLazy<P>(
+            fn,
+            ref as () => Promise<{ default: React.ComponentType<P> }>
+        );
+    }
+
+    // 4. React wrapper objects (React.forwardRef, React.memo) —
+    //    These are objects with $$typeof but are not functions.
+    if (typeof ref === "object" && "$$typeof" in (ref as object)) {
+        return ref as unknown as React.ComponentType<P>;
+    }
+
+    // 5. Unknown shape — return undefined to be safe
+    return undefined;
+}

package/src/hooks/useSlot.tsx

@@ -0,0 +1,64 @@
+import type { SlotName, SlotRegistry } from "@rebasepro/types";
+import React, { useMemo } from "react";
+;
+import { useCustomizationController } from "./useCustomizationController";
+import { ErrorBoundary } from "@rebasepro/ui";
+
+/**
+ * Hook that retrieves and renders all slot contributions for a given slot name.
+ *
+ * @param slot - The slot name to render contributions for.
+ * @param props - Props passed to each slot component.
+ * @returns An array of rendered React nodes, each wrapped in an ErrorBoundary.
+ *
+ * @example
+ * ```tsx
+ * const actions = useSlot("home.actions", { context });
+ * return <div>{actions}</div>;
+ * ```
+ *
+ * @group Hooks
+ */
+export function useSlot<K extends SlotName>(
+    slot: K,
+    props: SlotRegistry[K]
+): React.ReactNode[] {
+    const { resolvedSlots } = useCustomizationController();
+
+    const propsRef = React.useRef(props);
+    const currentProps = props as unknown as Record<string, unknown>;
+    const prevProps = propsRef.current as unknown as Record<string, unknown>;
+
+    let changed = false;
+    if (currentProps !== prevProps) {
+        const keys = Object.keys(currentProps);
+        const prevKeys = Object.keys(prevProps);
+        if (keys.length !== prevKeys.length) {
+            changed = true;
+        } else {
+            for (let i = 0; i < keys.length; i++) {
+                if (currentProps[keys[i]] !== prevProps[keys[i]]) {
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+
+    if (changed) {
+        propsRef.current = props;
+    }
+
+    const stableProps = propsRef.current;
+
+    return useMemo(() => {
+        return resolvedSlots
+            .filter(s => s.slot === slot)
+            .sort((a, b) => (a.order ?? 50) - (b.order ?? 50))
+            .map((s, i) => (
+                <ErrorBoundary key={`${slot}_${i}`}>
+                    <s.Component {...(stableProps as unknown as Record<string, unknown>)} {...(s.props ?? {})}/>
+                </ErrorBoundary>
+            ));
+    }, [resolvedSlots, slot, stableProps]);
+}

package/src/hooks/useSnackbarController.tsx

@@ -0,0 +1,52 @@
+import type { SnackbarMessageType } from "@rebasepro/types";
+import React, { useCallback, useMemo } from "react";
+import { useSnackbar } from "notistack";
+;
+
+/**
+ * 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,11 @@
+import { 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 = (): StorageSource => {
+    return useContext(StorageSourceContext);
+};

package/src/hooks/useStudioBridge.tsx

@@ -0,0 +1,209 @@
+import React, { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
+import type {
+    CollectionRegistryController,
+    SidePanelController,
+    UrlController,
+    NavigationStateController,
+    BreadcrumbEntry,
+    BreadcrumbsController
+} from "@rebasepro/types";
+
+export type { BreadcrumbEntry, BreadcrumbsController };
+
+// ─── Breadcrumbs ──────────────────────────────────────────────────
+
+
+// ─── Bridge interface ───────────────────────────────────────────────
+
+/**
+ * StudioBridge provides optional CMS capabilities to Studio components.
+ * When CMS is present, a bridge provider injects real implementations.
+ * When CMS is absent, noop defaults ensure Studio works standalone.
+ */
+export interface StudioBridge {
+    collectionRegistry: CollectionRegistryController;
+    sidePanelController: SidePanelController;
+    urlController: UrlController;
+    navigationState: NavigationStateController;
+    breadcrumbs: BreadcrumbsController;
+}
+
+// ─── Noop defaults ──────────────────────────────────────────────────
+
+const NOOP_COLLECTION_REGISTRY: CollectionRegistryController = {
+    getCollection: () => undefined,
+    getRawCollection: () => undefined,
+    getParentReferencesFromPath: () => [],
+    getParentCollectionSlugs: () => [],
+    getParentEntityIds: () => [],
+    convertIdsToPaths: () => [],
+    initialised: false
+};
+
+const NOOP_SIDE_PANEL: SidePanelController = {
+    open: () => {},
+    replace: () => {},
+    close: () => {}
+};
+
+const NOOP_URL_CONTROLLER: UrlController = {
+    basePath: "/",
+    baseCollectionPath: "/c",
+    urlPathToDataPath: () => "",
+    homeUrl: "/",
+    isUrlCollectionPath: () => false,
+    buildUrlCollectionPath: () => "",
+    buildAppUrlPath: () => "",
+    resolveDatabasePathsFrom: () => "",
+    navigate: () => {}
+};
+
+const NOOP_NAVIGATION_STATE: NavigationStateController = {
+    loading: false,
+    refreshNavigation: () => {}
+};
+
+const NOOP_BREADCRUMBS: BreadcrumbsController = {
+    breadcrumbs: [],
+    set: () => {},
+    updateCount: () => {}
+};
+
+const NOOP_BRIDGE: StudioBridge = {
+    collectionRegistry: NOOP_COLLECTION_REGISTRY,
+    sidePanelController: NOOP_SIDE_PANEL,
+    urlController: NOOP_URL_CONTROLLER,
+    navigationState: NOOP_NAVIGATION_STATE,
+    breadcrumbs: NOOP_BREADCRUMBS
+};
+
+// ─── Context & Provider ─────────────────────────────────────────────
+
+export const StudioBridgeContext = createContext<StudioBridge>(NOOP_BRIDGE);
+
+/**
+ * Provider that injects CMS capabilities into Studio.
+ * Accepts partial overrides — any field not provided falls back to noop.
+ *
+ * Usage (in app wiring, when CMS is present):
+ * ```tsx
+ * <StudioBridgeProvider value={{
+ *     collectionRegistry: useCollectionRegistryController(),
+ *     sidePanelController: useSidePanel(),
+ *     urlController: useUrlController(),
+ *     navigationState: useNavigationStateController(),
+ *     breadcrumbs: useBreadcrumbsController(),
+ * }}>
+ *     <RebaseStudio ... />
+ * </StudioBridgeProvider>
+ * ```
+ */
+export function StudioBridgeProvider({
+    value,
+    children
+}: {
+    value: Partial<StudioBridge>;
+    children: React.ReactNode;
+}) {
+    const merged = React.useMemo(
+        () => ({ ...NOOP_BRIDGE,
+...value }),
+        [value]
+    );
+    return (
+        <StudioBridgeContext.Provider value={merged}>
+            {children}
+        </StudioBridgeContext.Provider>
+    );
+}
+
+// ─── Convenience hooks ──────────────────────────────────────────────
+
+/** Collection registry — returns noop if CMS is not present. */
+export function useStudioCollectionRegistry(): CollectionRegistryController {
+    return useContext(StudioBridgeContext).collectionRegistry;
+}
+
+/** Side panel controller — returns noop if CMS is not present. */
+export function useStudioSidePanelController(): SidePanelController {
+    return useContext(StudioBridgeContext).sidePanelController;
+}
+
+/** URL controller — returns noop if CMS is not present. */
+export function useStudioUrlController(): UrlController {
+    return useContext(StudioBridgeContext).urlController;
+}
+
+/** Navigation state — returns noop if CMS is not present. */
+export function useStudioNavigationState(): NavigationStateController {
+    return useContext(StudioBridgeContext).navigationState;
+}
+
+/** Breadcrumbs controller — returns noop if CMS is not present. */
+export function useStudioBreadcrumbs(): BreadcrumbsController {
+    return useContext(StudioBridgeContext).breadcrumbs;
+}
+
+// ─── Self-Assembling Bridge Registry ────────────────────────────────
+
+/**
+ * Registry that controllers use to self-register their implementations
+ * into the Studio bridge. Each controller calls `register(key, value)`
+ * on mount and `unregister(key)` on unmount.
+ */
+export interface StudioBridgeRegistry {
+    register: <K extends keyof StudioBridge>(key: K, value: StudioBridge[K]) => void;
+    unregister: (key: keyof StudioBridge) => void;
+}
+
+export const StudioBridgeRegistryContext = createContext<StudioBridgeRegistry | null>(null);
+
+/**
+ * Provider that creates a self-assembling bridge.
+ *
+ * Mount this above the controller providers. Each controller calls
+ * `useBridgeRegistration(key, value)` to inject its implementation.
+ * The bridge context value is automatically kept in sync.
+ *
+ * ```tsx
+ * <StudioBridgeRegistryProvider>
+ *     <CollectionRegistryProvider>   // auto-registers
+ *     <SidePanelProvider>           // auto-registers
+ *     <UrlProvider>                  // auto-registers
+ *         <RebaseStudio />           // consumes bridge
+ *     </UrlProvider>
+ *     </SidePanelProvider>
+ *     </CollectionRegistryProvider>
+ * </StudioBridgeRegistryProvider>
+ * ```
+ */
+export function StudioBridgeRegistryProvider({ children }: { children: React.ReactNode }) {
+    const [version, setVersion] = useState(0);
+    const slicesRef = useRef<Partial<StudioBridge>>({});
+
+    const register = useCallback(<K extends keyof StudioBridge>(key: K, value: StudioBridge[K]) => {
+        slicesRef.current[key] = value;
+        setVersion(v => v + 1);
+    }, []);
+
+    const unregister = useCallback((key: keyof StudioBridge) => {
+        delete slicesRef.current[key];
+        setVersion(v => v + 1);
+    }, []);
+
+    const registry = useMemo<StudioBridgeRegistry>(() => ({ register,
+unregister }), [register, unregister]);
+
+    const bridgeValue = useMemo<StudioBridge>(() => ({
+        ...NOOP_BRIDGE,
+        ...slicesRef.current
+    }), [version]);
+
+    return (
+        <StudioBridgeRegistryContext.Provider value={registry}>
+            <StudioBridgeContext.Provider value={bridgeValue}>
+                {children}
+            </StudioBridgeContext.Provider>
+        </StudioBridgeRegistryContext.Provider>
+    );
+}

package/src/hooks/useTranslation.ts

@@ -0,0 +1,33 @@
+import { useTranslation as useI18nTranslation } from "react-i18next";
+import { useCallback, useMemo } from "react";
+
+const REBASE_NS = "rebase_core";
+
+/**
+ * Internal hook for translating Rebase UI strings.
+ *
+ * Uses the `rebase_core` i18next namespace that is initialised by
+ * `RebaseI18nProvider`. Do NOT use `react-i18next` directly in internal
+ * components — always go through this hook so the namespace is consistent.
+ *
+ * @example
+ * const { t } = useTranslation();
+ * <Button>{t("save")}</Button>
+ *
+ * @internal
+ */
+export function useTranslation() {
+    const { t, i18n } = useI18nTranslation(REBASE_NS);
+
+    /**
+     * Typed translation function scoped to RebaseTranslations keys.
+     * Also supports i18next interpolation variables, e.g.
+     *   t("add_to_field", { fieldName: "Tags" })
+     *   t("error_deleting", { message: err.message })
+     */
+    const typedT = useCallback((key: string, vars?: Record<string, string>): string =>
+        t(key, vars) as string, [t]);
+
+    return useMemo(() => ({ t: typedT,
+i18n }), [typedT, i18n]);
+}

package/src/hooks/useUnsavedChangesDialog.tsx

@@ -0,0 +1,64 @@
+import { useCallback, useEffect, useState, useMemo } 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]);
+
+    const triggerDialog = useCallback(() => setManualDialogOpen(true), []);
+
+    return useMemo(() => ({
+        dialogProps: {
+            open: manualDialogOpen || blocker.state === "blocked",
+            handleOk,
+            handleCancel,
+            body: "There are unsaved changes in this collection"
+        },
+        triggerDialog
+    }), [manualDialogOpen, blocker.state, handleOk, handleCancel, triggerDialog]);
+}