@rebasepro/admin 0.13.0 → 0.13.1-canary.g249daa1

package/src/components/EditViewBinding.tsx

@@ -38,13 +38,15 @@ import {
     useSlot,
     getIcon
 } from "@rebasepro/app";
-import { getEntityFromMemoryCache } from "@rebasepro/app";
+import { getEntityFromMemoryCache, removeEntityFromMemoryCache, saveEntityToMemoryCache } from "@rebasepro/app";
 import { EntityFormBinding } from "../form";
+import { getEditHandoffValues } from "../form/form_utils";
 import type { EntityFormBindingProps } from "../form";
 import type { OnUpdateParams } from "../types/components/EntityFormProps";
 import { EditFormActions } from "./EditFormActions";
 import { EntityIdentityBar } from "./EntityIdentityBar";
 import { SplitListCloseButton } from "./CollectionViewBinding/SplitListCloseButton";
+import { SplitListShowButton } from "./CollectionViewBinding/SplitListShowButton";
 import { useRecordActions } from "../hooks/useRecordActions";
 import { useSideDialogContext } from "./SideDialogs";
 import { useAdminContext } from "../hooks/useAdminContext";
@@ -53,10 +55,17 @@ import { useEntityDisplayTitle } from "../hooks/useEntityDisplayTitle";
 import { createFormexStub, getEntityFromCache } from "@rebasepro/app";
 import { usePermissions } from "@rebasepro/app";
 import { useUrlController } from "../hooks/navigation/contexts/UrlContext";
-import { withViewMode } from "../util/view_mode";
+import { withListState } from "../util/view_mode";
 import { useNavigate } from "react-router";
 
-import { MAIN_TAB_VALUE, JSON_TAB_VALUE, HISTORY_TAB_VALUE } from "../util/view_constants";
+import {
+    MAIN_TAB_VALUE,
+    JSON_TAB_VALUE,
+    HISTORY_TAB_VALUE,
+    ENTITY_VIEW_TAB_BAR_CLASS,
+    ENTITY_VIEW_TAB_CLASS,
+    ENTITY_VIEW_TAB_LABEL_CLASS
+} from "../util/view_constants";
 export { MAIN_TAB_VALUE, JSON_TAB_VALUE, HISTORY_TAB_VALUE };
 
 export type BarActionsParams = {
@@ -64,6 +73,19 @@ export type BarActionsParams = {
     status: EntityStatus,
     path: string,
     entityId?: string | number;
+    /** Whether `values` differ from what is stored. */
+    dirty: boolean;
+    /**
+     * Hand the edit in progress to the layout this action is about to open, so
+     * the record arrives showing — and still holding — what the user typed here.
+     * Call it from any action that changes layout without leaving the record;
+     * it decides on its own whether there is anything worth carrying, so a
+     * record nobody edited still arrives clean.
+     *
+     * Only supplied where there is a form to carry: the detail view passes no
+     * such thing.
+     */
+    carryEdit?: () => void;
 };
 
 export type OnTabChangeParams<M extends Record<string, unknown>> = {
@@ -89,6 +111,16 @@ export interface EditViewBindingProps<M extends Record<string, unknown> = Record
     onSaved?: (params: OnUpdateParams) => void;
     onTabChange?: (props: OnTabChangeParams<M>) => void;
     navigateBack?: () => void;
+    /**
+     * Dismiss this record — the ✕ at the identity bar's trailing edge, and what
+     * "save and close" reaches once the save lands.
+     *
+     * Set by the layouts that own the record's place on screen but are not side
+     * dialogs: the split, where dismissing is navigating back to the collection.
+     * The side panel and the dialog close through {@link useSideDialogContext}
+     * instead, which is what runs their unsaved-changes prompt.
+     */
+    onCloseRequest?: () => void;
     layout?: "side_panel" | "full_screen" | "split" | "dialog";
     barActions?: (params: BarActionsParams) => React.ReactNode;
     /**
@@ -96,6 +128,12 @@ export interface EditViewBindingProps<M extends Record<string, unknown> = Record
      * of the breadcrumb — the side panel's close button.
      */
     barActionsStart?: React.ReactNode;
+    /**
+     * Full screen only: bring the list back beside this record. Set when the
+     * record was opened out of a split collection, so folding the list away is
+     * reversible; it takes the place of the back arrow when present.
+     */
+    onShowList?: () => void;
     formProps?: Partial<EntityFormBindingProps<M>>,
     /**
      * Pre-populate the form with these values when creating a new entity.
@@ -127,9 +165,39 @@ export function EditViewBinding<M extends Record<string, unknown>>({
         useCache: false
     });
 
-    const initialDirtyValues = entityId
-        ? getEntityFromMemoryCache(props.path + "/" + entityId)
-        : (props.defaultValues ?? getEntityFromMemoryCache(props.path + "#new"));
+    // The edit handed over by another layout of this same record — see
+    // {@link carryEdit} below for the sending half.
+    //
+    // Read once per record and consumed: this is a handoff, and an edit left in
+    // the channel after it has been picked up is one that reopens the record
+    // dirty on a later, unrelated visit, carrying values the user walked away
+    // from. Held in a ref rather than re-read each render, because the read has
+    // to survive the clear — {@link EntityFormBinding} measures the
+    // local-changes banner against what the form opens showing, and a prop that
+    // reverted to `undefined` once the cache was cleared would raise the banner
+    // over the very edit that was just carried in.
+    //
+    // A copy is keyed with the new records, not under the record it was copied
+    // from: it is going to be stored as its own row, and both the handoff and
+    // the local-changes backup have always keyed it that way from the writing
+    // side. Reading it under `path/id` meant a copy in progress was written to
+    // one key and looked for under another.
+    const carriesAsNew = props.copy || entityId === undefined;
+    const handoffKey = carriesAsNew ? props.path + "#new" : props.path + "/" + entityId;
+    const handoff = useRef<{ key: string, values: object | undefined } | null>(null);
+    if (handoff.current?.key !== handoffKey) {
+        handoff.current = {
+            key: handoffKey,
+            values: getEntityFromMemoryCache(handoffKey)
+        };
+    }
+    useEffect(() => {
+        removeEntityFromMemoryCache(handoffKey);
+    }, [handoffKey]);
+
+    const initialDirtyValues = carriesAsNew
+        ? (props.defaultValues ?? handoff.current.values)
+        : handoff.current.values;
 
     const { canEdit: canEditHook } = usePermissions();
 
@@ -186,12 +254,14 @@ export function EditViewBindingInner<M extends Record<string, unknown>>({
     onSaved,
     onTabChange,
     navigateBack,
+    onCloseRequest,
     entity,
     initialDirtyValues,
     dataLoading,
     layout = "side_panel",
     barActions,
     barActionsStart,
+    onShowList,
     status,
     setStatus,
     formProps,
@@ -271,7 +341,9 @@ parentEntityIds,
         }
     }, [selectedTabProp, defaultSelectedView]);
 
-    const childViews = getAdminEntityChildViews(collection).filter(v => !v.collection.hideFromNavigation);
+    // See DetailViewBinding: tabs are governed by `hideFromEntityViews`, the
+    // drawer by `hideFromNavigation`. They are separate roles.
+    const childViews = getAdminEntityChildViews(collection).filter(v => !v.collection.hideFromEntityViews);
     const subcollections = childViews.map(v => v.collection);
     const subcollectionsCount = subcollections?.length ?? 0;
     const customViews = collection.entityViews ?? [];
@@ -405,8 +477,8 @@ parentEntityIds,
 
     const displayTitle = useEntityDisplayTitle({
         collection,
+        entity: usedEntity,
         values: (formContext?.values ?? usedEntity?.values) as Record<string, unknown> | undefined,
-        entityId,
         status
     });
 
@@ -420,6 +492,35 @@ parentEntityIds,
         || (status === "existing" && !formex?.dirty)
     );
 
+    /**
+     * Hand this record's edit in progress to the layout about to replace this
+     * one — the split's "hide list", full screen's "show list", the side panel's
+     * "open full screen". None of them is a navigation *away* from the record:
+     * the same record is about to be shown by a different form, and what the
+     * user has typed belongs to the record, not to the pane it was typed in.
+     *
+     * Every control that changes layout has to call this, and none of them is
+     * blocked by the unsaved-changes prompt — the prompt asks about leaving, and
+     * these do not leave. What used to happen instead is that the edit reached
+     * the next layout only as its local-changes backup, which is the channel for
+     * a draft left behind by a closed tab: the record reopened *clean*, with a
+     * banner offering to apply changes the user had never walked away from.
+     */
+    const carryEdit = useCallback(() => {
+        const carried = formex
+            ? getEditHandoffValues<M>({
+                status,
+                dirty: formex.dirty,
+                values: formex.values,
+                touched: formex.touched,
+                storedValues: usedEntity?.values
+            })
+            : undefined;
+        if (!carried) return;
+        const key = (status === "new" || status === "copy") ? path + "#new" : path + "/" + entityId;
+        saveEntityToMemoryCache(key, carried);
+    }, [formex, status, path, entityId, usedEntity]);
+
     const [inspectorTab, setInspectorTab] = useState<InspectorTab | null>(null);
     // A save adds a revision, and the inspector can be open while it happens:
     // Save lives in the identity bar, above the panel. Counting saves gives the
@@ -429,7 +530,26 @@ parentEntityIds,
     /* ---- record actions, in the bar's overflow menu ---------------------- */
 
     const sideDialogContext = useSideDialogContext();
-    const canCloseAfterSave = layout === "side_panel" || layout === "dialog";
+
+    /**
+     * Whether the save in flight was asked to dismiss the record afterwards.
+     *
+     * A ref, and for the reason {@link SideDialogs} keeps its own as one: the
+     * flag is raised and the form submitted in a single click handler, and the
+     * `onSaved` that has to act on it was captured before React could re-render.
+     * As state it read one save late — the first "save and close" saved and
+     * stayed open, and the *next* save closed the record.
+     *
+     * The side panel and the dialog use the side-dialog controller's flag,
+     * which their own close path consumes; this one covers the layouts that
+     * close by calling {@link onCloseRequest} instead.
+     */
+    const pendingCloseRef = useRef(false);
+
+    // The split can close after a save the same way the overlays do — through
+    // the callback its layout supplies. Without one there is nothing to close.
+    const canCloseAfterSave = layout === "side_panel" || layout === "dialog"
+        || (layout === "split" && Boolean(onCloseRequest));
 
     const recordActions = useRecordActions({
         collection,
@@ -524,35 +644,40 @@ parentEntityIds,
     const FormViewBuilder = formViewConfig?.Builder ? resolveComponentRef<EntityCustomViewParams>(formViewConfig.Builder as ComponentRef<EntityCustomViewParams>) : null;
     const formViewIncludeActions = formViewConfig?.includeActions !== false;
 
-    const entityReadOnlyView = !canEdit && entity ? <div
-        className={cls("flex-1 flex flex-row w-full overflow-y-auto justify-center", (canEdit || !mainViewVisible || selectedSecondaryForm) ? "hidden" : "")}>
-        <div
-            className={cls("relative flex flex-col max-w-4xl lg:max-w-3xl xl:max-w-4xl 2xl:max-w-6xl w-full h-fit")}>
-            <Typography className={"mt-16 mb-8 mx-8"} variant={"h4"}>
-                {collection.singularName ?? collection.name}
-            </Typography>
-            {FormViewBuilder && readOnlyFormContext ? (
-                <ErrorBoundary>
-                    <Suspense fallback={<CircularProgressCenter />}>
-                        <FormViewBuilder
-                            collection={collection}
-                            parentCollectionSlugs={parentCollectionSlugs} parentEntityIds={parentEntityIds}
-                            entity={usedEntity}
-                            modifiedValues={usedEntity?.values}
-                            formContext={readOnlyFormContext as FormContext<Record<string, unknown>>}
-                        />
-                    </Suspense>
-                </ErrorBoundary>
-            ) : (
-                <EntityViewBinding
-                    className={"px-8 h-full overflow-auto"}
-                    entity={entity}
-                    path={path}
-                    collection={collection} />
-            )}
-            <div className="h-16" />
-        </div>
-    </div> : null;
+    // Without edit permission the record is rendered read-only — the same
+    // sections, spans and rail as the form, so losing the permission changes the
+    // controls and nothing else. The `h4` that used to head this repeated the
+    // collection name the identity bar above it already carries.
+    const entityReadOnlyView = !canEdit && entity ? (
+        FormViewBuilder && readOnlyFormContext
+            ? <div className={cls(
+                "@container/form flex-1 flex flex-row w-full overflow-y-auto justify-center",
+                (canEdit || !mainViewVisible || selectedSecondaryForm) ? "hidden" : ""
+            )}>
+                {/* Same widths as the default form (see EntityForm). */}
+                <div className={"w-full max-w-3xl @7xl/form:max-w-4xl 2xl:max-w-4xl flex flex-col pt-6 pb-16 px-5 sm:px-8"}>
+                    <ErrorBoundary>
+                        <Suspense fallback={<CircularProgressCenter />}>
+                            <FormViewBuilder
+                                collection={collection}
+                                parentCollectionSlugs={parentCollectionSlugs} parentEntityIds={parentEntityIds}
+                                entity={usedEntity}
+                                modifiedValues={usedEntity?.values}
+                                formContext={readOnlyFormContext as FormContext<Record<string, unknown>>}
+                            />
+                        </Suspense>
+                    </ErrorBoundary>
+                </div>
+            </div>
+            : <EntityViewBinding
+                className={cls((canEdit || !mainViewVisible || selectedSecondaryForm) ? "hidden" : "")}
+                entity={entity}
+                path={path}
+                collection={collection}
+                asPage
+                openEntityMode={layout}
+                formContext={readOnlyFormContext}/>
+    ) : null;
 
     const entityView = FormViewBuilder ? (
         // formView.Builder replaces the default form
@@ -609,8 +734,32 @@ parentEntityIds,
                     ...params,
                     selectedTab: MAIN_TAB_VALUE === activeTab ? undefined : activeTab
                 };
+                // Two caller-supplied callbacks for one save, and either may
+                // navigate — the layouts' `onSaved` all do. Where both do, the
+                // second one's destination is what survives (docs/bug-classes.md
+                // #28), so `formProps.onSaved` is deliberately last: it belongs
+                // to whoever embedded this view, which outranks the layout.
                 onSaved?.(res);
                 formProps?.onSaved?.(res);
+
+                // After `onSaved`, never instead of it: the layout's own handler
+                // is what lowers its dirty flag, and closing is a navigation the
+                // unsaved-changes blocker would otherwise stop on values that
+                // are already stored.
+                //
+                // And after this handler returns, not inside it. The layouts
+                // that close this way close by navigating, and they have just
+                // navigated themselves — the split leaves `…/edit` for the
+                // record's own URL. Deferring keeps the close unambiguously
+                // last, which is what decides it: of two navigations raised for
+                // one action the final one survives, measured in
+                // `router_two_navigations_one_handler.test.tsx`. It also lets
+                // the state those handlers just set settle before the blocker
+                // reads it. See docs/bug-classes.md #28.
+                if (pendingCloseRef.current) {
+                    pendingCloseRef.current = false;
+                    setTimeout(() => onCloseRequest?.(), 0);
+                }
             }}
             Builder={resolveComponentRef(selectedSecondaryForm?.Builder as ComponentRef<EntityCustomViewParams<M>> | undefined) as React.ComponentType<EntityCustomViewParams<M>> | undefined}
         />
@@ -620,7 +769,7 @@ parentEntityIds,
         const icon = getIcon(subcollection.icon, undefined, undefined, "smallest");
         return (
             <Tab
-                className="text-sm min-w-[90px]"
+                className={cls(ENTITY_VIEW_TAB_CLASS, ENTITY_VIEW_TAB_LABEL_CLASS)}
                 value={subcollection.slug}
                 key={`entity_detail_collection_tab_${subcollection.name}`}>
                 <span className="flex items-center gap-1.5">
@@ -636,7 +785,7 @@ parentEntityIds,
             const icon = getIcon(view.icon, undefined, undefined, "smallest");
             return (
                 <Tab
-                    className={!view.tabComponent ? "text-sm min-w-[90px]" : undefined}
+                    className={cls(ENTITY_VIEW_TAB_CLASS, !view.tabComponent && ENTITY_VIEW_TAB_LABEL_CLASS)}
                     value={view.key}
                     key={`entity_detail_collection_tab_${view.name}`}>
                     {view.tabComponent ?? (
@@ -653,7 +802,7 @@ parentEntityIds,
             const icon = getIcon(view.icon, undefined, undefined, "smallest");
             return (
                 <Tab
-                    className={!view.tabComponent ? "text-sm min-w-[90px]" : undefined}
+                    className={cls(ENTITY_VIEW_TAB_CLASS, !view.tabComponent && ENTITY_VIEW_TAB_LABEL_CLASS)}
                     value={view.key}
                     key={`entity_detail_collection_tab_${view.name}`}>
                     {view.tabComponent ?? (
@@ -673,6 +822,7 @@ parentEntityIds,
             <IconButton
                 size="small"
                 onClick={() => {
+                    carryEdit();
                     const editSuffix = collection.defaultEntityAction === "view" ? "/edit" : "";
                     const entityUrl = urlController.buildUrlCollectionPath(`${path}/${entityId}${editSuffix}`);
                     navigate(`${entityUrl}#full`);
@@ -687,6 +837,9 @@ parentEntityIds,
 
         <EntityIdentityBar
             collection={collection as AdminCollection}
+            collectionUrl={layout === "full_screen" || layout === "split"
+                ? withListState(urlController.buildUrlCollectionPath(path))
+                : undefined}
             title={displayTitle}
             entityId={status === "existing" ? entityId : undefined}
             status={status}
@@ -696,29 +849,55 @@ parentEntityIds,
             saveDisabled={!canEdit || saveDisabled}
             // Full screen replaces the collection entirely, leaving browser Back
             // as the only route to it. The detail view has carried this arrow
-            // for that reason; the edit view is reached the same way.
-            onBack={layout === "full_screen"
-                ? () => navigate(withViewMode(urlController.buildUrlCollectionPath(path)))
+            // for that reason; the edit view is reached the same way. Where the
+            // list can be unfolded back beside the record, that chevron reaches
+            // the same collection and the arrow beside it is noise.
+            onBack={layout === "full_screen" && !onShowList
+                ? () => navigate(withListState(urlController.buildUrlCollectionPath(path)))
                 : undefined}
             onSave={canEdit && formContext ? () => {
                 sideDialogContext.setPendingClose?.(false);
+                pendingCloseRef.current = false;
                 formContext.submit();
             } : undefined}
             onSaveAndClose={canEdit && formContext && canCloseAfterSave ? () => {
+                // Lowered again once the submit settles. A submit the form
+                // rejects never reaches `onSaved`, so nothing would consume the
+                // flag and the *next* save — a keyboard ⌘S, say — would close
+                // the panel out from under an edit nobody asked to finish. A
+                // save that succeeds has already closed by the time this runs.
+                if (layout === "split") {
+                    pendingCloseRef.current = true;
+                    Promise.resolve(formContext.submit())
+                        .finally(() => { pendingCloseRef.current = false; });
+                    return;
+                }
                 sideDialogContext.setPendingClose?.(true);
-                formContext.submit();
+                Promise.resolve(formContext.submit())
+                    .finally(() => sideDialogContext.setPendingClose?.(false));
             } : undefined}
+            // Welded to Save in the split, its own button in the overlays.
+            saveAndClosePlacement={layout === "split" ? "menu" : "button"}
+            onClose={onCloseRequest}
             onDiscard={canEdit && formContext ? () => formContext.formex.resetForm() : undefined}
             onInspect={includeJsonView ? () => setInspectorTab("json") : undefined}
             onViewHistory={includeHistoryView ? () => setInspectorTab("history") : undefined}
+            externalLink={usedEntity
+                ? customizationController?.entityLinkBuilder?.({ entity: usedEntity })
+                : undefined}
             recordActions={recordActionItems}
             pluginActions={formPluginActions}
             leading={<>
                 {barActionsStart}
                 {/* Split view: closing the list is opening this record
                     full screen, and the control for it belongs at this
-                    bar's leading edge. */}
-                {layout === "split" && <SplitListCloseButton/>}
+                    bar's leading edge. Full screen carries its mirror.
+                    Both change layout, so both hand the edit over. */}
+                {layout === "split" && <SplitListCloseButton onBeforeHide={carryEdit}/>}
+                {layout === "full_screen" && onShowList && <SplitListShowButton onClick={() => {
+                    carryEdit();
+                    onShowList();
+                }}/>}
             </>}
             trailing={<>
                 {pluginActionsTop}
@@ -727,7 +906,9 @@ parentEntityIds,
                     path,
                     entityId,
                     values: formContext?.values ?? usedEntity?.values ?? {},
-                    status
+                    status,
+                    dirty: Boolean(formContext?.formex?.dirty),
+                    carryEdit
                 })}
             </>}
         />
@@ -737,10 +918,11 @@ parentEntityIds,
             disappears entirely when there is nowhere else to go. */}
         {hasAdditionalViews && <div className={cls(
             "h-10 shrink-0 flex items-stretch border-b px-2 min-w-0",
+            ENTITY_VIEW_TAB_BAR_CLASS,
             defaultBorderMixin
         )}>
             <Tabs
-                className={"!w-full"}
+                className={"!w-full items-stretch"}
                 innerClassName={"h-full"}
                 variant={"boxy"}
                 value={activeTab}
@@ -748,7 +930,8 @@ parentEntityIds,
                     onSideTabClick(value);
                 }}>
 
-                <Tab value={MAIN_TAB_VALUE}>
+                <Tab value={MAIN_TAB_VALUE}
+                     className={cls(ENTITY_VIEW_TAB_CLASS, ENTITY_VIEW_TAB_LABEL_CLASS)}>
                     <span className="flex items-center gap-1.5">
                         {getIcon(collection.icon, undefined, undefined, "smallest")}
                         {collection.singularName ?? collection.name}

package/src/components/EntityDisplayHeader.tsx

@@ -0,0 +1,170 @@
+import type { AdminCollection } from "@rebasepro/admin-types";
+import type { Entity, Property } from "@rebasepro/types";
+import React from "react";
+import { Chip, cls, Typography } from "@rebasepro/ui";
+
+import { useEntityDisplayValues } from "../hooks/useEntityDisplay";
+import { PropertyPreview } from "../preview";
+
+/**
+ * The roles whose property the read-only view takes out of its grid.
+ *
+ * A role rendered here and left in the grid prints the value twice, so the
+ * header's own rendering and this list have to agree — but the list is *not*
+ * simply "every role the header draws". Two are deliberately absent:
+ *
+ * `title`, because the heading above a record and a labelled field are not the
+ * same thing. `Order #` is a column with a name, a description and a format that
+ * someone reads the record to find; `ORD-2026-0043` sitting in the identity bar
+ * beside the breadcrumb is a label for the page. Removing the field because the
+ * page is named after it takes a value out of the record on the grounds that its
+ * text appears elsewhere, which is not a reason — a value in the database is
+ * shown.
+ *
+ * `date`, because the rail's record block already carries the timestamps, and a
+ * collection whose `date` role points at a business date — an order date, a due
+ * date — wants that field where it declared it.
+ */
+export const HEADER_DISPLAY_ROLES = ["subtitle", "image", "status", "tags"] as const;
+
+export interface EntityDisplayHeaderProps<M extends Record<string, unknown>> {
+    entity: Entity<M>;
+    collection: AdminCollection<M>;
+    /**
+     * Render the title. Off when an identity bar above already shows it — which
+     * is every full-page use — and on inside a dialog that has no bar.
+     */
+    showTitle?: boolean;
+    className?: string;
+}
+
+/**
+ * What the record *is*, above the fields that say what it holds.
+ *
+ * A record's picture, name, state and labels are the things you opened the page
+ * to see; on the plain grid they were fields like any other, so an order's
+ * status sat in the second cell of the first row at the same size and weight as
+ * its shipping cost, and its tags were a wrapped list of grey text.
+ *
+ * Every role here comes from `admin.display` and nothing is derived except the
+ * title, which was already derived for the identity bar. A collection that
+ * declares no display block therefore gets no header at all rather than a
+ * heuristic guess at which of its enums is a "status" — the panel does not know
+ * what these records are, and a wrong guess here is louder than no guess.
+ *
+ * A role filled by a *property* renders through {@link PropertyPreview}, so a
+ * status keeps its enum's colour and an image stays a storage thumbnail. A role
+ * filled by a resolver has no property behind it and renders as what it
+ * returned.
+ */
+export function EntityDisplayHeader<M extends Record<string, unknown>>({
+    entity,
+    collection,
+    showTitle = false,
+    className
+}: EntityDisplayHeaderProps<M>) {
+
+    const display = useEntityDisplayValues<M>({
+        collection,
+        entity
+    });
+
+    const title = showTitle ? asText(display.title.value) : undefined;
+    const subtitle = asText(display.subtitle.value);
+    const tags = asTags(display.tags.value);
+
+    const hasStatus = display.status.value !== undefined;
+    const hasImage = display.image.value !== undefined;
+
+    if (!title && !subtitle && !hasStatus && !hasImage && !tags.length) return null;
+
+    return (
+        <div className={cls("flex items-start gap-4 min-w-0", className)}>
+
+            {hasImage && (
+                <div className={"shrink-0 w-16 h-16 rounded-lg overflow-hidden flex items-center justify-center bg-surface-100 dark:bg-surface-800"}>
+                    <RoleValue role={display.image} propertyFallback={
+                        // A resolver's image is documented as a URL; a storage
+                        // path only resolves when a property is behind it, which
+                        // is what carries the storage source.
+                        typeof display.image.value === "string"
+                            ? <img src={display.image.value}
+                                alt={""}
+                                className={"w-full h-full object-cover"}/>
+                            : null
+                    }/>
+                </div>
+            )}
+
+            <div className={"flex flex-col gap-1.5 min-w-0 flex-1"}>
+
+                {title && (
+                    <Typography variant={"h5"} className={"min-w-0 truncate m-0"}>
+                        {title}
+                    </Typography>
+                )}
+
+                {subtitle && (
+                    <Typography variant={"body2"}
+                        color={"secondary"}
+                        className={"min-w-0 m-0"}>
+                        {subtitle}
+                    </Typography>
+                )}
+
+                {(hasStatus || tags.length > 0) && (
+                    <div className={"flex flex-wrap items-center gap-1.5"}>
+                        {hasStatus && (
+                            <RoleValue role={display.status} propertyFallback={
+                                <Chip size={"small"}>{asText(display.status.value)}</Chip>
+                            }/>
+                        )}
+                        {tags.map(tag => (
+                            <Chip key={tag} size={"small"} outlined>{tag}</Chip>
+                        ))}
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+}
+
+/**
+ * One resolved role, rendered richly when a property is behind it.
+ *
+ * `source` is set only when the value came from a property of this collection
+ * (see `useEntityDisplay`), and it carries what a rich rendering needs. Its
+ * absence is exactly the "this was computed" signal, and a computed value is a
+ * bare string with no property to describe it — hence the fallback.
+ */
+function RoleValue({
+    role,
+    propertyFallback
+}: {
+    role: { value: unknown, source?: { key: string, property: Property | undefined, value: unknown } };
+    propertyFallback: React.ReactNode;
+}) {
+    const source = role.source;
+    if (!source?.property) return <>{propertyFallback}</>;
+    return <PropertyPreview propertyKey={source.key}
+        value={source.value}
+        property={source.property}
+        hideLabel
+        size={"medium"}/>;
+}
+
+/** A role's value as a line of text, or nothing when it holds nothing to read. */
+function asText(value: unknown): string | undefined {
+    if (value === undefined || value === null) return undefined;
+    const text = String(value).trim();
+    return text.length ? text : undefined;
+}
+
+/** The `tags` role, which takes a single string as shorthand for one tag. */
+function asTags(value: unknown): string[] {
+    if (value === undefined || value === null) return [];
+    const list = Array.isArray(value) ? value : [value];
+    return list
+        .map(entry => asText(entry))
+        .filter((entry): entry is string => Boolean(entry));
+}