A local-first multi-agent app development platform, built on PenguinHarness
/**
* Option menu (controlled): the trigger button shows a compact current value, and clicking it
* expands a panel where each row has a title + description text + a selected-state checkmark.
* Replaces select controls that show only an abbreviation and rely on a hover tooltip for the
* details (tooltips are poorly discoverable — users have no idea they should hover before they've
* clicked once).
*
* The trigger button shares the sizeClass size tier with Input/Select, and the panel row styling
* matches the Select menu (py-1.5, the current row filled and checked), keeping visuals
* consistent when mixed with existing form controls.
*
* The panel is mounted via createPortal to document.body and positioned with `position: fixed`
* against viewport coordinates — it does not reuse a dropdown's in-place absolute positioning.
* Reason: an in-place panel is a DOM descendant of its trigger button, so if an ancestor in the
* chain has a container like overflow-x-auto (e.g. this component used inside a tool table), the
* CSS spec says that when one axis has non-visible overflow and the other is visible, the visible
* axis gets forced to `auto` — making that ancestor clip vertically overflowing descendants, and
* absolute positioning is not exempt. A portaled node is outside that ancestor's DOM subtree, so
* it is fundamentally unaffected by its overflow, without having to audit every call site's
* ancestor chain. Positioning and close behaviour live in use-portal-panel.ts.
*
* The panel uses z-[60] (above the modal overlay's z-50): a portaled node sits in the root
* stacking context, and this component may also be used inside a Modal form, where z-40 would
* get covered by the overlay.
*/
import { useId, useState } from "react";
import { createPortal } from "react-dom";
import { ChevronDown } from "../../icons/marks/marks";
import {
ChoiceCheck,
menuPanelClass,
menuRowClass,
menuRowTone,
} from "../../overlays/menu-panel/menu-panel";
import { usePortalPanel } from "../../overlays/portal-panel/use-portal-panel";
import { Field, controlBase } from "../field/field";
import { errorClass, sizeClass, sizeTextClass } from "../input/input";
import type { ControlSize } from "../input/input";
export interface OptionMenuChoice<T extends string> {
value: T;
/** Compact text on the trigger button (e.g. "rw"). */
triggerLabel: string;
/** Panel row title (e.g. "Read & write"). */
label: string;
/** Panel row description text explaining when this option actually takes effect. */
description: string;
}
const PANEL_WIDTH = 288; // w-72
/**
* A row description's font size per tier. Descriptions sit on the small rung: at the base tier
* that is a step below the row title; at the sm tier the title is already on the small rung and
* there is no rung below it, so the two share a size and the description stands apart by its
* muted ink alone (a fixed `text-[Npx]` would ignore the user's font-size setting). The Menu
* rows' description sits on the same small rung.
*/
export const rowDescClass: Record<ControlSize, string> = { base: "text-xs", sm: "text-xs" };
export function OptionMenu<T extends string>({
options,
value,
onChange,
placeholder,
mono,
label,
error,
required,
fullWidth,
size = "sm",
"aria-label": ariaLabel,
}: {
options: ReadonlyArray<OptionMenuChoice<T>>;
/** null/undefined means unset/default: the trigger shows the placeholder and no panel row is selected. */
value: T | null | undefined;
onChange: (value: T) => void;
/** Placeholder text on the trigger when value is empty. */
placeholder?: string;
/** Use a monospace font for the trigger text. */
mono?: boolean;
/** Field title above the control (same typography as Input); omit to render a bare trigger button (e.g. for table cell usage). */
label?: string;
/** Field-value error: the error border + message below, exactly like Input. */
error?: string;
/** Renders the required mark after the label. An optional field passes nothing — no counterpart mark, and no "optional" in the label. */
required?: boolean;
/** Stretch the trigger button to fill the container width, as a replacement for native Select in dense form areas. */
fullWidth?: boolean;
/** Same size tier as Input/Select (sizeClass), for pixel-perfect alignment when mixed together. */
size?: ControlSize;
"aria-label"?: string;
}) {
const [open, setOpen] = useState(false);
const { triggerRef, panelRef, position } = usePortalPanel({
open,
onClose: () => setOpen(false),
// Row height is roughly 48px (title + description two lines + py-1.5) + panel top/bottom padding.
estimatedHeight: options.length * 48 + 16,
panelWidth: PANEL_WIDTH,
});
const current = value != null ? options.find((o) => o.value === value) : undefined;
const errorId = useId();
const control = (
<>
<button
ref={triggerRef}
type="button"
aria-label={ariaLabel}
aria-haspopup="listbox"
aria-expanded={open}
aria-required={required || undefined}
aria-invalid={error ? true : undefined}
aria-describedby={error ? errorId : undefined}
onClick={() => setOpen((v) => !v)}
className={
`flex items-center gap-2 ${controlBase} ${sizeClass[size]} ${error ? errorClass : ""}` +
(fullWidth ? " w-full justify-between" : "")
}
>
<span className={`min-w-0 truncate ${mono ? "font-mono" : ""}`}>
{current?.triggerLabel ?? placeholder ?? "—"}
</span>
<ChevronDown className="text-fg-subtle" />
</button>
{open &&
position &&
createPortal(
<div
ref={panelRef}
role="listbox"
style={{
position: "fixed",
top: position.topPx,
bottom: position.bottomPx,
left: position.left,
minWidth: position.triggerWidth,
}}
className={`ui-glass ${menuPanelClass} z-[60] max-h-[70vh] w-72 max-w-[calc(100vw-2rem)]`}
>
{options.map((opt) => (
<button
key={opt.value}
type="button"
role="option"
aria-selected={opt.value === value}
onClick={() => {
onChange(opt.value);
setOpen(false);
}}
className={`block ${menuRowClass} ${menuRowTone(opt.value === value)}`}
>
<span className="flex items-center justify-between gap-2">
{/* Row title takes the control's own tier, so the menu reads exactly like
an Input of that tier. */}
<span className={sizeTextClass[size]}>{opt.label}</span>
<ChoiceCheck on={opt.value === value} />
</span>
<span className={`mt-0.5 block ${rowDescClass[size]} text-fg-muted`}>
{opt.description}
</span>
</button>
))}
</div>,
document.body,
)}
</>
);
return (
<Field label={label} error={error} errorId={errorId} required={required}>
{control}
</Field>
);
}