@proyecto-viviana/solidaria-components 0.5.0 → 0.7.0-rc.0

package/src/ComboBox.tsx

@@ -1,3 +1,17 @@
+/*
+ * Copyright 2022 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-aria-components/src/ComboBox.tsx
+
 /**
  * ComboBox component for solidaria-components
  *
@@ -6,19 +20,19 @@
  */
 
 import {
-  type JSX,
-  type Accessor,
-  type Context,
   createContext,
   createEffect,
   createMemo,
+  createRenderEffect,
   createSignal,
   onCleanup,
-  splitProps,
   useContext,
   For,
   Show,
+  createTrackedEffect,
 } from "solid-js";
+import type { Accessor, Context } from "solid-js";
+import type { JSX } from "@solidjs/web";
 import {
   createComboBox,
   createListBox,
@@ -27,8 +41,11 @@ import {
   createHover,
   createInteractOutside,
   createScrollIntoViewOnFocus,
+  createFocusRing,
+  createPress,
   mergeProps,
   isFocusVisible as isGlobalFocusVisible,
+  createFilter,
   type AriaComboBoxProps,
   type AriaListBoxProps,
   type AriaOptionProps,
@@ -47,11 +64,19 @@ import {
   type ClassNameOrFunction,
   type StyleOrFunction,
   type SlotProps,
+  DEFAULT_SLOT,
+  OptionContent,
   useRenderProps,
   filterDOMProps,
   Provider,
+  dataAttr,
 } from "./utils";
 import { TextContext } from "./Text";
+import { FieldErrorContext, type FieldErrorContextValue } from "./FieldError";
+import { useCollectionRenderer, useCollectionRoot } from "./Collection";
+import { ListBoxLoadMoreItem } from "./ListBox";
+import { VirtualizerItem } from "./Virtualizer";
+import { splitProps } from "@proyecto-viviana/solidaria/utils";
 import {
   SelectionIndicatorContext,
   type SelectionIndicatorContextValue,
@@ -262,8 +287,24 @@ export interface ComboBoxListBoxProps<T> extends SlotProps {
   class?: ClassNameOrFunction<ComboBoxListBoxRenderProps>;
   /** The inline style for the element. */
   style?: StyleOrFunction<ComboBoxListBoxRenderProps>;
+  /** A function to render when the listbox is empty. RAC ListBox `renderEmptyState`. */
+  renderEmptyState?: () => JSX.Element;
+  /** Called when the load more sentinel becomes visible. */
+  onLoadMore?: () => void | Promise<void>;
+  /** Whether additional items are currently loading. */
+  isLoading?: boolean;
+  /** Content to display in the load more sentinel row. */
+  renderLoadMore?: () => JSX.Element | undefined;
+  /** CSS class for the load more sentinel row. */
+  loadMoreClass?: ClassNameOrFunction<{ isLoading: boolean }>;
 }
 
+export type ComboBoxItemRenderProps = ComboBoxOptionRenderProps;
+export type ComboBoxItemProps<T> = ComboBoxOptionProps<T>;
+
+/**
+ * @deprecated Use {@link ComboBoxItemProps}. Removed in a future minor.
+ */
 export interface ComboBoxOptionRenderProps {
   /** Whether the option is selected. */
   isSelected: boolean;
@@ -320,6 +361,8 @@ interface ComboBoxContextValue<T> {
   setTriggerRef: (el: HTMLElement | null) => void;
   listBoxRef: () => HTMLElement | null;
   setListBoxRef: (el: HTMLElement | null) => void;
+  popoverRef: () => HTMLElement | null;
+  setPopoverRef: (el: HTMLElement | null) => void;
   registerOptionAction: (key: Key, action: (() => void) | undefined) => void;
   runOptionAction: (key: Key) => void;
   slots?: Record<string, Partial<ComboBoxProps<T>>>;
@@ -350,7 +393,8 @@ function callInputKeyDown(
  */
 export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
   const parentContext = useContext(ComboBoxContext) as ComboBoxContextValue<T> | null;
-  const contextSlotProps = parentContext?.slots?.[props.slot ?? "default"];
+  const contextSlotProps =
+    parentContext?.slots?.[typeof props.slot === "string" ? props.slot : "default"];
   const mergedComboBoxProps = contextSlotProps
     ? (mergeProps(contextSlotProps, props) as ComboBoxProps<T>)
     : props;
@@ -386,15 +430,22 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     ],
   );
 
-  let inputRef: HTMLInputElement | null = null;
+  const [inputEl, setInputEl] = createSignal<HTMLInputElement | null>(null, {
+    ownedWrite: true,
+  });
   let buttonRef: HTMLElement | null = null;
   let triggerRef: HTMLElement | null = null;
   let listBoxRef: HTMLElement | null = null;
+  const [popoverRef, setPopoverRef] = createSignal<HTMLElement | null>(null);
   const optionActions = new Map<Key, () => void>();
   const runOptionAction = (key: Key) => {
     optionActions.get(key)?.();
   };
 
+  // RAC ComboBox.tsx:204-207 — `useFilter({sensitivity: 'base'}).contains`
+  // is the default when the caller omits `defaultFilter`.
+  const intlFilter = createFilter({ sensitivity: "base" });
+
   const state = createComboBoxState<T>({
     get items() {
       return stateProps.items;
@@ -454,7 +505,7 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
       return stateProps.onOpenChange;
     },
     get defaultFilter() {
-      return stateProps.defaultFilter;
+      return stateProps.defaultFilter ?? intlFilter().contains;
     },
     get allowsCustomValue() {
       return stateProps.allowsCustomValue;
@@ -500,11 +551,15 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
       get name() {
         return effectiveFormValue() === "text" ? stateProps.name : undefined;
       },
+      get allowsCustomValue() {
+        return stateProps.allowsCustomValue;
+      },
     }),
     state,
-    () => inputRef,
+    () => inputEl(),
     () => buttonRef,
     () => listBoxRef,
+    () => popoverRef(),
   );
 
   const getInputProps = () => {
@@ -529,19 +584,13 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     } as JSX.InputHTMLAttributes<HTMLInputElement>;
   };
 
-  const { isHovered, hoverProps } = createHover({
-    get isDisabled() {
-      return ariaProps.isDisabled;
-    },
-  });
-
   const renderValues = createMemo<ComboBoxRenderProps>(() => ({
     isOpen: comboBoxAria.isOpen(),
     isFocused: comboBoxAria.isFocused(),
     isFocusVisible: comboBoxAria.isFocusVisible(),
     isDisabled: !!ariaProps.isDisabled,
     isRequired: !!ariaProps.isRequired,
-    isInvalid: !!ariaProps.isInvalid,
+    isInvalid: comboBoxAria.isInvalid,
     isReadOnly: !!ariaProps.isReadOnly,
     isSelected: state.selectedKey() != null,
     inputValue: state.inputValue(),
@@ -561,11 +610,6 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     return filtered;
   });
 
-  const cleanHoverProps = () => {
-    const { ref: _ref, ...rest } = hoverProps as Record<string, unknown>;
-    return rest;
-  };
-
   const ComboBoxChildren = () =>
     typeof local.children === "function"
       ? (local.children as (values: ComboBoxRenderProps) => JSX.Element)(renderValues())
@@ -582,8 +626,23 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     },
   };
 
+  // RAC ComboBox.tsx:359: `[FieldErrorContext, validation]`. HelpText's
+  // `<FieldError>` only paints when this context reports `isInvalid`.
+  const fieldErrorContext: FieldErrorContextValue = {
+    get validation() {
+      return {
+        isInvalid: comboBoxAria.isInvalid,
+        validationErrors: comboBoxAria.validationErrors,
+        validationDetails: comboBoxAria.validationDetails,
+      };
+    },
+    get errorMessageProps() {
+      return comboBoxAria.errorMessageProps;
+    },
+  };
+
   return (
-    <ComboBoxContext.Provider
+    <ComboBoxContext
       value={
         {
           state,
@@ -606,9 +665,9 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
           isFocused: comboBoxAria.isFocused,
           isFocusVisible: comboBoxAria.isFocusVisible,
           items: stateProps.items ?? stateProps.defaultItems ?? [],
-          inputRef: () => inputRef,
+          inputRef: () => inputEl(),
           setInputRef: (el) => {
-            inputRef = el;
+            setInputEl(el);
           },
           buttonRef: () => buttonRef,
           setButtonRef: (el) => {
@@ -622,6 +681,8 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
           setListBoxRef: (el) => {
             listBoxRef = el;
           },
+          popoverRef,
+          setPopoverRef,
           registerOptionAction: (key, action) => {
             if (action) {
               optionActions.set(key, action);
@@ -634,27 +695,34 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
         } as ComboBoxContextValue<unknown>
       }
     >
-      <ComboBoxStateContext.Provider value={state}>
+      <ComboBoxStateContext value={state}>
         <div
           {...domProps()}
-          {...cleanHoverProps()}
           ref={(el) => {
             assignRef(local.ref, el);
             assignRef(local.rootRef, el);
           }}
           class={renderProps.class()}
           style={renderProps.style()}
-          data-open={comboBoxAria.isOpen() || undefined}
-          data-focused={comboBoxAria.isFocused() || undefined}
-          data-focus-visible={comboBoxAria.isFocusVisible() || undefined}
-          data-disabled={ariaProps.isDisabled || undefined}
-          data-required={ariaProps.isRequired || undefined}
-          data-invalid={ariaProps.isInvalid || undefined}
-          data-readonly={ariaProps.isReadOnly || undefined}
-          data-hovered={isHovered() || undefined}
+          data-open={dataAttr(comboBoxAria.isOpen())}
+          data-focused={dataAttr(comboBoxAria.isFocused())}
+          data-disabled={dataAttr(ariaProps.isDisabled)}
+          data-required={dataAttr(ariaProps.isRequired)}
+          data-invalid={dataAttr(comboBoxAria.isInvalid)}
+          data-readonly={dataAttr(ariaProps.isReadOnly)}
           slot={local.slot}
         >
-          {/* Hidden input for key-based form submission parity */}
+          <Provider
+            values={
+              [
+                [TextContext, textSlots],
+                [FieldErrorContext, fieldErrorContext],
+              ] as Array<[Context<unknown>, unknown]>
+            }
+          >
+            <ComboBoxChildren />
+          </Provider>
+          {/* Hidden input last among root children — RAC ComboBox.tsx:373-374 */}
           <Show when={stateProps.name && effectiveFormValue() === "key"}>
             <input
               type="hidden"
@@ -663,12 +731,9 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
               value={state.selectedKey()?.toString() ?? ""}
             />
           </Show>
-          <Provider values={[[TextContext, textSlots]] as Array<[Context<unknown>, unknown]>}>
-            <ComboBoxChildren />
-          </Provider>
         </div>
-      </ComboBoxStateContext.Provider>
-    </ComboBoxContext.Provider>
+      </ComboBoxStateContext>
+    </ComboBoxContext>
   );
 }
 
@@ -715,7 +780,13 @@ export function ComboBoxDescription(props: ComboBoxDescriptionProps): JSX.Elemen
   // `Text` defaults to `elementType="span"` (Text.tsx:24) — so the help text is a
   // `<span>`, not a `<div>`. Match it (mirrors the TextField port's same revert).
   return (
-    <span {...domProps} {...cleanDescriptionProps()} class={local.class} style={local.style}>
+    <span
+      {...domProps}
+      {...cleanDescriptionProps()}
+      slot={local.slot ?? "description"}
+      class={local.class}
+      style={local.style}
+    >
       {local.children}
     </span>
   );
@@ -740,7 +811,13 @@ export function ComboBoxErrorMessage(props: ComboBoxErrorMessageProps): JSX.Elem
   // Same as the description: upstream's error is `<Text slot="errorMessage">`,
   // a `<span>` (RAC Text default elementType). Match it.
   return (
-    <span {...domProps} {...cleanErrorMessageProps()} class={local.class} style={local.style}>
+    <span
+      {...domProps}
+      {...cleanErrorMessageProps()}
+      slot={local.slot ?? "errorMessage"}
+      class={local.class}
+      style={local.style}
+    >
       {local.children}
     </span>
   );
@@ -786,7 +863,12 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
   );
 
   const cleanInputProps = () => {
-    const { ref: _ref1, value: _value, ...rest } = context.inputProps() as Record<string, unknown>;
+    const {
+      ref: _ref1,
+      value: _value,
+      "data-open": _dataOpen,
+      ...rest
+    } = context.inputProps() as Record<string, unknown>;
     return rest;
   };
   const cleanHoverProps = () => {
@@ -803,11 +885,10 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
       value={state.inputValue()}
       class={renderProps.class()}
       style={renderProps.style()}
-      data-open={isOpen() || undefined}
-      data-focused={isFocused() || undefined}
-      data-focus-visible={isFocusVisible() || undefined}
-      data-hovered={isHovered() || undefined}
-      data-disabled={state.isDisabled || undefined}
+      data-focused={dataAttr(isFocused())}
+      data-focus-visible={dataAttr(isFocusVisible())}
+      data-hovered={dataAttr(isHovered())}
+      data-disabled={dataAttr(state.isDisabled)}
     />
   );
 }
@@ -860,7 +941,7 @@ export function ComboBoxValue(props: ComboBoxValueProps): JSX.Element {
     <span
       class={renderProps.class()}
       style={renderProps.style()}
-      data-placeholder={isPlaceholder() || undefined}
+      data-placeholder={dataAttr(isPlaceholder())}
     >
       {props.children
         ? renderProps.renderChildren()
@@ -881,7 +962,7 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
   if (!context) {
     throw new Error("ComboBoxButton must be used within a ComboBox");
   }
-  const { isOpen, isFocused, state, setButtonRef } = context;
+  const { isOpen, state, setButtonRef } = context;
 
   const { isHovered, hoverProps } = createHover({
     get isDisabled() {
@@ -889,11 +970,21 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
     },
   });
 
+  // RAC Button (ComboBox chevron) uses its own hover/focus/press, not ComboBox
+  // isOpen / input isFocused. S2 `isPressed={false}` waits on #254.
+  const { isFocused, isFocusVisible, focusProps } = createFocusRing();
+  const { isPressed, pressProps } = createPress({
+    get isDisabled() {
+      return state.isDisabled || state.isReadOnly;
+    },
+    preventFocusOnPress: true,
+  });
+
   const renderValues = createMemo<ComboBoxButtonRenderProps>(() => ({
     isOpen: isOpen(),
     isFocused: isFocused(),
     isHovered: isHovered(),
-    isPressed: isOpen(),
+    isPressed: isPressed(),
     isDisabled: state.isDisabled,
   }));
 
@@ -910,30 +1001,49 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
   );
 
   const cleanButtonProps = () => {
-    const { ref: _ref1, ...rest } = context.buttonProps() as Record<string, unknown>;
+    const {
+      ref: _ref1,
+      "data-open": _dataOpen,
+      ...rest
+    } = context.buttonProps() as Record<string, unknown>;
     return rest;
   };
   const cleanHoverProps = () => {
     const { ref: _ref2, ...rest } = hoverProps as Record<string, unknown>;
     return rest;
   };
+  const cleanFocusProps = () => {
+    const { ref: _ref3, ...rest } = focusProps as Record<string, unknown>;
+    return rest;
+  };
+  const cleanPressProps = () => {
+    const { ref: _ref4, ...rest } = pressProps as Record<string, unknown>;
+    return rest;
+  };
+
+  const mergedButtonProps = () =>
+    mergeProps(
+      domProps as Record<string, unknown>,
+      cleanButtonProps(),
+      cleanHoverProps(),
+      cleanFocusProps(),
+      cleanPressProps(),
+    ) as JSX.ButtonHTMLAttributes<HTMLButtonElement>;
 
   return (
     <button
-      {...domProps}
+      {...mergedButtonProps()}
       ref={(el) => {
         setButtonRef(el);
         assignRef(local.ref, el);
       }}
-      {...cleanButtonProps()}
-      {...cleanHoverProps()}
       class={renderProps.class()}
       style={renderProps.style()}
-      data-open={isOpen() || undefined}
-      data-pressed={isOpen() || undefined}
-      data-focused={isFocused() || undefined}
-      data-hovered={isHovered() || undefined}
-      data-disabled={state.isDisabled || undefined}
+      data-pressed={dataAttr(isPressed())}
+      data-focused={dataAttr(isFocused())}
+      data-focus-visible={dataAttr(isFocusVisible())}
+      data-hovered={dataAttr(isHovered())}
+      data-disabled={dataAttr(state.isDisabled)}
     >
       {renderProps.renderChildren()}
     </button>
@@ -944,14 +1054,32 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
  * The listbox popup for a combobox.
  */
 export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element {
-  const [local, domProps] = splitProps(props, ["class", "style", "slot", "children"]);
+  const [local, domProps] = splitProps(props, [
+    "class",
+    "style",
+    "slot",
+    "children",
+    "renderEmptyState",
+    "onLoadMore",
+    "isLoading",
+    "renderLoadMore",
+    "loadMoreClass",
+  ]);
 
   const rawContext = useContext(ComboBoxContext);
   if (!rawContext) {
     throw new Error("ComboBoxListBox must be used within a ComboBox");
   }
   const context = rawContext as ComboBoxContextValue<T>;
-  const { state: comboBoxState, listState, isOpen, inputRef, buttonRef, setListBoxRef } = context;
+  const {
+    state: comboBoxState,
+    listState,
+    isOpen,
+    inputRef,
+    buttonRef,
+    setListBoxRef,
+    setPopoverRef,
+  } = context;
   const state = comboBoxState;
 
   let listBoxRef: HTMLElement | undefined;
@@ -978,6 +1106,9 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
       if (button?.contains(target)) {
         return;
       }
+      if (target.closest('[role="listbox"]') || target.closest('[role="option"]')) {
+        return;
+      }
       if (isOpen()) {
         state.close();
       }
@@ -987,14 +1118,34 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
     },
   });
 
-  // Create listbox aria props using ComboBoxState's ListState-compatible interface
+  // Create listbox aria props using ComboBoxState's ListState-compatible interface.
+  // A parent Virtualizer publishes `isVirtualized` through the collection renderer
+  // (RAC ListBox.tsx + Virtualizer); forward it so options emit posinset/setsize.
+  // RAC ComboBox list is a ListBox under Virtualizer, so CollectionRoot wraps
+  // items in VirtualizerItem. This listbox is ComboBox-owned; still consume
+  // that renderer so the popover list is not a bare in-flow option stack.
+  const parentCollectionRenderer = useCollectionRenderer<unknown>();
+  const CollectionRoot = useCollectionRoot<unknown>();
+  const isVirtualized = () => parentCollectionRenderer?.isVirtualized === true;
   const { listBoxProps } = createListBox(
-    context.listBoxProps as unknown as AriaListBoxProps,
+    () => ({
+      ...(context.listBoxProps() as AriaListBoxProps),
+      isVirtualized: parentCollectionRenderer?.isVirtualized,
+    }),
     listState,
   );
 
+  // RAC ListBox.tsx:366 — data-focused / data-focus-visible come from useFocusRing
+  // on the listbox. ComboBox uses virtual focus, so the listbox itself is not
+  // focused and must not emit data-focused.
+  const {
+    isFocused: isListBoxFocused,
+    isFocusVisible: isListBoxFocusVisible,
+    focusProps,
+  } = createFocusRing();
+
   const renderValues = createMemo<ComboBoxListBoxRenderProps>(() => ({
-    isFocused: state.isFocused(),
+    isFocused: isListBoxFocused(),
   }));
 
   const renderProps = useRenderProps(
@@ -1014,6 +1165,10 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
     const { ref: _ref2, ...rest } = listBoxProps as Record<string, unknown>;
     return rest;
   };
+  const cleanFocusProps = () => {
+    const { ref: _ref3, ...rest } = focusProps as Record<string, unknown>;
+    return rest;
+  };
 
   const items = () => Array.from(state.collection());
   const getNodeValue = (node: { key: Key; value?: T | null; index?: number }): T | null => {
@@ -1030,15 +1185,38 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
     );
   };
 
+  const [listBoxEl, setListBoxEl] = createSignal<HTMLElement | null>(null, {
+    ownedWrite: true,
+  });
+
+  // Resolve the overlay root after the listbox is inserted. A ref callback can
+  // fire before parentNode exists, so closest("[data-placement]") would miss
+  // the Popover (RAC ComboBox PopoverContext.ref) and hide-outside would keep
+  // only the listbox — aria-hiding the dismiss sibling.
+  createEffect(
+    () => listBoxEl(),
+    (el) => {
+      if (!el) {
+        setPopoverRef(null);
+        return;
+      }
+      const overlay = el.closest("[data-placement]");
+      setPopoverRef(overlay instanceof HTMLElement ? overlay : el);
+    },
+  );
+
   const setListBoxElement = (el: HTMLElement) => {
     listBoxRef = el;
     setListBoxRef(el);
+    setListBoxEl(el);
+    onCleanup(() => {
+      listBoxRef = undefined;
+      setListBoxRef(null);
+      setListBoxEl(null);
+      setPopoverRef(null);
+    });
   };
 
-  onCleanup(() => {
-    setListBoxRef(null);
-  });
-
   return (
     <Show when={isOpen()}>
       {/* `<div role="listbox">`, not `<ul>` — upstream RAC ListBox (and our own
@@ -1049,24 +1227,57 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
         ref={setListBoxElement}
         {...cleanContextProps()}
         {...cleanListBoxProps()}
+        {...cleanFocusProps()}
         class={renderProps.class()}
         style={renderProps.style()}
-        data-focused={state.isFocused() || undefined}
+        data-focused={dataAttr(isListBoxFocused())}
+        data-focus-visible={dataAttr(isListBoxFocusVisible())}
+        data-empty={dataAttr(state.collection().size === 0)}
+        data-layout="stack"
+        data-orientation="vertical"
       >
-        <Show
-          when={local.children}
-          fallback={
+        <CollectionRoot collection={items()} scrollRef={() => listBoxEl()}>
+          <Show
+            when={local.children}
+            fallback={
+              <For each={items()}>
+                {(node, index) => {
+                  const item = <ComboBoxItem id={node.key}>{node.textValue}</ComboBoxItem>;
+                  return isVirtualized() ? (
+                    <VirtualizerItem index={index()}>{item}</VirtualizerItem>
+                  ) : (
+                    item
+                  );
+                }}
+              </For>
+            }
+          >
             <For each={items()}>
-              {(node) => <ComboBoxOption id={node.key}>{node.textValue}</ComboBoxOption>}
+              {(node, index) => {
+                const value = getNodeValue(node);
+                const child = value != null ? (local.children as Function)!(value) : null;
+                return isVirtualized() ? (
+                  <VirtualizerItem index={index()}>{child}</VirtualizerItem>
+                ) : (
+                  child
+                );
+              }}
             </For>
-          }
-        >
-          <For each={items()}>
-            {(node) => {
-              const value = getNodeValue(node);
-              return value != null ? (local.children as Function)!(value) : null;
-            }}
-          </For>
+          </Show>
+        </CollectionRoot>
+        {state.collection().size === 0 && local.renderEmptyState ? (
+          <div role="option" style={{ display: "contents" }} data-empty-state>
+            {local.renderEmptyState()}
+          </div>
+        ) : null}
+        <Show when={local.onLoadMore}>
+          <ListBoxLoadMoreItem
+            onLoadMore={local.onLoadMore!}
+            isLoading={local.isLoading}
+            class={local.loadMoreClass}
+          >
+            {local.renderLoadMore?.()}
+          </ListBoxLoadMoreItem>
         </Show>
       </div>
     </Show>
@@ -1074,9 +1285,12 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
 }
 
 /**
- * An option in a combobox listbox.
+ * An item in a combobox listbox.
+ *
+ * Local addition: RAC ComboBox uses {@link ListBoxItem}. Prefer that when
+ * composing the headless ComboBox. This wrapper stays for existing call sites.
  */
-export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
+export function ComboBoxItem<T>(props: ComboBoxItemProps<T>): JSX.Element {
   const [local, ariaProps] = splitProps(props, [
     "class",
     "style",
@@ -1091,7 +1305,7 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
   const stateContext = useContext(ComboBoxStateContext);
   const comboBoxContext = useContext(ComboBoxContext);
   if (!stateContext || !comboBoxContext) {
-    throw new Error("ComboBoxOption must be used within a ComboBox");
+    throw new Error("ComboBoxItem must be used within a ComboBox");
   }
   const state = stateContext as ComboBoxState<T>;
   const listState = (comboBoxContext as ComboBoxContextValue<T>).listState;
@@ -1101,12 +1315,18 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
     return listBoxId ? `${listBoxId}-option-${local.id}` : String(local.id);
   };
 
-  createEffect(() => {
+  createTrackedEffect(() => {
+    const _s2Cleanups: Array<() => void> = [];
+
     const key = local.id;
     comboBoxContext?.registerOptionAction(key, local.onAction);
-    onCleanup(() => {
+    _s2Cleanups.push(() => {
       comboBoxContext?.registerOptionAction(key, undefined);
     });
+
+    return () => {
+      for (const c of _s2Cleanups) c();
+    };
   });
 
   // Create option aria props using ComboBoxState's ListState-compatible interface
@@ -1143,18 +1363,13 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
     () => ref(),
   );
 
-  // Mirror upstream `useOption` exactly (useOption.ts:172):
-  //   isFocusVisible = isFocused && selectionManager.isFocused && isFocusVisible()
-  // where `isFocusVisible()` is the GLOBAL interaction-modality singleton read as
-  // a render-time snapshot (NOT the input's focus ring, and NOT the option's own
-  // createFocusRing — the option div never receives real DOM focus under virtual
-  // focus, so its ring never lights). `optionAria.isFocused()` already folds in
-  // `selectionManager.isFocused()` (createSelectableItem.ts:239), so the upstream
-  // three-term product collapses to these two. Reading the global singleton off
-  // the `isFocused` dependency gives the same non-reactive snapshot semantics as
-  // React (mouse/hover focus → pointer modality → no ring; keyboard nav → keyboard
-  // modality → ring), which the earlier input-ring OR-branch got wrong (it lit the
-  // option ring whenever the input ring was on).
+  // useOption.ts:182, read live: the option is focused and the global modality
+  // is not pointer. This is the global modality, not the input's focus ring
+  // and not an option-local ring (the option div never receives real DOM focus
+  // under virtual focus). `optionAria.isFocused()` already includes
+  // `selectionManager.isFocused` (createSelectableItem.ts:239).
+  // `isGlobalFocusVisible()` tracks the modality counter, so this memo re-runs
+  // when that counter publishes.
   const isOptionFocusVisible = () => optionAria.isFocused() && isGlobalFocusVisible();
 
   const renderValues = createMemo<ComboBoxOptionRenderProps>(() => ({
@@ -1187,8 +1402,53 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
     return rest;
   };
 
+  const optionTextSlots = {
+    slots: {
+      get [DEFAULT_SLOT]() {
+        return optionAria.labelProps;
+      },
+      get label() {
+        return optionAria.labelProps;
+      },
+      get description() {
+        return optionAria.descriptionProps;
+      },
+    },
+  };
+
+  // Styled hosts emit `<span slot="label">` rather than `<Text>`. Stamp the
+  // slot id onto that node so `createSlotId` can resolve `aria-labelledby`.
+  // Render-prop children recreate the span when `isFocused` flips (End/Home);
+  // observe childList so the replacement node keeps the same id.
+  createRenderEffect(
+    () => ({
+      el: ref(),
+      labelId: optionAria.labelProps.id,
+      descriptionId: optionAria.descriptionProps.id,
+    }),
+    ({ el, labelId, descriptionId }) => {
+      if (!el) return;
+      const stamp = () => {
+        if (labelId) {
+          const label = el.querySelector("[slot='label']");
+          if (label && label.id !== labelId) label.id = labelId;
+        }
+        if (descriptionId) {
+          const description = el.querySelector("[slot='description']");
+          if (description && description.id !== descriptionId) description.id = descriptionId;
+        }
+      };
+      stamp();
+      const observer = new MutationObserver(stamp);
+      observer.observe(el, { childList: true, subtree: true });
+      return () => observer.disconnect();
+    },
+  );
+
+  const selectionMode = () => listState.selectionMode();
+
   return (
-    <SelectionIndicatorContext.Provider value={selectionIndicatorContext()}>
+    <SelectionIndicatorContext value={selectionIndicatorContext()}>
       {/* `<div role="option">`, not `<li>` — see the ComboBoxListBox note; the
           `role` comes from the spread option aria props (createOption). */}
       <div
@@ -1199,16 +1459,22 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
         {...cleanOptionProps()}
         class={renderProps.class()}
         style={renderProps.style()}
-        data-selected={optionAria.isSelected() || undefined}
-        data-focused={optionAria.isFocused() || undefined}
-        data-focus-visible={isOptionFocusVisible() || undefined}
-        data-pressed={optionAria.isPressed() || undefined}
-        data-hovered={optionAria.isHovered() || undefined}
-        data-disabled={optionAria.isDisabled() || undefined}
+        data-selected={dataAttr(optionAria.isSelected())}
+        data-focused={dataAttr(optionAria.isFocused())}
+        data-focus-visible={dataAttr(isOptionFocusVisible())}
+        data-pressed={dataAttr(optionAria.isPressed())}
+        data-hovered={dataAttr(optionAria.isHovered())}
+        data-disabled={dataAttr(optionAria.isDisabled())}
+        data-selection-mode={selectionMode() === "none" ? undefined : selectionMode()}
       >
-        {renderProps.renderChildren()}
+        <Provider values={[[TextContext, optionTextSlots] as [Context<unknown>, unknown]]}>
+          <OptionContent
+            render={renderProps.renderChildrenStable}
+            labelProps={optionAria.labelProps}
+          />
+        </Provider>
       </div>
-    </SelectionIndicatorContext.Provider>
+    </SelectionIndicatorContext>
   );
 }
 
@@ -1296,7 +1562,7 @@ export function ComboBoxTag(props: ComboBoxTagProps): JSX.Element {
         aria-label={`Remove ${props.item.label}`}
         onClick={handleRemove}
         class="solidaria-ComboBox-tag-remove"
-        tabIndex={-1}
+        tabindex={-1}
       >
         &#215;
       </button>
@@ -1307,7 +1573,12 @@ export function ComboBoxTag(props: ComboBoxTagProps): JSX.Element {
 ComboBox.Input = ComboBoxInput;
 ComboBox.Button = ComboBoxButton;
 ComboBox.ListBox = ComboBoxListBox;
-ComboBox.Option = ComboBoxOption;
+/**
+ * @deprecated Use {@link ComboBoxItem}. Local addition — RAC ComboBox uses ListBoxItem. Removed in a future minor.
+ */
+export const ComboBoxOption = ComboBoxItem;
+
+ComboBox.Option = ComboBoxItem;
 ComboBox.Label = ComboBoxLabel;
 ComboBox.Description = ComboBoxDescription;
 ComboBox.ErrorMessage = ComboBoxErrorMessage;
@@ -1355,6 +1626,10 @@ function createComboBoxListStateAdapter<T>(state: ComboBoxState<T>): ListState<T
     toggleSelection: (key) => state.select(key),
     replaceSelection: (key) => state.select(key),
     setSelectedKeys: (keys) => {
+      if (state.selectionMode() === "multiple") {
+        state.setSelectedKeys(new Set(keys));
+        return;
+      }
       const first = keys[Symbol.iterator]().next().value as Key | undefined;
       state.setSelectedKey(first ?? null);
     },