@rebasepro/app 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/hooks/data/collectionWindow.d.ts

@@ -17,6 +17,15 @@ export interface CollectionWindowState<M extends Record<string, unknown> = Recor
      * flashing a partial list.
      */
     rows: Entity<M>[] | undefined;
+    /**
+     * The same rows by position, with `undefined` where a row exists but has
+     * not been read — the rows above a scroll position the window was
+     * restored to ({@link CollectionWindowOptions.seed}), until the view
+     * scrolls to them. Absent when nothing is missing, which is always the
+     * case for a window no view reports a range to: `rows` is then complete
+     * from the first row.
+     */
+    sparse?: (Entity<M> | undefined)[];
     /** Rows not yet on screen are being read: the first page, or the next one. */
     loading: boolean;
     error: Error | undefined;
@@ -47,8 +56,38 @@ export interface CollectionWindowOptions<M extends Record<string, unknown>> {
      * The subscription still wins whenever it does answer.
      */
     firstPaintTimeoutMs?: number;
+    /**
+     * The quiet time kept between the end of one re-read of the rows past the
+     * first page and the start of the next. Defaults to
+     * {@link REREAD_INTERVAL_MS}. A push after a quiet spell is re-read at
+     * once; pushes inside this window fold into one re-read at its end.
+     */
+    rereadIntervalMs?: number;
+    /**
+     * Rows already known, from a view this window replaces (a scroll position
+     * kept while a record was open full screen): `rows` sit at `offset` and
+     * on. They are shown at once and read again only when a view reports
+     * them in range ({@link CollectionWindow.setVisibleRange}); the rows
+     * between the first page and `offset` are not read until a view scrolls
+     * to them. `target` should cover them.
+     */
+    seed?: {
+        offset: number;
+        rows: Entity<M>[];
+    };
     onChange: (state: CollectionWindowState<M>) => void;
 }
+/**
+ * The quiet time between two re-reads of the rows held past the first page.
+ *
+ * The server pushes at most once per ~300 ms of quiet per subscription, and at
+ * least once a second under a steady stream of writes; each push used to start
+ * a re-read of every held row past the first page as soon as the last one
+ * ended, so a table scrolled to 10,000 rows ran ten 1,000-row reads back to
+ * back for as long as the writes went on. This keeps the duty cycle bounded:
+ * at most one re-read per re-read time plus this.
+ */
+export declare const REREAD_INTERVAL_MS = 2000;
 /**
  * A scrolled collection view's rows, read one page at a time.
  *
@@ -72,14 +111,34 @@ export interface CollectionWindowOptions<M extends Record<string, unknown>> {
  *   view offers can express — a relevance-ordered search has no cursor — and
  *   because the server breaks ties on the id, so pages neither repeat nor skip
  *   rows under a sort with duplicates.
- * - **Realtime** covers every row held, not only the first page. The server
- *   re-runs a subscription on every write to its collection, so each push after
- *   the first says "something changed". The rows past the first page are then
- *   read again, in reads of at most `MAX_LIST_LIMIT`, and replaced in one step.
- *   Pushes that arrive while that re-read runs are folded into one more.
+ * - **Realtime.** The server re-runs a subscription on every write to its
+ *   collection, so each push after the first says "something changed", and
+ *   every row held past the first page is stale from then on. Which of them
+ *   are read again depends on whether a view says what it shows:
+ *   - A view that reports the rows it draws ({@link setVisibleRange}) has the
+ *     rows on screen read again, plus a page either side — one read, however
+ *     far it was scrolled. Rows further out stay stale and are read when they
+ *     come within half a page of the screen, before they are on it.
+ *   - Without a report, every row held is read again, in reads of at most
+ *     `MAX_LIST_LIMIT`, and replaced in one step — the only way a view that
+ *     cannot say what it shows never shows a stale row.
+ *   Either way a push after a quiet spell is re-read at once; pushes that
+ *   arrive while a re-read runs, or within `rereadIntervalMs` of the last one
+ *   ending, fold into one re-read at the end of that interval — at once if the
+ *   view asks for more rows or scrolls to rows not read since. The first page
+ *   itself is applied the moment it is pushed, as always.
  *
- * Rows are de-duplicated by id: between a push moving the first page and the
- * re-read of the rest, a row can briefly belong to both.
+ * Rows are de-duplicated by id, keeping the copy read last: an insert or a
+ * delete above shifts every offset by one, so between a push and the re-read
+ * of the rows it moved, a row can sit in two places — on the first page and in
+ * the stale row below it, or in the rows just re-read and the stale ones next
+ * to them.
+ *
+ * A window can hold **gaps**: a restored scroll position ({@link
+ * CollectionWindowOptions.seed}) shows the rows that were on screen without
+ * reading every row above them. A gap is read when a view scrolls to it; a
+ * window no view reports a range to reads its gaps at once and shows nothing
+ * until they are filled, as it would have read them all before.
  */
 export declare class CollectionWindow<M extends Record<string, unknown>> {
     private readonly accessor;
@@ -92,13 +151,26 @@ export declare class CollectionWindow<M extends Record<string, unknown>> {
     private head;
     /** The first page came back full, so there may be more past it. */
     private headFull;
-    /** Rows past the first page, from offset `pageSize` on. */
-    private tail;
-    /** The last read past the first page came back short. */
+    /**
+     * Rows past the first page: `slots[i]` is the row at offset
+     * `pageSize + i`, `undefined` where it has not been read (a gap).
+     */
+    private slots;
+    /** The last read reaching the end of the held rows came back short. */
     private tailEnded;
-    /** The first page changed after it first arrived: re-read the rest. */
-    private stale;
+    /** Moves on with every push after the first: rows read before it are stale. */
+    private version;
+    /**
+     * The offsets a view says it draws, end exclusive. `undefined` until one
+     * says so, and again when it goes: every held row is then kept current.
+     */
+    private range;
+    /** The view moved to rows not read since: read them without waiting. */
+    private rangeMoved;
+    /** Offset of each row (or gap) of the last state reported, by position. */
+    private emittedOffsets;
     private pumping;
+    private pumpQueued;
     private loadingMore;
     private headError;
     private tailError;
@@ -108,26 +180,87 @@ export declare class CollectionWindow<M extends Record<string, unknown>> {
     private liveAnswered;
     private unsubscribe;
     private firstPaintTimer;
+    /** When the last re-read of the rows past the first page finished. */
+    private lastRereadEndedAt;
+    /** A re-read waiting out {@link REREAD_INTERVAL_MS}. */
+    private rereadTimer;
     constructor(options: CollectionWindowOptions<M>);
     start(): void;
     /** Hold this many rows. Fewer than are held drops the rows past it. */
     setTarget(target: number): void;
+    /**
+     * The rows a view draws, by position in the last `rows` (or `sparse`) it
+     * was given, end exclusive; `undefined` when it stops drawing them. Rows
+     * near the range are kept current and gaps near it are read; see the
+     * class comment.
+     */
+    setVisibleRange(range: {
+        start: number;
+        end: number;
+    } | undefined): void;
+    /**
+     * What to keep of this window to show it again later: the rows read
+     * around the range a view last reported — or, with none reported, every
+     * row from the first — the offset of the first of them, and how many
+     * rows the window holds in all. See {@link CollectionWindowOptions.seed}.
+     */
+    snapshot(): {
+        offset: number;
+        rows: Entity<M>[];
+        held: number;
+    };
     dispose(): void;
     private readHeadOnce;
     private receiveLiveError;
     private receiveHead;
     /** Rows still wanted past the ones held. */
     private wanted;
+    private needsRead;
+    /**
+     * The held rows to read again now, by slot, or `undefined` if none.
+     *
+     * With a range: the stale rows and gaps within a page of it, once any of
+     * them is within half a page — so scrolling into stale rows reads a
+     * stretch of them ahead of the screen rather than one row per frame.
+     * Without: every stale row and gap, as one span.
+     */
+    private nextRefresh;
+    private schedulePump;
     /**
      * The one loop that reads past the first page, so a re-read and a next page
      * never run at the same time and interleave their offsets.
      */
     private pump;
+    /** How long a re-read due now still has to wait. 0 after a quiet spell. */
+    private rereadWait;
+    private armReread;
     private readNext;
-    /** Read every held row past the first page again, and swap them in at once. */
+    /**
+     * Read the held rows in slots `[from, to)` again, and swap them in at once.
+     * A read that comes back short says where the collection ends now: the
+     * rows held past that are dropped.
+     */
     private reread;
+    /**
+     * Every one-shot read the window makes: its query, never counted.
+     *
+     * Nothing here reads `meta.total` — a page ends the window by coming back
+     * short — and the `COUNT(*)` beside each page read every matching row to
+     * report a number that was thrown away: scrolling a table to 10,000 rows
+     * ran 199 of them. The first page's subscription is the accessor's and is
+     * left as it is.
+     */
+    private oneShot;
     private process;
     private complete;
+    private hasGaps;
     private emit;
+    /**
+     * The rows to show, in order, each id once — the copy read last wins, the
+     * first page counting as read now — with gaps kept as positions in
+     * `sparse`, and the offset each position stands for.
+     */
     private rows;
+    /** Positions in the last state reported, as offsets in the collection. */
+    private toOffsets;
 }

package/dist/hooks/data/save.d.ts

@@ -11,6 +11,13 @@ export type SaveEntityWithCallbacksProps<M extends Record<string, unknown>> = {
     previousValues?: Partial<EntityValues<M>>;
     collection?: AdminCollection<M>;
     status: EntityStatus;
+    /**
+     * The version the edit was made against — the edited entity's
+     * {@link Entity.etag}. An update is then refused with `412
+     * PRECONDITION_FAILED` if the record has changed since, rather than
+     * writing over the change. Ignored for a create.
+     */
+    ifMatch?: string;
     afterSave?: (updatedEntity: Entity<M>) => void;
     afterSaveError?: (e: Error) => void;
 };
@@ -33,7 +40,9 @@ export type SaveEntityWithCallbacksProps<M extends Record<string, unknown>> = {
  *
  * `afterSave`/`afterSaveError` below are the *caller's* UI callbacks — the
  * form's "close the dialog", the table's "clear the editing state" — and are
- * unrelated to the collection's. Both run: the collection's first.
+ * unrelated to the collection's. Both run: the collection's first. A
+ * collection `afterSave` that throws does not undo the save: the write has
+ * committed, so it is reported as a warning and the caller's `afterSave` runs.
  *
  * @param collection
  * @param path
@@ -47,7 +56,7 @@ export type SaveEntityWithCallbacksProps<M extends Record<string, unknown>> = {
  * @param afterSaveError
  * @group Hooks and utilities
  */
-export declare function saveEntityWithCallbacks<M extends Record<string, unknown>>({ collection, path, entityId, values, previousValues, status, data, context, afterSave, afterSaveError }: Omit<SaveEntityWithCallbacksProps<M>, "collection"> & {
+export declare function saveEntityWithCallbacks<M extends Record<string, unknown>>({ collection, path, entityId, values, previousValues, status, ifMatch, data, context, afterSave, afterSaveError }: Omit<SaveEntityWithCallbacksProps<M>, "collection"> & {
     collection: AdminCollection<M>;
     data: RebaseData;
     context: RebaseContext;

package/dist/hooks/data/useBatchedFetch.d.ts

@@ -0,0 +1,21 @@
+import type { AdminCollection } from "@rebasepro/cms-types";
+import type { FetchResult } from "./useFetch.js";
+/**
+ * {@link useFetch} for a record many previews on one screen ask for at once —
+ * the target of a reference in a table cell, a card, an array of references.
+ *
+ * The ids every preview asks for in one tick are read together: one query and
+ * one live subscription per batch, not one `listenById` per record. Updates
+ * reach a preview per batch — a write to any record of the batch refetches the
+ * batch — which is what a preview needs.
+ *
+ * For one record a view edits, use {@link useFetch}: it follows that record
+ * alone and seeds from the record cache.
+ *
+ * @group Hooks and utilities
+ */
+export declare function useBatchedFetch<M extends Record<string, any>>({ path, entityId, collection }: {
+    path: string;
+    entityId?: string | number;
+    collection: AdminCollection<M>;
+}): FetchResult<M>;

package/dist/hooks/data/useDataOrder.d.ts

@@ -5,6 +5,12 @@ export interface DataOrderProps<M extends Record<string, any>> {
 }
 /**
  * This hook is used to have some entities at the beginning of data.
+ *
+ * The result is the same array until `data` or `entitiesDisplayedFirst`
+ * changes. It used to be rebuilt on every call whenever rows were pinned, so
+ * the table controller around it — and everything rendering from that — was
+ * new on every render.
+ *
  * @param path
  * @param entitiesDisplayedFirst
  * @group Hooks and utilities

package/dist/hooks/data/useFetch.d.ts

@@ -9,6 +9,14 @@ export interface FetchProps<M extends Record<string, any>, USER extends User = U
     databaseId?: string;
     collection: AdminCollection<M, USER>;
     useCache?: boolean;
+    /**
+     * Load the collection's relation properties into the record, as a list
+     * read loads them into each row. The record views ask for it: a form built
+     * on a record without them shows a many-to-many field empty, and saving it
+     * sets that empty membership. A preview leaves it off, since it would load
+     * every related row of the record it previews.
+     */
+    relations?: boolean;
 }
 /**
  * @group Hooks and utilities
@@ -19,9 +27,9 @@ export interface FetchResult<M extends Record<string, any>> {
     dataLoadingError?: Error;
 }
 /**
- * Pre-populate the entity fetch cache with entities loaded from a collection.
- * This allows entity detail views to render instantly using cached data,
- * while the background fetch/listener brings in fresh data.
+ * Put records in the entity fetch cache, so a view that opens one renders it at
+ * once while the background fetch/listener brings in fresh data. The cache
+ * keeps the 2,000 records written or read most recently.
  * @param path - The collection path (e.g. "products")
  * @param entities - Array of entities to cache
  */
@@ -40,4 +48,4 @@ export declare function clearFetchCache(): void;
  * @param useCache
  * @group Hooks and utilities
  */
-export declare function useFetch<M extends Record<string, any>, USER extends User = User>({ path, entityId, collection, databaseId, useCache }: FetchProps<M, USER>): FetchResult<M>;
+export declare function useFetch<M extends Record<string, any>, USER extends User = User>({ path, entityId, collection, databaseId, useCache, relations }: FetchProps<M, USER>): FetchResult<M>;

package/dist/hooks/index.d.ts

@@ -2,6 +2,7 @@ export * from "./data/useData.js";
 export * from "./data/useCollection.js";
 export * from "./data/collectionWindow.js";
 export * from "./data/useFetch.js";
+export * from "./data/useBatchedFetch.js";
 export * from "./data/useRelationSelector.js";
 export * from "./data/save.js";
 export * from "./data/delete.js";
@@ -26,7 +27,6 @@ export * from "./useCustomizationController.js";
 export * from "./useBuildLocalConfigurationPersistence.js";
 export * from "./useBuildModeController.js";
 export * from "./useRebaseRegistry.js";
-export * from "./useBackendStorageSource.js";
 export * from "./usePermissions.js";
 export * from "./ApiConfigContext.js";
 export * from "./useTranslation.js";

package/dist/hooks/useBuildModeController.d.ts

@@ -1,6 +1,26 @@
 import type { ModeController } from "./useModeController.js";
+/**
+ * @group Hooks and utilities
+ */
+export interface BuildModeControllerOptions {
+    /**
+     * `false` builds a controller that touches nothing outside React: no `dark`
+     * class on `<html>`, no `prefers-color-scheme` listener, no localStorage.
+     * `<Rebase>` passes it when the host app hands over its own
+     * `modeController`. Defaults to `true`.
+     */
+    enabled?: boolean;
+}
 /**
  * Use this hook to build a color mode controller that determines
- * the theme of the admin
+ * the theme of the admin.
+ *
+ * While enabled it owns the page's theme: it puts the `dark` class on
+ * `document.documentElement`, follows `prefers-color-scheme` until the user
+ * picks a mode, and remembers that pick in localStorage. When the component
+ * using it unmounts, it takes away the `dark` class if it was the one that
+ * added it.
+ *
+ * @group Hooks and utilities
  */
-export declare function useBuildModeController(): ModeController;
+export declare function useBuildModeController(options?: BuildModeControllerOptions): ModeController;

package/dist/hooks/useComponentOverride.d.ts

@@ -3,15 +3,18 @@ import type { OverridableComponentName } from "@rebasepro/cms-types";
 /**
  * Resolves a potentially overridden component.
  *
- * Resolution order:
- * 1. Collection-scoped override (highest priority)
- * 2. Global override
- * 3. Default component (fallback)
+ * The two scopes compose, innermost first:
+ * 1. Default component
+ * 2. Global override (`<Rebase components>`), applied to the default
+ * 3. Collection-scoped override (`admin.components`), applied to the result
+ *    of 2
  *
  * Supports two override modes:
- * - **Eject** (default): The override component fully replaces the default.
- * - **Wrap** (`wrap: true`): The override component wraps the default.
- *   The default is passed as `OriginalComponent` in props.
+ * - **Eject** (default): The override component fully replaces what it is
+ *   applied to.
+ * - **Wrap** (`wrap: true`): The override component wraps what it is applied
+ *   to, passed as `OriginalComponent` in props — so a collection's wrapper
+ *   wraps the global override when there is one, not the built-in default.
  *
  * @param name - The overridable component name (e.g. `"Entity.Form"`)
  * @param DefaultComponent - The built-in default component

package/dist/hooks/useNavigationBlocker.d.ts

@@ -1,17 +1,25 @@
 import React from "react";
 import { Blocker, BlockerFunction } from "react-router";
 /**
- * Owns the single React Router blocker for the whole app.
+ * Owns the single navigation guard for the whole app.
  *
- * React Router only honours **one** blocker at a time: `shouldBlockNavigation`
- * picks the last-registered blocker function and silently ignores every other
- * one (it only logs a dev warning). Because blockers register in a `useEffect`,
- * the winner is whichever surface mounted most recently — so an unsaved-changes
- * guard could be disabled by an unrelated component mounting after it.
+ * Under a React Router **data router** (`createBrowserRouter` +
+ * `<RouterProvider>`) it holds the one `useBlocker` in the tree. React Router
+ * only honours one blocker at a time: `shouldBlockNavigation` picks the
+ * last-registered blocker function and silently ignores every other one (it
+ * only logs a dev warning). Because blockers register in a `useEffect`, the
+ * winner is whichever surface mounted most recently — so an unsaved-changes
+ * guard could be disabled by an unrelated component mounting after it. This
+ * provider registers the only one and multiplexes it, so every surface that
+ * guards navigation gets a say regardless of mount order.
  *
- * This provider registers the only `useBlocker` in the tree and multiplexes it,
- * so every surface that needs to guard navigation gets a say regardless of
- * mount order. Surfaces register through {@link useNavigationBlocker}.
+ * Under any **other** router (a plain `<BrowserRouter>`, a `<MemoryRouter>`)
+ * there is no `useBlocker` to call — it throws outside a data router — and no
+ * way to intercept an in-app navigation. The guards then degrade to the
+ * browser's own: leaving the page (reload, tab close, typing a URL) asks for
+ * confirmation while any registered guard would block leaving.
+ *
+ * Surfaces register through {@link useNavigationBlocker}.
  */
 export declare function NavigationBlockerProvider({ children }: {
     children: React.ReactNode;

package/dist/index.d.ts

@@ -13,7 +13,6 @@ export type { RebaseStorageSource } from "./core/RebaseProps.js";
 export { UnsavedChangesDialog } from "./components/UnsavedChangesDialog.js";
 export * from "./i18n/RebaseI18nProvider.js";
 export * from "./locales/en.js";
-export * from "./locales/es.js";
 export * from "./hooks/useStudioBridge.js";
 export { useBridgeRegistration } from "./hooks/useBridgeRegistration.js";
 export * from "./collections/index.js";