@multiplatform.one/forms 6.7.0 → 7.0.0

package/src/fields/Combobox/index.tsx

@@ -9,7 +9,7 @@ import {
   useState,
   memo,
 } from "react";
-import { useTranslation } from "react-i18next";
+import { useTranslation } from "../../shared/i18n";
 import {
   CaretDownIcon,
   CheckIcon,
@@ -26,7 +26,13 @@ import {
   FloatingFocusManager,
 } from "@floating-ui/react";
 import type { AnyFormApi } from "../../types";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  ensureFocusVisibleRing,
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  menuRowFrame,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import type { LabelProps, SizeTokens } from "tamagui";
 import { Pressable as RNPressable } from "react-native";
 import { Input as TInput, Text, View, XStack, YStack, isWeb, styled, useTheme } from "tamagui";
@@ -61,28 +67,44 @@ import { useIsInTableCell } from "../../shared/tableCellContext";
 
 // ── Styled row ───────────────────────────────────────────────
 
+// LC-16 menu-row frame + LC-71: fill (selected/active) and ring are orthogonal.
+// Virtual list navigation never DOM-focuses the row, so the keyboard ring is
+// painted from `keyboardFocusRingProps` on the active option (activedescendant),
+// same as TreeView. focusVisibleStyle remains for the rare real-focus path.
 const ComboboxRow = styled(View, {
   name: "ComboboxRow",
-  flexDirection: "row",
-  alignItems: "center",
+  ...menuRowFrame,
   gap: "$2",
-  paddingHorizontal: "$3",
   cursor: "default",
-  outlineStyle: "none" as any,
   hoverStyle: { backgroundColor: formInputColors.background.focus },
-  focusStyle: { outlineStyle: "none" as any },
-  focusVisibleStyle: { outlineStyle: "none" as any },
+  focusVisibleStyle: ensureFocusVisibleRing({ outlineOffset: -2 }),
   variants: {
     selected: {
       true: { backgroundColor: formInputColors.background.base },
       false: { backgroundColor: "transparent" },
     },
+    active: {
+      true: { backgroundColor: formInputColors.background.focus },
+      false: {},
+    },
     size: {
       "...size": (val: any) => ({ height: val }),
     },
   } as const,
 });
 
+function comboboxOptionId(baseId: string | undefined, index: number) {
+  return `${baseId ?? "combobox"}-opt-${index}`;
+}
+
+function comboboxListboxId(baseId: string | undefined) {
+  return `${baseId ?? "combobox"}-listbox`;
+}
+
+function listItemRingProps(keyboardRing: boolean) {
+  return keyboardRing ? keyboardFocusRingProps : { outlineWidth: 0 as const };
+}
+
 const GroupHeader = styled(Text, {
   name: "ComboboxGroupHeader",
   paddingHorizontal: "$3",
@@ -267,6 +289,8 @@ const ComboboxItem = memo(function ComboboxItem({
   index,
   isSelected,
   isActive,
+  keyboardRing,
+  optionId,
   suppressHover,
   handlers,
 }: {
@@ -274,6 +298,9 @@ const ComboboxItem = memo(function ComboboxItem({
   index: number;
   isSelected: boolean;
   isActive: boolean;
+  /** LC-71: inset ring on the activedescendant row during keyboard nav only. */
+  keyboardRing?: boolean;
+  optionId?: string;
   /** When true, disable hoverStyle so only isActive drives the highlight (avoids ghost highlight from stale hover) */
   suppressHover?: boolean;
   handlers: React.RefObject<ComboboxItemHandlers>;
@@ -291,6 +318,7 @@ const ComboboxItem = memo(function ComboboxItem({
         ctx.listItemsRef.current[index] = node as HTMLElement | null;
       }}
       {...itemProps}
+      id={optionId}
       data-combobox-index={index}
       data-active={isActive}
       onKeyDown={(e: React.KeyboardEvent) => {
@@ -304,9 +332,11 @@ const ComboboxItem = memo(function ComboboxItem({
       role="option"
       tabIndex={-1}
       selected={isSelected}
+      active={isActive}
       aria-selected={isSelected}
       data-state={isSelected ? "active" : "inactive"}
       size={ctx.knobProps.sizeToken}
+      {...listItemRingProps(Boolean(keyboardRing))}
       {...(suppressHover
         ? {
             hoverStyle: {
@@ -439,6 +469,7 @@ function FloatingComboboxCore({
   open: openProp,
   onOpenChange,
 }: FloatingComboboxCoreProps) {
+  if (isWeb) ensureKeyboardModalityTracking();
   const { t } = useTranslation();
   const inTableCell = useIsInTableCell();
   const describedBy = useFieldDescribedBy();
@@ -500,7 +531,7 @@ function FloatingComboboxCore({
 
   const filtered = useMemo(() => {
     if (onSearch || !filter) return options;
-    const query = filter.toLowerCase();
+    const query = filter.trim().toLowerCase();
     return options.filter(
       (option) =>
         option.label.toLowerCase().includes(query) ||
@@ -586,6 +617,11 @@ function FloatingComboboxCore({
   const searchInputRef = useRef<HTMLInputElement | null>(null);
   const listScrollRef = useRef<HTMLElement | null>(null);
   const keyboardNavRef = useRef(false);
+  const [listKeyboardRing, setListKeyboardRing] = useState(false);
+  const setKeyboardNav = useCallback((next: boolean) => {
+    keyboardNavRef.current = next;
+    setListKeyboardRing((prev) => (prev === next ? prev : next));
+  }, []);
   const lastMousePosRef = useRef<{ x: number; y: number } | null>(null);
   const currentMousePosRef = useRef({ x: 0, y: 0 });
   const lastKeyboardNavTimeRef = useRef(0);
@@ -643,6 +679,7 @@ function FloatingComboboxCore({
       lastMousePosRef.current = null;
       initialOrderRef.current = null;
       hasSearchedRef.current = false;
+      setKeyboardNav(false);
     }
   }, [open]);
 
@@ -670,7 +707,9 @@ function FloatingComboboxCore({
       const viewportHeight = window.innerHeight;
       const viewportWidth = window.innerWidth;
 
-      const minWidth = popoverWidth ?? triggerBounds.width + 8;
+      // OVERLAY_ANCHOR_GAP rule (theme/layoutTokens): the listbox matches the
+      // trigger width exactly and stays flush at triggerBounds.left below.
+      const minWidth = popoverWidth ?? triggerBounds.width;
       const maxWidth = viewportWidth - 20;
 
       dropdownElement.style.minWidth = `${minWidth}px`;
@@ -905,11 +944,11 @@ function FloatingComboboxCore({
     return () => document.removeEventListener("mousemove", onMove);
   }, [open, panel.refs]);
 
-  // When filter/list changes: truncate refs, sync activeIndex with cursor, clear keyboard mode.
+  // When filter/list changes: truncate refs, sync activeIndex with cursor.
+  // Typing is keyboard-origin (LC-71) — do not drop the list ring on filter.
   // After filter, the list remounts (Fragment key=filter) so mouseenter often doesn't fire for
   // elements that appear under a stationary cursor. Use elementFromPoint to set the correct index.
   useLayoutEffect(() => {
-    keyboardNavRef.current = false;
     const len = sortedFiltered.length + (showCreateOption ? 1 : 0);
     listItemsRef.current.length = len;
     justResetFromFilterRef.current = true;
@@ -941,7 +980,7 @@ function FloatingComboboxCore({
     activeIndex,
     onNavigate: (index) => {
       if (index !== null) {
-        keyboardNavRef.current = true;
+        setKeyboardNav(true);
         lastKeyboardNavTimeRef.current = Date.now();
         lastMousePosRef.current = { ...currentMousePosRef.current };
         setActiveIndex(index);
@@ -989,31 +1028,34 @@ function FloatingComboboxCore({
     [onValueChange, multiple, value, sortedFiltered],
   );
 
-  const handleListMouseMove = useCallback((e: React.MouseEvent) => {
-    const { clientX, clientY } = e;
-    currentMousePosRef.current = { x: clientX, y: clientY };
+  const handleListMouseMove = useCallback(
+    (e: React.MouseEvent) => {
+      const { clientX, clientY } = e;
+      currentMousePosRef.current = { x: clientX, y: clientY };
 
-    // Sync activeIndex from elementUnderCursor - list's own mousemove fires in correct context (works in iframes)
-    if (!keyboardNavRef.current && typeof document !== "undefined") {
-      const el = document.elementFromPoint(clientX, clientY);
-      const row = el?.closest?.("[data-combobox-index]");
-      const actualIndex = row?.getAttribute("data-combobox-index");
-      const list = sortedFilteredRef.current;
-      const len = list.length + (showCreateOptionRef.current ? 1 : 0);
-      const activeIdx = activeIndexRef.current;
-      const n = actualIndex != null ? Number(actualIndex) : null;
-      const next = n != null && n >= 0 && n < len ? n : activeIdx;
-      if (next !== activeIdx) setActiveIndex(next);
-    }
+      // Sync activeIndex from elementUnderCursor - list's own mousemove fires in correct context (works in iframes)
+      if (!keyboardNavRef.current && typeof document !== "undefined") {
+        const el = document.elementFromPoint(clientX, clientY);
+        const row = el?.closest?.("[data-combobox-index]");
+        const actualIndex = row?.getAttribute("data-combobox-index");
+        const list = sortedFilteredRef.current;
+        const len = list.length + (showCreateOptionRef.current ? 1 : 0);
+        const activeIdx = activeIndexRef.current;
+        const n = actualIndex != null ? Number(actualIndex) : null;
+        const next = n != null && n >= 0 && n < len ? n : activeIdx;
+        if (next !== activeIdx) setActiveIndex(next);
+      }
 
-    const last = lastMousePosRef.current;
-    const posChanged = last != null && (clientX !== last.x || clientY !== last.y);
-    if (!posChanged) return;
-    const now = Date.now();
-    if (now - lastKeyboardNavTimeRef.current < 200) return;
-    lastMousePosRef.current = { x: clientX, y: clientY };
-    keyboardNavRef.current = false;
-  }, []);
+      const last = lastMousePosRef.current;
+      const posChanged = last != null && (clientX !== last.x || clientY !== last.y);
+      if (!posChanged) return;
+      const now = Date.now();
+      if (now - lastKeyboardNavTimeRef.current < 200) return;
+      lastMousePosRef.current = { x: clientX, y: clientY };
+      setKeyboardNav(false);
+    },
+    [setKeyboardNav],
+  );
 
   const handlersRef = useRef({} as ComboboxItemHandlers);
 
@@ -1073,12 +1115,17 @@ function FloatingComboboxCore({
         event.key === "k"
       ) {
         event.preventDefault();
+        setKeyboardNav(true);
         setOpen(true);
         setActiveIndex(0);
       }
     },
   });
 
+  const listboxId = comboboxListboxId(id);
+  const activeDescendant =
+    open && activeIndex != null && activeIndex >= 0 ? comboboxOptionId(id, activeIndex) : undefined;
+
   const boxEventProps: Record<string, any> = {};
   for (const [key, val] of Object.entries(referenceProps)) {
     if (key === "ref" || typeof val === "function") boxEventProps[key] = val;
@@ -1088,11 +1135,17 @@ function FloatingComboboxCore({
   boxEventProps.role = "combobox";
   boxEventProps["aria-haspopup"] = "listbox";
   boxEventProps["aria-expanded"] = open;
+  boxEventProps["aria-controls"] = listboxId;
+  if (hideSearch) {
+    boxEventProps["aria-autocomplete"] = "list";
+    if (activeDescendant) boxEventProps["aria-activedescendant"] = activeDescendant;
+  }
   if (id) boxEventProps.id = id;
   if (ariaLabel) boxEventProps["aria-label"] = ariaLabel;
-  else if (hasLabel && id) boxEventProps["aria-labelledby"] = `${id}-label`;
-  // Standalone triggers (no label prop) still need a name (axe aria-input-field-name)
-  else if (placeholder) boxEventProps["aria-label"] = placeholder;
+  // A labelled trigger is already named: the sibling Label wires
+  // `aria-labelledby` onto this id itself, so naming it again here doubles the
+  // spoken name. Standalone triggers still need one (axe aria-input-field-name).
+  else if (!(hasLabel && id) && placeholder) boxEventProps["aria-label"] = placeholder;
   if (describedBy) boxEventProps["aria-describedby"] = describedBy;
 
   // Total navigable items includes the create option if shown
@@ -1106,7 +1159,7 @@ function FloatingComboboxCore({
       if (isDown || isUp) {
         e.preventDefault();
         e.stopPropagation();
-        keyboardNavRef.current = true;
+        setKeyboardNav(true);
         lastKeyboardNavTimeRef.current = Date.now();
         lastMousePosRef.current = { ...currentMousePosRef.current };
         setActiveIndex((prev) => {
@@ -1127,7 +1180,7 @@ function FloatingComboboxCore({
         });
       }
     },
-    [totalNavigableItems],
+    [totalNavigableItems, setKeyboardNav],
   );
 
   handlersRef.current = {
@@ -1146,7 +1199,7 @@ function FloatingComboboxCore({
       const isUp = event.key === "ArrowUp" || event.key === "k";
       if (isDown) {
         event.preventDefault();
-        keyboardNavRef.current = true;
+        setKeyboardNav(true);
         lastKeyboardNavTimeRef.current = Date.now();
         lastMousePosRef.current = { ...currentMousePosRef.current };
         setActiveIndex((prev) => {
@@ -1155,13 +1208,23 @@ function FloatingComboboxCore({
         });
       } else if (isUp) {
         event.preventDefault();
-        keyboardNavRef.current = true;
+        setKeyboardNav(true);
         lastKeyboardNavTimeRef.current = Date.now();
         lastMousePosRef.current = { ...currentMousePosRef.current };
         setActiveIndex((prev) => {
           const next = prev == null ? totalNavigableItems - 1 : prev - 1;
           return next < 0 ? totalNavigableItems - 1 : next;
         });
+      } else if (event.key === "Home") {
+        event.preventDefault();
+        setKeyboardNav(true);
+        lastKeyboardNavTimeRef.current = Date.now();
+        setActiveIndex(0);
+      } else if (event.key === "End") {
+        event.preventDefault();
+        setKeyboardNav(true);
+        lastKeyboardNavTimeRef.current = Date.now();
+        setActiveIndex(Math.max(0, totalNavigableItems - 1));
       } else if (event.key === "Enter" || event.key === " ") {
         event.preventDefault();
         if (activeIndex === createOptionIndex && showCreateOption) {
@@ -1190,6 +1253,7 @@ function FloatingComboboxCore({
       createOptionIndex,
       showCreateOption,
       multiple,
+      setKeyboardNav,
     ],
   );
 
@@ -1239,6 +1303,8 @@ function FloatingComboboxCore({
       width="100%"
       alignSelf="stretch"
       flexShrink={0}
+      outlineWidth={0}
+      focusVisibleStyle={ensureFocusVisibleRing({ outlineOffset: -2 })}
       style={{ display: "flex", alignItems: "stretch", width: "100%" }}
     >
       {triggerRender(multiple ? selectedOptions : selectedOption, open)}
@@ -1252,6 +1318,10 @@ function FloatingComboboxCore({
       cursor={disabled ? "not-allowed" : "pointer"}
       disabled={disabled}
       size={knobProps.sizeToken}
+      // One surface owner (OVERLAY_ANCHOR_GAP rule): the open panel covers
+      // this trigger (panel top = trigger top), so the trigger's outer focus
+      // ring must not paint — it would ghost around the panel's corners.
+      suppressFocusRing={open}
       {...(inTableCell
         ? // Chromeless in cells, but keep a ≥44px pressable target (SP-FIXED).
           { minHeight: 44 }
@@ -1354,6 +1424,7 @@ function FloatingComboboxCore({
             pointerEvents={panel.visible ? "auto" : "none"}
             {...getFloatingProps({
               ref: panel.refs.setFloating,
+              id: listboxId,
             })}
             style={
               {
@@ -1386,6 +1457,8 @@ function FloatingComboboxCore({
                   borderBottomColor={formCommonColors.divider}
                   borderRadius={0}
                   elevation={undefined}
+                  // LC-71: search is text-entry — ring the whole row (magnifier included).
+                  {...(isWeb ? { className: "mp-composite-ring" } : undefined)}
                 >
                   <InputParts.Section>
                     <InputParts.Icon adornment="leading">
@@ -1399,6 +1472,10 @@ function FloatingComboboxCore({
                       onChangeText={(text: string) => setInternalFilter(text)}
                       placeholder={searchPlaceholder}
                       onKeyDown={handleSearchKeyDown as any}
+                      aria-autocomplete="list"
+                      aria-controls={listboxId}
+                      aria-activedescendant={activeDescendant}
+                      aria-expanded={open}
                     />
                   </InputParts.Section>
                   {loading ? (
@@ -1455,8 +1532,10 @@ function FloatingComboboxCore({
                           key={option.value}
                           option={option}
                           index={index}
+                          optionId={comboboxOptionId(id, index)}
                           isSelected={isSelected(option.value)}
                           isActive={index === activeIndex}
+                          keyboardRing={index === activeIndex && listKeyboardRing}
                           suppressHover={activeIndex != null}
                           handlers={handlersRef}
                         />
@@ -1471,8 +1550,10 @@ function FloatingComboboxCore({
                             key={item.option.value}
                             option={item.option}
                             index={item.flatIndex}
+                            optionId={comboboxOptionId(id, item.flatIndex)}
                             isSelected={isSelected(item.option.value)}
                             isActive={item.flatIndex === activeIndex}
+                            keyboardRing={item.flatIndex === activeIndex && listKeyboardRing}
                             suppressHover={activeIndex != null}
                             handlers={handlersRef}
                           />
@@ -1482,10 +1563,13 @@ function FloatingComboboxCore({
                     <ComboboxRow
                       role="option"
                       tabIndex={-1}
+                      id={comboboxOptionId(id, createOptionIndex)}
                       selected={false}
+                      active={createOptionIndex === activeIndex}
                       size={knobProps.sizeToken}
                       data-combobox-index={createOptionIndex}
                       data-active={createOptionIndex === activeIndex}
+                      {...listItemRingProps(createOptionIndex === activeIndex && listKeyboardRing)}
                       backgroundColor={
                         createOptionIndex === activeIndex
                           ? formInputColors.background.focus
@@ -1518,14 +1602,16 @@ function FloatingComboboxCore({
                   )}
                 </Fragment>
               ) : showCreateOption ? (
-                <View
-                  flexDirection="row"
-                  alignItems="center"
-                  gap="$2"
-                  paddingHorizontal="$3"
-                  height={knobProps.sizeToken}
+                <ComboboxRow
+                  role="option"
+                  tabIndex={-1}
+                  id={comboboxOptionId(id, createOptionIndex)}
+                  selected={false}
+                  active={createOptionIndex === activeIndex}
+                  size={knobProps.sizeToken}
                   data-combobox-index={createOptionIndex}
                   data-active={createOptionIndex === activeIndex}
+                  {...listItemRingProps(createOptionIndex === activeIndex && listKeyboardRing)}
                   onPress={handleCreate}
                   hoverStyle={
                     activeIndex != null
@@ -1555,7 +1641,7 @@ function FloatingComboboxCore({
                   >
                     {createLabel.replace("{value}", filter.trim())}
                   </Text>
-                </View>
+                </ComboboxRow>
               ) : loading ? (
                 // Async search in flight with nothing loaded yet: a bounded
                 // loading row — never a premature "no results".
@@ -1670,6 +1756,7 @@ function NativeComboboxCore({
   open: openProp,
   onOpenChange,
 }: FloatingComboboxCoreProps) {
+  if (isWeb) ensureKeyboardModalityTracking();
   const { t } = useTranslation();
   const inTableCell = useIsInTableCell();
   const describedBy = useFieldDescribedBy();
@@ -1690,6 +1777,10 @@ function NativeComboboxCore({
   // Use external searchValue when provided, otherwise use internal filter
   const filter = searchValue !== undefined ? searchValue : internalFilter;
   const [activeIndex, setActiveIndex] = useState<number | null>(0);
+  const [listKeyboardRing, setListKeyboardRing] = useState(false);
+  const setKeyboardNav = useCallback((next: boolean) => {
+    setListKeyboardRing((prev) => (prev === next ? prev : next));
+  }, []);
   const listRef = useRef<HTMLElement | null>(null);
   const fieldA11y = useFieldA11y();
 
@@ -1735,7 +1826,7 @@ function NativeComboboxCore({
 
   const filtered = useMemo(() => {
     if (onSearch || !filter) return options;
-    const query = filter.toLowerCase();
+    const query = filter.trim().toLowerCase();
     return options.filter(
       (option) =>
         option.label.toLowerCase().includes(query) ||
@@ -1814,6 +1905,9 @@ function NativeComboboxCore({
 
   const totalItems = sortedFiltered.length + (showCreateOption ? 1 : 0);
   const createOptionIndex = showCreateOption ? sortedFiltered.length : -1;
+  const listboxId = comboboxListboxId(id);
+  const activeDescendant =
+    open && activeIndex != null && activeIndex >= 0 ? comboboxOptionId(id, activeIndex) : undefined;
 
   const handleSelect = useCallback(
     (option: ComboboxOption) => {
@@ -1837,6 +1931,7 @@ function NativeComboboxCore({
       const isUp = e.key === "ArrowUp" || e.key === "k";
       if (isDown) {
         e.preventDefault();
+        setKeyboardNav(true);
         listRef.current?.focus();
         setActiveIndex((prev) => {
           const next = prev == null ? 0 : prev + 1;
@@ -1844,14 +1939,23 @@ function NativeComboboxCore({
         });
       } else if (isUp) {
         e.preventDefault();
+        setKeyboardNav(true);
         listRef.current?.focus();
         setActiveIndex((prev) => {
           const next = prev == null ? totalItems - 1 : prev - 1;
           return next < 0 ? totalItems - 1 : next;
         });
+      } else if (e.key === "Home") {
+        e.preventDefault();
+        setKeyboardNav(true);
+        setActiveIndex(0);
+      } else if (e.key === "End") {
+        e.preventDefault();
+        setKeyboardNav(true);
+        setActiveIndex(Math.max(0, totalItems - 1));
       }
     },
-    [totalItems],
+    [totalItems, setKeyboardNav],
   );
 
   const handleListKeyDown = useCallback(
@@ -1861,16 +1965,26 @@ function NativeComboboxCore({
       const isUp = e.key === "ArrowUp" || e.key === "k";
       if (isDown) {
         e.preventDefault();
+        setKeyboardNav(true);
         setActiveIndex((prev) => {
           const next = prev == null ? 0 : prev + 1;
           return next >= totalItems ? 0 : next;
         });
       } else if (isUp) {
         e.preventDefault();
+        setKeyboardNav(true);
         setActiveIndex((prev) => {
           const next = prev == null ? totalItems - 1 : prev - 1;
           return next < 0 ? totalItems - 1 : next;
         });
+      } else if (e.key === "Home") {
+        e.preventDefault();
+        setKeyboardNav(true);
+        setActiveIndex(0);
+      } else if (e.key === "End") {
+        e.preventDefault();
+        setKeyboardNav(true);
+        setActiveIndex(Math.max(0, totalItems - 1));
       } else if (e.key === "Enter" || e.key === " ") {
         e.preventDefault();
         if (activeIndex === createOptionIndex && showCreateOption) {
@@ -1890,6 +2004,7 @@ function NativeComboboxCore({
       handleCreate,
       handleSelect,
       multiple,
+      setKeyboardNav,
     ],
   );
 
@@ -1960,8 +2075,17 @@ function NativeComboboxCore({
     // VoiceOver blob.
     <View
       ref={listRef as any}
-      {...(isWeb ? { tabIndex: 0, onKeyDown: handleListKeyDown } : undefined)}
-      outlineStyle="none"
+      {...(isWeb
+        ? // role="listbox" is a valid ARIA role but outside RN's `Role` union;
+          // this web-only bag forwards it to the DOM node (house Record cast).
+          ({
+            tabIndex: 0,
+            onKeyDown: handleListKeyDown,
+            role: "listbox",
+            id: listboxId,
+          } as Record<string, unknown>)
+        : undefined)}
+      outlineWidth={0}
       // Native sheet: flex={1} inside FloatingPanel ScrollView collapses rows.
     >
       {searchError ? (
@@ -1988,11 +2112,20 @@ function NativeComboboxCore({
                 alignItems="center"
                 gap="$2"
                 paddingHorizontal="$3"
+                id={comboboxOptionId(id, i)}
+                role="option"
+                aria-selected={selected}
+                data-combobox-index={i}
+                data-active={active}
+                {...listItemRingProps(active && listKeyboardRing)}
                 {...(option.description
                   ? { minHeight: knobProps.sizeToken, paddingVertical: "$2" }
                   : { height: knobProps.sizeToken })}
                 onPress={isWeb ? () => handleSelect(option) : undefined}
-                onMouseEnter={() => setActiveIndex(i)}
+                onMouseEnter={() => {
+                  setKeyboardNav(false);
+                  setActiveIndex(i);
+                }}
                 {...(!isWeb ? { pointerEvents: "none" as const } : {})}
                 hoverStyle={
                   activeIndex != null
@@ -2076,8 +2209,16 @@ function NativeComboboxCore({
               gap="$2"
               paddingHorizontal="$3"
               height={knobProps.sizeToken}
+              role="option"
+              id={comboboxOptionId(id, createOptionIndex)}
+              data-combobox-index={createOptionIndex}
+              data-active={createOptionIndex === activeIndex}
+              {...listItemRingProps(createOptionIndex === activeIndex && listKeyboardRing)}
               onPress={handleCreate}
-              onMouseEnter={() => setActiveIndex(createOptionIndex)}
+              onMouseEnter={() => {
+                setKeyboardNav(false);
+                setActiveIndex(createOptionIndex);
+              }}
               hoverStyle={
                 activeIndex != null
                   ? {
@@ -2113,8 +2254,16 @@ function NativeComboboxCore({
           gap="$2"
           paddingHorizontal="$3"
           height={knobProps.sizeToken}
+          role="option"
+          id={comboboxOptionId(id, createOptionIndex)}
+          data-combobox-index={createOptionIndex}
+          data-active={createOptionIndex === activeIndex}
+          {...listItemRingProps(createOptionIndex === activeIndex && listKeyboardRing)}
           onPress={handleCreate}
-          onMouseEnter={() => setActiveIndex(createOptionIndex)}
+          onMouseEnter={() => {
+            setKeyboardNav(false);
+            setActiveIndex(createOptionIndex);
+          }}
           hoverStyle={
             activeIndex != null
               ? {
@@ -2173,6 +2322,8 @@ function NativeComboboxCore({
       width="100%"
       alignSelf="stretch"
       flexShrink={0}
+      outlineWidth={0}
+      focusVisibleStyle={ensureFocusVisibleRing({ outlineOffset: -2 })}
       style={{ display: "flex", alignItems: "stretch", width: "100%" }}
     >
       {triggerRender(multiple ? selectedOptions : selectedOption, open)}
@@ -2185,6 +2336,10 @@ function NativeComboboxCore({
       cursor={disabled ? "not-allowed" : "pointer"}
       disabled={disabled}
       size={knobProps.sizeToken}
+      // One surface owner (OVERLAY_ANCHOR_GAP rule): the open FloatingPanel
+      // covers this trigger (panel top = trigger top), so the trigger's outer
+      // focus ring must not paint — it would ghost around the panel's corners.
+      suppressFocusRing={open}
       {...(inTableCell
         ? // Chromeless in cells, but keep a ≥44px pressable target (SP-FIXED).
           { minHeight: 44 }
@@ -2203,9 +2358,13 @@ function NativeComboboxCore({
             role: "combobox" as const,
             "aria-haspopup": "listbox",
             "aria-expanded": open,
-            // Standalone (no label): fall back to placeholder for the name
+            "aria-controls": listboxId,
+            "aria-activedescendant": hideSearch ? activeDescendant : undefined,
+            "aria-autocomplete": hideSearch ? ("list" as const) : undefined,
+            // Standalone (no label): fall back to placeholder for the name.
+            // Labelled: the sibling Label wires `aria-labelledby` onto this id
+            // itself — naming it here too doubles the spoken name.
             "aria-label": ariaLabel ?? (!hasLabel ? placeholder : undefined),
-            "aria-labelledby": !ariaLabel && hasLabel && id ? `${id}-label` : undefined,
             "aria-describedby": describedBy,
             tabIndex: disabled ? -1 : 0,
           }
@@ -2219,6 +2378,7 @@ function NativeComboboxCore({
           e.code === "Space"
         ) {
           e.preventDefault();
+          setKeyboardNav(true);
           if (!open) handleOpenChange(true);
         }
       }}