@multiplatform.one/forms 7.4.0 → 7.5.0

package/src/fields/Combobox/index.tsx

@@ -31,6 +31,7 @@ import {
   ensureKeyboardModalityTracking,
   keyboardFocusRingProps,
   menuRowFrame,
+  useGlyphColor,
   useResolvedKnobs,
 } from "@multiplatform.one/theme";
 import type { LabelProps, SizeTokens } from "tamagui";
@@ -41,7 +42,7 @@ import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout, useFieldA11y, useFieldDescribedBy } from "../../fieldLayout";
 import { Input as InputParts } from "../../InputParts";
 import { Spinner } from "../../Spinner";
-import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { formCommonColors, formInputColors, formSelectedColors } from "../../shared/colorRamps";
 import {
   getFieldError,
   getFieldHeight,
@@ -64,6 +65,7 @@ import {
 import { zIndex } from "../../shared/zIndex";
 import { useDragScroll } from "../../shared/useDragScroll";
 import { useIsInTableCell } from "../../shared/tableCellContext";
+import { orderOptionsBySelected, type SelectedOrder } from "../selectedOrder";
 
 // ── Styled row ───────────────────────────────────────────────
 
@@ -105,6 +107,29 @@ function listItemRingProps(keyboardRing: boolean) {
   return keyboardRing ? keyboardFocusRingProps : { outlineWidth: 0 as const };
 }
 
+/**
+ * Resolve the LC-05 selected-mark token to a real paint (MPO-63).
+ *
+ * MPO-65 put `formSelectedColors.mark` ("$accentBackground") on the tick, but a
+ * phosphor glyph is NOT a Tamagui styled component: its IconBase writes the
+ * prop straight into `<svg fill>`. On web "$accentBackground" is not a valid
+ * paint, so the declaration is dropped and `fill` falls back to its initial
+ * value — an opaque BLACK tick, measured 1.19:1 against the `$color2` selected
+ * row. On native the shim can only resolve a token the theme in scope actually
+ * carries, and the component sub-themes carry no `accentBackground` at all.
+ * Resolve it here, where the value becomes a paint — the same shape as
+ * `mutedColor` for the search glyph. Keyed off the ramp constant so the token
+ * stays declared once in colorRamps, and degrading to `$color` ink rather than
+ * black when a narrow sub-theme has no accent step.
+ */
+function useSelectedMarkColor(): string {
+  const theme = useTheme();
+  const entry = (theme as unknown as Record<string, { val?: string } | undefined>)[
+    formSelectedColors.mark.slice(1)
+  ];
+  return entry?.val ?? theme.color?.val ?? "currentColor";
+}
+
 const GroupHeader = styled(Text, {
   name: "ComboboxGroupHeader",
   paddingHorizontal: "$3",
@@ -180,6 +205,11 @@ export interface ComboboxProps {
   popoverWidth?: number;
   tabIndex?: number;
   multiple?: boolean;
+  /**
+   * Multi-select list order. `selected-first` (default) pins chosen rows to the
+   * top, alphabetically among themselves. `stable` keeps `options` order.
+   */
+  selectedOrder?: SelectedOrder;
   /** Show dismiss button on badges to remove selected items (only applies when multiple=true) */
   dismissible?: boolean;
   /** When true, renders a skeleton placeholder instead of the combobox */
@@ -281,6 +311,8 @@ interface ComboboxItemHandlers {
   onItemKeyDown?: (e: React.KeyboardEvent, index: number) => void;
   knobProps: KnobProps;
   textColor: string;
+  /** LC-05 selected mark, already resolved to a paint. */
+  markColor: string;
   listItemsRef: React.RefObject<Array<HTMLElement | null>>;
 }
 
@@ -395,7 +427,7 @@ const ComboboxItem = memo(function ComboboxItem({
           {option.label}
         </Text>
       )}
-      {isSelected && <CheckIcon size={14} />}
+      {isSelected && <CheckIcon size={14} color={ctx.markColor} />}
     </ComboboxRow>
   );
 });
@@ -426,6 +458,7 @@ interface FloatingComboboxCoreProps {
   trigger?: (selected: ComboboxOption | ComboboxOption[] | undefined, open: boolean) => ReactNode;
   knobProps: KnobProps;
   multiple?: boolean;
+  selectedOrder?: SelectedOrder;
   dismissible?: boolean;
   creatable?: boolean;
   onCreate?: (value: string) => ComboboxOption | void;
@@ -460,6 +493,7 @@ function FloatingComboboxCore({
   trigger: triggerRender,
   knobProps,
   multiple,
+  selectedOrder,
   dismissible,
   creatable,
   onCreate,
@@ -473,6 +507,7 @@ function FloatingComboboxCore({
   const { t } = useTranslation();
   const inTableCell = useIsInTableCell();
   const describedBy = useFieldDescribedBy();
+  const glyphColor = useGlyphColor();
   const [internalOpen, setInternalOpen] = useState(false);
   // Use external open state when provided (controlled), otherwise use internal state
   const open = openProp !== undefined ? openProp : internalOpen;
@@ -492,6 +527,7 @@ function FloatingComboboxCore({
   const [activeIndex, setActiveIndex] = useState<number | null>(null);
 
   const textColor = knobProps.textAccentColor;
+  const markColor = useSelectedMarkColor();
 
   const labelCacheRef = useRef<Map<string, string>>(new Map());
   for (const o of options) labelCacheRef.current.set(o.value, o.label);
@@ -578,22 +614,17 @@ function FloatingComboboxCore({
     if (hasSearchedRef.current) return filtered; // user searched then cleared; keep natural order
     if (initialOrderRef.current === null) {
       const current = Array.isArray(value) ? value : value ? [value] : [];
-      const snap = new Set(current);
-      if (snap.size === 0) {
-        initialOrderRef.current = filtered;
-      } else {
-        const first = filtered
-          .filter((o) => snap.has(o.value))
-          .sort((a, b) => a.label.localeCompare(b.label));
-        const rest = filtered.filter((o) => !snap.has(o.value));
-        initialOrderRef.current = [...first, ...rest];
-      }
+      initialOrderRef.current = orderOptionsBySelected(filtered, current, selectedOrder);
     }
     return initialOrderRef.current;
-  }, [filtered, filter, open, multiple, value]);
-
-  // Group options for rendering with headers (only when not in multiple mode)
-  const { items: groupedItems, flatOptions: _flatOptions } = useMemo(
+  }, [filtered, filter, open, multiple, value, selectedOrder]);
+
+  // Group for render. `activeIndex` indexes `navigableOptions` — selectable
+  // rows in that same order — not `sortedFiltered`. `groupComboboxOptions`
+  // clusters by group and assigns `flatIndex` on the reordered list; keeping
+  // activeIndex on sortedFiltered while rendering headers silently breaks
+  // ArrowUp/ArrowDown (MPO-38 AC-6).
+  const { items: groupedItems, flatOptions: navigableOptions } = useMemo(
     () => groupComboboxOptions(sortedFiltered),
     [sortedFiltered],
   );
@@ -686,8 +717,8 @@ function FloatingComboboxCore({
   // Document-level Enter/Escape to close (catches keys when focus is on list, not just search)
   const activeIndexRef = useRef(activeIndex);
   activeIndexRef.current = activeIndex;
-  const sortedFilteredRef = useRef(sortedFiltered);
-  sortedFilteredRef.current = sortedFiltered;
+  const navigableOptionsRef = useRef(navigableOptions);
+  navigableOptionsRef.current = navigableOptions;
   const showCreateOptionRef = useRef(showCreateOption);
   showCreateOptionRef.current = showCreateOption;
   const multipleRef = useRef(multiple);
@@ -726,20 +757,33 @@ function FloatingComboboxCore({
       const contentHeight = searchBarHeight + listContentHeight + borderHeight;
 
       const isDropup = panel.placement.startsWith("top");
+      // Cover ruling (MPO-38). A single-value Combobox covers its trigger:
+      // the trigger shows one label, and the panel replaces it in place
+      // (macOS-style aligned listbox). A MULTI-select trigger carries live
+      // state — the selected chips and the query you are typing — so a panel
+      // drawn over it hides the very thing you are editing. Measured before
+      // this landed: panel top == trigger top and panel width == trigger
+      // width with `multiple` set, chips and filter text both covered.
+      // A trigger carrying live state keeps its own surface; the panel
+      // attaches flush on its BOTTOM edge instead.
+      const coversTrigger = !multipleRef.current;
       let top: number;
 
       if (searchTopRef.current === null) {
+        // The edge the panel hangs from: the trigger's far edge when it
+        // covers, its near edge when it only attaches (MPO-38).
+        const dropupAnchor = coversTrigger ? triggerBounds.bottom : triggerBounds.top;
         if (isDropup) {
-          const availableAbove = triggerBounds.bottom - panelViewportPadding;
+          const availableAbove = dropupAnchor - panelViewportPadding;
           const initialHeight = Math.min(contentHeight, availableAbove);
-          top = triggerBounds.bottom - initialHeight;
+          top = dropupAnchor - initialHeight;
         } else {
-          top = triggerBounds.top;
+          top = coversTrigger ? triggerBounds.top : triggerBounds.bottom;
         }
         searchTopRef.current = top;
 
         const maxAvailable = isDropup
-          ? triggerBounds.bottom - top
+          ? dropupAnchor - top
           : viewportHeight - top - panelViewportPadding;
         let height = Math.min(contentHeight, maxAvailable);
         height = Math.max(120, height);
@@ -796,13 +840,17 @@ function FloatingComboboxCore({
         // For dropdowns: don't move the panel below the trigger
         // For dropups: don't move the panel above where it started
         if (!isDropup) {
-          // Keep the panel starting at or above the trigger
-          top = Math.min(top, triggerTop);
+          // Keep the panel starting at or above the trigger. A non-covering
+          // (multi-select) panel may not grow upward at all — that is what
+          // would swallow the chips (MPO-38).
+          top = coversTrigger ? Math.min(top, triggerTop) : triggerBottom;
         } else {
-          // Keep the panel ending at or below the trigger
+          // Keep the panel ending at or below the trigger; a non-covering
+          // drop-up stops at the trigger's TOP edge.
+          const floor = coversTrigger ? triggerBottom : triggerTop;
           const panelBottom = top + height;
-          if (panelBottom < triggerBottom) {
-            top = triggerBottom - height;
+          if (panelBottom < floor) {
+            top = floor - height;
           }
         }
         searchTopRef.current = top;
@@ -931,7 +979,7 @@ function FloatingComboboxCore({
       if (!el || !floating.contains(el)) return;
       const row = el.closest?.("[data-combobox-index]");
       const actualIndex = row?.getAttribute("data-combobox-index");
-      const list = sortedFilteredRef.current;
+      const list = navigableOptionsRef.current;
       const len = list.length + (showCreateOptionRef.current ? 1 : 0);
       const activeIdx = activeIndexRef.current;
       const n = actualIndex != null ? Number(actualIndex) : null;
@@ -949,7 +997,7 @@ function FloatingComboboxCore({
   // 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(() => {
-    const len = sortedFiltered.length + (showCreateOption ? 1 : 0);
+    const len = navigableOptions.length + (showCreateOption ? 1 : 0);
     listItemsRef.current.length = len;
     justResetFromFilterRef.current = true;
 
@@ -970,7 +1018,7 @@ function FloatingComboboxCore({
     } else {
       setActiveIndex(0);
     }
-  }, [filter, sortedFiltered.length, showCreateOption]);
+  }, [filter, navigableOptions.length, showCreateOption]);
 
   const click = useClick(panel.context, { event: "mousedown", keyboardHandlers: false });
   const dismiss = useDismiss(panel.context);
@@ -1010,7 +1058,7 @@ function FloatingComboboxCore({
         if (event?.shiftKey && lastSelectedIndexRef.current != null) {
           const from = Math.min(lastSelectedIndexRef.current, index);
           const to = Math.max(lastSelectedIndexRef.current, index);
-          const rangeValues = sortedFiltered.slice(from, to + 1).map((o) => o.value);
+          const rangeValues = navigableOptions.slice(from, to + 1).map((o) => o.value);
           const merged = new Set([...current, ...rangeValues]);
           onValueChange?.([...merged]);
         } else {
@@ -1025,7 +1073,7 @@ function FloatingComboboxCore({
         setOpen(false);
       }
     },
-    [onValueChange, multiple, value, sortedFiltered],
+    [onValueChange, multiple, value, navigableOptions],
   );
 
   const handleListMouseMove = useCallback(
@@ -1038,7 +1086,7 @@ function FloatingComboboxCore({
         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 list = navigableOptionsRef.current;
         const len = list.length + (showCreateOptionRef.current ? 1 : 0);
         const activeIdx = activeIndexRef.current;
         const n = actualIndex != null ? Number(actualIndex) : null;
@@ -1084,7 +1132,7 @@ function FloatingComboboxCore({
         e.preventDefault();
         e.stopPropagation();
         const idx = activeIndexRef.current;
-        const list = sortedFilteredRef.current;
+        const list = navigableOptionsRef.current;
         const createIdx = showCreateOptionRef.current ? list.length : -1;
         if (idx === createIdx && showCreateOptionRef.current) {
           handleCreate();
@@ -1149,8 +1197,8 @@ function FloatingComboboxCore({
   if (describedBy) boxEventProps["aria-describedby"] = describedBy;
 
   // Total navigable items includes the create option if shown
-  const totalNavigableItems = sortedFiltered.length + (showCreateOption ? 1 : 0);
-  const createOptionIndex = showCreateOption ? sortedFiltered.length : -1;
+  const totalNavigableItems = navigableOptions.length + (showCreateOption ? 1 : 0);
+  const createOptionIndex = showCreateOption ? navigableOptions.length : -1;
 
   const handleItemKeyDown = useCallback(
     (e: React.KeyboardEvent, _index: number) => {
@@ -1190,6 +1238,7 @@ function FloatingComboboxCore({
     onItemKeyDown: handleItemKeyDown,
     knobProps,
     textColor,
+    markColor,
     listItemsRef,
   };
 
@@ -1231,8 +1280,8 @@ function FloatingComboboxCore({
           handleCreate();
         } else if (event.key === "Enter" && multiple && hasSelectedSinceOpenRef.current) {
           setOpen(false);
-        } else if (activeIndex != null && sortedFiltered[activeIndex]) {
-          handleSelect(sortedFiltered[activeIndex], activeIndex);
+        } else if (activeIndex != null && navigableOptions[activeIndex]) {
+          handleSelect(navigableOptions[activeIndex], activeIndex);
           if (event.key === "Enter" || !multiple) setOpen(false);
         } else {
           setOpen(false);
@@ -1245,7 +1294,7 @@ function FloatingComboboxCore({
       }
     },
     [
-      sortedFiltered,
+      navigableOptions,
       activeIndex,
       handleSelect,
       handleCreate,
@@ -1318,10 +1367,12 @@ 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}
+      // One surface owner: a single-value 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. A multi-select panel
+      // attaches below instead (MPO-38), leaving the trigger on screen and
+      // focusable, so it keeps its ring.
+      suppressFocusRing={open && !multiple}
       {...(inTableCell
         ? // Chromeless in cells, but keep a ≥44px pressable target (SP-FIXED).
           { minHeight: 44 }
@@ -1408,7 +1459,7 @@ function FloatingComboboxCore({
         </View>
       )}
       <View paddingInlineEnd="$2" alignSelf="center">
-        <CaretDownIcon size={16} />
+        <CaretDownIcon size={16} color={glyphColor} />
       </View>
     </InputParts.Box>
   );
@@ -1524,41 +1575,31 @@ function FloatingComboboxCore({
                     {searchError}
                   </Text>
                 </View>
-              ) : sortedFiltered.length > 0 ? (
+              ) : navigableOptions.length > 0 ? (
                 <Fragment key={filter}>
-                  {multiple
-                    ? sortedFiltered.map((option, index) => (
-                        <ComboboxItem
-                          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}
-                        />
-                      ))
-                    : groupedItems.map((item, _i) =>
-                        item.type === "header" ? (
-                          <GroupHeader key={`header-${item.label}`} color={textColor}>
-                            {item.label}
-                          </GroupHeader>
-                        ) : (
-                          <ComboboxItem
-                            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}
-                          />
-                        ),
-                      )}
+                  {groupedItems.map((item) =>
+                    item.type === "header" ? (
+                      <GroupHeader
+                        key={`header-${item.label}`}
+                        color={textColor}
+                        data-combobox-group-header=""
+                      >
+                        {item.label}
+                      </GroupHeader>
+                    ) : (
+                      <ComboboxItem
+                        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}
+                      />
+                    ),
+                  )}
                   {showCreateOption && (
                     <ComboboxRow
                       role="option"
@@ -1747,6 +1788,7 @@ function NativeComboboxCore({
   trigger: triggerRender,
   knobProps,
   multiple,
+  selectedOrder,
   dismissible,
   creatable,
   onCreate,
@@ -1760,6 +1802,7 @@ function NativeComboboxCore({
   const { t } = useTranslation();
   const inTableCell = useIsInTableCell();
   const describedBy = useFieldDescribedBy();
+  const glyphColor = useGlyphColor();
   const [internalOpen, setInternalOpen] = useState(false);
   // Use external open state when provided (controlled), otherwise use internal state
   const open = openProp !== undefined ? openProp : internalOpen;
@@ -1787,6 +1830,7 @@ function NativeComboboxCore({
   const textColor = knobProps.textAccentColor;
   const theme = useTheme();
   const mutedColor = theme.color7?.val ?? "$color7";
+  const markColor = useSelectedMarkColor();
 
   const labelCacheRef = useRef<Map<string, string>>(new Map());
   for (const o of options) labelCacheRef.current.set(o.value, o.label);
@@ -1867,17 +1911,12 @@ function NativeComboboxCore({
   const hasScrollableContent = Boolean(onSearch) || filtered.length > 6;
   const sheetTransition = knobProps.transition ?? "medium";
 
-  // Selected item(s) at top when filter empty (single + multi); reset to normal order when searching
+  // Selected item(s) at top when filter empty (single + multi); `stable` never rearranges
   const sortedFiltered = useMemo(() => {
     if (filter.trim()) return filtered;
     const current = Array.isArray(value) ? value : value ? [value] : [];
-    if (current.length === 0) return filtered;
-    const first = filtered
-      .filter((o) => current.includes(o.value))
-      .sort((a, b) => getLabel(a.value).localeCompare(getLabel(b.value)));
-    const rest = filtered.filter((o) => !current.includes(o.value));
-    return [...first, ...rest];
-  }, [filtered, value, filter, getLabel]);
+    return orderOptionsBySelected(filtered, current, selectedOrder);
+  }, [filtered, value, filter, selectedOrder]);
 
   const searchCleanupRef = useRef<(() => void) | null>(null);
   useEffect(() => {
@@ -2181,12 +2220,16 @@ function NativeComboboxCore({
                     {option.label}
                   </Text>
                 )}
-                {selected && <CheckIcon size={14} />}
+                {selected && <CheckIcon size={14} color={markColor} />}
               </View>
             );
             return (
               <View key={option.value}>
-                {showGroupHeader && <GroupHeader color={textColor}>{option.group}</GroupHeader>}
+                {showGroupHeader && (
+                  <GroupHeader color={textColor} data-combobox-group-header="">
+                    {option.group}
+                  </GroupHeader>
+                )}
                 {isWeb ? (
                   optionRow
                 ) : (
@@ -2336,10 +2379,11 @@ 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}
+      // One surface owner: a single-value 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. A multi-select
+      // panel attaches below instead (MPO-38), so it keeps its ring.
+      suppressFocusRing={open && !multiple}
       {...(inTableCell
         ? // Chromeless in cells, but keep a ≥44px pressable target (SP-FIXED).
           { minHeight: 44 }
@@ -2448,7 +2492,7 @@ function NativeComboboxCore({
         </View>
       )}
       <View paddingInlineEnd="$2" alignSelf="center">
-        <CaretDownIcon size={16} />
+        <CaretDownIcon size={16} color={glyphColor} />
       </View>
     </InputParts.Box>
   );
@@ -2529,6 +2573,7 @@ export function Combobox({
   popoverWidth,
   tabIndex: tabIndexProp,
   multiple,
+  selectedOrder,
   dismissible,
   skeleton,
   compact,
@@ -2646,6 +2691,7 @@ export function Combobox({
         trigger={trigger}
         knobProps={knobProps}
         multiple={multiple}
+        selectedOrder={selectedOrder}
         dismissible={dismissible}
         creatable={creatable}
         onCreate={onCreate}