@rebasepro/admin-types 0.10.1-canary.0

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 CMS
+     */
+    urlController?: import("./controllers/navigation").UrlController;
+
+    /**
+     * Controller to handle simple confirmation and alert dialogs
+     */
+    dialogsController?: import("./controllers/dialogs_controller").DialogsController;
+
+    /**
+     * Controller for CMS 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,27 @@
+export interface BreadcrumbEntry {
+    title: string;
+    url: string;
+    /**
+     * Optional entity count for collection breadcrumbs.
+     * - undefined: not applicable (e.g., entity breadcrumb, custom view)
+     * - null: loading
+     * - number: loaded count
+     */
+    count?: number | null;
+    /**
+     * Unique identifier for this breadcrumb (e.g., collection path).
+     * Used to update count without replacing entire breadcrumb array.
+     */
+    id?: string;
+}
+
+export interface BreadcrumbsController {
+    breadcrumbs: BreadcrumbEntry[];
+    set: (props: {
+        breadcrumbs: BreadcrumbEntry[];
+    }) => void;
+    /**
+     * Update the count for a specific breadcrumb by ID.
+     */
+    updateCount: (id: string, count: number | null | undefined) => 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/admin-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/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,127 @@
+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/admin-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
+     */
+    icon?: React.ReactElement;
+
+    /**
+     * 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;
+
+};

package/src/types/entity_link_builder.ts

@@ -0,0 +1,8 @@
+import { Entity } from "@rebasepro/types";
+
+/**
+ * @group Models
+ */
+export type EntityLinkBuilder<M extends Record<string, unknown> = Record<string, unknown>> = ({ entity }: {
+    entity: Entity<M>
+}) => string;

package/src/types/entity_views.tsx

@@ -0,0 +1,114 @@
+import React from "react";
+import type { Entity, EntityValues } from "@rebasepro/types";
+
+import type { FormexController } from "./formex";
+import type { ComponentRef } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/admin-types";
+
+/**
+ * Context passed to custom fields and entity views.
+ * @group Form custom fields
+ */
+export interface FormContext<M extends Record<string, unknown> = Record<string, unknown>> {
+
+    /**
+     * Current values of the entity
+     */
+    values: M;
+
+    /**
+     * Update the value of a field
+     */
+    setFieldValue: (key: string, value: unknown, shouldValidate?: boolean) => void;
+
+    /**
+     * Quietly persist the entity to the database without any UI feedback
+     * (no validation, no snackbar, no form reset).
+     * Use this for programmatic/background saves from custom views.
+     */
+    save: (values: M) => void;
+
+    /**
+     * Submit the form — validates, saves, resets the form, and shows
+     * a success snackbar. This is what the Save button calls.
+     * Use this from custom views when you want the full "user saved" experience.
+     */
+    submit: () => void;
+
+    /**
+     * Collection of the entity being modified
+     */
+    collection?: AdminCollection<M>;
+
+    /**
+     * Entity id, it can be undefined if it's a new entity
+     */
+    entityId?: string | number;
+
+    /**
+     * Path this entity is located at
+     */
+    path?: string;
+
+    status: "new" | "existing" | "copy";
+
+    entity?: Entity<M>;
+
+    savingError?: Error;
+
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+
+    /**
+     * The underlying formex controller that powers the form.
+     */
+    formex: FormexController<M>;
+
+    disabled: boolean;
+
+    /**
+     * Whether the form context is in read-only detail view mode.
+     * Custom entity views can use this to adjust their rendering.
+     */
+    readOnly?: boolean;
+}
+
+export type EntityCustomView<M extends Record<string, unknown> = Record<string, unknown>> = {
+    key: string;
+    name: string;
+    icon?: string | React.ReactNode;
+    tabComponent?: React.ReactNode;
+    includeActions?: boolean | "bottom";
+    Builder?: ComponentRef<EntityCustomViewParams<M>>;
+    position?: "start" | "end";
+};
+
+/**
+ * Configuration to replace the default entity form with a custom component.
+ * The Builder receives the same props as entity view tabs (entity, formContext, etc.)
+ * and has full control over the UI.
+ *
+ * The form tab still appears in the tab bar but renders your Builder
+ * instead of the auto-generated field form.
+ *
+ * @group Models
+ */
+export type FormViewConfig<M extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * Custom component that replaces the default form.
+     */
+    Builder: ComponentRef<EntityCustomViewParams<M>>;
+    /**
+     * If true, the save/delete action bar is rendered alongside the custom view.
+     * Defaults to true.
+     */
+    includeActions?: boolean;
+};
+
+export interface EntityCustomViewParams<M extends Record<string, unknown> = Record<string, unknown>> {
+    collection: AdminCollection<M>;
+    entity?: Entity<M>;
+    modifiedValues?: EntityValues<M>;
+    formContext: FormContext<M>;
+    parentCollectionSlugs?: string[];
+    parentEntityIds?: string[];
+}

package/src/types/export_import.ts

@@ -0,0 +1,26 @@
+import type { Entity } from "@rebasepro/types";
+import type { User } from "@rebasepro/types";
+import type { RebaseContext } from "../rebase_context";
+
+/**
+ * You can use this configuration to add additional fields to the data
+ * exports
+ * @group Models
+ */
+export interface ExportConfig<USER extends User = User> {
+    additionalFields: ExportMappingFunction<USER>[];
+}
+
+/**
+ * @group Models
+ */
+export interface ExportMappingFunction<USER extends User = User> {
+    key: string;
+    builder: ({
+        entity,
+        context
+    }: {
+        entity: Entity,
+        context: RebaseContext<USER>
+    }) => Promise<string> | string;
+}

package/src/types/formex.ts

@@ -0,0 +1,45 @@
+import React, { FormEvent } from "react";
+
+export type FormexController<T = unknown> = {
+    values: T;
+    initialValues: T;
+    setValues: (values: T) => void;
+    setFieldValue: (key: string, value: unknown, shouldValidate?: boolean) => void;
+    touched: Record<string, boolean>;
+    setFieldTouched: (key: string, touched: boolean, shouldValidate?: boolean) => void;
+    setTouched: (touched: Record<string, boolean>) => void;
+    dirty: boolean;
+    setDirty: (dirty: boolean) => void;
+    setSubmitCount: (submitCount: number) => void;
+    errors: Record<string, string>;
+    setFieldError: (key: string, error?: string) => void;
+    handleChange: (event: React.SyntheticEvent) => void,
+    handleBlur: (event: React.FocusEvent) => void,
+    handleSubmit: (event?: FormEvent<HTMLFormElement>) => void;
+    validate: () => void;
+    resetForm: (props?: FormexResetProps<T>) => void;
+    submitCount: number;
+    isSubmitting: boolean;
+    setSubmitting: (isSubmitting: boolean) => void;
+    isValidating: boolean;
+    /**
+     * The version of the form. This is incremented every time the form is reset
+     * or the form is submitted.
+     */
+    version: number;
+
+    debugId?: string;
+
+    undo: () => void;
+    redo: () => void;
+
+    canUndo: boolean;
+    canRedo: boolean;
+}
+
+export type FormexResetProps<T = unknown> = {
+    values?: T;
+    submitCount?: number;
+    errors?: Record<string, string>;
+    touched?: Record<string, boolean>;
+};