@rebasepro/app 0.13.0 → 0.13.1-canary.g06dbe5b

package/dist/collections/entity-display-cache.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The store behind a computed display value.
+ *
+ * A record's title is asked for far more often than it changes, and by many
+ * components at once: a list of fifty rows, each row's relation chips, the
+ * breadcrumb above them. Resolving per component is what makes an async display
+ * value a bad idea — fifty rows becomes fifty reads, then fifty more on the next
+ * render.
+ *
+ * So resolution is keyed by record *and* role, in-flight calls are shared, and
+ * results are kept until something says otherwise. Deliberately not a React
+ * thing: the same store answers an imperative caller (an export, a breadcrumb
+ * built outside the tree), and it is testable without a renderer.
+ */
+import type { EntityDisplayRole } from "@rebasepro/admin-types";
+export type EntityDisplayKey = string;
+/** The identity of one role of one record, as a cache key. */
+export declare function entityDisplayKey(path: string, entityId: string | number | undefined, role: EntityDisplayRole): EntityDisplayKey;
+export declare class EntityDisplayCache {
+    private readonly entries;
+    private readonly listeners;
+    /**
+     * The resolved value, or `undefined` when this pair has not been resolved
+     * yet. `null` is a resolved absence, and the two must stay distinct: a
+     * caller that reads "not yet" as "nothing" flickers its fallback in on every
+     * mount.
+     */
+    peek(key: EntityDisplayKey): unknown | undefined;
+    /** True while a resolution for this pair is in flight. */
+    isLoading(key: EntityDisplayKey): boolean;
+    /**
+     * Resolve once per record and role. Concurrent callers share the first
+     * call's promise; later callers get the cached value with no promise at all.
+     *
+     * A resolver that throws is recorded as "nothing" rather than retried: the
+     * alternative is every render re-running a call that just failed. And it is
+     * reported here, which is a correction.
+     *
+     * It used to say "the caller that saw the rejection is the one that logs
+     * it", and `useEntityDisplay` duly attached a `.catch()` that warned. But
+     * both failure paths below swallow and return a *resolved* promise, so that
+     * catch could never run — the two halves each did the reasonable thing and
+     * between them the log was unreachable. A resolver that blew up produced a
+     * blank chip and total silence, which is the failure mode
+     * `EntityDisplayResolver`'s own contract ("treated as `undefined` and logged
+     * once") exists to rule out.
+     *
+     * Reporting belongs here for the reason the caller could not do it: this is
+     * the one place that runs exactly once per key, so "once" is a property of
+     * the code rather than a hope about how many components mount.
+     */
+    resolve(key: EntityDisplayKey, resolver: () => unknown): Promise<unknown>;
+    /**
+     * Drop what is known about a record, so the next ask resolves again. Called
+     * after a write: the row that just saved may be called something else now.
+     */
+    invalidate(path: string, entityId?: string | number): void;
+    /** Drop everything. The user signed out, or the app swapped datasource. */
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    private set;
+    /**
+     * Record a failed resolution as "nothing", and say so once.
+     *
+     * The key is the message: it is `<role> <path> <id>`, which is exactly what a
+     * reader needs to find the resolver that blew up. A warning with no key would
+     * tell them a display resolver failed somewhere in a list of fifty rows.
+     *
+     * `console.warn` rather than a thrown error, because this runs while a row is
+     * rendering: the contract is that a title which cannot be fetched must not
+     * take down the row that shows it.
+     */
+    private fail;
+    private emit;
+}

package/dist/collections/entity-display.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reading a collection's `display` block.
+ *
+ * Two questions, kept apart because they are answered at different times: which
+ * *property* fills a role (readable from values already in hand) and which
+ * *resolver* fills it (may have to go to the network). A caller that cannot
+ * await — a sort comparator, an export column, a server render — uses the key
+ * and is documented to ignore resolvers.
+ */
+import type { AdminCollection, EntityDisplayResolver, EntityDisplayRole } from "@rebasepro/admin-types";
+/**
+ * The property path a role is declared to read, when it is declared as a path.
+ *
+ * Returns `undefined` for a role filled by a resolver — a resolver has no key —
+ * and for a role the collection says nothing about, which is then derived.
+ *
+ * @group Collections
+ */
+export declare function getDisplayPropertyKey<M extends Record<string, unknown>>(collection: AdminCollection<M>, role: EntityDisplayRole): string | undefined;
+/**
+ * The resolver a role is declared to use, when it is declared as one.
+ *
+ * @group Collections
+ */
+export declare function getDisplayResolver<M extends Record<string, unknown>>(collection: AdminCollection<M>, role: EntityDisplayRole): EntityDisplayResolver<M, unknown> | undefined;
+/**
+ * True when the collection states this role at all, in either form.
+ *
+ * The derivation is a guess about what a collection probably means; a statement
+ * outranks it, and the heuristics that look for "the first enum" or "the leading
+ * relation" have to stand down when one exists.
+ *
+ * @group Collections
+ */
+export declare function hasDeclaredDisplay<M extends Record<string, unknown>>(collection: AdminCollection<M>, role: EntityDisplayRole): boolean;

package/dist/collections/entity_image_preview.d.ts

@@ -1,2 +1,10 @@
 import { CollectionConfig } from "@rebasepro/types";
+/**
+ * The property that fills a record's image slot.
+ *
+ * `admin.display.image` first, then six fallbacks in descending confidence —
+ * the first image-typed storage property, an array of them, a URL rendered as an
+ * image, and so on. The ladder stays for collections that say nothing; a
+ * collection that names its picture is not guessed at.
+ */
 export declare function getEntityImagePreviewPropertyKey<M extends Record<string, unknown>>(collection: CollectionConfig<M>): string | undefined;

package/dist/collections/form-layout.d.ts

@@ -34,6 +34,12 @@ export interface ResolvedFormSection {
     /** Initial state only; the form owns it after first interaction. */
     collapsed: boolean;
     fields: ResolvedFormField[];
+    /**
+     * Declared arrangement for the read-only view. Carried through untouched —
+     * the resolver decides *which* fields a section holds, not how the surface
+     * that renders it stacks them, and only the read view honours this.
+     */
+    readVariant?: "grid" | "summary";
 }
 export interface ResolvedFormLayout {
     sections: ResolvedFormSection[];

package/dist/collections/index.d.ts

@@ -1,9 +1,13 @@
 export * from "./collection_view_config";
 export * from "./entity_image_preview";
+export * from "./entity-display";
+export * from "./entity-display-cache";
 export * from "./filter-operator-resolution";
 export * from "./form-layout";
 export * from "./navigation_from_path";
 export * from "./navigation_utils";
 export * from "./parent_references_from_path";
+export * from "./property-path";
 export * from "./property_presentation";
+export * from "./summary-property";
 export * from "./title-property";

package/dist/collections/property-path.d.ts

@@ -0,0 +1,16 @@
+import type { Properties, Property } from "@rebasepro/types";
+/**
+ * The property at a dotted path, walking `map` children — `address.street`.
+ *
+ * The value counterpart is `getValueInPath` in `@rebasepro/utils`; this is the
+ * schema half, and the two have to be used together. Reading a dotted path off
+ * an entity while looking its property up with a flat `properties[path]` gives
+ * the value and `undefined` for how to render it, which is how a declared title
+ * on a nested field silently fell back to a derived one.
+ *
+ * There were three copies of this: one private to `useColumnsIds`, one exported
+ * from the admin layer, and the flat lookup in the title resolver that was not
+ * this function at all. This is the one, in the lowest layer that needs it —
+ * admin re-exports it under the name it already published.
+ */
+export declare function getPropertyInPath(properties: Properties, path: string): Property | undefined;

package/dist/collections/property_presentation.d.ts

@@ -10,11 +10,26 @@
  * That last one is worth knowing about rather than assuming: the collection editor
  * has a whole Conditions UI, `serializable_utils` persists what it writes, and
  * `BaseProperty.conditions` documents itself as "evaluated at runtime like property
- * builders" — but the evaluator below is reached only from its own tests. The
- * declarative conditions feature is authored and stored, never applied. It lives
- * here now because here is where it would be called from once it is wired up.
+ * builders" — but the evaluator below is reached only from its own tests. It lives
+ * here because here is where it would be called from once it is wired up.
+ *
+ * The one part of `conditions` that *is* applied is the literal case:
+ * `hidden`/`readOnly`/`disabled` stated as a plain boolean rather than as a rule.
+ * A literal needs no context, so `isHidden`/`isReadOnly`/`isDisabled` can answer
+ * it directly, and those three gates are consulted everywhere a field is laid
+ * out. A *rule* still is not evaluated anywhere in production — the split is
+ * deliberate, not an oversight: it is the difference between a condition that
+ * needs an entity to be evaluated against and one that does not.
  */
 import type { ConditionContext, Property } from "@rebasepro/types";
 export declare function isReadOnly(property: Property): boolean;
 export declare function isHidden(property: Property): boolean;
+/**
+ * Whether the field is disabled by its own declaration, ignoring form state.
+ *
+ * The `admin.disabled` block and `conditions.disabled: true` say the same thing
+ * two ways, so every caller that gated on the first now asks here instead of
+ * growing a second check of its own.
+ */
+export declare function isDisabled(property: Property): boolean;
 export declare function applyPropertyConditions(property: Property, context: ConditionContext): Property;

package/dist/collections/summary-property.d.ts

@@ -0,0 +1,65 @@
+import type { Property } from "@rebasepro/types";
+/**
+ * Whether a property can stand in for a record in *one line*.
+ *
+ * Preview surfaces — the reference card, a list row, a board card — have a
+ * single line per property and no way to grow. That is a constraint on the
+ * *value*, not on the property's importance: a Markdown biography is the most
+ * interesting column on an author, and it is still the wrong thing to paste
+ * into a 44px card. Ranking it here means the picker can skip it without
+ * anyone having to configure their way out of a broken card.
+ *
+ * Kept beside {@link getTitlePropertyCandidates} because the two answer
+ * neighbouring questions — "what is this record called" and "what else can be
+ * said about it in a line" — from the same property schema.
+ *
+ * @group Collections
+ */
+export declare const SUMMARY_RANK: {
+    /**
+     * No single-line form exists. A map renders as a key/value table and an
+     * array of maps as a stack of them; there is no first line to take.
+     */
+    readonly UNUSABLE: 0;
+    /**
+     * Readable in one line, but only as an excerpt — the property holds a
+     * document, and the line is its opening. Worth showing when nothing better
+     * is available, never in preference to a value that fits whole.
+     */
+    readonly EXCERPT: 1;
+    /** Short and self-contained: the line *is* the value. */
+    readonly DIRECT: 2;
+};
+/** One of the three summary ranks. */
+export type SummaryRank = typeof SUMMARY_RANK[keyof typeof SUMMARY_RANK];
+/**
+ * File-storage backed content (single image, array of images, generic upload…).
+ * Preview surfaces give these their own image slot, so they are never also a
+ * text line.
+ *
+ * @group Collections
+ */
+export declare function isStorageProperty(property: Property | undefined): boolean;
+/**
+ * True when the property holds free text long enough to be a document rather
+ * than a value — Markdown, or an explicitly multi-line string.
+ *
+ * @group Collections
+ */
+export declare function isLongTextProperty(property: Property | undefined): boolean;
+/**
+ * How well a property reads as one line of a preview. See {@link SUMMARY_RANK}.
+ *
+ * Decided from the property *schema* only: no values are consulted, so the
+ * answer is stable for a collection and can be memoised per collection rather
+ * than per row.
+ *
+ * @group Collections
+ */
+export declare function rankSummaryProperty(property: Property | undefined): SummaryRank;
+/**
+ * True when the property has any single-line form at all.
+ *
+ * @group Collections
+ */
+export declare function canSummariseProperty(property: Property | undefined): boolean;

package/dist/components/LoginView/oauth-redirect-flow.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The browser half of the OAuth authorization-code flow.
+ *
+ * The server only ever sees a `code` and a `redirectUri` taken from the
+ * request body, so `state`, PKCE and the binding between "this browser started
+ * a login" and "this code came back" are, by construction, the client's job.
+ * In the admin login they had been nobody's job: the authorize URL carried no
+ * `state`, and the return leg accepted any `?code=` as long as a localStorage
+ * marker naming the *provider* was set — a marker written on button click and
+ * removed only on a callback that carried a code, so abandoning the flow left
+ * it set indefinitely.
+ *
+ * Everything here is provider-agnostic on purpose. A button that wants a new
+ * provider calls {@link startOAuthRedirect} and gets state, expiry and PKCE
+ * without deciding anything, which is what stops the next provider shipping
+ * without them.
+ */
+export interface OAuthRedirectRequest {
+    /** Provider id, as mounted at `POST /auth/<id>`. */
+    provider: string;
+    /** The provider's authorization endpoint. */
+    authorizeUrl: string;
+    clientId: string;
+    scope: string;
+    /** Where the provider sends the browser back. Echoed to the token exchange. */
+    redirectUri: string;
+    /** Set when the provider implements PKCE. */
+    pkce?: boolean;
+    /** Extra authorize-endpoint parameters (`response_type`, and so on). */
+    params?: Record<string, string>;
+}
+/** What the browser remembers between leaving for the provider and coming back. */
+export interface PendingOAuthRedirect {
+    provider: string;
+    state: string;
+    codeVerifier?: string;
+    redirectUri: string;
+    startedAt: number;
+}
+export type OAuthCallbackResult = 
+/** No OAuth callback in this URL. */
+{
+    status: "none";
+}
+/** The provider reported a failure, or the user declined. */
+ | {
+    status: "error";
+    error: string;
+}
+/**
+ * A code arrived that this browser cannot account for: no pending
+ * authorization, an expired one, or a `state` that does not match. This is
+ * what a login-CSRF / code-injection attempt looks like.
+ */
+ | {
+    status: "mismatch";
+} | {
+    status: "ok";
+    provider: string;
+    code: string;
+    codeVerifier?: string;
+    redirectUri: string;
+};
+type Storage = Pick<globalThis.Storage, "getItem" | "setItem" | "removeItem">;
+export declare function readPendingOAuthRedirect(storage?: Storage | null): PendingOAuthRedirect | null;
+export declare function clearPendingOAuthRedirect(storage?: Storage | null): void;
+/**
+ * Build the authorize URL and the pending record that will validate its
+ * callback. Split out from {@link startOAuthRedirect} so it can be tested
+ * without navigating.
+ */
+export declare function buildOAuthAuthorization(request: OAuthRedirectRequest, now?: number): Promise<{
+    url: string;
+    pending: PendingOAuthRedirect;
+}>;
+/** Remember the authorization and send the browser to the provider. */
+export declare function startOAuthRedirect(request: OAuthRedirectRequest, storage?: Storage | null): Promise<void>;
+/**
+ * Interpret a return from the provider.
+ *
+ * Clears the pending record on **every** path that saw a callback — including
+ * `?error=` and a state mismatch — so a declined or abandoned consent screen
+ * cannot leave the browser primed to accept somebody else's code later.
+ */
+export declare function consumeOAuthCallback(search: string, storage?: Storage | null, now?: number): OAuthCallbackResult;
+export {};

package/dist/components/common/useColumnsIds.d.ts

@@ -5,6 +5,28 @@ export type PropertyColumnConfig = {
     disabled: boolean;
 };
 export declare function getSubcollectionColumnId(collection: AdminCollection<any>): string;
+/**
+ * The jump-to-tab columns a collection table does not need, because the relation
+ * behind them already has a column of its own.
+ *
+ * Every child view gets a 200px button column that opens its tab. For a relation
+ * declared in `relations` that button is the relation's only presence in the
+ * table. For one declared as a property it is the second: the property's own
+ * column is already there, hydrated by the list fetch's `include: ["*"]`, showing
+ * the child rows themselves — and carrying the *same heading*, because the tab
+ * takes its name from the declaring property. Two columns called "Applications",
+ * one of them a button, and nothing in the header to tell them apart.
+ *
+ * The property column wins: it shows what the children are, and each chip in it
+ * opens one. The tab stays reachable by opening the record, which is what the
+ * rest of the table's rows do anyway.
+ *
+ * Unless the author hid that column — `hideFromCollection` on the property, or a
+ * `propertiesOrder` that omits it, is a statement about the column and not about
+ * the relation, so the button comes back rather than the relation dropping out
+ * of the table altogether.
+ */
+export declare function getRedundantChildViewColumnIds<M extends Record<string, any>>(collection: AdminCollection<M>): Set<string>;
 export declare function useColumnIds<M extends Record<string, any>>(collection: AdminCollection<M>, includeSubcollections: boolean): PropertyColumnConfig[];
 export declare function getColumnKeysForProperty(property: Property, key: string, disabled?: boolean): PropertyColumnConfig[];
 export declare function getFormFieldKeys(collection: AdminCollection): string[];

package/dist/core/Rebase.d.ts

@@ -12,4 +12,4 @@ import { User } from "@rebasepro/types";
  *
  * @group Core
  */
-export declare function Rebase<USER extends User>(props: RebaseProps<USER>): React.JSX.Element;
+export declare function Rebase<USER extends User, DB = unknown>(props: RebaseProps<USER, DB>): React.JSX.Element;

package/dist/core/RebaseProps.d.ts

@@ -99,7 +99,7 @@ import type { EffectiveRoleController } from "@rebasepro/types";
  *
  * @group Models
  */
-export type RebaseProps<USER extends User> = {
+export type RebaseProps<USER extends User, DB = unknown> = {
     /**
      * The root components of your application. Use RebaseAdmin, RebaseStudio, and RebaseShell.
      * Alternatively, pass a render function that receives { context, loading }.
@@ -140,8 +140,16 @@ export type RebaseProps<USER extends User> = {
      * 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;
+    client?: RebaseClient<DB>;
     /**
      * The data sources of the app. Each entry pairs a
      * {@link DataSourceDefinition} (key, engine, transport) with an optional

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

@@ -0,0 +1,45 @@
+import type { FindParams, FilterValues, LogicalCondition } 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 a plain `[string, direction]` read off user config or a URL, where the
+     * column is 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?: [string, "asc" | "desc"];
+    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 declare function toFindParams<M extends Record<string, unknown>>(input: CollectionQueryInput<M>): FindParams<M>;

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

@@ -36,6 +36,17 @@ export interface UseRelationSelectorProps<M extends Record<string, any> = any> {
      * Property name to use as the secondary display field
      */
     descriptionProperty?: keyof M;
+    /**
+     * Whether the list should be fetched at all. Defaults to `true`.
+     *
+     * A picker that is mounted is not a picker that is open, and the two used
+     * to be the same thing here: the fetch ran on mount, so a collection table
+     * with a relation column paid for one query — or one realtime subscription
+     * — per rendered row before anyone clicked a cell. Pass `false` until the
+     * list is actually needed and nothing is requested; flipping it to `true`
+     * fetches once, and it never goes back.
+     */
+    enabled?: boolean;
 }
 export interface RelationSelectorController {
     items: RelationItem[];
@@ -49,4 +60,4 @@ export interface RelationSelectorController {
 /**
  * Hook to manage relation selection with data fetching from Rebase data source
  */
-export declare function useRelationSelector<M extends Record<string, any> = any>({ path, collection, fixedFilter, pageSize, getLabelFromEntity, getDescriptionFromEntity, descriptionProperty }: UseRelationSelectorProps<M>): RelationSelectorController;
+export declare function useRelationSelector<M extends Record<string, any> = any>({ path, collection, fixedFilter, pageSize, getLabelFromEntity, getDescriptionFromEntity, descriptionProperty, enabled }: UseRelationSelectorProps<M>): RelationSelectorController;