@octane-xplat/ui 0.9.0 → 0.11.0

package/src/CommandPalette.tsrx

@@ -1,65 +1,70 @@
 /** @jsxImportSource @nativescript-community/octane */
-import { useState } from 'octane';
+import { useEffect, useMemo, useRef } from 'octane';
+import type { CommandPaletteItem, CommandPaletteProps } from './props';
+import { createCommandPaletteController } from './command-palette-state';
+import { useStore } from './use-store.tsrx';
+import { groupTypeaheadItems } from './typeahead-source';
+import { cx } from './cx';
 import { Screen } from '@nativescript/core';
-import type { CommandPaletteProps, MenuItem } from "./props";
-import { cx } from "./cx";
-import { Overlay } from './Overlay.tsrx';
+import { BottomSheet } from './BottomSheet.tsrx';
 import { TextInput } from './TextInput.tsrx';
-import { Icon } from './Icon.tsrx';
+import { Pressable } from './Pressable.tsrx';
+import { announceCommandPalette } from './command-palette-accessibility.mobile';
+import { Icon } from './Icon';
 
-/** CommandPalette — in-window overlay: search field + filtered action
- *  list. Shade dismisses; Enter selects the first match. */
-export function CommandPalette(props: CommandPaletteProps) @{
-	const [query, setQuery] = useState('');
+function PaletteBody<T extends CommandPaletteItem>(props: { options: CommandPaletteProps<T>; controller: ReturnType<typeof createCommandPaletteController<T>> }) @{
+	const state = useStore(props.controller.store);
+	const statusView = useRef<any>(null);
+	const groups = useMemo(() => groupTypeaheadItems(state.results), [state.results]);
 
-	const setOpen = (next: boolean) => {
-		if (!next) setQuery('');
-		props.onOpenChange?.(next);
-	};
+	useEffect(() => {
+		if (!state.query.trim()) return;
+		const message = state.status === 'loading' ? props.options.loadingText ?? 'Loading…'
+			: state.status === 'error' ? props.options.errorText ?? 'Could not load commands. Try again.'
+				: !state.results.length ? props.options.emptySearchText ?? 'No results'
+					: `${state.results.length} result${state.results.length === 1 ? '' : 's'}`;
 
-	const shown = query
-		? props.items.filter((i) => (i.label ?? i.key).toLowerCase().includes(query.toLowerCase()))
-		: props.items;
+		announceCommandPalette(statusView.current, message);
+	}, [state.status, state.query, state.results]);
 
-	const panelStyle = {
-		...props.style,
-		maxWidth: props.style?.maxWidth ?? Screen.mainScreen.widthDIPs * 0.9,
-	};
+	<flexboxlayout flexDirection="column" className={cx('vx-commandpalette', props.options.className)} style={{ width: props.options.width ?? Screen.mainScreen.widthDIPs * 0.9, ...props.options.style }} id={props.options.id} accessibilityLabel={props.options.label ?? 'Command palette'}>
+		<flexboxlayout flexDirection="row" className="vx-cmdk-input-row">
+			<TextInput id={`${props.options.id ?? 'command-palette'}-query`} className="vx-cmdk-search" label={props.options.label ?? 'Command palette'} accessibilityLabel={props.options.label ?? 'Command palette'} placeholder={props.options.placeholder ?? 'Search commands…'} value={state.query} onChange={props.controller.search} onSubmit={() => props.controller.search(state.query)} returnKeyType="search" hasClear={false} />
+			<button id={`${props.options.id ?? 'command-palette'}-clear`} text="Clear" onTap={() => props.controller.search('')} accessibilityLabel="Clear search" />
+			<button id={`${props.options.id ?? 'command-palette'}-cancel`} text="Cancel" onTap={props.controller.close} />
+		</flexboxlayout>
+		<label ref={(view: any) => { statusView.current = view; }} id={`${props.options.id ?? 'command-palette'}-status`} className="vx-cmdk-status" text={state.status === 'loading' ? props.options.loadingText ?? 'Loading…' : state.status === 'error' ? props.options.errorText ?? 'Could not load commands. Try again.' : state.status === 'ready' && !state.results.length ? state.query.trim() ? props.options.emptySearchText ?? 'No results' : props.options.emptyBootstrapText ?? 'Type to search' : ''} />
+		{state.status === 'error' ? <button text="Retry" onTap={() => props.controller.search(state.query)} /> : null}
+		<scrollview className="vx-cmdk-list" height={props.options.maxHeight ?? Screen.mainScreen.heightDIPs * 0.3}>
+			<stacklayout className="vx-menu-list">
+				@for (const group of groups; index gi; key group.heading ?? gi) {
+					<stacklayout accessibilityLabel={group.heading ?? undefined}>
+						{group.heading != null ? <label className="vx-cmdk-heading" text={group.heading} /> : null}
+						@for (const item of group.items; key item.id) {
+							<Pressable id={`${props.options.id ?? 'command-palette'}-item-${item.id}`} className={cx('vx-menu-item', item.disabled && 'vx-menu-item--disabled', item.id === state.highlighted && 'vx-cmdk-highlighted')} disabled={item.disabled} accessibilityRole="button" accessibilityLabel={item.label} accessibilityState={{ disabled: item.disabled, selected: item.id === state.selected }} onPress={() => props.controller.select(item.id)}>
+								{props.options.renderItem ? props.options.renderItem(item, item.id === state.selected) : <>
+									{item.icon ? <Icon name={item.icon} /> : null}
+									<stacklayout className="vx-cmdk-item-content"><label className="vx-menu-item-label" text={item.label} />{item.description ? <label className="vx-cmdk-description" text={item.description} /> : null}</stacklayout>
+									{item.shortcut ? <label className="vx-cmdk-shortcut" text={item.shortcut} /> : null}
+								</>}
+							</Pressable>
+						}
+					</stacklayout>
+				}
+			</stacklayout>
+		</scrollview>
+		{props.options.footer != null && props.options.footer !== false ? <flexboxlayout className="vx-cmdk-footer">{props.options.footer}</flexboxlayout> : null}
+	</flexboxlayout>
+}
 
-	const select = (item: MenuItem) => {
-		if (item.disabled) return;
-		setOpen(false);
-		item.onSelect?.();
-	};
+/** Touch-first search sheet. Search submits the query; explicit taps activate rows. */
+export function CommandPalette<T extends CommandPaletteItem>(props: CommandPaletteProps<T>) @{
+	const controller = useMemo(() => createCommandPaletteController(() => props), []);
+	useEffect(() => controller.configure(props), [props.open, props.searchSource, props.items, props.searchMode, props.value, props.onOpenChange, props.onValueChange]);
+	useEffect(() => () => controller.dispose(), []);
+	const state = useStore(controller.store);
 
-	<Overlay open={props.open} shadeCover={true} onDismiss={() => setOpen(false)} className="vx-cmdk-layer">
-		<flexboxlayout
-			className={cx('vx-commandpalette', props.className)}
-			style={panelStyle}
-			id={props.id}
-			flexDirection="column"
-			horizontalAlignment="center"
-			verticalAlignment="top"
-			marginTop={80}
-		>
-			<TextInput
-				className="vx-cmdk-search"
-				placeholder={props.placeholder ?? 'Type a command…'}
-				value={query}
-				onChange={setQuery}
-				onSubmit={() => { if (shown.length && !shown[0].disabled) select(shown[0]); }}
-			/>
-			<flexboxlayout className="vx-menu-list vx-cmdk-list">
-				@for (const item of shown; key item.key) {
-					<flexboxlayout
-						className={cx('vx-menu-item', item.disabled && 'vx-menu-item--disabled')}
-						onTap={item.disabled ? undefined : () => select(item)}
-					>
-						{item.icon ? <Icon name={item.icon} /> : null}
-						{item.label != null ? <label className="vx-menu-item-label" text={item.label} /> : null}
-					</flexboxlayout>
-				}
-			</flexboxlayout>
-		</flexboxlayout>
-	</Overlay>
+	<BottomSheet isOpen={state.open} onOpenChange={(open: boolean) => { if (!open) controller.close(); }} label={props.label ?? 'Command palette'} height="hug" ios={props.ios} android={props.android}>
+		<PaletteBody options={props} controller={controller} />
+	</BottomSheet>
 }

package/src/CommandPalette.web.test.tsrx

@@ -0,0 +1,88 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRoot, act } from 'octane';
+vi.mock('./theme/theme-scheme', () => ({ useThemeScheme: () => 'light' }));
+import { CommandPalette } from './CommandPalette.web.tsrx';
+
+const cleanups: (() => void)[] = [];
+afterEach(() => { cleanups.splice(0).forEach((cleanup) => cleanup()); document.body.replaceChildren(); });
+async function mount(props: any) {
+	const host = document.createElement('div');
+	document.body.append(host);
+	const root = createRoot(host);
+	await act(() => root.render(<CommandPalette {...props} />));
+	cleanups.push(() => root.unmount());
+	return root;
+}
+
+const key = async (input: Element, value: string, isComposing = false) => {
+	await act(() => input.dispatchEvent(new KeyboardEvent('keydown', { key: value, bubbles: true, cancelable: true, isComposing })));
+};
+
+const type = async (input: HTMLInputElement, query: string) => {
+	await act(() => { input.value = query; input.dispatchEvent(new Event('input', { bubbles: true })); });
+};
+
+describe('CommandPalette web interaction', () => {
+	it('links a named input and grouped results; navigates enabled rows and activates only the highlight', async () => {
+		const selected: string[] = [];
+		let closes = 0;
+		await mount({ open: true, onOpenChange: () => { closes++; }, onValueChange: (id: string) => selected.push(id), items: [
+			{ key: 'off', label: 'Off', disabled: true, group: 'Actions' },
+			{ key: 'settings', label: 'Settings', group: 'Navigation' },
+			{ key: 'new', label: 'New', group: 'Actions' },
+		] });
+
+		const input = document.querySelector('[role="combobox"]')!;
+		expect(input.getAttribute('aria-label')).toBe('Command palette');
+		expect(document.getElementById(input.getAttribute('aria-controls')!)?.getAttribute('role')).toBe('listbox');
+		expect(document.activeElement).toBe(input);
+		await key(input, 'Enter');
+		expect(selected).toEqual([]);
+		await key(input, 'ArrowDown');
+		expect(document.getElementById(input.getAttribute('aria-activedescendant')!)?.textContent).toContain('New');
+		await key(input, 'Enter', true);
+		expect(selected).toEqual([]);
+		await key(input, 'ArrowDown');
+		await key(input, 'Enter');
+		expect(selected).toEqual(['settings']);
+		expect(closes).toBe(1);
+		expect(document.querySelector('[role="combobox"]')).toBeNull();
+	});
+
+	it('renders loading, rejected search, retry and no results without executing stale commands', async () => {
+		let reject!: (error: Error) => void;
+		let fail = true;
+		await mount({ open: true, searchSource: { bootstrap: () => [], search: () => fail ? new Promise((_, no) => { reject = no; }) : [] } });
+		const input = document.querySelector('input')!;
+		await type(input, 'remote');
+		expect(document.querySelector('[role="status"]')!.textContent).toContain('Loading');
+		await act(async () => { reject(new Error('offline')); await Promise.resolve(); });
+		expect(document.querySelector('[role="status"]')!.textContent).toContain('Could not load');
+		fail = false;
+		await act(() => Array.from(document.querySelectorAll('button')).find((button) => button.textContent === 'Retry')!.click());
+		expect(document.querySelector('[role="status"]')!.textContent).toBe('No results');
+	});
+
+	it('follows external close/reopen and replaces a pending source', async () => {
+		const original = { open: true, items: [{ key: 'one', label: 'One' }] };
+		const root = await mount(original);
+		await type(document.querySelector('input')!, 'missing');
+		await act(() => root.render(<CommandPalette {...original} open={false} />));
+		expect(document.querySelector('input')).toBeNull();
+		await act(() => root.render(<CommandPalette {...original} open={true} />));
+		expect(document.querySelector('input')?.value).toBe('');
+		expect(document.querySelector('[role="option"]')?.textContent).toContain('One');
+	});
+
+	it('hover changes highlight without scrolling, and Escape closes once', async () => {
+		let closes = 0;
+		await mount({ open: true, onOpenChange: () => { closes++; }, items: [{ key: 'one', label: 'One' }] });
+		const option = document.querySelector('[role="option"]')!;
+		await act(() => option.dispatchEvent(new MouseEvent('mouseenter', { bubbles: false })));
+		const input = document.querySelector('input')!;
+		expect(input.getAttribute('aria-activedescendant')).toBe(option.id);
+		await key(input, 'Escape');
+		expect(closes).toBe(1);
+	});
+});

package/src/CommandPalette.web.tsrx

@@ -1,59 +1,95 @@
-import { useEffect, useState } from 'octane';
-import type { CommandPaletteProps, MenuItem } from "./props";
+import { useEffect, useId, useMemo, useRef } from 'octane';
+import type { CommandPaletteItem, CommandPaletteProps } from './props';
 import { Overlay } from './Overlay.web.tsrx';
-import { TextInput } from './TextInput.web.tsrx';
 import { Icon } from './Icon.web.tsrx';
+import { useStore } from './use-store.web.tsrx';
+import { createCommandPaletteController } from './command-palette-state';
+import { groupTypeaheadItems } from './typeahead-source';
 
-/** CommandPalette — in-window overlay: search field + filtered action
- *  list. Esc or shade dismisses; Enter selects the first match. */
-export function CommandPalette(props: CommandPaletteProps) @{
-	const [query, setQuery] = useState('');
-
-	const setOpen = (next: boolean) => {
-		if (!next) setQuery('');
-		props.onOpenChange?.(next);
+/** Desktop command search: focus remains in the input while arrows highlight results. */
+export function CommandPalette<T extends CommandPaletteItem>(props: CommandPaletteProps<T>) @{
+	const controller = useMemo(() => createCommandPaletteController(() => props), []);
+	useEffect(() => controller.configure(props), [props.open, props.searchSource, props.items, props.searchMode, props.value, props.onOpenChange, props.onValueChange]);
+	useEffect(() => () => controller.dispose(), []);
+	const state = useStore(controller.store);
+	const generatedId = useId();
+	const listId = `${generatedId}-commands`;
+	const input = useRef<HTMLInputElement | null>(null);
+	const groups = useMemo(() => groupTypeaheadItems(state.results), [state.results]);
+	const optionId = (id: string) => `${props.id ?? listId}-item-${id}`;
+	const keyDown = (event: any) => {
+		controller.keyDown(event);
+		if (event.defaultPrevented && ['ArrowDown', 'ArrowUp', 'PageUp', 'PageDown'].includes(event.key)) {
+			const highlighted = controller.store.get().highlighted;
+			if (highlighted) document.getElementById(optionId(highlighted))?.scrollIntoView?.({ block: 'nearest' });
+		}
 	};
 
-	useEffect(() => {
-		if (!props.open) return;
-		const onKey = (e: any) => { if (e.key === 'Escape') setOpen(false); };
-		window.addEventListener('keydown', onKey);
-		return () => window.removeEventListener('keydown', onKey);
-	}, [props.open]);
-
-	const shown = query
-		? props.items.filter((i) => (i.label ?? i.key).toLowerCase().includes(query.toLowerCase()))
-		: props.items;
-
-	const select = (item: MenuItem) => {
-		if (item.disabled) return;
-		setOpen(false);
-		item.onSelect?.();
-	};
-
-	<Overlay open={props.open} shadeCover={true} onDismiss={() => setOpen(false)} className="vx-cmdk-layer">
-		<div className={['vx-commandpalette', props.className]} style={props.style} id={props.id}>
-			<TextInput
-				className="vx-cmdk-search"
-				placeholder={props.placeholder ?? 'Type a command…'}
-				value={query}
-				onChange={setQuery}
-				onSubmit={() => { if (shown.length && !shown[0].disabled) select(shown[0]); }}
-			/>
-			<div role="listbox" className="vx-menu-list vx-cmdk-list">
-				{shown.map((item: MenuItem) => (
-					<div
-						key={item.key}
-						role="option"
-						aria-disabled={item.disabled || undefined}
-						className={['vx-menu-item', item.disabled ? 'vx-menu-item--disabled' : undefined]}
-						onClick={item.disabled ? undefined : () => select(item)}
-					>
-						{item.icon ? <Icon name={item.icon} /> : null}
-						{item.label != null ? <span className="vx-menu-item-label">{item.label}</span> : null}
+	<Overlay accessibilityLabel={props.label ?? 'Command palette'} open={state.open} shadeCover={true} onDismiss={controller.close} className="vx-cmdk-layer">
+		<div
+			className={['vx-commandpalette', props.className]}
+			style={{ ...(props.width != null ? { width: props.width } : {}), ...props.style }}
+			id={props.id}
+			role="group"
+			aria-label={props.label ?? 'Command palette'}
+			{...props.web}
+		>
+			<div className="vx-cmdk-input-row">
+				<input
+					ref={input}
+					id={`${props.id ?? generatedId}-query`}
+					className="vx-input vx-cmdk-search"
+					type="text"
+					role="combobox"
+					aria-label={props.label ?? 'Command palette'}
+					aria-expanded={state.open}
+					aria-controls={listId}
+					aria-activedescendant={state.highlighted ? optionId(state.highlighted) : undefined}
+					aria-autocomplete="list"
+					aria-busy={state.status === 'loading' || undefined}
+					placeholder={props.placeholder ?? 'Type a command…'}
+					value={state.query}
+					onInput={(event: any) => controller.search(event.target.value)}
+					onKeyDown={keyDown}
+					autoComplete="off"
+				/>
+				<button type="button" className="vx-input-clear" aria-label="Clear search" disabled={!state.query} onClick={() => { controller.search(''); input.current?.focus(); }}>×</button>
+				<button type="button" className="vx-cmdk-cancel" onClick={controller.close}>Cancel</button>
+			</div>
+			<div id={`${props.id ?? generatedId}-status`} className="vx-cmdk-status" role="status" aria-live="polite">
+				{state.status === 'loading' ? props.loadingText ?? 'Loading…'
+					: state.status === 'error' ? props.errorText ?? 'Could not load commands. Try again.'
+						: state.status === 'ready' && !state.results.length ? state.query.trim() ? props.emptySearchText ?? 'No results' : props.emptyBootstrapText ?? 'Type to search'
+							: state.query.trim() ? `${state.results.length} result${state.results.length === 1 ? '' : 's'}` : ''}
+			</div>
+			{state.status === 'error' ? <button type="button" onClick={() => controller.search(state.query)}>Retry</button> : null}
+			<div id={listId} role="listbox" aria-label="Commands" className="vx-menu-list vx-cmdk-list" style={{ maxHeight: props.maxHeight ?? 320 }}>
+				{groups.map((group, gi) => (
+					<div key={group.heading ?? gi} role={group.heading != null ? 'group' : undefined} aria-label={group.heading ?? undefined}>
+						{group.heading != null ? <div className="vx-cmdk-heading" aria-hidden="true">{group.heading}</div> : null}
+						{group.items.map((item) => (
+							<div
+								key={item.id}
+								id={optionId(item.id)}
+								role="option"
+								aria-selected={item.id === state.selected}
+								aria-disabled={item.disabled || undefined}
+								className={['vx-menu-item', item.disabled ? 'vx-menu-item--disabled' : undefined, item.id === state.highlighted ? 'vx-cmdk-highlighted' : undefined]}
+								onMouseDown={(event: any) => event.preventDefault()}
+								onMouseEnter={() => { if (!item.disabled) controller.highlight(item.id); }}
+								onClick={() => controller.select(item.id)}
+							>
+								{props.renderItem ? props.renderItem(item, item.id === state.selected) : <>
+									{item.icon ? <Icon name={item.icon} /> : null}
+									<div className="vx-cmdk-item-content"><span className="vx-menu-item-label">{item.label}</span>{item.description ? <span className="vx-cmdk-description">{item.description}</span> : null}</div>
+									{item.shortcut ? <kbd className="vx-cmdk-shortcut">{item.shortcut}</kbd> : null}
+								</>}
+							</div>
+						))}
 					</div>
 				))}
 			</div>
+			{props.footer !== false ? <div className="vx-cmdk-footer">{props.footer ?? <><kbd>↑</kbd><kbd>↓</kbd> Navigate <kbd>Enter</kbd> Select <kbd>Esc</kbd> Close</>}</div> : null}
 		</div>
 	</Overlay>
 }

package/src/ComplexSelector.macos.tsrx

@@ -0,0 +1,106 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useImperativeHandle, useEffect, useId, useRef, useState } from 'octane';
+import type { ComplexSelectorHandle, ComplexSelectorProps } from './props';
+import { cx } from './cx';
+import { FormField } from './FormField.macos.tsrx';
+import { Popover } from './surfaces.macos.tsrx';
+import { Pressable } from './Pressable.macos.tsrx';
+import { Icon } from './Icon.macos.tsrx';
+import { ActivityIndicator } from './controls.macos.tsrx';
+
+/** Field trigger and anchored render-function surface for custom pickers. */
+export function ComplexSelector<Value,>(props: ComplexSelectorProps<Value>) @{
+	const triggerId = useId();
+	const contentId = useId();
+	const anchor = useRef<any>(null);
+	const [isOpen, setIsOpen] = useState(false);
+	const [isBusy, setIsBusy] = useState(false);
+	const [optimisticValue, setOptimisticValue] = useState(props.value);
+
+	if (optimisticValue !== props.value && !isBusy) setOptimisticValue(props.value);
+
+	const setOpen = (next: boolean) => {
+		setIsOpen(next);
+		props.onOpenChange?.(next);
+		if (!next) { anchor.current?.focus?.(); anchor.current?.requestFocus?.(); }
+	};
+
+	const handle: ComplexSelectorHandle = {
+		open: () => setOpen(true),
+		close: () => setOpen(false),
+		toggle: () => setOpen(!isOpen),
+		isOpen: () => isOpen,
+	};
+
+	useImperativeHandle(props.ref, () => handle, [props.ref, isOpen]);
+
+	const commit = async (next: Value) => {
+		const previous = optimisticValue;
+		setOptimisticValue(next);
+		props.onChange?.(next);
+		if (!props.changeAction) return;
+		setIsBusy(true);
+		try {
+			await props.changeAction(next);
+		} catch {
+			setOptimisticValue(previous);
+			props.onChange?.(previous);
+		} finally {
+			setIsBusy(false);
+		}
+	};
+
+	const content = props.children(optimisticValue, commit, () => setOpen(false), { isOpen, isBusy: isBusy || Boolean(props.isLoading), triggerId, contentId });
+
+	const trigger = <Pressable
+		id={triggerId}
+		ref={(view: any) => { anchor.current = view; }}
+		className={cx('vx-complex-selector-trigger', `vx-complex-selector-trigger--${props.variant ?? 'input'}`)}
+		disabled={props.isDisabled || props.isReadOnly || isBusy}
+		accessibilityLabel={props.label}
+		accessibilityHint={props.description}
+		accessibilityRole="button"
+		accessibilityState={{ expanded: isOpen, disabled: props.isDisabled || isBusy } as any}
+		onPress={() => setOpen(!isOpen)}
+	>
+		{typeof props.startIcon === 'string' ? <Icon name={props.startIcon} size={16} /> : props.startIcon}
+		<label className={cx('vx-complex-selector-value', props.triggerLabel == null && props.value == null && 'vx-complex-selector-placeholder')}
+			text={props.triggerLabel ?? (props.value == null ? props.placeholder ?? '' : String(props.value))} />
+		{props.isLoading || isBusy ? <ActivityIndicator busy={true} /> : null}
+	</Pressable>;
+
+	const body = <>
+		{props.variant === 'ghost' ? trigger : <flexboxlayout
+			className={cx('vx-complex-selector', `vx-complex-selector--size-${props.size ?? 'md'}`, props.status && `vx-complex-selector--status-${props.status.type}`)}
+			flexDirection="row"
+			alignItems="center"
+		>
+			{trigger}
+		</flexboxlayout>}
+		<Popover anchor={anchor} open={isOpen} placement={props.placement ?? 'bottom'} alignment={props.alignment ?? 'start'} onDismiss={() => setOpen(false)} className={props.contentClassName} style={props.contentXstyle}>
+			<gridlayout id={contentId} accessibilityRole={"dialog" as any}>{content}</gridlayout>
+		</Popover>
+	</>;
+
+	if (props.variant === 'ghost') return body;
+
+	<FormField
+		id={props.id}
+		label={props.label}
+		description={props.description}
+		isLabelHidden={props.isLabelHidden}
+		isRequired={props.isRequired}
+		isOptional={props.isOptional}
+		isDisabled={props.isDisabled}
+		isReadOnly={props.isReadOnly}
+		isLoading={props.isLoading || isBusy}
+		status={props.status}
+		statusVariant={props.statusVariant}
+		labelTooltip={props.labelTooltip}
+		size={props.size}
+		className={props.className}
+		style={{ ...(props.width != null ? { width: props.width } : {}), ...props.style }}
+	>
+		{body}
+	</FormField>
+}

package/src/ComplexSelector.tsrx

@@ -0,0 +1,106 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useImperativeHandle, useEffect, useId, useRef, useState } from 'octane';
+import type { ComplexSelectorHandle, ComplexSelectorProps } from './props';
+import { cx } from './cx';
+import { FormField } from './FormField';
+import { Popover } from './Popover';
+import { Pressable } from './Pressable';
+import { Icon } from './Icon';
+import { ActivityIndicator } from './ActivityIndicator.tsrx';
+
+/** Field trigger and anchored render-function surface for custom pickers. */
+export function ComplexSelector<Value,>(props: ComplexSelectorProps<Value>) @{
+	const triggerId = useId();
+	const contentId = useId();
+	const anchor = useRef<any>(null);
+	const [isOpen, setIsOpen] = useState(false);
+	const [isBusy, setIsBusy] = useState(false);
+	const [optimisticValue, setOptimisticValue] = useState(props.value);
+
+	if (optimisticValue !== props.value && !isBusy) setOptimisticValue(props.value);
+
+	const setOpen = (next: boolean) => {
+		setIsOpen(next);
+		props.onOpenChange?.(next);
+		if (!next) { anchor.current?.focus?.(); anchor.current?.requestFocus?.(); }
+	};
+
+	const handle: ComplexSelectorHandle = {
+		open: () => setOpen(true),
+		close: () => setOpen(false),
+		toggle: () => setOpen(!isOpen),
+		isOpen: () => isOpen,
+	};
+
+	useImperativeHandle(props.ref, () => handle, [props.ref, isOpen]);
+
+	const commit = async (next: Value) => {
+		const previous = optimisticValue;
+		setOptimisticValue(next);
+		props.onChange?.(next);
+		if (!props.changeAction) return;
+		setIsBusy(true);
+		try {
+			await props.changeAction(next);
+		} catch {
+			setOptimisticValue(previous);
+			props.onChange?.(previous);
+		} finally {
+			setIsBusy(false);
+		}
+	};
+
+	const content = props.children(optimisticValue, commit, () => setOpen(false), { isOpen, isBusy: isBusy || Boolean(props.isLoading), triggerId, contentId });
+
+	const trigger = <Pressable
+		id={triggerId}
+		ref={(view: any) => { anchor.current = view; }}
+		className={cx('vx-complex-selector-trigger', `vx-complex-selector-trigger--${props.variant ?? 'input'}`)}
+		disabled={props.isDisabled || props.isReadOnly || isBusy}
+		accessibilityLabel={props.label}
+		accessibilityHint={props.description}
+		accessibilityRole="button"
+		accessibilityState={{ expanded: isOpen, disabled: props.isDisabled || isBusy } as any}
+		onPress={() => setOpen(!isOpen)}
+	>
+		{typeof props.startIcon === 'string' ? <Icon name={props.startIcon} size={16} /> : props.startIcon}
+		<label className={cx('vx-complex-selector-value', props.triggerLabel == null && props.value == null && 'vx-complex-selector-placeholder')}
+			text={props.triggerLabel ?? (props.value == null ? props.placeholder ?? '' : String(props.value))} />
+		{props.isLoading || isBusy ? <ActivityIndicator busy={true} /> : null}
+	</Pressable>;
+
+	const body = <>
+		{props.variant === 'ghost' ? trigger : <flexboxlayout
+			className={cx('vx-complex-selector', `vx-complex-selector--size-${props.size ?? 'md'}`, props.status && `vx-complex-selector--status-${props.status.type}`)}
+			flexDirection="row"
+			alignItems="center"
+		>
+			{trigger}
+		</flexboxlayout>}
+		<Popover anchor={anchor} open={isOpen} placement={props.placement ?? 'bottom'} alignment={props.alignment ?? 'start'} onDismiss={() => setOpen(false)} className={props.contentClassName} style={props.contentXstyle}>
+			<gridlayout id={contentId} accessibilityRole={"dialog" as any}>{content}</gridlayout>
+		</Popover>
+	</>;
+
+	if (props.variant === 'ghost') return body;
+
+	<FormField
+		id={props.id}
+		label={props.label}
+		description={props.description}
+		isLabelHidden={props.isLabelHidden}
+		isRequired={props.isRequired}
+		isOptional={props.isOptional}
+		isDisabled={props.isDisabled}
+		isReadOnly={props.isReadOnly}
+		isLoading={props.isLoading || isBusy}
+		status={props.status}
+		statusVariant={props.statusVariant}
+		labelTooltip={props.labelTooltip}
+		size={props.size}
+		className={props.className}
+		style={{ ...(props.width != null ? { width: props.width } : {}), ...props.style }}
+	>
+		{body}
+	</FormField>
+}