@rebasepro/app 0.0.1-canary.4829d6e

package/src/core/RebaseProps.tsx

@@ -0,0 +1,320 @@
+import React from "react";
+import { Locale, User, AuthController, AnalyticsEvent, DataDriver, DataSourceDefinition, StorageSource, StorageSourceDefinition, UserConfigurationPersistence, CollectionRegistryController, DatabaseAdmin, UrlController, NavigationStateController, RebaseClient, RebaseContext, EntityLinkBuilder, RebasePlugin, SlotContribution, PropertyConfig, EntityCustomView, EntityAction, RebaseTranslations, ComponentOverrideMap } from "@rebasepro/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 interface EffectiveRoleController {
+    effectiveRole: string | null;
+    setEffectiveRole: (role: string | null) => void;
+}
+
+
+/**
+ * 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> = {
+
+    /**
+     * The root components of your application. Use RebaseAdmin, 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 CMS 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 CMS.
+     * Defaults to 'MMMM dd, yyyy, HH:mm:ss'
+     */
+    dateTimeFormat?: string;
+
+    /**
+     * Locale of the CMS, 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.
+     */
+    client?: RebaseClient;
+
+    /**
+     * 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 CMS
+     */
+    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 CMS
+     */
+    plugins?: RebasePlugin[];
+
+    /**
+     * Extra slots for the CMS
+     */
+    slots?: SlotContribution[];
+
+    /**
+     * Property configs (widgets)
+     */
+    propertyConfigs?: Record<string, PropertyConfig>;
+
+    /**
+     * Entity Views
+     */
+    entityViews?: EntityCustomView[];
+
+    /**
+     * 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

@@ -0,0 +1,17 @@
+import { createBrowserRouter, RouterProvider } from "react-router-dom"
+import { removeInitialAndTrailingSlashes } from "@rebasepro/common";
+
+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

@@ -0,0 +1,24 @@
+import React from "react";
+import { Route, Routes, useLocation } from "react-router-dom";
+
+
+/**
+ * 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

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

package/src/hooks/ApiConfigContext.tsx

@@ -0,0 +1,41 @@
+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;
+    getAuthToken?: () => Promise<string | null>;
+}
+
+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);
+}
+
+/**
+ * Provide API configuration (apiUrl, getAuthToken) to the entire subtree.
+ * Typically rendered inside `<Rebase>` or at the app root.
+ */
+export function ApiConfigProvider({
+    apiUrl,
+    getAuthToken,
+    children
+}: ApiConfig & { children: React.ReactNode }) {
+    const value = React.useMemo(() => ({ apiUrl,
+getAuthToken }), [apiUrl, getAuthToken]);
+    return (
+        <ApiConfigContext.Provider value={value}>
+            {children}
+        </ApiConfigContext.Provider>
+    );
+}

package/src/hooks/data/delete.ts

@@ -0,0 +1,55 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import { Entity, CollectionCallbacks, RebaseContext, User } from "@rebasepro/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?: CollectionConfig<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: CollectionConfig<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

@@ -0,0 +1,77 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import { Entity, EntityStatus, EntityValues, RebaseContext } from "@rebasepro/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?: CollectionConfig<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
+}: SaveEntityWithCallbacksProps<M> & {
+    collection: CollectionConfig,
+    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;
+    });
+}