@rebasepro/cms-types 0.17.0-canary.0

package/src/augment.ts

@@ -0,0 +1,79 @@
+/**
+ * The admin block, added back onto the core types by declaration merging.
+ *
+ * `@rebasepro/types` declares no `admin` field — not on `BaseCollectionConfig`, not on
+ * any property. A BaaS install therefore cannot write one: `admin: { … }` on a property
+ * there is a type error, which is the whole point. Installing this package is what makes
+ * the surface exist.
+ *
+ * This works because every target is an `interface`. Interfaces merge; `type` aliases do
+ * not, so `BaseProperty` and the ten concrete property types must stay interfaces in core
+ * for this file to be possible at all.
+ *
+ * Two consequences worth knowing:
+ *
+ * - The augmentation applies to the whole **program**, not to the files that import it.
+ *   `config/` and `frontend/` are separate tsconfig programs, so a collection file needs
+ *   this package in *its* program. The templates do that with one line in one file —
+ *   `config/cms.d.ts`, holding `/// <reference types="@rebasepro/cms-types" />` —
+ *   which is why no collection file has to import anything from here to write `admin`.
+ *   That reference resolves through `typeRoots`, so the project must also depend on this
+ *   package; `tooling/scripts/check-templates.mjs` asserts both halves.
+ * - Each concrete property narrows the block to its own options type
+ *   (`AdminStringOptions` on `StringProperty`, and so on). That is legal because each
+ *   extends `AdminPropertyOptions`, exactly as it was declared when these lived in core.
+ */
+import type {
+    AdminArrayOptions,
+    AdminDateOptions,
+    AdminMapOptions,
+    AdminNumberOptions,
+    AdminPropertyOptions,
+    AdminReferenceOptions,
+    AdminRelationOptions,
+    AdminStringOptions,
+    AdminVectorOptions
+} from "./types/property_options";
+import type { AdminCollectionOptions } from "./admin_collection";
+// Named in the merged declaration's parameter list, which must match core's.
+import type { User } from "@rebasepro/types";
+
+declare module "@rebasepro/types" {
+
+    /**
+     * Presentation and behaviour for a collection in the admin panel.
+     *
+     * The type parameters are repeated here verbatim because declaration
+     * merging requires an identical parameter list — and they have to be
+     * *forwarded* to `AdminCollectionOptions`, which is the part that was
+     * missing. Written as a bare `admin?: AdminCollectionOptions`, `M` fell
+     * back to its default `Record<string, unknown>`, so `Extract<keyof M,
+     * string>` widened to `string` and every key-shaped field in the block —
+     * `display`, `sort`, `propertiesOrder`, `listProperties` — silently
+     * accepted any string. The completion `defineCollection` advertises is
+     * derived from `M`, so it never appeared: the inference was computed,
+     * carried to this seam, and dropped one line short of the field that
+     * needed it.
+     */
+    interface BaseCollectionConfig<
+        M extends Record<string, unknown> = Record<string, unknown>,
+        USER extends User = User
+    > {
+        admin?: AdminCollectionOptions<M, USER>;
+    }
+
+    interface BaseProperty<CustomProps = unknown> {
+        admin?: AdminPropertyOptions<CustomProps>;
+    }
+
+    interface StringProperty { admin?: AdminStringOptions; }
+    interface NumberProperty { admin?: AdminNumberOptions; }
+    interface BooleanProperty { admin?: AdminPropertyOptions; }
+    interface VectorProperty { admin?: AdminVectorOptions; }
+    interface DateProperty { admin?: AdminDateOptions; }
+    interface GeopointProperty { admin?: AdminPropertyOptions; }
+    interface ReferenceProperty { admin?: AdminReferenceOptions; }
+    interface RelationProperty { admin?: AdminRelationOptions; }
+    interface ArrayProperty { admin?: AdminArrayOptions; }
+    interface MapProperty { admin?: AdminMapOptions; }
+}

package/src/collections.ts

@@ -0,0 +1,312 @@
+/**
+ * Admin-panel view models for a collection.
+ *
+ * These twelve types came out of `collections.ts`, where they sat interleaved
+ * with the collection shape itself. None of them describes data: they are the
+ * table's controllers, the selection state, the kanban layout, the shape of a
+ * toolbar action's props. Every one names `React` or `RebaseContext`, and none is
+ * imported by a single backend package — checked across `server`,
+ * `server-postgres`, `server-mongo`, `client`, `common`, `utils`, `cli` and
+ * `codegen`.
+ *
+ * That is what made them safe to lift: they were never part of the BaaS surface,
+ * only stored next to it.
+ */
+import React, { Dispatch, SetStateAction } from "react";
+import type { Entity, EntityStatus, FilterValues, OrderByTuple, Property, User } from "@rebasepro/types";
+
+import type { RebaseContext } from "./rebase_context";
+import type { AdminCollection, PropertyPath } from "@rebasepro/cms-types";
+
+/**
+ * Configuration for Kanban board view mode.
+ * @group Collections
+ */
+export interface KanbanConfig<M extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Property key to use for Kanban board columns.
+     * Must reference a string property with `enum` values defined.
+     * Entities will be grouped into columns based on this property's value.
+     * The column order is determined by the order of `enum` values in the property.
+     *
+     * Left permissive on purpose, unlike the *optional* key fields on the admin
+     * block (`display`, `sort`, `propertiesOrder`, …), which are checked
+     * against `M`.
+     *
+     * This one is **required**, and that is the whole difference: a required
+     * generic-dependent property puts `Extract<keyof M, string>` in an invariant
+     * position, so `AdminCollection<M>` stops being assignable to
+     * `AdminCollection`. The admin package passes collections between those two
+     * forms in roughly fifteen places — `CollectionBoardViewBinding`, the
+     * collection editor, the view bindings — and every one of them breaks.
+     * Tightening this is a worthwhile change, but it is a refactor of those call
+     * sites rather than a type edit. Verified by trying it: `columnProperty:
+     * Extract<keyof M, string>` alone produced ~15 errors, and doing it alongside
+     * `entityViews`/`formView`/`Actions` produced 95.
+     */
+    columnProperty: Extract<keyof M, string> | (string & {});
+}
+
+/**
+ * View mode for displaying a collection.
+ * - "list": Simple, clean list view — the classic admin default
+ * - "table": Table with inline editing
+ * - "cards": Grid of visual cards with thumbnails
+ * - "kanban": Board view grouped by a property
+ *
+ * Any other string is the `key` of a custom view declared in
+ * `admin.customViews` or registered on `<RebaseCMS collectionViews={…}>`.
+ * The `(string & {})` arm is what keeps the four built-ins in autocomplete
+ * while still admitting those keys.
+ *
+ * @group Collections
+ */
+export type ViewMode = "list" | "table" | "cards" | "kanban" | (string & {});
+
+/**
+ * Parameter passed to the `Actions` prop in the collection configuration.
+ * The component will receive this prop when it is rendered in the collection
+ * toolbar.
+ *
+ * @group Models
+ */
+export interface CollectionActionsProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User, EC extends AdminCollection<M> = AdminCollection<M>> {
+    /**
+     * Full collection path of this entity. This is the full path, like
+     * `users/1234/addresses`
+     */
+    path: string;
+
+    /**
+     * Path of the last collection, like `addresses`
+     */
+    relativePath: string;
+
+    /**
+     * Array of the parent path segments like `['users']`
+     */
+    parentCollectionSlugs: string[];
+    parentEntityIds: string[];
+
+    /**
+     * The collection configuration
+     */
+    collection: EC;
+
+    /**
+     * Use this controller to get the selected entities and to update the
+     * selected entities state.
+     */
+    selectionController: SelectionController<M>;
+
+    /**
+     * Use this controller to get the table controller and to update the
+     * table controller state.
+     */
+    tableController: EntityTableController<M>;
+
+    /**
+     * Context of the app status
+     */
+    context: RebaseContext<USER>;
+
+    /**
+     * Count of the entities in this collection.
+     * undefined means the count is still loading.
+     */
+    collectionEntitiesCount?: number;
+
+    /**
+     * Programmatically open the new-document form for this collection,
+     * optionally pre-populating it with initial field values.
+     * The form opens in the same mode configured for the collection
+     * (side panel, full screen, or split).
+     *
+     * This is the primary hook for workflows that need to create a document
+     * from external data — e.g. fetching content from a URL, importing from
+     * a third-party API, or duplicating from another system.
+     *
+     * @example
+     * // Inside a custom CollectionAction component:
+     * openNewDocument({ title: "Fetched title", body: "..." });
+     */
+    openNewDocument: (defaultValues?: Record<string, unknown>) => void;
+
+}
+
+/**
+ * Use this controller to retrieve the selected entities or modify them in
+ * an {@link AdminCollection}
+ * @group Models
+ */
+export interface SelectionController<M extends Record<string, unknown> = Record<string, unknown>> {
+    selectedEntities: Entity<M>[];
+    setSelectedEntities(entities: Entity<M>[]): void;
+    setSelectedEntities(action: (prev: Entity<M>[]) => Entity<M>[]): void;
+    isEntitySelected(entity: Entity<M>): boolean;
+    toggleEntitySelection(entity: Entity<M>, newSelectedState?: boolean): void;
+}
+
+// Canonical filter types — re-exported from the single source-of-truth.
+
+/**
+ * Used to indicate valid filter combinations (e.g. created in Firestore)
+ * If the user selects a specific filter/sort combination, the admin checks if it's
+ * valid, otherwise it reverts to the simpler valid case
+ * @group Models
+ */
+export type FilterCombination<Key extends string> = Partial<Record<Key, "asc" | "desc">>;
+
+/**
+ * Sizes in which a collection can be rendered
+ * @group Models
+ */
+export type CollectionSize = "xs" | "s" | "m" | "l" | "xl";
+
+export type AdditionalFieldDelegateProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = {
+    entity: Entity<M>,
+    context: RebaseContext<USER>
+};
+
+/**
+ * Use this interface for adding additional fields to entity collection views and forms.
+ *
+ * **Computed for display only. The server never sees it.**
+ *
+ * `value` is async and receives the whole {@link RebaseContext}, so it *can*
+ * read another collection, and its result is cached per record. That makes it
+ * read like a computed column, and it is not one: it runs in the browser, once
+ * per row, **after** the page has already been fetched and ordered. There is no
+ * point at which its result could take part in choosing which rows came back or
+ * in what order. So a derived value can be shown, and can never be filtered,
+ * sorted or paged on — no matter what it is derived from.
+ *
+ * To filter or sort on a derived value it has to exist in the database. Two
+ * ways, in order of preference:
+ *
+ *  - if the value is an aggregate over a relation, ask for it in the query
+ *    instead — `where: { "applications.status": ["in", [...]] }` and
+ *    `orderBy: [[{ relation: "applications", field: "created_at", agg: "min" }, "asc"]]`
+ *    are both compiled by the driver, which means they run before paging;
+ *  - otherwise denormalise it onto the row — a generated column, or a
+ *    trigger-maintained one — and it becomes an ordinary property.
+ *
+ * @group Models
+ */
+export interface AdditionalFieldDelegate<M extends Record<string, unknown> = Record<string, unknown>,
+    USER extends User = User> {
+
+    /**
+     * ID of this column. You can use this id in the `properties` field of the
+     * collection in any order you want
+     */
+    key: string;
+
+    /**
+     * Header of this column
+     */
+    name: string;
+
+    /**
+     * Width of the generated column in pixels
+     */
+    width?: number;
+
+    /**
+     * Builder for the custom field
+     */
+    Builder?(props: { entity: Entity<M>, context: RebaseContext<USER> }): React.ReactNode;
+
+    /**
+     * If this column needs to update dynamically based on other properties,
+     * you can define an array of keys as strings with the
+     * `dependencies` prop.
+     * e.g. ["name", "surname"]
+     * This is a performance optimization, if you don't define dependencies
+     * it will be updated in every render.
+     *
+     * A key that is not a property of this collection can never change, so
+     * listing one is always a mistake — it silently pins the column to the
+     * "never re-render" path, which reads as a stale cell rather than a typo.
+     * The `NoInfer` wrappers keep these keys from participating in inference of
+     * `M`; the `(string & {})` arms they used to sit beside made the whole union
+     * `string`, so the wrappers had nothing to protect.
+     */
+    dependencies?: NoInfer<PropertyPath<M>> | NoInfer<PropertyPath<M>>[];
+
+    /**
+     * Use this prop to define the value of the column as a string or number.
+     * This is the value that will be used for exporting the collection.
+     * If `Builder` is defined, this prop will be ignored in the collection
+     * view.
+     * @param entity
+     */
+    value?(props: {
+        entity: Entity<M>,
+        context: RebaseContext
+    }): string | number | Promise<string | number> | undefined;
+}
+
+/**
+ * Used in the {@link AdminCollection#defaultSelectedView} to define the default
+ * @group Models
+ */
+export type DefaultSelectedViewBuilder = (params: DefaultSelectedViewParams) => string | undefined;
+
+/**
+ * Used in the {@link AdminCollection#defaultSelectedView} to define the default
+ * @group Models
+ */
+export type DefaultSelectedViewParams = {
+    status?: EntityStatus;
+    entityId?: string | number;
+};
+
+/**
+ * You can use this controller to control the table view of a collection.
+ */
+export type EntityTableController<M extends Record<string, unknown> = Record<string, unknown>> = {
+    data: Entity<M>[];
+    dataLoading: boolean;
+    noMoreToLoad: boolean;
+    dataLoadingError?: Error;
+    filterValues?: FilterValues<Extract<keyof M, string> | (string & {})>;
+    setFilterValues?: (filterValues: FilterValues<Extract<keyof M, string> | (string & {})>) => void;
+    /**
+     * The sort keys in order of significance, the second breaking ties on the
+     * first. A single key is a one-element list — this was a bare tuple, which
+     * could only ever express one, so `collection.sort` could not describe an
+     * order like "by role, newest first within each role" and the table had no
+     * state to hold one in.
+     */
+    sortBy?: OrderByTuple<Extract<keyof M, string> | (string & {})>[];
+    setSortBy?: (sortBy?: OrderByTuple<Extract<keyof M, string> | (string & {})>[]) => void;
+    searchString?: string;
+    setSearchString?: (searchString?: string) => void;
+    clearFilter?: () => void;
+    itemCount?: number;
+    setItemCount?: (itemCount: number) => void;
+    initialScroll?: number;
+    onScroll?: (props: {
+        scrollDirection: "forward" | "backward",
+        scrollOffset: number,
+        scrollUpdateWasRequested: boolean
+    }) => void;
+    paginationEnabled?: boolean;
+    pageSize?: number;
+    checkFilterCombination?: (filterValues: FilterValues<string>,
+        sortBy?: OrderByTuple[]) => boolean;
+    popupCell?: SelectedCellProps<M>;
+    setPopupCell?: (popupCell?: SelectedCellProps<M>) => void;
+
+    onAddColumn?: (column: string) => void;
+}
+
+export type SelectedCellProps<M extends Record<string, unknown> = Record<string, unknown>> = {
+    propertyKey: Extract<keyof M, string> | (string & {});
+    cellRect: DOMRect;
+    width: number;
+    height: number;
+    entityPath: string;
+    entityId: string | number;
+};

package/src/controllers/analytics_controller.tsx

@@ -0,0 +1,57 @@
+export type AnalyticsController = {
+
+    /**
+     * Callback used to get analytics events from the admin
+     */
+    onAnalyticsEvent?: (event: AnalyticsEvent, data?: object) => void;
+
+}
+
+export type AnalyticsEvent =
+    | "entity_click"
+    | "entity_click_from_reference"
+
+    | "reference_selection_clear"
+    | "reference_selection_toggle"
+    | "reference_selected_single"
+    | "reference_selection_new_entity"
+
+    | "edit_entity_clicked"
+    | "entity_edited"
+    | "new_entity_click"
+    | "new_entity_saved"
+    | "copy_entity_click"
+    | "entity_copied"
+
+    | "single_delete_dialog_open"
+    | "multiple_delete_dialog_open"
+    | "single_entity_deleted"
+    | "multiple_entities_deleted"
+
+    | "drawer_navigate_to_home"
+    | "drawer_navigate_to_collection"
+    | "drawer_navigate_to_view"
+
+    | "home_navigate_to_collection"
+    | "home_favorite_navigate_to_collection"
+    | "home_navigate_to_view"
+    | "home_navigate_to_admin_view"
+    | "home_favorite_navigate_to_view"
+    | "home_move_card"
+    | "home_move_group"
+    | "home_drop_new_group"
+
+    | "collection_inline_editing"
+
+    | "view_mode_changed"
+
+    | "kanban_card_moved"
+    | "kanban_column_reorder"
+    | "kanban_property_changed"
+    | "kanban_new_entity_in_column"
+    | "kanban_backfill_order"
+
+    | "card_view_entity_click"
+
+    | "unmapped_event"
+    ;

package/src/controllers/auth.ts

@@ -0,0 +1,122 @@
+import type { User } from "@rebasepro/types";
+
+/**
+ * Capabilities advertised by an auth provider.
+ * UI components use this to show/hide features dynamically
+ * (e.g. password reset, registration, session management).
+ * @group Hooks and utilities
+ */
+export interface AuthCapabilities {
+    emailPasswordLogin?: boolean;
+    googleLogin?: boolean;
+    /** Self-registration is open right now — the wire's `registrationEnabled`. */
+    registrationEnabled?: boolean;
+    /** Self-service password reset (emailing a reset link) is available. */
+    passwordReset?: boolean;
+    /**
+     * An admin can reset another user's password. Gates the "Reset Password"
+     * entity action in the admin UI. See `AuthAdapterCapabilities`.
+     */
+    adminPasswordReset?: boolean;
+    sessionManagement?: boolean;
+    profileUpdate?: boolean;
+    emailVerification?: boolean;
+    /** List of enabled OAuth provider IDs (e.g. ["google", "github", "discord"]) */
+    enabledProviders?: string[];
+}
+
+/**
+ * Controller for retrieving the logged user or performing auth related operations.
+ * Note that if you are implementing your AuthController, you probably will want
+ * to do it as the result of a hook.
+ * @group Hooks and utilities
+ */
+export type AuthController<USER extends User = User, ExtraData = unknown> = {
+
+    /**
+     * The user currently logged in
+     * The values can be: the user object, null if they skipped login
+     */
+    user: USER | null;
+
+    /**
+     * Initial loading flag. It is used not to display the login screen
+     * when the app first loads, and it has not been checked whether the user
+     * is logged in or not.
+     */
+    initialLoading?: boolean;
+
+    /**
+     * Loading flag. It is used to display a loading screen when the user is
+     * logging in or out.
+     */
+    authLoading: boolean;
+
+    /**
+     * Sign out
+     */
+    signOut: () => Promise<void>;
+
+    /**
+     * Error initializing the authentication
+     */
+    authError?: unknown;
+
+    /**
+     * Error dispatched by the auth provider
+     */
+    authProviderError?: unknown;
+
+    /**
+     * You can use this method to retrieve the auth token for the current user.
+     */
+    getAuthToken: () => Promise<string>;
+
+    /**
+     * Has the user skipped the login process
+     */
+    loginSkipped: boolean;
+
+    extra: ExtraData;
+
+    setExtra: (extra: ExtraData) => void;
+
+
+    setUser?(user: USER | null): void;
+
+    setUserRoles?(roles: string[]): void;
+
+    /**
+     * Capabilities advertised by the auth provider.
+     * UI components use this to feature-detect what the backend supports.
+     */
+    capabilities?: AuthCapabilities;
+
+};
+
+/**
+ * Extended auth controller with common optional auth methods.
+ * Backend implementations (Rebase backend, Firebase, etc.)
+ * extend this with their own backend-specific extras.
+ * @group Hooks and utilities
+ */
+export interface AuthControllerExtended<USER extends User = User, ExtraData = unknown> extends AuthController<USER, ExtraData> {
+    /** Login with email and password */
+    emailPasswordLogin?(email: string, password: string): Promise<void>;
+    /** Login with Google — accepts an ID token, access token, or authorization code payload */
+    googleLogin?: (payload: { idToken: string } | { accessToken: string } | { code: string; redirectUri: string }) => Promise<void>;
+    /** Generic OAuth login — works with any provider. Posts payload to /auth/{providerId}. */
+    oauthLogin?: (providerId: string, payload: Record<string, unknown>) => Promise<void>;
+    /** Register a new user */
+    register?(email: string, password: string, displayName?: string): Promise<void>;
+    /** Skip login (for anonymous access if enabled) */
+    skipLogin?(): void;
+    /** Request password reset email */
+    forgotPassword?(email: string): Promise<void>;
+    /** Reset password using a token */
+    resetPassword?(token: string, password: string): Promise<void>;
+    /** Change password for the authenticated user */
+    changePassword?(oldPassword: string, newPassword: string): Promise<void>;
+    /** Update user profile */
+    updateProfile?(displayName?: string, photoURL?: string): Promise<USER>;
+}

package/src/controllers/customization_controller.tsx

@@ -0,0 +1,81 @@
+
+import type { EntityLinkBuilder } from "../types/entity_link_builder";
+import type { Locale } from "../types/locales";
+import type { EntityAction } from "../types/entity_actions";
+import type { EntityCustomView } from "../types/entity_views";
+import type { CollectionCustomView } from "../types/collection_views";
+import type { RebasePlugin } from "../types/plugins";
+import type { PropertyConfig } from "../types/property_config";
+import type { SlotContribution } from "../types/slots";
+import type { ComponentOverrideMap } from "../types/component_overrides";
+
+export type CustomizationController = {
+
+    /**
+     * Builder for generating utility links for entities
+     */
+    entityLinkBuilder?: EntityLinkBuilder;
+
+    /**
+     * Use plugins to modify the behaviour of the admin.
+     */
+    plugins?: RebasePlugin[];
+
+    /**
+     * Pre-merged slots from plugins + direct slot contributions.
+     */
+    resolvedSlots: SlotContribution[];
+
+    /**
+     * List of additional custom views for entities.
+     * You can use the key to reference the custom view in
+     * the `entityViews` prop of a collection.
+     *
+     * You can also define a entity view from the UI.
+     */
+    entityViews?: EntityCustomView[];
+
+    /**
+     * List of additional ways to render a collection's rows. You can use the
+     * key to reference the view in the `admin.customViews` prop of a
+     * collection, which is also what makes it selectable from the collection
+     * editor.
+     */
+    collectionViews?: CollectionCustomView[];
+
+    /**
+     * List of actions that can be performed on entities.
+     * These actions are displayed in the entity view and in the collection view.
+     * You can later reuse these actions in the `entityActions` prop of a collection,
+     * by specifying the `key` of the action.
+     */
+    entityActions?: EntityAction[];
+
+    /**
+     * Format of the dates in the admin.
+     * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
+     */
+    dateTimeFormat?: string;
+
+    /**
+     * Locale of the admin, currently only affecting dates
+     */
+    locale?: Locale;
+
+    /**
+     * Record of custom form fields to be used in the admin.
+     * You can use the key to reference the custom field in
+     * the `propertyConfig` prop of a property in a collection.
+     */
+    propertyConfigs: Record<string, PropertyConfig>;
+
+    /**
+     * Global component overrides. Keys are component names from
+     * {@link OverridableComponentName}. Values replace the default
+     * implementation everywhere in the app.
+     *
+     * Collection-scoped overrides (set on individual collections)
+     * take precedence over global overrides.
+     */
+    components?: ComponentOverrideMap;
+}

package/src/controllers/dialogs_controller.tsx

@@ -0,0 +1,37 @@
+import React from "react";
+
+/**
+ * Controller to open the side dialog
+ * @group Hooks and utilities
+ */
+export interface DialogsController {
+
+    /**
+     * Close the last dialog
+     */
+    close: () => void;
+
+    /**
+     * Open a dialog
+     * @param props
+     */
+    open: <T extends object = object>(props: DialogControllerEntryProps<T>) => { closeDialog: () => void };
+}
+
+/**
+ * Props used to open a side dialog
+ * @group Hooks and utilities
+ */
+export interface DialogControllerEntryProps<T extends object = object> {
+
+    key: string;
+    /**
+     * The component type that will be rendered
+     */
+    Component: React.ComponentType<{ open: boolean, closeDialog: () => void } & T>;
+    /**
+     * Props to pass to the dialog component
+     */
+    props?: T;
+
+}