@proyecto-viviana/ui 0.6.2 → 0.8.0-rc.0

package/src/combobox/index.tsx

@@ -1,23 +1,43 @@
 // @ts-nocheck
+
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Ported to SolidJS for Proyecto Viviana; based on packages/@react-spectrum/s2/src/ComboBox.tsx
+
+// Port of packages/@react-spectrum/s2/src/ComboBox.tsx.
+
 import {
-  type JSX,
   createContext,
   createEffect,
+  createMemo,
   createSignal,
   createUniqueId,
-  mergeProps,
   onCleanup,
   Show,
-  splitProps,
   useContext,
+  createTrackedEffect,
 } from "solid-js";
-import { createHover } from "@proyecto-viviana/solidaria";
+import type { JSX } from "@solidjs/web";
+import {
+  mergeProps,
+  createHover,
+  createFocusVisibleListener,
+  getInteractionModality,
+} from "@proyecto-viviana/solidaria";
 import {
   ComboBox as HeadlessComboBox,
   ComboBoxButton as HeadlessComboBoxButton,
   ComboBoxContext as HeadlessComboBoxContext,
-  ComboBoxDescription as HeadlessComboBoxDescription,
-  ComboBoxErrorMessage as HeadlessComboBoxErrorMessage,
   ComboBoxInput as HeadlessComboBoxInput,
   ComboBoxLabel as HeadlessComboBoxLabel,
   ComboBoxListBox as HeadlessComboBoxListBox,
@@ -25,7 +45,10 @@ import {
   ComboBoxTag as HeadlessComboBoxTag,
   ComboBoxTagGroup as HeadlessComboBoxTagGroup,
   ListBoxSection as HeadlessListBoxSection,
-  Popover as HeadlessPopover,
+  Text as HeadlessText,
+  TextContext as HeadlessTextContext,
+  ListLayout,
+  Virtualizer,
   defaultContainsFilter,
   type ListBoxSectionProps as HeadlessListBoxSectionProps,
   type ComboBoxButtonProps as HeadlessComboBoxButtonProps,
@@ -41,19 +64,18 @@ import {
   type ComboBoxTagGroupProps as HeadlessComboBoxTagGroupProps,
   type ComboBoxTagProps as HeadlessComboBoxTagProps,
 } from "@proyecto-viviana/solidaria-components";
-import type { FilterFn, Key, MenuTriggerAction } from "@proyecto-viviana/solid-stately";
+import type {
+  FilterFn,
+  Key,
+  LoadingState,
+  MenuTriggerAction,
+} from "@proyecto-viviana/solid-stately";
+import { ProgressCircle } from "../progress/ProgressCircle";
 import type { StyleString } from "../style";
-import {
-  baseColor,
-  focusRing,
-  fontRelative,
-  lightDark,
-  setColorScheme,
-  space,
-  style,
-} from "../style" with { type: "macro" };
+import { baseColor, focusRing, fontRelative, space, style } from "../style" with { type: "macro" };
 import { edgeToText } from "../style/spectrum-theme" with { type: "macro" };
 import {
+  centerPadding,
   control,
   controlBorderRadius,
   controlFont,
@@ -63,14 +85,20 @@ import {
   fieldLabel,
   getAllowedOverrides,
 } from "../s2-internal/style-utils" with { type: "macro" };
-import { CenterBaseline } from "../icon/center-baseline";
+import { CenterBaseline, centerBaseline } from "../icon/center-baseline";
+import { IconContext } from "../icon/spectrum-icon";
+import { AvatarContext } from "../avatar";
 import { FieldPrefix, PrefixInputProvider } from "../field/prefix";
 import AlertTriangleIcon from "../icon/s2wf-icons/AlertTriangleIcon";
 import AsteriskIcon from "../icon/ui-icons/Asterisk";
+import { createStringFormatter } from "@proyecto-viviana/solidaria";
+import { s2IntlStrings } from "../intl";
 import CheckmarkIcon from "../icon/ui-icons/Checkmark";
 import ChevronIcon from "../icon/ui-icons/Chevron";
 import { pressScale } from "../pressScale";
-import { useProviderProps, useTheme } from "../provider";
+import { useProviderProps } from "../provider";
+import { Popover } from "../popover";
+import { createMediaQuery } from "../utils/createMediaQuery";
 import { Divider } from "../divider";
 import { FormContext, useFormProps, useIsInForm } from "../form";
 import {
@@ -82,12 +110,23 @@ import {
   type RefLike,
   type SpectrumContextValue,
 } from "../button/spectrum-context";
+import { HelpText } from "../form/HelpText";
+import { HeaderContext, HeadingContext, TextContext } from "../text";
+import { splitProps } from "@proyecto-viviana/solidaria/utils";
+import {
+  menuItemDescription,
+  menuItemIcon,
+  menuItemIconCenterWrapper,
+  menuItemLabel,
+  menuSectionHeading,
+} from "../menu/s2-menu-styles";
 
 export type ComboBoxSize = "S" | "M" | "L" | "XL" | "sm" | "md" | "lg";
 type S2ComboBoxSize = "S" | "M" | "L" | "XL";
 export type ComboBoxLabelPosition = "top" | "side";
 export type ComboBoxLabelAlign = "start" | "end";
 export type ComboBoxNecessityIndicator = "icon" | "label";
+export type ComboBoxLoadingState = LoadingState;
 
 export interface ComboBoxProps<T> extends Omit<
   HeadlessComboBoxProps<T>,
@@ -112,6 +151,10 @@ export interface ComboBoxProps<T> extends Omit<
   align?: "start" | "end";
   menuWidth?: number;
   shouldFlip?: boolean;
+  /** The current loading state of the ComboBox. Determines whether or not the progress circle should be shown. */
+  loadingState?: LoadingState;
+  /** Handler that is called when more items should be loaded. */
+  onLoadMore?: () => void | Promise<void>;
   children?: JSX.Element | ((item: T) => JSX.Element);
   slot?: string | null;
   ref?: RefLike<HTMLDivElement>;
@@ -329,46 +372,95 @@ const comboBoxListBox = style<ComboBoxListBoxRenderProps & { size?: S2ComboBoxSi
   fontFamily: "sans",
   fontSize: controlFont(),
   outlineStyle: "none",
-  margin: 0,
-  padding: 8,
-  listStyleType: "none",
 });
 
-const comboBoxPopover = style({
-  ...setColorScheme(),
-  "--s2-container-bg": {
-    type: "backgroundColor",
-    value: {
-      default: "layer-2",
-      forcedColors: "Background",
+// S2 ComboBox.tsx:765-768 — width additions on the composed Popover `styles` prop.
+const comboBoxMenuWidth = style({
+  minWidth: "--trigger-width",
+  width: "--trigger-width",
+});
+
+const comboBoxListBoxFrame = style({
+  display: "flex",
+  width: "full",
+  height: "full",
+});
+
+// S2 ComboBox.tsx:315-328 — Header slot styles for listbox sections. Picker
+// imports the same export (`s2/Picker.tsx:71`).
+export const listboxHeader = style<{ size?: S2ComboBoxSize }>({
+  color: "neutral",
+  boxSizing: "border-box",
+  minHeight: controlSize(),
+  paddingY: centerPadding(),
+  marginX: {
+    size: {
+      S: `[${edgeToText(24)}]`,
+      M: `[${edgeToText(32)}]`,
+      L: `[${edgeToText(40)}]`,
+      XL: `[${edgeToText(48)}]`,
     },
   },
-  backgroundColor: "--s2-container-bg",
-  // Glasselated: frost the scene behind the surface — the container bg is the
-  // translucent `--surface-card`; the blur is what makes it read as glass.
-  backdropFilter: "var(--blur-card)",
-  boxShadow: "elevated",
-  borderRadius: "panel",
+});
+
+const comboBoxLoadingWrapper = style({
+  gridColumnStart: 1,
+  gridColumnEnd: -1,
   display: "flex",
-  padding: 0,
-  minHeight: 0,
-  overflow: "visible",
-  boxSizing: "border-box",
-  isolation: "isolate",
-  outlineStyle: "solid",
-  outlineWidth: 1,
-  outlineColor: {
-    default: lightDark("transparent-white-25", "gray-200"),
-    forcedColors: "ButtonBorder",
+  alignItems: "center",
+  justifyContent: "center",
+  marginY: 8,
+});
+
+const comboBoxProgressCircle = style<{ isInput?: boolean }>({
+  size: "1lh",
+  marginStart: {
+    isInput: "text-to-visual",
   },
 });
 
-const comboBoxListBoxFrame = style({
+const comboBoxEmptyStateText = style<{ size?: S2ComboBoxSize }>({
+  height: {
+    size: {
+      S: 24,
+      M: 32,
+      L: 40,
+      XL: 48,
+    },
+  },
+  font: {
+    size: {
+      S: "ui-sm",
+      M: "ui",
+      L: "ui-lg",
+      XL: "ui-xl",
+    },
+  },
   display: "flex",
-  width: "full",
-  height: "full",
+  alignItems: "center",
+  paddingStart: "edge-to-text",
 });
 
+// Not from any design, just following the sizing of the existing rows
+export const LOADER_ROW_HEIGHTS = {
+  S: {
+    medium: 24,
+    large: 30,
+  },
+  M: {
+    medium: 32,
+    large: 40,
+  },
+  L: {
+    medium: 40,
+    large: 50,
+  },
+  XL: {
+    medium: 48,
+    large: 60,
+  },
+};
+
 const comboBoxOption = style<ComboBoxOptionStyleProps>({
   ...focusRing(),
   ...control({ shape: "default", wrap: true, icon: true, register: "row" }),
@@ -381,12 +473,11 @@ const comboBoxOption = style<ComboBoxOptionStyleProps>({
   // `control({register: "row"})` above deliberately contributes no backgroundColor
   // (only the `matte` register paints one), so nothing else reintroduces it.
   //
-  // Keyboard focus is still drawn by `focusRing()` above, and it is not at risk of
-  // being clipped here: the ring sits 4px outside the row's border box
-  // (outlineOffset 2 + outlineWidth 2, style/index.ts), while `comboBoxListBox` gives
-  // the scroll container `padding: 8` — so the ring stays inside the padding box that
-  // `overflow` clips to. No forced-colors branch is needed either: this option sets no
-  // `forcedColorAdjust`, so high-contrast mode still paints its own highlight.
+  // Keyboard focus is still drawn by `focusRing()` above. S2 listbox padding is
+  // 0; ListLayout `padding: 8` insets the absolutely positioned rows the same
+  // way RAC does, so the ring sits in that layout gutter. No forced-colors
+  // branch is needed either: this option sets no `forcedColorAdjust`, so
+  // high-contrast mode still paints its own highlight.
   backgroundColor: "transparent",
   color: {
     // Highlight is full-strength `accent` rather than a dimmed tint: an option has no
@@ -443,6 +534,12 @@ const comboBoxOptionLabel = style<{ size?: S2ComboBoxSize }>({
   truncate: true,
 });
 
+// S2 ComboBox.tsx:354-357 — AvatarContext styles on ComboBoxItem.
+const comboBoxAvatar = style({
+  gridArea: "icon",
+  marginEnd: "text-to-visual",
+});
+
 const comboBoxCheckmark = style<ComboBoxOptionStyleProps>({
   gridArea: "checkmark",
   visibility: {
@@ -452,7 +549,6 @@ const comboBoxCheckmark = style<ComboBoxOptionStyleProps>({
   color: baseColor("accent"),
   marginEnd: "text-to-control",
   aspectRatio: "square",
-  flexShrink: 0,
   "--iconPrimary": {
     type: "fill",
     value: {
@@ -465,45 +561,15 @@ const comboBoxCheckmark = style<ComboBoxOptionStyleProps>({
   },
 });
 
-const helpTextStyles = style<ComboBoxStyleProps>({
-  gridArea: "helptext",
-  display: "flex",
-  margin: 0,
-  alignItems: "baseline",
-  gap: "text-to-visual",
-  font: controlFont(),
-  color: {
-    default: "neutral-subdued",
-    isInvalid: {
-      default: "negative",
-      forcedColors: "Mark",
-    },
-    isDisabled: {
-      default: "disabled",
-      forcedColors: "GrayText",
-    },
-  },
-  "--iconPrimary": {
-    type: "fill",
-    value: "currentColor",
-  },
-  contain: "inline-size",
-  paddingTop: "--field-gap",
-  cursor: {
-    default: "text",
-    isDisabled: "default",
-  },
-});
-
 const fieldErrorIcon = style({
-  size: fontRelative(20),
+  size: "1lh",
   marginStart: "text-to-visual",
   marginEnd: fontRelative(-2),
   flexShrink: 0,
   "--iconPrimary": {
     type: "fill",
     value: {
-      default: "negative",
+      default: "negative-1000",
       forcedColors: "Mark",
     },
   },
@@ -554,14 +620,6 @@ function requiredIconStyle(size: S2ComboBoxSize): JSX.CSSProperties {
   };
 }
 
-function comboBoxCheckmarkIconStyle(size: S2ComboBoxSize): JSX.CSSProperties {
-  const pixelSize = size === "XL" ? 14 : size === "L" ? 12 : 10;
-  return {
-    width: `${pixelSize}px`,
-    height: `${pixelSize}px`,
-  };
-}
-
 function comboBoxChevronIconStyle(size: S2ComboBoxSize): JSX.CSSProperties {
   const pixelSize = size === "XL" ? 14 : size === "L" ? 12 : 10;
   return {
@@ -600,11 +658,33 @@ function ComboBoxFieldGroup(props: {
 }) {
   const context = useContext(HeadlessComboBoxContext) as {
     isFocused?: () => boolean;
-    isFocusVisible?: () => boolean;
     setTriggerRef?: (el: HTMLElement | null) => void;
   } | null;
   const isFocused = () => context?.isFocused?.() ?? props.renderProps.isFocused;
-  const isFocusVisible = () => context?.isFocusVisible?.() ?? props.renderProps.isFocusVisible;
+
+  // S2 FieldGroup is a RAC `<Group>` with `useFocusRing({ within: true })`, not
+  // the ComboBox input's `useFocusRing({ isTextInput: true })`. Copying the
+  // input ring lit the group after pointer-open + ArrowDown + Enter: RAC
+  // `dispatchVirtualFocus` re-samples global keyboard modality on the already-
+  // focused input, and the group inherited that. `createFocusRing({ within:
+  // true })` cannot be used here — Solid `onFocus` does not bubble to a
+  // container (DateField FieldGroup uses the same workaround). Track the
+  // group's own keyboard-modality flag; `isKeyboardFocusEvent` auto-detects
+  // the text input so ArrowDown/type/Enter do not flip it.
+  const [isFocusVisibleModality, setIsFocusVisibleModality] = createSignal(
+    getInteractionModality() !== "pointer",
+  );
+  createTrackedEffect(() => {
+    const _s2Cleanups: Array<() => void> = [];
+
+    const cleanup = createFocusVisibleListener((visible) => setIsFocusVisibleModality(visible));
+    _s2Cleanups.push(cleanup);
+
+    return () => {
+      for (const c of _s2Cleanups) c();
+    };
+  });
+  const isFocusVisible = () => isFocused() && isFocusVisibleModality();
 
   // Upstream FieldGroup renders a RAC `<Group>`, whose own `useHover` drives the
   // `isHovered` render prop that `fieldGroupStyles` reads to brighten the text to
@@ -638,7 +718,7 @@ function ComboBoxFieldGroup(props: {
       }}
       onTouchEnd={focusFieldInput}
       data-hovered={isHovered() ? "true" : undefined}
-      data-focused={isFocused() ? "true" : undefined}
+      data-focus-within={isFocused() ? "true" : undefined}
       data-focus-visible={isFocusVisible() ? "true" : undefined}
       data-disabled={props.renderProps.isDisabled ? "true" : undefined}
       data-invalid={props.renderProps.isInvalid ? "true" : undefined}
@@ -648,6 +728,79 @@ function ComboBoxFieldGroup(props: {
   );
 }
 
+function ComboBoxFieldSpinner(props: {
+  loadingState: () => LoadingState | undefined;
+  menuTrigger: () => MenuTriggerAction | undefined;
+  label: string;
+}) {
+  const comboBoxContext = useContext(HeadlessComboBoxContext) as {
+    state?: { inputValue?: () => string };
+    isOpen?: () => boolean;
+  } | null;
+  const [showLoading, setShowLoading] = createSignal(false);
+  const spinnerId = createUniqueId();
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  let lastInputValue: string | undefined;
+
+  const isLoadingOrFiltering = () =>
+    props.loadingState() === "loading" || props.loadingState() === "filtering";
+
+  createTrackedEffect(() => {
+    const loading = isLoadingOrFiltering();
+    const inputValue = comboBoxContext?.state?.inputValue?.();
+    const currentlyShowing = showLoading();
+
+    if (loading && !currentlyShowing) {
+      if (timeout === null) {
+        timeout = setTimeout(() => {
+          setShowLoading(true);
+        }, 500);
+      }
+      if (inputValue !== lastInputValue) {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        timeout = setTimeout(() => {
+          setShowLoading(true);
+        }, 500);
+      }
+    } else if (!loading) {
+      setShowLoading(false);
+      if (timeout) {
+        clearTimeout(timeout);
+        timeout = null;
+      }
+    }
+
+    lastInputValue = inputValue;
+  });
+
+  onCleanup(() => {
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = null;
+    }
+  });
+
+  const showFieldSpinner = () =>
+    showLoading() &&
+    (comboBoxContext?.isOpen?.() === true ||
+      props.menuTrigger() === "manual" ||
+      props.loadingState() === "loading");
+
+  return (
+    <Show when={showFieldSpinner()}>
+      <ProgressCircle
+        id={spinnerId}
+        isIndeterminate
+        size="S"
+        styles={comboBoxProgressCircle({ isInput: true })}
+        aria-label={props.label}
+      />
+    </Show>
+  );
+}
+
 function ComboBoxListBoxPopover(props: {
   size: () => S2ComboBoxSize;
   direction: () => "bottom" | "top";
@@ -656,7 +809,6 @@ function ComboBoxListBoxPopover(props: {
   shouldFlip: () => boolean;
   children: JSX.Element;
 }) {
-  const theme = useTheme();
   const comboBoxContext = useContext(HeadlessComboBoxContext) as {
     state?: { close?: () => void };
     isOpen?: () => boolean;
@@ -671,49 +823,31 @@ function ComboBoxListBoxPopover(props: {
     comboBoxContext?.inputRef?.() ??
     comboBoxContext?.buttonRef?.() ??
     null;
-  const [triggerWidth, setTriggerWidth] = createSignal<string | undefined>();
 
-  const updateTriggerWidth = () => {
+  // RAC useOverlay has no document focusin closer. Solid createOverlay does,
+  // and ComboBox is non-modal with DOM focus remaining on the input. Treat the
+  // trigger as inside the overlay so menuTrigger=focus is not dismissed on the
+  // same focus that opened it.
+  const shouldCloseOnInteractOutside = (element: Element) => {
     const trigger = triggerRef();
-    if (trigger) {
-      setTriggerWidth(`${trigger.getBoundingClientRect().width}px`);
+    if (trigger === element || trigger?.contains(element)) {
+      return false;
     }
-  };
-
-  createEffect(() => {
-    const trigger = triggerRef();
-    if (!trigger) {
-      setTriggerWidth(undefined);
-      return;
-    }
-
-    updateTriggerWidth();
-    if (typeof ResizeObserver === "undefined") {
-      return;
-    }
-
-    const resizeObserver = new ResizeObserver(updateTriggerWidth);
-    resizeObserver.observe(trigger);
-    onCleanup(() => resizeObserver.disconnect());
-  });
-
-  const resolvedTriggerWidth = () => {
-    const explicitMenuWidth = props.menuWidth();
-    if (explicitMenuWidth != null) {
-      return `${explicitMenuWidth}px`;
+    const input = comboBoxContext?.inputRef?.();
+    if (input === element || input?.contains(element)) {
+      return false;
     }
-
-    const measuredWidth = triggerWidth();
-    if (measuredWidth) {
-      return measuredWidth;
+    const button = comboBoxContext?.buttonRef?.();
+    if (button === element || button?.contains(element)) {
+      return false;
     }
-
-    const trigger = triggerRef();
-    return trigger ? `${trigger.getBoundingClientRect().width}px` : undefined;
+    return true;
   };
 
   return (
-    <HeadlessPopover
+    <Popover
+      hideArrow
+      padding="none"
       trigger="ComboBox"
       triggerRef={triggerRef}
       isOpen={comboBoxContext?.isOpen?.() ?? false}
@@ -723,26 +857,18 @@ function ComboBoxListBoxPopover(props: {
         }
       }}
       isNonModal
+      shouldCloseOnInteractOutside={shouldCloseOnInteractOutside}
       placement={`${props.direction()} ${props.align()}`}
       offset={comboBoxMenuOffset(props.size())}
       shouldFlip={props.shouldFlip()}
       autoFocus={false}
-      class={(renderProps) =>
-        comboBoxPopover({
-          ...renderProps,
-          colorScheme: theme.colorScheme,
-          isArrowShown: false,
-          isSubmenu: false,
-        })
-      }
-      style={() => ({
-        "--trigger-width": resolvedTriggerWidth(),
-        minWidth: "var(--trigger-width)",
-        width: "var(--trigger-width)",
-      })}
+      UNSAFE_style={{
+        "--trigger-width": props.menuWidth() != null ? `${props.menuWidth()}px` : undefined,
+      }}
+      styles={comboBoxMenuWidth}
     >
       <div class={comboBoxListBoxFrame}>{props.children}</div>
-    </HeadlessPopover>
+    </Popover>
   );
 }
 
@@ -755,6 +881,7 @@ function ComboBoxFieldLabel(props: {
   // Renders the label text + necessity indicator as the direct children of the
   // `<label>` (the class lives on `HeadlessComboBoxLabel`), so the label text's
   // nearest element is the `<label>` — matching upstream FieldLabel.
+  const stringFormatter = createStringFormatter(s2IntlStrings, "@react-spectrum/s2");
   return (
     <>
       {props.label}
@@ -765,7 +892,9 @@ function ComboBoxFieldLabel(props: {
             when={props.necessityIndicator === "icon"}
             fallback={
               <span aria-hidden={props.isRequired ? true : undefined}>
-                {props.isRequired ? "(required)" : "(optional)"}
+                {stringFormatter().format(
+                  props.isRequired ? "label.(required)" : "label.(optional)",
+                )}
               </span>
             }
           >
@@ -786,6 +915,14 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
   const isInForm = useIsInForm();
   const formContext = useContext(FormContext);
   const providerProps = useProviderProps(useFormProps(props));
+  const [flags] = splitProps(providerProps, [
+    "isQuiet",
+    "isEmphasized",
+    "isDisabled",
+    "isRequired",
+    "isReadOnly",
+    "validationState",
+  ]);
   const contextProps = getSlottedContextProps(useContext(ComboBoxContext), props.slot);
   const defaultProps: Partial<ComboBoxProps<T>> = {
     labelPosition: "top",
@@ -795,7 +932,7 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     align: "start",
     shouldFlip: true,
   };
-  const mergedProps = mergeProps(defaultProps, providerProps, contextProps ?? {}, props);
+  const mergedProps = mergeProps(defaultProps, flags, contextProps ?? {}, props);
   const [local, headlessProps] = splitProps(mergedProps, [
     "size",
     "styles",
@@ -815,7 +952,8 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     "align",
     "menuWidth",
     "shouldFlip",
-    "defaultItems",
+    "loadingState",
+    "onLoadMore",
     "children",
     "slot",
     "ref",
@@ -823,9 +961,13 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
 
   const prefixId = createUniqueId();
   const size = () => normalizeComboBoxSize(local.size);
+  // S2 `useScale()` (`packages/@react-spectrum/s2/src/utils.ts`): coarse pointer → large.
+  const matchesCoarsePointer = createMediaQuery("not ((hover: hover) and (pointer: fine))");
+  const scale = (): "medium" | "large" => (matchesCoarsePointer() ? "large" : "medium");
   const labelPosition = () => local.labelPosition ?? "top";
   const labelAlign = () => local.labelAlign ?? "start";
   const necessityIndicator = () => local.necessityIndicator ?? "icon";
+  const stringFormatter = createStringFormatter(s2IntlStrings, "@react-spectrum/s2");
   const direction = () => local.direction ?? "bottom";
   const align = () => local.align ?? "start";
   const shouldFlip = () => local.shouldFlip ?? true;
@@ -873,25 +1015,19 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
       isOpen: renderProps.isOpen,
     });
 
-  const helpClass = (renderProps: ComboBoxRenderProps, isInvalid: boolean) =>
-    helpTextStyles({
-      ...renderProps,
-      size: size(),
-      isInvalid,
-    });
-
   const listBoxChildren = typeof local.children === "function" ? local.children : undefined;
 
   return (
-    <ComboBoxSizeContext.Provider value={size()}>
+    <ComboBoxSizeContext value={size()}>
+      {/* RAC S2 ComboBox.tsx:401-404 — `{...comboBoxProps}` onto AriaComboBox
+          keeps `items` and `defaultItems` distinct. RAC ComboBox.tsx:208-209
+          passes `items: props.items` into useComboBoxState; coalescing
+          defaultItems onto items here skips defaultFilter
+          (useComboBoxState.ts:297-302). */}
       <HeadlessComboBox
         {...headlessProps}
-        items={headlessProps.items ?? props.defaultItems}
-        defaultItems={props.defaultItems}
         allowsEmptyCollection
         label={local.label}
-        description={local.isInvalid ? undefined : local.description}
-        errorMessage={local.errorMessage}
         isInvalid={local.isInvalid}
         slot={local.slot ?? undefined}
         rootRef={(element) => assignRootRef(element)}
@@ -944,6 +1080,13 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
                   <AlertTriangleIcon styles={fieldErrorIcon} />
                 </CenterBaseline>
               </Show>
+              <ComboBoxFieldSpinner
+                loadingState={() => local.loadingState}
+                menuTrigger={() =>
+                  (headlessProps as { menuTrigger?: MenuTriggerAction }).menuTrigger
+                }
+                label={stringFormatter().format("table.loading")}
+              />
               <HeadlessComboBoxButton
                 ref={setChevronEl}
                 class={buttonClass}
@@ -957,17 +1100,14 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
               </HeadlessComboBoxButton>
             </ComboBoxFieldGroup>
 
-            <Show when={local.description && !renderProps.isInvalid}>
-              <HeadlessComboBoxDescription class={helpClass(renderProps, false)}>
-                {local.description}
-              </HeadlessComboBoxDescription>
-            </Show>
-
-            <Show when={local.errorMessage && renderProps.isInvalid}>
-              <HeadlessComboBoxErrorMessage class={helpClass(renderProps, true)}>
-                {local.errorMessage}
-              </HeadlessComboBoxErrorMessage>
-            </Show>
+            <HelpText
+              size={size()}
+              isDisabled={renderProps.isDisabled}
+              isInvalid={renderProps.isInvalid || local.isInvalid}
+              description={local.description}
+            >
+              {local.errorMessage}
+            </HelpText>
 
             <ComboBoxListBoxPopover
               size={size}
@@ -976,7 +1116,7 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
               menuWidth={() => local.menuWidth}
               shouldFlip={shouldFlip}
             >
-              <FormContext.Provider
+              <FormContext
                 value={{
                   ...(formContext ?? {}),
                   get size() {
@@ -985,17 +1125,75 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
                   isRequired: undefined,
                 }}
               >
-                <HeadlessComboBoxListBox
-                  class={(listBoxProps) => comboBoxListBox({ ...listBoxProps, size: size() })}
-                >
-                  {listBoxChildren}
-                </HeadlessComboBoxListBox>
-              </FormContext.Provider>
+                <HeaderContext value={{ styles: () => listboxHeader({ size: size() }) }}>
+                  <HeadingContext
+                    value={{
+                      role: "presentation",
+                      styles: menuSectionHeading,
+                    }}
+                  >
+                    <TextContext
+                      value={{
+                        slots: {
+                          description: {
+                            styles: () =>
+                              menuItemDescription({
+                                size: size(),
+                                isFocused: false,
+                                isDisabled: false,
+                              }),
+                          },
+                        },
+                      }}
+                    >
+                      <Virtualizer
+                        layout={ListLayout}
+                        layoutOptions={{
+                          estimatedRowHeight: 32,
+                          padding: 8,
+                          estimatedHeadingHeight: 50,
+                          loaderHeight: LOADER_ROW_HEIGHTS[size()][scale()],
+                        }}
+                      >
+                        <HeadlessComboBoxListBox
+                          class={(listBoxProps) =>
+                            comboBoxListBox({ ...listBoxProps, size: size() })
+                          }
+                          onLoadMore={local.onLoadMore}
+                          isLoading={local.loadingState === "loadingMore"}
+                          loadMoreClass={comboBoxLoadingWrapper}
+                          renderLoadMore={() =>
+                            local.loadingState === "loadingMore" ? (
+                              <ProgressCircle
+                                isIndeterminate
+                                size="S"
+                                styles={comboBoxProgressCircle({})}
+                                aria-label={stringFormatter().format("table.loadingMore")}
+                              />
+                            ) : undefined
+                          }
+                          renderEmptyState={() => (
+                            <span class={comboBoxEmptyStateText({ size: size() })}>
+                              {stringFormatter().format(
+                                local.loadingState === "loading"
+                                  ? "table.loading"
+                                  : "combobox.noResults",
+                              )}
+                            </span>
+                          )}
+                        >
+                          {listBoxChildren}
+                        </HeadlessComboBoxListBox>
+                      </Virtualizer>
+                    </TextContext>
+                  </HeadingContext>
+                </HeaderContext>
+              </FormContext>
             </ComboBoxListBoxPopover>
           </>
         )}
       />
-    </ComboBoxSizeContext.Provider>
+    </ComboBoxSizeContext>
   );
 }
 
@@ -1066,17 +1264,14 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
   return <HeadlessComboBoxListBox {...headlessProps} class={listClass} children={props.children} />;
 }
 
+/**
+ * @deprecated Use {@link ComboBoxItem}. Removed in a future minor.
+ */
 export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
   const [local, headlessProps] = splitProps(props, ["class", "children", "ref", "UNSAFE_style"]);
   const size = useContext(ComboBoxSizeContext);
   const [optionEl, setOptionEl] = createSignal<HTMLElement | null>(null);
   const isLink = () => (props as Record<string, unknown>).href != null;
-  const textLabel = () =>
-    isTextOnlyChildren(local.children)
-      ? Array.isArray(local.children)
-        ? local.children.join("")
-        : String(local.children)
-      : undefined;
   const optionClass = (renderProps: ComboBoxOptionRenderProps) =>
     [
       comboBoxOption({
@@ -1090,6 +1285,73 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
       .join(" ");
   const checkClass = (renderProps: ComboBoxOptionRenderProps) =>
     comboBoxCheckmark({ ...renderProps, size });
+  // Consume children in a nested component so the tracked read runs under the
+  // item Icon/Avatar/Text providers. A memo on ComboBoxOption itself would
+  // create `<Text slot="label">` against the overlay description-only
+  // TextContext (Invalid slot "label"). MenuItemContents is the same pattern.
+  // Copy headless label/description ids into Spectrum TextContext (MenuItem
+  // does the same) so S2 `<Text>` gets `aria-labelledby` without RAC Text.
+  const ComboBoxOptionChrome = (contentProps: { renderProps: ComboBoxOptionRenderProps }) => {
+    const headlessText = useContext(HeadlessTextContext) as {
+      slots?: Record<string, { id?: string } | undefined>;
+    } | null;
+    const labelId = headlessText?.slots?.label?.id ?? headlessText?.slots?.default?.id;
+    const descriptionId = headlessText?.slots?.description?.id;
+    return (
+      <TextContext
+        value={{
+          slots: {
+            label: {
+              styles: () => menuItemLabel({ size }),
+              "data-rsp-slot": "text",
+              id: labelId,
+            },
+            description: {
+              styles: () =>
+                menuItemDescription({
+                  size,
+                  isFocused: contentProps.renderProps.isFocused,
+                  isDisabled: contentProps.renderProps.isDisabled,
+                }),
+              "data-rsp-slot": "text",
+              id: descriptionId,
+            },
+          },
+        }}
+      >
+        <ComboBoxOptionContents renderProps={contentProps.renderProps} />
+      </TextContext>
+    );
+  };
+  const ComboBoxOptionContents = (contentProps: { renderProps: ComboBoxOptionRenderProps }) => {
+    // Share one tracked child value between classification and insertion.
+    // Re-evaluation can construct children; keep reactive inputs live rather
+    // than capturing an untracked setup-time snapshot.
+    const content = createMemo(() => local.children);
+    const checkClassName = createMemo(() => checkClass(contentProps.renderProps));
+    return (
+      <>
+        <CheckmarkIcon
+          size={size === "S" ? "XS" : size}
+          // Apply via `class` (raw), not `styles`: the icon `styles` path
+          // filters through `iconAllowedOverrides`, which omits `visibility`
+          // and would strip the checkmark's `visibility` toggle, leaving it
+          // visible on every option. Mirrors upstream S2 ComboBox `className`.
+          class={checkClassName()}
+        />
+        {isTextOnlyChildren(content()) ? (
+          // S2 ComboBoxItem wraps string children in `<Text slot="label">` so
+          // RAC TextContext supplies the option's labelledby id as a prop.
+          // A raw span lost that id when the render-prop tree remounted on End.
+          <HeadlessText slot="label" class={comboBoxOptionLabel({ size })} data-rsp-slot="text">
+            {content()}
+          </HeadlessText>
+        ) : (
+          content()
+        )}
+      </>
+    );
+  };
 
   return (
     <HeadlessComboBoxOption
@@ -1098,35 +1360,42 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
         setOptionEl(el);
         assignRef(local.ref, el);
       }}
-      aria-label={headlessProps["aria-label"] ?? textLabel()}
+      aria-label={headlessProps["aria-label"]}
       class={optionClass}
       // Faithful to upstream S2 `ComboBoxItem` `style={pressScale(ref, UNSAFE_style)}`.
       style={pressScale(() => optionEl(), local.UNSAFE_style)}
     >
       {(renderProps: ComboBoxOptionRenderProps) => (
-        <>
-          <CheckmarkIcon
-            size={size === "S" ? "XS" : size}
-            // Apply via `class` (raw), not `styles`: the icon `styles` path
-            // filters through `iconAllowedOverrides`, which omits `visibility`
-            // and would strip the checkmark's `visibility` toggle, leaving it
-            // visible on every option. Mirrors upstream S2 ComboBox `className`.
-            class={checkClass(renderProps)}
-            style={comboBoxCheckmarkIconStyle(size)}
-          />
-          {isTextOnlyChildren(local.children) ? (
-            <span slot="label" class={comboBoxOptionLabel({ size })} data-rsp-slot="text">
-              {local.children}
-            </span>
-          ) : (
-            local.children
-          )}
-        </>
+        <IconContext
+          value={{
+            slot: "icon",
+            render: centerBaseline({
+              slot: "icon",
+              styles: menuItemIconCenterWrapper,
+            }),
+            styles: menuItemIcon,
+          }}
+        >
+          <AvatarContext
+            value={{
+              slots: {
+                default: { size: "1lh", styles: comboBoxAvatar },
+                avatar: { size: "1lh", styles: comboBoxAvatar },
+              },
+            }}
+          >
+            <ComboBoxOptionChrome renderProps={renderProps} />
+          </AvatarContext>
+        </IconContext>
       )}
     </HeadlessComboBoxOption>
   );
 }
 
+/** S2 canonical item name. */
+export const ComboBoxItem = ComboBoxOption;
+export type ComboBoxItemProps<T> = ComboBoxOptionProps<T>;
+
 export interface ComboBoxTagGroupProps extends Omit<
   HeadlessComboBoxTagGroupProps,
   "class" | "style"