@rebasepro/admin-types 0.10.1-canary.0

package/src/collections.ts

@@ -0,0 +1,256 @@
+/**
+ * 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, Property, User } from "@rebasepro/types";
+
+import type { RebaseContext } from "./rebase_context";
+import type { AdminCollection } from "@rebasepro/admin-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.
+     */
+    columnProperty: Extract<keyof M, string> | (string & {});
+}
+
+/**
+ * View mode for displaying a collection.
+ * - "list": Simple, clean list view — the classic CMS default
+ * - "table": Table with inline editing
+ * - "cards": Grid of visual cards with thumbnails
+ * - "kanban": Board view grouped by a property
+ * @group Collections
+ */
+export type ViewMode = "list" | "table" | "cards" | "kanban";
+
+/**
+ * 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 CMS 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.
+ * @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.
+     */
+    dependencies?: NoInfer<Extract<keyof M, string>> | NoInfer<Extract<keyof M, string>>[] | (string & {}) | (string & {})[];
+
+    /**
+     * 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;
+    sortBy?: [Extract<keyof M, string> | (string & {}), "asc" | "desc"];
+    setSortBy?: (sortBy?: [Extract<keyof M, string> | (string & {}), "asc" | "desc"]) => 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?: [string, "asc" | "desc"]) => 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 CMS
+     */
+    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,121 @@
+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;
+    registration?: 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,72 @@
+
+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 { 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 CMS.
+     */
+    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 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 CMS.
+     * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
+     */
+    dateTimeFormat?: string;
+
+    /**
+     * Locale of the CMS, currently only affecting dates
+     */
+    locale?: Locale;
+
+    /**
+     * Record of custom form fields to be used in the CMS.
+     * 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;
+
+}

package/src/controllers/index.ts

@@ -0,0 +1,10 @@
+export * from "./analytics_controller";
+export * from "./auth";
+export * from "./customization_controller";
+export * from "./dialogs_controller";
+export * from "./local_config_persistence";
+export * from "./navigation";
+export * from "./registry";
+export * from "./side_dialogs_controller";
+export * from "./side_panel_controller";
+export * from "./snackbar";

package/src/controllers/local_config_persistence.tsx

@@ -0,0 +1,22 @@
+import type { AdminCollection } from "@rebasepro/admin-types";
+
+/**
+ * @group Models
+ */
+export type PartialCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>> = Partial<AdminCollection<M>>;
+
+/**
+ * This interface is in charge of defining the controller that persists
+ * modifications to a collection or collection, and retrieves them back from
+ * a data source, such as local storage or Firestore.
+ */
+export interface UserConfigurationPersistence {
+    onCollectionModified: <M extends Record<string, unknown> = Record<string, unknown>>(path: string, partialCollection: PartialCollectionConfig<M>) => void;
+    getCollectionConfig: <M extends Record<string, unknown> = Record<string, unknown>>(path: string) => PartialCollectionConfig<M>;
+    recentlyVisitedPaths: string[];
+    setRecentlyVisitedPaths: (paths: string[]) => void;
+    favouritePaths: string[];
+    setFavouritePaths: (paths: string[]) => void;
+    collapsedGroups: string[];
+    setCollapsedGroups: (paths: string[]) => void;
+}