@rebasepro/app 0.17.3 → 0.18.0

package/src/core/RebaseProps.tsx

@@ -1,333 +0,0 @@
-import React from "react";
-import { User, DataDriver, DataSourceDefinition, StorageSource, StorageSourceDefinition, CollectionRegistryController, DatabaseAdmin, RebaseClient } from "@rebasepro/types";
-import { Locale, AuthController, AnalyticsEvent, UserConfigurationPersistence, UrlController, NavigationStateController, RebaseContext, EntityLinkBuilder, RebasePlugin, SlotContribution, PropertyConfig, EntityCustomView, CollectionCustomView, EntityAction, RebaseTranslations, ComponentOverrideMap } from "@rebasepro/cms-types";
-
-/**
- * A data source registered on `<Rebase>`. Extends the shared
- * {@link DataSourceDefinition} with the frontend {@link DataDriver} used for
- * `direct`/`custom` transports. Server-mediated sources omit `driver` — they
- * are reached through the `client`.
- *
- * @group Models
- */
-export type RebaseDataSource = DataSourceDefinition & {
-    /**
-     * The client-side driver for this source. Required for `direct`/`custom`
-     * transports; omit for `server` transport (handled by the `client`).
-     *
-     * When `transport` is not stated it is inferred from this field:
-     * driver present → `"direct"`, absent → `"server"`.
-     */
-    driver?: DataDriver;
-};
-
-/**
- * A storage source registered on `<Rebase>`. Extends the shared
- * {@link StorageSourceDefinition} with an optional frontend
- * {@link StorageSource} for `direct` transports. Server-mediated sources
- * omit `source` — they are reached through the `client`.
- *
- * @group Models
- */
-export type RebaseStorageSource = StorageSourceDefinition & {
-    /**
-     * The client-side StorageSource for this backend. Required for `direct`
-     * transport (e.g. Firebase Storage via `@firebase/storage`); omit for
-     * `server` transport (proxied by the Rebase backend).
-     */
-    source?: StorageSource;
-};
-
-/** DeepPartial helper — allows partial overrides at any nesting level */
-type DeepPartial<T> = T extends object
-    ? { [K in keyof T]?: DeepPartial<T[K]> }
-    : T;
-
-/**
- * Controller to simulate different roles when dev mode is active.
- * @group Models
- */
-export type { EffectiveRoleController } from "@rebasepro/types";
-import type { EffectiveRoleController } from "@rebasepro/types";
-
-
-/**
- * Props for the main {@link Rebase} component.
- *
- * ## Data
- *
- * Everything is a data source, and there is one list: {@link dataSources}.
- * The **default** source (serving every collection without a `dataSource`
- * key) resolves with three rules:
- *
- * 1. A `dataSources` entry keyed `"(default)"` (`DEFAULT_DATA_SOURCE_KEY`)
- *    *with a driver* is the default source.
- * 2. Otherwise `client.data` is the default.
- * 3. Otherwise, if exactly one source is registered, it is the default.
- *    Zero sources, or several without a `"(default)"` key, **throw**.
- *
- * A `"(default)"` entry *without* a driver never provides data — it only
- * declares the default source's `engine`/`label` (capabilities) when the
- * client is the default.
- *
- * All other `dataSources` entries are routed non-default sources:
- * collections opt in via `collection.dataSource`.
- *
- * ### Auth
- *
- * - `authController` prop → completely disables the `client.auth`
- *   subscription (an override, not a merge). The recommended pattern is to
- *   pass both `client` and an `authController` built from that client via
- *   `useRebaseAuthController({ client })`.
- * - Otherwise, `client.auth` is subscribed to via `useAuthSubscription`.
- *
- * ### Storage (default source)
- *
- * Default: `storageSource` prop ?? `client.storage`.
- *
- * Named sources are merged in priority order (later entries with the same
- * key overwrite earlier ones):
- * 1. Backend-discovered remote definitions (`client.fetchStorageSources()`,
- *    fetched after auth/login-skip).
- * 2. Client `storageRegistry` entries.
- * 3. `storageSources` prop entries (live `direct` instances; `server`-
- *    transport keys are materialized via `client.createStorageSource`).
- * 4. Default storage (keyed `DEFAULT_STORAGE_SOURCE_KEY`) as fallback.
- *
- * ## Decision Ladder
- *
- * | Scenario | Props to use |
- * |---|---|
- * | Standard app | `client` (+ `authController` built from it) |
- * | Multi-backend data | add `dataSources` |
- * | Multi-backend storage | add `storageSources` |
- * | Fully headless / custom | `dataSources` with a `"(default)"`-keyed driver entry + `storageSource` |
- *
- * @group Models
- */
-export type RebaseProps<USER extends User, DB = unknown> = {
-
-    /**
-     * The root components of your application. Use RebaseCMS, RebaseStudio, and RebaseShell.
-     * Alternatively, pass a render function that receives { context, loading }.
-     */
-    children: React.ReactNode | ((props: { context: RebaseContext; loading: boolean }) => React.ReactNode);
-
-    /**
-     * Optional base path for the entire Rebase app.
-     * Defaults to "/"
-     */
-    basePath?: string;
-
-    /**
-     * Optional base path for the admin collections.
-     * Defaults to "/c"
-     */
-    baseCollectionPath?: string;
-
-    /**
-     * Base URL for the backend API (e.g. "http://localhost:3001").
-     * When provided, this is available via `useApiConfig()` to any hook
-     * in the tree, reducing repetitive `apiUrl` threading.
-     */
-    apiUrl?: string;
-
-
-    /**
-     * 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;
-
-    /**
-     * Unified RebaseClient for data, auth, and storage.
-     *
-     * `client.data` is the default data source unless a {@link dataSources}
-     * entry keyed `"(default)"` carries a driver.
-     * `client.auth` is subscribed unless `authController` is provided.
-     * `client.storage` is used unless `storageSource` is provided.
-     *
-     * `DB` is inferred from whatever is passed, and defaults to `unknown` for
-     * an untyped client. It has to be a parameter rather than a fixed
-     * `RebaseClient`: `RebaseClient<unknown>` is not a supertype of
-     * `RebaseClient<Database>` — the dynamic branch of `RebaseSdkData` is an
-     * index signature that no concrete instantiation satisfies — so pinning it
-     * here rejected the client of every project that generates a `Database`
-     * type, which is the whole typed-SDK path.
-     */
-    client?: RebaseClient<DB>;
-
-    /**
-     * The data sources of the app. Each entry pairs a
-     * {@link DataSourceDefinition} (key, engine, transport) with an optional
-     * client-side {@link DataDriver}.
-     *
-     * Register the **direct** (e.g. Firestore, talking straight to its backend)
-     * and **custom** sources here. Server-mediated sources (Postgres, MongoDB,
-     * …) do *not* need an entry — they ride the `client` and are routed by the
-     * Rebase backend.
-     *
-     * An entry keyed `"(default)"` with a driver **replaces** `client.data`
-     * as the default data source (this is how a fully client-side app, e.g.
-     * Firestore-only, is wired). Without a driver, a `"(default)"` entry just
-     * declares the default source's engine/capabilities.
-     *
-     * Collections are routed automatically by their `dataSource` key (resolved
-     * by collection path against the registry), so routing works transparently
-     * for list/entity views, references, the board view, import/export, and
-     * programmatic `context.data` access — no per-collection wiring.
-     *
-     * @example
-     * ```tsx
-     * // Postgres via the Rebase client (default) + a direct Firestore source.
-     * <Rebase
-     *     client={rebaseClient}
-     *     dataSources={[
-     *         { key: "analytics", engine: "firestore", driver: firestoreDriver }
-     *     ]}
-     * >
-     * // Collections opt in with `{ ..., dataSource: "analytics" }`.
-     * ```
-     */
-    dataSources?: RebaseDataSource[];
-
-    /**
-     * Custom auth controller. When provided, the `client.auth` subscription
-     * is **completely disabled** (not merged).
-     *
-     * The recommended pattern is to pass both `client` and an
-     * `authController` built from that client:
-     * ```tsx
-     * const authController = useRebaseAuthController({ client });
-     * <Rebase client={client} authController={authController} />
-     * ```
-     * This lets the `authController` own the auth lifecycle while `client`
-     * still provides data and storage.
-     */
-    authController?: AuthController<USER>;
-
-    /**
-     * Default storage source. Overrides `client.storage` when provided.
-     * Named sources in {@link storageSources} are unaffected.
-     */
-    storageSource?: StorageSource;
-
-    /**
-     * Additional storage sources beyond the default `client.storage`.
-     *
-     * Register **direct** (e.g. Firebase Storage, talking straight to the
-     * cloud) sources here. Server-mediated sources (S3, GCS proxied by the
-     * Rebase backend) do *not* need an entry — they are routed by
-     * `storageId` query parameter on the REST API.
-     *
-     * Collection properties opt in via `storage.storageSource: "key"`.
-     *
-     * @example
-     * ```tsx
-     * <Rebase
-     *     client={rebaseClient}
-     *     storageSources={[
-     *         { key: "firebase", engine: "firebase", transport: "direct", source: firebaseStorageSource }
-     *     ]}
-     * >
-     * ```
-     */
-    storageSources?: RebaseStorageSource[];
-
-    /**
-     * Administrative database operations (SQL, schema discovery).
-     * Only needed when the studio/admin features are enabled.
-     */
-    databaseAdmin?: DatabaseAdmin;
-
-    /**
-     * Use this controller to access the configuration that is stored locally,
-     * and not defined in code
-     */
-    userConfigPersistence?: UserConfigurationPersistence;
-
-    /**
-     * Callback used to get analytics events from the admin
-     */
-    onAnalyticsEvent?: (event: AnalyticsEvent, data?: object) => void;
-
-    /**
-     * Optional link builder you can add to generate a button in your entity forms.
-     * The function must return a URL that gets opened when the button is clicked
-     */
-    entityLinkBuilder?: EntityLinkBuilder;
-
-
-    /**
-     * Plugins loaded in the admin
-     */
-    plugins?: RebasePlugin[];
-
-    /**
-     * Extra slots for the admin
-     */
-    slots?: SlotContribution[];
-
-    /**
-     * Property configs (widgets)
-     */
-    propertyConfigs?: Record<string, PropertyConfig>;
-
-    /**
-     * Entity Views
-     */
-    entityViews?: EntityCustomView[];
-
-    /**
-     * Custom collection view modes, available to every collection by `key`.
-     * A collection opts into one by naming that key in `admin.customViews`.
-     */
-    collectionViews?: CollectionCustomView[];
-
-    /**
-     * Entity Actions
-     */
-    entityActions?: EntityAction[];
-
-    /**
-     * Controller to simulate different roles when dev mode is active.
-     */
-    effectiveRoleController?: EffectiveRoleController;
-
-    /**
-     * Override or extend any Rebase UI string, keyed by locale.
-     */
-    translations?: {
-        [locale: string]: DeepPartial<RebaseTranslations>;
-    };
-
-    /**
-     * Override built-in UI components with custom implementations.
-     *
-     * Keys are component names from {@link OverridableComponentName}.
-     * Values specify the replacement component and an optional `wrap`
-     * flag for the wrapping pattern.
-     *
-     * @example
-     * ```tsx
-     * <Rebase
-     *     client={client}
-     *     components={{
-     *         "Shell.AppBar": { Component: MyCustomAppBar },
-     *         "EditView.FormActions": {
-     *             Component: MyFormActions,
-     *             wrap: true
-     *         }
-     *     }}
-     * >
-     * ```
-     */
-    components?: ComponentOverrideMap;
-
-};
-

package/src/core/RebaseRouter.tsx

@@ -1,18 +0,0 @@
-import { createBrowserRouter } from "react-router"
-import { RouterProvider } from "react-router/dom"
-import { removeInitialAndTrailingSlashes } from "@rebasepro/app";
-
-export function RebaseRouter({
-    children,
-    basePath
-}: {
-    children: React.ReactNode,
-    basePath?: string;
-}) {
-    return <RouterProvider router={createBrowserRouter([
-        {
-            path: basePath ? `${removeInitialAndTrailingSlashes(basePath)}/*` : "/*",
-            element: children
-        }
-    ])}/>;
-}

package/src/core/RebaseRoutes.tsx

@@ -1,24 +0,0 @@
-import React from "react";
-import { Route, Routes, useLocation } from "react-router";
-
-
-/**
- * A drop-in replacement for react-router's `<Routes>` that preserves the
- * underlying view when a side dialog navigates the URL to a different path.
- *
- * When opening a side dialog from e.g. `/posts` to `authors/123#side`,
- * the `base_location` stored in router state is used so the route tree
- * keeps rendering the original `/posts` view underneath the dialog overlay.
- *
- * Additionally, registered views from `useNavigationStateController()` are
- * automatically routed — no need to manually map them to `<Route>` elements.
- * Views with `nestedRoutes: true` get a wildcard route (slug/*) as well.
- * Explicitly declared `children` routes take priority.
- */
-export function RebaseRoutes({ children }: { children?: React.ReactNode }) {
-    const location = useLocation();
-    const state = location.state as Record<string, unknown> | null;
-    const baseLocation = state?.base_location ?? location;
-
-    return <Routes location={baseLocation}>{children}</Routes>;
-}

package/src/core/index.tsx

@@ -1,5 +0,0 @@
-export * from "./Rebase";
-export * from "./PluginProviderStack";
-
-export * from "./RebaseRouter";
-export * from "./RebaseRoutes";

package/src/hooks/ApiConfigContext.tsx

@@ -1,83 +0,0 @@
-import React, { useContext } from "react";
-
-/**
- * Configuration for API connectivity. Passed once at the top level
- * and available to any hook that needs `apiUrl` or `getAuthToken`.
- *
- * Individual hooks can still accept explicit overrides — this context
- * serves as a fallback to eliminate repetitive threading.
- */
-export interface ApiConfig {
-    apiUrl: string;
-    /**
-     * The path the backend mounts its API under, appended to {@link apiUrl}.
-     *
-     * `"/api"` by default, which is the server's default `basePath`. It is
-     * carried here because a good deal of UI builds request URLs by hand
-     * instead of going through the client's typed methods, and every one of
-     * those sites used to write `/api` as a literal — so a backend configured
-     * with any other `basePath` served an admin panel whose auth-provider
-     * discovery, storage browser, history panel, user picker and Studio tools
-     * all requested paths that did not exist.
-     */
-    apiPath: string;
-    getAuthToken?: () => Promise<string | null>;
-}
-
-/** What the server uses when `basePath` is not configured. */
-export const DEFAULT_API_PATH = "/api";
-
-const ApiConfigContext = React.createContext<ApiConfig | undefined>(undefined);
-
-/**
- * Read the API config from context. Returns `undefined` if no provider is present,
- * allowing hooks to fall back to their own props.
- */
-export function useApiConfig(): ApiConfig | undefined {
-    return useContext(ApiConfigContext);
-}
-
-/**
- * `apiUrl` and `apiPath` joined, with no trailing slash — the prefix to build a
- * request URL from.
- *
- * Returns `undefined` when there is no provider, so a caller can keep its own
- * fallback rather than silently requesting a relative path.
- */
-export function useApiBase(): string | undefined {
-    const config = useApiConfig();
-    if (!config?.apiUrl) return undefined;
-    return config.apiUrl.replace(/\/+$/, "") + (config.apiPath || DEFAULT_API_PATH);
-}
-
-/**
- * The same prefix, derived from a client rather than from context.
- *
- * For the code that holds a `RebaseClient` but sits outside (or above) an
- * `ApiConfigProvider`. Returns `undefined` when the client has no base URL,
- * which is the signal every caller already treats as "cannot build a request".
- */
-export function apiBaseOf(client?: { baseUrl?: string; apiPath?: string }): string | undefined {
-    if (!client?.baseUrl) return undefined;
-    return client.baseUrl.replace(/\/+$/, "") + (client.apiPath || DEFAULT_API_PATH);
-}
-
-/**
- * Provide API configuration (apiUrl, apiPath, getAuthToken) to the entire subtree.
- * Typically rendered inside `<Rebase>` or at the app root.
- */
-export function ApiConfigProvider({
-    apiUrl,
-    apiPath = DEFAULT_API_PATH,
-    getAuthToken,
-    children
-}: Omit<ApiConfig, "apiPath"> & { apiPath?: string; children: React.ReactNode }) {
-    const value = React.useMemo(() => ({ apiUrl,
-apiPath,
-getAuthToken }), [apiUrl, apiPath, getAuthToken]);
-    return (
-        <ApiConfigContext.Provider value={value}>
-            {children}
-        </ApiConfigContext.Provider>
-    );
-}

package/src/hooks/data/collectionQuery.ts

@@ -1,55 +0,0 @@
-import type { FindParams, FilterValues, LogicalCondition, OrderBySpec } from "@rebasepro/types";
-
-/**
- * The one place a collection read's parameters are assembled.
- *
- * ## Why this exists
- *
- * Four call sites used to build this object by hand — `useCollection` and
- * `useDataTableController`, each in both their `listen` and `find` branches.
- * Every one of them listed the fields it forwarded, so adding an option to
- * `FindParams` meant remembering four places, and forgetting one failed
- * silently: the option simply never reached the server, and the feature it
- * enabled looked broken for reasons nowhere near the code that dropped it.
- *
- * That is not hypothetical. `searchExplain` was added to three of the four and
- * the miss was found by intercepting a WebSocket frame, because nothing else
- * could see it.
- *
- * A field added here reaches every read. `toFindParams` returns `FindParams`
- * itself, so the compiler checks the shape rather than a hand-copied list.
- */
-export interface CollectionQueryInput<M extends Record<string, unknown>> {
-    where?: FilterValues<Extract<keyof M, string>>;
-    logical?: LogicalCondition;
-    /**
-     * Loosened from `FindParams["orderBy"]` on purpose: callers hold the sort
-     * as plain `[string, direction]` pairs read off user config or a URL, where
-     * the columns are not statically known. Narrowing it here would push a cast
-     * onto every call site, which is the kind of friction that sends people back
-     * to hand-building the object this exists to replace.
-     */
-    orderBy?: OrderBySpec;
-    limit?: number;
-    offset?: number;
-    page?: number;
-    searchString?: string;
-    include?: string[];
-}
-
-/**
- * Build the parameters for one collection read.
- *
- * Derived options live here rather than at the call sites, so they cannot
- * disagree: `searchExplain` rides along exactly when there is a search string
- * to explain, which is also the only time it costs anything.
- */
-export function toFindParams<M extends Record<string, unknown>>(
-    input: CollectionQueryInput<M>
-): FindParams<M> {
-    const { searchString, ...rest } = input;
-    return {
-        ...rest,
-        ...(searchString ? { searchString, searchExplain: true } : {})
-    } as FindParams<M>;
-}

package/src/hooks/data/delete.ts

@@ -1,56 +0,0 @@
-
-import { Entity, CollectionCallbacks, User } from "@rebasepro/types";
-import { RebaseContext, AdminCollection } from "@rebasepro/cms-types";
-import { RebaseData } from "@rebasepro/types";
-
-/**
- * @group Hooks and utilities
- */
-export type DeleteEntityWithCallbacksProps<M extends Record<string, any>, USER extends User = User> = {
-    entity: Entity<M>;
-    collection?: AdminCollection<M>;
-    callbacks?: CollectionCallbacks<M, USER>;
-    onDeleteSuccess?: (entity: Entity<M>) => void;
-    onDeleteFailure?: (entity: Entity<M>, e: Error) => void;
-}
-
-/**
- * This function is in charge of deleting a entity.
- * It will run all the delete callbacks specified in the collection.
- * It is also possible to attach callbacks on save success or error, and callback
- * errors.
- *
- * @param data
- * @param entity
- * @param collection
- * @param callbacks
- * @param onDeleteSuccess
- * @param onDeleteFailure
- * @param context
- * @group Hooks and utilities
- */
-export async function deleteEntityWithCallbacks<M extends Record<string, any>, USER extends User>({
-    data,
-    entity,
-    collection,
-    callbacks,
-    onDeleteSuccess,
-    onDeleteFailure,
-    context
-}: DeleteEntityWithCallbacksProps<M> & {
-    collection: AdminCollection<M>,
-    data: RebaseData,
-    context: RebaseContext<USER>
-}
-): Promise<boolean> {
-
-    console.debug("Deleting entity", entity.path, entity.id);
-
-    return data.collection(entity.path).delete(entity.id).then(() => {
-        if (onDeleteSuccess) onDeleteSuccess(entity);
-        return true;
-    }).catch((e) => {
-        if (onDeleteFailure) onDeleteFailure(entity, e);
-        return false;
-    });
-}

package/src/hooks/data/save.ts

@@ -1,78 +0,0 @@
-
-import { Entity, EntityStatus, EntityValues } from "@rebasepro/types";
-import { RebaseContext, AdminCollection } from "@rebasepro/cms-types";
-import { RebaseData } from "@rebasepro/types";
-
-/**
- * @group Hooks and utilities
- */
-export type SaveEntityWithCallbacksProps<M extends Record<string, unknown>> = {
-    path: string;
-    values: Partial<EntityValues<M>>;
-    entityId?: string | number;
-    previousValues?: Partial<EntityValues<M>>;
-    collection?: AdminCollection<M>;
-    status: EntityStatus;
-    afterSave?: (updatedEntity: Entity<M>) => void,
-    afterSaveError?: (e: Error) => void
-}
-
-/**
- * This function is in charge of saving a entity.
- * It will run all the save callbacks specified in the collection.
- * It is also possible to attach callbacks on save success or error, and callback
- * errors.
- *
- * @param collection
- * @param path
- * @param entityId
- * @param callbacks
- * @param values
- * @param previousValues
- * @param status
- * @param data
- * @param context
- * @param afterSave
- * @param afterSaveError
- * @group Hooks and utilities
- */
-export async function saveEntityWithCallbacks<M extends Record<string, unknown>>({
-    collection,
-    path,
-    entityId,
-    values,
-    previousValues,
-    status,
-    data,
-    context,
-    afterSave,
-    afterSaveError
-}: Omit<SaveEntityWithCallbacksProps<M>, "collection"> & {
-    collection: AdminCollection<M>,
-    data: RebaseData,
-    context: RebaseContext,
-}
-): Promise<Entity<M>> {
-
-    if (status !== "new" && status !== "copy" && !entityId) {
-        throw new Error("Entity id must be specified when updating an existing entity");
-    }
-
-    const accessor = data.collection(path);
-
-    let savePromise: Promise<Entity<M>>;
-    if (status === "new" || status === "copy") {
-        savePromise = accessor.create(values, entityId) as Promise<Entity<M>>;
-    } else {
-        savePromise = accessor.update(entityId!, values) as Promise<Entity<M>>;
-    }
-
-    return savePromise.then((entity) => {
-        if (afterSave)
-            afterSave(entity);
-        return entity as Entity<M>;
-    }).catch((e) => {
-        if (afterSaveError) afterSaveError(e);
-        throw e;
-    });
-}