@proyecto-viviana/solidaria-components 0.2.9 → 0.3.1

package/src/ComboBox.tsx

@@ -15,17 +15,19 @@ import {
   useContext,
   For,
   Show,
-} from 'solid-js';
+} from "solid-js";
 import {
   createComboBox,
   createListBox,
   createOption,
+  getComboBoxData,
   createHover,
   createInteractOutside,
+  mergeProps,
   type AriaComboBoxProps,
   type AriaListBoxProps,
   type AriaOptionProps,
-} from '@proyecto-viviana/solidaria';
+} from "@proyecto-viviana/solidaria";
 import {
   createComboBoxState,
   defaultContainsFilter,
@@ -34,7 +36,7 @@ import {
   type Key,
   type FilterFn,
   type MenuTriggerAction,
-} from '@proyecto-viviana/solid-stately';
+} from "@proyecto-viviana/solid-stately";
 import {
   type RenderChildren,
   type ClassNameOrFunction,
@@ -42,15 +44,22 @@ import {
   type SlotProps,
   useRenderProps,
   filterDOMProps,
-} from './utils';
+} from "./utils";
 import {
   SelectionIndicatorContext,
   type SelectionIndicatorContextValue,
-} from './SelectionIndicator';
+} from "./SelectionIndicator";
 
-// ============================================
-// TYPES
-// ============================================
+type RefLike<T> = ((el: T) => void) | { current?: T | null } | undefined;
+
+function assignRef<T>(ref: RefLike<T>, el: T): void {
+  if (!ref) return;
+  if (typeof ref === "function") {
+    ref(el);
+  } else {
+    ref.current = el;
+  }
+}
 
 export interface ComboBoxRenderProps {
   /** Whether the combobox listbox is open. */
@@ -65,17 +74,19 @@ export interface ComboBoxRenderProps {
   isRequired: boolean;
   /** Whether the combobox is invalid. */
   isInvalid: boolean;
+  /** Whether the combobox is read only. */
+  isReadOnly: boolean;
   /** Whether a value is selected. */
   isSelected: boolean;
   /** The current input value. */
   inputValue: string;
 }
 
-export interface ComboBoxProps<T>
-  extends Omit<AriaComboBoxProps, 'children'>,
-    SlotProps {
+export interface ComboBoxProps<T> extends Omit<AriaComboBoxProps, "children">, SlotProps {
   /** The items to render in the combobox. */
-  items: T[];
+  items?: T[];
+  /** The default items to render in the combobox when uncontrolled. */
+  defaultItems?: T[];
   /** Function to get the key from an item. */
   getKey?: (item: T) => Key;
   /** Function to get the text value from an item. */
@@ -84,12 +95,20 @@ export interface ComboBoxProps<T>
   getDisabled?: (item: T) => boolean;
   /** Keys of disabled items. */
   disabledKeys?: Iterable<Key>;
-  /** The currently selected key (controlled). */
+  /** The selection mode for the combobox. */
+  selectionMode?: "single" | "multiple";
+  /** The currently selected key (controlled, single mode). */
   selectedKey?: Key | null;
-  /** The default selected key (uncontrolled). */
+  /** The default selected key (uncontrolled, single mode). */
   defaultSelectedKey?: Key | null;
-  /** Handler called when selection changes. */
+  /** The currently selected keys (controlled, multiple mode). */
+  selectedKeys?: Iterable<Key>;
+  /** The default selected keys (uncontrolled, multiple mode). */
+  defaultSelectedKeys?: Iterable<Key>;
+  /** Handler called when selection changes (single mode). */
   onSelectionChange?: (key: Key | null) => void;
+  /** Handler called when selection changes (multiple mode). */
+  onSelectionChangeMultiple?: (keys: Set<Key>) => void;
   /** The current input value (controlled). */
   inputValue?: string;
   /** The default input value (uncontrolled). */
@@ -109,7 +128,7 @@ export interface ComboBoxProps<T>
   /** Whether to allow an empty collection (show listbox even with no matches). */
   allowsEmptyCollection?: boolean;
   /** The trigger mechanism for the combobox menu. */
-  menuTrigger?: 'focus' | 'input' | 'manual';
+  menuTrigger?: "focus" | "input" | "manual";
   /** The name of the combobox, used when submitting an HTML form. */
   name?: string;
   /**
@@ -119,13 +138,19 @@ export interface ComboBoxProps<T>
    *
    * When allowsCustomValue is true, formValue is forced to 'text'.
    */
-  formValue?: 'key' | 'text';
+  formValue?: "key" | "text";
   /** The children of the component (compound components: ComboBoxInput, ComboBoxButton, ComboBoxListBox). */
-  children: JSX.Element;
+  children: RenderChildren<ComboBoxRenderProps>;
   /** The CSS className for the element. */
   class?: ClassNameOrFunction<ComboBoxRenderProps>;
   /** The inline style for the element. */
   style?: StyleOrFunction<ComboBoxRenderProps>;
+  /** Ref for the root combobox element. */
+  ref?: RefLike<HTMLDivElement>;
+  /** Internal alias for libraries that wrap ComboBox and need a root ref. */
+  rootRef?: RefLike<HTMLDivElement>;
+  /** Slot definitions provided through ComboBoxContext. */
+  slots?: Record<string, Partial<ComboBoxProps<T>>>;
 }
 
 export interface ComboBoxInputRenderProps {
@@ -195,12 +220,16 @@ export interface ComboBoxButtonRenderProps {
 export interface ComboBoxValueRenderProps {
   textValue: string;
   isPlaceholder: boolean;
+  selectedItems: unknown[];
+  selectedText: string;
+  state: ComboBoxState<unknown>;
 }
 
 export interface ComboBoxValueProps extends SlotProps {
   children?: RenderChildren<ComboBoxValueRenderProps>;
   class?: ClassNameOrFunction<ComboBoxValueRenderProps>;
   style?: StyleOrFunction<ComboBoxValueRenderProps>;
+  placeholder?: JSX.Element;
 }
 
 export interface ComboBoxButtonProps extends SlotProps {
@@ -242,8 +271,7 @@ export interface ComboBoxOptionRenderProps {
 }
 
 export interface ComboBoxOptionProps<T>
-  extends Omit<AriaOptionProps, 'children' | 'key'>,
-    SlotProps {
+  extends Omit<AriaOptionProps, "children" | "key">, SlotProps {
   /** The unique key for the option. */
   id: Key;
   /** The item value. */
@@ -256,20 +284,18 @@ export interface ComboBoxOptionProps<T>
   style?: StyleOrFunction<ComboBoxOptionRenderProps>;
   /** The text value of the option (for typeahead). */
   textValue?: string;
+  /** Handler called when the option is activated. */
+  onAction?: () => void;
 }
 
-// ============================================
-// CONTEXT
-// ============================================
-
 interface ComboBoxContextValue<T> {
   state: ComboBoxState<T>;
-  inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
-  buttonProps: JSX.HTMLAttributes<HTMLElement>;
-  listBoxProps: JSX.HTMLAttributes<HTMLElement>;
-  labelProps: JSX.HTMLAttributes<HTMLElement>;
-  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
-  errorMessageProps: JSX.HTMLAttributes<HTMLElement>;
+  inputProps: () => JSX.InputHTMLAttributes<HTMLInputElement>;
+  buttonProps: () => JSX.HTMLAttributes<HTMLElement>;
+  listBoxProps: () => JSX.HTMLAttributes<HTMLElement>;
+  labelProps: () => JSX.HTMLAttributes<HTMLElement>;
+  descriptionProps: () => JSX.HTMLAttributes<HTMLElement>;
+  errorMessageProps: () => JSX.HTMLAttributes<HTMLElement>;
   isOpen: Accessor<boolean>;
   isFocused: Accessor<boolean>;
   isFocusVisible: Accessor<boolean>;
@@ -278,59 +304,70 @@ interface ComboBoxContextValue<T> {
   setInputRef: (el: HTMLInputElement | null) => void;
   buttonRef: () => HTMLElement | null;
   setButtonRef: (el: HTMLElement | null) => void;
+  triggerRef: () => HTMLElement | null;
+  setTriggerRef: (el: HTMLElement | null) => void;
   listBoxRef: () => HTMLElement | null;
   setListBoxRef: (el: HTMLElement | null) => void;
+  slots?: Record<string, Partial<ComboBoxProps<T>>>;
 }
 
 export const ComboBoxContext = createContext<ComboBoxContextValue<unknown> | null>(null);
 export const ComboBoxStateContext = createContext<ComboBoxState<unknown> | null>(null);
 export const ComboBoxValueContext = ComboBoxContext;
 
-// ============================================
-// COMPONENTS
-// ============================================
-
 /**
  * A combobox combines a text input with a listbox, allowing users to filter a list of options.
  */
 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 mergedComboBoxProps = contextSlotProps
+    ? (mergeProps(contextSlotProps, props) as ComboBoxProps<T>)
+    : props;
   const [local, stateProps, ariaProps] = splitProps(
-    props,
-    ['class', 'style', 'slot', 'children'],
+    mergedComboBoxProps,
+    ["class", "style", "slot", "children", "ref", "rootRef", "slots"],
     [
-      'items',
-      'getKey',
-      'getTextValue',
-      'getDisabled',
-      'disabledKeys',
-      'selectedKey',
-      'defaultSelectedKey',
-      'onSelectionChange',
-      'inputValue',
-      'defaultInputValue',
-      'onInputChange',
-      'isOpen',
-      'defaultOpen',
-      'onOpenChange',
-      'defaultFilter',
-      'allowsCustomValue',
-      'allowsEmptyCollection',
-      'menuTrigger',
-      'name',
-      'formValue',
-    ]
+      "items",
+      "defaultItems",
+      "getKey",
+      "getTextValue",
+      "getDisabled",
+      "disabledKeys",
+      "selectionMode",
+      "selectedKey",
+      "defaultSelectedKey",
+      "selectedKeys",
+      "defaultSelectedKeys",
+      "onSelectionChange",
+      "onSelectionChangeMultiple",
+      "inputValue",
+      "defaultInputValue",
+      "onInputChange",
+      "isOpen",
+      "defaultOpen",
+      "onOpenChange",
+      "defaultFilter",
+      "allowsCustomValue",
+      "allowsEmptyCollection",
+      "menuTrigger",
+      "name",
+      "formValue",
+    ],
   );
 
-  // Refs
   let inputRef: HTMLInputElement | null = null;
   let buttonRef: HTMLElement | null = null;
+  let triggerRef: HTMLElement | null = null;
   let listBoxRef: HTMLElement | null = null;
 
-  // Create combobox state
   const state = createComboBoxState<T>({
     get items() {
       return stateProps.items;
     },
+    get defaultItems() {
+      return stateProps.defaultItems;
+    },
     get getKey() {
       return stateProps.getKey;
     },
@@ -343,15 +380,27 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     get disabledKeys() {
       return stateProps.disabledKeys;
     },
+    get selectionMode() {
+      return stateProps.selectionMode;
+    },
     get selectedKey() {
       return stateProps.selectedKey;
     },
     get defaultSelectedKey() {
       return stateProps.defaultSelectedKey;
     },
+    get selectedKeys() {
+      return stateProps.selectedKeys;
+    },
+    get defaultSelectedKeys() {
+      return stateProps.defaultSelectedKeys;
+    },
     get onSelectionChange() {
       return stateProps.onSelectionChange;
     },
+    get onSelectionChangeMultiple() {
+      return stateProps.onSelectionChangeMultiple;
+    },
     get inputValue() {
       return stateProps.inputValue;
     },
@@ -393,35 +442,42 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     },
   });
 
-  const effectiveFormValue = createMemo<'key' | 'text'>(() => {
+  const effectiveFormValue = createMemo<"key" | "text">(() => {
     if (stateProps.allowsCustomValue) {
-      return 'text';
+      return "text";
     }
-    return stateProps.formValue ?? 'key';
+    return stateProps.formValue ?? "key";
+  });
+
+  const comboBoxAriaProps = createMemo(() => {
+    const cleanProps: Record<string, unknown> = {};
+    for (const key in ariaProps) {
+      if (!key.startsWith("data-")) {
+        cleanProps[key] = (ariaProps as Record<string, unknown>)[key];
+      }
+    }
+    return cleanProps as AriaComboBoxProps;
   });
 
-  // Create combobox aria props
   const comboBoxAria = createComboBox<T>(
-    {
-      ...ariaProps,
+    () => ({
+      ...comboBoxAriaProps(),
       get name() {
-        return effectiveFormValue() === 'text' ? stateProps.name : undefined;
+        return effectiveFormValue() === "text" ? stateProps.name : undefined;
       },
-    },
+    }),
     state,
     () => inputRef,
     () => buttonRef,
-    () => listBoxRef
+    () => listBoxRef,
   );
 
-  // Create hover for wrapper
   const { isHovered, hoverProps } = createHover({
     get isDisabled() {
       return ariaProps.isDisabled;
     },
   });
 
-  // Render props values
   const renderValues = createMemo<ComboBoxRenderProps>(() => ({
     isOpen: comboBoxAria.isOpen(),
     isFocused: comboBoxAria.isFocused(),
@@ -429,58 +485,78 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     isDisabled: !!ariaProps.isDisabled,
     isRequired: !!ariaProps.isRequired,
     isInvalid: !!ariaProps.isInvalid,
+    isReadOnly: !!ariaProps.isReadOnly,
     isSelected: state.selectedKey() != null,
     inputValue: state.inputValue(),
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-ComboBox',
+      defaultClassName: "solidaria-ComboBox",
     },
-    renderValues
+    renderValues,
   );
 
-  // Filter DOM props
   const domProps = createMemo(() => {
     const filtered = filterDOMProps(ariaProps as Record<string, unknown>, { global: true });
     return filtered;
   });
 
-  // Remove ref from hover props
   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())
+      : local.children;
+
   return (
     <ComboBoxContext.Provider
-      value={{
-        state,
-        inputProps: comboBoxAria.inputProps,
-        buttonProps: comboBoxAria.buttonProps,
-        listBoxProps: comboBoxAria.listBoxProps,
-        labelProps: comboBoxAria.labelProps,
-        descriptionProps: comboBoxAria.descriptionProps,
-        errorMessageProps: comboBoxAria.errorMessageProps,
-        isOpen: comboBoxAria.isOpen,
-        isFocused: comboBoxAria.isFocused,
-        isFocusVisible: comboBoxAria.isFocusVisible,
-        items: stateProps.items,
-        inputRef: () => inputRef,
-        setInputRef: (el) => { inputRef = el; },
-        buttonRef: () => buttonRef,
-        setButtonRef: (el) => { buttonRef = el; },
-        listBoxRef: () => listBoxRef,
-        setListBoxRef: (el) => { listBoxRef = el; },
-      }}
+      value={
+        {
+          state,
+          inputProps: () => comboBoxAria.inputProps,
+          buttonProps: () => comboBoxAria.buttonProps,
+          listBoxProps: () => comboBoxAria.listBoxProps,
+          labelProps: () => comboBoxAria.labelProps,
+          descriptionProps: () => comboBoxAria.descriptionProps,
+          errorMessageProps: () => comboBoxAria.errorMessageProps,
+          isOpen: comboBoxAria.isOpen,
+          isFocused: comboBoxAria.isFocused,
+          isFocusVisible: comboBoxAria.isFocusVisible,
+          items: stateProps.items ?? stateProps.defaultItems ?? [],
+          inputRef: () => inputRef,
+          setInputRef: (el) => {
+            inputRef = el;
+          },
+          buttonRef: () => buttonRef,
+          setButtonRef: (el) => {
+            buttonRef = el;
+          },
+          triggerRef: () => triggerRef,
+          setTriggerRef: (el) => {
+            triggerRef = el;
+          },
+          listBoxRef: () => listBoxRef,
+          setListBoxRef: (el) => {
+            listBoxRef = el;
+          },
+          slots: local.slots,
+        } as ComboBoxContextValue<unknown>
+      }
     >
       <ComboBoxStateContext.Provider 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}
@@ -489,17 +565,20 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
           data-disabled={ariaProps.isDisabled || undefined}
           data-required={ariaProps.isRequired || undefined}
           data-invalid={ariaProps.isInvalid || undefined}
+          data-readonly={ariaProps.isReadOnly || undefined}
           data-hovered={isHovered() || undefined}
+          slot={local.slot}
         >
           {/* Hidden input for key-based form submission parity */}
-          <Show when={stateProps.name && effectiveFormValue() === 'key'}>
+          <Show when={stateProps.name && effectiveFormValue() === "key"}>
             <input
               type="hidden"
               name={stateProps.name}
-              value={state.selectedKey()?.toString() ?? ''}
+              form={ariaProps.form}
+              value={state.selectedKey()?.toString() ?? ""}
             />
           </Show>
-          {local.children}
+          <ComboBoxChildren />
         </div>
       </ComboBoxStateContext.Provider>
     </ComboBoxContext.Provider>
@@ -510,25 +589,20 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
  * Label element for a combobox.
  */
 export function ComboBoxLabel(props: ComboBoxLabelProps): JSX.Element {
-  const [local, domProps] = splitProps(props, ['class', 'style', 'slot', 'children']);
+  const [local, domProps] = splitProps(props, ["class", "style", "slot", "children"]);
 
   const context = useContext(ComboBoxContext);
   if (!context) {
-    throw new Error('ComboBoxLabel must be used within a ComboBox');
+    throw new Error("ComboBoxLabel must be used within a ComboBox");
   }
 
   const cleanLabelProps = () => {
-    const { ref: _ref, ...rest } = context.labelProps as Record<string, unknown>;
+    const { ref: _ref, ...rest } = context.labelProps() as Record<string, unknown>;
     return rest;
   };
 
   return (
-    <label
-      {...domProps}
-      {...cleanLabelProps()}
-      class={local.class}
-      style={local.style}
-    >
+    <label {...domProps} {...cleanLabelProps()} class={local.class} style={local.style}>
       {local.children}
     </label>
   );
@@ -538,25 +612,20 @@ export function ComboBoxLabel(props: ComboBoxLabelProps): JSX.Element {
  * Description element for a combobox.
  */
 export function ComboBoxDescription(props: ComboBoxDescriptionProps): JSX.Element {
-  const [local, domProps] = splitProps(props, ['class', 'style', 'slot', 'children']);
+  const [local, domProps] = splitProps(props, ["class", "style", "slot", "children"]);
 
   const context = useContext(ComboBoxContext);
   if (!context) {
-    throw new Error('ComboBoxDescription must be used within a ComboBox');
+    throw new Error("ComboBoxDescription must be used within a ComboBox");
   }
 
   const cleanDescriptionProps = () => {
-    const { ref: _ref, ...rest } = context.descriptionProps as Record<string, unknown>;
+    const { ref: _ref, ...rest } = context.descriptionProps() as Record<string, unknown>;
     return rest;
   };
 
   return (
-    <div
-      {...domProps}
-      {...cleanDescriptionProps()}
-      class={local.class}
-      style={local.style}
-    >
+    <div {...domProps} {...cleanDescriptionProps()} class={local.class} style={local.style}>
       {local.children}
     </div>
   );
@@ -566,25 +635,20 @@ export function ComboBoxDescription(props: ComboBoxDescriptionProps): JSX.Elemen
  * Error message element for a combobox.
  */
 export function ComboBoxErrorMessage(props: ComboBoxErrorMessageProps): JSX.Element {
-  const [local, domProps] = splitProps(props, ['class', 'style', 'slot', 'children']);
+  const [local, domProps] = splitProps(props, ["class", "style", "slot", "children"]);
 
   const context = useContext(ComboBoxContext);
   if (!context) {
-    throw new Error('ComboBoxErrorMessage must be used within a ComboBox');
+    throw new Error("ComboBoxErrorMessage must be used within a ComboBox");
   }
 
   const cleanErrorMessageProps = () => {
-    const { ref: _ref, ...rest } = context.errorMessageProps as Record<string, unknown>;
+    const { ref: _ref, ...rest } = context.errorMessageProps() as Record<string, unknown>;
     return rest;
   };
 
   return (
-    <div
-      {...domProps}
-      {...cleanErrorMessageProps()}
-      class={local.class}
-      style={local.style}
-    >
+    <div {...domProps} {...cleanErrorMessageProps()} class={local.class} style={local.style}>
       {local.children}
     </div>
   );
@@ -594,23 +658,20 @@ export function ComboBoxErrorMessage(props: ComboBoxErrorMessageProps): JSX.Elem
  * The text input for a combobox.
  */
 export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
-  const [local, domProps] = splitProps(props, ['class', 'style', 'slot', 'children']);
+  const [local, domProps] = splitProps(props, ["class", "style", "slot", "children"]);
 
-  // Get context
   const context = useContext(ComboBoxContext);
   if (!context) {
-    throw new Error('ComboBoxInput must be used within a ComboBox');
+    throw new Error("ComboBoxInput must be used within a ComboBox");
   }
-  const { inputProps, isOpen, isFocused, isFocusVisible, state, setInputRef } = context;
+  const { isOpen, isFocused, isFocusVisible, state, setInputRef } = context;
 
-  // Create hover
   const { isHovered, hoverProps } = createHover({
     get isDisabled() {
       return state.isDisabled;
     },
   });
 
-  // Render props values
   const renderValues = createMemo<ComboBoxInputRenderProps>(() => ({
     isOpen: isOpen(),
     isFocused: isFocused(),
@@ -620,20 +681,18 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
     inputValue: state.inputValue(),
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       children: local.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-ComboBox-input',
+      defaultClassName: "solidaria-ComboBox-input",
     },
-    renderValues
+    renderValues,
   );
 
-  // Remove ref from spread props
   const cleanInputProps = () => {
-    const { ref: _ref1, value: _value, ...rest } = inputProps as Record<string, unknown>;
+    const { ref: _ref1, value: _value, ...rest } = context.inputProps() as Record<string, unknown>;
     return rest;
   };
   const cleanHoverProps = () => {
@@ -662,11 +721,27 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
 export function ComboBoxValue(props: ComboBoxValueProps): JSX.Element {
   const context = useContext(ComboBoxContext);
   if (!context) {
-    throw new Error('ComboBoxValue must be used within a ComboBox');
+    throw new Error("ComboBoxValue must be used within a ComboBox");
   }
 
   const state = context.state;
-  const textValue = createMemo(() => state.inputValue() ?? '');
+  const isMulti = createMemo(() => state.selectionMode() === "multiple");
+  const selectedItem = createMemo(() => state.selectedItem());
+  const selectedItems = createMemo(() => {
+    if (isMulti()) {
+      return state.selectedItems().map((node) => node.value ?? null);
+    }
+    const item = selectedItem();
+    return item ? [item.value ?? null] : [];
+  });
+  const selectedText = createMemo(() => {
+    if (isMulti()) {
+      const items = state.selectedItems();
+      return items.map((n) => n.textValue).join(", ");
+    }
+    return selectedItem()?.textValue ?? "";
+  });
+  const textValue = createMemo(() => selectedText() || state.inputValue() || "");
   const isPlaceholder = createMemo(() => textValue().length === 0);
 
   const renderProps = useRenderProps(
@@ -674,12 +749,15 @@ export function ComboBoxValue(props: ComboBoxValueProps): JSX.Element {
       children: props.children,
       class: props.class,
       style: props.style,
-      defaultClassName: 'solidaria-ComboBox-value',
+      defaultClassName: "solidaria-ComboBox-value",
     },
     () => ({
       textValue: textValue(),
       isPlaceholder: isPlaceholder(),
-    })
+      selectedItems: selectedItems(),
+      selectedText: selectedText(),
+      state: state as ComboBoxState<unknown>,
+    }),
   );
 
   return (
@@ -688,7 +766,11 @@ export function ComboBoxValue(props: ComboBoxValueProps): JSX.Element {
       style={renderProps.style()}
       data-placeholder={isPlaceholder() || undefined}
     >
-      {props.children ? renderProps.renderChildren() : textValue()}
+      {props.children
+        ? renderProps.renderChildren()
+        : isPlaceholder()
+          ? props.placeholder
+          : textValue()}
     </span>
   );
 }
@@ -697,23 +779,20 @@ export function ComboBoxValue(props: ComboBoxValueProps): JSX.Element {
  * The trigger button for a combobox.
  */
 export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
-  const [local, domProps] = splitProps(props, ['class', 'style', 'slot', 'children']);
+  const [local, domProps] = splitProps(props, ["class", "style", "slot", "children"]);
 
-  // Get context
   const context = useContext(ComboBoxContext);
   if (!context) {
-    throw new Error('ComboBoxButton must be used within a ComboBox');
+    throw new Error("ComboBoxButton must be used within a ComboBox");
   }
-  const { buttonProps, isOpen, isFocused, state, setButtonRef } = context;
+  const { isOpen, isFocused, state, setButtonRef } = context;
 
-  // Create hover
   const { isHovered, hoverProps } = createHover({
     get isDisabled() {
       return state.isDisabled;
     },
   });
 
-  // Render props values
   const renderValues = createMemo<ComboBoxButtonRenderProps>(() => ({
     isOpen: isOpen(),
     isFocused: isFocused(),
@@ -722,20 +801,18 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
     isDisabled: state.isDisabled,
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       children: local.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-ComboBox-button',
+      defaultClassName: "solidaria-ComboBox-button",
     },
-    renderValues
+    renderValues,
   );
 
-  // Remove ref from spread props
   const cleanButtonProps = () => {
-    const { ref: _ref1, ...rest } = buttonProps as Record<string, unknown>;
+    const { ref: _ref1, ...rest } = context.buttonProps() as Record<string, unknown>;
     return rest;
   };
   const cleanHoverProps = () => {
@@ -752,6 +829,7 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
       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}
@@ -765,27 +843,18 @@ 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"]);
 
-  // Get context
-  const context = useContext(ComboBoxContext);
-  if (!context) {
-    throw new Error('ComboBoxListBox must be used within a ComboBox');
+  const rawContext = useContext(ComboBoxContext);
+  if (!rawContext) {
+    throw new Error("ComboBoxListBox must be used within a ComboBox");
   }
-  const {
-    listBoxProps: contextListBoxProps,
-    state: comboBoxState,
-    isOpen,
-    inputRef,
-    buttonRef,
-    setListBoxRef,
-  } = context;
-  const state = comboBoxState as ComboBoxState<T>;
-
-  // Ref for the listbox element (for click outside detection)
+  const context = rawContext as ComboBoxContextValue<T>;
+  const { state: comboBoxState, isOpen, inputRef, buttonRef, setListBoxRef } = context;
+  const state = comboBoxState;
+
   let listBoxRef: HTMLUListElement | undefined;
 
-  // Handle click outside to close combobox
   createInteractOutside({
     ref: () => listBoxRef ?? null,
     onInteractOutside: (e) => {
@@ -810,28 +879,25 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
 
   // Create listbox aria props using ComboBoxState's ListState-compatible interface
   const { listBoxProps } = createListBox(
-    contextListBoxProps as unknown as AriaListBoxProps,
-    createComboBoxListStateAdapter(state)
+    context.listBoxProps as unknown as AriaListBoxProps,
+    createComboBoxListStateAdapter(state),
   );
 
-  // Render props values
   const renderValues = createMemo<ComboBoxListBoxRenderProps>(() => ({
     isFocused: state.isFocused(),
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-ComboBox-listbox',
+      defaultClassName: "solidaria-ComboBox-listbox",
     },
-    renderValues
+    renderValues,
   );
 
-  // Remove ref from spread props
   const cleanContextProps = () => {
-    const { ref: _ref1, ...rest } = contextListBoxProps as Record<string, unknown>;
+    const { ref: _ref1, ...rest } = context.listBoxProps() as Record<string, unknown>;
     return rest;
   };
   const cleanListBoxProps = () => {
@@ -840,37 +906,26 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
   };
 
   const items = () => Array.from(state.collection());
+  const getNodeValue = (node: { key: Key; value?: T | null; index?: number }): T | null => {
+    if (node.value != null) {
+      return node.value;
+    }
 
-  // Prevent focus from being lost when clicking in the listbox
-  // This is critical - if we don't prevent default, the input loses focus
-  // and the blur handler closes the menu before the click can be processed
-  // We need to attach this in the ref callback to use capture phase
-  let cleanupFocusGuard: (() => void) | undefined;
-
-  const setupMouseDownHandler = (el: HTMLUListElement) => {
-    cleanupFocusGuard?.();
-    cleanupFocusGuard = undefined;
+    return (
+      context.items.find((item, index) => {
+        const candidate = item as { key?: Key; id?: Key };
+        const key = candidate.key ?? candidate.id ?? index;
+        return key === node.key;
+      }) ?? null
+    );
+  };
 
+  const setListBoxElement = (el: HTMLUListElement) => {
     listBoxRef = el;
     setListBoxRef(el);
-    if (el) {
-      const mouseHandler = (e: MouseEvent) => {
-        e.preventDefault();
-      };
-      const pointerHandler = (e: PointerEvent) => {
-        e.preventDefault();
-      };
-      el.addEventListener('mousedown', mouseHandler, true); // capture phase
-      el.addEventListener('pointerdown', pointerHandler, true); // capture phase
-      cleanupFocusGuard = () => {
-        el.removeEventListener('mousedown', mouseHandler, true);
-        el.removeEventListener('pointerdown', pointerHandler, true);
-      };
-    }
   };
 
   onCleanup(() => {
-    cleanupFocusGuard?.();
     setListBoxRef(null);
   });
 
@@ -878,24 +933,26 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
     <Show when={isOpen()}>
       <ul
         {...domProps}
-        ref={setupMouseDownHandler}
+        ref={setListBoxElement}
         {...cleanContextProps()}
         {...cleanListBoxProps()}
         class={renderProps.class()}
         style={renderProps.style()}
         data-focused={state.isFocused() || undefined}
       >
-        <Show when={local.children} fallback={
-          <For each={items()}>
-            {(node) => (
-              <ComboBoxOption id={node.key}>
-                {node.textValue}
-              </ComboBoxOption>
-            )}
-          </For>
-        }>
+        <Show
+          when={local.children}
+          fallback={
+            <For each={items()}>
+              {(node) => <ComboBoxOption id={node.key}>{node.textValue}</ComboBoxOption>}
+            </For>
+          }
+        >
           <For each={items()}>
-            {(node) => node.value != null ? (local.children as Function)!(node.value) : null}
+            {(node) => {
+              const value = getNodeValue(node);
+              return value != null ? (local.children as Function)!(value) : null;
+            }}
           </For>
         </Show>
       </ul>
@@ -908,89 +965,102 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
  */
 export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
   const [local, ariaProps] = splitProps(props, [
-    'class',
-    'style',
-    'slot',
-    'id',
-    'item',
-    'textValue',
+    "class",
+    "style",
+    "slot",
+    "id",
+    "item",
+    "textValue",
+    "onAction",
   ]);
 
-  // Get state from context
-  const context = useContext(ComboBoxStateContext);
-  if (!context) {
-    throw new Error('ComboBoxOption must be used within a ComboBox');
+  const stateContext = useContext(ComboBoxStateContext);
+  const comboBoxContext = useContext(ComboBoxContext);
+  if (!stateContext) {
+    throw new Error("ComboBoxOption must be used within a ComboBox");
   }
-  const state = context as ComboBoxState<T>;
+  const state = stateContext as ComboBoxState<T>;
+  const optionId = () => {
+    const listBoxId = getComboBoxData(state as ComboBoxState<unknown>)?.listBoxId;
+    return listBoxId ? `${listBoxId}-option-${local.id}` : String(local.id);
+  };
 
   // Create option aria props using ComboBoxState's ListState-compatible interface
   const optionAria = createOption<T>(
     {
       key: local.id,
+      get optionId() {
+        return optionId();
+      },
       get isDisabled() {
         return ariaProps.isDisabled;
       },
-      get 'aria-label'() {
-        return ariaProps['aria-label'];
+      get "aria-label"() {
+        return ariaProps["aria-label"];
+      },
+      get onAction() {
+        return local.onAction;
+      },
+      shouldSelectOnPressUp: true,
+      shouldFocusOnHover: true,
+      shouldUseVirtualFocus: true,
+      allowsDifferentPressOrigin: true,
+      get onHoverStart() {
+        return ariaProps.onHoverStart;
+      },
+      get onHoverEnd() {
+        return ariaProps.onHoverEnd;
+      },
+      get onHoverChange() {
+        return ariaProps.onHoverChange;
       },
     },
-    createComboBoxListStateAdapter(state)
+    createComboBoxListStateAdapter(state),
   );
 
-  // Create hover
-  const { isHovered, hoverProps } = createHover({
-    get isDisabled() {
-      return optionAria.isDisabled();
-    },
-  });
+  const isOptionFocusVisible = () =>
+    optionAria.isFocusVisible() ||
+    (optionAria.isFocused() && (comboBoxContext?.isFocusVisible() ?? false));
 
-  // Render props values
   const renderValues = createMemo<ComboBoxOptionRenderProps>(() => ({
     isSelected: optionAria.isSelected(),
     isFocused: optionAria.isFocused(),
-    isFocusVisible: optionAria.isFocusVisible(),
+    isFocusVisible: isOptionFocusVisible(),
     isPressed: optionAria.isPressed(),
-    isHovered: isHovered(),
+    isHovered: optionAria.isHovered(),
     isDisabled: optionAria.isDisabled(),
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       children: props.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-ComboBox-option',
+      defaultClassName: "solidaria-ComboBox-option",
     },
-    renderValues
+    renderValues,
   );
 
   const selectionIndicatorContext = createMemo<SelectionIndicatorContextValue>(() => ({
     isSelected: optionAria.isSelected,
   }));
 
-  // Remove ref from spread props
   const cleanOptionProps = () => {
     const { ref: _ref1, ...rest } = optionAria.optionProps as Record<string, unknown>;
     return rest;
   };
-  const cleanHoverProps = () => {
-    const { ref: _ref2, ...rest } = hoverProps as Record<string, unknown>;
-    return rest;
-  };
 
   return (
     <SelectionIndicatorContext.Provider value={selectionIndicatorContext()}>
       <li
         {...cleanOptionProps()}
-        {...cleanHoverProps()}
         class={renderProps.class()}
         style={renderProps.style()}
         data-selected={optionAria.isSelected() || undefined}
         data-focused={optionAria.isFocused() || undefined}
-        data-focus-visible={optionAria.isFocusVisible() || undefined}
+        data-focus-visible={isOptionFocusVisible() || undefined}
         data-pressed={optionAria.isPressed() || undefined}
-        data-hovered={isHovered() || undefined}
+        data-hovered={optionAria.isHovered() || undefined}
         data-disabled={optionAria.isDisabled() || undefined}
       >
         {renderProps.renderChildren()}
@@ -999,7 +1069,98 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
   );
 }
 
-// Attach sub-components
+export interface ComboBoxTagGroupProps {
+  /** Render function for each selected item. */
+  children: (item: { key: Key; label: string }) => JSX.Element;
+  /** The CSS className for the container. */
+  class?: string;
+  /** The inline style for the container. */
+  style?: JSX.CSSProperties;
+}
+
+/**
+ * Renders selected items as tags in multi-select mode.
+ */
+export function ComboBoxTagGroup(props: ComboBoxTagGroupProps): JSX.Element {
+  const context = useContext(ComboBoxContext);
+  if (!context) {
+    throw new Error("ComboBoxTagGroup must be used within a ComboBox");
+  }
+
+  const state = context.state;
+  const items = createMemo(() =>
+    state.selectedItems().map((node) => ({
+      key: node.key,
+      label: node.textValue,
+    })),
+  );
+
+  return (
+    <Show when={items().length > 0}>
+      <div
+        class={props.class ?? "solidaria-ComboBox-tagGroup"}
+        style={props.style}
+        role="group"
+        aria-label="Selected items"
+      >
+        <For each={items()}>{(item) => props.children(item)}</For>
+      </div>
+    </Show>
+  );
+}
+
+export interface ComboBoxTagProps {
+  /** The item data. */
+  item: { key: Key; label: string };
+  /** Handler called when the tag remove button is clicked. */
+  onRemove?: () => void;
+  /** The children to render inside the tag. */
+  children?: JSX.Element;
+  /** The CSS className for the tag. */
+  class?: string;
+  /** The inline style for the tag. */
+  style?: JSX.CSSProperties;
+}
+
+/**
+ * A tag representing a selected item in a multi-select combobox.
+ */
+export function ComboBoxTag(props: ComboBoxTagProps): JSX.Element {
+  const context = useContext(ComboBoxContext);
+  if (!context) {
+    throw new Error("ComboBoxTag must be used within a ComboBox");
+  }
+
+  const state = context.state;
+
+  const handleRemove = () => {
+    if (props.onRemove) {
+      props.onRemove();
+    } else {
+      state.removeSelectedKey(props.item.key);
+    }
+  };
+
+  return (
+    <span
+      class={props.class ?? "solidaria-ComboBox-tag"}
+      style={props.style}
+      data-key={String(props.item.key)}
+    >
+      {props.children ?? props.item.label}
+      <button
+        type="button"
+        aria-label={`Remove ${props.item.label}`}
+        onClick={handleRemove}
+        class="solidaria-ComboBox-tag-remove"
+        tabIndex={-1}
+      >
+        &#215;
+      </button>
+    </span>
+  );
+}
+
 ComboBox.Input = ComboBoxInput;
 ComboBox.Button = ComboBoxButton;
 ComboBox.ListBox = ComboBoxListBox;
@@ -1007,12 +1168,16 @@ ComboBox.Option = ComboBoxOption;
 ComboBox.Label = ComboBoxLabel;
 ComboBox.Description = ComboBoxDescription;
 ComboBox.ErrorMessage = ComboBoxErrorMessage;
+ComboBox.TagGroup = ComboBoxTagGroup;
+ComboBox.Tag = ComboBoxTag;
 
-// Re-export filter function for convenience
 export { defaultContainsFilter };
 
 function createComboBoxListStateAdapter<T>(state: ComboBoxState<T>): ListState<T> {
   const selectedKeys = createMemo(() => {
+    if (state.selectionMode() === "multiple") {
+      return state.selectedKeys();
+    }
     const key = state.selectedKey();
     return key != null ? new Set<Key>([key]) : new Set<Key>();
   });
@@ -1033,11 +1198,11 @@ function createComboBoxListStateAdapter<T>(state: ComboBoxState<T>): ListState<T
     setFocusedKey: (key) => state.setFocusedKey(key ?? null),
     childFocusStrategy: () => null,
     selectionMode: state.selectionMode,
-    selectionBehavior: () => 'replace',
+    selectionBehavior: () => "replace",
     disallowEmptySelection: () => true,
     selectedKeys,
     disabledKeys,
-    disabledBehavior: () => 'all',
+    disabledBehavior: () => "all",
     isEmpty: () => selectedKeys().size === 0,
     isSelectAll: () => false,
     isSelected: state.isSelected,