@bytebrand/fe-ui-core-autobahn 1.0.119 → 1.0.121

package/compat/MdField/MdField.tsx

@@ -79,6 +79,11 @@ const MdField: React.FunctionComponent<MdFieldProps> = ({
       <div
         className={
           'mfield'
+          // .mfield's base height:48px + align-items:center is sized for a single-line input.
+          // .mfield.mtextarea (md3.css) overrides that to height:auto + align-items:stretch for a
+          // multiline field — without it a tall `rows` textarea just overflows past the 48px box
+          // instead of growing it, visually spilling over whatever sits below/beside the field.
+          + (multiline ? ' mtextarea' : '')
           + (hasError ? ' mfield--error' : '')
           + (disabled ? ' mfield--disabled' : '')
           + (floatingLabel ? ' mfield--floating' : '')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebrand/fe-ui-core-autobahn",
-  "version": "1.0.119",
+  "version": "1.0.121",
   "description": "auto.de md3 (Autobahn) design system — UI primitives, cards, chrome, VDP modules, theme CSS and locales. Ships raw TypeScript source (like fe-ui-core before it); each consumer's bundler compiles it.",
   "main": "index.ts",
   "license": "UNLICENSED",

package/theme/md3.css

@@ -9563,6 +9563,11 @@ color: #005CFF;
   align-items: flex-start;
   padding: 7px 14px;
 }
+/* nothing selected yet: single-line placeholder, same as a normal select — center it instead
+   of top-aligning (top-align only earns its keep once there are wrapped chips to protect). */
+.md3 .mfd-multi-btn--empty {
+  align-items: center;
+}
 .md3 .mfd-multi-btn .mselect-chev {
   align-self: center;
 }
@@ -9650,6 +9655,11 @@ color: #005CFF;
   display: flex;
   flex-direction: column;
   gap: 6px;
+  /* this is the element that actually sits IN a CSS grid column (e.g. VehicleEdit Safety
+     .row) — grid items default to a content-based auto min-width too, so this needs the
+     same override as .mcheck/.mcheck-label below or a long label can still force its own
+     column wider than its track instead of wrapping inside it. */
+  min-width: 0;
 }
 
 /* 44px touch target: the label is the hit area; the visual box sits centred inside. */
@@ -9663,6 +9673,12 @@ color: #005CFF;
   font-family: var(--md-font);
   color: var(--md-on-surface);
   -webkit-tap-highlight-color: transparent;
+  /* a flex item's automatic min-width is its content's un-wrapped size, not 0 — inside a
+     narrow grid column (see VehicleEdit Safety .row) that let a long label's text refuse to
+     wrap and push past the column instead. 0 lets this actually shrink to whatever width its
+     container gives it, same as .mcheck-label below (belt-and-suspenders: either alone fixes
+     it depending on which element the browser treats as the shrink boundary). */
+  min-width: 0;
 }
 .md3 .mcheck--disabled {
   cursor: not-allowed;
@@ -9720,6 +9736,8 @@ color: #005CFF;
   line-height: 1.5;
   padding-top: 7px;
   color: var(--md-on-surface);
+  /* see .mcheck's min-width:0 above — same fix, on the actual text-bearing flex item. */
+  min-width: 0;
 }
 /* rich labels (T&C/permission) — links pick up the brand colour. */
 .md3 .mcheck-label a {

package/ui/Dropdown.tsx

@@ -21,6 +21,7 @@ import React from 'react';
 import * as ReactDOM from 'react-dom';
 
 import Icon from './Icon';
+import { usePortalMenuPosition } from './usePortalMenuPosition';
 
 export interface DropdownOption {
   value: string;
@@ -104,7 +105,6 @@ const Dropdown: React.FunctionComponent<DropdownProps> = ({
   const rootRef = React.useRef<HTMLDivElement | null>(null);
   const btnRef = React.useRef<HTMLButtonElement | null>(null);
   const menuRef = React.useRef<HTMLUListElement | null>(null);
-  const menuElRef = React.useRef<HTMLDivElement | 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]);
@@ -205,60 +205,18 @@ const Dropdown: React.FunctionComponent<DropdownProps> = ({
     return () => document.removeEventListener('mousedown', onDocMouseDown);
   }, [open, close]);
 
-  // menuPortal: a fresh div.md3 appended to body while open, so --md-* tokens and every
-  // `.md3 .mselect-*` rule still resolve at body level (same technique as ui/Modal.tsx).
-  const portalRoot = React.useMemo<HTMLDivElement | null>(() => {
-    if (!menuPortal || typeof document === 'undefined') return null;
-    const el = document.createElement('div');
-    el.className = 'md3';
-    return el;
-  }, [menuPortal]);
-
-  React.useEffect(() => {
-    if (!menuPortal || !open || !portalRoot || typeof document === 'undefined') return undefined;
-    document.body.appendChild(portalRoot);
-    return () => {
-      if (portalRoot.parentNode) portalRoot.parentNode.removeChild(portalRoot);
-    };
-  }, [menuPortal, open, portalRoot]);
-
-  // menuPortal position: computed from the trigger's on-screen rect (position:fixed, so it's
-  // viewport-relative — kept in sync on scroll/resize below). ESTIMATED_MENU_HEIGHT (the list's
-  // own max-height, 288px, plus the menu's padding/border) only needs to be a reasonable guess —
-  // it's used to DECIDE whether to flip above the trigger, not to size anything; the "above"
-  // placement is positioned via `bottom` instead of `top` so it grows upward regardless of its
-  // real height.
-  const ESTIMATED_MENU_HEIGHT = 300;
-  const [menuPos, setMenuPos] = React.useState<
-    { width: number; top?: number; bottom?: number; left?: number; right?: number } | null
-  >(null);
-
-  const positionMenu = React.useCallback(() => {
-    if (!menuPortal || !rootRef.current || typeof window === 'undefined') return;
-    const rect = rootRef.current.getBoundingClientRect();
-    const spaceBelow = window.innerHeight - rect.bottom;
-    const openAbove = spaceBelow < ESTIMATED_MENU_HEIGHT && rect.top > spaceBelow;
-    setMenuPos({
-      width: rect.width,
-      left: menuAlign === 'right' ? undefined : rect.left,
-      right: menuAlign === 'right' ? window.innerWidth - rect.right : undefined,
-      top: openAbove ? undefined : rect.bottom + 4,
-      bottom: openAbove ? window.innerHeight - rect.top + 4 : undefined,
-    });
-  }, [menuPortal, menuAlign]);
-
-  React.useEffect(() => {
-    if (!open || !menuPortal) return undefined;
-    positionMenu();
-    // capture:true — a scroll inside any nested scrollable ancestor (not just the window) must
-    // also reposition, since the trigger moves relative to the viewport either way.
-    window.addEventListener('scroll', positionMenu, true);
-    window.addEventListener('resize', positionMenu);
-    return () => {
-      window.removeEventListener('scroll', positionMenu, true);
-      window.removeEventListener('resize', positionMenu);
-    };
-  }, [open, menuPortal, positionMenu]);
+  // 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(() => {
@@ -347,13 +305,18 @@ const Dropdown: React.FunctionComponent<DropdownProps> = ({
   const suppressEmptyMenu = allowCustomValue && searchable && query.trim() !== '' && filteredOptions.length === 0;
 
   // shared between the in-place popover and the menuPortal one — identical option list either way.
-  const renderMenuList = () => (
+  // 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) => (
@@ -433,7 +396,13 @@ const Dropdown: React.FunctionComponent<DropdownProps> = ({
               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 rather than flash at (0,0)/full-width.
+              // 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
                   ? {
@@ -444,11 +413,34 @@ const Dropdown: React.FunctionComponent<DropdownProps> = ({
                       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,
                     }
-                  : { visibility: 'hidden' }
+                  : { position: 'fixed', visibility: 'hidden' }
               }
             >
-              {renderMenuList()}
+              {renderMenuList(menuPos?.maxHeight)}
             </div>,
             portalRoot,
           )
@@ -466,3 +458,4 @@ const Dropdown: React.FunctionComponent<DropdownProps> = ({
 };
 
 export default Dropdown;
+

package/ui/FormDropdown.tsx

@@ -30,10 +30,12 @@
 // `.md3` subtree.
 
 import * as React from 'react';
+import * as ReactDOM from 'react-dom';
 import { observer } from 'mobx-react';
 
 import Icon from './Icon';
 import Dropdown, { DropdownOption } from './Dropdown';
+import { usePortalMenuPosition } from './usePortalMenuPosition';
 
 export interface FormDropdownProps {
   /** mobx-react-form field (form.$('basicDataForm.mainData_make') etc.). Untyped — the lib ships no TS types. */
@@ -59,10 +61,10 @@ export interface FormDropdownProps {
   style?: React.CSSProperties;
   /** extra class on the wrapper (legacy `className`). */
   className?: string;
-  /** forwarded to the underlying Dropdown — see Dropdown.tsx's own doc comment. Escapes a known
-   *  clipping ancestor (e.g. a collapsing Accordion region) by rendering the popover into a
-   *  document.body portal instead of nesting it in place. Single-select only (isMulti unaffected —
-   *  its checklist menu doesn't go through the base Dropdown). Off by default. */
+  /** escapes a known clipping ancestor (e.g. a collapsing Accordion region) by rendering the
+   *  popover/checklist into a document.body portal instead of nesting it in place — see
+   *  Dropdown.tsx's own doc comment (single-select) / usePortalMenuPosition.ts (shared with
+   *  MultiDropdown's checklist below). Off by default. */
   menuPortal?: boolean;
 }
 
@@ -137,6 +139,7 @@ const FormDropdown: React.FunctionComponent<FormDropdownProps> = observer(
           ariaLabel={label}
           style={style}
           className={className}
+          menuPortal={menuPortal}
         />
       );
     }
@@ -211,25 +214,45 @@ interface MultiProps {
   ariaLabel: string;
   style?: React.CSSProperties;
   className?: string;
+  /** see FormDropdownProps.menuPortal above. */
+  menuPortal?: boolean;
 }
 
 const MultiDropdown: React.FunctionComponent<MultiProps> = observer(
-  ({ field, options, label, hasError, disabled, ariaLabel, style, className }) => {
+  ({ field, options, label, hasError, disabled, ariaLabel, style, className, menuPortal }) => {
     const [open, setOpen] = React.useState(false);
     const rootRef = React.useRef<HTMLDivElement | null>(null);
     const btnRef = React.useRef<HTMLButtonElement | null>(null);
 
     const selected: string[] = Array.isArray(field.value) ? field.value.map(String) : [];
 
-    // click-away (guarded for SSR), matching the base Dropdown.
+    // menuPortal: same body-portal + trigger-relative positioning as the single-select Dropdown
+    // — see usePortalMenuPosition.ts. A checklist can run just as long as any other option list
+    // (Safety's Airbag field has 13 entries) and lives in the exact same clipping Accordion
+    // section the single-select fix targeted, so it needs the identical escape hatch.
+    const onCloseAway = React.useCallback(() => setOpen(false), []);
+    const { portalRoot, menuPos, menuElRef } = usePortalMenuPosition<HTMLUListElement>({
+      enabled: !!menuPortal,
+      open,
+      rootRef,
+      onCloseAway,
+    });
+
+    // click-away (guarded for SSR), matching the base Dropdown. menuElRef is checked too — with
+    // menuPortal the checklist renders outside rootRef (at document.body), so without this every
+    // option click would look like a click-away and close the menu before toggle() had a chance
+    // to fire.
     React.useEffect(() => {
       if (!open || typeof document === 'undefined') return undefined;
       const onDocMouseDown = (e: MouseEvent) => {
-        if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false);
+        const target = e.target as Node;
+        if (rootRef.current && rootRef.current.contains(target)) return;
+        if (menuElRef.current && menuElRef.current.contains(target)) return;
+        setOpen(false);
       };
       document.addEventListener('mousedown', onDocMouseDown);
       return () => document.removeEventListener('mousedown', onDocMouseDown);
-    }, [open]);
+    }, [open, menuElRef]);
 
     const toggle = (value: string) => {
       if (disabled) return;
@@ -261,6 +284,29 @@ const MultiDropdown: React.FunctionComponent<MultiProps> = observer(
       return o ? o.label : value;
     };
 
+    // shared between the in-place checklist and the menuPortal one — identical options either way.
+    const renderOptions = () =>
+      options.map((opt, i) => {
+        const checked = selected.indexOf(opt.value) > -1;
+        return (
+          <li key={`${opt.value}_${i}`} role="presentation">
+            <button
+              type="button"
+              role="option"
+              aria-selected={checked}
+              disabled={opt.disabled}
+              className={'mselect-opt mfd-multi-opt' + (checked ? ' is-checked' : '')}
+              onClick={() => toggle(opt.value)}
+            >
+              <span className={'mfd-check' + (checked ? ' mfd-check--on' : '')}>
+                {checked ? <Icon name="check" size={14} /> : null}
+              </span>
+              <span className="mselect-opt-label">{opt.label}</span>
+            </button>
+          </li>
+        );
+      });
+
     return (
       <div className={'mfd' + (className ? ' ' + className : '')} style={style}>
         {label ? <label className="md-label-sm mfield-label mfd-label">{label}</label> : null}
@@ -268,7 +314,16 @@ const MultiDropdown: React.FunctionComponent<MultiProps> = observer(
           <button
             ref={btnRef}
             type="button"
-            className={'mselect-btn mfd-multi-btn' + (hasError ? ' mfd-invalid' : '')}
+            // .mfd-multi-btn top-aligns its content (align-items:flex-start) so wrapped chips
+            // don't clip once there are enough of them to reach a second line — but with nothing
+            // selected yet, the trigger shows one single-line placeholder just like a normal
+            // select, and that same top-align just shoved it up instead of centering it.
+            // --empty switches it back to centered for exactly that (no chips) case.
+            className={
+              'mselect-btn mfd-multi-btn' +
+              (selected.length ? '' : ' mfd-multi-btn--empty') +
+              (hasError ? ' mfd-invalid' : '')
+            }
             aria-haspopup="listbox"
             aria-expanded={open}
             aria-label={ariaLabel}
@@ -299,29 +354,46 @@ const MultiDropdown: React.FunctionComponent<MultiProps> = observer(
             )}
             <Icon name="chevron-down" cls="mselect-chev" />
           </button>
-          {open && (
-            <ul className="mselect-menu mfd-multi-menu" role="listbox" aria-multiselectable="true" tabIndex={-1}>
-              {options.map((opt, i) => {
-                const checked = selected.indexOf(opt.value) > -1;
-                return (
-                  <li key={`${opt.value}_${i}`} role="presentation">
-                    <button
-                      type="button"
-                      role="option"
-                      aria-selected={checked}
-                      disabled={opt.disabled}
-                      className={'mselect-opt mfd-multi-opt' + (checked ? ' is-checked' : '')}
-                      onClick={() => toggle(opt.value)}
-                    >
-                      <span className={'mfd-check' + (checked ? ' mfd-check--on' : '')}>
-                        {checked ? <Icon name="check" size={14} /> : null}
-                      </span>
-                      <span className="mselect-opt-label">{opt.label}</span>
-                    </button>
-                  </li>
-                );
-              })}
-            </ul>
+          {open && (menuPortal && portalRoot
+            ? ReactDOM.createPortal(
+                <ul
+                  ref={menuElRef}
+                  className="mselect-menu mselect-menu--portal mfd-multi-menu"
+                  role="listbox"
+                  aria-multiselectable="true"
+                  tabIndex={-1}
+                  // see Dropdown.tsx's render for why every side is explicit ('auto', never
+                  // omitted — the "opens but nothing visible" collapse otherwise) and why
+                  // maxHeight adds the box's own padding/border (+14, box-sizing:border-box).
+                  // overflowY:auto: unlike the single-select's .mselect-list, .mfd-multi-menu has
+                  // no height cap of its own (in-place it just grows — fine there, clipped by the
+                  // accordion instead of scrolling; portaled it needs to scroll internally once it
+                  // hits the space actually available).
+                  style={
+                    menuPos
+                      ? {
+                          position: 'fixed',
+                          top: menuPos.top,
+                          bottom: menuPos.bottom,
+                          left: menuPos.left,
+                          right: menuPos.right,
+                          width: menuPos.width,
+                          minWidth: menuPos.width,
+                          maxHeight: menuPos.maxHeight + 14,
+                          overflowY: 'auto',
+                        }
+                      : { position: 'fixed', visibility: 'hidden' }
+                  }
+                >
+                  {renderOptions()}
+                </ul>,
+                portalRoot,
+              )
+            : (
+              <ul className="mselect-menu mfd-multi-menu" role="listbox" aria-multiselectable="true" tabIndex={-1}>
+                {renderOptions()}
+              </ul>
+            )
           )}
         </div>
         {hasError ? <span className="mfield-error-text mfd-error">{field.error}</span> : null}

package/ui/usePortalMenuPosition.ts

@@ -0,0 +1,213 @@
+// Autobahn (auto.de redesign) — shared body-portal positioning for md3 popover menus.
+//
+// Extracted out of Dropdown.tsx (the single-select) so MultiDropdown (FormDropdown.tsx's
+// isMulti checklist) can get the exact same `menuPortal` escape-hatch — same clipping problem
+// (a checklist menu inside a VehicleEdit Accordion section gets cut off by `.macc-region-inner`'s
+// overflow:hidden, see md3.css), same fix, and every hard-won timing/CSS fix that went into this
+// belongs in ONE place so the two consumers can't drift out of sync. See Dropdown.tsx's own
+// `menuPortal` doc comment for the user-facing behaviour this produces (escapes clipping
+// ancestors, tracks the trigger on scroll/resize while open, flips above when there's no room
+// below, closes instead of trying to visually "chase" the trigger on a real user scroll).
+//
+// Consumers own their OWN <ul>/menu markup and className — this hook only owns: the body-portal
+// root element, the trigger-relative position math, and the effect timing/scroll-listener
+// plumbing. Apply `menuPos` to whatever floating element you render into `portalRoot` via
+// ReactDOM.createPortal, and pass that same element's ref as `menuElRef` so its own internal
+// scrolling doesn't get misread as a user scrolling the trigger away.
+
+import * as React from 'react';
+
+export interface PortalMenuPos {
+  width: number;
+  // always a concrete value — a real px number for whichever side is anchoring the box, 'auto'
+  // (never omitted) for the other. React drops a style property from the DOM entirely when its
+  // value is `undefined`, so `undefined` is NOT "unset" the way it is in the style object here in
+  // JS — it just means "don't touch whatever's already cascading in from CSS", and the menu's own
+  // stylesheet rule (`top: calc(100% + 4px); left: 0;`) was right there to fill back in and fight
+  // the side that WAS set inline, forcing a negative used-height (CSS 2.1 §10.6.4, clamped to 0 —
+  // the "opens but nothing visible" collapse). Explicit 'auto' writes a real `top: auto` / `left:
+  // auto` inline, which — unlike an omitted property — reliably beats the stylesheet rule
+  // regardless of specificity, so only the intended side ever constrains the box.
+  top: number | 'auto';
+  bottom: number | 'auto';
+  left: number | 'auto';
+  right: number | 'auto';
+  // the space actually available in whichever direction the menu opened, clamped to a sane
+  // [120, ESTIMATED_MENU_HEIGHT-12] range — apply as the floating element's OWN maxHeight (plus
+  // its padding/border, box-sizing:border-box) so it never relies on shrink-to-fit auto-sizing.
+  maxHeight: number;
+}
+
+export interface UsePortalMenuPositionArgs {
+  /** opt-in flag (the `menuPortal` prop on the consumer). */
+  enabled: boolean;
+  open: boolean;
+  /** the trigger's wrapping element — always rendered (regardless of `open`), measured for position. */
+  rootRef: React.RefObject<HTMLElement>;
+  menuAlign?: 'left' | 'right';
+  /** called when the trigger scrolls out of view entirely, or a real user scroll happens after
+   *  the post-open grace window — the menu has nothing sensible left to anchor to or chase. */
+  onCloseAway: () => void;
+}
+
+// TMenuEl: the concrete element type of whatever you portal (Dropdown.tsx portals a wrapping
+// `<div>`; MultiDropdown's checklist has no separate wrapper and portals its `<ul>` directly) —
+// keeps `menuElRef` assignable straight to that element's own `ref` without a cast.
+export interface UsePortalMenuPositionResult<TMenuEl extends HTMLElement = HTMLDivElement> {
+  /** a fresh `div.md3` appended to `document.body` while open (so --md-* tokens and every
+   *  `.md3 .mselect-*` rule still resolve at body level, same technique as ui/Modal.tsx) — pass
+   *  as the portal target to `ReactDOM.createPortal`. `null` when `!enabled`. */
+  portalRoot: HTMLDivElement | null;
+  /** `null` for one frame on open, before position is first measured — render `visibility:hidden`
+   *  (not just omit inline styles) in that case, see Dropdown.tsx's render for the exact pattern. */
+  menuPos: PortalMenuPos | null;
+  /** attach to the actual floating menu element you portal — excludes its own internal scrolling
+   *  (e.g. a long option list) from being misread as the user scrolling the trigger away, and is
+   *  also what click-away logic should check alongside the trigger's own root. */
+  menuElRef: React.RefObject<TMenuEl>;
+}
+
+// the list's own max-height guess (plus the menu box's padding/border) — only needs to be a
+// reasonable estimate; it decides whether to flip ABOVE the trigger. The real size is then
+// clamped to the space actually available (see `maxHeight` above), not just guessed at.
+const ESTIMATED_MENU_HEIGHT = 300;
+// a scroll within this window of opening REPOSITIONS instead of closing — see the effect below.
+const SELF_SCROLL_GRACE_MS = 500;
+
+export function usePortalMenuPosition<TMenuEl extends HTMLElement = HTMLDivElement>({
+  enabled,
+  open,
+  rootRef,
+  menuAlign = 'left',
+  onCloseAway,
+}: UsePortalMenuPositionArgs): UsePortalMenuPositionResult<TMenuEl> {
+  const menuElRef = React.useRef<TMenuEl | null>(null);
+  // timestamp of the last open — lets the close-on-scroll listener below tell a genuine user
+  // scroll apart from a scroll OUR OWN opening sequence causes (e.g. a searchable dropdown's own
+  // scrollIntoView, or the browser's native "scroll a just-focused element into view" behaviour).
+  // useLayoutEffect (not useEffect): must be set before the scroll-listener effect further down
+  // can possibly attach and fire — same synchronous pre-paint phase as the portal-attach/position
+  // effects below, so there's no window where a scroll could be misjudged against a stale (or
+  // zero) timestamp.
+  const openedAtRef = React.useRef(0);
+  React.useLayoutEffect(() => {
+    if (open) openedAtRef.current = Date.now();
+  }, [open]);
+
+  const portalRoot = React.useMemo<HTMLDivElement | null>(() => {
+    if (!enabled || typeof document === 'undefined') return null;
+    const el = document.createElement('div');
+    el.className = 'md3';
+    return el;
+  }, [enabled]);
+
+  // useLayoutEffect, not useEffect: createPortal(children, portalRoot) renders content INTO
+  // portalRoot the moment `open` becomes true, but that's a detached node until THIS effect
+  // appends it to document.body; a plain useEffect only runs after the browser paints, so there
+  // was a real window where the (correctly rendered, correctly positioned) menu simply wasn't
+  // attached to the visible page yet — reading as "opens but nothing appears" rather than a late
+  // attach.
+  React.useLayoutEffect(() => {
+    if (!enabled || !open || !portalRoot || typeof document === 'undefined') return undefined;
+    document.body.appendChild(portalRoot);
+    return () => {
+      if (portalRoot.parentNode) portalRoot.parentNode.removeChild(portalRoot);
+    };
+  }, [enabled, open, portalRoot]);
+
+  // the portal menu's z-index (1400, .mselect-menu--portal) is intentionally higher than every
+  // other fixed overlay it must paint over (checkout sheets/modals) — which also means it would
+  // paint over the sticky app header (.topbar, position:sticky/top:0/z-index:50) if left
+  // unconstrained. Reading the header's live bottom edge (0 when absent, e.g. inside a modal, or
+  // when TopBar's autoHideOnScroll has slid it away) gives a correct top boundary without
+  // hardcoding a pixel height that could drift from the header's own CSS.
+  const getSafeTop = (): number => {
+    if (typeof document === 'undefined') return 0;
+    const header = document.querySelector('.topbar');
+    return header ? Math.max(0, header.getBoundingClientRect().bottom) : 0;
+  };
+
+  const [menuPos, setMenuPos] = React.useState<PortalMenuPos | null>(null);
+
+  const positionMenu = React.useCallback(() => {
+    if (!enabled || !rootRef.current || typeof window === 'undefined') return;
+    const rect = rootRef.current.getBoundingClientRect();
+    const GAP = 4;
+    const safeTop = getSafeTop();
+    // the trigger itself scrolled out of view (fully under the header or past either viewport
+    // edge) — position:fixed keeps the menu exactly where it last was, visually "stuck" over
+    // unrelated content instead of tracking a trigger that isn't on screen to track anymore. Just
+    // dismiss it, same as a native <select>'s options close the instant you scroll the trigger away.
+    if (rect.bottom <= safeTop || rect.top >= window.innerHeight) {
+      onCloseAway();
+      return;
+    }
+    const spaceBelow = window.innerHeight - rect.bottom - GAP;
+    const spaceAbove = rect.top - safeTop - GAP;
+    const openAbove = spaceBelow < ESTIMATED_MENU_HEIGHT && spaceAbove > spaceBelow;
+    // cap the menu to the space it ACTUALLY has in whichever direction it opens, instead of
+    // trusting a static CSS max-height on its own — near the header or viewport edge that static
+    // cap can still be taller than what's really available, which is what let the menu paint over
+    // the header in the first place. The consumer's own overflow-y:auto takes it from there once
+    // content exceeds this.
+    const available = Math.max(120, Math.min(ESTIMATED_MENU_HEIGHT - 12, openAbove ? spaceAbove : spaceBelow));
+    setMenuPos({
+      width: rect.width,
+      left: menuAlign === 'right' ? 'auto' : rect.left,
+      right: menuAlign === 'right' ? window.innerWidth - rect.right : 'auto',
+      top: openAbove ? 'auto' : rect.bottom + GAP,
+      bottom: openAbove ? window.innerHeight - rect.top + GAP : 'auto',
+      maxHeight: available,
+    });
+  }, [enabled, menuAlign, onCloseAway, rootRef]);
+
+  // Synchronous (pre-paint) position computation. useLayoutEffect — not useEffect — matters here:
+  // it runs right after the DOM mutation that mounted the portal but BEFORE the browser paints, so
+  // there is no frame where the menu is mounted-but-unpositioned. positionMenu also needs rootRef
+  // already attached, which it is by the time this runs — the wrapper element it measures is
+  // always rendered regardless of `open`, so its ref was set on an earlier commit already.
+  React.useLayoutEffect(() => {
+    if (!open || !enabled) return;
+    positionMenu();
+  }, [open, enabled, positionMenu]);
+
+  React.useEffect(() => {
+    if (!open || !enabled) return undefined;
+    // A scroll of the page/an ancestor CLOSES the menu instead of repositioning it. Continuously
+    // chasing the trigger during a scroll (recompute + setState + re-render) always lags a frame or
+    // more behind the browser's own native, synchronous scroll — the fixed-position menu visibly
+    // trails the trigger and then "snaps" into place once scrolling settles. A native <select> (and
+    // most real-world custom ones) just closes on scroll instead; that reads as correct rather than
+    // janky, and sidesteps the lag entirely instead of trying to out-run it. capture:true so a
+    // scroll on any nested scrollable ancestor is caught too, not just the window. Scrolling INSIDE
+    // the menu itself (menuElRef's own subtree) must NOT close it — that's just browsing a long
+    // list, not scrolling the trigger away — so that's the one scroll target excluded.
+    // A short grace window after opening REPOSITIONS instead of closing on scroll — two different
+    // self-triggered scrolls land in this window: a searchable dropdown's own scrollIntoView effect
+    // smooth-scrolls the trigger into view the instant the menu opens, AND — for every dropdown —
+    // the BROWSER ITSELF auto-scrolls a just-focused element into view when it was partially cut
+    // off at the viewport edge. Both were previously just swallowed (ignored) here, on the theory
+    // that "our own open" scroll isn't a real user scroll-away — true, but positionMenu() was
+    // computed ONCE, before that scroll happened, so the menu was left floating at its PRE-scroll
+    // coordinates while the page settled at a new scroll offset under it. Resyncing the position on
+    // every grace-window scroll fixes that (cheap: one rect read + setState) without reintroducing
+    // the janky continuous-chase during a real user scroll — this only runs for the ~500ms settle
+    // window right after open, not for scrolling in general (that still closes, below).
+    const onScroll = (e: Event) => {
+      if (menuElRef.current && e.target instanceof Node && menuElRef.current.contains(e.target)) return;
+      if (Date.now() - openedAtRef.current < SELF_SCROLL_GRACE_MS) {
+        positionMenu();
+        return;
+      }
+      onCloseAway();
+    };
+    window.addEventListener('scroll', onScroll, true);
+    window.addEventListener('resize', positionMenu);
+    return () => {
+      window.removeEventListener('scroll', onScroll, true);
+      window.removeEventListener('resize', positionMenu);
+    };
+  }, [open, enabled, positionMenu, onCloseAway]);
+
+  return { portalRoot, menuPos, menuElRef };
+}

package/vdp/index.ts

@@ -71,7 +71,7 @@ export type {
 } from './VdpModules';
 
 // View-model types + the spec-table helper.
-export { defaultVdpSpecs } from './types';
+export { defaultVdpSpecs, isZeroSpecValue } from './types';
 export type {
   VehicleDetail,
   VehicleCondition,

package/vdp/types.ts

@@ -20,6 +20,39 @@ export type { AutobahnPhev };
 /** One row of the Fahrzeugdaten spec table: [kebab-case lucide icon, label, value]. */
 export type VdpSpec = readonly [icon: string, label: string, value: string];
 
+// ---------------------------------------------------------------------------
+// Zero-value spec visibility (CDP ticket "Hide meaningless zero-value vehicle
+// attributes") — the single shared rule behind whether a Fahrzeugdaten row
+// renders when its underlying measurement is 0.
+//
+// Most numeric vehicle attributes (Leergewicht, Hubraum, Drehmoment, …) are
+// physical measurements that are never legitimately 0 — a 0 there means "no
+// data", not "the car weighs nothing", and rendering "0 kg" actively damages
+// trust in the data (the reported bug). The DEFAULT for a numeric spec is
+// therefore to hide the row entirely rather than show a fabricated-looking
+// zero.
+//
+// That default must NOT apply blindly to every field, per two carve-outs:
+//   - some fields have a real, meaningful zero (0 Vorbesitzer = never owned,
+//     0 km = brand-new car) — callers opt these OUT of hiding explicitly;
+//   - the Pkw-EnVKV legally-required consumption/emissions figures (cons,
+//     co2, co2class, and by the same regulatory family Verbrauch innerorts/
+//     außerorts) must never be suppressed by this generic rule — their own
+//     compliance/data-quality logic decides what renders, so callers building
+//     those rows must never run them through this check at all.
+//
+// isZeroSpecValue operates on the already-FORMATTED display string (not the
+// raw number) because callers combine both string-typed values (decorated
+// getters that already bake in a unit, e.g. "0 kg") and plain numbers
+// (`${n} Sitze`) into the same VdpSpec value slot — checking the rendered
+// string is the one place both shapes agree. It matches a leading zero
+// magnitude (optionally with an all-zero decimal, "0,0"/"0.0") followed by
+// whitespace (a unit) or end-of-string, so "0 kg"/"0,0 l/100 km"/"0" all
+// count as zero but "10 kg"/"0.5 l" (a real non-zero measurement) do not.
+export function isZeroSpecValue(formatted: string): boolean {
+  return /^-?0([.,]0+)?(\s|$)/.test(formatted.trim());
+}
+
 /**
  * Grouped equipment: each entry is a section title mapped to its item labels,
  * e.g. { Komfort: ['Klimaautomatik', …], Sicherheit: [...] }. Replaces the design
@@ -200,20 +233,27 @@ export interface VehicleDetail {
  * Build the design's twelve-row Fahrzeugdaten table from the typed fields. Used
  * when a VehicleDetail carries no explicit `specs`. Pure — produces the same rows
  * and order as the spec's ScreenVDP `specs` array.
+ *
+ * `allowZero: true` marks fields where 0 is a real, meaningful value (or isn't a
+ * zero-able numeric at all) — everything else gets the isZeroSpecValue default
+ * (hide the row rather than render a fabricated-looking "0 X"). cons/co2class
+ * are Pkw-EnVKV legally-required and are marked allowZero for that reason, not
+ * because 0 is plausible there — see isZeroSpecValue's own comment.
  */
 export function defaultVdpSpecs(v: VehicleDetail): VdpSpec[] {
-  return [
-    ['gauge', 'Kilometerstand', `${v.km.toLocaleString('de-DE')} km`],
-    ['calendar', 'Erstzulassung', v.reg],
-    ['zap', 'Leistung', v.power],
-    ['fuel', 'Kraftstoff', v.fuel],
-    ['cog', 'Getriebe', v.gear],
-    ['users', 'Sitze', `${v.seats} Sitze`],
-    ['door-open', 'Türen', `${v.doors} Türen`],
-    ['user', 'Halter', `${v.owners}. Hand`],
-    ['palette', 'Außenfarbe', v.color],
-    ['car-front', 'Karosserie', v.body],
-    ['droplet', 'Verbrauch komb.', v.cons],
-    ['leaf', 'CO₂ · Klasse', `${v.co2} · ${v.co2class}`],
+  const rows: ReadonlyArray<readonly [spec: VdpSpec, allowZero: boolean]> = [
+    [['gauge', 'Kilometerstand', `${v.km.toLocaleString('de-DE')} km`], true], // Neuwagen: 0 km is valid
+    [['calendar', 'Erstzulassung', v.reg], true],
+    [['zap', 'Leistung', v.power], true],
+    [['fuel', 'Kraftstoff', v.fuel], true],
+    [['cog', 'Getriebe', v.gear], true],
+    [['users', 'Sitze', `${v.seats} Sitze`], false],
+    [['door-open', 'Türen', `${v.doors} Türen`], false],
+    [['user', 'Halter', `${v.owners}. Hand`], true], // 0 Vorbesitzer is valid
+    [['palette', 'Außenfarbe', v.color], true],
+    [['car-front', 'Karosserie', v.body], true],
+    [['droplet', 'Verbrauch komb.', v.cons], true], // Pkw-EnVKV — exempt from this rule
+    [['leaf', 'CO₂ · Klasse', `${v.co2} · ${v.co2class}`], true], // Pkw-EnVKV — exempt
   ];
+  return rows.filter(([spec, allowZero]) => allowZero || !isZeroSpecValue(spec[2])).map(([spec]) => spec);
 }