AI media harness for planning, generating, and editing locally
TypeScript
/* ComboBox — the WinUI drop-down, a drop-in for <select>.
A 32px trigger styled as a standard button with a chevron. It opens an
acrylic listbox flyout (8px corners, 4px padding, 32px items, a 3×16px
accent pill beside the selected item) positioned so the selected item sits
right over the trigger when there is room, else below or above.
Focus never leaves the trigger: it is the ARIA 1.2 select-only combobox, so
the list is driven with aria-activedescendant and Tab simply moves on.
Keyboard, closed: Alt+Down / F4 / Enter / Space open; Up / Down / Home / End
and typing change the value directly, like a native select.
Keyboard, open: arrows / Home / End / PageUp / PageDown / typing move,
Enter or Space picks, Esc or Alt+Up closes, Tab picks-nothing and moves on.
Migrating from <select> is mechanical — keep the <option> children:
<select value={v} onChange={(e) => setV(e.target.value)}>…options…</select>
<ComboBox value={v} onChange={setV}>…same options…</ComboBox>
or pass data:
<ComboBox aria-label="Generator" value={id} onChange={setId}
options={[{ value: "a", label: "Alpha" }, { label: "More", options: [...] }]} />
Editable mode (`editable`) is the WinUI IsEditable ComboBox: a text field
with the drop-down button at its end. The list works as above; typed text
is committed on Enter or when focus leaves, through `parseText`, which
returns the value the text means or null to refuse it (the field then goes
back to `displayText`). Esc drops what was typed. Focus stays in the field:
<ComboBox editable aria-label="Zoom" value={preset} displayText="137%"
parseText={(text) => parsePercent(text)} options={presets} onChange={zoomTo} />
*/
import { ChevronDown12 } from "./icons";
import {
Children, Fragment, isValidElement, useId, useLayoutEffect, useMemo, useRef, useState,
type CSSProperties, type KeyboardEvent, type ReactElement, type ReactNode,
} from "react";
import { createPortal } from "react-dom";
import {
LAYER_ATTR, VIEWPORT_MARGIN, createTypeahead, cx, isPrintableKey, placeAnchored, textOf, useLightDismiss, viewport,
} from "./internal";
export type ComboValue = string | number;
export interface ComboOption<V extends ComboValue = string> {
value: V;
label: ReactNode;
disabled?: boolean;
/** A second, caption-sized line under the label (in the list only). */
description?: ReactNode;
/** 16px leading icon (list and trigger). */
icon?: ReactNode;
/** Plain text for typeahead / accessibility when `label` is not a string. */
textValue?: string;
}
export interface ComboGroup<V extends ComboValue = string> {
label: string;
options: ComboOption<V>[];
}
export type ComboItems<V extends ComboValue = string> = (ComboOption<V> | ComboGroup<V>)[];
export interface ComboBoxProps<V extends ComboValue = string> {
value: V | null | undefined;
onChange: (value: V) => void;
/** Data form. When omitted, <option>/<optgroup> children are read instead. */
options?: ComboItems<V>;
children?: ReactNode;
id?: string;
name?: string;
"aria-label"?: string;
"aria-labelledby"?: string;
"aria-describedby"?: string;
"data-tooltip"?: string;
disabled?: boolean;
/** Shown when no option matches `value`. */
placeholder?: ReactNode;
className?: string;
/** CSS width of the trigger (number = px). Default: sized by the stylesheet (min 120px). */
width?: number | string;
onBlur?: () => void;
onFocus?: () => void;
/** A text field with a drop-down button instead of a select-only button. */
editable?: boolean;
/** Editable mode: the value typed text stands for, or null to reject it.
* Default: the option whose label or value matches, ignoring case. */
parseText?: (text: string) => V | null;
/** Override the selected text without changing the option labels.
* In editable mode, shown while nothing is being typed. */
displayText?: string;
}
const isGroup = <V extends ComboValue>(item: ComboOption<V> | ComboGroup<V>): item is ComboGroup<V> =>
"options" in item && Array.isArray((item as ComboGroup<V>).options);
/** Read <option>/<optgroup> React children into ComboBox items. Values stay strings, like a select's. */
export function optionsFromChildren(children: ReactNode): ComboItems<string> {
const items: ComboItems<string> = [];
const readOption = (element: ReactElement<{ value?: unknown; children?: ReactNode; disabled?: boolean; label?: string }>): ComboOption<string> => {
const { value, children: label, disabled } = element.props;
const text = textOf(label);
return { value: value === undefined ? text : String(value), label: label ?? element.props.label ?? "", disabled: Boolean(disabled), textValue: text };
};
Children.forEach(children, (child) => {
if (!isValidElement(child)) return;
if (child.type === "option") items.push(readOption(child as ReactElement<{ value?: unknown; children?: ReactNode }>));
else if (child.type === "optgroup") {
const props = child.props as { label?: string; children?: ReactNode };
const options: ComboOption<string>[] = [];
Children.forEach(props.children, (inner) => {
if (isValidElement(inner) && inner.type === "option") options.push(readOption(inner as ReactElement<{ value?: unknown; children?: ReactNode }>));
});
items.push({ label: props.label ?? "", options });
} else if (child.type === Fragment) {
// Fragments of options (e.g. {list.map(...)} inside <>…</>).
items.push(...optionsFromChildren((child.props as { children?: ReactNode }).children));
}
});
return items;
}
interface FlatOption<V extends ComboValue> extends ComboOption<V> { group?: string; firstInGroup?: boolean; text: string }
function flatten<V extends ComboValue>(items: ComboItems<V>): FlatOption<V>[] {
const flat: FlatOption<V>[] = [];
for (const item of items) {
if (isGroup(item)) item.options.forEach((option, index) => flat.push({ ...option, group: item.label, firstInGroup: index === 0, text: option.textValue ?? textOf(option.label) }));
else flat.push({ ...item, text: item.textValue ?? textOf(item.label) });
}
return flat;
}
const ITEM_HEIGHT = 32;
export function ComboBox<V extends ComboValue = string>(props: ComboBoxProps<V>) {
return props.editable ? <EditableComboBox {...props} /> : <SelectComboBox {...props} />;
}
function SelectComboBox<V extends ComboValue = string>(props: ComboBoxProps<V>) {
const {
value, onChange, options, children, id, name, disabled, placeholder, className, width, onBlur, onFocus,
} = props;
const items = useMemo(() => (options ?? (optionsFromChildren(children) as unknown as ComboItems<V>)), [options, children]);
const flat = useMemo(() => flatten(items), [items]);
const selectedIndex = flat.findIndex((option) => option.value === value || String(option.value) === String(value ?? "\u0000"));
const selected = selectedIndex >= 0 ? flat[selectedIndex] : undefined;
const [open, setOpen] = useState(false);
const [active, setActive] = useState(-1);
const [position, setPosition] = useState<CSSProperties>({ visibility: "hidden" });
const trigger = useRef<HTMLButtonElement>(null);
const list = useRef<HTMLDivElement>(null);
const typeahead = useRef(createTypeahead());
const autoId = useId();
const listId = `${autoId}-list`;
const optionId = (index: number) => `${autoId}-opt-${index}`;
const enabledIndexes = flat.map((option, index) => (option.disabled ? -1 : index)).filter((index) => index >= 0);
const commit = (index: number) => {
const option = flat[index];
if (!option || option.disabled) return;
if (option.value !== value) onChange(option.value);
};
const openList = () => {
if (disabled || !flat.length) return;
setActive(selectedIndex >= 0 && !flat[selectedIndex].disabled ? selectedIndex : enabledIndexes[0] ?? -1);
setPosition({ visibility: "hidden" });
setOpen(true);
};
const close = (focusTrigger = true) => {
setOpen(false);
if (focusTrigger) trigger.current?.focus({ preventScroll: true });
};
useLightDismiss(list, open, (reason) => close(reason === "escape"), { ignore: [trigger] });
/* Place the list: selected item over the trigger, else below, else above. */
useLayoutEffect(() => {
if (!open || !list.current || !trigger.current) return;
const anchor = trigger.current.getBoundingClientRect();
const view = viewport();
const listRect = list.current.getBoundingClientRect();
const height = listRect.height || flat.length * ITEM_HEIGHT + 8;
const width = Math.max(anchor.width, listRect.width);
const item = active >= 0 ? document.getElementById(optionId(selectedIndex >= 0 ? selectedIndex : active)) : null;
let top: number;
let left = anchor.left;
const overTop = item ? anchor.top + anchor.height / 2 - (item.offsetTop - list.current.scrollTop + item.offsetHeight / 2) : NaN;
if (item && overTop >= VIEWPORT_MARGIN && overTop + height <= view.height - VIEWPORT_MARGIN) {
top = overTop;
} else {
const placed = placeAnchored(anchor, { width, height }, "bottom", 4, view);
top = placed.top;
left = placed.left;
}
left = Math.max(VIEWPORT_MARGIN, Math.min(left, view.width - width - VIEWPORT_MARGIN));
setPosition({ top, left, minWidth: anchor.width });
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [open]);
/* Keep the active option in view. */
useLayoutEffect(() => {
if (!open || active < 0) return;
const element = document.getElementById(optionId(active));
element?.scrollIntoView?.({ block: "nearest" });
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [open, active]);
const step = (from: number, delta: number) => {
if (!enabledIndexes.length) return -1;
const at = enabledIndexes.indexOf(from);
if (at < 0) return delta > 0 ? enabledIndexes[0] : enabledIndexes[enabledIndexes.length - 1];
return enabledIndexes[Math.max(0, Math.min(enabledIndexes.length - 1, at + delta))];
};
const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
if (disabled) return;
const { key, altKey } = event;
if (!open) {
if ((altKey && key === "ArrowDown") || key === "F4" || key === "Enter" || key === " ") {
event.preventDefault();
openList();
return;
}
let next = -1;
if (key === "ArrowDown" || key === "ArrowRight") next = step(selectedIndex, 1);
else if (key === "ArrowUp" || key === "ArrowLeft") next = step(selectedIndex, -1);
else if (key === "Home") next = enabledIndexes[0] ?? -1;
else if (key === "End") next = enabledIndexes.at(-1) ?? -1;
else if (isPrintableKey(event)) next = typeahead.current(key, flat.map((option) => (option.disabled ? "" : option.text)), selectedIndex);
else return;
event.preventDefault();
if (next >= 0) commit(next);
return;
}
// Open.
if (key === "Escape" || (altKey && key === "ArrowUp") || key === "F4") {
event.preventDefault();
event.stopPropagation();
close();
return;
}
if (key === "Enter" || key === " ") {
event.preventDefault();
event.stopPropagation();
if (active >= 0) commit(active);
close();
return;
}
if (key === "Tab") { close(false); return; }
const page = Math.max(1, Math.floor((list.current?.clientHeight ?? 320) / ITEM_HEIGHT) - 1);
let next = active;
if (key === "ArrowDown") next = step(active, 1);
else if (key === "ArrowUp") next = step(active, -1);
else if (key === "Home") next = enabledIndexes[0] ?? -1;
else if (key === "End") next = enabledIndexes.at(-1) ?? -1;
else if (key === "PageDown") next = step(active, page);
else if (key === "PageUp") next = step(active, -page);
else if (isPrintableKey(event)) {
const found = typeahead.current(key, flat.map((option) => (option.disabled ? "" : option.text)), active);
if (found >= 0) next = found;
} else return;
event.preventDefault();
setActive(next);
};
const style: CSSProperties | undefined = width !== undefined ? { width: typeof width === "number" ? `${width}px` : width } : undefined;
return (
<>
<button
ref={trigger}
type="button"
id={id}
role="combobox"
className={cx("ui-combo", className)}
style={style}
disabled={disabled}
aria-label={props["aria-label"]}
aria-labelledby={props["aria-labelledby"]}
aria-describedby={props["aria-describedby"]}
aria-haspopup="listbox"
aria-expanded={open}
aria-controls={open ? listId : undefined}
aria-activedescendant={open && active >= 0 ? optionId(active) : undefined}
data-tooltip={props["data-tooltip"]}
data-value={value ?? ""}
onClick={() => (open ? close() : openList())}
onKeyDown={onKeyDown}
onBlur={onBlur}
onFocus={onFocus}
>
{selected?.icon && <span className="ui-combo__icon" aria-hidden="true">{selected.icon}</span>}
<span className={cx("ui-combo__value", !selected && "ui-combo__value--placeholder")}>{props.displayText ?? (selected ? selected.label : placeholder ?? " ")}</span>
<ChevronDown12 className="ui-combo__chevron" aria-hidden="true" />
</button>
{name !== undefined && <input type="hidden" name={name} value={value === null || value === undefined ? "" : String(value)} />}
{open && createPortal(
<div
ref={list}
id={listId}
role="listbox"
className="ui-combo__list"
aria-label={props["aria-label"]}
aria-labelledby={props["aria-labelledby"]}
style={position}
{...{ [LAYER_ATTR]: "listbox" }}
// Keep DOM focus on the trigger.
onMouseDown={(event) => event.preventDefault()}
>
{flat.map((option, index) => (
<div key={`${String(option.value)}-${index}`} role="presentation">
{option.firstInGroup && <div className="ui-combo__group" role="presentation">{option.group}</div>}
<div
id={optionId(index)}
role="option"
data-value={String(option.value)}
aria-selected={index === selectedIndex}
aria-disabled={option.disabled || undefined}
className={cx("ui-combo__option", index === active && "ui-combo__option--active", index === selectedIndex && "ui-combo__option--selected")}
onMouseMove={() => { if (!option.disabled && active !== index) setActive(index); }}
onClick={() => { if (option.disabled) return; commit(index); close(); }}
>
{option.icon && <span className="ui-combo__icon" aria-hidden="true">{option.icon}</span>}
<span className="ui-combo__option-text">
<span className="ui-combo__option-label">{option.label}</span>
{option.description && <span className="ui-combo__option-description">{option.description}</span>}
</span>
</div>
</div>
))}
</div>,
document.body,
)}
</>
);
}
/* --- Editable mode ------------------------------------------------------------ */
function EditableComboBox<V extends ComboValue = string>(props: ComboBoxProps<V>) {
const {
value, onChange, options, children, id, name, disabled, placeholder, className, width, onBlur, onFocus, parseText, displayText,
} = props;
const items = useMemo(() => (options ?? (optionsFromChildren(children) as unknown as ComboItems<V>)), [options, children]);
const flat = useMemo(() => flatten(items), [items]);
const selectedIndex = flat.findIndex((option) => option.value === value || String(option.value) === String(value ?? "\u0000"));
const shown = displayText ?? (selectedIndex >= 0 ? flat[selectedIndex].text : "");
const [draft, setDraft] = useState<string | null>(null);
const [open, setOpen] = useState(false);
const [active, setActive] = useState(-1);
const [position, setPosition] = useState<CSSProperties>({ visibility: "hidden" });
const box = useRef<HTMLSpanElement>(null);
const input = useRef<HTMLInputElement>(null);
const list = useRef<HTMLDivElement>(null);
const autoId = useId();
const listId = `${autoId}-list`;
const optionId = (index: number) => `${autoId}-opt-${index}`;
const enabledIndexes = flat.map((option, index) => (option.disabled ? -1 : index)).filter((index) => index >= 0);
const parse = (text: string): V | null => {
if (parseText) return parseText(text);
const needle = text.trim().toLowerCase();
const match = flat.find((option) => !option.disabled && (option.text.toLowerCase() === needle || String(option.value).toLowerCase() === needle));
return match ? match.value : null;
};
/** Commits typed text (if any). Returns true when something was typed. */
const commitDraft = () => {
if (draft === null) return false;
const next = draft.trim() === shown.trim() ? null : parse(draft);
setDraft(null);
if (next !== null) onChange(next);
return true;
};
const choose = (index: number) => {
const option = flat[index];
if (!option || option.disabled) return;
setDraft(null);
onChange(option.value);
};
const openList = () => {
if (disabled || !flat.length) return;
setActive(selectedIndex >= 0 && !flat[selectedIndex].disabled ? selectedIndex : -1);
setPosition({ visibility: "hidden" });
setOpen(true);
};
const close = () => setOpen(false);
useLightDismiss(list, open, () => close(), { ignore: [box] });
useLayoutEffect(() => {
if (!open || !list.current || !box.current) return;
const anchor = box.current.getBoundingClientRect();
const view = viewport();
const listRect = list.current.getBoundingClientRect();
const height = listRect.height || flat.length * ITEM_HEIGHT + 8;
const listWidth = Math.max(anchor.width, listRect.width);
const placed = placeAnchored(anchor, { width: listWidth, height }, "bottom", 4, view);
const left = Math.max(VIEWPORT_MARGIN, Math.min(placed.left, view.width - listWidth - VIEWPORT_MARGIN));
setPosition({ top: placed.top, left, minWidth: anchor.width });
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [open]);
useLayoutEffect(() => {
if (!open || active < 0) return;
document.getElementById(optionId(active))?.scrollIntoView?.({ block: "nearest" });
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [open, active]);
const step = (from: number, delta: number) => {
if (!enabledIndexes.length) return -1;
const at = enabledIndexes.indexOf(from);
if (at < 0) return delta > 0 ? enabledIndexes[0] : enabledIndexes[enabledIndexes.length - 1];
return enabledIndexes[Math.max(0, Math.min(enabledIndexes.length - 1, at + delta))];
};
const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
if (disabled) return;
const { key, altKey } = event;
if ((altKey && key === "ArrowDown") || key === "F4") {
event.preventDefault();
if (open) close(); else openList();
return;
}
if (key === "ArrowDown" || key === "ArrowUp") {
event.preventDefault();
if (altKey) { close(); return; }
if (!open) { openList(); return; }
// Moving through the list drops what was typed: Enter takes the item.
setDraft(null);
setActive(step(active, key === "ArrowDown" ? 1 : -1));
return;
}
if (key === "Enter") {
event.preventDefault();
event.stopPropagation();
if (!commitDraft() && open && active >= 0) choose(active);
close();
input.current?.select();
return;
}
if (key === "Escape") {
if (!open && draft === null) return;
event.preventDefault();
event.stopPropagation();
if (open) close();
else setDraft(null);
return;
}
if (key === "Tab" && open) close();
};
const style: CSSProperties | undefined = width !== undefined ? { width: typeof width === "number" ? `${width}px` : width } : undefined;
return (
<>
<span ref={box} className={cx("ui-combo", "ui-combo--editable", disabled && "ui-combo--disabled", className)} style={style} data-tooltip={props["data-tooltip"]}>
<input
ref={input}
id={id}
type="text"
role="combobox"
className="ui-combo__input"
disabled={disabled}
aria-label={props["aria-label"]}
aria-labelledby={props["aria-labelledby"]}
aria-describedby={props["aria-describedby"]}
aria-autocomplete="none"
aria-haspopup="listbox"
aria-expanded={open}
aria-controls={open ? listId : undefined}
aria-activedescendant={open && active >= 0 ? optionId(active) : undefined}
data-value={value ?? ""}
spellCheck={false}
autoComplete="off"
placeholder={typeof placeholder === "string" ? placeholder : undefined}
value={draft ?? shown}
onChange={(event) => setDraft(event.target.value)}
onKeyDown={onKeyDown}
onFocus={(event) => { event.currentTarget.select(); onFocus?.(); }}
onBlur={() => { commitDraft(); close(); onBlur?.(); }}
/>
<button
type="button"
className="ui-combo__button"
tabIndex={-1}
aria-hidden="true"
disabled={disabled}
// Keep focus (and any typing) in the field.
onMouseDown={(event) => event.preventDefault()}
onClick={() => { input.current?.focus(); if (open) close(); else openList(); }}
>
<ChevronDown12 className="ui-combo__chevron" aria-hidden="true" />
</button>
</span>
{name !== undefined && <input type="hidden" name={name} value={value === null || value === undefined ? "" : String(value)} />}
{open && createPortal(
<div
ref={list}
id={listId}
role="listbox"
className="ui-combo__list"
aria-label={props["aria-label"]}
aria-labelledby={props["aria-labelledby"]}
style={position}
{...{ [LAYER_ATTR]: "listbox" }}
onMouseDown={(event) => event.preventDefault()}
>
{flat.map((option, index) => (
<div key={`${String(option.value)}-${index}`} role="presentation">
{option.firstInGroup && <div className="ui-combo__group" role="presentation">{option.group}</div>}
<div
id={optionId(index)}
role="option"
data-value={String(option.value)}
aria-selected={index === selectedIndex}
aria-disabled={option.disabled || undefined}
className={cx("ui-combo__option", index === active && "ui-combo__option--active", index === selectedIndex && "ui-combo__option--selected")}
onMouseMove={() => { if (!option.disabled && active !== index) setActive(index); }}
onClick={() => { if (option.disabled) return; choose(index); close(); input.current?.select(); }}
>
{option.icon && <span className="ui-combo__icon" aria-hidden="true">{option.icon}</span>}
<span className="ui-combo__option-text">
<span className="ui-combo__option-label">{option.label}</span>
{option.description && <span className="ui-combo__option-description">{option.description}</span>}
</span>
</div>
</div>
))}
</div>,
document.body,
)}
</>
);
}