@rebasepro/admin 0.0.1-canary.4f204c2

package/src/hooks/useCMSContext.tsx

@@ -0,0 +1,79 @@
+import { useMemo } from "react";
+import { useRebaseContext } from "@rebasepro/core";
+import type {
+    AuthController,
+    RebaseContext,
+    SideDialogsController,
+    SideEntityController,
+    User
+} from "@rebasepro/types";
+import type {
+    CollectionRegistryController,
+    NavigationStateController,
+    UrlController
+} from "@rebasepro/types";
+import { useSideEntityController } from "./useSideEntityController";
+import { useSideDialogsController } from "./useSideDialogsController";
+import {
+    useUrlController,
+    useNavigationStateController,
+    useCollectionRegistryController
+} from "./navigation/contexts";
+
+/**
+ * The CMS context extends the core RebaseContext with CMS-specific
+ * controllers that are only available inside the CMS routing tree.
+ *
+ * Use {@link useCMSContext} to obtain an instance.
+ * @group Hooks and utilities
+ */
+export type CMSContext<
+    DB = Record<string, unknown>,
+    USER extends User = User,
+    AuthControllerType extends AuthController<USER> = AuthController<USER>
+> = RebaseContext<USER, AuthControllerType> & {
+    sideEntityController: SideEntityController;
+    sideDialogsController: SideDialogsController;
+    urlController: UrlController;
+    navigationStateController: NavigationStateController;
+    collectionRegistryController: CollectionRegistryController<DB>;
+};
+
+/**
+ * Hook that builds a fully-populated CMS context by combining the
+ * core {@link RebaseContext} with CMS-specific controllers.
+ *
+ * Use this instead of `useRebaseContext()` in CMS components that
+ * need to pass context to entity action callbacks, plugin slots,
+ * or any consumer that expects CMS controllers on the context object.
+ *
+ * @group Hooks and utilities
+ */
+export function useCMSContext<
+    DB = Record<string, unknown>,
+    USER extends User = User,
+    AuthControllerType extends AuthController<USER> = AuthController<USER>
+>(): CMSContext<DB, USER, AuthControllerType> {
+    const baseContext = useRebaseContext<USER, AuthControllerType>();
+    const sideEntityController = useSideEntityController();
+    const sideDialogsController = useSideDialogsController();
+    const urlController = useUrlController();
+    const navigationStateController = useNavigationStateController();
+    const collectionRegistryController = useCollectionRegistryController<DB>();
+
+    return useMemo(() => ({
+        ...baseContext,
+        sideEntityController,
+        sideDialogsController,
+        urlController,
+        navigationStateController,
+        collectionRegistryController
+    }), [
+        baseContext,
+        sideEntityController,
+        sideDialogsController,
+        urlController,
+        navigationStateController,
+        collectionRegistryController
+    ]);
+}

package/src/hooks/useEntityHistory.ts

@@ -0,0 +1,167 @@
+import { useCallback, useEffect, useRef, useState, useMemo } from "react";
+import { useApiConfig } from "@rebasepro/core";
+
+export interface HistoryEntryData {
+    id: string;
+    table_name: string;
+    entity_id: string;
+    action: "create" | "update" | "delete";
+    changed_fields: string[] | null;
+    values: Record<string, unknown> | null;
+    previous_values: Record<string, unknown> | null;
+    updated_by: string | null;
+    updated_at: string;
+}
+
+export interface UseEntityHistoryResult {
+    entries: HistoryEntryData[];
+    total: number;
+    isLoading: boolean;
+    hasMore: boolean;
+    error?: Error;
+    loadMore: () => void;
+    revert: (historyId: string) => Promise<void>;
+}
+
+/**
+ * Hook to fetch entity history from the backend REST API.
+ * Replaces the old subcollection-based approach with a proper API call.
+ */
+export function useEntityHistory(params: {
+    slug: string;
+    entityId: string | number | undefined;
+    enabled?: boolean;
+    pageSize?: number;
+}): UseEntityHistoryResult {
+    const { slug, entityId, enabled = true, pageSize = 10 } = params;
+    const apiConfig = useApiConfig();
+
+    const [entries, setEntries] = useState<HistoryEntryData[]>([]);
+    const [total, setTotal] = useState(0);
+    const [isLoading, setIsLoading] = useState(false);
+    const [hasMore, setHasMore] = useState(true);
+    const [error, setError] = useState<Error | undefined>();
+    const [offset, setOffset] = useState(0);
+    const [refreshTrigger, setRefreshTrigger] = useState(0);
+
+    // Track the current entity identity so we can detect stale responses
+    const currentEntityRef = useRef<string | undefined>(undefined);
+
+    const fetchEntries = useCallback(async (
+        currentOffset: number,
+        signal?: AbortSignal
+    ) => {
+        if (!apiConfig?.apiUrl || !entityId || !enabled) return;
+
+        setIsLoading(true);
+        setError(undefined);
+
+        try {
+            const token = await apiConfig.getAuthToken?.();
+            const headers: Record<string, string> = {
+                "Content-Type": "application/json"
+            };
+            if (token) headers["Authorization"] = `Bearer ${token}`;
+
+            const url = `${apiConfig.apiUrl}/api/data/${slug}/${entityId}/history?limit=${pageSize}&offset=${currentOffset}`;
+            const response = await fetch(url, { headers,
+signal });
+
+            // Check if the request was aborted or the entity changed while in-flight
+            if (signal?.aborted) return;
+            const entityKey = `${slug}/${entityId}`;
+            if (currentEntityRef.current !== entityKey) return;
+
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
+                throw new Error(errorData.error?.message || `Failed to fetch history (${response.status})`);
+            }
+
+            const result = await response.json();
+
+            if (currentOffset === 0) {
+                setEntries(result.data);
+            } else {
+                setEntries(prev => [...prev, ...result.data]);
+            }
+
+            setTotal(result.meta.total);
+            setHasMore(result.meta.hasMore);
+        } catch (err) {
+            // Don't set error state for intentional aborts
+            if (err instanceof DOMException && err.name === "AbortError") return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+        } finally {
+            setIsLoading(false);
+        }
+    }, [apiConfig, slug, entityId, enabled, pageSize]);
+
+    // Single unified effect: reset state when entity changes, fetch when offset changes.
+    // Uses AbortController to cancel stale requests on entity change or unmount.
+    useEffect(() => {
+        const entityKey = `${slug}/${entityId}`;
+        const isNewEntity = currentEntityRef.current !== entityKey;
+
+        if (isNewEntity) {
+            // Reset state for new entity
+            currentEntityRef.current = entityKey;
+            setEntries([]);
+            setTotal(0);
+            setHasMore(true);
+            setOffset(0);
+        }
+
+        if (!enabled || !entityId) return;
+
+        const abortController = new AbortController();
+        // When entity changed, always fetch from offset 0
+        const effectiveOffset = isNewEntity ? 0 : offset;
+        fetchEntries(effectiveOffset, abortController.signal);
+
+        return () => {
+            abortController.abort();
+        };
+    }, [fetchEntries, offset, enabled, entityId, slug, refreshTrigger]);
+
+    const loadMore = useCallback(() => {
+        if (!isLoading && hasMore && offset + entries.length < total) {
+            setOffset(prev => prev + pageSize);
+        }
+    }, [isLoading, hasMore, pageSize, offset, entries.length, total]);
+
+    const revert = useCallback(async (historyId: string) => {
+        if (!apiConfig?.apiUrl || !entityId) {
+            throw new Error("Cannot revert: missing API configuration or entity ID");
+        }
+
+        const token = await apiConfig.getAuthToken?.();
+        const headers: Record<string, string> = {
+            "Content-Type": "application/json"
+        };
+        if (token) headers["Authorization"] = `Bearer ${token}`;
+
+        const url = `${apiConfig.apiUrl}/api/data/${slug}/${entityId}/history/${historyId}/revert`;
+        const response = await fetch(url, { method: "POST",
+headers });
+
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
+            throw new Error(errorData.error?.message || `Failed to revert (${response.status})`);
+        }
+
+        // Refresh the history list after revert by resetting the entity ref
+        // and triggering the effect.
+        currentEntityRef.current = undefined;
+        setRefreshTrigger(prev => prev + 1);
+    }, [apiConfig, slug, entityId]);
+
+    return useMemo(() => ({
+        entries,
+        total,
+        isLoading,
+        hasMore,
+        error,
+        loadMore,
+        revert
+    }), [entries, total, isLoading, hasMore, error, loadMore, revert]);
+}

package/src/hooks/useEntitySelectionDialog.tsx

@@ -0,0 +1,57 @@
+import { EntitySelectionProps, EntitySelectionTable } from "../components";
+import type { EntityCollection } from "@rebasepro/types";
+import { useCallback, useMemo } from "react";
+import { useSideDialogsController } from "../index";
+import { useCollectionRegistryController } from "../index";
+
+/**
+ * This hook is used to open a side dialog that allows the selection
+ * of entities under a given path.
+ * You can use it in custom views for selecting entities.
+ * You need to specify the path of the target collection at least.
+ * If your collection is not defined in your  top collection configuration
+ * (in your `Rebase` component), you need to specify explicitly.
+ * This is the same hook used internally when a reference property is defined.
+ * @group Hooks and utilities
+ */
+export function useEntitySelectionDialog<M extends Record<string, unknown>>(referenceDialogProps: Omit<EntitySelectionProps<M>, "path"> & {
+    path?: string | false;
+    onClose?: () => void;
+}): { open: () => void; close: () => void } {
+
+    const navigation = useCollectionRegistryController();
+    const sideDialogsController = useSideDialogsController();
+
+    const open = useCallback(() => {
+        if (referenceDialogProps.path) {
+            let usedCollection = referenceDialogProps.collection;
+            if (!usedCollection)
+                usedCollection = navigation.getCollection(referenceDialogProps.path) as EntityCollection<M> | undefined;
+            if (!usedCollection)
+                throw Error("Not able to resolve the collection in useEntitySelectionDialog. Make sure a collection is registered in path " + referenceDialogProps.path);
+            sideDialogsController.open({
+                key: `reference_${referenceDialogProps.path}`,
+                component:
+                    <EntitySelectionTable
+                        collection={usedCollection}
+                        {...referenceDialogProps as EntitySelectionProps<M>}/>,
+                width: "90vw",
+                onClose: () => {
+                    referenceDialogProps.onClose?.();
+                }
+            });
+        } else {
+            throw Error("useReferenceDialog: You are trying to open a reference dialog, but have not declared the `path`")
+        }
+    }, [navigation, referenceDialogProps, sideDialogsController]);
+
+    const close = useCallback(() => {
+        sideDialogsController.close();
+    }, [sideDialogsController]);
+
+    return useMemo(() => ({
+        open,
+        close
+    }), [open, close]);
+
+}

package/src/hooks/useResolvedNavigationFrom.tsx

@@ -0,0 +1,160 @@
+import type { EntityCollection, EntityCustomView } from "@rebasepro/types";
+import { Entity, RebaseContext, User } from "@rebasepro/types";
+import { useEffect, useState, useMemo } from "react";
+import { getNavigationEntriesFromPath } from "@rebasepro/common";
+import { useCMSContext } from "./useCMSContext";
+
+/**
+ * @see resolveNavigationFrom
+ * @group Hooks and utilities
+ */
+export type ResolvedNavigationEntry<M extends Record<string, unknown>> =
+    | ResolvedNavigationEntity<M>
+    | ResolvedNavigationCollection<M>
+    | ResolvedNavigationEntityCustom<M>;
+
+/**
+ * @see resolveNavigationFrom
+ * @group Hooks and utilities
+ */
+export interface ResolvedNavigationEntity<M extends Record<string, unknown>> {
+    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, unknown>> {
+    type: "collection";
+    path: string;
+    collection: EntityCollection<M>;
+}
+
+/**
+ * @see resolveNavigationFrom
+ * @group Hooks and utilities
+ */
+interface ResolvedNavigationEntityCustom<M extends Record<string, unknown>> {
+    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, unknown>, USER extends User>({
+    path,
+    context
+}: {
+    path: string,
+    context: RebaseContext<USER>
+}): Promise<ResolvedNavigationEntry<M>[]> {
+
+    const data = context.data;
+    const { navigationStateController, collectionRegistryController } = context;
+
+    if (!navigationStateController || !collectionRegistryController) {
+        throw Error("Calling resolveNavigationFrom, but main navigation has not yet been initialised");
+    }
+
+    const navigationEntries = getNavigationEntriesFromPath({
+        path,
+        collections: collectionRegistryController.collections ?? []
+    });
+
+    const resultPromises: Promise<ResolvedNavigationEntry<any>>[] = navigationEntries
+        .map((entry) => {
+            if (entry.type === "collection") {
+                return Promise.resolve(entry);
+            } else if (entry.type === "entity") {
+                const collection = collectionRegistryController.getCollection(entry.slug);
+                if (!collection) {
+                    throw Error(`No collection defined in the navigation for the entity with path ${entry.slug}`);
+                }
+                return data.collection(entry.slug).findById(entry.entityId)
+                    .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, unknown>> {
+    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, unknown>>(
+    {
+        path
+    }: NavigationFromProps): NavigationFrom<M> {
+
+    const context = useCMSContext();
+    const { navigationStateController, collectionRegistryController } = context;
+
+    const [data, setData] = useState<ResolvedNavigationEntry<M>[] | undefined>();
+    const [dataLoading, setDataLoading] = useState<boolean>(false);
+    const [dataLoadingError, setDataLoadingError] = useState<Error | undefined>();
+
+    useEffect(() => {
+        if (navigationStateController && collectionRegistryController) {
+            setDataLoading(true);
+            setDataLoadingError(undefined);
+            resolveNavigationFrom<M, User>({ path,
+context })
+                .then(setData)
+                .catch((e) => setDataLoadingError(e))
+                .finally(() => setDataLoading(false));
+        }
+
+    }, [path, context]);
+
+    return useMemo(() => {
+        if (!navigationStateController) {
+            return { dataLoading: true };
+        }
+        return { data,
+dataLoading,
+dataLoadingError };
+    }, [navigationStateController, data, dataLoading, dataLoadingError]);
+}

package/src/hooks/useSideDialogsController.tsx

@@ -0,0 +1,25 @@
+import React from "react";
+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
+ */
+import { SideDialogPanelProps, SideDialogsController } from "@rebasepro/types";
+
+export type { SideDialogPanelProps, SideDialogsController };
+
+export const useSideDialogsController = (): SideDialogsController => useContext(SideDialogsControllerContext);

package/src/hooks/useSideEntityController.tsx

@@ -0,0 +1,13 @@
+import type { SideEntityController } from "@rebasepro/types";
+import React, { useContext } from "react";
+
+export const SideEntityControllerContext = React.createContext<SideEntityController>({} as SideEntityController);
+
+/**
+ * Use this hook to retrieve an entity controller that allows you to open
+ * a side dialog to edit an entity.
+ *
+ * @see SideEntityController
+ * @group Hooks and utilities
+ */
+export const useSideEntityController = (): SideEntityController => useContext(SideEntityControllerContext);

package/src/index.ts

@@ -0,0 +1,95 @@
+// CMS-specific types take priority over base types when names conflict
+export * from "./types";
+// Editor types only — the full ProseMirror editor is a heavy import (~300 KB)
+// and is available as a separate entry point: @rebasepro/admin/editor
+export type { RebaseEditorProps, JSONContent, EditorAIController } from "./editor";
+export * from "./form";
+export * from "./preview";
+export * from "./routes";
+
+// Components — explicitly listed to avoid conflicts with ./types re-exports
+export {
+    EntityView,
+    EntitySelectionTable,
+    SelectableTable,
+    SelectableTableContext,
+    EntityCollectionView,
+    EntityCollectionViewActions,
+    EntityCollectionCardView,
+    EntityCard,
+    useSelectionController,
+    PropertyConfigBadge,
+    PropertyIdCopyTooltip,
+    EntityCollectionTable,
+    EntityCollectionRowActions,
+    VirtualTableInput,
+    ArrayContainer,
+    type ArrayEntryParams,
+    ReferenceWidget,
+    SearchIconsView,
+    FieldCaption,
+    EntityPreview,
+    getFieldConfig,
+    getFieldId,
+    getDefaultFieldConfig,
+    getDefaultFieldId,
+    DEFAULT_FIELD_CONFIGS,
+    editEntityAction,
+    copyEntityAction,
+    deleteEntityAction,
+    SideEntityProvider,
+    Scaffold,
+    AppBar,
+    Drawer,
+    AdminModeSyncer,
+    // ContentHomePage, UsersView, RolesView are lazy-loaded — not re-exported here
+    RebaseCMS,
+    RebaseShell,
+    RebaseAuthGate,
+    RebaseNavigation,
+    RebaseLayout,
+    RebaseRouteDefs,
+    SideDialogs,
+    useApp
+} from "./components";
+export type {
+    EntityViewProps,
+    EntitySelectionProps,
+    SelectableTableProps
+} from "./components";
+
+export * from "./hooks";
+// Util
+export {
+    addInitialSlash,
+    removeInitialSlash,
+    removeTrailingSlash,
+    removeInitialAndTrailingSlashes,
+    getLastSegment,
+    getCollectionBySlugWithin,
+    getCollectionPathsCombinations,
+    resolveCollectionPathIds,
+    mergeEntityActions,
+    resolveEntityAction,
+    resolveEntityView,
+    // Property utilities (moved from @rebasepro/core — property-aware logic belongs in CMS)
+    isReferenceProperty,
+    isRelationProperty,
+    getIconForWidget,
+    getIconForProperty,
+    getPropertyInPath,
+    getResolvedPropertyInPath,
+    getBracketNotation,
+    getPropertiesWithPropertiesOrder,
+    getDefaultPropertiesOrder,
+    // Preview utilities (moved from @rebasepro/core — property-aware logic belongs in CMS)
+    getEntityPreviewKeys,
+    getEntityTitlePropertyKey
+} from "./util";
+
+// Data import/export — merged from former standalone packages
+export * from "./data_import";
+export * from "./data_export";
+
+// Collection editor — moved from @rebasepro/studio (CMS-dependent visual schema editor)
+export * from "./collection_editor";