Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(editor): unify inspector dropdowns on one keyboard/ARIA listbox

yhhec6259912449
diff --git a/desktop/src/components/Select.tsx b/desktop/src/components/Select.tsx
index f2bce0e8a..4e4eef980 100644
--- a/desktop/src/components/Select.tsx
+++ b/desktop/src/components/Select.tsx
@@ -12,9 +12,10 @@
* like Details' EnumControl). List styling reuses the `.dd-*` popover
* vocabulary.
*/
-import { useEffect, useRef, type CSSProperties } from 'react';
+import { useRef, type CSSProperties } from 'react';
import { ChevronDown, Check } from 'lucide-react';
import { Popover, usePopover } from './Popover';
+import { useListbox } from './useListbox';
export interface SelectOption<T extends string> {
value: T;
@@ -41,7 +42,7 @@ export function Select<T extends string>({
}) {
const pop = usePopover();
const trigger = useRef<HTMLButtonElement>(null);
- const listRef = useRef<HTMLDivElement>(null);
+ const { triggerProps, listProps } = useListbox(pop.isOpen);
const cur = options.find((o) => o.value === value);
const close = () => {
@@ -53,29 +54,6 @@ export function Select<T extends string>({
else pop.open(trigger.current);
};
- // Seed focus on the current option so arrow keys work immediately.
- useEffect(() => {
- if (!pop.isOpen) return;
- const raf = requestAnimationFrame(() => {
- const list = listRef.current;
- const target =
- list?.querySelector<HTMLButtonElement>('.dd-opt.on') ??
- list?.querySelector<HTMLButtonElement>('.dd-opt');
- target?.focus();
- });
- return () => cancelAnimationFrame(raf);
- }, [pop.isOpen]);
-
- const onListKey = (e: React.KeyboardEvent) => {
- if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return;
- e.preventDefault();
- const items = [...(listRef.current?.querySelectorAll<HTMLButtonElement>('.dd-opt') ?? [])];
- if (!items.length) return;
- const i = items.indexOf(document.activeElement as HTMLButtonElement);
- const next = e.key === 'ArrowDown' ? Math.min(items.length - 1, i + 1) : Math.max(0, i - 1);
- items[next]?.focus();
- };
-
const triggerClass =
variant === 'field' ? 'dd-trigger' : `sel-trigger${className ? ` ${className}` : ''}`;
@@ -87,8 +65,7 @@ export function Select<T extends string>({
className={triggerClass}
style={style}
aria-label={ariaLabel}
- aria-haspopup="listbox"
- aria-expanded={pop.isOpen}
+ {...triggerProps}
onMouseDown={(e) => e.stopPropagation()}
onClick={toggle}
>
@@ -97,7 +74,7 @@ export function Select<T extends string>({
</button>
{pop.anchor && (
<Popover anchor={pop.anchor} width={Math.max(pop.anchor.width, 120)} onClose={close}>
- <div className="dd-list" role="listbox" ref={listRef} onKeyDown={onListKey}>
+ <div className="dd-list" {...listProps}>
{options.map((o) => (
<button
key={o.value}
diff --git a/desktop/src/components/useListbox.ts b/desktop/src/components/useListbox.ts
new file mode 100644
index 000000000..02d4fa518
--- /dev/null
+++ b/desktop/src/components/useListbox.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file useListbox.ts
+ * @brief The shared keyboard + ARIA behavior for the editor's popover dropdowns
+ * — the standalone <Select> and the inspector's Enum / Entity / Flags
+ * controls. One implementation so every dropdown navigates and reads to a
+ * screen reader the same way, instead of each rolling (or omitting) its own.
+ *
+ * Seeds focus on the current option when the popover opens (skipped when a
+ * search box owns focus), arrow-navigates the `.dd-opt` buttons, and hands
+ * back ARIA props for the trigger + list. Escape / backdrop dismissal and
+ * focus-return to the trigger stay with the caller's `close()` (it also
+ * ends any inspector edit gesture).
+ */
+import { useEffect, useRef, type KeyboardEvent as ReactKeyboardEvent } from 'react';
+
+export function useListbox(isOpen: boolean, opts: { seedFocus?: boolean; multi?: boolean } = {}) {
+ const { seedFocus = true, multi = false } = opts;
+ const listRef = useRef<HTMLDivElement>(null);
+
+ // Focus the current (or first) option on open so arrow keys work immediately —
+ // unless a search box autofocused, in which case typing wins.
+ useEffect(() => {
+ if (!isOpen || !seedFocus) return;
+ const raf = requestAnimationFrame(() => {
+ const list = listRef.current;
+ const target =
+ list?.querySelector<HTMLButtonElement>('.dd-opt.on') ??
+ list?.querySelector<HTMLButtonElement>('.dd-opt');
+ target?.focus();
+ });
+ return () => cancelAnimationFrame(raf);
+ }, [isOpen, seedFocus]);
+
+ const onListKey = (e: ReactKeyboardEvent) => {
+ if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return;
+ e.preventDefault();
+ const items = [...(listRef.current?.querySelectorAll<HTMLButtonElement>('.dd-opt') ?? [])];
+ if (!items.length) return;
+ const i = items.indexOf(document.activeElement as HTMLButtonElement);
+ // From outside the list (e.g. a search box), ArrowDown enters at the top,
+ // ArrowUp at the bottom; otherwise step and clamp.
+ const next = i < 0
+ ? (e.key === 'ArrowDown' ? 0 : items.length - 1)
+ : e.key === 'ArrowDown' ? Math.min(items.length - 1, i + 1) : Math.max(0, i - 1);
+ items[next]?.focus();
+ };
+
+ const triggerProps = { 'aria-haspopup': 'listbox' as const, 'aria-expanded': isOpen };
+ const listProps = {
+ ref: listRef,
+ role: 'listbox' as const,
+ 'aria-multiselectable': multi || undefined,
+ onKeyDown: onListKey,
+ };
+ return { listRef, onListKey, triggerProps, listProps };
+}
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 69d07a978..ea59494b5 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -85,6 +85,7 @@ import { EmptyState } from '@/components/EmptyState';
import { ContextMenu } from '@/components/Menu';
import { NumField, useScrub, fmt, type ControlGesture } from '@/components/NumField';
import { Popover, usePopover } from '@/components/Popover';
+import { useListbox } from '@/components/useListbox';
import { SearchField } from '@/components/SearchField';
import { Select } from '@/components/Select';
import { Segmented, type SegmentedOption } from '@/components/Segmented';
@@ -266,8 +267,10 @@ export function EnumControl({
const searchable = options.length > 8;
const ql = q.trim().toLowerCase();
const filtered = ql ? options.filter((o) => prettyLabel(o.label).toLowerCase().includes(ql)) : options;
+ const { triggerProps, listProps } = useListbox(pop.isOpen, { seedFocus: !searchable });
const close = () => {
pop.close();
+ trigger.current?.focus();
onEnd?.();
};
const toggle = () => {
@@ -278,7 +281,7 @@ export function EnumControl({
};
return (
<span className="field dropdown">
- <button ref={trigger} type="button" className="dd-trigger" onMouseDown={(e) => e.stopPropagation()} onClick={toggle}>
+ <button ref={trigger} type="button" className="dd-trigger" {...triggerProps} onMouseDown={(e) => e.stopPropagation()} onClick={toggle}>
<span className={`dd-val${mixed ? ' mixed' : ''}`}>{mixed ? '—' : label}</span>
<ChevronDown size={12} strokeWidth={2} />
</button>
@@ -287,11 +290,13 @@ export function EnumControl({
{searchable && (
<SearchField flush className="dd-search" iconSize={12} autoFocus placeholder={t('ui.search')} value={q} onChange={setQ} />
)}
- <div className="dd-list">
+ <div className="dd-list" {...listProps}>
{filtered.map((o) => (
<button
key={o.value}
type="button"
+ role="option"
+ aria-selected={o.value === value && !mixed}
className={`dd-opt${o.value === value && !mixed ? ' on' : ''}`}
onClick={() => {
onChange(o.value);
@@ -354,8 +359,10 @@ export function EntityControl({
: t('det.entityMissing', { id: value });
const ql = q.trim().toLowerCase();
const filtered = ql ? options.filter((o) => o.name.toLowerCase().includes(ql)) : options;
+ const { triggerProps, listProps } = useListbox(pop.isOpen, { seedFocus: options.length <= 8 });
const close = () => {
pop.close();
+ trigger.current?.focus();
onEnd?.();
};
const toggle = () => {
@@ -370,7 +377,7 @@ export function EntityControl({
};
return (
<span className="field dropdown">
- <button ref={trigger} type="button" className="dd-trigger" onMouseDown={(e) => e.stopPropagation()} onClick={toggle}
+ <button ref={trigger} type="button" className="dd-trigger" {...triggerProps} onMouseDown={(e) => e.stopPropagation()} onClick={toggle}
title={isDangling ? t('det.entityMissingTip') : undefined}>
<span className={`dd-val${mixed || isUnsetEntity(value) || isDangling ? ' dd-none' : ''}`}>{mixed ? '—' : label}</span>
<ChevronDown size={12} strokeWidth={2} />
@@ -380,13 +387,13 @@ export function EntityControl({
{options.length > 8 && (
<SearchField flush className="dd-search" iconSize={12} autoFocus placeholder={t('ui.search')} value={q} onChange={setQ} />
)}
- <div className="dd-list">
- <button type="button" className={`dd-opt${isUnsetEntity(value) && !mixed ? ' on' : ''}`} onClick={() => pick(INVALID_ENTITY)}>
+ <div className="dd-list" {...listProps}>
+ <button type="button" role="option" aria-selected={isUnsetEntity(value) && !mixed} className={`dd-opt${isUnsetEntity(value) && !mixed ? ' on' : ''}`} onClick={() => pick(INVALID_ENTITY)}>
<span className="dd-opt-label dd-none">{t('det.entityNone')}</span>
{isUnsetEntity(value) && !mixed && <Check size={12} strokeWidth={2.4} />}
</button>
{filtered.map((o) => (
- <button key={o.id} type="button" className={`dd-opt${o.id === value && !mixed ? ' on' : ''}`} onClick={() => pick(o.id)}>
+ <button key={o.id} type="button" role="option" aria-selected={o.id === value && !mixed} className={`dd-opt${o.id === value && !mixed ? ' on' : ''}`} onClick={() => pick(o.id)}>
<span className="dd-opt-label">{o.name}</span>
{o.id === value && !mixed && <Check size={12} strokeWidth={2.4} />}
</button>
@@ -422,8 +429,10 @@ function FlagsControl({
: active.length === bits.length && bits.length >= 4
? t('det.everything')
: active.map((o) => prettyLabel(o.label)).join(' | ');
+ const { triggerProps, listProps } = useListbox(pop.isOpen, { multi: true });
const close = () => {
pop.close();
+ trigger.current?.focus();
onEnd?.();
};
const toggle = () => {
@@ -433,7 +442,7 @@ function FlagsControl({
};
return (
<span className="field dropdown">
- <button ref={trigger} type="button" className="dd-trigger" onMouseDown={(e) => e.stopPropagation()} onClick={toggle}>
+ <button ref={trigger} type="button" className="dd-trigger" {...triggerProps} onMouseDown={(e) => e.stopPropagation()} onClick={toggle}>
<span className={`dd-val${mixed ? ' mixed' : ''}`}>{summary}</span>
<ChevronDown size={12} strokeWidth={2} />
</button>
@@ -449,7 +458,7 @@ function FlagsControl({
</button>
</div>
)}
- <div className="dd-list">
+ <div className="dd-list" {...listProps}>
{bits.map((o) => {
const on = !mixed && (value & o.value) === o.value;
// From a MIXED selection the checkboxes all read empty, so a click sets
@@ -457,7 +466,7 @@ function FlagsControl({
// XORing the primary's mask instead would silently stamp its OTHER bits
// onto the rest of the selection.
return (
- <button key={o.value} type="button" className="dd-opt" onClick={() => onChange(mixed ? o.value : value ^ o.value)}>
+ <button key={o.value} type="button" role="option" aria-selected={on} className="dd-opt" onClick={() => onChange(mixed ? o.value : value ^ o.value)}>
<span className={`fchk${on ? ' on' : ''}`}>{on && <Check size={10} strokeWidth={3.2} />}</span>
<span className="dd-opt-label">{prettyLabel(o.label)}</span>
</button>
@@ -555,7 +564,9 @@ export function BoolControl({
return (
<span
className={`toggle${value ? ' on' : ''}${mixed ? ' mixed' : ''}`}
- role="switch"
+ // `switch` has no tri-state — use `checkbox` when the multi-selection is
+ // mixed so aria-checked="mixed" is valid (matches the component enable box).
+ role={mixed ? 'checkbox' : 'switch'}
aria-checked={mixed ? 'mixed' : value}
tabIndex={0}
onClick={commit}
@@ -970,7 +981,7 @@ export function AssetControl({
onClick={() => info && revealAsset(info.path)}
>
<span className="th">
- {!mixed && assetType === 'texture' && info ? (
+ {!mixed && isImageAsset(assetType as AssetType) && info ? (
<img src={`estella://project/${info.path}`} alt="" draggable={false} />
) : (
<Box size={11} strokeWidth={1.7} />