@rebasepro/admin 0.13.0 → 0.13.1-canary.gcd6689e

package/src/hooks/useEntityDisplay.tsx

@@ -0,0 +1,258 @@
+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((error: unknown) => {
+            // `resolve` has already recorded the failure as "nothing"; this is
+            // the one line that says why, once, rather than per render.
+            console.warn(`[rebase] Could not resolve ${role} for ${key}:`, error);
+        });
+    }, [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 };

package/src/hooks/useEntityDisplayTitle.tsx

@@ -1,60 +1,49 @@
 import type { AdminCollection } from "@rebasepro/admin-types";
-import type { EntityStatus } from "@rebasepro/types";
-import { getValueInPath } from "@rebasepro/utils";
-import { getEntityTitlePropertyKeyForEntity, isUserSelectProperty, resolveTitleToString } from "../util/previews";
-import { getUserLabel, useResolvedUser } from "./useResolvedUsers";
+import type { Entity, EntityStatus } from "@rebasepro/types";
+import { useEntityTitle } from "./useEntityDisplay";
 
 export interface UseEntityDisplayTitleParams<M extends Record<string, unknown>> {
     collection: AdminCollection<M>;
+    /** The record. Needed for a computed title; see {@link useEntityTitle}. */
+    entity?: Entity<M>;
+    /** Live form values, when they are ahead of the entity. */
     values?: Record<string, unknown>;
-    entityId?: string | number;
     status: EntityStatus;
 }
 
 /**
- * The human name for a record, for the identity bar and the breadcrumb.
+ * The heading for a record: the identity bar and the breadcrumb.
  *
- * The guard on `status` is the point. The title resolver walks candidate
- * properties and returns the first non-empty one, and on a brand new entity the
- * only populated values are the property defaults — so creating a blog post
- * opened a page headed **draft**, the default of its `status` enum. A record
- * that does not exist yet has no name; it has an intent.
+ * Everything about *what a record is called* lives in {@link useEntityTitle}.
+ * What is left here is the heading's own two rules, which are presentation, not
+ * identity:
+ *
+ * The guard on `status` is the first. The title resolver returns the first
+ * candidate carrying a value, and on a brand new entity the only values are the
+ * property defaults — so creating a blog post opened a page headed **draft**,
+ * the default of its `status` enum. A record that does not exist yet has no
+ * name; it has an intent.
+ *
+ * The fallback is the second. A page needs a heading even when the record has
+ * nothing readable in it, and the honest one is what kind of thing it is.
  */
 export function useEntityDisplayTitle<M extends Record<string, unknown>>({
     collection,
+    entity,
     values,
-    entityId,
     status
 }: UseEntityDisplayTitleParams<M>): string {
 
     const isNew = status === "new";
-
-    const titlePropertyKey = getEntityTitlePropertyKeyForEntity(collection, values, entityId);
-    const rawTitle = !isNew && values && titlePropertyKey
-        ? getValueInPath(values, titlePropertyKey)
-        : undefined;
-
-    // A user picker stores an id: resolve it to the person, like a relation.
-    const titleUser = useResolvedUser(
-        isUserSelectProperty(collection, titlePropertyKey) && typeof rawTitle === "string"
-            ? rawTitle
-            : undefined
-    );
-
     const singular = collection.singularName ?? collection.name;
 
-    if (isNew) {
-        return `New ${singular.toLowerCase()}`;
-    }
-
-    if (titleUser) {
-        return getUserLabel(titleUser);
-    }
-
-    if (rawTitle !== undefined && rawTitle !== null) {
-        const resolved = resolveTitleToString(rawTitle);
-        if (resolved) return resolved;
-    }
+    const { value: title } = useEntityTitle<M>({
+        collection,
+        entity,
+        values,
+        enabled: !isNew
+    });
 
-    return singular;
+    if (isNew) return `New ${singular.toLowerCase()}`;
+    return title ?? singular;
 }

package/src/preview/PropertyPreview.tsx

@@ -270,7 +270,7 @@ export const PropertyPreview = React.memo(function PropertyPreview<P extends Pro
 
     } else if (property.type === "boolean") {
         if (typeof value === "boolean") {
-            content = <BooleanPreview value={value} size={size} property={property}/>;
+            content = <BooleanPreview value={value} size={size} property={property} hideLabel={props.hideLabel}/>;
         } else {
             content = buildWrongValueType(propertyKey, property.type, value);
         }

package/src/preview/components/BooleanPreview.tsx

@@ -8,18 +8,21 @@ import { PreviewSize } from "../../types/components/PropertyPreviewProps";
 export function BooleanPreview({
     value,
     size,
-    property
+    property,
+    hideLabel
 }: {
     value: boolean,
     size: PreviewSize,
     property: Property,
+    /** The caller already shows the name — see `PropertyPreviewProps.hideLabel`. */
+    hideLabel?: boolean,
 }): React.ReactElement {
     return <div className={"flex flex-row gap-2 items-center"}>
         <Checkbox checked={value}
             padding={false}
             size={size}
             color={"secondary"}/>
-        {property.name && <span
+        {!hideLabel && property.name && <span
             className={cls("text-text-secondary dark:text-text-secondary-dark", size === "small" ? "text-sm" : "")}>{property.name}</span>}
     </div>;
 }

package/src/routes/RebaseRoute.tsx

@@ -6,10 +6,10 @@ import { DetailViewBinding } from "../components/DetailViewBinding";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useNavigate } from "react-router";
 import { CollectionViewBinding } from "../components/CollectionViewBinding/CollectionViewBinding";
-import { NotFoundPage, useUserConfigurationPersistence, useComponentOverride, useNavigationBlocker } from "@rebasepro/app";
+import { ErrorView, NotFoundPage, useUserConfigurationPersistence, useComponentOverride, useNavigationBlocker } from "@rebasepro/app";
 import { resolveOpenEntityMode, resolveViewMode } from "../util/view_mode";
 import { UnsavedChangesDialog } from "@rebasepro/app";
-import { CircularProgressCenter } from "@rebasepro/ui";
+import { CenteredView, CircularProgressCenter } from "@rebasepro/ui";
 import { NavigationViewCollectionInternal, NavigationViewEntityCustomInternal, NavigationViewInternal } from "@rebasepro/app";
 import { getNavigationEntriesFromPath } from "@rebasepro/app";
 import { toArray } from "@rebasepro/utils";
@@ -94,7 +94,7 @@ export function RebaseRoute() {
             if (!collectionRegistry.initialised) {
                 return <CircularProgressCenter/>;
             }
-            return null;
+            return <UnresolvedCollectionView path={navigationEntries[0].slug}/>;
         }
         return <ResolvedCollectionView
             key={`collection_view_${collection.slug}`}
@@ -117,7 +117,7 @@ export function RebaseRoute() {
                 if (!collectionRegistry.initialised) {
                     return <CircularProgressCenter/>;
                 }
-                return null;
+                return <UnresolvedCollectionView path={firstEntry.slug}/>;
             }
             return <ResolvedCollectionView
                 key={`collection_view_${collection.slug}`}
@@ -233,6 +233,7 @@ function EntityFullScreenRoute({
     const urlController = useUrlController();
     const navigate = useNavigate();
     const location = useLocation();
+    const userConfigPersistence = useUserConfigurationPersistence();
 
     // defaultValues may be carried via location.state when openNewDocument() is called
     // for full-screen mode. We read it once on mount — after that, the form owns its state.
@@ -340,6 +341,30 @@ function EntityFullScreenRoute({
     // Determine if this is a detail-view-first collection showing the view page
     const isDetailMode = collection.defaultEntityAction === "view" && !isNew && !isCopy && entityId && !isEditRoute;
 
+    // A record is full screen either because its collection has no list to show
+    // beside it, or because the user folded that list away. Only the second is
+    // reversible, and it is reversible by dropping `#full` alone: this is the
+    // same URL the split route reads, so the same conditions decide it.
+    const splitListAvailable = !isNew && !isCopy && entityId !== undefined &&
+        navigationEntries[0]?.type === "collection" &&
+        (navigationEntries.length === 2 || navigationEntries.length === 3) &&
+        resolveOpenEntityMode({
+            collection,
+            viewMode: resolveViewMode({
+                collection,
+                search: location.search,
+                savedViewMode: userConfigPersistence?.getCollectionConfig(collection.slug)?.defaultViewMode as ViewMode | undefined
+            })
+        }) === "split";
+
+    const showList = splitListAvailable
+        ? () => navigate({
+            pathname,
+            search: location.search,
+            hash: ""
+        })
+        : undefined;
+
     if (isDetailMode) {
         return <>
             <DetailViewBinding
@@ -349,6 +374,7 @@ function EntityFullScreenRoute({
                 layout={"full_screen"}
                 path={collectionPath}
                 selectedTab={selectedTab ?? undefined}
+                onShowList={showList}
                 onEditClick={() => {
                     const editUrl = urlController.buildUrlCollectionPath(`${collectionPath}/${entityId}`) + "/edit";
                     navigate(editUrl + hash);
@@ -377,6 +403,7 @@ function EntityFullScreenRoute({
             path={collectionPath}
             copy={isCopy}
             selectedTab={selectedTab ?? undefined}
+            onShowList={showList}
             defaultValues={isNew ? defaultValues : undefined}
             onValuesModified={(modified) => blocked.current = modified}
             navigateBack={() => {
@@ -415,3 +442,34 @@ function EntityFullScreenRoute({
             body={"You have unsaved changes in this entity."}/>
     </>;
 }
+
+/**
+ * Shown when a URL names a collection the registry cannot resolve.
+ *
+ * This used to be `return null`, which renders an empty pane inside the app
+ * chrome: the sidebar, the nav highlight and the breadcrumb all still work,
+ * because those read the collections array directly, while the view itself is
+ * blank. Nothing is thrown, and the only trace is a `console.debug` — so the
+ * panel looks like it lost its data rather than like it failed to find the
+ * collection, and there is no string to search for.
+ *
+ * A slug containing slashes went unresolvable this way and cost an afternoon to
+ * find. The lookup is fixed; this is the part that made it expensive.
+ */
+function UnresolvedCollectionView({ path }: { path: string }) {
+    // Warn, not debug: this is a route that renders nothing useful, and it
+    // should be visible at the console's default level.
+    useEffect(() => {
+        console.warn(
+            `[rebase] No collection is registered for "${path}", so this route has nothing to render. ` +
+            "Check that the collection is in the collections array and that its slug matches the URL."
+        );
+    }, [path]);
+
+    return <CenteredView>
+        <ErrorView
+            title={"Collection not found"}
+            error={`Nothing is registered for "${path}".`}
+            tooltip={"The URL names a collection the panel does not know about. It may have been renamed or removed from the collections array, or the slug may not match the path."}/>
+    </CenteredView>;
+}

package/src/types/components/PropertyPreviewProps.tsx

@@ -61,4 +61,12 @@ export interface PropertyPreviewProps<P extends Property | Property, CustomProps
      */
     textOnly?: boolean;
 
+    /**
+     * The caller has already labelled this value, so the preview must not
+     * repeat the property name. A boolean is the one that does: it renders its
+     * name beside the checkbox, which reads as a caption in a table cell and as
+     * a stutter under a field label — "VIP" over a checkbox saying "VIP".
+     */
+    hideLabel?: boolean;
+
 }