@rebasepro/admin-types 0.10.1-canary.0

package/src/controllers/navigation.ts

@@ -0,0 +1,264 @@
+import React from "react";
+import type { EntityReference } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/admin-types";
+
+/**
+ * Controller that handles URL path building and resolution.
+ * @group Models
+ */
+export type UrlController = {
+    /**
+     * Default path under the navigation routes of the CMS will be created.
+     * Defaults to '/'. You may want to change this `basepath` to 'admin' for example.
+     */
+    basePath: string;
+
+    /**
+     * Default path under the collection routes of the CMS will be created.
+     * It defaults to '/c'
+     */
+    baseCollectionPath: string;
+
+    /**
+     * Convert a URL path to a collection or entity path
+     * `/c/products` => `products`
+     * `/my_cms/c/products/B34SAP8Z` => `products/B34SAP8Z`
+     * `/my_cms/my_view` => `my_view`
+     * @param cmsPath
+     */
+    urlPathToDataPath: (cmsPath: string) => string;
+
+    /**
+     * Base url path for the home screen
+     */
+    homeUrl: string;
+
+    /**
+     * Check if a url path belongs to a collection
+     * @param path
+     */
+    isUrlCollectionPath: (urlPath: string) => boolean;
+
+    /**
+     * Build a URL collection path from a data path
+     * `products` => `/c/products`
+     * `products/B34SAP8Z` => `/c/products/B34SAP8Z`
+     * @param path
+     */
+    buildUrlCollectionPath: (path: string) => string;
+
+    /**
+     * Build a URL path for the CMS (e.g. for custom views)
+     * @param path
+     */
+    buildAppUrlPath: (path: string) => string;
+
+    /**
+     * Turn a path with collection ids into a resolved path.
+     * The ids (typically used in urls) will be replaced with relative paths (typically used in database paths)
+     * @param path
+     */
+    resolveDatabasePathsFrom: (path: string) => string;
+
+    /**
+     * A function to navigate to a specified route or URL.
+     *
+     * @param {string} to - The target route or URL to navigate to.
+     * @param {NavigateOptions} [options] - Optional configuration settings for navigation, such as replace behavior or state data.
+     */
+    navigate: (to: string, options?: NavigateOptions) => void;
+};
+
+/**
+ * Controller that manages the state of the navigation menu,
+ * including resolved views and top-level grouping.
+ * @group Models
+ */
+export type NavigationStateController = {
+    /**
+     * Custom additional views created by the developer, added to the main
+     * navigation
+     */
+    views?: AppView[];
+
+    /**
+     * Custom additional views created by the developer, added to the admin
+     * navigation
+     */
+    adminViews?: AppView[];
+
+    /**
+     * Configuration for the views that should be displayed at the top
+     * level of the navigation (e.g. in the home page or the navigation
+     * drawer)
+     */
+    topLevelNavigation?: NavigationResult;
+
+    /**
+     * Is the navigation loading (the configuration persistence has not
+     * loaded yet, or a specified navigation builder has not completed)
+     */
+    loading: boolean;
+
+    /**
+     * Was there an error while loading the navigation data
+     */
+    navigationLoadingError?: Error;
+
+    /**
+     * Call this method to recalculate the navigation
+     */
+    refreshNavigation: () => void;
+};
+
+export interface NavigateOptions {
+    replace?: boolean;
+    state?: unknown;
+    preventScrollReset?: boolean;
+    relative?: "route" | "path";
+    flushSync?: boolean;
+    viewTransition?: boolean;
+}
+
+/**
+ * Custom additional views created by the developer, added to the main
+ * navigation.
+ * @group Models
+ */
+export interface AppView {
+
+    /**
+     * CMS Path you can reach this view from.
+     */
+    slug: string;
+
+    /**
+     * Name of this view
+     */
+    name: string;
+
+    /**
+     * Optional description of this view. You can use Markdown
+     */
+    description?: string;
+
+    /**
+     * Icon key to use in this view.
+     * You can use any of the icons in the Lucide specs:
+     * https://lucide.dev/icons/
+     * e.g. 'ShoppingCart' or 'User'
+     * Find all the icons in https://rebase.pro/docs/icons
+     */
+    icon?: string | React.ReactNode;
+
+    /**
+     * Should this view be hidden from the main navigation panel.
+     * It will still be accessible if you reach the specified path
+     */
+    hideFromNavigation?: boolean;
+
+    /**
+     * Navigation group for this view.
+     * Views sharing the same group name will be visually grouped
+     * together in the drawer and home page. If not set, the view
+     * falls into the default "Views" group.
+     */
+    group?: string;
+
+    /**
+     * Component to be rendered. This can be any React component, and can use
+     * any of the provided hooks.
+     *
+     * Pass a `ComponentType` to enable lazy rendering — the component will
+     * only be instantiated when the route is visited. This is recommended
+     * for dynamic views generated from database data.
+     */
+    view: React.ReactNode | React.ComponentType;
+
+    /**
+     * If true, a wildcard route (slug/*) is automatically registered
+     * alongside the base route, enabling nested navigation within this view.
+     */
+    nestedRoutes?: boolean;
+
+    /**
+     * Restrict this view to users with at least one of the listed roles.
+     * When omitted or empty, the view is visible to all authenticated users.
+     * Applied during view resolution — the view is filtered out entirely
+     * (not just hidden from nav) if the user lacks a matching role.
+     */
+    roles?: string[];
+
+}
+
+/**
+ * A composable section that can be rendered on the home page.
+ * Use this to add custom content alongside the auto-generated
+ * navigation groups.
+ * @group Models
+ */
+export interface HomePageSection {
+    /**
+     * Unique key for this section.
+     */
+    key: string;
+
+    /**
+     * Title displayed as the section header.
+     */
+    title: string;
+
+    /**
+     * Arbitrary React content rendered inside the section.
+     */
+    children: React.ReactNode;
+}
+
+/**
+ * Used to group navigation entries in the main navigation.
+ */
+export interface NavigationGroupMapping {
+    /**
+     * Name of the group, used to display the group header in the UI
+     */
+    name: string;
+    /**
+     * List of collection ids or view paths that belong to this group.
+     */
+    entries: string[];
+    /**
+     * Configure which groups start collapsed.
+     * Set to `true` to collapse in both drawer and home page,
+     * or use an object to control each independently.
+     *
+     * @defaultValue false (expanded)
+     */
+    collapsedByDefault?: boolean | {
+        drawer?: boolean;
+        home?: boolean;
+    };
+}
+
+export interface NavigationEntry {
+    id: string;
+    url: string;
+    name: string;
+    slug: string;
+    type: "collection" | "view" | "admin";
+    collection?: AdminCollection;
+    view?: AppView;
+    description?: string;
+    group: string;
+}
+
+export type NavigationResult = {
+
+    allowDragAndDrop: boolean;
+
+    navigationEntries: NavigationEntry[],
+
+    groups: string[],
+
+    onNavigationEntriesUpdate: (entries: NavigationGroupMapping[]) => void;
+};
+

package/src/controllers/registry.ts

@@ -0,0 +1,96 @@
+import { ReactNode } from "react";
+
+import type { CollectionConfigsBuilder, AppViewsBuilder } from "../types/builders";
+import type { EntityCustomView } from "../types/entity_views";
+import type { EntityAction } from "../types/entity_actions";
+import type { AppView, NavigationGroupMapping } from "./navigation";
+import type { AdminCollection } from "@rebasepro/admin-types";
+
+/**
+ * Options to enable the built-in collection editor.
+ * When provided to `<RebaseAdmin>`, the editor is auto-wired as a native feature.
+ */
+export interface CollectionEditorOptions {
+    /**
+     * Function that returns an auth token for schema-editor API calls.
+     * Falls back to `authController.getAuthToken` when omitted.
+     */
+    getAuthToken?: () => Promise<string | null>;
+    /** Mark the editor as read-only (disable mutations). */
+    readOnly?: boolean;
+    /** Suggested base paths shown when creating new collections. */
+    pathSuggestions?: string[];
+}
+
+export interface RebaseAdminConfig<EC extends AdminCollection = AdminCollection> {
+    collections?: EC[] | CollectionConfigsBuilder<EC>;
+
+    /**
+     * Custom top-level views added to the main navigation.
+     * Accepts a static array of views or an async builder function
+     * that receives the current user/auth context for role-based views.
+     */
+    views?: AppView[] | AppViewsBuilder;
+
+    homePage?: ReactNode;
+    entityViews?: EntityCustomView[];
+    entityActions?: EntityAction[];
+
+    /**
+     * Centralized configuration for how collections and views are grouped
+     * in the navigation sidebar and home page.
+     * Each mapping defines a named group and the collection/view slugs
+     * that belong to it. The array order determines group display order.
+     * Entry order within each group determines card order.
+     */
+    navigationGroupMappings?: NavigationGroupMapping[];
+
+    /**
+     * Enable the built-in visual collection/schema editor.
+     * Pass `true` for zero-config, or an options object for fine-grained control.
+     * When enabled, the editor slots, provider, and Studio schema view
+     * are all auto-wired — no plugin or manual view injection needed.
+     */
+    collectionEditor?: boolean | CollectionEditorOptions;
+
+    /**
+     * URL path prefix the admin is mounted under, when it does not live at the
+     * site root. Set this when the admin is rendered inside a path-prefixed
+     * route (e.g. `<Route path="/admin/*">`) so URL⇄collection resolution
+     * accounts for the prefix — otherwise the current path won't be recognized
+     * as a collection path and views hang on a spinner with no data fetch.
+     *
+     * Do NOT set this when mounting via a react-router `basename` — react-router
+     * already strips the prefix from the location, so the default (`/`) is correct.
+     *
+     * @default "/"
+     */
+    basePath?: string;
+}
+
+export interface RebaseStudioConfig {
+    tools?: ("sql" | "js" | "rls" | "schema" | "storage" | "cron" | "schema-visualizer" | "branches" | "backups" | "api" | "logs" | "api-keys")[];
+    homePage?: ReactNode;
+    devViews?: AppView[];
+}
+
+export interface RebaseAuthConfig {
+    loginView?: ReactNode;
+}
+
+export interface RebaseRegistryController {
+    // Current state
+    cmsConfig: RebaseAdminConfig | null;
+    studioConfig: RebaseStudioConfig | null;
+    authConfig: RebaseAuthConfig | null;
+
+    // Registration functions
+    registerCMS: (config: RebaseAdminConfig) => void;
+    unregisterCMS: () => void;
+
+    registerStudio: (config: RebaseStudioConfig) => void;
+    unregisterStudio: () => void;
+
+    registerAuth: (config: RebaseAuthConfig) => void;
+    unregisterAuth: () => void;
+}

package/src/controllers/side_dialogs_controller.tsx

@@ -0,0 +1,82 @@
+import React from "react";
+
+/**
+ * Controller to open the side dialog
+ * @group Hooks and utilities
+ */
+export interface SideDialogsController {
+
+    /**
+     * Close the last panel
+     */
+    close: () => void;
+
+    /**
+     * List of side panels currently open
+     */
+    sidePanels: SideDialogPanelProps[];
+
+    /**
+     * Override the current side panels
+     * @param panels
+     */
+    setSidePanels: (panels: SideDialogPanelProps[]) => void;
+
+    /**
+     * Open one or multiple side panels
+     * @param props
+     */
+    open: (panelProps: SideDialogPanelProps | SideDialogPanelProps[]) => void;
+
+    /**
+     * Replace the last open panel with the given one
+     * @param props
+     */
+    replace: (panelProps: SideDialogPanelProps | SideDialogPanelProps[]) => void;
+}
+
+/**
+ * Props used to open a side dialog
+ * @group Hooks and utilities
+ */
+export interface SideDialogPanelProps {
+
+    /**
+     * A key that identifies this panel
+     */
+    key: string;
+
+    /**
+     * The component type that will be rendered
+     */
+    component: React.ReactNode;
+
+    /**
+     * Optional width of the panel
+     */
+    width?: string;
+
+    /**
+     * When open, change the URL to this path.
+     * Note that if you want to restore state from a URL you need to add the
+     * logic yourself by listening to URL updates, and probably call `open`.
+     */
+    urlPath?: string;
+
+    /**
+     * If the navigation stack is empty (you landed in the `urlPath` url), what
+     * url path to change to when the panel gets closed.
+     */
+    parentUrlPath?: string;
+
+    /**
+     * Callback when the panel is closed
+     */
+    onClose?: () => void;
+
+    /**
+     * Use this prop to store additional data in the panel
+     */
+    additional?: unknown;
+
+}

package/src/controllers/side_panel_controller.tsx

@@ -0,0 +1,112 @@
+import type { Entity } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/admin-types";
+
+/**
+ * Props used to open a side dialog
+ * @group Hooks and utilities
+ */
+export interface SidePanelBindingProps<M extends Record<string, unknown> = Record<string, unknown>> {
+
+    /**
+     * Absolute path of the entity
+     */
+    path: string;
+
+    /**
+     * ID of the entity, if not set, it means we are creating a new entity
+     */
+    entityId?: string | number;
+
+    /**
+     * Set this flag to true if you want to make a copy of an existing entity
+     */
+    copy?: boolean;
+
+    /**
+     * Open the entity with a selected sub-collection view. If the panel for this
+     * entity was already open, it is replaced.
+     */
+    selectedTab?: string;
+
+    /**
+     * Use this prop to override the width of the form view.
+     * e.g. "600px"
+     */
+    width?: number | string;
+
+    /**
+     * Collection representing the entities of this view.
+     * If you leave it blank it will be induced by your navigation
+     */
+    collection?: AdminCollection<M>;
+
+    /**
+     * Should update the URL when opening the dialog.
+     * Consider that if the collection that you provide is not defined in the base
+     * config of your `Rebase` component, you will not be able to recreate
+     * the state if copying the URL to a different window.
+     */
+    updateUrl?: boolean;
+
+    /**
+     * Callback when the entity is updated
+     * @param params
+     */
+    onUpdate?: (params: { entity: Entity<M> }) => void;
+
+    /**
+     * Callback when the dialog is closed
+     */
+    onClose?: () => void;
+
+    /**
+     * Should this panel close when saving
+     */
+    closeOnSave?: boolean;
+
+    /**
+     * Override some form properties
+     */
+    formProps?: Record<string, unknown>;
+
+    /**
+     * Allow the user to open the entity fullscreen
+     */
+    allowFullScreen?: boolean;
+
+    /**
+     * Pre-populate the form with these values when creating a new entity.
+     * Only applied when `entityId` is not set (i.e. the form is in "new" mode).
+     * Useful for actions that fetch data from an external source (e.g. a URL)
+     * and want to pre-fill the document before the user saves.
+     */
+    defaultValues?: Partial<M>;
+}
+
+/**
+ * Controller to open the side dialog displaying entity forms
+ * @group Hooks and utilities
+ */
+export interface SidePanelController {
+    /**
+     * Close the last panel
+     */
+    close: () => void;
+
+    /**
+     * Open a new entity sideDialog. By default, the collection and configuration
+     * of the view is fetched from the collections you have specified in the
+     * navigation.
+     * At least you need to pass the path of the entity you would like
+     * to edit. You can set a entityId if you would like to edit and existing one
+     * (or a new one with that id).
+     * @param props
+     */
+    open: <M extends Record<string, unknown> = Record<string, unknown>>(props: SidePanelBindingProps<M>) => void;
+
+    /**
+     * Replace the last open entity panel with the given one.
+     * @param props
+     */
+    replace: <M extends Record<string, unknown> = Record<string, unknown>>(props: SidePanelBindingProps<M>) => void;
+}

package/src/controllers/snackbar.ts

@@ -0,0 +1,29 @@
+
+/**
+ * Possible snackbar types
+ * @group Hooks and utilities
+ */
+export type SnackbarMessageType = "success" | "info" | "warning" | "error";
+
+/**
+ * Controller to display snackbars
+ * @group Hooks and utilities
+ */
+export interface SnackbarController {
+
+    /**
+     * Close the currently open snackbar
+     */
+    close: () => void;
+
+    /**
+     * Display a new snackbar. You need to specify the type and message.
+     * You can optionally specify a title
+     */
+    open: (props: {
+        type: SnackbarMessageType;
+        message: React.ReactNode;
+        autoHideDuration?: number;
+    }) => void;
+
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @rebasepro/admin-types — the React-flavoured half of the Rebase type surface.
+ *
+ * Everything here describes the admin panel: what a collection looks like on
+ * screen, the controllers the panel runs on, the props a custom field or view
+ * receives. It depends on @rebasepro/types and nothing in @rebasepro/types
+ * depends on it, which is what lets a BaaS install exist without React.
+ *
+ * If you are building a backend, you want @rebasepro/types.
+ */
+// Side-effect import: this is what adds `admin` back onto the core types.
+import "./augment";
+
+export * from "./types/property_options";
+export * from "./react_component_ref";
+export * from "./collections";
+export * from "./admin_collection";
+export * from "./rebase_context";
+export * from "./types";
+export * from "./controllers";

package/src/react_component_ref.ts

@@ -0,0 +1,52 @@
+import type React from "react";
+import type { ComponentLike, ComponentRef, LazyComponentRef } from "@rebasepro/types";
+
+/**
+ * `ComponentRef`, narrowed to real React types.
+ *
+ * Core's {@link ComponentRef} describes a component structurally
+ * ({@link ComponentLike}) so that `properties.ts` — and therefore the whole
+ * property model the backend reads — can live without React. The trade is that
+ * the return type is `unknown`, so a function returning something React cannot
+ * render type-checks there.
+ *
+ * Use this type wherever React genuinely exists: authoring a collection's admin
+ * options, and inside the admin packages. Assignments flow into core unchanged,
+ * because every member of this union is a member of that one.
+ */
+export type ReactComponentRef<P = any> =
+    | string
+    | LazyComponentRef<P>
+    | (() => Promise<{ default: React.ComponentType<P> }>)
+    | React.ComponentType<P>;
+
+/**
+ * The `ComponentLike` contract, as a signature the compiler has to keep true.
+ *
+ * The split rests on one claim: **every form a React component takes is
+ * assignable to `ComponentLike`** — function components, class components,
+ * `memo`, `forwardRef`. If that stopped holding, core's `ComponentRef` would
+ * quietly begin rejecting real components, and the failure would surface far away
+ * in whichever collection file happened to use the broken form.
+ *
+ * So the claim is not left to a test that someone has to run. This function's
+ * parameter and return types state it, and `pnpm typecheck` enforces it on every
+ * commit. It is also useful on its own: an explicit widening at the point where
+ * an authored component enters a collection config.
+ *
+ * @example
+ * import { MyField } from "./MyField";
+ * admin: { Field: asComponentRef(MyField) }
+ */
+export function asComponentRef<P>(component: React.ComponentType<P>): ComponentRef<P> {
+    return component;
+}
+
+/**
+ * The same contract in the other direction: a `ComponentLike` is only renderable
+ * once narrowed, and this is the single sanctioned place that narrowing is
+ * spelled out. `resolveComponentRef` in `@rebasepro/app` does the runtime half.
+ */
+export function asReactComponent<P>(component: ComponentLike<P>): React.ComponentType<P> {
+    return component as React.ComponentType<P>;
+}