@bytebrand/fe-ui-core-autobahn 1.0.127 → 1.0.130

package/ui/Dropdown.tsx

@@ -1,461 +1,467 @@
-// Autobahn (auto.de redesign) — md3 single-select dropdown.
-//
-// A real, themeable replacement for the native HTML `<select>`. The browser renders
-// a native `<select>`'s option list with the OS popup, which CANNOT be styled (it
-// ignores the scoped `.md3` theme and reads as "broken"/un-md3). This component
-// reproduces the control as a button trigger (`.mselect-btn`, styled like `.mfield`)
-// plus an absolutely-positioned `.mcard`-style popover menu we fully control.
-//
-// Behaviour parity with a real select:
-//   - controlled: `value` + `options` ({value,label,disabled?}) + `onChange(value)`.
-//   - keyboard: ↓/Enter/Space open; ↑/↓ move the active option; Enter selects;
-//     Esc / Tab close (Esc refocuses the trigger); Home/End jump.
-//   - click-away (document mousedown) closes; the active option scrolls into view.
-//   - a11y: trigger `aria-haspopup=listbox` + `aria-expanded`; menu `role=listbox`;
-//     options `role=option` + `aria-selected`; `aria-activedescendant` tracks focus.
-//
-// Pure/presentational — no store/API/window beyond the click-away listener (guarded
-// for SSR). Renders correctly only inside a `<div className="md3">` subtree.
-
-import React from 'react';
-import * as ReactDOM from 'react-dom';
-
-import Icon from './Icon';
-import { usePortalMenuPosition } from './usePortalMenuPosition';
-
-export interface DropdownOption {
-  value: string;
-  label: string;
-  disabled?: boolean;
-}
-
-export interface DropdownProps {
-  /** currently selected option value. */
-  value: string;
-  /** the selectable options, in display order. */
-  options: DropdownOption[];
-  /** fired with the chosen option's value. */
-  onChange: (value: string) => void;
-  /** shown (muted) when `value` matches no option. */
-  placeholder?: string;
-  /** leading lucide icon (kebab-case), e.g. 'arrow-up-down'. */
-  icon?: string;
-  disabled?: boolean;
-  /** full-width trigger (default true for form fields; pass false for inline controls). */
-  block?: boolean;
-  /** compact height (sort bar / inline). */
-  size?: 'sm' | 'md';
-  /** accessible label when there is no visible <label> wrapping the control. */
-  ariaLabel?: string;
-  /** marks the trigger aria-invalid (screen readers) when the owning field has a validation
-   *  error — purely additive/opt-in, undefined by default so existing callers are unaffected. */
-  ariaInvalid?: boolean;
-  /** id of the (possibly visually-hidden) error text describing why the field is invalid. */
-  ariaDescribedBy?: string;
-  /** extra class on the wrapper (e.g. 'srp-sort' for width rules). */
-  className?: string;
-  /** align the popover to the right edge of the trigger (default left). */
-  menuAlign?: 'left' | 'right';
-  /** show a text input at the top of the popover that filters `options` by label (substring, case-insensitive). */
-  searchable?: boolean;
-  /** placeholder for the search input (only used when `searchable`). */
-  searchPlaceholder?: string;
-  /** restrict the combobox input to digits (numeric "up to" fields) — filters every keystroke and sets inputMode="numeric" pattern="[0-9]*". Requires `searchable`. */
-  numeric?: boolean;
-  /** allow committing a typed value that matches no option, instead of only ever allowing an exact pick from the list — for numeric "up to" fields where any amount is valid, not just the preset rungs. Committed on close (blur/Tab/click-away/Enter), not on every keystroke. Requires `searchable`. */
-  allowCustomValue?: boolean;
-  /** renders the closed-trigger label for a custom (non-list) value. Falls back to the raw value itself when omitted — pass this whenever `allowCustomValue` so the trigger reads naturally (e.g. `(v) => \`bis ${v} km\``). */
-  formatCustomLabel?: (value: string) => string;
-  /**
-   * Render the popover into a `document.body` portal instead of nesting it in place — escapes an
-   * ancestor's `overflow:hidden`/clipping (e.g. inside a collapsing Accordion region, see
-   * `.macc-region-inner` in md3.css) that would otherwise cut the option list off instead of
-   * letting it float over the following content. Position is computed from the trigger's on-screen
-   * rect, kept in sync on scroll/resize while open, and flips to open ABOVE the trigger when
-   * there isn't room below. Off by default — every existing caller keeps the simple in-place
-   * popover; opt in only at call sites with a known clipping ancestor.
-   */
-  menuPortal?: boolean;
-}
-
-const Dropdown: React.FunctionComponent<DropdownProps> = ({
-  value,
-  options,
-  onChange,
-  placeholder,
-  icon,
-  disabled = false,
-  block = true,
-  size = 'md',
-  ariaLabel,
-  ariaInvalid,
-  ariaDescribedBy,
-  className,
-  menuAlign = 'left',
-  searchable = false,
-  searchPlaceholder,
-  numeric = false,
-  allowCustomValue = false,
-  formatCustomLabel,
-  menuPortal = false,
-}) => {
-  const [open, setOpen] = React.useState(false);
-  const [activeIndex, setActiveIndex] = React.useState(-1);
-  const [query, setQuery] = React.useState('');
-  const rootRef = React.useRef<HTMLDivElement | null>(null);
-  const btnRef = React.useRef<HTMLButtonElement | null>(null);
-  const menuRef = React.useRef<HTMLUListElement | null>(null);
-  const searchRef = React.useRef<HTMLInputElement | null>(null);
-  // stable id base for aria-activedescendant (avoids Math.random / Date.now, which are unavailable).
-  const idBase = React.useMemo(() => `mselect-${Math.round(value ? value.length : 0)}-`, [value]);
-
-  const selectedIndex = options.findIndex((o) => o.value === value);
-  const selected = selectedIndex !== -1 ? options[selectedIndex] : undefined;
-  // a real value that just doesn't happen to match any option — only possible with
-  // allowCustomValue (e.g. a hand-typed "1421232" the preset rungs don't cover).
-  const customLabel = allowCustomValue && value && !selected
-    ? (formatCustomLabel ? formatCustomLabel(value) : value)
-    : undefined;
-  const hasValue = !!selected || customLabel !== undefined;
-
-  const filteredOptions = React.useMemo(() => {
-    if (!searchable || !query.trim()) return options;
-    const q = query.trim().toLowerCase();
-    const matches = options.filter((o) => o.label.toLowerCase().includes(q));
-    // some option lists intentionally repeat entries across groups while closed (e.g. a "Top
-    // Marken" shortlist followed by the FULL "Alle Marken" list, which includes those same top
-    // brands again) — harmless when browsing both sections, but shows the same match twice while
-    // searching. Keep only the first occurrence of each label once the user is actually filtering.
-    const seen = new Set<string>();
-    return matches.filter((o) => {
-      const key = o.label.toLowerCase();
-      if (seen.has(key)) return false;
-      seen.add(key);
-      return true;
-    });
-  }, [searchable, query, options]);
-
-  // deferred: when searchable, the trigger <button> is swapped out for an <input> while
-  // open (see render), so btnRef.current is null *during* the close() call itself — the
-  // button only exists again after this state flips `open` back to false and React
-  // re-renders. Consumed by the effect below, once that re-render has actually happened.
-  const focusTriggerAfterClose = React.useRef(false);
-
-  // close + restore focus to the trigger. `commitTyped` (default true) commits whatever's
-  // currently typed as a custom value when `allowCustomValue` — this is what makes "just leave
-  // the field" (blur/click-away/Tab) work, not only an explicit pick from the list. Callers that
-  // already committed an explicit option (commit()) or that are cancelling (Escape) pass false.
-  const close = React.useCallback((focusTrigger: boolean, commitTyped: boolean = true) => {
-    if (allowCustomValue && commitTyped) {
-      const raw = query.trim();
-      if (raw !== value) onChange(raw);
-    }
-    setOpen(false);
-    setActiveIndex(-1);
-    setQuery('');
-    focusTriggerAfterClose.current = focusTrigger;
-  }, [allowCustomValue, query, value, onChange]);
-
-  React.useEffect(() => {
-    if (!open && focusTriggerAfterClose.current) {
-      focusTriggerAfterClose.current = false;
-      if (btnRef.current) btnRef.current.focus();
-    }
-  }, [open]);
-
-  const openMenu = React.useCallback(() => {
-    if (disabled) return;
-    setOpen(true);
-    // start the keyboard highlight on the current selection (or the first option).
-    setActiveIndex(selectedIndex !== -1 ? selectedIndex : 0);
-    // pre-fill the combobox with the current value (raw, not the formatted label) so a custom
-    // entry can be edited/replaced in place instead of always starting from a blank field.
-    if (allowCustomValue) setQuery(value || '');
-  }, [disabled, selectedIndex, allowCustomValue, value]);
-
-  // when opened searchable, focus the search input instead of leaving focus on the trigger.
-  // scrollIntoView first: on mobile the keyboard is about to eat ~40% of the viewport, so the
-  // trigger (and the popover below it) needs to already be scrolled above the fold before focus
-  // fires, or the popover can end up hidden behind the keyboard with no way to see it open.
-  React.useEffect(() => {
-    if (!open || !searchable) return;
-    if (rootRef.current && rootRef.current.scrollIntoView) {
-      rootRef.current.scrollIntoView({ block: 'center', behavior: 'smooth' });
-    }
-    if (searchRef.current) {
-      searchRef.current.focus();
-      // pre-filled custom value (see openMenu) starts selected, so typing immediately
-      // replaces it instead of appending — same "click a number field, type over it" feel.
-      if (allowCustomValue) searchRef.current.select();
-    }
-  }, [open, searchable, allowCustomValue]);
-
-  // click-away (guarded for SSR). menuElRef is checked too — with menuPortal the popover renders
-  // outside rootRef (at document.body), so without this every option click would look like a
-  // click-away and close the menu before the option's own onClick had a chance to fire.
-  React.useEffect(() => {
-    if (!open || typeof document === 'undefined') return undefined;
-    const onDocMouseDown = (e: MouseEvent) => {
-      const target = e.target as Node;
-      if (rootRef.current && rootRef.current.contains(target)) return;
-      if (menuElRef.current && menuElRef.current.contains(target)) return;
-      close(false);
-    };
-    document.addEventListener('mousedown', onDocMouseDown);
-    return () => document.removeEventListener('mousedown', onDocMouseDown);
-  }, [open, close]);
-
-  // menuPortal: body-portal root + trigger-relative position, tracked on scroll/resize, flipping
-  // above the trigger when there isn't room below. Shared with MultiDropdown's checklist menu
-  // below — see usePortalMenuPosition's own doc comment for the full reasoning (every timing/CSS
-  // fix that went into this belongs in one place so the two consumers can't drift apart).
-  const onCloseAway = React.useCallback(() => close(false, false), [close]);
-  const { portalRoot, menuPos, menuElRef } = usePortalMenuPosition({
-    enabled: menuPortal,
-    open,
-    rootRef,
-    menuAlign,
-    onCloseAway,
-  });
-
-  // keep the active option scrolled into view while navigating by keyboard.
-  React.useEffect(() => {
-    if (!open || activeIndex < 0 || !menuRef.current) return;
-    const el = menuRef.current.children[activeIndex] as HTMLElement | undefined;
-    if (el && el.scrollIntoView) el.scrollIntoView({ block: 'nearest' });
-  }, [open, activeIndex]);
-
-  // reset the keyboard highlight to the top match whenever the filtered list changes.
-  React.useEffect(() => {
-    if (searchable && open) setActiveIndex(filteredOptions.length ? 0 : -1);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [filteredOptions]);
-
-  const commit = (idx: number) => {
-    const opt = filteredOptions[idx];
-    if (!opt || opt.disabled) return;
-    onChange(opt.value);
-    // false: the explicit pick already won — don't also commit whatever's still sitting in the
-    // (now-stale) typed query behind it.
-    close(true, false);
-  };
-
-  // move the active highlight, skipping disabled options.
-  const move = (dir: 1 | -1) => {
-    if (!filteredOptions.length) return;
-    let i = activeIndex;
-    for (let step = 0; step < filteredOptions.length; step += 1) {
-      i = (i + dir + filteredOptions.length) % filteredOptions.length;
-      if (!filteredOptions[i].disabled) {
-        setActiveIndex(i);
-        return;
-      }
-    }
-  };
-
-  const onMenuKeyDown = (e: React.KeyboardEvent) => {
-    switch (e.key) {
-      case 'ArrowDown': e.preventDefault(); move(1); break;
-      case 'ArrowUp': e.preventDefault(); move(-1); break;
-      case 'Home': e.preventDefault(); setActiveIndex(filteredOptions.findIndex((o) => !o.disabled)); break;
-      case 'End': e.preventDefault(); for (let i = filteredOptions.length - 1; i >= 0; i -= 1) { if (!filteredOptions[i].disabled) { setActiveIndex(i); break; } } break;
-      case 'Enter':
-        e.preventDefault();
-        // an active list match wins when there is one; otherwise, for allowCustomValue fields,
-        // Enter commits whatever's typed (same value close() would commit on blur anyway).
-        if (activeIndex >= 0) commit(activeIndex);
-        else if (allowCustomValue) close(true);
-        break;
-      // Escape cancels — close(..., false) so an in-progress custom edit is discarded, not committed.
-      case 'Escape': e.preventDefault(); close(true, false); break;
-      case 'Tab': close(false); break;
-      default: break;
-    }
-  };
-
-  const onTriggerKeyDown = (e: React.KeyboardEvent) => {
-    if (disabled) return;
-    if (!open) {
-      if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' || e.key === ' ') {
-        e.preventDefault();
-        openMenu();
-      }
-      return;
-    }
-    if (e.key === ' ') { e.preventDefault(); if (activeIndex >= 0) commit(activeIndex); return; }
-    onMenuKeyDown(e);
-  };
-
-  const wrapCls = ['mselect'];
-  if (size === 'sm') wrapCls.push('mselect--sm');
-  if (block) wrapCls.push('mselect--block');
-  if (className) wrapCls.push(className);
-
-  const label = selected ? selected.label : (customLabel !== undefined ? customLabel : placeholder || '');
-
-  const editing = searchable && open;
-
-  // Bug 53/37: "Rate bis" / "km bis" allow a hand-typed amount the preset rungs don't cover
-  // (allowCustomValue) — that typed number never matches any option label, so filteredOptions
-  // comes back empty and the popover would show "Keine Treffer", reading as "no cars match this"
-  // to the customer even though the typed value is perfectly valid input. Once there's an actual
-  // typed query with zero matches on an allowCustomValue field, suppress the popover entirely
-  // (not just the "Keine Treffer" row) — an empty floating box would be just as confusing. Plain
-  // (non-custom) searchable dropdowns, e.g. Make/Model, are unaffected and keep showing it.
-  const suppressEmptyMenu = allowCustomValue && searchable && query.trim() !== '' && filteredOptions.length === 0;
-
-  // shared between the in-place popover and the menuPortal one — identical option list either way.
-  // maxHeight (menuPortal only — see positionMenu) overrides the CSS static 288px cap with the
-  // space actually available in whichever direction the menu opened; inline style wins over the
-  // class rule regardless of specificity, and falls back to the CSS default when omitted (the
-  // in-place, non-portal popover keeps relying on that + whatever ancestor clipping already existed).
-  const renderMenuList = (maxHeight?: number) => (
-    <ul
-      ref={menuRef}
-      id={`${idBase}list`}
-      className="mselect-list"
-      role="listbox"
-      tabIndex={-1}
-      style={maxHeight != null ? { maxHeight } : undefined}
-      aria-activedescendant={activeIndex >= 0 ? `${idBase}${activeIndex}` : undefined}
-    >
-      {filteredOptions.map((opt, i) => (
-        <li key={`${opt.value}_${i}`} role="presentation">
-          <button
-            id={`${idBase}${i}`}
-            type="button"
-            role="option"
-            aria-selected={opt.value === value}
-            disabled={opt.disabled}
-            className={'mselect-opt' + (i === activeIndex ? ' is-active' : '')}
-            onMouseEnter={() => setActiveIndex(i)}
-            onClick={() => commit(i)}
-          >
-            <span className="mselect-opt-label">{opt.label}</span>
-            {opt.value === value && <Icon name="check" size={16} cls="mselect-check" />}
-          </button>
-        </li>
-      ))}
-      {searchable && filteredOptions.length === 0 && (
-        <li className="mselect-empty" role="presentation">Keine Treffer</li>
-      )}
-    </ul>
-  );
-
-  return (
-    <div className={wrapCls.join(' ')} ref={rootRef}>
-      {editing ? (
-        // combobox mode: the trigger itself becomes the text field (not a separate input
-        // inside the popover) — a <button> can't legally contain an <input>, so this is a
-        // <div> standing in for it, same `.mselect-btn` class for identical chrome.
-        <div className="mselect-btn mselect-btn--editing">
-          {icon && <Icon name={icon} />}
-          <input
-            ref={searchRef}
-            type="text"
-            className="mselect-input"
-            placeholder={searchPlaceholder || placeholder}
-            value={query}
-            onChange={(e) => setQuery(numeric ? e.target.value.replace(/\D/g, '') : e.target.value)}
-            onKeyDown={onMenuKeyDown}
-            aria-label={ariaLabel}
-            aria-haspopup="listbox"
-            aria-expanded={open}
-            aria-controls={`${idBase}list`}
-            aria-activedescendant={activeIndex >= 0 ? `${idBase}${activeIndex}` : undefined}
-            aria-invalid={ariaInvalid ? true : undefined}
-            aria-describedby={ariaDescribedBy}
-            {...(numeric ? { inputMode: 'numeric' as const, pattern: '[0-9]*' } : {})}
-          />
-          <button type="button" className="mselect-chev-btn" aria-label="Close" onClick={() => close(true)}>
-            <Icon name="chevron-down" cls="mselect-chev" />
-          </button>
-        </div>
-      ) : (
-        <button
-          ref={btnRef}
-          type="button"
-          className="mselect-btn"
-          aria-haspopup="listbox"
-          aria-expanded={open}
-          aria-label={ariaLabel}
-          aria-invalid={ariaInvalid ? true : undefined}
-          aria-describedby={ariaDescribedBy}
-          disabled={disabled}
-          onClick={() => (open ? close(false) : openMenu())}
-          onKeyDown={onTriggerKeyDown}
-        >
-          {icon && <Icon name={icon} />}
-          <span className={'mselect-label' + (hasValue ? '' : ' mselect-label--ph')}>{label}</span>
-          <Icon name="chevron-down" cls="mselect-chev" />
-        </button>
-      )}
-      {open && !suppressEmptyMenu && (menuPortal && portalRoot
-        ? ReactDOM.createPortal(
-            <div
-              ref={menuElRef}
-              className={'mselect-menu mselect-menu--portal' + (searchable ? ' mselect-menu--searchable' : '')}
-              // menuPos is null for one frame on open, before the position effect has measured
-              // the trigger — stay invisible (not just visually, via `visibility`) rather than
-              // flash at (0,0)/full-width. `position: fixed` is set UNCONDITIONALLY, in both
-              // branches — leaving it out of this fallback used to mean the element briefly
-              // rendered as a normal in-flow block at the end of <body> for that one frame,
-              // which could visibly shift the page's scroll position the instant a dropdown
-              // opened (the block's real height — up to .mselect-list's 288px — briefly counted
-              // toward the document's scrollable height before flipping back out of flow).
-              style={
-                menuPos
-                  ? {
-                      position: 'fixed',
-                      top: menuPos.top,
-                      bottom: menuPos.bottom,
-                      left: menuPos.left,
-                      right: menuPos.right,
-                      width: menuPos.width,
-                      minWidth: menuPos.width,
-                      // Root cause of the "open above" collapse (menuPos.top/left now always a
-                      // concrete number-or-'auto', never omitted — see the menuPos state comment):
-                      // top/bottom (and left/right) here used to leave the unanchored side as
-                      // `undefined`, which React just drops from the inline style rather than
-                      // writing `auto`. With `top` missing from the DOM's inline style, the
-                      // `.mselect-menu` stylesheet rule (`top: calc(100% + 4px)`) filled back in —
-                      // fighting the inline `bottom` we DID set. Both `top` and `bottom` pinned at
-                      // once, with `height` still auto, forces the used height to the distance
-                      // between them (CSS 2.1 §10.6.4), which computed out negative (top landing
-                      // just past the viewport's bottom edge, bottom landing just above the
-                      // trigger) — clamped to 0, leaving only .mselect-menu's own padding+border
-                      // visible (6px*2 + 1px*2 = 14px, exactly the reported near-zero height). The
-                      // `top`-anchored "open below" case never hit this: its inline `top` overrode
-                      // the stylesheet regardless, and `bottom` being class-omitted (not written at
-                      // all, `auto` is the CSS default for `bottom`) matched the intended math.
-                      // With every side now explicitly 'auto' when unused, no stylesheet fallback
-                      // can leak in and `height` is a normal shrink-to-fit-then-clamped-by-maxHeight
-                      // calculation in both directions. This own explicit maxHeight (list's
-                      // maxHeight + .mselect-menu's padding/border, 6px*2 + 1px*2 = 14) still
-                      // matters on top of that fix — box-sizing: border-box means maxHeight here
-                      // must include the padding/border the inner .mselect-list's own maxHeight
-                      // (renderMenuList below) doesn't count, or the list gets squeezed twice.
-                      maxHeight: menuPos.maxHeight + 14,
-                    }
-                  : { position: 'fixed', visibility: 'hidden' }
-              }
-            >
-              {renderMenuList(menuPos?.maxHeight)}
-            </div>,
-            portalRoot,
-          )
-        : (
-          <div
-            ref={menuElRef}
-            className={'mselect-menu' + (menuAlign === 'right' ? ' mselect-menu--right' : '') + (searchable ? ' mselect-menu--searchable' : '')}
-          >
-            {renderMenuList()}
-          </div>
-        )
-      )}
-    </div>
-  );
-};
-
-export default Dropdown;
-
+// Autobahn (auto.de redesign) — md3 single-select dropdown.
+//
+// A real, themeable replacement for the native HTML `<select>`. The browser renders
+// a native `<select>`'s option list with the OS popup, which CANNOT be styled (it
+// ignores the scoped `.md3` theme and reads as "broken"/un-md3). This component
+// reproduces the control as a button trigger (`.mselect-btn`, styled like `.mfield`)
+// plus an absolutely-positioned `.mcard`-style popover menu we fully control.
+//
+// Behaviour parity with a real select:
+//   - controlled: `value` + `options` ({value,label,disabled?}) + `onChange(value)`.
+//   - keyboard: ↓/Enter/Space open; ↑/↓ move the active option; Enter selects;
+//     Esc / Tab close (Esc refocuses the trigger); Home/End jump.
+//   - click-away (document mousedown) closes; the active option scrolls into view.
+//   - a11y: trigger `aria-haspopup=listbox` + `aria-expanded`; menu `role=listbox`;
+//     options `role=option` + `aria-selected`; `aria-activedescendant` tracks focus.
+//
+// Pure/presentational — no store/API/window beyond the click-away listener (guarded
+// for SSR). Renders correctly only inside a `<div className="md3">` subtree.
+
+import React from 'react';
+import * as ReactDOM from 'react-dom';
+
+import Icon from './Icon';
+import { usePortalMenuPosition } from './usePortalMenuPosition';
+
+export interface DropdownOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface DropdownProps {
+  /** currently selected option value. */
+  value: string;
+  /** the selectable options, in display order. */
+  options: DropdownOption[];
+  /** fired with the chosen option's value. */
+  onChange: (value: string) => void;
+  /** shown (muted) when `value` matches no option. */
+  placeholder?: string;
+  /** leading lucide icon (kebab-case), e.g. 'arrow-up-down'. */
+  icon?: string;
+  /** custom leading icon element — takes precedence over `icon` when both are given. For a
+   *  one-off icon that isn't in lucide-react (e.g. a Figma-exported glyph); give it a
+   *  `className="lucide"` so it picks up the same `.mselect-btn .lucide` sizing/color rules
+   *  every named `icon` gets. */
+  iconNode?: React.ReactNode;
+  disabled?: boolean;
+  /** full-width trigger (default true for form fields; pass false for inline controls). */
+  block?: boolean;
+  /** compact height (sort bar / inline). */
+  size?: 'sm' | 'md';
+  /** accessible label when there is no visible <label> wrapping the control. */
+  ariaLabel?: string;
+  /** marks the trigger aria-invalid (screen readers) when the owning field has a validation
+   *  error — purely additive/opt-in, undefined by default so existing callers are unaffected. */
+  ariaInvalid?: boolean;
+  /** id of the (possibly visually-hidden) error text describing why the field is invalid. */
+  ariaDescribedBy?: string;
+  /** extra class on the wrapper (e.g. 'srp-sort' for width rules). */
+  className?: string;
+  /** align the popover to the right edge of the trigger (default left). */
+  menuAlign?: 'left' | 'right';
+  /** show a text input at the top of the popover that filters `options` by label (substring, case-insensitive). */
+  searchable?: boolean;
+  /** placeholder for the search input (only used when `searchable`). */
+  searchPlaceholder?: string;
+  /** restrict the combobox input to digits (numeric "up to" fields) — filters every keystroke and sets inputMode="numeric" pattern="[0-9]*". Requires `searchable`. */
+  numeric?: boolean;
+  /** allow committing a typed value that matches no option, instead of only ever allowing an exact pick from the list — for numeric "up to" fields where any amount is valid, not just the preset rungs. Committed on close (blur/Tab/click-away/Enter), not on every keystroke. Requires `searchable`. */
+  allowCustomValue?: boolean;
+  /** renders the closed-trigger label for a custom (non-list) value. Falls back to the raw value itself when omitted — pass this whenever `allowCustomValue` so the trigger reads naturally (e.g. `(v) => \`bis ${v} km\``). */
+  formatCustomLabel?: (value: string) => string;
+  /**
+   * Render the popover into a `document.body` portal instead of nesting it in place — escapes an
+   * ancestor's `overflow:hidden`/clipping (e.g. inside a collapsing Accordion region, see
+   * `.macc-region-inner` in md3.css) that would otherwise cut the option list off instead of
+   * letting it float over the following content. Position is computed from the trigger's on-screen
+   * rect, kept in sync on scroll/resize while open, and flips to open ABOVE the trigger when
+   * there isn't room below. Off by default — every existing caller keeps the simple in-place
+   * popover; opt in only at call sites with a known clipping ancestor.
+   */
+  menuPortal?: boolean;
+}
+
+const Dropdown: React.FunctionComponent<DropdownProps> = ({
+  value,
+  options,
+  onChange,
+  placeholder,
+  icon,
+  iconNode,
+  disabled = false,
+  block = true,
+  size = 'md',
+  ariaLabel,
+  ariaInvalid,
+  ariaDescribedBy,
+  className,
+  menuAlign = 'left',
+  searchable = false,
+  searchPlaceholder,
+  numeric = false,
+  allowCustomValue = false,
+  formatCustomLabel,
+  menuPortal = false,
+}) => {
+  const [open, setOpen] = React.useState(false);
+  const [activeIndex, setActiveIndex] = React.useState(-1);
+  const [query, setQuery] = React.useState('');
+  const rootRef = React.useRef<HTMLDivElement | null>(null);
+  const btnRef = React.useRef<HTMLButtonElement | null>(null);
+  const menuRef = React.useRef<HTMLUListElement | null>(null);
+  const searchRef = React.useRef<HTMLInputElement | null>(null);
+  // stable id base for aria-activedescendant (avoids Math.random / Date.now, which are unavailable).
+  const idBase = React.useMemo(() => `mselect-${Math.round(value ? value.length : 0)}-`, [value]);
+
+  const selectedIndex = options.findIndex((o) => o.value === value);
+  const selected = selectedIndex !== -1 ? options[selectedIndex] : undefined;
+  // a real value that just doesn't happen to match any option — only possible with
+  // allowCustomValue (e.g. a hand-typed "1421232" the preset rungs don't cover).
+  const customLabel = allowCustomValue && value && !selected
+    ? (formatCustomLabel ? formatCustomLabel(value) : value)
+    : undefined;
+  const hasValue = !!selected || customLabel !== undefined;
+
+  const filteredOptions = React.useMemo(() => {
+    if (!searchable || !query.trim()) return options;
+    const q = query.trim().toLowerCase();
+    const matches = options.filter((o) => o.label.toLowerCase().includes(q));
+    // some option lists intentionally repeat entries across groups while closed (e.g. a "Top
+    // Marken" shortlist followed by the FULL "Alle Marken" list, which includes those same top
+    // brands again) — harmless when browsing both sections, but shows the same match twice while
+    // searching. Keep only the first occurrence of each label once the user is actually filtering.
+    const seen = new Set<string>();
+    return matches.filter((o) => {
+      const key = o.label.toLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }, [searchable, query, options]);
+
+  // deferred: when searchable, the trigger <button> is swapped out for an <input> while
+  // open (see render), so btnRef.current is null *during* the close() call itself — the
+  // button only exists again after this state flips `open` back to false and React
+  // re-renders. Consumed by the effect below, once that re-render has actually happened.
+  const focusTriggerAfterClose = React.useRef(false);
+
+  // close + restore focus to the trigger. `commitTyped` (default true) commits whatever's
+  // currently typed as a custom value when `allowCustomValue` — this is what makes "just leave
+  // the field" (blur/click-away/Tab) work, not only an explicit pick from the list. Callers that
+  // already committed an explicit option (commit()) or that are cancelling (Escape) pass false.
+  const close = React.useCallback((focusTrigger: boolean, commitTyped: boolean = true) => {
+    if (allowCustomValue && commitTyped) {
+      const raw = query.trim();
+      if (raw !== value) onChange(raw);
+    }
+    setOpen(false);
+    setActiveIndex(-1);
+    setQuery('');
+    focusTriggerAfterClose.current = focusTrigger;
+  }, [allowCustomValue, query, value, onChange]);
+
+  React.useEffect(() => {
+    if (!open && focusTriggerAfterClose.current) {
+      focusTriggerAfterClose.current = false;
+      if (btnRef.current) btnRef.current.focus();
+    }
+  }, [open]);
+
+  const openMenu = React.useCallback(() => {
+    if (disabled) return;
+    setOpen(true);
+    // start the keyboard highlight on the current selection (or the first option).
+    setActiveIndex(selectedIndex !== -1 ? selectedIndex : 0);
+    // pre-fill the combobox with the current value (raw, not the formatted label) so a custom
+    // entry can be edited/replaced in place instead of always starting from a blank field.
+    if (allowCustomValue) setQuery(value || '');
+  }, [disabled, selectedIndex, allowCustomValue, value]);
+
+  // when opened searchable, focus the search input instead of leaving focus on the trigger.
+  // scrollIntoView first: on mobile the keyboard is about to eat ~40% of the viewport, so the
+  // trigger (and the popover below it) needs to already be scrolled above the fold before focus
+  // fires, or the popover can end up hidden behind the keyboard with no way to see it open.
+  React.useEffect(() => {
+    if (!open || !searchable) return;
+    if (rootRef.current && rootRef.current.scrollIntoView) {
+      rootRef.current.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    }
+    if (searchRef.current) {
+      searchRef.current.focus();
+      // pre-filled custom value (see openMenu) starts selected, so typing immediately
+      // replaces it instead of appending — same "click a number field, type over it" feel.
+      if (allowCustomValue) searchRef.current.select();
+    }
+  }, [open, searchable, allowCustomValue]);
+
+  // click-away (guarded for SSR). menuElRef is checked too — with menuPortal the popover renders
+  // outside rootRef (at document.body), so without this every option click would look like a
+  // click-away and close the menu before the option's own onClick had a chance to fire.
+  React.useEffect(() => {
+    if (!open || typeof document === 'undefined') return undefined;
+    const onDocMouseDown = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (rootRef.current && rootRef.current.contains(target)) return;
+      if (menuElRef.current && menuElRef.current.contains(target)) return;
+      close(false);
+    };
+    document.addEventListener('mousedown', onDocMouseDown);
+    return () => document.removeEventListener('mousedown', onDocMouseDown);
+  }, [open, close]);
+
+  // menuPortal: body-portal root + trigger-relative position, tracked on scroll/resize, flipping
+  // above the trigger when there isn't room below. Shared with MultiDropdown's checklist menu
+  // below — see usePortalMenuPosition's own doc comment for the full reasoning (every timing/CSS
+  // fix that went into this belongs in one place so the two consumers can't drift apart).
+  const onCloseAway = React.useCallback(() => close(false, false), [close]);
+  const { portalRoot, menuPos, menuElRef } = usePortalMenuPosition({
+    enabled: menuPortal,
+    open,
+    rootRef,
+    menuAlign,
+    onCloseAway,
+  });
+
+  // keep the active option scrolled into view while navigating by keyboard.
+  React.useEffect(() => {
+    if (!open || activeIndex < 0 || !menuRef.current) return;
+    const el = menuRef.current.children[activeIndex] as HTMLElement | undefined;
+    if (el && el.scrollIntoView) el.scrollIntoView({ block: 'nearest' });
+  }, [open, activeIndex]);
+
+  // reset the keyboard highlight to the top match whenever the filtered list changes.
+  React.useEffect(() => {
+    if (searchable && open) setActiveIndex(filteredOptions.length ? 0 : -1);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filteredOptions]);
+
+  const commit = (idx: number) => {
+    const opt = filteredOptions[idx];
+    if (!opt || opt.disabled) return;
+    onChange(opt.value);
+    // false: the explicit pick already won — don't also commit whatever's still sitting in the
+    // (now-stale) typed query behind it.
+    close(true, false);
+  };
+
+  // move the active highlight, skipping disabled options.
+  const move = (dir: 1 | -1) => {
+    if (!filteredOptions.length) return;
+    let i = activeIndex;
+    for (let step = 0; step < filteredOptions.length; step += 1) {
+      i = (i + dir + filteredOptions.length) % filteredOptions.length;
+      if (!filteredOptions[i].disabled) {
+        setActiveIndex(i);
+        return;
+      }
+    }
+  };
+
+  const onMenuKeyDown = (e: React.KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); move(1); break;
+      case 'ArrowUp': e.preventDefault(); move(-1); break;
+      case 'Home': e.preventDefault(); setActiveIndex(filteredOptions.findIndex((o) => !o.disabled)); break;
+      case 'End': e.preventDefault(); for (let i = filteredOptions.length - 1; i >= 0; i -= 1) { if (!filteredOptions[i].disabled) { setActiveIndex(i); break; } } break;
+      case 'Enter':
+        e.preventDefault();
+        // an active list match wins when there is one; otherwise, for allowCustomValue fields,
+        // Enter commits whatever's typed (same value close() would commit on blur anyway).
+        if (activeIndex >= 0) commit(activeIndex);
+        else if (allowCustomValue) close(true);
+        break;
+      // Escape cancels — close(..., false) so an in-progress custom edit is discarded, not committed.
+      case 'Escape': e.preventDefault(); close(true, false); break;
+      case 'Tab': close(false); break;
+      default: break;
+    }
+  };
+
+  const onTriggerKeyDown = (e: React.KeyboardEvent) => {
+    if (disabled) return;
+    if (!open) {
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        openMenu();
+      }
+      return;
+    }
+    if (e.key === ' ') { e.preventDefault(); if (activeIndex >= 0) commit(activeIndex); return; }
+    onMenuKeyDown(e);
+  };
+
+  const wrapCls = ['mselect'];
+  if (size === 'sm') wrapCls.push('mselect--sm');
+  if (block) wrapCls.push('mselect--block');
+  if (className) wrapCls.push(className);
+
+  const label = selected ? selected.label : (customLabel !== undefined ? customLabel : placeholder || '');
+
+  const editing = searchable && open;
+
+  // Bug 53/37: "Rate bis" / "km bis" allow a hand-typed amount the preset rungs don't cover
+  // (allowCustomValue) — that typed number never matches any option label, so filteredOptions
+  // comes back empty and the popover would show "Keine Treffer", reading as "no cars match this"
+  // to the customer even though the typed value is perfectly valid input. Once there's an actual
+  // typed query with zero matches on an allowCustomValue field, suppress the popover entirely
+  // (not just the "Keine Treffer" row) — an empty floating box would be just as confusing. Plain
+  // (non-custom) searchable dropdowns, e.g. Make/Model, are unaffected and keep showing it.
+  const suppressEmptyMenu = allowCustomValue && searchable && query.trim() !== '' && filteredOptions.length === 0;
+
+  // shared between the in-place popover and the menuPortal one — identical option list either way.
+  // maxHeight (menuPortal only — see positionMenu) overrides the CSS static 288px cap with the
+  // space actually available in whichever direction the menu opened; inline style wins over the
+  // class rule regardless of specificity, and falls back to the CSS default when omitted (the
+  // in-place, non-portal popover keeps relying on that + whatever ancestor clipping already existed).
+  const renderMenuList = (maxHeight?: number) => (
+    <ul
+      ref={menuRef}
+      id={`${idBase}list`}
+      className="mselect-list"
+      role="listbox"
+      tabIndex={-1}
+      style={maxHeight != null ? { maxHeight } : undefined}
+      aria-activedescendant={activeIndex >= 0 ? `${idBase}${activeIndex}` : undefined}
+    >
+      {filteredOptions.map((opt, i) => (
+        <li key={`${opt.value}_${i}`} role="presentation">
+          <button
+            id={`${idBase}${i}`}
+            type="button"
+            role="option"
+            aria-selected={opt.value === value}
+            disabled={opt.disabled}
+            className={'mselect-opt' + (i === activeIndex ? ' is-active' : '')}
+            onMouseEnter={() => setActiveIndex(i)}
+            onClick={() => commit(i)}
+          >
+            <span className="mselect-opt-label">{opt.label}</span>
+            {opt.value === value && <Icon name="check" size={16} cls="mselect-check" />}
+          </button>
+        </li>
+      ))}
+      {searchable && filteredOptions.length === 0 && (
+        <li className="mselect-empty" role="presentation">Keine Treffer</li>
+      )}
+    </ul>
+  );
+
+  return (
+    <div className={wrapCls.join(' ')} ref={rootRef}>
+      {editing ? (
+        // combobox mode: the trigger itself becomes the text field (not a separate input
+        // inside the popover) — a <button> can't legally contain an <input>, so this is a
+        // <div> standing in for it, same `.mselect-btn` class for identical chrome.
+        <div className="mselect-btn mselect-btn--editing">
+          {iconNode || (icon && <Icon name={icon} />)}
+          <input
+            ref={searchRef}
+            type="text"
+            className="mselect-input"
+            placeholder={searchPlaceholder || placeholder}
+            value={query}
+            onChange={(e) => setQuery(numeric ? e.target.value.replace(/\D/g, '') : e.target.value)}
+            onKeyDown={onMenuKeyDown}
+            aria-label={ariaLabel}
+            aria-haspopup="listbox"
+            aria-expanded={open}
+            aria-controls={`${idBase}list`}
+            aria-activedescendant={activeIndex >= 0 ? `${idBase}${activeIndex}` : undefined}
+            aria-invalid={ariaInvalid ? true : undefined}
+            aria-describedby={ariaDescribedBy}
+            {...(numeric ? { inputMode: 'numeric' as const, pattern: '[0-9]*' } : {})}
+          />
+          <button type="button" className="mselect-chev-btn" aria-label="Close" onClick={() => close(true)}>
+            <Icon name="chevron-down" cls="mselect-chev" />
+          </button>
+        </div>
+      ) : (
+        <button
+          ref={btnRef}
+          type="button"
+          className="mselect-btn"
+          aria-haspopup="listbox"
+          aria-expanded={open}
+          aria-label={ariaLabel}
+          aria-invalid={ariaInvalid ? true : undefined}
+          aria-describedby={ariaDescribedBy}
+          disabled={disabled}
+          onClick={() => (open ? close(false) : openMenu())}
+          onKeyDown={onTriggerKeyDown}
+        >
+          {iconNode || (icon && <Icon name={icon} />)}
+          <span className={'mselect-label' + (hasValue ? '' : ' mselect-label--ph')}>{label}</span>
+          <Icon name="chevron-down" cls="mselect-chev" />
+        </button>
+      )}
+      {open && !suppressEmptyMenu && (menuPortal && portalRoot
+        ? ReactDOM.createPortal(
+            <div
+              ref={menuElRef}
+              className={'mselect-menu mselect-menu--portal' + (searchable ? ' mselect-menu--searchable' : '')}
+              // menuPos is null for one frame on open, before the position effect has measured
+              // the trigger — stay invisible (not just visually, via `visibility`) rather than
+              // flash at (0,0)/full-width. `position: fixed` is set UNCONDITIONALLY, in both
+              // branches — leaving it out of this fallback used to mean the element briefly
+              // rendered as a normal in-flow block at the end of <body> for that one frame,
+              // which could visibly shift the page's scroll position the instant a dropdown
+              // opened (the block's real height — up to .mselect-list's 288px — briefly counted
+              // toward the document's scrollable height before flipping back out of flow).
+              style={
+                menuPos
+                  ? {
+                      position: 'fixed',
+                      top: menuPos.top,
+                      bottom: menuPos.bottom,
+                      left: menuPos.left,
+                      right: menuPos.right,
+                      width: menuPos.width,
+                      minWidth: menuPos.width,
+                      // Root cause of the "open above" collapse (menuPos.top/left now always a
+                      // concrete number-or-'auto', never omitted — see the menuPos state comment):
+                      // top/bottom (and left/right) here used to leave the unanchored side as
+                      // `undefined`, which React just drops from the inline style rather than
+                      // writing `auto`. With `top` missing from the DOM's inline style, the
+                      // `.mselect-menu` stylesheet rule (`top: calc(100% + 4px)`) filled back in —
+                      // fighting the inline `bottom` we DID set. Both `top` and `bottom` pinned at
+                      // once, with `height` still auto, forces the used height to the distance
+                      // between them (CSS 2.1 §10.6.4), which computed out negative (top landing
+                      // just past the viewport's bottom edge, bottom landing just above the
+                      // trigger) — clamped to 0, leaving only .mselect-menu's own padding+border
+                      // visible (6px*2 + 1px*2 = 14px, exactly the reported near-zero height). The
+                      // `top`-anchored "open below" case never hit this: its inline `top` overrode
+                      // the stylesheet regardless, and `bottom` being class-omitted (not written at
+                      // all, `auto` is the CSS default for `bottom`) matched the intended math.
+                      // With every side now explicitly 'auto' when unused, no stylesheet fallback
+                      // can leak in and `height` is a normal shrink-to-fit-then-clamped-by-maxHeight
+                      // calculation in both directions. This own explicit maxHeight (list's
+                      // maxHeight + .mselect-menu's padding/border, 6px*2 + 1px*2 = 14) still
+                      // matters on top of that fix — box-sizing: border-box means maxHeight here
+                      // must include the padding/border the inner .mselect-list's own maxHeight
+                      // (renderMenuList below) doesn't count, or the list gets squeezed twice.
+                      maxHeight: menuPos.maxHeight + 14,
+                    }
+                  : { position: 'fixed', visibility: 'hidden' }
+              }
+            >
+              {renderMenuList(menuPos?.maxHeight)}
+            </div>,
+            portalRoot,
+          )
+        : (
+          <div
+            ref={menuElRef}
+            className={'mselect-menu' + (menuAlign === 'right' ? ' mselect-menu--right' : '') + (searchable ? ' mselect-menu--searchable' : '')}
+          >
+            {renderMenuList()}
+          </div>
+        )
+      )}
+    </div>
+  );
+};
+
+export default Dropdown;
+