@rebasepro/cms-types 0.17.0-canary.0

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>;
+}

package/src/rebase_context.ts

@@ -0,0 +1,81 @@
+import type { AnalyticsController } from "./controllers/analytics_controller";
+import type { AuthController } from "./controllers/auth";
+import type { UserConfigurationPersistence } from "./controllers/local_config_persistence";
+import type { DatabaseAdmin } from "@rebasepro/types";
+import type { RebaseCallContext } from "@rebasepro/types";
+import type { User } from "@rebasepro/types";
+
+/**
+ * Context that includes the internal controllers and contexts used by the app.
+ * Some controllers and context included in this context can be accessed
+ * directly from their respective hooks.
+ * @group Hooks and utilities
+ * @see useRebaseContext
+ */
+export type RebaseContext<USER extends User = User, AuthControllerType extends AuthController<USER> = AuthController<USER>> = RebaseCallContext<USER> & {
+
+    authController: AuthControllerType;
+
+    /**
+     * Controller mapping strings to collections
+     */
+    collectionRegistryController?: import("@rebasepro/types").CollectionRegistryController;
+
+    /**
+     * Controller for navigation state
+     */
+    navigationStateController?: import("./controllers/navigation").NavigationStateController;
+
+    /**
+     * Controller for side dialogs (side sheets)
+     */
+    sideDialogsController?: import("./controllers/side_dialogs_controller").SideDialogsController;
+
+    /**
+     * Controller to open the side panel displaying entity forms
+     */
+    sidePanelController?: import("./controllers/side_panel_controller").SidePanelController;
+
+    /**
+     * Controller resolving URLs in the admin
+     */
+    urlController?: import("./controllers/navigation").UrlController;
+
+    /**
+     * Controller to handle simple confirmation and alert dialogs
+     */
+    dialogsController?: import("./controllers/dialogs_controller").DialogsController;
+
+    /**
+     * Controller for admin customization
+     */
+    customizationController?: import("./controllers/customization_controller").CustomizationController;
+
+    /**
+     * Controller for effective role
+     */
+    effectiveRoleController?: { effectiveRole: string | null, setEffectiveRole: (role: string | null) => void };
+
+    /**
+     * Use this controller to access data stored in the browser for the user
+     */
+    userConfigPersistence?: UserConfigurationPersistence;
+
+    /**
+     * Callback to send analytics events
+     */
+    analyticsController?: AnalyticsController;
+
+
+    /**
+     * Administrative database operations (SQL, schema discovery).
+     * Only available in developer/admin contexts.
+     */
+    databaseAdmin?: DatabaseAdmin;
+
+    /**
+     * Controller for snackbars
+     */
+    snackbarController?: import("./controllers/snackbar").SnackbarController;
+
+};

package/src/types/breadcrumbs.ts

@@ -0,0 +1,16 @@
+export interface BreadcrumbEntry {
+    title: string;
+    url: string;
+    /**
+     * Stable identifier for this entry (e.g., collection path). Lets the
+     * provider tell a rebuilt-but-unchanged trail from a real navigation.
+     */
+    id?: string;
+}
+
+export interface BreadcrumbsController {
+    breadcrumbs: BreadcrumbEntry[];
+    set: (props: {
+        breadcrumbs: BreadcrumbEntry[];
+    }) => void;
+}

package/src/types/builders.ts

@@ -0,0 +1,18 @@
+import type { AuthController } from "../controllers/auth";
+import type { RebaseData } from "@rebasepro/types";
+import type { User } from "@rebasepro/types";
+
+import type { AppView } from "../controllers/navigation";
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+export type CollectionConfigsBuilder<EC extends AdminCollection = AdminCollection> = (params: {
+    user: User | null,
+    authController: AuthController,
+    data: RebaseData
+}) => EC[] | Promise<EC[]>;
+
+export type AppViewsBuilder = (params: {
+    user: User | null,
+    authController: AuthController,
+    data: RebaseData
+}) => AppView[] | Promise<AppView[]>;

package/src/types/collection_views.tsx

@@ -0,0 +1,125 @@
+import React from "react";
+import type { Entity, ComponentRef } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+import type { CollectionSize, EntityTableController, SelectionController, ViewMode } from "../collections";
+
+/**
+ * A custom rendering of *one* collection's rows, selectable from the same view
+ * switcher as list / table / cards / kanban.
+ *
+ * This is the middle scope of custom UI. The other two already exist and this
+ * is not a substitute for either:
+ *
+ * - one record → `entityViews` (the entity tab strip)
+ * - one collection's rows, rendered differently → **this**
+ * - a workflow spanning several collections → `AppView` (`views={[…]}`)
+ *
+ * A view mode is another rendering of the *same query*. The `Builder` is handed
+ * the live {@link EntityTableController}, so it inherits the collection's
+ * filters, search string, sort, pagination, role checks and entity side panel
+ * for free — which is the whole reason to declare one instead of an `AppView`.
+ *
+ * If your component ignores `tableController` and fetches tables of its own, it
+ * wants to be an `AppView`: the toolbar above it — search box, filters, the
+ * record count — would be describing a query the view does not render.
+ *
+ * @group Models
+ */
+export type CollectionCustomView<M extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Identifies this view. It is what `defaultViewMode` and `enabledViews`
+     * name, and what the `__view` URL param carries, so it must not collide
+     * with a built-in mode ("list", "table", "cards", "kanban").
+     *
+     * Treat it as frozen once shipped: users have it persisted in their saved
+     * collection config and in bookmarked URLs.
+     */
+    key: string;
+
+    /** Label shown in the view switcher. */
+    name: string;
+
+    /**
+     * Icon shown beside the name, as a `lucide-react` icon name (e.g. `"Map"`)
+     * or a rendered node. A name is what the collection editor can store.
+     */
+    icon?: string | React.ReactNode;
+
+    /**
+     * The component that renders the rows.
+     */
+    Builder: ComponentRef<CollectionCustomViewParams<M>>;
+
+    /**
+     * How clicking a record should present it, overriding what
+     * `resolveOpenEntityMode` would otherwise derive from the view mode.
+     * Defaults to `"side_panel"`, which is what the board uses: a custom view
+     * usually owns its whole surface and should keep it.
+     */
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+
+    /**
+     * Whether the size selector applies to this view. Off by default — most
+     * custom views have no notion of row height.
+     */
+    sizeable?: boolean;
+};
+
+/**
+ * What a {@link CollectionCustomView}'s `Builder` receives.
+ *
+ * This is the same set the built-in view bindings are given, so a custom view
+ * starts from parity with them.
+ *
+ * @group Models
+ */
+export interface CollectionCustomViewParams<M extends Record<string, unknown> = Record<string, unknown>> {
+    /** The collection being rendered, fully resolved. */
+    collection: AdminCollection<M>;
+
+    /**
+     * The live query: rows, loading state, pagination, and the filter / sort /
+     * search state shared with the toolbar. Read rows from here rather than
+     * fetching — that is what keeps the toolbar honest.
+     */
+    tableController: EntityTableController<M>;
+
+    /** Full path of the collection, e.g. `users/1234/addresses`. */
+    path: string;
+
+    /** Parent path segments, when this is a subcollection. */
+    parentCollectionSlugs?: string[];
+    parentEntityIds?: string[];
+
+    /**
+     * Open a record. Routes through the collection's resolved
+     * `openEntityMode`, so the side panel, split view and full-screen form all
+     * work without the view knowing which one it got.
+     */
+    onEntityClick?: (entity: Entity<M>) => void;
+
+    /** Create a record. Undefined when the user may not create. */
+    onNewClick?: () => void;
+
+    /** Whether the current user may create records in this collection. */
+    canCreate?: boolean;
+
+    selectionController?: SelectionController<M>;
+    selectionEnabled?: boolean;
+
+    /** Records to draw as highlighted, e.g. the one open in the side panel. */
+    highlightedEntities?: Entity<M>[];
+
+    /** Records deleted in this session, for optimistic removal. */
+    deletedEntities?: Entity<M>[];
+
+    /** The shared empty state, so a custom view matches the built-ins. */
+    emptyComponent?: React.ReactNode;
+
+    /** Set when the view declared `sizeable`. */
+    size?: CollectionSize;
+
+    /** The mode this view was resolved to, for views that render several. */
+    viewMode?: ViewMode;
+}

package/src/types/component_overrides.ts

@@ -0,0 +1,244 @@
+import type React from "react";
+import type { Property } from "@rebasepro/types";
+import type { WhereFilterOp } from "@rebasepro/types";
+
+// ── Scoped component name unions ──────────────────────────────────────
+
+/**
+ * Components that can only be overridden at the **app level** via the
+ * `components` prop on `<Rebase>`.
+ *
+ * These are shell-level / global components that exist outside of any
+ * specific collection context.
+ *
+ * @group Component Overrides
+ */
+export type AppComponentName =
+    // ── Shell / Layout ──
+    | "Shell.AppBar"
+    | "Shell.Drawer"
+    | "Shell.DrawerNavigationItem"
+    | "Shell.DrawerNavigationGroup"
+
+    // ── Home Page ──
+    | "HomePage"
+    | "HomePage.CollectionCard"
+
+    // ── Auth ──
+    | "Auth.LoginView";
+
+/**
+ * Components that can be overridden at the **collection level**
+ * (on an individual collection definition) or at the **app level**
+ * (as a default for all collections).
+ *
+ * When set at the app level, these act as defaults. When set on a
+ * specific collection, they override the app-level default for that
+ * collection only.
+ *
+ * @group Component Overrides
+ */
+export type CollectionComponentName =
+    // ── Collection View ──
+    | "Collection.View"
+    | "Collection.Table"
+    | "Collection.Card"
+    | "Collection.EmptyState"
+    | "Collection.Actions"
+    | "Collection.FilterField"
+
+    // ── Entity / Form ──
+    | "Entity.Form"
+    | "EditView.FormActions"
+    | "DetailView"
+    | "Entity.SidePanel"
+    | "EntityPreview"
+    | "Entity.MissingReference";
+
+/**
+ * All overridable component names across all scopes.
+ * @group Component Overrides
+ */
+export type OverridableComponentName = AppComponentName | CollectionComponentName;
+
+/**
+ * Props received by a filter field component — whether it is a built-in
+ * per-type field, a property-level replacement (`property.ui.Filter`), or a
+ * `"Collection.FilterField"` override.
+ *
+ * The `operators` list is **already resolved**: it is the intersection of the
+ * engine's {@link DataSourceCapabilities.filterOperators}, the property-type
+ * defaults, and any `property.ui.filterOperators` narrowing. A custom field
+ * should only offer operators from this list — anything else may throw at
+ * query time on engines that cannot execute it.
+ *
+ * @example
+ * ```tsx
+ * function MyStatusFilter({ value, setValue, operators }: FilterFieldBindingProps) {
+ *     return (
+ *         <select
+ *             value={value?.[1] as string ?? ""}
+ *             onChange={e => setValue(e.target.value ? ["==", e.target.value] : undefined)}>
+ *             <option value="">Any</option>
+ *             <option value="active">Active</option>
+ *             <option value="archived">Archived</option>
+ *         </select>
+ *     );
+ * }
+ * ```
+ *
+ * @group Component Overrides
+ */
+export interface FilterFieldBindingProps {
+    /** Key of the property being filtered (the column id). */
+    propertyKey: string;
+
+    /**
+     * The resolved property. For array properties this is the **item**
+     * property (`property.of`), with `isArray` set to true.
+     */
+    property: Property;
+
+    /** True when the underlying property is an array of `property`. */
+    isArray: boolean;
+
+    /**
+     * Operators this field may offer, already narrowed by engine
+     * capabilities, property-type defaults, and `property.ui.filterOperators`.
+     */
+    operators: readonly WhereFilterOp[];
+
+    /** Current filter condition for this property, if any. */
+    value?: [WhereFilterOp, unknown];
+
+    /** Set (or clear, with `undefined`) the filter condition. */
+    setValue: (value?: [WhereFilterOp, unknown]) => void;
+
+    /** Display title for the field (usually the property name). */
+    title?: string;
+
+    /**
+     * Coordination flags used by fields that open their own dialogs
+     * (e.g. the reference picker hides the parent filters dialog).
+     */
+    hidden?: boolean;
+    setHidden?: (hidden: boolean) => void;
+}
+
+// ── Override entry ────────────────────────────────────────────────────
+
+/**
+ * A single component override entry.
+ *
+ * - **Eject mode** (default): Your component fully replaces the built-in one.
+ *   It receives the same props as the original.
+ *
+ * - **Wrap mode** (`wrap: true`): Your component wraps the original. The
+ *   built-in component is passed as `OriginalComponent` in props, so you can
+ *   render it inside your custom layout/logic.
+ *
+ * @example
+ * ```tsx
+ * // Eject — full replacement
+ * { Component: MyCustomAppBar }
+ *
+ * // Wrap — augment the original
+ * {
+ *     Component: ({ OriginalComponent, ...props }) => (
+ *         <div>
+ *             <MyBanner />
+ *             <OriginalComponent {...props} />
+ *         </div>
+ *     ),
+ *     wrap: true
+ * }
+ * ```
+ *
+ * @group Component Overrides
+ */
+export interface ComponentOverride<P = Record<string, unknown>> {
+    /**
+     * The replacement component. Receives the same props as the built-in
+     * component it replaces.
+     *
+     * When `wrap` is true, an additional `OriginalComponent` prop is injected
+     * containing the default component, allowing you to render it within
+     * your custom wrapper.
+     */
+    Component: React.ComponentType<P>;
+
+    /**
+     * When true, the original default component is injected as the
+     * `OriginalComponent` prop into your Component, enabling the
+     * wrapping pattern (similar to Docusaurus's `--wrap` swizzle mode).
+     *
+     * When false or omitted, your component fully replaces the default
+     * (similar to Docusaurus's `--eject` swizzle mode).
+     *
+     * @default false
+     */
+    wrap?: boolean;
+}
+
+// ── Override maps by scope ────────────────────────────────────────────
+
+/**
+ * Collection-scoped overrides. Only collection-level components
+ * can be overridden here.
+ *
+ * Set on a collection's `components` field to customize
+ * components for that specific collection.
+ *
+ * @example
+ * ```tsx
+ * const productsCollection = {
+ *     name: "Products",
+ *     slug: "products",
+ *     components: {
+ *         "Entity.Form": { Component: ProductForm },
+ *         "Collection.EmptyState": { Component: ProductsEmptyState },
+ *         "Collection.Card": { Component: ProductCard },
+ *     }
+ * };
+ * ```
+ *
+ * @group Component Overrides
+ */
+export type CollectionComponentOverrideMap = {
+    [K in CollectionComponentName]?: ComponentOverride;
+};
+
+/**
+ * App-level overrides. Includes both app-only components (Shell, HomePage, Auth)
+ * and collection-level components (as defaults for all collections).
+ *
+ * Pass this to the `components` prop on `<Rebase>`.
+ *
+ * Collection-level components set here act as **defaults** — they apply to all
+ * collections unless a specific collection overrides them in its own
+ * `components`.
+ *
+ * @example
+ * ```tsx
+ * <Rebase
+ *     client={client}
+ *     components={{
+ *         // App-level: only available here
+ *         "Shell.AppBar": { Component: MyAppBar },
+ *         "HomePage": { Component: MyDashboard },
+ *
+ *         // Collection defaults: apply to ALL collections
+ *         "EditView.FormActions": {
+ *             Component: MyFormActions,
+ *             wrap: true
+ *         },
+ *         "Collection.EmptyState": { Component: MyEmptyState },
+ *     }}
+ * />
+ * ```
+ *
+ * @group Component Overrides
+ */
+export type ComponentOverrideMap = {
+    [K in OverridableComponentName]?: ComponentOverride;
+};

package/src/types/entity_actions.tsx

@@ -0,0 +1,134 @@
+import React from "react";
+import type { Entity } from "@rebasepro/types";
+
+import type { SelectionController } from "../collections";
+import type { FormContext } from "./entity_views";
+import type { User } from "@rebasepro/types";
+import type { RebaseContext } from "../rebase_context";
+import type { SidePanelController } from "../controllers/side_panel_controller";
+import type { AdminCollection } from "@rebasepro/cms-types";
+
+/**
+ * A entity action is a custom action that can be performed on a entity.
+ * They are displayed in the entity view and in the collection view.
+ */
+export interface EntityAction<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
+    /**
+     * Title of the action
+     */
+    name: string;
+
+    /**
+     * Key of the action. You only need to provide this if you want to
+     * override the default actions, or if you are not passing the action
+     * directly to the `entityActions` prop of a collection.
+     * You can define your actions at the app level, in which case you
+     * must provide a key.
+     * The default actions are:
+     * - edit
+     * - delete
+     * - copy
+     */
+    key?: string;
+
+    /**
+     * Icon of the action: a Lucide icon name (`"FileBarChart"`) or an element.
+     *
+     * The name form is what lets a collection declare one from the config package,
+     * which is plain `.ts` with no React dependency — an element would drag the
+     * whole UI layer into a backend that only loads the collection for its schema.
+     * It also matches how every other icon in a collection is written
+     * (`admin.icon`, `entityViews[].icon`), which were already strings while this
+     * one alone was not.
+     */
+    icon?: React.ReactElement | string;
+
+    /**
+     * Callback when the action is clicked
+     * @param props
+     */
+    onClick(props: EntityActionClickProps<M, USER>): Promise<void> | void;
+
+    /**
+     * Optional callback in case you want to disable the action
+     * @param props
+     */
+    isEnabled?(props: EntityActionClickProps<M, USER>): boolean;
+
+    /**
+     * When true, this action is rendered inline on each row in the list view.
+     * By default, entity actions only appear in the table view and entity form.
+     * Use this for actions that should be easily accessible regardless of view mode.
+     */
+    showActionsInListView?: boolean;
+
+    /**
+     * Show this action collapsed in the menu of the collection view.
+     * Defaults to true
+     * If false, the action will be shown in the menu
+     */
+    collapsed?: boolean;
+
+    /**
+     * Show this action in the form, defaults to true
+     */
+    includeInForm?: boolean;
+
+}
+
+export type EntityActionClickProps<M extends Record<string, unknown>, USER extends User = User> = {
+    entity?: Entity<M>;
+    context?: RebaseContext<USER>;
+
+    path?: string;
+    collection?: AdminCollection<M>;
+
+    /**
+     * Optional form context, present if the action is being called from a form.
+     * This allows you to access the form state and methods, including modifying the form values.
+     */
+    formContext?: FormContext;
+
+    /**
+     * Present if this actions is being called from a side dialog only
+     */
+    sidePanelController?: SidePanelController;
+
+    /**
+     * Is the action being called from the collection view or from the entity form view?
+     */
+    view: "collection" | "form";
+
+    /**
+     * If the action is rendered in the form, is it open in a side panel or full screen?
+     */
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+
+    /**
+     * Optional selection controller, present if the action is being called from a collection view
+     */
+    selectionController?: SelectionController;
+
+    /**
+     * Optional highlight function to highlight the entity in the collection view
+     * @param entity
+     */
+    highlightEntity?: (entity: Entity<Record<string, unknown>>) => void;
+
+    /**
+     * Optional unhighlight function to remove the highlight from the entity in the collection view
+     * @param entity
+     */
+    unhighlightEntity?: (entity: Entity<Record<string, unknown>>) => void;
+
+    /**
+     * Optional function to navigate back (e.g. when deleting a entity or navigating from a form)
+     */
+    navigateBack?: () => void;
+
+    /**
+     * Callback to be called when the collection changes, e.g. after a entity is deleted or created.
+     */
+    onCollectionChange?: () => void;
+
+};