@rebasepro/admin 0.13.0 → 0.13.1-canary.g3660bd5

package/src/components/EntityViewBinding.tsx

@@ -1,11 +1,69 @@
-import type { Properties } from "@rebasepro/types";
+import type { Property } from "@rebasepro/types";
 
-import type { CustomizationController, AdminCollection } from "@rebasepro/admin-types";
-import React from "react";
+import type { AdditionalFieldDelegateProps, AdminCollection } from "@rebasepro/admin-types";
+import type { ResolvedFormField, ResolvedFormSection } from "@rebasepro/app";
+import type { FormContext } from "../types/fields";
+import React, { useCallback, useMemo, useRef, useState } from "react";
 import { Entity } from "@rebasepro/types";
-import { ExternalLinkIcon, IconButton, Tooltip } from "@rebasepro/ui";
-import { useCustomizationController } from "@rebasepro/app";
-import { PropertyCollectionView } from "./PropertyCollectionView";
+import {
+    AlignLeftIcon,
+    cls,
+    defaultBorderMixin,
+    ErrorBoundary,
+    paperMixin
+} from "@rebasepro/ui";
+import { getFormFieldKeys, resolveFormLayout } from "@rebasepro/app";
+import { getValueInPath } from "@rebasepro/utils";
+
+import { FieldBlock, LABEL_ICON_SIZE, spanClass } from "../form/components/FieldBlock";
+import { AdditionalFieldValue } from "./AdditionalFieldValue";
+import { EntityDisplayHeader, HEADER_DISPLAY_ROLES } from "./EntityDisplayHeader";
+import { FormSections } from "../form/components/FormSections";
+import { FormRail, RecordMeta } from "../form/components/FormRail";
+import { useEntityDisplayValues } from "../hooks/useEntityDisplay";
+import { useRailVisible } from "../form/components/useRailVisible";
+import { LabelWithIconAndTooltip } from "../form/components/LabelWithIconAndTooltip";
+import { PropertyPreview } from "../preview";
+
+/** Nothing can be in error in a view that cannot be submitted. */
+const NO_ERRORS: ReadonlySet<string> = new Set<string>();
+
+/**
+ * The fields the read-only view lays out, in render order.
+ *
+ * The same set the form uses, minus two groups. Both are dropped *before* the
+ * layout resolves rather than skipped while rendering, because the resolver has
+ * by then given each one a place on the grid — skipping later leaves that place
+ * as a hole.
+ *
+ * - The `additionalFields` when there is no form context to hand them: those
+ *   entries are arbitrary components, not values, and one rendered against no
+ *   context is nothing at all.
+ * - `headerKeys` — the properties {@link EntityDisplayHeader} has already
+ *   rendered as the record's picture, subtitle, state and labels. Leaving one in
+ *   prints its value twice on one screen.
+ *
+ * The record's **title property is not among them**, deliberately. It names the
+ * page in the identity bar, but a heading and a labelled field are different
+ * things: `Order #` is a column with a name and a description that someone opens
+ * the record to read, and dropping it because its text also appears in the
+ * breadcrumb removes a value from the record on the grounds that it is legible
+ * somewhere else. See {@link HEADER_DISPLAY_ROLES}.
+ */
+export function readOnlyFieldKeys(
+    collection: AdminCollection,
+    hasFormContext: boolean,
+    headerKeys?: ReadonlySet<string>
+): string[] {
+    const keys = getFormFieldKeys(collection);
+    const additional = hasFormContext
+        ? undefined
+        : new Set((collection.additionalFields ?? []).map(field => field.key));
+
+    return keys.filter(key =>
+        !additional?.has(key)
+        && !headerKeys?.has(key));
+}
 
 /**
  * @group Components
@@ -15,57 +73,299 @@ export interface EntityViewBindingProps<M extends Record<string, unknown>> {
     collection: AdminCollection<M>;
     path: string;
     className?: string;
+    /**
+     * Lay the record out as a page: a centred, scrolling column with the
+     * metadata rail beside it, exactly as the form does. Off for the inline
+     * uses — the delete dialog renders the record inside a box it already owns.
+     */
+    asPage?: boolean;
+    /** Padding preset, matching the form's. Only read when `asPage`. */
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+    /**
+     * Needed only to render `additionalFields`, which are arbitrary components
+     * that take a form context. Without one those entries are left out rather
+     * than rendered against a fake context.
+     */
+    formContext?: FormContext<M>;
 }
 
 /**
  * The read-only rendering of a record's values.
  *
- * This used to prepend a synthetic `Id` row of its own. Between that row, the
- * collection's own id property, and the `path/id` chip above it, the same UUID
- * appeared three times — and in the ~340px split pane each copy wrapped over
- * four lines, so most of the first screen was one id repeated. The id is now a
- * copyable chip in the identity bar, once.
+ * This is the same layout as {@link EntityForm}: the sections, the grid spans,
+ * the labels and the rail all come from the one resolver, so the record does
+ * not rearrange itself when you press Edit. Only the controls differ — each
+ * field renders its {@link PropertyPreview} instead of an input.
+ *
+ * It used to be a flat two-column table of every value in the record: no
+ * grouping, no widths, a label column sized for short names and a value column
+ * that wrapped emails over two lines while the pane beside it stayed empty. A
+ * boolean and a markdown body were given the same room.
+ *
+ * The synthetic `Id` row it used to prepend is gone with the same reasoning the
+ * form applies: between that row, the collection's own id property and the
+ * `path/id` chip above them, one UUID appeared three times. The id is a
+ * copyable chip in the identity bar, and the rail's record block, once each.
+ *
+ * The labels are the form's labels, icon and all: a field is the same field
+ * whether or not you are editing it. What `mode: "read"` drops is the per-field
+ * *description*, which is input help rather than part of the label — and what it
+ * adds is room. A control is a bordered box that separates itself from the next
+ * one; a value is bare text, so the rows and sections are opened up rather than
+ * inheriting spacing sized for inputs.
  */
 export function EntityViewBinding<M extends Record<string, unknown>>(
     {
         entity,
         collection,
-        path,
-        className
+        className,
+        asPage = false,
+        openEntityMode = "full_screen",
+        formContext
     }: EntityViewBindingProps<M>) {
 
-    const customizationController: CustomizationController = useCustomizationController();
-
-    // A single surrogate id is the chip in the identity bar, so listing it again
-    // as the first row here is the duplication the form already removed.
-    //
-    // A composite key is different: `entity.id` is then a synthesised address
-    // (`a:::b`), and the real key columns are data — on a junction row they say
-    // which two records this joins. Those stay in the table.
-    const properties: Properties = React.useMemo(() => {
-        const entries = Object.entries(collection.properties ?? {});
-        const idKeys = entries.filter(([, p]) => p && "isId" in p && p.isId);
-        if (idKeys.length !== 1) return collection.properties;
-        return Object.fromEntries(entries.filter(([key]) => key !== idKeys[0][0])) as Properties;
-    }, [collection.properties]);
-    const externalLink = customizationController?.entityLinkBuilder?.({ entity });
+    // The record's name, picture, state and labels, lifted out of the grid and
+    // into a header. Resolved here rather than inside it because the fields it
+    // renders have to come *out* of the layout, and the layout is resolved here.
+    const display = useEntityDisplayValues<M>({
+        collection,
+        entity
+    });
+
+    const headerKeys = useMemo(() => {
+        const keys = new Set<string>();
+        for (const role of HEADER_DISPLAY_ROLES) {
+            // Set only for a role filled by a property of this collection. A
+            // role filled by a resolver has no field on the grid to remove.
+            const key = display[role].source?.key;
+            if (key) keys.add(key);
+        }
+        return keys;
+    }, [display]);
+
+    // Only *whether* there is a form context changes the field list, not which
+    // one it is — so the memo turns on the boolean rather than on the context
+    // object, which is rebuilt on every keystroke of the form above it.
+    const hasFormContext = Boolean(formContext);
+    const fieldKeys = useMemo(
+        () => readOnlyFieldKeys(collection as AdminCollection, hasFormContext, headerKeys),
+        [collection, hasFormContext, headerKeys]
+    );
+
+    // `status: "existing"` — a record you are reading exists by definition, and
+    // that is what routes a generated id and the audit timestamps out of the
+    // column and into the record block.
+    const layout = useMemo(() => resolveFormLayout({
+        collection,
+        fieldKeys,
+        status: "existing"
+    }), [collection, fieldKeys]);
+
+    const containerRef = useRef<HTMLDivElement>(null);
+    // Measured, not a breakpoint — see `useRailVisible`. The same reasoning as
+    // the form's: the resolver *moves* fields into the rail, so when the rail
+    // cannot be shown they have to fold back into the column.
+    const railVisible = useRailVisible(containerRef);
+    const showRail = asPage && layout.hasRail && railVisible;
+
+    const [collapsedSections, setCollapsedSections] = useState<Set<string>>(
+        () => new Set(layout.sections.filter(section => section.collapsed).map(section => section.key))
+    );
+    const toggleSection = useCallback((key: string) => {
+        setCollapsedSections(prev => {
+            const next = new Set(prev);
+            if (next.has(key)) next.delete(key); else next.add(key);
+            return next;
+        });
+    }, []);
+
+    const renderField = useCallback((field: ResolvedFormField): React.ReactNode => {
+
+        if (field.additional) {
+            const additionalField = collection.additionalFields?.find(f => f.key === field.key);
+            if (!additionalField || !formContext) return null;
+
+            const AdditionalFieldBuilder = additionalField.Builder;
+            const additionalFieldContext = formContext as unknown as AdditionalFieldDelegateProps["context"];
+            const child = AdditionalFieldBuilder
+                ? <AdditionalFieldBuilder entity={entity} context={additionalFieldContext}/>
+                : <div className={"w-full"}>
+                    <AdditionalFieldValue
+                        field={additionalField}
+                        entity={entity}
+                        context={additionalFieldContext}/>
+                </div>;
+
+            return (
+                <div key={`additional_${field.key}`} className={spanClass(field.span)}>
+                    <LabelWithIconAndTooltip
+                        propertyKey={field.key}
+                        icon={<AlignLeftIcon size={LABEL_ICON_SIZE}/>}
+                        title={additionalField.name}
+                        className={"text-text-secondary dark:text-text-secondary-dark"}/>
+                    <div className={cls(paperMixin, "w-full min-h-14 p-4 md:p-6 overflow-x-auto no-scrollbar")}>
+                        <ErrorBoundary>
+                            {child}
+                        </ErrorBoundary>
+                    </div>
+                </div>
+            );
+        }
+
+        const property = collection.properties?.[field.key] as Property | undefined;
+        if (!property) return null;
+
+        return (
+            <div key={`field_${field.key}`} className={spanClass(field.span)}>
+                {/* Always labelled from here, unlike the form. The panel editors
+                    that carry their own header have no header in preview — a map
+                    previews as a table of its children and an array as its items,
+                    so leaving the label to them would leave them unlabelled. */}
+                <FieldBlock propertyKey={field.key}
+                    property={property}
+                    showLabel={true}
+                    mode={"read"}>
+                    {/* One control's height for a single-line value, so a row of
+                        short fields lines up with the taller ones beside it, and
+                        anything longer simply grows. Matched to the form's row
+                        rather than shrunk to the text: it is what keeps a value
+                        from sitting directly on the label of the row below. */}
+                    <div className={"min-h-8 flex flex-col justify-center min-w-0 text-text-primary dark:text-text-primary-dark"}>
+                        <PropertyPreview propertyKey={field.key}
+                            value={getValueInPath(entity.values, field.key)}
+                            property={property}
+                            hideLabel
+                            size={"medium"}/>
+                    </div>
+                </FieldBlock>
+            </div>
+        );
+    }, [collection, entity, formContext]);
+
+    /**
+     * One field of a `readVariant: "summary"` section: a label/value row rather
+     * than a grid cell, with the last one emphasised.
+     *
+     * The last row is the one a summary exists for — a run of figures is read to
+     * arrive at its final line — so it is separated by a rule and set at the
+     * weight the grid gave every cell equally.
+     */
+    const renderSummaryField = useCallback((
+        field: ResolvedFormField,
+        index: number,
+        total: number
+    ): React.ReactNode => {
+
+        const property = collection.properties?.[field.key] as Property | undefined;
+        if (!property) return null;
+
+        const last = index === total - 1;
+
+        return (
+            <div key={`summary_${field.key}`}
+                className={cls(
+                    "flex items-baseline justify-between gap-4 min-w-0 py-2",
+                    last && total > 1 && cls("mt-1.5 pt-3 border-t", defaultBorderMixin)
+                )}>
+                <span className={cls(
+                    "min-w-0 truncate",
+                    last
+                        ? "text-sm font-semibold text-text-primary dark:text-text-primary-dark"
+                        : "text-sm text-text-secondary dark:text-text-secondary-dark"
+                )}>
+                    {property.name ?? field.key}
+                </span>
+                <span className={cls(
+                    "shrink-0 text-right text-text-primary dark:text-text-primary-dark",
+                    last ? "text-base font-semibold" : "text-sm"
+                )}>
+                    <PropertyPreview propertyKey={field.key}
+                        value={getValueInPath(entity.values, field.key)}
+                        property={property}
+                        hideLabel
+                        size={"medium"}/>
+                </span>
+            </div>
+        );
+    }, [collection, entity]);
+
+    // Same fold-back as the form: with no room for the rail its fields become a
+    // trailing group rather than disappearing.
+    const sections: ResolvedFormSection[] = showRail || !layout.sidebar.length
+        ? layout.sections
+        : [
+            ...layout.sections,
+            {
+                key: "__rail",
+                title: "Settings",
+                collapsible: false,
+                collapsed: false,
+                fields: layout.sidebar
+            }
+        ];
+
+    const content = <>
+        {/* The title only when nothing above is already showing it. Every
+            full-page use sits under an identity bar that carries it; the
+            inline ones — the delete dialog — have no bar. */}
+        <EntityDisplayHeader entity={entity}
+            collection={collection}
+            showTitle={!asPage}
+            className={"mb-10"}/>
+
+        <FormSections sections={sections}
+            collapsed={collapsedSections}
+            onToggle={toggleSection}
+            errorKeys={NO_ERRORS}
+            renderField={renderField}
+            renderSummaryField={renderSummaryField}
+            mode={"read"}/>
+
+        {/* Folded back with the rail's fields, and for the same reason. The rail
+            renders only where it has been measured to fit, so on the split pane,
+            the side panel and the dialog this block was dropped outright and the
+            record's id was nowhere on screen but the truncated chip in the bar.
+            An id you cannot read or copy is the one piece of a record you most
+            often opened it for. */}
+        {!showRail && layout.showRecordMeta && (
+            <div className={cls("mt-10 pt-6 border-t max-w-sm", defaultBorderMixin)}>
+                <RecordMeta entity={entity as Entity<Record<string, unknown>>}/>
+            </div>
+        )}
+    </>;
+
+    if (!asPage) {
+        // `@container/col` even here: the spans resolve against the column they
+        // sit in, and inside a dialog that column is the dialog.
+        return (
+            <div ref={containerRef} className={cls("@container/col w-full min-w-0", className)}>
+                {content}
+            </div>
+        );
+    }
 
     return (
-        <div className={"w-full " + (className ?? "")}>
-
-            {externalLink && (
-                <div className={"flex justify-end mb-2"}>
-                    <Tooltip title={"Open in the live site"}>
-                        <a href={externalLink} rel={"noopener noreferrer"} target={"_blank"}>
-                            <IconButton size={"small"}>
-                                <ExternalLinkIcon/>
-                            </IconButton>
-                        </a>
-                    </Tooltip>
+        <div ref={containerRef} className={cls("flex-1 flex flex-row w-full min-h-0", className)}>
+
+            {/* `items-start`: without it the cross-axis default stretches the
+                column to the scroller's height and its bottom padding lands at
+                the bottom of the viewport instead of after the last field. */}
+            <div className={"flex-1 min-w-0 overflow-y-auto flex justify-center items-start"}>
+                <div className={cls(
+                    "@container/col w-full max-w-3xl 2xl:max-w-4xl flex flex-col",
+                    openEntityMode === "dialog"
+                        ? "pt-5 pb-8 px-6 sm:px-8"
+                        : "pt-6 pb-12 px-5 sm:px-8"
+                )}>
+                    {content}
                 </div>
-            )}
+            </div>
 
-            <PropertyCollectionView data={entity.values} properties={properties} size={"medium"}/>
+            {showRail && <FormRail
+                fields={layout.sidebar}
+                showRecordMeta={layout.showRecordMeta}
+                entity={entity as Entity<Record<string, unknown>>}
+                renderField={renderField}/>}
         </div>
     );
 }

package/src/components/InlineEntityPreview.tsx

@@ -3,10 +3,9 @@ import * as React from "react";
 import { Entity } from "@rebasepro/types";
 import { cls, LinkIcon, Skeleton, Tooltip } from "@rebasepro/ui";
 import { useAnalyticsController } from "@rebasepro/app";
-import { getValueInPath } from "@rebasepro/utils";
 import type { AdminCollection } from "@rebasepro/admin-types";
 
-import { getEntityTitlePropertyKeyForEntity } from "../util/previews";
+import { useEntityTitle } from "../hooks/useEntityDisplay";
 import { useCollectionRegistryController } from "../hooks/navigation/contexts/CollectionRegistryContext";
 import { useSidePanel } from "../hooks/useSidePanel";
 
@@ -57,14 +56,15 @@ export function InlineEntityPreview({
 
     const collection = collectionProp ?? collectionRegistryController.getCollection(entity.path);
 
-    const titlePropertyKey = collection
-        ? getEntityTitlePropertyKeyForEntity(collection, entity.values, entity.id)
-        : undefined;
-    const titleValue = titlePropertyKey ? getValueInPath(entity.values, titlePropertyKey) : undefined;
-    const resolvedLabel = label
-        ?? (titleValue !== undefined && titleValue !== null && String(titleValue).trim().length > 0
-            ? String(titleValue)
-            : String(entity.id));
+    // The id is the right fallback *here* specifically: this renders a pointer at
+    // another record, and a pointer with no label is still followable if it says
+    // which record it points at. A page heading makes the opposite choice.
+    const { value: title } = useEntityTitle({
+        collection: collection as AdminCollection,
+        entity,
+        enabled: Boolean(collection)
+    });
+    const resolvedLabel = label ?? title ?? String(entity.id);
 
     const interactive = !disabled && (onClick !== undefined || (includeEntityLink && collection !== undefined));
 

package/src/components/RebaseLayout.tsx

@@ -19,7 +19,7 @@ export interface RebaseLayoutProps {
     appBar?: React.ReactNode;
     /** Custom Drawer to override the default. */
     drawer?: React.ReactNode;
-    /** Expand the drawer while the pointer is over it. Not a load-time default — that is `defaultDrawerOpen`. */
+    /** Expand the drawer while the pointer is over it. On by default; pass `false` to opt out. Not a load-time default — that is `defaultDrawerOpen`. */
     autoOpenDrawer?: boolean;
     /** Start with the drawer expanded instead of collapsed to icons. Ignored on small layouts. */
     defaultDrawerOpen?: boolean;
@@ -52,7 +52,7 @@ export function RebaseLayout(props: RebaseLayoutProps) {
         title = "Rebase",
         appBar,
         drawer,
-        autoOpenDrawer = false,
+        autoOpenDrawer = true,
         defaultDrawerOpen = false,
         logo,
         devViews = []

package/src/components/RebaseShell.tsx

@@ -14,7 +14,7 @@ export interface RebaseShellProps {
     /** Top bar. Only rendered if provided — pass `<AppBar/>` for the default one. */
     appBar?: React.ReactNode;
     drawer?: React.ReactNode;
-    /** Expand the drawer while the pointer is over it. Not a load-time default — that is `defaultDrawerOpen`. */
+    /** Expand the drawer while the pointer is over it. On by default; pass `false` to opt out. Not a load-time default — that is `defaultDrawerOpen`. */
     autoOpenDrawer?: boolean;
     /** Start with the drawer expanded instead of collapsed to icons. Ignored on small layouts. */
     defaultDrawerOpen?: boolean;
@@ -44,7 +44,7 @@ export function RebaseShell(props: RebaseShellProps) {
         title = "Rebase",
         appBar,
         drawer,
-        autoOpenDrawer = false,
+        autoOpenDrawer = true,
         defaultDrawerOpen = false,
         logo,
         children

package/src/components/app/Scaffold.tsx

@@ -4,17 +4,48 @@ import { ChevronLeftIcon, ErrorBoundary, MenuIcon } from "@rebasepro/ui";
 import { deepEqual as equal } from "fast-equals"
 
 import { useLargeLayout, useAdminModeController, useTranslation } from "@rebasepro/app";
+import { useUrlController } from "../../hooks/navigation/contexts/UrlContext";
 import { AppContext } from "./useApp";
 
 export const DRAWER_WIDTH = 280;
 
+/**
+ * Namespaced by base path: two admins served from one origin are two different
+ * navigations, and a single key would have them overwrite each other's drawer.
+ */
+export function drawerOpenStorageKey(basePath: string | undefined) {
+    return `rebase-drawer-open:${basePath || "/"}`;
+}
+
+/** `null` when the user has never toggled the drawer, or storage is unavailable. */
+function readStoredDrawerOpen(key: string): boolean | null {
+    if (typeof window === "undefined") return null;
+    try {
+        const stored = window.localStorage.getItem(key);
+        return stored === null ? null : stored === "true";
+    } catch (e) {
+        // Storage can be blocked: private mode, sandboxed iframe, cookie policy.
+        return null;
+    }
+}
+
+function writeStoredDrawerOpen(key: string, open: boolean) {
+    if (typeof window === "undefined") return;
+    try {
+        window.localStorage.setItem(key, String(open));
+    } catch (e) {
+        // Same as above: a drawer that forgets is better than a crash.
+    }
+}
+
 /**
  * @group Core
  */
 export interface ScaffoldProps {
 
     /**
-     * Open the drawer on hover
+     * Expand the collapsed drawer while the pointer is over it. On by default —
+     * pass `false` to keep the rail a rail until the user clicks the toggle.
      */
     autoOpenDrawer?: boolean;
 
@@ -22,8 +53,8 @@ export interface ScaffoldProps {
      * Start with the drawer expanded rather than collapsed to icons.
      *
      * Distinct from {@link autoOpenDrawer}, which is a hover behaviour: this one
-     * only seeds the initial state, so the user's own toggle still wins for the
-     * rest of the session.
+     * only seeds the very first visit. Once the user toggles the drawer, that
+     * choice is stored in `localStorage` and wins over this prop on every load.
      *
      * Ignored on small layouts, where an expanded drawer covers the content it is
      * meant to navigate.
@@ -62,7 +93,7 @@ export const Scaffold = React.memo<PropsWithChildren<ScaffoldProps>>(
 
         const {
             children,
-            autoOpenDrawer,
+            autoOpenDrawer = true,
             defaultDrawerOpen = false,
             logo,
             className,
@@ -83,25 +114,96 @@ export const Scaffold = React.memo<PropsWithChildren<ScaffoldProps>>(
         const includeDrawer = drawerChildren.length > 0;
         const largeLayout = useLargeLayout();
 
+        const storageKey = drawerOpenStorageKey(useUrlController().basePath);
+
         // Seeded once, deliberately: a `useEffect` syncing this to the prop would
         // re-expand the drawer under a user who had just collapsed it.
-        const [drawerOpen, setDrawerOpen] = React.useState(defaultDrawerOpen && largeLayout);
+        const [drawerOpen, setDrawerOpenState] = React.useState(defaultDrawerOpen && largeLayout);
         const [onHover, setOnHover] = React.useState(false);
 
-        const setOnHoverTrue = useCallback(() => setOnHover(true), []);
+        // The stored choice is a client-only fact, so it is applied after the first
+        // render rather than seeded into it: reading storage while rendering would
+        // make the client disagree with server-rendered HTML. A layout effect runs
+        // before paint, so the drawer still arrives in its remembered state.
+        // `defaultDrawerOpen` seeds the very first visit and is ignored after that.
+        React.useLayoutEffect(() => {
+            const stored = readStoredDrawerOpen(storageKey);
+            if (stored === null) return;
+            setDrawerOpenState(stored && largeLayout);
+            // Deliberately not re-run on `largeLayout`: crossing the breakpoint is
+            // the effect below, and re-running here would undo a user's toggle.
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        }, [storageKey]);
+
+        // One piece of state drives two different things: the expanded rail on
+        // large layouts, and the modal sheet on small ones. Carrying an expanded
+        // rail across the breakpoint would drop that sheet, overlay and all, over
+        // the content — so the crossing resets it, and widening again restores
+        // whatever the user last chose.
+        const wasLargeLayout = React.useRef(largeLayout);
+        React.useEffect(() => {
+            if (wasLargeLayout.current === largeLayout) return;
+            wasLargeLayout.current = largeLayout;
+            setDrawerOpenState(largeLayout ? (readStoredDrawerOpen(storageKey) ?? defaultDrawerOpen) : false);
+        }, [largeLayout, defaultDrawerOpen, storageKey]);
+
+        const setDrawerOpen = useCallback((open: boolean) => {
+            setDrawerOpenState(open);
+            // Small layouts render the drawer as a modal sheet. Remembering that
+            // one would greet the next load with an overlay over the content.
+            if (!largeLayout) return;
+            writeStoredDrawerOpen(storageKey, open);
+        }, [largeLayout, storageKey]);
+
+        // The pointer has left, but a popover the drawer opened is still up, so the
+        // collapse is owed rather than cancelled. See `setOnHoverFalse`.
+        const collapseWhenPopoverCloses = React.useRef(false);
+
+        const setOnHoverTrue = useCallback(() => {
+            // Hover expansion is the default; `autoOpenDrawer={false}` opts out for
+            // admins that want the rail to stay a rail until the toggle is clicked.
+            if (!autoOpenDrawer) return;
+            collapseWhenPopoverCloses.current = false;
+            setOnHover(true);
+        }, [autoOpenDrawer]);
         const setOnHoverFalse = useCallback(() => {
-            // Don't collapse the drawer while a popover/dropdown is open
-            if (document.querySelector("[data-radix-popper-content-wrapper]")) return;
+            // Don't collapse the drawer out from under an open popover/dropdown —
+            // its content is portalled outside the drawer, so reaching for it reads
+            // as a mouseleave. The collapse is owed until that popover closes.
+            if (document.querySelector("[data-radix-popper-content-wrapper]")) {
+                collapseWhenPopoverCloses.current = true;
+                return;
+            }
+            collapseWhenPopoverCloses.current = false;
             setOnHover(false);
         }, []);
 
+        // Nothing fires a second mouseleave when the popover finally closes, so the
+        // owed collapse has to be noticed rather than waited for. Only mounted
+        // while the drawer is actually floating open.
+        React.useEffect(() => {
+            if (!onHover) return;
+            const collapseIfOwed = () => {
+                if (!collapseWhenPopoverCloses.current) return;
+                if (document.querySelector("[data-radix-popper-content-wrapper]")) return;
+                collapseWhenPopoverCloses.current = false;
+                setOnHover(false);
+            };
+            const observer = new MutationObserver(collapseIfOwed);
+            observer.observe(document.body, {
+                childList: true,
+                subtree: true
+            });
+            return () => observer.disconnect();
+        }, [onHover]);
+
         const handleDrawerOpen = useCallback(() => {
             setDrawerOpen(true);
-        }, []);
+        }, [setDrawerOpen]);
 
         const handleDrawerClose = useCallback(() => {
             setDrawerOpen(false);
-        }, []);
+        }, [setDrawerOpen]);
 
         const computedDrawerOpen: boolean = drawerOpen;
         const computedDrawerHovered = Boolean(largeLayout && onHover);