@rebasepro/cms-types 0.17.0-canary.0

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,112 @@
+import React from "react";
+import type { Entity } from "@rebasepro/types";
+import type { SelectionController } from "../collections.js";
+import type { FormContext } from "./entity_views.js";
+import type { User } from "@rebasepro/types";
+import type { RebaseContext } from "../rebase_context.js";
+import type { SidePanelController } from "../controllers/side_panel_controller.js";
+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;
+};

package/dist/types/entity_display.d.ts

@@ -0,0 +1,148 @@
+/**
+ * How a record shows up: its title, image, subtitle, status, date and tags.
+ *
+ * Every surface that draws a record draws some subset of these six roles. A list
+ * row is image + title + subtitle + status + date; a card is the same with the
+ * image on top; a board card drops the image; a reference picker is title +
+ * subtitle; a page heading is the title alone. The roles are stable — what fills
+ * them is not.
+ *
+ * Before this block, the roles were derived and only derived. `titleProperty`
+ * was the single exception, and it could only ever name a property of the
+ * collection: seven separate implementations read that key, disagreed about the
+ * fallback, and none of them could await. (It is gone now — `display.title`
+ * replaced it outright.) The other five roles could not be
+ * stated at all — the image was whichever storage property came first, the
+ * status whichever enum, the date whichever timestamp. Right often enough to
+ * feel automatic, and wrong with no way to say so.
+ *
+ * So: one mechanism, six roles, two forms each.
+ *
+ * ```ts
+ * admin: {
+ *     display: {
+ *         title: "name",                       // a property path
+ *         image: "photos.0",                   // a dotted path
+ *         subtitle: ({ entity }) =>            // computed
+ *             `${entity.values.city}, ${entity.values.country}`,
+ *         status: async ({ entity, context }) => {   // and may be async
+ *             const latest = await context.data.audits.get(`${entity.id}/latest`);
+ *             return latest?.state;
+ *         }
+ *     }
+ * }
+ * ```
+ *
+ * Anything left out is derived exactly as it is today, so an existing collection
+ * renders identically, and a collection that needs one role fixed states that
+ * one role.
+ */
+import type { Entity, User } from "@rebasepro/types";
+import type { RebaseContext } from "../rebase_context.js";
+/**
+ * What a resolver is handed.
+ *
+ * The whole {@link RebaseContext}, matching `AdditionalFieldDelegate.value` and
+ * `EntityAction.onClick` — so a resolver can reach `context.data` and
+ * `context.client` and read anything the panel can read, including a document in
+ * a subcollection that the entity itself never loads.
+ */
+export type EntityDisplayResolverParams<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = {
+    entity: Entity<M>;
+    context: RebaseContext<USER>;
+};
+/**
+ * Computes what fills one display role for one record.
+ *
+ * May be async. While a promise is in flight the surface shows the derived value
+ * and swaps the resolved one in when it lands — a title is never a spinner.
+ * Results are cached per record and per role, and concurrent calls for the same
+ * pair share one execution, so a list of fifty rows resolves each row once
+ * rather than once per render.
+ *
+ * Return `undefined` when this record has nothing for this role. Do not return a
+ * placeholder: the surface's own fallback is better informed than the resolver
+ * is about what belongs there instead — a heading wants the collection's
+ * singular name, a link wants the id.
+ *
+ * A resolver that throws is treated as `undefined` and logged once. A title that
+ * cannot be fetched must not take down the row that shows it.
+ */
+export type EntityDisplayResolver<M extends Record<string, unknown> = Record<string, unknown>, T = unknown, USER extends User = User> = {
+    /**
+     * Declared as a *method* and then indexed back out, which is the only way to
+     * write a standalone function type whose parameters stay bivariant.
+     *
+     * Not a style choice. `AdminCollectionOptions<M>` has to remain assignable
+     * to `AdminCollectionOptions<Record<string, unknown>>` — every consumer that
+     * takes a collection it did not author depends on it, and losing it breaks
+     * `defineCollection`'s own overloads. A resolver takes `Entity<M>` in
+     * parameter position, so written as `(params) => …` it makes the entire
+     * admin block invariant in `M`, and a typed collection stops being usable as
+     * a collection. Method syntax is bivariant under `strictFunctionTypes`; the
+     * sibling callbacks (`EntityAction.onClick`, `AdditionalFieldDelegate.value`)
+     * are all written this way, and `packages/types/__tests__/bivariance` is the
+     * record of finding it out the hard way.
+     */
+    resolve(params: EntityDisplayResolverParams<M, USER>): T | undefined | Promise<T | undefined>;
+}["resolve"];
+/**
+ * Where one display role gets its value: a property path on this collection, or
+ * a resolver that computes it.
+ *
+ * The path arm is checked against `M` and read with `getValueInPath`, so
+ * `"profile.displayName"` is as valid as `"title"`. It also keeps the property's
+ * own rendering — an enum status stays a coloured chip, a date stays formatted,
+ * a storage path stays a thumbnail — which a resolver returning a bare string
+ * cannot. Prefer the path whenever the value is on the record.
+ *
+ * `Path` is a type parameter rather than `PropertyPath<M>` directly, so this
+ * module does not import from `admin_collection`, which imports it.
+ */
+export type EntityDisplaySource<Path extends string, M extends Record<string, unknown> = Record<string, unknown>, T = unknown, USER extends User = User> = Path | EntityDisplayResolver<M, T, USER>;
+/**
+ * The six roles, and what may fill each.
+ *
+ * The value types describe what the renderers accept, not what a resolver must
+ * produce exactly: a `date` resolver may return a `Date`, an ISO string or an
+ * epoch number, and `tags` takes a single string as shorthand for one tag. A
+ * property path is not constrained by them at all — the property's own type
+ * decides how it renders.
+ */
+export type EntityDisplay<Path extends string = string, M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = {
+    /**
+     * What the record is called: the heading, the breadcrumb, the row, and the
+     * label of every relation chip and reference that points at it.
+     */
+    title?: EntityDisplaySource<Path, M, string, USER>;
+    /**
+     * The line under the title — a short description, a location, a summary.
+     */
+    subtitle?: EntityDisplaySource<Path, M, string, USER>;
+    /**
+     * The record's picture. A storage path or a URL: the same two things a
+     * `storage` property holds, so a resolver may return either.
+     */
+    image?: EntityDisplaySource<Path, M, string, USER>;
+    /**
+     * The state chip — published, archived, paid. Rendered with the enum's own
+     * colour when it comes from an enum property.
+     */
+    status?: EntityDisplaySource<Path, M, string, USER>;
+    /**
+     * The timestamp a row is stamped with, usually when it last changed.
+     */
+    date?: EntityDisplaySource<Path, M, Date | string | number, USER>;
+    /**
+     * Free chips beside the status: labels, categories, topics. A single string
+     * is accepted as shorthand for one tag.
+     */
+    tags?: EntityDisplaySource<Path, M, string[] | string, USER>;
+};
+/**
+ * The roles as data, so every consumer iterates the same list instead of
+ * repeating it — the mistake that let `titleProperty` grow seven readers.
+ */
+export declare const ENTITY_DISPLAY_ROLES: readonly ["title", "subtitle", "image", "status", "date", "tags"];
+/** One of the six display roles. */
+export type EntityDisplayRole = typeof ENTITY_DISPLAY_ROLES[number];

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,115 @@
+import React from "react";
+import type { Entity, EntityValues } from "@rebasepro/types";
+import type { FormexController } from "./formex.js";
+import type { ComponentRef } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/cms-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;
+    /**
+     * A save is in flight. Covers the autosave debounce too, which `formex`
+     * cannot report because it never goes through `handleSubmit`.
+     *
+     * The identity bar reads this to label its Save button, which is what
+     * replaced the unlabelled floating status circle in the form.
+     */
+    isSaving?: 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>>;
+    /**
+     * Which side of the record's own tab this one sits on.
+     *
+     * `"end"` (the default) puts it after the record and before the
+     * subcollections, which is where an extra reading of a row belongs.
+     *
+     * `"start"` puts it *before* the record — the cover of an entity: a
+     * read-only summary an operator opens the row to see, with the form that
+     * edits it one tab to the right. Pair it with
+     * {@link AdminCollectionOptions.defaultSelectedView}, or the strip will open
+     * on a tab that is not the first one.
+     */
+    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.js";
+/**
+ * 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;
+}