@rebasepro/admin-types 0.10.1-canary.0

package/dist/react_component_ref.d.ts

@@ -0,0 +1,43 @@
+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 declare function asComponentRef<P>(component: React.ComponentType<P>): ComponentRef<P>;
+/**
+ * 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 declare function asReactComponent<P>(component: ComponentLike<P>): React.ComponentType<P>;

package/dist/rebase_context.d.ts

@@ -0,0 +1,68 @@
+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/dist/types/breadcrumbs.d.ts

@@ -0,0 +1,26 @@
+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/dist/types/builders.d.ts

@@ -0,0 +1,15 @@
+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/dist/types/component_overrides.d.ts

@@ -0,0 +1,196 @@
+import type React from "react";
+import type { Property } from "@rebasepro/types";
+import type { WhereFilterOp } from "@rebasepro/types";
+/**
+ * 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.AppBar" | "Shell.Drawer" | "Shell.DrawerNavigationItem" | "Shell.DrawerNavigationGroup" | "HomePage" | "HomePage.CollectionCard" | "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.Table" | "Collection.Card" | "Collection.EmptyState" | "Collection.Actions" | "Collection.FilterField" | "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;
+}
+/**
+ * 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;
+}
+/**
+ * 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/dist/types/entity_actions.d.ts

@@ -0,0 +1,105 @@
+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/dist/types/entity_link_builder.d.ts

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

package/dist/types/entity_views.d.ts

@@ -0,0 +1,95 @@
+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/dist/types/export_import.d.ts

@@ -0,0 +1,21 @@
+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/dist/types/formex.d.ts

@@ -0,0 +1,40 @@
+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>;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./breadcrumbs";
+export * from "./builders";
+export * from "./component_overrides";
+export * from "./entity_actions";
+export * from "./entity_link_builder";
+export * from "./entity_views";
+export * from "./export_import";
+export * from "./formex";
+export * from "./locales";
+export * from "./modify_collections";
+export * from "./plugins";
+export * from "./property_config";
+export * from "./slots";
+export * from "./translations";
+export * from "./user_management_delegate";

package/dist/types/locales.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @group Models
+ */
+export type Locale = "af" | "ar" | "arDZ" | "arMA" | "arSA" | "az" | "be" | "bg" | "bn" | "ca" | "cs" | "cy" | "da" | "de" | "el" | "enAU" | "enCA" | "enGB" | "enIN" | "enNZ" | "enUS" | "eo" | "es" | "et" | "eu" | "faIR" | "fi" | "fil" | "fr" | "frCA" | "frCH" | "gd" | "gl" | "gu" | "he" | "hi" | "hr" | "hu" | "hy" | "id" | "is" | "it" | "ja" | "ka" | "kk" | "kn" | "ko" | "lb" | "lt" | "lv" | "mk" | "ms" | "mt" | "nb" | "nl" | "nlBE" | "nn" | "pl" | "pt" | "ptBR" | "ro" | "ru" | "sk" | "sl" | "sr" | "srLatn" | "sv" | "ta" | "te" | "th" | "tr" | "ug" | "uk" | "uz" | "vi" | "zhCN" | "zhTW";

package/dist/types/modify_collections.d.ts

@@ -0,0 +1,5 @@
+import type { AdminCollection } from "@rebasepro/admin-types";
+export type ModifyCollectionProps = {
+    collection: AdminCollection;
+    parentPaths: string[];
+};