nexus-shared 3.0.0 → 3.1.0

package/dist/Client.Index.d.ts

@@ -43,12 +43,15 @@ export * from "./Components/Layouts/PopupRules.ts";
 export * from "./Components/Layouts/ThemePicker.tsx";
 export * from "./Components/Layouts/ThemeSwitcher.tsx";
 export * from "./Components/Layouts/Toaster.tsx";
+export * from "./Components/Viewers/Avatar.tsx";
 export * from "./Components/Viewers/DataTable.tsx";
 export * from "./Components/Viewers/DataTableParts.tsx";
 export * from "./Helpers/ChatHooks.ts";
 export * from "./Helpers/DatePreferences.ts";
 export * from "./Helpers/DragHelpers.ts";
 export * from "./Helpers/PopoverHelpers.ts";
+export * from "./Helpers/PopoverHooks.ts";
+export * from "./Helpers/UserPreferences.ts";
 export * from "./Services/BrowserApi.ts";
 export * from "./Services/ChatApi.ts";
 export * from "./Services/ExcelApi.ts";

package/dist/Client.Index.js

@@ -46,6 +46,7 @@ export * from "./Components/Layouts/PopupRules.js";
 export * from "./Components/Layouts/ThemePicker.js";
 export * from "./Components/Layouts/ThemeSwitcher.js";
 export * from "./Components/Layouts/Toaster.js";
+export * from "./Components/Viewers/Avatar.js";
 export * from "./Components/Viewers/DataTable.js";
 export * from "./Components/Viewers/DataTableParts.js";
 // Helpers
@@ -53,6 +54,8 @@ export * from "./Helpers/ChatHooks.js";
 export * from "./Helpers/DatePreferences.js";
 export * from "./Helpers/DragHelpers.js";
 export * from "./Helpers/PopoverHelpers.js";
+export * from "./Helpers/PopoverHooks.js";
+export * from "./Helpers/UserPreferences.js";
 // Services
 export * from "./Services/BrowserApi.js";
 export * from "./Services/ChatApi.js";

package/dist/Components/Chats/ChatParts.d.ts

@@ -1,7 +1,7 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import { type ChatTimeOptions } from "../../Helpers/ChatHelpers.ts";
 import type { ChatAttachment, ChatId, ChatMessage, ChatParticipant } from "../../Interfaces/ChatInterfaces.ts";
-/** A round photo, or the initials of the name on a tone picked from it — the same look and tones as a dropdown's. */
+/** The shared `Avatar`, under the name the chat has always exported it by. */
 export declare function ChatAvatar({ name, src, size }: {
     name: string;
     src?: string | null;

package/dist/Components/Chats/ChatParts.js

@@ -1,23 +1,19 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { iconAlertCircle, iconCheck, iconChecks, iconCornerUpLeft, iconFile, iconLoader2, iconRefresh, iconTrash, iconX, InlineIcon } from "nexus-icons";
-import { useState } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { chatDeliveryState, chatFileSize, chatTimeLabel, sameChatId, CHAT_DELIVERY_LABELS } from "../../Helpers/ChatHelpers.js";
-import { avatarTone, initials } from "../../Helpers/DropdownHelpers.js";
 import { markdownToPlainText } from "../../Helpers/MarkdownHelpers.js";
+import { Avatar } from "../Viewers/Avatar.js";
 import { MarkdownView } from "../Viewers/MarkdownView.js";
 /*
  * The pieces a chat is drawn from: the avatar, one message, the lines that break a thread into days and into read and
  * unread, and the participants. Each one draws what it is given and nothing else — the state is in `ChatStore` — so
  * the same pieces serve the panel, a page-wide chat, and a demo with messages in memory.
  */
-/** A round photo, or the initials of the name on a tone picked from it — the same look and tones as a dropdown's. */
+/** The shared `Avatar`, under the name the chat has always exported it by. */
 export function ChatAvatar({ name, src, size = "md" }) {
-    const url = typeof src === "string" ? src.trim() : "";
-    const [failed, setFailed] = useState(null);
-    const photo = url !== "" && failed !== url;
-    return (_jsx("span", { className: cx("nx-chat-avatar", size === "sm" && "nx-chat-avatar--sm"), "data-tone": photo ? undefined : avatarTone(name), "aria-hidden": "true", children: photo ? _jsx("img", { src: url, alt: "", loading: "lazy", decoding: "async", onError: () => setFailed(url) }) : initials(name) }));
+    return _jsx(Avatar, { name: name, src: src, size: size });
 }
 /** The day a run of messages was written: "Today", "Yesterday", or the date in the user's calendar. */
 export function ChatDayDivider({ label }) {

package/dist/Components/Chats/ChatThread.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { iconArrowDown, iconMessageCircle, InlineIcon } from "nexus-icons";
 import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { smoothScrollAllowed } from "../../Helpers/AnimationHelpers.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { chatBadgeText, chatMessageKey, groupChatMessages, sameChatId } from "../../Helpers/ChatHelpers.js";
 import { useBrowserTimeZone, useDatePreferences } from "../../Helpers/DatePreferences.js";
@@ -37,9 +38,8 @@ export function ChatThread({ store, state, userId, time, replies = true, onReply
         const list = listRef.current;
         if (!list)
             return;
-        // Windows with its animations off reports reduced motion, and a smooth scroll there may never run: jump instead.
-        const reduced = typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-        list.scrollTo({ top: list.scrollHeight, behavior: smooth && !reduced ? "smooth" : "auto" });
+        // Smooth only when the visitor and the system both allow motion; otherwise it jumps.
+        list.scrollTo({ top: list.scrollHeight, behavior: smooth && smoothScrollAllowed() ? "smooth" : "auto" });
     }, []);
     // New messages: stay at the bottom when already there, otherwise hold the place and count what came in.
     useLayoutEffect(() => {

package/dist/Components/Documents/Button.d.ts

@@ -21,9 +21,14 @@ export interface ButtonProps extends ComponentPropsWithRef<"button"> {
     loading?: boolean;
     /** Fills the width of its container. */
     block?: boolean;
+    /**
+     * A small dot on the corner. `true` is the red dot of something new, such as unread notifications; `"primary"` marks
+     * a state that is on, such as filters.
+     */
+    dot?: boolean | "primary";
 }
 /**
  * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
  * Has no client state, so it renders in server and client components alike.
  */
-export declare function Button({ variant, size, hoverTone, icon, iconEnd, loading, block, type, disabled, className, children, ...rest }: ButtonProps): import("react").JSX.Element;
+export declare function Button({ variant, size, hoverTone, icon, iconEnd, loading, block, dot, type, disabled, className, children, ...rest }: ButtonProps): import("react").JSX.Element;

package/dist/Components/Documents/Button.js

@@ -5,7 +5,7 @@ import { cx } from "../../Helpers/ClassHelpers.js";
  * A button. Without children it becomes a square icon button, which then needs an `aria-label`.
  * Has no client state, so it renders in server and client components alike.
  */
-export function Button({ variant = "secondary", size = "md", hoverTone, icon, iconEnd, loading = false, block = false, type = "button", disabled, className, children, ...rest }) {
+export function Button({ variant = "secondary", size = "md", hoverTone, icon, iconEnd, loading = false, block = false, dot = false, type = "button", disabled, className, children, ...rest }) {
     const hasLabel = children !== undefined && children !== null && children !== false;
-    return (_jsxs("button", { type: type, className: cx("nx-btn", `nx-btn--${variant}`, `nx-btn--${size}`, hoverTone && `nx-btn--hover-${hoverTone}`, block && "nx-btn--block", !hasLabel && "nx-btn--icon", className), disabled: disabled || loading, "aria-busy": loading || undefined, ...rest, children: [loading ? _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) : icon, hasLabel && _jsx("span", { className: "nx-btn__label", children: children }), iconEnd] }));
+    return (_jsxs("button", { type: type, className: cx("nx-btn", `nx-btn--${variant}`, `nx-btn--${size}`, hoverTone && `nx-btn--hover-${hoverTone}`, block && "nx-btn--block", !hasLabel && "nx-btn--icon", className), disabled: disabled || loading, "aria-busy": loading || undefined, ...rest, children: [loading ? _jsx(InlineIcon, { icon: iconLoader2, className: "nx-spin" }) : icon, hasLabel && _jsx("span", { className: "nx-btn__label", children: children }), iconEnd, dot && _jsx("span", { className: "nx-btn__dot", "data-tone": dot === true ? undefined : dot, "aria-hidden": "true" })] }));
 }

package/dist/Components/Documents/Menu.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { iconCheck, InlineIcon } from "nexus-icons";
 import { cloneElement, useId, useLayoutEffect, useRef, useState, } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
-import { followAnchor, isPopoverOpen, placeAtPoint, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { followAnchor, isPopoverOpen, placeAtPoint, placeUnderAnchor, showPanel } from "../../Helpers/PopoverHelpers.js";
 export function isMenuItem(entry) {
     return "value" in entry;
 }
@@ -12,10 +12,16 @@ const ITEM_ROLE = {
     radio: "menuitemradio",
     checkbox: "menuitemcheckbox",
 };
-const ENABLED_ITEM = '.nx-menu__item:not([aria-disabled="true"])';
+// A row, and a control an app put in a heading (the admin's account card has the picture there). The arrow keys walk
+// both: Tab shuts a menu, so a control inside one is reachable no other way.
+const ENABLED_ITEM = '.nx-menu__item:not([aria-disabled="true"]), .nx-menu__heading [role="menuitem"]:not([aria-disabled="true"])';
 function enabledItems(panel) {
     return Array.from(panel.querySelectorAll(ENABLED_ITEM));
 }
+/** Where a menu opened from the keyboard starts: its first row, never a control in a heading above the rows. */
+function firstRowIndex(panel) {
+    return Math.max(0, enabledItems(panel).findIndex(item => item.classList.contains("nx-menu__item")));
+}
 /** Focuses the item at `index`, counting from the end when negative and wrapping past either end. */
 function focusItemAt(panel, index) {
     const items = enabledItems(panel);
@@ -87,7 +93,8 @@ export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", clo
         event.preventDefault();
     }
     // Focus follows the pointer, so the arrow keys carry on from the item under it. Only a pointer that moved counts:
-    // a menu opened from the keyboard under a resting pointer keeps the focus on its first item.
+    // a menu opened from the keyboard under a resting pointer keeps the focus on its first item. It never scrolls the
+    // list: an item half under the edge would pull the list up under the pointer, and the heading out of sight with it.
     const pointerRef = useRef({ x: 0, y: 0 });
     function onPointerMove(event) {
         const last = pointerRef.current;
@@ -96,12 +103,17 @@ export function MenuPanel({ id, items, onSelect, kind = "menu", size = "md", clo
         pointerRef.current = { x: event.clientX, y: event.clientY };
         const item = event.currentTarget;
         if (item.getAttribute("aria-disabled") !== "true" && document.activeElement !== item)
-            item.focus();
+            item.focus({ preventScroll: true });
+    }
+    // A control in a heading is chosen like a row, so it closes the menu like one.
+    function onClick(event) {
+        if (closeOnSelect && event.target.closest('.nx-menu__heading [role="menuitem"]'))
+            hide(event.currentTarget);
     }
     const role = ITEM_ROLE[kind];
     // When any item has an icon, every item keeps the icon column, so the labels line up.
     const hasIcons = items.some(entry => isMenuItem(entry) && entry.icon);
-    return (_jsx("div", { ref: ref, id: id, popover: "auto", role: "menu", tabIndex: -1, className: cx("nx-popover", "nx-menu", `nx-menu--${size}`, className), onToggle: onToggle, onKeyDown: onKeyDown, ...labelling, children: _jsx("div", { role: "none", className: "nx-menu__list", children: items.map((entry, index) => {
+    return (_jsx("div", { ref: ref, id: id, popover: "auto", role: "menu", tabIndex: -1, className: cx("nx-popover", "nx-menu", `nx-menu--${size}`, className), onToggle: onToggle, onKeyDown: onKeyDown, onClick: onClick, ...labelling, children: _jsx("div", { role: "none", className: "nx-menu__list nx-popover__scroll", children: items.map((entry, index) => {
                 // Items are keyed by their value, so a separator keyed by its index alone collided with an item whose value
                 // was that number ("5" in a menu of projects). The prefix keeps the two apart.
                 if (!isMenuItem(entry)) {
@@ -151,12 +163,12 @@ export function Menu({ children, align = "start", "aria-label": ariaLabel, onOpe
         const panel = panelRef.current;
         if (!canShow(panel) || isPopoverOpen(panel))
             return;
-        panel.showPopover();
+        showPanel(panel);
         place();
         if (focus === "panel")
             panel.focus();
         else
-            focusItemAt(panel, focus === "first" ? 0 : -1);
+            focusItemAt(panel, focus === "first" ? firstRowIndex(panel) : -1);
     }
     // The panel is fixed, so it follows the button while the page scrolls or the window changes size.
     useLayoutEffect(() => {
@@ -223,7 +235,7 @@ export function ContextMenu({ children, "aria-label": ariaLabel = "Context menu"
             return;
         event.preventDefault();
         hide(panel);
-        panel.showPopover();
+        showPanel(panel);
         const fromPointer = performance.now() - pressedAtRef.current < 1500;
         if (fromPointer) {
             placeAtPoint(panel, event.clientX, event.clientY);
@@ -233,7 +245,7 @@ export function ContextMenu({ children, "aria-label": ariaLabel = "Context menu"
             // From the keyboard (Shift+F10, the Menu key): browsers report the event at the element or at 0,0, so the
             // menu opens under the focused element like a dropdown (above it when there is no room), on its first item.
             placeUnderAnchor(panel, event.target.getBoundingClientRect());
-            focusItemAt(panel, 0);
+            focusItemAt(panel, firstRowIndex(panel));
         }
     }
     return (_jsxs("div", { className: "nx-context-target", onPointerDown: () => {

package/dist/Components/Documents/SplitButton.d.ts

@@ -29,6 +29,8 @@ export interface SplitButtonProps<T extends string = string> {
     storageKey?: string;
     /** Picking an action in the menu also runs it. Default false: it only becomes the main button, as on GitHub. */
     runOnSelect?: boolean;
+    /** The main button never changes: the menu holds other ways to do it, each run when picked, with no check mark. */
+    fixed?: boolean;
     /** Default `primary`. */
     variant?: ButtonVariant;
     /** Default `md`. */
@@ -61,4 +63,4 @@ export interface SplitButtonProps<T extends string = string> {
  *   { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready" },
  * ]} />
  */
-export declare function SplitButton<T extends string>({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect, variant, size, loading, disabled, block, type, form, name, menuLabel, align, className, style, }: SplitButtonProps<T>): import("react").JSX.Element | null;
+export declare function SplitButton<T extends string>({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect, fixed, variant, size, loading, disabled, block, type, form, name, menuLabel, align, className, style, }: SplitButtonProps<T>): import("react").JSX.Element | null;

package/dist/Components/Documents/SplitButton.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { iconChevronDown, InlineIcon } from "nexus-icons";
 import { useId, useLayoutEffect, useRef, useState } from "react";
 import { cx } from "../../Helpers/ClassHelpers.js";
-import { followAnchor, isPopoverOpen, placeUnderAnchor } from "../../Helpers/PopoverHelpers.js";
+import { followAnchor, isPopoverOpen, placeUnderAnchor, showPanel } from "../../Helpers/PopoverHelpers.js";
 import { Button } from "./Button.js";
 import { MenuPanel } from "./Menu.js";
 const STORAGE_PREFIX = "nx-split:";
@@ -37,7 +37,7 @@ function saveChoice(key, value) {
  *   { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready" },
  * ]} />
  */
-export function SplitButton({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect = false, variant = "primary", size = "md", loading = false, disabled = false, block = false, type = "button", form, name, menuLabel = "More actions", align = "end", className, style, }) {
+export function SplitButton({ options, onAction, defaultValue, value, onValueChange, storageKey, runOnSelect = false, fixed = false, variant = "primary", size = "md", loading = false, disabled = false, block = false, type = "button", form, name, menuLabel = "More actions", align = "end", className, style, }) {
     const id = useId();
     const panelId = `${id}-menu`;
     const toggleRef = useRef(null);
@@ -68,7 +68,7 @@ export function SplitButton({ options, onAction, defaultValue, value, onValueCha
         const panel = panelRef.current;
         if (!panel || typeof panel.showPopover !== "function" || isPopoverOpen(panel))
             return;
-        panel.showPopover();
+        showPanel(panel);
         place();
         if (focusFirst)
             panel.querySelector('.nx-menu__item:not([aria-disabled="true"])')?.focus();
@@ -92,6 +92,8 @@ export function SplitButton({ options, onAction, defaultValue, value, onValueCha
         const option = usable(next);
         if (!option || !current)
             return;
+        if (fixed)
+            return onAction(next, option);
         if (value === undefined)
             setChosen(next);
         saveChoice(storageKey, next);
@@ -100,7 +102,7 @@ export function SplitButton({ options, onAction, defaultValue, value, onValueCha
         if (runOnSelect)
             onAction(next, option);
     }
-    const items = options.map(option => ({
+    const items = (fixed ? options.filter(option => option.value !== current.value) : options).map(option => ({
         value: option.value,
         label: option.label,
         description: option.description,
@@ -125,5 +127,5 @@ export function SplitButton({ options, onAction, defaultValue, value, onValueCha
                         event.preventDefault();
                         show(true);
                     }
-                } }), _jsx(MenuPanel, { ref: panelRef, id: panelId, kind: "radio", size: size, items: items, onSelect: pick, "aria-label": menuLabel, onToggle: onToggle, className: "nx-split__menu" })] }));
+                } }), _jsx(MenuPanel, { ref: panelRef, id: panelId, kind: fixed ? "menu" : "radio", size: size, items: items, onSelect: pick, "aria-label": menuLabel, onToggle: onToggle, className: "nx-split__menu" })] }));
 }

package/dist/Components/Documents/TabButtons.d.ts

@@ -13,8 +13,11 @@ export interface TabButtonOption<T extends string = string> {
     /** Tooltip. With `labels="selected"`, a text label is the default tooltip. */
     title?: string;
 }
-/** `all`: every option shows its label. `selected`: options show only their icon, and the selected one adds its label. */
-export type TabButtonLabels = "all" | "selected";
+/**
+ * `all`: every option shows its label. `selected`: options show only their icon, and the selected one adds its label.
+ * `auto`: every label while its container (a data table) is at least 900px wide, `selected` below that.
+ */
+export type TabButtonLabels = "all" | "selected" | "auto";
 /** `nav`: a horizontal track with a sliding indicator. `list`: a vertical list of rows, for settings pages and side panels. */
 export type TabButtonDesign = "nav" | "list";
 interface TabButtonsBaseProps<T extends string> {

package/dist/Components/Documents/TabButtons.js

@@ -16,7 +16,7 @@ export function TabButtons(props) {
     const generatedName = useId();
     const groupName = name ?? generatedName;
     const list = design === "list";
-    const labelsSelected = !list && labels === "selected";
+    const labelsSelected = !list && labels !== "all";
     const chosen = props.multiple ? new Set(props.value) : null;
     // One choice slides one indicator; several have no single place for it, so each chosen option draws its own.
     const index = chosen ? -1 : options.findIndex(option => option.value === props.value);
@@ -34,5 +34,5 @@ export function TabButtons(props) {
             next.delete(option.value);
         props.onChange(options.filter(one => next.has(one.value)).map(one => one.value));
     };
-    return (_jsxs("div", { role: chosen ? "group" : "radiogroup", "aria-orientation": list && !chosen ? "vertical" : undefined, ...labelling, className: cx("nx-tabs", `nx-tabs--${size}`, list && "nx-tabs--list", tone === "primary" && "nx-tabs--primary", labelsSelected && "nx-tabs--labels-selected", chosen && !list && "nx-tabs--multiple", block && "nx-tabs--block", className), style: list || chosen ? undefined : style, children: [index >= 0 && !list && !labelsSelected && _jsx("span", { className: "nx-tabs__indicator", "aria-hidden": "true" }), options.map(option => (_jsxs("label", { className: "nx-tabs__option", title: option.title ?? (labelsSelected && typeof option.label === "string" ? option.label : undefined), children: [_jsx("input", { type: chosen ? "checkbox" : "radio", className: "nx-visually-hidden", name: groupName, form: form, value: option.value, checked: isChecked(option), disabled: option.disabled, onChange: event => toggle(option, event.currentTarget.checked) }), option.icon, _jsxs("span", { className: "nx-tabs__label", children: [_jsx("span", { className: "nx-tabs__text", children: option.label }), list && option.description && _jsx("span", { className: "nx-tabs__description", children: option.description })] }), list && option.badge !== undefined && option.badge !== null && _jsx("span", { className: "nx-tabs__badge", children: option.badge })] }, option.value)))] }));
+    return (_jsxs("div", { role: chosen ? "group" : "radiogroup", "aria-orientation": list && !chosen ? "vertical" : undefined, ...labelling, className: cx("nx-tabs", `nx-tabs--${size}`, list && "nx-tabs--list", tone === "primary" && "nx-tabs--primary", labelsSelected && "nx-tabs--labels-selected", !list && labels === "auto" && "nx-tabs--labels-auto", chosen && !list && "nx-tabs--multiple", block && "nx-tabs--block", className), style: list || chosen ? undefined : style, children: [index >= 0 && !list && !labelsSelected && _jsx("span", { className: "nx-tabs__indicator", "aria-hidden": "true" }), options.map(option => (_jsxs("label", { className: "nx-tabs__option", title: option.title ?? (labelsSelected && typeof option.label === "string" ? option.label : undefined), children: [_jsx("input", { type: chosen ? "checkbox" : "radio", className: "nx-visually-hidden", name: groupName, form: form, value: option.value, checked: isChecked(option), disabled: option.disabled, onChange: event => toggle(option, event.currentTarget.checked) }), option.icon, _jsxs("span", { className: "nx-tabs__label", children: [_jsx("span", { className: "nx-tabs__text", children: option.label }), list && option.description && _jsx("span", { className: "nx-tabs__description", children: option.description })] }), list && option.badge !== undefined && option.badge !== null && _jsx("span", { className: "nx-tabs__badge", children: option.badge })] }, option.value)))] }));
 }

package/dist/Components/Forms/ApiForm.d.ts

@@ -7,7 +7,7 @@ import type { ApiFormProps, FormValues } from "../../Interfaces/FormInterfaces.t
  * details, or any JSON by its status. On success a toast says so and the values become the form's own; on failure the
  * server's own words show - every message it sent, on the inputs they name and the rest under the form, with our message
  * by status only for an answer that explains nothing - and the first input with a message takes focus. `loadValue` loads
- * the record to edit, with placeholders and Retry.
+ * the record to edit: the inputs show disabled until it lands, and a failure offers Retry.
  *
  * @example
  * const ROOMS = apiController(NexusModule.Reservation, "Room", "room");

package/dist/Components/Forms/ApiForm.js

@@ -20,7 +20,7 @@ import { SubmitForm } from "./SubmitForm.js";
  * details, or any JSON by its status. On success a toast says so and the values become the form's own; on failure the
  * server's own words show - every message it sent, on the inputs they name and the rest under the form, with our message
  * by status only for an answer that explains nothing - and the first input with a message takes focus. `loadValue` loads
- * the record to edit, with placeholders and Retry.
+ * the record to edit: the inputs show disabled until it lands, and a failure offers Retry.
  *
  * @example
  * const ROOMS = apiController(NexusModule.Reservation, "Room", "room");