@rebasepro/app 0.13.0 → 0.13.1-canary.gcd6689e

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/app",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.gcd6689e",
   "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/common": "0.13.1-canary.gcd6689e",
+    "@rebasepro/types": "0.13.1-canary.gcd6689e",
+    "@rebasepro/forms": "0.13.1-canary.gcd6689e",
+    "@rebasepro/admin-types": "0.13.1-canary.gcd6689e",
+    "@rebasepro/utils": "0.13.1-canary.gcd6689e",
+    "@rebasepro/ui": "0.13.1-canary.gcd6689e"
   },
   "peerDependencies": {
     "react": ">=19.2.7",

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

@@ -0,0 +1,166 @@
+/**
+ * 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. The caller
+     * that saw the rejection is the one that logs it.
+     */
+    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 {
+            this.set(key, null);
+            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(() => {
+                this.set(key, null);
+                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();
+    }
+
+    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/index.ts

@@ -1,9 +1,12 @@
 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 "./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/title-property.ts

@@ -2,6 +2,8 @@ import { isRelationalCollectionConfig, type Property, type Relation } from "@reb
 import { generateForeignKeyName } from "@rebasepro/utils";
 import type { AdminCollection } from "@rebasepro/admin-types";
 import { getPrimaryKeys, isPropertyBuilder } from "@rebasepro/common";
+import { getPropertyInPath } from "./property-path";
+import { getDisplayPropertyKey, hasDeclaredDisplay } from "./entity-display";
 
 /**
  * How good a property is as the human-readable title of an entity.
@@ -182,8 +184,13 @@ export function getTitlePropertyCandidates<M extends Record<string, unknown>>(
 ): string[] {
     if (!collection.properties) return [];
 
-    if (collection.titleProperty && collection.properties[collection.titleProperty as string]) {
-        return [collection.titleProperty as string];
+    // `getPropertyInPath`, not `properties[key]`: a declared title on a nested
+    // field — `profile.display_name` — was looked up flat, found nothing, and
+    // silently fell through to the derived ranking. The dotted form has been
+    // documented as valid the whole time.
+    const declared = getDisplayPropertyKey(collection, "title");
+    if (declared && getPropertyInPath(collection.properties, declared)) {
+        return [declared];
     }
 
     const idKeys = new Set<string>(getPrimaryKeys(collection) as string[]);
@@ -237,7 +244,9 @@ export function getLeadingRelationTitleKey<M extends Record<string, unknown>>(
     collection: AdminCollection<M>
 ): string | undefined {
     if (!collection.properties) return undefined;
-    if (collection.titleProperty) return undefined;
+    // The collection states what it is called, in one form or the other; either
+    // way it is not asking for the leading-relation heuristic.
+    if (hasDeclaredDisplay(collection, "title")) return undefined;
 
     const idKeys = new Set<string>(getPrimaryKeys(collection) as string[]);
     const foreignKeys = getForeignKeyColumns(collection);

package/src/components/common/useColumnsIds.tsx

@@ -3,26 +3,7 @@ import { useMemo } from "react";
 ;
 import { getSubcollections } from "@rebasepro/common";
 import type { AdminCollection } from "@rebasepro/admin-types";
-
-/**
- * Get a property in a property tree from a dot-path like `address.street`.
- * Inlined here to avoid importing property-aware utilities from the admin layer.
- */
-function getPropertyInPath(properties: Properties, path: string): Property | undefined {
-    if (typeof properties === "object") {
-        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;
-}
+import { getPropertyInPath } from "../../collections/property-path";
 
 export type PropertyColumnConfig = {
     key: string;

package/src/locales/de.ts

@@ -77,6 +77,7 @@ export const de: RebaseTranslations = {
     column_cannot_be_edited: "Diese Spalte kann nicht direkt bearbeitet werden",
     close: "Schließen",
     hide_list: "Liste ausblenden",
+    show_list: "Liste einblenden",
     unsaved_local_changes: "Ungespeicherte lokale Änderungen",
     unsaved_local_changes_description: "Dieses Dokument wurde lokal bearbeitet und weist ungespeicherte Änderungen auf. Diese lokalen Änderungen gehen verloren, wenn Sie sie nicht anwenden.",
     preview_changes: "Änderungen in der Vorschau anzeigen",

package/src/locales/en.ts

@@ -87,6 +87,7 @@ export const en: RebaseTranslations = {
     column_cannot_be_edited: "This column can't be edited directly",
     close: "Close",
     hide_list: "Hide list",
+    show_list: "Show list",
     unsaved_local_changes: "Unsaved Local changes",
     unsaved_local_changes_description: "This document was edited locally and has unsaved changes. These local changes will be lost if you don't apply them.",
     preview_changes: "Preview Changes",

package/src/locales/es.ts

@@ -85,6 +85,7 @@ export const es: RebaseTranslations = {
     column_cannot_be_edited: "Esta columna no se puede editar directamente",
     close: "Cerrar",
     hide_list: "Ocultar lista",
+    show_list: "Mostrar lista",
     unsaved_local_changes: "Cambios locales sin guardar",
     unsaved_local_changes_description: "Este documento ha sido editado localmente y tiene cambios sin guardar. Estos cambios locales se perderán si no los aplicas.",
     preview_changes: "Previsualizar cambios",

package/src/locales/fr.ts

@@ -77,6 +77,7 @@ export const fr: RebaseTranslations = {
     column_cannot_be_edited: "Cette colonne ne peut pas être modifiée directement",
     close: "Fermer",
     hide_list: "Masquer la liste",
+    show_list: "Afficher la liste",
     unsaved_local_changes: "Modifications locales non enregistrées",
     unsaved_local_changes_description: "Ce document a été modifié localement et contient des modifications non enregistrées. Ces modifications locales seront perdues si vous ne les appliquez pas.",
     preview_changes: "Aperçu des modifications",

package/src/locales/hi.ts

@@ -77,6 +77,7 @@ export const hi: RebaseTranslations = {
     column_cannot_be_edited: "इस कॉलम को सीधे संपादित नहीं किया जा सकता",
     close: "बंद करें",
     hide_list: "सूची छिपाएँ",
+    show_list: "सूची दिखाएँ",
     unsaved_local_changes: "सहेजे नहीं गए स्थानीय परिवर्तन",
     unsaved_local_changes_description: "इस दस्तावेज़ को स्थानीय स्तर पर संपादित किया गया था और इसमें सहेजे नहीं गए परिवर्तन हैं। यदि आप इन्हें लागू नहीं करते हैं तो ये स्थानीय परिवर्तन खो जाएंगे।",
     preview_changes: "परिवर्तनों का पूर्वावलोकन करें",

package/src/locales/it.ts

@@ -77,6 +77,7 @@ export const it: RebaseTranslations = {
     column_cannot_be_edited: "Questa colonna non può essere modificata direttamente",
     close: "Chiudi",
     hide_list: "Nascondi elenco",
+    show_list: "Mostra elenco",
     unsaved_local_changes: "Modifiche locali non salvate",
     unsaved_local_changes_description: "Questo documento è stato modificato localmente e ha modifiche non salvate. Queste modifiche locali andranno perse se non le applichi.",
     preview_changes: "Anteprima modifiche",

package/src/locales/pt.ts

@@ -82,6 +82,7 @@ export const pt: RebaseTranslations = {
     column_cannot_be_edited: "Esta coluna não pode ser editada diretamente",
     close: "Fechar",
     hide_list: "Ocultar lista",
+    show_list: "Mostrar lista",
     unsaved_local_changes: "Alterações locais não guardadas",
     unsaved_local_changes_description: "Este documento foi editado localmente e tem alterações não guardadas. Estas alterações locais serão perdidas se não as aplicar.",
     preview_changes: "Pré-visualizar alterações",