(null);
const enabled = React.useMemo(() => options.filter((o) => !o.disabled), [options]);
const active = raw !== null && enabled.some((o) => o.value === raw) ? raw : autoActivateFirst ? (enabled[0]?.value ?? null) : null;
const buffer = React.useRef({ text: "", at: 0 });
const step = (delta: number) => {
if (!enabled.length) return null;
const i = enabled.findIndex((o) => o.value === active);
const next = i === -1 ? (delta > 0 ? enabled[0] : enabled[enabled.length - 1]) : enabled[Math.max(0, Math.min(enabled.length - 1, i + delta))];
setActive(next.value);
return next.value;
};
const edge = (where: "first" | "last") => {
const next = where === "first" ? enabled[0] : enabled[enabled.length - 1];
setActive(next?.value ?? null);
return next?.value ?? null;
};
const typeahead = (char: string, timeStamp: number) => {
const b = buffer.current;
b.text = timeStamp - b.at > 600 ? char : b.text + char;
b.at = timeStamp;
const q = fold(b.text);
const start = enabled.findIndex((o) => o.value === active);
const from = q.length > 1 ? Math.max(0, start) : start + 1;
const ordered = [...enabled.slice(from), ...enabled.slice(0, from)];
let match = ordered.find((o) => fold(o.label).startsWith(q));
if (!match && Array.from(q).every((c) => c === q[0])) match = ordered.find((o) => fold(o.label).startsWith(q[0]));
if (match) setActive(match.value);
return match?.value ?? null;
};
return { active, setActive, step, edge, typeahead, enabled };
}
/** True for a key that types one visible character (no modifiers). */
export function isPrintableKey(e: React.KeyboardEvent) {
return e.key.length === 1 && e.key !== " " && !e.ctrlKey && !e.metaKey && !e.altKey;
}
/* ------------------------------------------------------------------ */
/* Option list */
/* ------------------------------------------------------------------ */
export interface ListboxProps {
id: string;
entries: readonly ListboxEntry[];
selected: readonly string[];
active: string | null;
onActiveChange: (value: string) => void;
onPick: (option: ListboxOption) => void;
multiple?: boolean;
/** Selection mark: a drawn check on the right, a checkbox on the left, or none. */
indicator?: "check" | "checkbox" | "none";
size?: ListboxSize;
/** Highlight this text inside labels. */
query?: string;
"aria-label"?: string;
"aria-labelledby"?: string;
/** Rendered (outside the listbox role) when there are no options: empty or loading state. */
empty?: React.ReactNode;
busy?: boolean;
maxHeight?: number;
className?: string;
}
/** Option list with group headings, separators, media slots and one volt highlight that glides between rows. */
export function Listbox({
id,
entries,
selected,
active,
onActiveChange,
onPick,
multiple,
indicator = "check",
size = "md",
query,
empty,
busy,
maxHeight,
className,
...aria
}: ListboxProps) {
const reduce = useReducedMotion();
const picked = React.useMemo(() => new Set(selected), [selected]);
const hasOptions = flattenEntries(entries).length > 0;
// Keep the active row in view (keyboard moves, filtering, first open).
React.useEffect(() => {
if (active) document.getElementById(optionId(id, active))?.scrollIntoView({ block: "nearest" });
}, [id, active]);
const renderOption = (o: ListboxOption) => {
const isSelected = picked.has(o.value);
const isActive = active === o.value;
return (
{
if (!o.disabled && !isActive) onActiveChange(o.value);
}}
onMouseDown={(e) => e.preventDefault()}
onClick={() => {
if (!o.disabled) onPick(o);
}}
className={cn(
"relative flex cursor-pointer select-none items-center text-ink-muted transition-colors duration-100",
listboxRowSize[size],
isActive && "text-ink",
isSelected && "text-ink",
o.disabled && "cursor-not-allowed opacity-45",
)}
>
{isActive && (
)}
{indicator === "checkbox" && (
)}
{o.description && {o.description}}
{o.meta && {o.meta}}
{o.shortcut && {o.shortcut}}
{indicator === "check" && (
{isSelected && }
)}
);
};
let blocks = 0;
return (
<>
{entries.map((e, i) => {
if (isListboxSeparator(e)) return ;
const first = blocks++ === 0;
if (!isListboxGroup(e)) return renderOption(e);
const headingId = `${id}-g${i}`;
const prev = entries[i - 1];
return (
{e.heading && (
{e.heading}
)}
{e.options.map(renderOption)}