@rebasepro/admin 0.13.0 → 0.13.1-canary.g18cfeb7

package/src/form/field_bindings/GeopointFieldBinding.tsx

@@ -128,27 +128,24 @@ export function GeopointFieldBinding({
                 : undefined;
 
     return (
-        <div className="flex flex-col gap-2 w-full mt-2">
-            <div className="flex items-center justify-between mb-1">
-                {!hideLabel && <LabelWithIcon
+        <div className="flex flex-col gap-2 w-full">
+            {/* Label only, and only when there is one: a row that survives
+                `hideLabel` still spends its `mb-1` and the column's `gap-2`, so
+                the pair of inputs sat below the control next to them even
+                though the two labels were level. */}
+            {!hideLabel && <div className="flex items-center justify-between mb-1">
+                <LabelWithIcon
                     icon={getIconForProperty(property, "small")}
                     required={property.validation?.required}
                     title={property.name ?? propertyKey}
-                />}
-                {!disabled && (latText || lngText) && (
-                    <IconButton
-                        size="small"
-                        onClick={handleClear}
-                        className="text-text-secondary hover:text-red-500"
-                        aria-label="Clear location"
-                    >
-                        <Trash2Icon size={14}/>
-                    </IconButton>
-                )}
-            </div>
+                />
+            </div>}
 
             <PropertyIdCopyTooltip propertyKey={propertyKey}>
-                <div className="flex gap-4 w-full">
+                {/* Clear sits beside the inputs rather than above them, so
+                    entering a location does not grow the field by a row and
+                    knock it out of line with its neighbour. */}
+                <div className="flex gap-4 w-full items-center">
                     <TextField
                         className="flex-1"
                         size={size}
@@ -178,6 +175,16 @@ export function GeopointFieldBinding({
                         placeholder="e.g. 2.1686"
                         inputClassName="font-mono"
                     />
+                    {!disabled && (latText || lngText) && (
+                        <IconButton
+                            size="small"
+                            onClick={handleClear}
+                            className="shrink-0 text-text-secondary hover:text-red-500"
+                            aria-label="Clear location"
+                        >
+                            <Trash2Icon size={14}/>
+                        </IconButton>
+                    )}
                 </div>
             </PropertyIdCopyTooltip>
 

package/src/form/field_bindings/MapFieldBinding.tsx

@@ -6,7 +6,7 @@ import { useTranslation } from "@rebasepro/app";
 
 import { ErrorBoundary } from "@rebasepro/ui";
 import { getIconForProperty } from "../../util/property_utils";
-import { isHidden, isReadOnly } from "@rebasepro/app";
+import { isDisabled, isHidden, isReadOnly } from "@rebasepro/app";
 import { FieldHelperText } from "../components/FieldHelperText";
 import { LabelWithIconAndTooltip } from "../components/LabelWithIconAndTooltip";
 import { PropertyFieldBinding } from "../PropertyFieldBinding";
@@ -50,7 +50,7 @@ export function MapFieldBinding({
             {Object.entries(mapProperties)
                 .filter(([_, property]) => !isHidden(property))
                 .map(([entryKey, childProperty], index) => {
-                    const thisDisabled = isReadOnly(childProperty) || Boolean(childProperty.admin?.disabled);
+                    const thisDisabled = isReadOnly(childProperty) || isDisabled(childProperty);
                     const fieldBindingProps: PropertyFieldBindingProps<Record<string, unknown>> = {
                         propertyKey: `${propertyKey}.${entryKey}`,
                         disabled: disabled || thisDisabled,

package/src/form/field_bindings/MarkdownEditorFieldBinding.tsx

@@ -216,17 +216,26 @@ export function MarkdownEditorFieldBinding({
 
     return (
         <>
-            <div className="flex items-center w-full">
-                {!hideLabel && <LabelWithIconAndTooltip
+            {!hideLabel && <div className="flex items-center w-full">
+                <LabelWithIconAndTooltip
                     propertyKey={propertyKey}
                     icon={getIconForProperty(property, "small")}
                     required={property.validation?.required}
                     title={property.name ?? propertyKey}
-                    className={"h-8 text-text-secondary dark:text-text-secondary-dark ml-3.5"}/>}
-                <div className="flex-grow"/>
+                    className={"h-8 text-text-secondary dark:text-text-secondary-dark ml-3.5"}/>
+            </div>}
+            {/* `relative` so Clear can float inside the box. It used to sit in
+                the label row, which meant a clearable field with its label
+                lifted out by the form still drew a row of chrome above the box
+                and started lower than the field beside it.
+                Bottom-right, not top: the editor puts its own mode toggle at
+                `top-2 right-2` and the two would sit on each other. */}
+            <div
+                className={cls("relative rounded-md", fieldBackgroundMixin, disabled ? fieldBackgroundDisabledMixin : fieldBackgroundHoverMixin)}>
                 {property.admin?.clearable && !disabled && (
                     <IconButton
                         size="small"
+                        className="absolute bottom-1 right-1 z-10"
                         onClick={(e) => {
                             e.stopPropagation();
                             e.preventDefault();
@@ -236,9 +245,6 @@ export function MarkdownEditorFieldBinding({
                         <XIcon/>
                     </IconButton>
                 )}
-            </div>
-            <div
-                className={cls("rounded-md", fieldBackgroundMixin, disabled ? fieldBackgroundDisabledMixin : fieldBackgroundHoverMixin)}>
                 {editor}
             </div>
             <FieldHelperText includeDescription={includeDescription}

package/src/form/field_bindings/MultiSelectFieldBinding.tsx

@@ -87,7 +87,13 @@ export function MultiSelectFieldBinding({
     return (
         <>
             <MultiSelect
-                className={"w-full mt-2"}
+                // No top margin: `className` lands on the box itself, not on
+                // the label above it, so `mt-2` was 8px of gap between the
+                // form's label and this control and none between the label and
+                // the text field beside it. A binding renders a control, not a
+                // labelled control — the top of what it renders is the top of
+                // the box, or it will not line up with its neighbour.
+                className={"w-full"}
                 size={size}
                 value={validValue ? value.map((v) => v?.toString()) : []}
                 disabled={disabled}

package/src/form/field_bindings/ReadOnlyFieldBinding.tsx

@@ -53,7 +53,13 @@ export function ReadOnlyFieldBinding({
                     "w-full overflow-x-scroll no-scrollbar flex items-center",
                     skipCardWrapper
                         ? ""
-                        : "rounded-lg border border-surface-200 dark:border-surface-700 px-4 md:px-6 min-h-10 opacity-80"
+                        // `min-h-12` is `TextField`'s own `large` height, which is
+                        // what every editable field in the form is. At 40px a
+                        // read-only field sat 8px short of the input beside it,
+                        // so a row holding one of each had its two boxes'
+                        // baselines and bottom edges disagree — the field looked
+                        // misaligned rather than uneditable.
+                        : "rounded-lg border border-surface-200 dark:border-surface-700 px-4 md:px-6 min-h-12 opacity-80"
                 )}>
 
                 <ErrorBoundary>

package/src/form/field_bindings/ReferenceFieldBinding.tsx

@@ -121,7 +121,7 @@ function ReferenceFieldBindingInternal({
                 />}
 
                 {!refValue && <div className="justify-center text-left">
-                    <EntityPreviewContainer className={cls("px-6 h-16 text-sm font-medium flex items-center gap-6",
+                    <EntityPreviewContainer className={cls("px-6 h-12 text-sm font-medium flex items-center gap-6",
                         disabled || isSubmitting
                             ? "text-surface-accent-500"
                             : "cursor-pointer text-surface-accent-700 dark:text-surface-accent-300 hover:bg-surface-accent-50 dark:hover:bg-surface-800 group-hover:bg-surface-accent-50 dark:group-hover:bg-surface-800")}

package/src/form/field_bindings/RelationFieldBinding.tsx

@@ -72,7 +72,10 @@ function RelationSelectorBinding({
     const singleValue = normalizedSingle ?? null;
     const multipleValue = (manyRelation && Array.isArray(value)) ? value : [];
 
-    const selectorSize: "small" | "medium" | undefined = size === "large" ? "medium" : size;
+    // Passed straight through. Mapping the form's `large` onto the selector's
+    // `medium` produced a 56px box next to 48px text fields — the labels lined
+    // up and the boxes did not.
+    const selectorSize = size;
 
     return (
         <div className="">
@@ -176,7 +179,7 @@ function SingleRelationFieldBinding({
                 />}
 
                 {!value && <div className="justify-center text-left">
-                    <EntityPreviewContainer className={cls("px-6 h-16 text-sm font-medium flex items-center gap-6",
+                    <EntityPreviewContainer className={cls("px-6 h-12 text-sm font-medium flex items-center gap-6",
                         disabled || isSubmitting
                             ? "text-surface-accent-500"
                             : "cursor-pointer text-surface-accent-700 dark:text-surface-accent-300 hover:bg-surface-accent-50 dark:hover:bg-surface-800 group-hover:bg-surface-accent-50 dark:group-hover:bg-surface-800")}

package/src/form/field_bindings/RepeatFieldBinding.tsx

@@ -11,7 +11,7 @@ import { getIconForProperty } from "../../util/property_utils";
 import { PropertyFieldBinding } from "../PropertyFieldBinding";
 import { ExpandablePanel, Typography } from "@rebasepro/ui";
 import { useClearRestoreValue } from "../useClearRestoreValue";
-import { useAuthController, useTranslation } from "@rebasepro/app";
+import { isDisabled, useAuthController, useTranslation } from "@rebasepro/app";
 import { mergeDeep } from "@rebasepro/utils";
 
 /**
@@ -96,14 +96,14 @@ export function RepeatFieldBinding({
         </ErrorBoundary>;
     };
 
-    const canAddElements = !property.admin?.disabled && !isSubmitting && !disabled && (property.admin?.canAddElements || property.admin?.canAddElements === undefined);
+    const canAddElements = !isDisabled(property) && !isSubmitting && !disabled && (property.admin?.canAddElements || property.admin?.canAddElements === undefined);
     const sortable = property.admin?.sortable === undefined ? true : property.admin.sortable;
     const arrayContainer = <ArrayContainer droppableId={propertyKey}
         addLabel={property.name ? t("add_to_field", { fieldName: property.name }) : t("add_entry")}
         value={(value as unknown[]) ?? []}
         buildEntry={buildEntry}
         onInternalIdAdded={setLastAddedId}
-        disabled={isSubmitting || Boolean(property.admin?.disabled)}
+        disabled={isSubmitting || isDisabled(property)}
         canAddElements={canAddElements}
         sortable={sortable}
         newDefaultEntry={getDefaultValueFor(property.of)}

package/src/form/field_bindings/StorageUploadFieldBinding.tsx

@@ -8,7 +8,7 @@ import { useDropzone } from "react-dropzone";
 import { FieldHelperText } from "../components/FieldHelperText";
 import { LabelWithIconAndTooltip } from "../components/LabelWithIconAndTooltip";
 
-import { isReadOnly } from "@rebasepro/app";
+import { isDisabled, isReadOnly } from "@rebasepro/app";
 import { getIconForProperty } from "../../util/property_utils";
 import { useAuthController, useSnackbarController, useStorageSource, useTranslation } from "@rebasepro/app";
 import { StorageSourceContext } from "@rebasepro/app";
@@ -74,7 +74,7 @@ export function StorageUploadFieldBinding({
     const authController = useAuthController();
 
     const storageSource = useStorageSource();
-    const disabled = isReadOnly(property) || !!property.admin?.disabled || isSubmitting || context.disabled;
+    const disabled = isReadOnly(property) || isDisabled(property) || isSubmitting || context.disabled;
 
     const {
         internalValue,

package/src/form/field_bindings/UserSelectFieldBinding.tsx

@@ -34,7 +34,10 @@ export function UserSelectFieldBinding({
                                            size = "large"
                                        }: UserSelectProps) {
 
-    const selectorSize: "small" | "medium" | undefined = size === "large" ? "medium" : size;
+    // Passed straight through. Mapping the form's `large` onto the selector's
+    // `medium` produced a 56px box next to 48px text fields — the labels lined
+    // up and the boxes did not.
+    const selectorSize = size;
 
     return (
         <>

package/src/form/field_bindings/VectorFieldBinding.tsx

@@ -98,11 +98,13 @@ export function VectorFieldBinding({
     const isPopulated = arrayValue.length > 0;
 
     return (
-        <div className="flex flex-col gap-2 w-full mt-2">
-            {/* Field Label */}
-            <div className="flex items-center justify-between mb-1">
+        <div className="flex flex-col gap-2 w-full">
+            {/* Only when there is a label to put in it — an empty row still
+                spends its `mb-1` and the column's `gap-2`, and the control ends
+                up below the one beside it under a label at the same height. */}
+            {label && <div className="flex items-center justify-between mb-1">
                 {label}
-            </div>
+            </div>}
 
             <PropertyIdCopyTooltip propertyKey={propertyKey}>
                 <div className="w-full">

package/src/form/form_utils.ts

@@ -114,6 +114,84 @@ export function getChanges<T extends object>(source: Partial<T>, comparison: Par
     return changes;
 }
 
+/**
+ * What the local-changes backup still has to offer, given what the form is
+ * already showing — the answer the "unsaved local changes" banner is asking for.
+ * `undefined` means there is nothing left to apply, and no banner.
+ *
+ * Measured against what the form *opens showing*, not against the stored
+ * record. The banner exists to offer a draft the form is not already displaying,
+ * and an edit carried across a change of layout is in both the backup and the
+ * form: measuring against the stored values alone offered to restore the values
+ * already on screen, over an edit the user had never left.
+ */
+export function getUnappliedLocalChanges<M extends Record<string, unknown>>(
+    backupValues: Partial<M>,
+    openingValues: Partial<M>
+): Partial<M> | undefined {
+    const changes = getChanges(backupValues, openingValues);
+    const cleaned = removeEmptyContainers(changes);
+    if (!cleaned || typeof cleaned !== "object" || Object.keys(cleaned).length === 0) {
+        return undefined;
+    }
+    return cleaned as Partial<M>;
+}
+
+/**
+ * What travels when the same record changes layout — the split's "hide list",
+ * full screen's "show list", the side panel's "open full screen". One mounted
+ * form is replaced by another showing the same record, so the edit in progress
+ * has to be handed over; left to the local-changes backup alone, the new form
+ * met it as a draft from a closed tab and raised the "unsaved local changes"
+ * banner over changes the user had made a second earlier and never left.
+ *
+ * Returns `undefined` when there is nothing to carry, which is its own answer: a
+ * record nobody edited must open in the next layout exactly as clean as it was.
+ *
+ * Only what was edited here travels, keyed by `touched` — the same subset the
+ * backup stores. Carrying the whole record instead marks every field touched in
+ * the receiving form, which lights up every empty required field as an error and
+ * writes the entire record back out as a "local change".
+ */
+export function getEditHandoffValues<M extends Record<string, unknown>>({
+    status,
+    dirty,
+    values,
+    touched,
+    storedValues
+}: {
+    status: EntityStatus;
+    /** Whether `values` differ from what is stored. */
+    dirty: boolean;
+    values: Partial<M>;
+    touched: Record<string, boolean>;
+    /** The stored record, for the fallback below. Absent for a new one. */
+    storedValues?: Partial<M>;
+}): Partial<M> | undefined {
+
+    if (!values) return undefined;
+
+    // A record with nothing stored behind it carries whole: there is no
+    // baseline to fall back to, so anything not carried is simply lost.
+    if (status === "new" || status === "copy") {
+        return Object.keys(values).length > 0 ? values : undefined;
+    }
+
+    if (!dirty) return undefined;
+
+    const touchedValues = removeEmptyContainers(extractTouchedValues(values, touched ?? {})) as Partial<M> | undefined;
+    if (touchedValues && Object.keys(touchedValues).length > 0) {
+        return touchedValues;
+    }
+
+    // Dirty with nothing touched — a value set programmatically, by a plugin or
+    // a custom field that writes through `setFieldValue` without the blur that
+    // marks it. Diffing against the stored record still finds it, and dropping
+    // it here would hand over a form that opens clean over an edit.
+    const changes = getChanges(values, storedValues ?? {});
+    return Object.keys(changes).length > 0 ? changes : undefined;
+}
+
 export function getInitialEntityValues<M extends Record<string, unknown>>(
     authController: AuthController,
     collection: AdminCollection,

package/src/hooks/navigation/useBuildCollectionRegistryController.tsx

@@ -41,11 +41,35 @@ export function useBuildCollectionRegistryController(props: {
         if (!collectionPath) return undefined;
 
         let collection: AdminCollection | undefined;
-        try {
-            collection = registry.resolvePathToCollections(collectionPath).finalCollection;
-        } catch (e) {
-            console.debug(`Could not resolve path to collection: ${collectionPath}`, e);
-            return undefined;
+
+        // An exact slug match first, because a slug is allowed to contain
+        // slashes and several drivers need it to: a Firestore collection
+        // partitioned by locale is declared as `content/de-DE/podcasts`, and
+        // that string is its *name*, not a path to walk.
+        //
+        // Without this, such a slug went straight to `resolvePathToCollections`,
+        // which reads any `a/b/c` as collection/entity/subcollection, looked for
+        // a root collection called `content`, found none and threw — and the
+        // catch below turned that into `undefined`. `RebaseRoute` renders
+        // `null` for an unresolved collection, so the whole view came out blank
+        // with nothing in the console above `debug`. Thirty-five collections in
+        // one app were unreachable that way.
+        // `collectionPath`, not `cleanedPath`: an even segment count means the
+        // path ends at a record, and the id has already been trimmed off above.
+        // Matching the raw path instead would only ever hit for a collection
+        // route, leaving `content/de-DE/podcasts/abc123` back on the walker.
+        collection = registry.get(collectionPath) as AdminCollection | undefined;
+
+        if (!collection) {
+            try {
+                collection = registry.resolvePathToCollections(collectionPath).finalCollection;
+            } catch (e) {
+                // Warn, not debug. An unresolved collection ends as a route with
+                // nothing in it, and at `debug` there was no way to tell that
+                // from a collection that legitimately has no rows.
+                console.warn(`[rebase] Could not resolve a collection for "${collectionPath}"`, e);
+                return undefined;
+            }
         }
 
         if (!collection) {

package/src/hooks/useEntityDisplay.tsx

@@ -0,0 +1,262 @@
+import type { AdminCollection, EntityDisplayRole } from "@rebasepro/admin-types";
+import type { Entity, Property } from "@rebasepro/types";
+import { ENTITY_DISPLAY_ROLES } from "@rebasepro/admin-types";
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import {
+    EntityDisplayCache,
+    entityDisplayKey,
+    getDisplayPropertyKey,
+    getDisplayResolver,
+    getPropertyInPath,
+    useRebaseContext
+} from "@rebasepro/app";
+import { getValueInPath } from "@rebasepro/utils";
+
+import { getEntityTitlePropertyKeyForEntity, isUserSelectProperty, resolveTitleToString } from "../util/previews";
+import { getUserLabel, useResolvedUser } from "./useResolvedUsers";
+
+/**
+ * What fills one display role for one record.
+ *
+ * `value` is `undefined` rather than a placeholder when nothing resolved,
+ * because the substitute differs by surface and each one knows its own better
+ * than this hook does: a page heading wants the singular collection name, a link
+ * wants the id, a draft wants "New customer". A single baked-in fallback is
+ * exactly what produced three different ones scattered across the consumers.
+ */
+export interface ResolvedDisplayValue<T = unknown> {
+    /** What goes in the slot. `undefined` when the record has nothing for it. */
+    value: T | undefined;
+    /**
+     * A resolver is in flight, and `value` currently holds the derived answer or
+     * nothing. Surfaces that can show a skeleton may; none has to.
+     */
+    loading: boolean;
+    /**
+     * Set only when the value came from a property of this collection. Carries
+     * what a rich renderer needs — a status shows as its enum's coloured chip,
+     * an image as a storage thumbnail — which a bare resolved string cannot
+     * describe.
+     */
+    source?: {
+        key: string;
+        property: Property | undefined;
+        value: unknown;
+    };
+}
+
+/**
+ * One shared store, so every surface agrees on a record and resolves it once.
+ *
+ * Module-level rather than a provider: two app instances on one page share a
+ * cache keyed by collection path and record id, which *is* the same record.
+ * Nothing here is user-specific — a resolver that reads per-user data must
+ * invalidate on sign-out, which {@link useEntityDisplayCache} exposes.
+ */
+let sharedCache: EntityDisplayCache | undefined;
+
+/**
+ * The store behind {@link useEntityDisplay}, for invalidating after a write.
+ *
+ * Built on first use rather than at module scope. Importing a module should not
+ * construct anything: it runs during SSR where there is nothing to cache, and it
+ * made this module unimportable from any test that stubs `@rebasepro/app` —
+ * which several do, and which is a legitimate thing for them to do.
+ */
+export function useEntityDisplayCache(): EntityDisplayCache {
+    if (!sharedCache) sharedCache = new EntityDisplayCache();
+    return sharedCache;
+}
+
+export interface UseEntityDisplayParams<M extends Record<string, unknown>> {
+    /**
+     * Optional because several callers look the collection up in the registry by
+     * path and may not find it — a relation into a collection the panel does not
+     * register. A hook that could not be called until that succeeded would have
+     * to sit below an early return, which is not where hooks go.
+     */
+    collection?: AdminCollection<M>;
+    /**
+     * The record. A resolver is handed the whole entity — its id and path are
+     * how it reaches anything the record does not carry — so a computed value is
+     * only available once there is an entity to compute it from.
+     */
+    entity?: Entity<M>;
+    /**
+     * Values to read a declared path from when they are newer than the entity:
+     * the live form values while editing. Falls back to `entity.values`.
+     */
+    values?: Record<string, unknown>;
+    /** Set false to skip resolver work entirely — a draft has nothing to show. */
+    enabled?: boolean;
+}
+
+/**
+ * What fills one display role of one record.
+ *
+ * This is the only implementation. Before it there were seven for the title
+ * alone — the identity bar, the detail header, inline previews, reference cards,
+ * list slots, relation chips and the headless view — each re-deriving it from
+ * `collection.properties` and disagreeing about the answer.
+ *
+ * Resolution order, per role:
+ *
+ * 1. `admin.display[role]` as a **resolver** — awaited, cached per record and
+ *    role, with the derived value showing meanwhile so nothing flickers empty.
+ * 2. `admin.display[role]` as a **property path** (or, for the title, the
+ *    deprecated `titleProperty`).
+ * 3. The **derived** answer: for the title, the best-ranked property carrying a
+ *    readable value; for the rest, today's per-role heuristics.
+ *
+ * A user-picker title resolves to the person behind the id, as it always did —
+ * that path is now here rather than in two of the seven.
+ */
+export function useEntityDisplay<T = unknown, M extends Record<string, unknown> = Record<string, unknown>>(
+    role: EntityDisplayRole,
+    {
+        collection,
+        entity,
+        values: valuesProp,
+        enabled = true
+    }: UseEntityDisplayParams<M>
+): ResolvedDisplayValue<T> {
+
+    const context = useRebaseContext();
+    const cache = useEntityDisplayCache();
+
+    const values = valuesProp ?? entity?.values;
+
+    /* ---- the declared or derived key ------------------------------------- */
+
+    // The title is the one role with a ranking behind it: several candidates,
+    // best first, skipping the ones that hold nothing for *this* record. The
+    // others are a single declared or derived key.
+    const declaredKey = collection ? getDisplayPropertyKey(collection, role) : undefined;
+    const propertyKey = collection && role === "title" && !declaredKey
+        ? getEntityTitlePropertyKeyForEntity(collection, values, entity?.id)
+        : declaredKey;
+
+    const rawValue = values && propertyKey ? getValueInPath(values, propertyKey) : undefined;
+
+    // A user picker stores an auth id and renders the person: resolved like a
+    // relation, and hooked unconditionally so the hook order never changes.
+    const titleUser = useResolvedUser(
+        collection && role === "title" && isUserSelectProperty(collection, propertyKey) && typeof rawValue === "string"
+            ? rawValue
+            : undefined
+    );
+
+    const derived = useMemo<T | undefined>(() => {
+        if (titleUser) return getUserLabel(titleUser) as T;
+        if (rawValue === undefined || rawValue === null) return undefined;
+        // Only text roles get flattened to a string; a date stays a date and an
+        // image stays whatever the storage property holds, so the renderer can
+        // still format them.
+        if (role === "title" || role === "subtitle" || role === "status") {
+            return (resolveTitleToString(rawValue) || undefined) as T | undefined;
+        }
+        return rawValue as T;
+    }, [titleUser, rawValue, role]);
+
+    /* ---- the computed answer --------------------------------------------- */
+
+    const resolver = collection ? getDisplayResolver(collection, role) : undefined;
+    const canResolve = Boolean(enabled && resolver && entity);
+    const key = entity ? entityDisplayKey(entity.path, entity.id, role) : undefined;
+
+    const resolved = useSyncExternalStore<unknown>(
+        // Subscribing unconditionally keeps the hook order stable. The store
+        // only notifies when an entry changes, so a collection with no resolver
+        // never re-renders from it.
+        cb => cache.subscribe(cb),
+        () => (canResolve && key ? cache.peek(key) : undefined),
+        // Server render: nothing is resolved, so every slot starts at its
+        // fallback and hydration does not disagree with the markup.
+        () => undefined
+    );
+
+    const loading = Boolean(canResolve && key && resolved === undefined);
+
+    useEffect(() => {
+        if (!canResolve || !key || !resolver || !entity) return;
+        if (cache.peek(key) !== undefined) return;
+        cache.resolve(key, () => resolver({
+            entity,
+            context
+        })).catch(() => {
+            // Unreachable, and kept only so it stays that way: `resolve` records a
+            // failure as "nothing" and returns a RESOLVED promise, which is why
+            // the warning that used to live here could never run — see the note on
+            // `EntityDisplayCache.resolve`. The cache reports the failure itself
+            // now, once per key. This exists so that if `resolve` ever starts
+            // rejecting, it surfaces as a caught no-op rather than an unhandled
+            // rejection during render.
+        });
+    }, [cache, canResolve, key, resolver, entity, context, role]);
+
+    /* ---- the answer ------------------------------------------------------ */
+
+    // A resolver that produced nothing falls back to the derived value rather
+    // than to blank: it said this record has no computed answer for the role,
+    // not that the role should be empty.
+    const computed = canResolve && resolved !== null ? resolved as T | undefined : undefined;
+    const value = computed ?? derived;
+
+    return useMemo(() => ({
+        value,
+        loading,
+        source: collection && propertyKey && value === derived && derived !== undefined
+            ? {
+                key: propertyKey,
+                property: getPropertyInPath(collection.properties, propertyKey),
+                value: rawValue
+            }
+            : undefined
+    }), [value, loading, propertyKey, derived, collection, rawValue]);
+}
+
+/**
+ * Every display role of a record at once — what a list row, a card or a board
+ * card needs, in one call rather than six.
+ *
+ * The role list is iterated from {@link ENTITY_DISPLAY_ROLES} so the hook order
+ * is fixed and adding a role does not mean editing every caller.
+ */
+export function useEntityDisplayValues<M extends Record<string, unknown>>(
+    params: UseEntityDisplayParams<M>
+): Record<EntityDisplayRole, ResolvedDisplayValue> & { loading: boolean } {
+
+    // Not a loop over `useEntityDisplay`: the number of hooks a component calls
+    // has to be fixed at compile time, and a role added to the array later would
+    // silently change it. Written out, it is checked by the return type.
+    const title = useEntityDisplay<string, M>("title", params);
+    const subtitle = useEntityDisplay<string, M>("subtitle", params);
+    const image = useEntityDisplay<string, M>("image", params);
+    const status = useEntityDisplay<string, M>("status", params);
+    const date = useEntityDisplay<Date | string | number, M>("date", params);
+    const tags = useEntityDisplay<string[] | string, M>("tags", params);
+
+    return useMemo(() => ({
+        title,
+        subtitle,
+        image,
+        status,
+        date,
+        tags,
+        loading: title.loading || subtitle.loading || image.loading
+            || status.loading || date.loading || tags.loading
+    }), [title, subtitle, image, status, date, tags]);
+}
+
+/**
+ * What the record is called — the one role asked for often enough on its own to
+ * deserve a name.
+ */
+export function useEntityTitle<M extends Record<string, unknown>>(
+    params: UseEntityDisplayParams<M>
+): ResolvedDisplayValue<string> {
+    return useEntityDisplay<string, M>("title", params);
+}
+
+/** Re-exported so a caller can iterate roles without reaching into types. */
+export { ENTITY_DISPLAY_ROLES };