@rebasepro/cms-types 0.17.0-canary.0

package/src/controllers/index.ts

@@ -0,0 +1,10 @@
+export * from "./analytics_controller";
+export * from "./auth";
+export * from "./customization_controller";
+export * from "./dialogs_controller";
+export * from "./local_config_persistence";
+export * from "./navigation";
+export * from "./registry";
+export * from "./side_dialogs_controller";
+export * from "./side_panel_controller";
+export * from "./snackbar";

package/src/controllers/local_config_persistence.tsx

@@ -0,0 +1,22 @@
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+/**
+ * @group Models
+ */
+export type PartialCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>> = Partial<AdminCollection<M>>;
+
+/**
+ * This interface is in charge of defining the controller that persists
+ * modifications to a collection or collection, and retrieves them back from
+ * a data source, such as local storage or Firestore.
+ */
+export interface UserConfigurationPersistence {
+    onCollectionModified: <M extends Record<string, unknown> = Record<string, unknown>>(path: string, partialCollection: PartialCollectionConfig<M>) => void;
+    getCollectionConfig: <M extends Record<string, unknown> = Record<string, unknown>>(path: string) => PartialCollectionConfig<M>;
+    recentlyVisitedPaths: string[];
+    setRecentlyVisitedPaths: (paths: string[]) => void;
+    favouritePaths: string[];
+    setFavouritePaths: (paths: string[]) => void;
+    collapsedGroups: string[];
+    setCollapsedGroups: (paths: string[]) => void;
+}

package/src/controllers/navigation.ts

@@ -0,0 +1,288 @@
+import React from "react";
+import type { EntityReference } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+/**
+ * Controller that handles URL path building and resolution.
+ * @group Models
+ */
+export type UrlController = {
+    /**
+     * Default path under the navigation routes of the admin 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 admin 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 admin (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 {
+
+    /**
+     * admin 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.
+     *
+     * Two names are special: a group called `"Admin"` or `"Settings"` sinks to
+     * the bottom of the drawer, by string comparison on the name. That predates
+     * {@link pinToBottom} and still works, but rename the group — translate the
+     * label, say — and the ordering silently stops happening. Use
+     * `pinToBottom` for anything that is not literally one of those two words.
+     */
+    group?: string;
+
+    /**
+     * Sink this view's group to the bottom of the drawer, below the ordinary
+     * groups.
+     *
+     * What `group: "Settings"` has always done, said out loud. Setting it on
+     * any one view in a group pins the whole group, since the drawer orders
+     * groups and not individual views.
+     */
+    pinToBottom?: boolean;
+
+    /**
+     * 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[];
+    /**
+     * Icon for the group header, as a Lucide icon name (`"Users"`, `"CreditCard"`).
+     *
+     * It labels the group header and nothing more — the entries below keep their own
+     * icons either way. Only shown while the drawer is expanded, since a drawer
+     * collapsed to a rail hides the headers entirely.
+     */
+    icon?: 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,114 @@
+import { ReactNode } from "react";
+
+import type { CollectionConfigsBuilder, AppViewsBuilder } from "../types/builders";
+import type { EntityCustomView } from "../types/entity_views";
+import type { CollectionCustomView } from "../types/collection_views";
+import type { EntityAction } from "../types/entity_actions";
+import type { AppView, NavigationGroupMapping } from "./navigation";
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+/**
+ * Options to enable the built-in collection editor.
+ * When provided to `<RebaseCMS>`, 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 RebaseCMSConfig<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[];
+
+    /**
+     * Custom collection view modes available to every collection by `key`.
+     * A collection opts into one by naming that key in `admin.customViews`,
+     * the same way `entityViews` works.
+     */
+    collectionViews?: CollectionCustomView[];
+
+    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[];
+}
+
+/**
+ * Props of the `<RebaseAuth>` front-end route — what the sign-in screen renders.
+ *
+ * Named `RebaseAuthConfig` until it collided head-on with `RebaseAuthConfig` in
+ * `@rebasepro/server`, which is the *backend* auth configuration: JWT secrets,
+ * OAuth providers, password hooks, the users collection. Two unrelated shapes
+ * under one name, one of them exported from a package whose whole job is to be
+ * imported alongside the other.
+ */
+export interface RebaseAuthViewConfig {
+    loginView?: ReactNode;
+}
+
+export interface RebaseRegistryController {
+    // Current state
+    cmsConfig: RebaseCMSConfig | null;
+    studioConfig: RebaseStudioConfig | null;
+    authConfig: RebaseAuthViewConfig | null;
+
+    // Registration functions
+    registerAdmin: (config: RebaseCMSConfig) => void;
+    unregisterAdmin: () => void;
+
+    registerStudio: (config: RebaseStudioConfig) => void;
+    unregisterStudio: () => void;
+
+    registerAuth: (config: RebaseAuthViewConfig) => 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/cms-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,51 @@
+
+/**
+ * Possible snackbar types
+ * @group Hooks and utilities
+ */
+export type SnackbarMessageType = "success" | "info" | "warning" | "error";
+
+/**
+ * A single button rendered inside a snackbar.
+ *
+ * The reason snackbars have one: undo-after-mutation is the core interaction of
+ * any queue or triage screen, and the window in which "undo" means anything is
+ * exactly the window the snackbar is on screen. Without a slot here every such
+ * view has to build its own strip somewhere else on the page, at which point the
+ * confirmation and the way to reverse it are two different pieces of UI.
+ *
+ * The snackbar dismisses itself after `onClick`, since the action it was
+ * offering has been taken.
+ *
+ * @group Hooks and utilities
+ */
+export interface SnackbarAction {
+    label: string;
+    onClick: () => void;
+}
+
+/**
+ * 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;
+        title?: string;
+        message: React.ReactNode;
+        autoHideDuration?: number;
+        /** A button rendered alongside the message — typically "Undo". */
+        action?: SnackbarAction;
+    }) => void;
+
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @rebasepro/cms-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";