@rebasepro/app 0.13.0 → 0.13.1-canary.g18cfeb7

package/dist/util/entity_cache.d.ts

@@ -1,15 +1,31 @@
 /**
- * Saves data to the in-memory cache and persists it individually in `sessionStorage`.
+ * Saves data to the local-changes backup in `sessionStorage`.
+ *
+ * The backup only — a draft that survives a reload is not an edit in flight.
+ * {@link saveEntityToMemoryCache} is the other channel; see {@link entityCache}
+ * for what separates them.
  * @param path - The unique path/key for the data.
  * @param data - The data to cache and persist.
  */
 export declare function saveEntityToCache(path: string, data: object): void;
+/**
+ * Consumes a handoff. The channel is one-shot: whoever picks an edit up owns it
+ * from then on, and an edit left behind here is one that reopens a record dirty
+ * long after the user stopped looking at it.
+ */
 export declare function removeEntityFromMemoryCache(path: string): void;
+/**
+ * Parks an edit in flight for the layout about to take over. See
+ * {@link entityCache}: this is the handoff, not the backup.
+ */
 export declare function saveEntityToMemoryCache(path: string, data: object): void;
 export declare function getEntityFromMemoryCache(path: string): object | undefined;
 /**
- * Retrieves a entity from the in-memory cache or `sessionStorage`.
- * If the entity is not in the cache but exists in `sessionStorage`, it loads it into the cache.
+ * Retrieves a entity from the local-changes backup in `sessionStorage`.
+ *
+ * The backup only — the handoff channel is read through
+ * {@link getEntityFromMemoryCache}, and the two mean different things to the
+ * form that receives them.
  * @param path - The unique path/key for the entity.
  * @returns The cached entity or `undefined` if not found.
  */

package/dist/util/previews.d.ts

@@ -1,5 +1,24 @@
 import type { PropertyConfig, AdminCollection } from "@rebasepro/admin-types";
 import { AuthController } from "@rebasepro/admin-types";
+/**
+ * The properties a preview surface should render for a record, best first.
+ *
+ * Three things decide the answer, in this order:
+ *
+ * 1. `previewProperties` — passed in, or declared on the collection. A stated
+ *    list is returned verbatim, ranking and limit included: a developer who
+ *    asks for the Markdown biography gets the Markdown biography.
+ * 2. Whether the value has a one-line form at all. A map renders as a
+ *    key/value table and a Markdown field as a document; neither fits a card
+ *    line, so they never take a slot from a value that does. See
+ *    {@link rankSummaryProperty}.
+ * 3. `propertiesOrder`, which breaks ties.
+ *
+ * The middle step is the one that is easy to get wrong by leaving out.
+ * `propertiesOrder` states the *column* order of a collection table — it is
+ * not a statement that the first three columns summarise a record, and reading
+ * it as one is how a card ends up rendering somebody's entire biography.
+ */
 export declare function getEntityPreviewKeys(authController: AuthController, targetCollection: AdminCollection<any>, fields: Record<string, PropertyConfig>, previewProperties?: string[], limit?: number): string[];
 /**
  * The `include` params that eager-load a collection's relations in the same

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/app",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.g18cfeb7",
   "description": "Rebase core — framework-agnostic runtime for data-driven admin panels",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -52,12 +52,12 @@
     "magic-string": "^0.30.0",
     "notistack": "^3.0.2",
     "react-i18next": "^17.0.11",
-    "@rebasepro/admin-types": "0.13.0",
-    "@rebasepro/common": "0.13.0",
-    "@rebasepro/forms": "0.13.0",
-    "@rebasepro/types": "0.13.0",
-    "@rebasepro/ui": "0.13.0",
-    "@rebasepro/utils": "0.13.0"
+    "@rebasepro/admin-types": "0.13.1-canary.g18cfeb7",
+    "@rebasepro/common": "0.13.1-canary.g18cfeb7",
+    "@rebasepro/forms": "0.13.1-canary.g18cfeb7",
+    "@rebasepro/types": "0.13.1-canary.g18cfeb7",
+    "@rebasepro/ui": "0.13.1-canary.g18cfeb7",
+    "@rebasepro/utils": "0.13.1-canary.g18cfeb7"
   },
   "peerDependencies": {
     "react": ">=19.2.7",

package/src/auth/useRebaseAuthController.ts

@@ -100,7 +100,15 @@ export function useRebaseAuthController(
         // Fetch backend auth configuration
         auth.getAuthConfig().then((config: AuthConfigResponse) => {
             if (isMountedRef.current) setAuthConfig(config);
-        }).catch(() => {});
+        }).catch((e: unknown) => {
+            // Swallowed entirely before. This is what tells the login view which
+            // providers exist, so losing it renders a login form that is wrong
+            // rather than one that is broken — the hardest kind to report. Not
+            // promoted to `authError`, which blanks the whole app: a signed-in
+            // user is unaffected by this failing.
+            console.warn("[Rebase] Could not load the backend auth configuration; " +
+                "the login view will fall back to defaults.", e);
+        });
 
         const unsubscribe = auth.onAuthStateChange(syncState);
 

package/src/collections/entity-display-cache.ts

@@ -0,0 +1,195 @@
+/**
+ * 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";
+
+type CacheEntry = {
+    /** Set once resolved. `null` means "resolved to nothing", not "unknown". */
+    value: unknown;
+} | {
+    /** Shared by every caller that arrives while the first one is in flight. */
+    promise: Promise<unknown>;
+};
+
+export type EntityDisplayKey = string;
+
+/** The identity of one role of one record, as a cache key. */
+export function entityDisplayKey(
+    path: string,
+    entityId: string | number | undefined,
+    role: EntityDisplayRole
+): EntityDisplayKey {
+    return `${role} ${path} ${entityId ?? ""}`;
+}
+
+export class EntityDisplayCache {
+
+    private readonly entries = new Map<EntityDisplayKey, CacheEntry>();
+    private readonly listeners = new Set<() => void>();
+
+    /**
+     * 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 {
+        const entry = this.entries.get(key);
+        if (!entry || "promise" in entry) return undefined;
+        return entry.value;
+    }
+
+    /** True while a resolution for this pair is in flight. */
+    isLoading(key: EntityDisplayKey): boolean {
+        const entry = this.entries.get(key);
+        return Boolean(entry && "promise" in entry);
+    }
+
+    /**
+     * 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> {
+        const entry = this.entries.get(key);
+        if (entry) {
+            return "promise" in entry ? entry.promise : Promise.resolve(entry.value);
+        }
+
+        let produced: unknown;
+        try {
+            produced = resolver();
+        } catch (error: unknown) {
+            this.fail(key, error);
+            return Promise.resolve(null);
+        }
+
+        // A synchronous resolver never enters the loading state. Putting it
+        // through one would render every caller's fallback for a frame, for
+        // nothing.
+        if (!isPromise(produced)) {
+            const value = normalize(produced);
+            this.set(key, value);
+            return Promise.resolve(value);
+        }
+
+        const promise = produced
+            .then(resolved => {
+                const value = normalize(resolved);
+                this.set(key, value);
+                return value;
+            })
+            .catch((error: unknown) => {
+                this.fail(key, error);
+                return null;
+            });
+
+        this.entries.set(key, { promise });
+        return promise;
+    }
+
+    /**
+     * 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 {
+        const suffix = ` ${path} ${entityId ?? ""}`;
+        let changed = false;
+        for (const key of [...this.entries.keys()]) {
+            // `undefined` id means the whole collection — after an import, or a
+            // locale switch that changes what every title in it reads.
+            const matches = entityId === undefined
+                ? key.includes(` ${path} `) || key.endsWith(` ${path} `)
+                : key.endsWith(suffix);
+            if (matches) {
+                this.entries.delete(key);
+                changed = true;
+            }
+        }
+        if (changed) this.emit();
+    }
+
+    /** Drop everything. The user signed out, or the app swapped datasource. */
+    clear(): void {
+        if (this.entries.size === 0) return;
+        this.entries.clear();
+        this.emit();
+    }
+
+    subscribe(listener: () => void): () => void {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+
+    private set(key: EntityDisplayKey, value: unknown): void {
+        this.entries.set(key, { value });
+        this.emit();
+    }
+
+    /**
+     * 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(key: EntityDisplayKey, error: unknown): void {
+        console.warn(`[rebase] Could not resolve display value for ${key}:`, error);
+        this.set(key, null);
+    }
+
+    private emit(): void {
+        for (const listener of [...this.listeners]) listener();
+    }
+}
+
+/**
+ * Empty strings and empty arrays are absences, not values — a title of `"  "`
+ * would otherwise beat the derived one and render as a blank heading.
+ */
+function normalize(value: unknown): unknown {
+    if (value === undefined || value === null) return null;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    if (Array.isArray(value)) return value.length > 0 ? value : null;
+    return value;
+}
+
+function isPromise(value: unknown): value is Promise<unknown> {
+    return typeof (value as Promise<unknown> | undefined)?.then === "function";
+}

package/src/collections/entity-display.ts

@@ -0,0 +1,105 @@
+/**
+ * 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";
+
+/**
+ * Collections that have already warned about a deprecated field, so a list of
+ * fifty rows produces one line in the console rather than fifty.
+ */
+const deprecationWarned = new Set<string>();
+
+function collectionId(collection: AdminCollection<never> | AdminCollection<any>): string {
+    return (collection.slug ?? collection.name ?? "collection") as string;
+}
+
+function warnOnce(id: string, message: string): void {
+    const key = `${id}:${message}`;
+    if (deprecationWarned.has(key)) return;
+    deprecationWarned.add(key);
+    console.warn(message);
+}
+
+/**
+ * What the collection declares for a role, before deciding which form it is.
+ *
+ * `display.title` wins over the deprecated `titleProperty`: a collection setting
+ * both is mid-migration, and the new field is the one it means.
+ */
+function getDeclaredSource<M extends Record<string, unknown>>(
+    collection: AdminCollection<M>,
+    role: EntityDisplayRole
+): string | EntityDisplayResolver<M, unknown> | undefined {
+
+    const display = collection.display as Record<string, unknown> | undefined;
+    const declared = display?.[role];
+    if (declared !== undefined) return declared as string | EntityDisplayResolver<M, unknown>;
+
+    if (role === "title" && collection.titleProperty) {
+        const id = collectionId(collection);
+        warnOnce(
+            id,
+            `[rebase] Collection "${id}" uses admin.titleProperty, which is deprecated. ` +
+            `Move it to admin.display.title — the same string works there, and display.title ` +
+            `also accepts a resolver for a title the record does not carry.`
+        );
+        return collection.titleProperty as string;
+    }
+
+    return undefined;
+}
+
+/**
+ * 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 function getDisplayPropertyKey<M extends Record<string, unknown>>(
+    collection: AdminCollection<M>,
+    role: EntityDisplayRole
+): string | undefined {
+    const declared = getDeclaredSource(collection, role);
+    return typeof declared === "string" ? declared : undefined;
+}
+
+/**
+ * The resolver a role is declared to use, when it is declared as one.
+ *
+ * @group Collections
+ */
+export function getDisplayResolver<M extends Record<string, unknown>>(
+    collection: AdminCollection<M>,
+    role: EntityDisplayRole
+): EntityDisplayResolver<M, unknown> | undefined {
+    const declared = getDeclaredSource(collection, role);
+    return typeof declared === "function" ? declared : 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 function hasDeclaredDisplay<M extends Record<string, unknown>>(
+    collection: AdminCollection<M>,
+    role: EntityDisplayRole
+): boolean {
+    return getDeclaredSource(collection, role) !== undefined;
+}

package/src/collections/entity_image_preview.ts

@@ -1,7 +1,20 @@
 import { CollectionConfig } from "@rebasepro/types";
+import type { AdminCollection } from "@rebasepro/admin-types";
+import { getDisplayPropertyKey } from "./entity-display";
 
+/**
+ * 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 function getEntityImagePreviewPropertyKey<M extends Record<string, unknown>>(collection: CollectionConfig<M>): string | undefined {
 
+    const declared = getDisplayPropertyKey(collection as AdminCollection<M>, "image");
+    if (declared) return declared;
+
     // find first storage property of type image
     for (const key in collection.properties) {
         const property = collection.properties[key];

package/src/collections/form-layout.ts

@@ -54,6 +54,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 {
@@ -346,7 +352,8 @@ export function resolveFormLayout<M extends Record<string, unknown>>({
                 title: section.title,
                 collapsible: section.collapsible ?? titled,
                 collapsed: titled ? Boolean(section.collapsed) : false,
-                fields
+                fields,
+                readVariant: section.readVariant
             });
         }
     }

package/src/collections/index.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/src/collections/property-path.ts

@@ -0,0 +1,30 @@
+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 function getPropertyInPath(properties: Properties, path: string): Property | undefined {
+    if (typeof properties !== "object" || !properties) return undefined;
+    if (path in properties) {
+        return (properties as Record<string, Property>)[path];
+    }
+    if (path.includes(".")) {
+        const pathSegments = path.split(".");
+        const childProperty = (properties as Record<string, Property>)[pathSegments[0]];
+        if (typeof childProperty === "object" && childProperty?.type === "map" && childProperty.properties) {
+            return getPropertyInPath(childProperty.properties, pathSegments.slice(1).join("."));
+        }
+    }
+    return undefined;
+}

package/src/collections/property_presentation.ts

@@ -10,17 +10,40 @@
  * 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, EnumValueConfig, Property, PropertyConditions, ReferenceProperty } from "@rebasepro/types";
+import type { ConditionContext, ConditionRule, EnumValueConfig, Property, PropertyConditions, ReferenceProperty } from "@rebasepro/types";
 import type { AdminArrayOptions, AdminReferenceOptions } from "@rebasepro/admin-types";
 import { evaluateCondition } from "@rebasepro/common";
 
+/**
+ * A condition stated as a literal rather than as a rule.
+ *
+ * `PropertyConditions` accepts either, and the two are answered in different
+ * places: a rule needs a context and so can only be evaluated while rendering a
+ * particular entity, but a literal is already the answer. Reading it here is
+ * what makes `hidden: true` work without every gate below having to build a
+ * condition context first — and without the caller reaching for
+ * `{ "==": [1, 1] }` to say something it can say with a boolean.
+ */
+function literalCondition(condition: ConditionRule | undefined): boolean {
+    return condition === true;
+}
+
 export function isReadOnly(property: Property): boolean {
     if (property.admin?.readOnly)
         return true;
+    if (literalCondition(property.conditions?.readOnly))
+        return true;
     if (property.type === "date") {
         if (property.autoValue)
             return true;
@@ -32,9 +55,21 @@ export function isReadOnly(property: Property): boolean {
 }
 
 export function isHidden(property: Property): boolean {
+    if (literalCondition(property.conditions?.hidden)) return true;
     return typeof property.admin?.disabled === "object" && Boolean(property.admin?.disabled.hidden);
 }
 
+/**
+ * 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 function isDisabled(property: Property): boolean {
+    return Boolean(property.admin?.disabled) || literalCondition(property.conditions?.disabled);
+}
+
 export function applyPropertyConditions(
     property: Property,
     context: ConditionContext