@adecore/ui 0.38.0 → 0.40.0

package/src/IconPicker.tsx

@@ -16,35 +16,41 @@ export type { IconPickerGroup } from './icon-picker.ts';
 
 /* A row of cells is 28 high with a gap of 4. Under a heading of 28 the last row keeps 8 below it; without headings the grid has 6 above as well. */
 const ROW_HEIGHT = 32;
+
 const HEADED_EXTRA = 32;
 const BARE_EXTRA = 10;
 
 export interface IconPickerProps {
-    /* Every icon on offer by its name, in the order of the grid, or in groups under a heading each. The name is also its tooltip. */
+    /* By name, in the order of the grid, or in groups under a heading each. The name is also its tooltip. */
     icons: IconPickerIcons;
-    /* The name of the icon as it stands, or null for none. */
+
     value: string | null;
     onValueChange(name: string): void;
-    /* More words a search finds an icon by, beside its name and its group's label, by icon name. */
+
+    /* By icon name: more words a search finds it by, beside its name and its group's label. */
     keywords?: Readonly<Record<string, readonly string[]>>;
-    /* A search field on top of the grid. On by default for groups, off for a flat set. */
+
+    /* On by default for groups, off for a flat set. */
     searchable?: boolean;
-    /* The grid as a scroll area this many rows high, with room for a heading. Without it the grid is as tall as its icons. */
+
+    /* The grid as a scroll area this many rows high. Without it the grid is as tall as its icons. */
     rows?: number;
+
     disabled?: boolean;
-    /* Clearing the icon. A surface that falls back to a default of its own offers that instead. */
     onClear?: () => void;
-    /* The label above the trigger. A surface that also takes an image calls this something else, or the two read as one list. */
     label?: string;
-    /* Leaves the label out of sight, for a row that names the control beside it; it still names the trigger. */
+
+    /* It still names the trigger. */
     hideLabel?: boolean;
+
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
 
-/* A heading is stuck while its group runs past the top of the scroll area, and only then draws a line under it. */
+/* Only a stuck heading draws a line under it. */
 const markStuckHeadings = (area: HTMLElement): void => {
     const top = area.scrollTop;
+
     for (const heading of area.querySelectorAll<HTMLElement>('[data-icon-heading]')) {
         const group = heading.parentElement;
         const stuck = group !== null && top > 0 && group.offsetTop <= top && group.offsetTop + group.offsetHeight > top;
@@ -52,11 +58,7 @@ const markStuckHeadings = (area: HTMLElement): void => {
     }
 };
 
-/*
- * The mark a thing wears, one of a set of Lucide icons, behind a trigger drawn like a field. The
- * popover holds a search over the grid. The grid is one tab stop: arrows move the focus and only
- * Enter, Space or a click chooses, since a caller may save every choice at once.
- */
+/* The grid is one tab stop: arrows move the focus and only Enter, Space or a click chooses, since a caller may save every choice at once. */
 export function IconPicker({
     icons,
     value,
@@ -168,7 +170,7 @@ interface IconPickerPanelProps {
     onClear: (() => void) | undefined;
 }
 
-/* What the popover holds. It mounts on every open, so a search and the focus start over each time. */
+/* It mounts on every open, so a search and the focus start over each time. */
 function IconPickerPanel({ id, name, sections, headed, value, keywords, searchable, rows, disabled, onChoose, onClear }: IconPickerPanelProps) {
     const { t } = useTranslation('ui');
     const input = useRef<HTMLInputElement>(null);
@@ -176,6 +178,7 @@ function IconPickerPanel({ id, name, sections, headed, value, keywords, searchab
     const [query, setQuery] = useState('');
     const [focused, setFocused] = useState<string | null>(null);
     const shown = filterSections(sections, query, keywords);
+
     const tabStop = tabStopOf(
         shown.flatMap((section) => section.icons.map(([icon]) => icon)),
         focused,
@@ -186,15 +189,18 @@ function IconPickerPanel({ id, name, sections, headed, value, keywords, searchab
     useLayoutEffect(() => {
         const element = area.current;
         const chosen = element?.querySelector<HTMLElement>('[aria-checked="true"]');
+
         if (!element || !chosen || element.scrollHeight <= element.clientHeight) {
             return;
         }
+
         const heading = element.querySelector<HTMLElement>('[data-icon-heading]')?.offsetHeight ?? 0;
         element.scrollTop = Math.round(chosen.offsetTop - heading - (element.clientHeight - heading - chosen.offsetHeight) / 2);
     }, []);
 
     const search = (next: string): void => {
         setQuery(next);
+
         if (area.current) {
             area.current.scrollTop = 0;
         }
@@ -205,6 +211,7 @@ function IconPickerPanel({ id, name, sections, headed, value, keywords, searchab
         if (!escapeClearsSearch(event.key, query)) {
             return;
         }
+
         event.stopPropagation();
         event.preventDefault();
         search('');
@@ -215,19 +222,24 @@ function IconPickerPanel({ id, name, sections, headed, value, keywords, searchab
         if (event.metaKey || event.ctrlKey || event.altKey) {
             return;
         }
+
         const cells = [...event.currentTarget.querySelectorAll<HTMLElement>('[role="radio"]')];
         const from = cells.indexOf(event.target as HTMLElement);
+
         if (from === -1) {
             return;
         }
+
         const to = cellForKey(
             event.key,
             cells.map((cell) => cell.getBoundingClientRect()),
             from
         );
+
         if (to === null) {
             return;
         }
+
         event.preventDefault();
         cells[to]?.focus();
     };
@@ -305,10 +317,13 @@ function IconPickerPanel({ id, name, sections, headed, value, keywords, searchab
                                 ))}
                             </div>
                         );
+
                         if (section.label === null) {
                             return cells;
                         }
+
                         const headingId = `${id}-group-${index}`;
+
                         return (
                             <div key={section.id} role="group" aria-labelledby={headingId}>
                                 {/* A step lighter than the popover in the dark theme, where a darker band would read as a hole in it. */}

package/src/Input.tsx

@@ -5,17 +5,18 @@ import { fieldControlProps, useFieldControl } from './field-context.ts';
 import { Icon } from './Icon.tsx';
 
 export interface InputProps extends Omit<ComponentProps<'input'>, 'size'> {
-    /* `sm` is the height of a small button: a row of tools, or a name typed in place of the label it renames. */
+    /* `sm` is the height of a small button. */
     size?: 'md' | 'sm';
-    /* A branch, a path or anything else read back letter by letter. */
+
     mono?: boolean;
-    /* Drawn in front of the text, such as a magnifier on a search field. `className` then goes to the box around the icon and the input; `ref` stays on the input. */
+
+    /* `className` then goes to the box around the icon and the input; `ref` stays on the input. */
     icon?: LucideIcon;
-    /* Drawn after the text inside the field, such as a count of matches and an `IconButton` that clears it. `className` then goes to the box, as with `icon`. */
+
+    /* Inside the field, after the text. `className` then goes to the box, as with `icon`. */
     end?: ReactNode;
 }
 
-/* The one text input: one border and one focus ring at the one height or the compact one. */
 export function Input({ size = 'md', mono = false, icon, end, className, id, ...props }: InputProps) {
     const field = useFieldControl();
     const small = size === 'sm';
@@ -50,19 +51,20 @@ export function Input({ size = 'md', mono = false, icon, end, className, id, ...
 }
 
 export interface TextAreaProps extends ComponentProps<'textarea'> {
-    /* `sm` is the type and the padding of a small input: a commit message or a note in a narrow panel. */
+    /* `sm` is the type and the padding of a small input. */
     size?: 'md' | 'sm';
-    /* `vertical` gives it a handle to drag it taller, for a draft of a few sentences. */
+
     resize?: 'none' | 'vertical';
-    /* A command or anything else read back letter by letter. */
     mono?: boolean;
+
     /* `bare` drops the border, the ground and the focus outline, for a field inside a card that draws all three around it. */
     variant?: 'field' | 'bare';
 }
 
-/* A field of a few lines: a commit message, the body of a pull request, a note. At least 64px tall; `rows` makes it taller. */
+/* At least 64px tall; `rows` makes it taller. */
 export function TextArea({ size = 'md', resize = 'none', mono = false, variant = 'field', className, id, ...props }: TextAreaProps) {
     const field = useFieldControl();
+
     return (
         <textarea
             {...fieldControlProps(field, id)}

package/src/Kbd.tsx

@@ -6,7 +6,7 @@ import { formatShortcut, shortcutParts, type Shortcut } from './shortcut.ts';
 /* A shortcut chip on the surface it sits on: in a tooltip, in a palette's footer, in a line of help. */
 const INLINE_KBD = 'rounded-sm bg-surface-sunken px-[5px] py-px font-sans text-xs/[inherit] text-text-muted';
 
-/* One key, drawn as a cap. A settings page prints a shortcut key by key, so a gesture can stand beside it. */
+/* A settings page prints a shortcut key by key, so a gesture can stand beside it. */
 const KEY_CAP = 'inline-grid place-items-center rounded-md border border-b-2 border-border-strong bg-surface-hover bg-clip-padding font-sans text-text';
 
 /* `sm` fits inside a small field, as the hint of the key that focuses it. */
@@ -15,17 +15,16 @@ const KEY_CAP_SIZES = { md: 'h-6 min-w-6 px-1.5 text-xs', sm: 'h-5 min-w-5 px-1
 export interface KbdProps {
     /* Printed the way this platform writes it. Without one, the children are printed as they are (`↑`, `Esc`). */
     shortcut?: Shortcut;
+
     children?: ReactNode;
-    /*
-     * Where the shortcut is printed. In a menu row the `.menu-item kbd` rule dresses it, as the
-     * quiet hint at the end of the row; anywhere else it is a chip on the surface it sits on.
-     */
+
+    /* In a menu row the `.menu-item kbd` rule dresses it; anywhere else it is a chip on the surface it sits on. */
     variant?: 'menu' | 'inline';
+
     className?: string;
     ref?: Ref<HTMLElement>;
 }
 
-/* A shortcut as this platform prints it: `⌘K` on macOS, `Ctrl+K` elsewhere. */
 export function Kbd({ shortcut, children, variant = 'menu', className, ref }: KbdProps) {
     return (
         <kbd ref={ref} className={clsx(variant === 'inline' && INLINE_KBD, className)}>
@@ -51,16 +50,18 @@ export function KeyCap({ children, size = 'md', className, ref }: KeyCapProps) {
 
 export interface KeysProps {
     shortcut: Shortcut;
+
     /* The pointer gesture the keys go with, such as "drag", as one more cap. */
     then?: string;
+
     size?: 'md' | 'sm';
     className?: string;
     ref?: Ref<HTMLSpanElement>;
 }
 
-/* A shortcut as one cap per key, `⌘` and `K`, plus the pointer gesture it goes with. */
 export function Keys({ shortcut, then, size = 'md', className, ref }: KeysProps) {
     const parts = [...shortcutParts(shortcut, isApplePlatform()), ...(then ? [then] : [])];
+
     return (
         <span ref={ref} className={clsx('flex items-center', size === 'sm' ? 'gap-0.5' : 'gap-1', className)}>
             {parts.map((part, index) => (

package/src/LazyBoundary.tsx

@@ -7,13 +7,13 @@ export interface LazyBoundaryProps {
 }
 
 /*
- * `Suspense` for what `lazyNamed` loads. React holds content that comes in as a retry back until
- * 300 ms after its fallback showed; this boundary draws again as an ordinary update once a module
- * lands, so a chunk that takes 20 ms shows after 20 ms.
+ * React holds content that comes in as a retry back until 300 ms after its fallback showed; this
+ * boundary draws again as an ordinary update once a module lands, so a 20 ms chunk shows after 20 ms.
  */
 export function LazyBoundary({ fallback = null, children }: LazyBoundaryProps) {
     // Compiled, the same boundary would come back and the landing would wait for React's own retry after all.
     'use no memo';
     useSyncExternalStore(subscribeLandings, readLandings, readLandings);
+
     return <Suspense fallback={fallback}>{children}</Suspense>;
 }

package/src/Meter.tsx

@@ -4,19 +4,24 @@ import clsx from 'clsx';
 export interface MeterProps {
     /* In the unit of `min` and `max`, held to them. Null draws an empty track, for a level not measured yet. */
     value: number | null;
+
     min?: number;
     max?: number;
-    /* Values drawn as lines across the track, such as a target or a limit. */
+
+    /* Drawn as lines across the track, such as a target or a limit. */
     marks?: readonly number[];
+
     label: string;
+
     /* The value in words for a screen reader, such as "-18.2 LUFS". Left out, it reads the number. */
     valueText?: string;
+
     /* Its width, which it fills. */
     className?: string;
+
     ref?: Ref<HTMLDivElement>;
 }
 
-/* A level against a scale: how full it is, and where a target or a limit sits on the same scale. */
 export function Meter({ value, min = 0, max = 100, marks = [], label, valueText, className, ref }: MeterProps) {
     const fractionOf = (level: number): number => (max > min ? Math.min(1, Math.max(0, (level - min) / (max - min))) : 0);
 

package/src/MiddleTruncate.tsx

@@ -6,27 +6,33 @@ import { Tooltip } from './Tooltip.tsx';
 
 export interface MiddleTruncateProps {
     text: string;
+
     /* The whole text on hover and focus while it is cut. Off where the caller's own tooltip already says it. */
     tooltip?: boolean;
+
     className?: string;
     ref?: Ref<HTMLSpanElement>;
 }
 
 let canvas: HTMLCanvasElement | null = null;
 
-/* How wide a text is drawn in the face of `element`, or null where the page cannot tell (no canvas). */
+/* Null where the page has no canvas. */
 function textMeasure(element: HTMLElement): ((text: string) => number) | null {
     const view = element.ownerDocument.defaultView;
     canvas ??= element.ownerDocument.createElement('canvas');
     const context = canvas.getContext('2d');
+
     if (context === null || view === null) {
         return null;
     }
+
     const style = view.getComputedStyle(element);
     context.font = style.font || `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+
     if ('letterSpacing' in context) {
         context.letterSpacing = style.letterSpacing === 'normal' ? '0px' : style.letterSpacing;
     }
+
     return (text) => context.measureText(text).width;
 }
 
@@ -34,11 +40,7 @@ function sameCut(first: MiddleCut | null, second: MiddleCut | null): boolean {
     return first?.head === second?.head && first?.tail === second?.tail;
 }
 
-/*
- * A path or a branch name on one line that keeps its start and its end and cuts the middle. It asks
- * for the width of the whole text and measures what it gets. The part it cuts stays in the element
- * at no width, so selecting, copying and finding read the whole text.
- */
+/* The part it cuts stays in the element at no width, so selecting, copying and finding read the whole text. */
 export function MiddleTruncate({ text, tooltip = true, className, ref }: MiddleTruncateProps) {
     const [element, setElement] = useState<HTMLSpanElement | null>(null);
     const [cut, setCut] = useState<MiddleCut | null>(null);
@@ -48,18 +50,23 @@ export function MiddleTruncate({ text, tooltip = true, className, ref }: MiddleT
         if (element === null) {
             return;
         }
+
         const update = (): void => {
             const measure = textMeasure(element);
             // Layout rounds what a canvas measures, so a text a fraction wider than its box still fits.
             const next = measure === null ? null : fitMiddle(text, element.getBoundingClientRect().width + 0.5, measure);
             setCut((current) => (sameCut(current, next) ? current : next));
         };
+
         update();
+
         if (typeof ResizeObserver === 'undefined') {
             return;
         }
+
         const observer = new ResizeObserver(update);
         observer.observe(element);
+
         return () => observer.disconnect();
     }, [element, text]);
 
@@ -76,9 +83,11 @@ export function MiddleTruncate({ text, tooltip = true, className, ref }: MiddleT
             )}
         </span>
     );
+
     // Only a cut text has more to say, and a long list of whole ones keeps no hover handlers.
     if (cut === null || !tooltip) {
         return content;
     }
+
     return <Tooltip label={text}>{content}</Tooltip>;
 }

package/src/PanelEmpty.tsx

@@ -6,23 +6,25 @@ import { EmptyState } from './EmptyState.tsx';
 export interface PanelEmptyProps {
     /* The panel's own header, kept above the sentence so a person can still act while nothing is listed. */
     header?: ReactNode;
+
     icon?: LucideIcon;
-    /* A `Spinner` in place of the icon, for a panel that is still loading. */
+
+    /* A `Spinner` in place of the icon. */
     busy?: boolean;
+
     action?: ReactNode;
-    /* The sunken ground, for a box that has none behind it yet (a card on a canvas) rather than a panel that does. */
+
+    /* For a box that has no ground behind it yet, such as a card on a canvas. */
     sunken?: boolean;
-    /*
-     * A panel is one track of a flex column and takes what is left of it; a card is a box with a
-     * height of its own, and `grow` means nothing to the block that lays it out.
-     */
+
+    /* A panel is one track of a flex column; a card is a box with a height of its own, where `grow` means nothing. */
     fill?: 'grow' | 'full';
+
     children: ReactNode;
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
 
-/* What a panel or a card shows while it holds nothing: a sentence, one icon, at most one button. */
 export function PanelEmpty({ header, icon, busy = false, action, sunken = false, fill = 'grow', children, className, ref }: PanelEmptyProps) {
     return (
         <div ref={ref} className={clsx('grid min-h-0 place-items-center', fill === 'full' ? 'h-full' : 'grow', sunken && 'bg-surface-sunken', className)}>

package/src/PanelHeader.tsx

@@ -4,14 +4,11 @@ import { useRender } from '@base-ui/react/use-render';
 import { SectionLabel } from './SectionLabel.tsx';
 
 export type PanelHeaderProps = useRender.ComponentProps<'header'> & {
-    /* The panel's name, as a section label first on the bar. Left out when the caller lays out the name itself. */
+    /* Left out when the caller lays out the name itself. */
     title?: ReactNode;
 };
 
-/*
- * The bar across the top of a side panel, as tall as a 48px toolbar beside it: the panel's name,
- * its own controls, and a close button last.
- */
+/* As tall as a 48px toolbar beside it. */
 export function PanelHeader({ title, render, className, ref, children, ...props }: PanelHeaderProps) {
     return useRender({
         render,

package/src/Pill.tsx

@@ -1,11 +1,7 @@
 import type { ReactNode, Ref } from 'react';
 import clsx from 'clsx';
 
-/*
- * What the label says about the thing it names, drawn as its ground. Every ground is an alpha over
- * whatever the pill stands on, the way a border is: in the dark theme it lifts a shade off the row
- * under it, in the light theme it sinks one. A solid sunken ground read as a hole on a dark row.
- */
+/* Every ground is an alpha over whatever the pill stands on, the way a border is: a solid sunken ground read as a hole on a dark row. */
 const TONES = {
     muted: 'bg-text/7 text-text-muted',
     /* A step further off the ground, for a label that should stand out as a control. */
@@ -34,18 +30,19 @@ export interface PillProps {
     tone?: keyof typeof TONES;
     shape?: keyof typeof SHAPES;
     size?: 'md' | 'sm';
-    /* A branch name or a count reads better in the monospace face. */
     mono?: boolean;
+
     /* With a handler the pill is a button; without one it is a label. */
     onClick?: () => void;
-    /* Makes the button a toggle, for a switch of what a surface shows. */
+
+    /* Makes the button a toggle. */
     pressed?: boolean;
+
     disabled?: boolean;
     className?: string;
     ref?: Ref<HTMLElement>;
 }
 
-/* The small rounded label in a header, a sidebar row or a settings line: a count, a branch, a status. */
 export function Pill({ icon, children, tone = 'muted', shape = 'pill', size = 'md', mono = false, onClick, pressed, disabled, className, ref }: PillProps) {
     // Never broken inside itself: in a row that wraps, a pill that does not fit moves to the next line whole.
     const shared = clsx(
@@ -56,6 +53,7 @@ export function Pill({ icon, children, tone = 'muted', shape = 'pill', size = 'm
         mono && 'font-mono',
         className
     );
+
     if (!onClick) {
         return (
             <span ref={ref} className={shared}>
@@ -64,6 +62,7 @@ export function Pill({ icon, children, tone = 'muted', shape = 'pill', size = 'm
             </span>
         );
     }
+
     return (
         <button
             ref={ref as Ref<HTMLButtonElement>}

package/src/ProjectSwitcher.tsx

@@ -10,14 +10,19 @@ export interface ProjectSwitcherItem {
     id: string;
     name: string;
     icon?: ReactNode;
+
     /* The folder or other details, shown in a tooltip so the row stays on one line. */
     description?: ReactNode;
-    /* A machine or workspace name at the end of the row. */
+
+    /* At the end of the row. */
     hint?: ReactNode;
+
     disabled?: boolean;
+
     /* A stale or disconnected project can still be selected to try opening it. */
     muted?: boolean;
-    /* Menu items for the submenu beside this project's row. */
+
+    /* For the submenu beside this project's row. */
     actions?: ReactNode;
 }
 
@@ -26,14 +31,19 @@ export interface ProjectSwitcherProps<Item extends ProjectSwitcherItem = Project
     projects: readonly Item[];
     recentProjects?: readonly Item[];
     onSelect(project: Item, event: MouseEvent<HTMLElement>): void;
-    /* Before the current project's icon, such as the machine it runs on. */
+
+    /* Before the current project's icon. */
     leading?: ReactNode;
-    /* Menu items in a group of their own between the open projects and Recent projects. */
+
+    /* A group of their own between the open projects and Recent projects. */
     before?: ReactNode;
-    /* Menu items in one group with Recent projects, such as opening a folder or creating a project. */
+
+    /* In one group with Recent projects. */
     children?: ReactNode;
+
     /* What the trigger reads while `current` is null; next to a current project, it comes before that name in the accessible name. */
     label?: string;
+
     disabled?: boolean;
     open?: boolean;
     defaultOpen?: boolean;
@@ -83,7 +93,7 @@ export function ProjectSwitcher<Item extends ProjectSwitcherItem>({
     );
 }
 
-/* The rows of the popup, apart from it so they render without an open menu. */
+/* Apart from the popup, so the rows render without an open menu. */
 export function ProjectSwitcherGroups<Item extends ProjectSwitcherItem>({
     projects,
     recentProjects = [],

package/src/PromptDialog.tsx

@@ -11,56 +11,59 @@ import { useAsyncAction } from './useAsyncAction.ts';
 export interface PromptDialogProps {
     open: boolean;
     title: string;
-    /* The mark beside the title, for a dialog that names the thing it is about. */
     titleIcon?: LucideIcon;
     description?: ReactNode;
-    /* A one line field the answer is typed in; without it the dialog is a confirm and nothing else. */
+
+    /* Without it the dialog is a confirm and nothing else. */
     field?: {
-        /* Drawn above the field. Without one only a screen reader hears the name, from `ariaLabel`. */
+        /* Without one only a screen reader hears the name, from `ariaLabel`. */
         label?: string;
+
         ariaLabel?: string;
         initial?: string;
         placeholder?: string;
-        /* A branch, a path or anything else read back letter by letter. */
         mono?: boolean;
         maxLength?: number;
     };
-    /* A second, taller field under it, for the body of a pull request. */
+
+    /* A second, taller field under it. */
     area?: { label: string; initial?: string; placeholder?: string };
+
     confirmLabel: string;
-    /* What the button says while the step runs, for one slow enough that a quiet button is not enough. */
     confirmBusyLabel?: string;
     confirmIcon?: LucideIcon;
     danger?: boolean;
-    /* The caller runs the step somewhere else and says when it is busy; a step this dialog awaits says so itself. */
+
+    /* For a step the caller runs elsewhere; a step this dialog awaits says so itself. */
     busy?: boolean;
-    /* Lets the field be confirmed empty, for a list that may be cleared or a name with a default. */
+
     allowEmpty?: boolean;
+
     /* A reason this question cannot be answered at all, beside the one an empty field is. */
     confirmDisabled?: boolean;
-    /* A second way out next to the confirm, such as merging before removing. */
+
     secondary?: { label: string; onClick(): void };
-    /* Over another dialog, so what is under it is dimmed a second time. */
     nested?: boolean;
-    /* Whatever this question needs beyond a field, between the description and the buttons. */
+
+    /* Between the description and the buttons. */
     children?: ReactNode;
-    /* Told what was typed. A rejection stays on screen as the reason and leaves the dialog open. */
+
+    /* A rejection stays on screen as the reason and leaves the dialog open. */
     onConfirm(value: string, body: string): void | Promise<unknown>;
-    /* What the failure line reads when the rejection carries no sentence of its own. */
+
+    /* For a rejection that carries no sentence of its own. */
     fallbackMessage?: string;
-    /* Only ever told `false`: Cancel, Escape or a click outside. The dialog never closes itself. */
+
+    /* Only ever told `false`: the dialog never closes itself. */
     onOpenChange(open: boolean): void;
-    /* Extra on the popup. */
+
+    /* On the popup. */
     className?: string;
+
     ref?: Ref<HTMLDivElement>;
 }
 
-/*
- * The one dialog a question is asked in: a name to type, or a warning to agree with. Every confirm
- * and every rename shares it, so none of them grows a layout of its own. It never closes itself,
- * because what a confirm leads to is the caller's business: an action that asks a second question
- * would be shut out by a close of its own.
- */
+/* It never closes itself: an action that asks a second question would be shut out by a close of its own. */
 export function PromptDialog({
     open,
     title,
@@ -85,20 +88,21 @@ export function PromptDialog({
     ref
 }: PromptDialogProps) {
     const { t } = useTranslation('ui');
-    /* The dialog stays mounted between questions, so every opening starts from what it was handed.
-       The token is what it was handed, so a new question resets the fields in the same render that
-       shows it and not in a second one after. */
+    /* The dialog stays mounted between questions; a new question resets the fields in the render that shows it. */
     const token = open ? `${field?.initial ?? ''}\u0000${area?.initial ?? ''}` : '';
     const [draft, setDraft] = useState({ token, value: field?.initial ?? '', body: area?.initial ?? '' });
     const step = useAsyncAction(fallbackMessage);
+
     if (draft.token !== token) {
         setDraft({ token, value: field?.initial ?? '', body: area?.initial ?? '' });
         step.clear();
     }
-    const value = draft.value;
-    const body = draft.body;
+
+    const { value, body } = draft;
     const working = busy || step.busy;
+
     const setValue = (next: string): void => setDraft({ ...draft, value: next });
+
     const setBody = (next: string): void => setDraft({ ...draft, body: next });
 
     const submit = (): void => {
@@ -131,6 +135,7 @@ export function PromptDialog({
                             onKeyDown={(event) => {
                                 // Whatever listens on the window has keys of its own, and a name may hold any of them.
                                 event.stopPropagation();
+
                                 if (event.key === 'Enter') {
                                     event.preventDefault();
                                     submit();