@eifi1/ui-kit 0.5.0 → 0.6.0

package/src/components/combobox-core.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment, useEffect, useId, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import type {
   ComponentPropsWithoutRef,
@@ -18,6 +18,7 @@ import { type AnchorRect } from "../hooks/use-anchored-rect";
 import { useAnchoredPanel, type AnchoredPanel } from "../hooks/use-anchored-panel";
 import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
 import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { hasMessage, mergeDescribedBy } from "./choice-parts";
 
 export interface ComboOption<V extends string | number> {
   value: V;
@@ -34,15 +35,126 @@ export interface ComboOption<V extends string | number> {
   group?: string;
 }
 
-export interface ComboboxCoreOptions<V extends string | number> {
-  /** Already-loaded options (client-side filtered), also used to resolve labels. */
+/**
+ * Where a combobox's rows come from, and how a query narrows them. Shared by the
+ * trigger pickers ({@link useComboboxCore}) and the inline {@link Autocomplete}, so
+ * the two cannot drift in what a failed lookup or a too-short query does.
+ */
+export interface OptionSourceOptions<V extends string | number> {
+  /** Already-loaded options (client-side filtered unless `filter` is false), also
+   *  used to resolve labels. */
   options?: ComboOption<V>[];
-  /** Async option source, debounced and race-safe; stale responses are ignored. */
+  /** Async option source, debounced and race-safe; stale responses are ignored,
+   *  and a rejection is caught and reported as `failed`. */
   loadOptions?: (query: string) => Promise<ComboOption<V>[]>;
   /** External loading flag, OR-ed with the internal async state. */
   loading?: boolean;
+  /**
+   * Narrow `options` by the query (label/sublabel substring). Default `true`.
+   *
+   * `false` shows `options` exactly as given, in the given order — for a list the
+   * caller has already searched and ranked on a server (Keksdose's geocoder), which a
+   * second, client-side substring filter could only get wrong: a provider that
+   * matches "Bahnhofstr." to "Bahnhofstrasse" is right, and a label filter would
+   * throw that row away.
+   */
+  filter?: boolean;
+  /**
+   * Below this many (trimmed) characters nothing is offered and `loadOptions` is not
+   * called. Default `0` — the pickers list everything on open. Set it for a source
+   * that is costly or rate-limited: one letter against a geocoder matches half a
+   * continent, and a request per opened panel is a request nobody asked for.
+   */
+  minChars?: number;
+  /** Quiet time after the last keystroke before `loadOptions` runs. Default 150 ms. */
+  debounceMs?: number;
+}
+
+export interface OptionSource<V extends string | number> {
+  results: ComboOption<V>[];
+  busy: boolean;
+  /** The last lookup for this query REJECTED. The rows are emptied with it: results
+   *  from an earlier query under a failed one would read as the answer to it. */
+  failed: boolean;
+  /** The query is shorter than `minChars`, so nothing was asked. */
+  tooShort: boolean;
+}
+
+/**
+ * The rows half of a combobox: client-side filtering, or a debounced, race-safe
+ * `loadOptions` with its loading and failure states.
+ *
+ * `active` gates the async side — a closed list asks nothing. Loading is DERIVED
+ * ("the settled answer is for a different query") rather than flagged on in the
+ * effect, so there is no render between a keystroke and the debounce in which an
+ * empty list could claim "No results" for a question still being asked.
+ */
+export function useOptionSource<V extends string | number>({
+  options,
+  loadOptions,
+  loading,
+  filter = true,
+  minChars = 0,
+  debounceMs = 150,
+  query,
+  active,
+}: OptionSourceOptions<V> & { query: string; active: boolean }): OptionSource<V> {
+  const isAsync = typeof loadOptions === "function";
+  const tooShort = query.trim().length < minChars;
+  const [settled, setSettled] = useState<{
+    query: string | null;
+    results: ComboOption<V>[];
+    failed: boolean;
+  }>({ query: null, results: [], failed: false });
+  const loadRef = useRef(loadOptions);
+  useEffect(() => {
+    loadRef.current = loadOptions;
+  });
+  const reqId = useRef(0);
+
+  useEffect(() => {
+    // Bumped even when nothing is asked, so a request still in flight from a longer
+    // query cannot land after the user has deleted back below `minChars`.
+    const id = ++reqId.current;
+    if (!active || !isAsync || tooShort) return;
+    const t = setTimeout(
+      async () => {
+        try {
+          const r = await loadRef.current!(query);
+          if (reqId.current === id) setSettled({ query, results: r, failed: false });
+        } catch {
+          // The one path the old `try/finally` had no answer for: the list kept the
+          // previous query's rows and said nothing (Keksdose proposal §2).
+          if (reqId.current === id) setSettled({ query, results: [], failed: true });
+        }
+      },
+      query ? debounceMs : 0,
+    );
+    return () => clearTimeout(t);
+  }, [query, active, isAsync, tooShort, debounceMs]);
+
+  const clientResults = useMemo(() => {
+    if (isAsync) return [];
+    const src = options ?? [];
+    const q = query.trim().toLowerCase();
+    if (!filter || !q) return src;
+    return src.filter(
+      (o) => o.label.toLowerCase().includes(q) || (o.sublabel ?? "").toLowerCase().includes(q),
+    );
+  }, [isAsync, options, query, filter]);
+
+  const pending = isAsync && active && !tooShort && settled.query !== query;
+  const failed = isAsync && !tooShort && settled.failed;
+  return {
+    results: tooShort ? [] : isAsync ? (failed ? [] : settled.results) : clientResults,
+    busy: Boolean(loading) || pending,
+    failed: failed && !pending,
+    tooShort,
+  };
 }
 
+export type ComboboxCoreOptions<V extends string | number> = OptionSourceOptions<V>;
+
 export interface ComboboxCore<V extends string | number> {
   triggerRef: RefObject<HTMLButtonElement | null>;
   panelRef: RefObject<HTMLDivElement | null>;
@@ -55,6 +167,10 @@ export interface ComboboxCore<V extends string | number> {
   setActive: Dispatch<SetStateAction<number>>;
   results: ComboOption<V>[];
   busy: boolean;
+  /** See {@link OptionSource}. */
+  failed: boolean;
+  tooShort: boolean;
+  minChars: number;
   rect: AnchorRect | null;
   /** Where the dropdown goes, clamped to the visible viewport (feedback #135). */
   placement: AnchoredPanel;
@@ -75,8 +191,8 @@ export interface ComboboxCore<V extends string | number> {
  */
 export function useComboboxCore<V extends string | number>({
   options,
-  loadOptions,
-  loading,
+  minChars = 0,
+  ...source
 }: ComboboxCoreOptions<V>): ComboboxCore<V> {
   const triggerRef = useRef<HTMLButtonElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
@@ -85,13 +201,6 @@ export function useComboboxCore<V extends string | number>({
   const [query, setQuery] = useState("");
   const [active, setActive] = useState(0);
 
-  const isAsync = typeof loadOptions === "function";
-  const [asyncResults, setAsyncResults] = useState<ComboOption<V>[]>([]);
-  const [asyncLoading, setAsyncLoading] = useState(false);
-  const loadRef = useRef(loadOptions);
-  loadRef.current = loadOptions;
-  const reqId = useRef(0);
-
   const close = () => setOpen(false);
   // Escape unmounts the panel the user is typing in; without this the browser drops
   // focus on <body>, so the caret disappears and the next Tab restarts at the top of
@@ -131,35 +240,15 @@ export function useComboboxCore<V extends string | number>({
     return () => cancelAnimationFrame(id);
   }, [open]);
 
-  // Debounced, race-safe async search (only when loadOptions is provided).
-  useEffect(() => {
-    if (!open || !isAsync) return;
-    const id = ++reqId.current;
-    setAsyncLoading(true);
-    const run = async () => {
-      try {
-        const r = await loadRef.current!(query);
-        if (reqId.current === id) setAsyncResults(r);
-      } finally {
-        if (reqId.current === id) setAsyncLoading(false);
-      }
-    };
-    const t = setTimeout(run, query ? 150 : 0);
-    return () => clearTimeout(t);
-  }, [query, open, isAsync]);
-
-  const clientResults = useMemo(() => {
-    if (isAsync) return [];
-    const src = options ?? [];
-    const q = query.trim().toLowerCase();
-    if (!q) return src;
-    return src.filter(
-      (o) => o.label.toLowerCase().includes(q) || (o.sublabel ?? "").toLowerCase().includes(q),
-    );
-  }, [isAsync, options, query]);
-
-  const results = isAsync ? asyncResults : clientResults;
-  const busy = Boolean(loading) || (isAsync && asyncLoading);
+  // Debounced, race-safe async search (only when loadOptions is provided) or the
+  // client-side filter — see {@link useOptionSource}.
+  const { results, busy, failed, tooShort } = useOptionSource<V>({
+    ...source,
+    options,
+    minChars,
+    query,
+    active: open,
+  });
 
   // Accumulate every option we've seen so a selected value can render its label
   // even after the async list has moved on to other query results.
@@ -188,6 +277,9 @@ export function useComboboxCore<V extends string | number>({
     setActive,
     results,
     busy,
+    failed,
+    tooShort,
+    minChars,
     rect,
     placement,
     cacheRef,
@@ -196,6 +288,45 @@ export function useComboboxCore<V extends string | number>({
   };
 }
 
+/** The error line under a field — the same type as `ui.tsx`'s (module-private) one,
+ *  so a combobox's message is indistinguishable from an Input's. */
+const FIELD_ERROR_CLASS = "mt-1 text-[11px] leading-tight text-[var(--danger)]";
+
+/**
+ * {@link Input}'s `error` for the combobox family: the message under the field, its
+ * id on the control's `aria-describedby` (merged, never replacing — the hint the
+ * caller pointed at stays first), and `invalid` implied. ui.tsx's `useFieldError` is
+ * module-private, so this restates it on the same rules `choice-parts.ts` does.
+ */
+export function useComboboxFieldError(
+  error: ReactNode,
+  invalid: boolean | undefined,
+  describedBy?: string,
+) {
+  const errorId = useId();
+  const has = hasMessage(error);
+  return {
+    isInvalid: Boolean(invalid) || has,
+    describedBy: mergeDescribedBy(describedBy, has && errorId),
+    errorEl: has ? (
+      <p id={errorId} className={FIELD_ERROR_CLASS}>
+        {error}
+      </p>
+    ) : null,
+  };
+}
+
+/** The anchored suggestion list's box and rows — one look for {@link Combobox},
+ *  {@link InlineEntityCombobox} and {@link Autocomplete}. */
+export const SUGGESTION_LIST_CLASS =
+  "max-h-64 overflow-y-auto rounded-md border border-[var(--border)] bg-[var(--bg-surface)] py-1 shadow-lg";
+
+export const suggestionRowClass = (isActive: boolean) =>
+  cn(
+    "block w-full truncate px-3 py-1.5 text-left text-sm text-[var(--text-primary)]",
+    isActive ? "bg-[var(--bg-active)]" : "hover:bg-[var(--bg-hover)]",
+  );
+
 /**
  * Keep the option the keyboard is on inside the visible part of the list.
  *
@@ -236,6 +367,8 @@ export interface ComboboxPanelProps<V extends string | number>
    *  desktop, where the panel sits under the field that already says it. */
   sheetTitle?: ReactNode;
   closeLabel?: string;
+  /** Default: `combobox.loadError` from the {@link UiKitProvider}, else English. */
+  loadErrorLabel?: string;
 }
 
 /**
@@ -277,6 +410,7 @@ export function ComboboxPanel<V extends string | number>({
   createContent,
   sheetTitle,
   closeLabel,
+  loadErrorLabel,
   className,
   style,
   ...rest
@@ -290,6 +424,8 @@ export function ComboboxPanel<V extends string | number>({
     setQuery,
     results,
     busy,
+    failed,
+    tooShort,
     active,
     setActive,
     closeToTrigger,
@@ -337,6 +473,51 @@ export function ComboboxPanel<V extends string | number>({
     }
   };
 
+  // What the list holds, said in ONE place that is both on screen and a polite
+  // live region. Focus stays in the search box, so the list changing under it was
+  // silent — a reader typed and heard nothing back, and a failed lookup was the same
+  // silence as a slow one. Outside the listbox, which may own only options.
+  //
+  // Three different empties, and only one of them is "nothing matched": a lookup
+  // that failed must not claim there is nothing to find, and a query under
+  // `minChars` was never asked. With rows showing, the count is for the reader only.
+  const message: ReactNode =
+    busy && results.length === 0 ? (
+      // The ellipsis is the picture; the words are for a reader, who otherwise met
+      // an empty-looking list with a lone "…" in it — or, in most readers, nothing
+      // at all, since punctuation alone is skipped.
+      <>
+        <span aria-hidden>…</span>
+        <span className="sr-only">{labels.loading}</span>
+      </>
+    ) : !busy && results.length === 0 && !showCreate ? (
+      failed ? (
+        (loadErrorLabel ?? labels.loadError)
+      ) : tooShort ? (
+        labels.minChars(core.minChars)
+      ) : (
+        (emptyLabel ?? labels.noResults)
+      )
+    ) : null;
+  // `relative` so the sr-only text has a local containing block (see
+  // sr-only-containment.test).
+  const announcement = (
+    <div
+      role="status"
+      aria-live="polite"
+      className={cn(
+        "relative",
+        message !== null && cn("py-2 text-sm", isPhone ? "px-4" : "px-3"),
+        failed ? "text-[var(--danger)]" : "text-[var(--text-muted)]",
+      )}
+    >
+      {message ??
+        (results.length > 0 && (
+          <span className="sr-only">{labels.resultCount(results.length)}</span>
+        ))}
+    </div>
+  );
+
   if (!core.open || typeof document === "undefined") return null;
 
   const list = (
@@ -346,21 +527,6 @@ export function ComboboxPanel<V extends string | number>({
       aria-multiselectable={multi}
       className={cn("min-h-0 flex-1 overflow-y-auto py-1", isPhone && "flex-none")}
     >
-      {busy && results.length === 0 && (
-        // The ellipsis is the picture; the words are for a reader, who otherwise met
-        // an empty-looking list with a lone "…" in it — or, in most readers, nothing
-        // at all, since punctuation alone is skipped. `relative` so the sr-only text
-        // has a local containing block (see sr-only-containment.test).
-        <li className="relative px-3 py-2 text-sm text-[var(--text-muted)]">
-          <span aria-hidden>…</span>
-          <span className="sr-only">{labels.loading}</span>
-        </li>
-      )}
-      {!busy && results.length === 0 && !showCreate && (
-        <li className="px-3 py-2 text-sm text-[var(--text-muted)]">
-          {emptyLabel ?? labels.noResults}
-        </li>
-      )}
       {results.map((o, i) => {
         const selected = isSelected(o.value);
         // One heading per group rather than a grey suffix on every row (#136), and
@@ -488,7 +654,10 @@ export function ComboboxPanel<V extends string | number>({
         inputRef={inputRef}
         closeLabel={closeLabel}
       >
-        <div onKeyDown={onKeyDown}>{list}</div>
+        <div onKeyDown={onKeyDown} className="relative">
+          {list}
+          {announcement}
+        </div>
       </PickerSheet>
     );
   }
@@ -534,6 +703,7 @@ export function ComboboxPanel<V extends string | number>({
       {/* One list, two containers: the desktop panel and the phone sheet render
           the same rows through the same handlers (live #200). */}
       {list}
+      {announcement}
     </div>,
     document.body,
   );

package/src/components/combobox.tsx

@@ -8,13 +8,19 @@ import { useDropdown } from "./dropdown";
 import { useAnchoredPanel } from "../hooks/use-anchored-panel";
 import { useMediaQuery } from "../hooks/use-media-query";
 import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet";
-import { useActiveOptionScroll, type ComboOption } from "./combobox-core";
+import {
+  SUGGESTION_LIST_CLASS,
+  suggestionRowClass,
+  useActiveOptionScroll,
+  useComboboxFieldError,
+  type ComboOption,
+} from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels";
 
 // One look for both combobox flavors below — the suggestion list and its rows
-// must stay pixel-identical between the free-text and the id-keyed variant.
-const LIST_CLASS =
-  "max-h-64 overflow-y-auto rounded-md border border-[var(--border)] bg-[var(--bg-surface)] py-1 shadow-lg";
+// must stay pixel-identical between the free-text and the id-keyed variant (and
+// `Autocomplete`, which shares them from the core).
+const LIST_CLASS = SUGGESTION_LIST_CLASS;
 
 /**
  * "This focus came from a mouse button that is not the left one" — for the two
@@ -105,11 +111,7 @@ function SuggestionList({
   );
 }
 
-const rowClass = (isActive: boolean) =>
-  cn(
-    "block w-full truncate px-3 py-1.5 text-left text-sm text-[var(--text-primary)]",
-    isActive ? "bg-[var(--bg-active)]" : "hover:bg-[var(--bg-hover)]",
-  );
+const rowClass = suggestionRowClass;
 
 /**
  * Four of the div's own attributes are omitted because this component already owns
@@ -133,6 +135,14 @@ export interface ComboboxProps
    *  delete the `[&_input]:…` copy of {@link FIELD_INVALID} it had been carrying
    *  because this component had no `invalid` of its own. */
   invalid?: boolean;
+  /** What is wrong with the value, as {@link Input}'s `error`: rendered under the
+   *  field, on the `<input>`'s `aria-describedby`, and implies `invalid` (lenkbank's
+   *  scope fields, which moved here off `<Input list>` + `<datalist>`). */
+  error?: ReactNode;
+  /** As `<input disabled>`: no focus, no list, the field's settled look. The chevron
+   *  stops toggling with it — it is a mouse target the input's own `disabled` does
+   *  not reach. */
+  disabled?: boolean;
   /** Heading an option belongs under. Supplying it makes this list read exactly
    *  like {@link InlineEntityCombobox}'s — one heading per group with its rows
    *  indented beneath — instead of a flat list (feedback #136 rework: the payee
@@ -211,6 +221,8 @@ export function Combobox({
   closeLabel,
   createLabel,
   invalid,
+  error,
+  disabled,
   optionAdornment,
   autoFocus,
   onBlur,
@@ -218,6 +230,7 @@ export function Combobox({
   "aria-label": ariaLabel,
   ...rest
 }: ComboboxProps) {
+  const field = useComboboxFieldError(error, invalid);
   const generated = useId();
   const fieldId = id ?? generated;
   // Derived from the GENERATED id, never from `id`: a caller's id is theirs to
@@ -373,8 +386,10 @@ export function Combobox({
           aria-controls={listboxId}
           aria-activedescendant={activeId}
           aria-autocomplete="list"
-          aria-invalid={invalid || undefined}
+          aria-invalid={field.isInvalid || undefined}
+          aria-describedby={field.describedBy}
           autoComplete="off"
+          disabled={disabled}
           autoFocus={autoFocus}
           onBlur={onBlur}
           onMouseDown={primaryOnly.onMouseDown}
@@ -444,21 +459,30 @@ export function Combobox({
             // the desktop list is capped at 8 rows — so jumping it would be worth
             // almost nothing and would cost the one gesture that field is used with.
           }}
-          className={cn(FIELD_BASE, label !== undefined && FIELD_FLOATING_PAD, "pr-9", invalid && FIELD_INVALID)}
+          className={cn(
+            FIELD_BASE,
+            label !== undefined && FIELD_FLOATING_PAD,
+            "pr-9",
+            field.isInvalid && FIELD_INVALID,
+          )}
         />
         <ChevronDown
           aria-hidden
           onMouseDown={(e) => {
             // Toggle on the chevron without stealing focus from the input.
             e.preventDefault();
-            setOpen((o) => !o);
+            if (!disabled) setOpen((o) => !o);
           }}
-          className="absolute right-2.5 top-1/2 size-4 -translate-y-1/2 cursor-pointer text-[var(--text-placeholder)]"
+          className={cn(
+            "absolute right-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]",
+            disabled ? "opacity-50" : "cursor-pointer",
+          )}
         />
       </div>
+      {field.errorEl}
       {isPhone && (
         <PickerSheet
-          open={open}
+          open={open && !disabled}
           onClose={() => setOpen(false)}
           title={label}
           // The sheet's input IS the field: this is a free-text control, so what is
@@ -523,7 +547,7 @@ export function Combobox({
           </ul>
         </PickerSheet>
       )}
-      {!isPhone && open && (matches.length > 0 || createRow) && (
+      {!isPhone && open && !disabled && (matches.length > 0 || createRow) && (
         <SuggestionList id={listboxId} anchorRef={fieldRef} panelRef={panelRef}>
           {createRow && (
             <li role="presentation">
@@ -609,6 +633,8 @@ export interface InlineEntityComboboxProps<V extends string | number>
   value: V | null;
   /** Required and unanswered — see {@link Combobox}'s `invalid`. */
   invalid?: boolean;
+  /** What is wrong with the value — see {@link Combobox}'s `error`. */
+  error?: ReactNode;
   /** A picked/typed option emits its id; emptying the field emits `null`. */
   onChange: (v: V | null) => void;
   options: ComboOption<V>[];
@@ -676,9 +702,11 @@ export function InlineEntityCombobox<V extends string | number>({
   clearable,
   clearLabel,
   invalid,
+  error,
   "aria-label": ariaLabel,
   ...rest
 }: InlineEntityComboboxProps<V>) {
+  const field = useComboboxFieldError(error, invalid);
   const generated = useId();
   const fieldId = id ?? generated;
   // See the twin above on why these hang off the generated id.
@@ -816,7 +844,8 @@ export function InlineEntityCombobox<V extends string | number>({
           aria-controls={listboxId}
           aria-activedescendant={activeId}
           aria-autocomplete="list"
-          aria-invalid={invalid || undefined}
+          aria-invalid={field.isInvalid || undefined}
+          aria-describedby={field.describedBy}
           autoComplete="off"
           disabled={disabled}
           autoFocus={autoFocus}
@@ -875,7 +904,12 @@ export function InlineEntityCombobox<V extends string | number>({
             // Home/End stay with the caret — see the note in {@link Combobox}: this
             // field is editable, and its text is what `reconcile` judges.
           }}
-          className={cn(FIELD_BASE, label !== undefined && FIELD_FLOATING_PAD, "pr-9", invalid && FIELD_INVALID)}
+          className={cn(
+            FIELD_BASE,
+            label !== undefined && FIELD_FLOATING_PAD,
+            "pr-9",
+            field.isInvalid && FIELD_INVALID,
+          )}
         />
         {showClear ? (
           <button
@@ -906,9 +940,11 @@ export function InlineEntityCombobox<V extends string | number>({
           <ChevronDown
             aria-hidden
             onMouseDown={(e) => {
-              // Toggle on the chevron without stealing focus from the input.
+              // Toggle on the chevron without stealing focus from the input — and
+              // not at all on a disabled field, which the input's own `disabled`
+              // does not stop from here.
               e.preventDefault();
-              setOpen((o) => !o);
+              if (!disabled) setOpen((o) => !o);
             }}
             className={cn(
               "absolute right-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]",
@@ -917,9 +953,10 @@ export function InlineEntityCombobox<V extends string | number>({
           />
         )}
       </div>
+      {field.errorEl}
       {isPhone && (
         <PickerSheet
-          open={open}
+          open={open && !disabled}
           // Closing without choosing keeps the value: `text` was never emptied, so
           // reconcile has nothing to undo — it just puts the label back.
           onClose={reconcile}
@@ -966,7 +1003,7 @@ export function InlineEntityCombobox<V extends string | number>({
           </ul>
         </PickerSheet>
       )}
-      {!isPhone && open && matches.length > 0 && (
+      {!isPhone && open && !disabled && matches.length > 0 && (
         <SuggestionList id={listboxId} anchorRef={fieldRef} panelRef={panelRef}>
           {matches.map((o, i) => (
             // A group heading is emitted at each group boundary rather than repeating

package/src/components/currency-select.tsx

@@ -4,7 +4,12 @@ import { Check } from "lucide-react";
 import { FieldChevron, FieldLabel, FIELD_TRIGGER, FIELD_INVALID, FIELD_FLOATING_PAD } from "./ui";
 import { cn } from "../lib/cn";
 import { DropdownPanel, DropdownSearchHeader, useDropdownSearch } from "./dropdown";
-import { DEFAULT_CURRENCY_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import {
+  DEFAULT_COMMON_LABELS,
+  DEFAULT_CURRENCY_LABELS,
+  useKitLabels,
+  useKitLocale,
+} from "../i18n/kit-labels";
 
 export interface CurrencyOption {
   code: string;
@@ -159,6 +164,7 @@ export function CurrencySelect({
   const { open, setOpen, wrapperRef, query, setQuery, inputRef } = useDropdownSearch();
   // `labels` > `currency` from the provider > English.
   const text = useKitLabels("currency", DEFAULT_CURRENCY_LABELS, labels);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
   const locale = useKitLocale();
 
   const selected = getCurrency(value);
@@ -180,6 +186,14 @@ export function CurrencySelect({
 
   const listboxId = `${useId()}-listbox`;
 
+  // The trigger's NAME. A combobox does not take its name from its content, and the
+  // floating label is a <span>, not a <label for> — so without `aria-label` from the
+  // caller this trigger had no name at all (keksdose's test suite, 0.5.0). Composed the
+  // way MultiSelect and the entity comboboxes compose theirs, "label: value", with the
+  // `currency` word standing in for a missing label so it is never nameless.
+  const fieldName = typeof label === "string" ? label : text.currency;
+  const name = ariaLabel ?? common.fieldValue(fieldName, selected ? selected.code : (placeholder ?? text.currency));
+
   return (
     // The wrapper takes `rest`; the trigger takes the name. This field's label is a
     // floating <span> rather than a <label for>, so a caller who wants the control to
@@ -188,7 +202,7 @@ export function CurrencySelect({
       {label !== undefined && <FieldLabel>{label}</FieldLabel>}
       <button
         type="button"
-        aria-label={ariaLabel}
+        aria-label={name}
         onClick={() => setOpen((v) => !v)}
         // The implicit `button` role supports neither `aria-expanded` nor
         // `aria-invalid`, so this trigger previously wore a red border and announced