@proyecto-viviana/solidaria-components 0.2.5 → 0.3.0

package/src/ComboBox.tsx

@@ -10,28 +10,33 @@ import {
   type Accessor,
   createContext,
   createMemo,
+  onCleanup,
   splitProps,
   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,
   type ComboBoxState,
+  type ListState,
   type Key,
   type FilterFn,
   type MenuTriggerAction,
-} from '@proyecto-viviana/solid-stately';
+} from "@proyecto-viviana/solid-stately";
 import {
   type RenderChildren,
   type ClassNameOrFunction,
@@ -39,11 +44,22 @@ import {
   type SlotProps,
   useRenderProps,
   filterDOMProps,
-} from './utils';
+} from "./utils";
+import {
+  SelectionIndicatorContext,
+  type SelectionIndicatorContextValue,
+} from "./SelectionIndicator";
+
+type RefLike<T> = ((el: T) => void) | { current?: T | null } | undefined;
 
-// ============================================
-// TYPES
-// ============================================
+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. */
@@ -56,17 +72,21 @@ export interface ComboBoxRenderProps {
   isDisabled: boolean;
   /** Whether the combobox is required. */
   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. */
@@ -75,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). */
@@ -100,15 +128,29 @@ 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;
+  /**
+   * Controls what value is submitted in forms.
+   * - 'key': submit the selected key via hidden input (default)
+   * - 'text': submit the text input value
+   *
+   * When allowsCustomValue is true, formValue is forced to '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 {
@@ -135,6 +177,33 @@ export interface ComboBoxInputProps extends SlotProps {
   style?: StyleOrFunction<ComboBoxInputRenderProps>;
 }
 
+export interface ComboBoxLabelProps extends SlotProps {
+  /** The children of the label element. */
+  children?: JSX.Element;
+  /** The CSS className for the element. */
+  class?: string;
+  /** The inline style for the element. */
+  style?: JSX.CSSProperties;
+}
+
+export interface ComboBoxDescriptionProps extends SlotProps {
+  /** The children of the description element. */
+  children?: JSX.Element;
+  /** The CSS className for the element. */
+  class?: string;
+  /** The inline style for the element. */
+  style?: JSX.CSSProperties;
+}
+
+export interface ComboBoxErrorMessageProps extends SlotProps {
+  /** The children of the error message element. */
+  children?: JSX.Element;
+  /** The CSS className for the element. */
+  class?: string;
+  /** The inline style for the element. */
+  style?: JSX.CSSProperties;
+}
+
 export interface ComboBoxButtonRenderProps {
   /** Whether the combobox is open. */
   isOpen: boolean;
@@ -148,6 +217,21 @@ export interface ComboBoxButtonRenderProps {
   isDisabled: boolean;
 }
 
+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 {
   /** The children of the button. */
   children?: RenderChildren<ComboBoxButtonRenderProps>;
@@ -187,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. */
@@ -201,18 +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>;
+  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>;
@@ -221,54 +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);
-
-// ============================================
-// COMPONENTS
-// ============================================
+export const ComboBoxValueContext = ComboBoxContext;
 
 /**
  * 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'],
+    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',
-    ]
+      "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;
     },
@@ -281,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;
     },
@@ -331,76 +442,121 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     },
   });
 
-  // Create combobox aria props
+  const effectiveFormValue = createMemo<"key" | "text">(() => {
+    if (stateProps.allowsCustomValue) {
+      return "text";
+    }
+    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;
+  });
+
   const comboBoxAria = createComboBox<T>(
-    ariaProps,
+    () => ({
+      ...comboBoxAriaProps(),
+      get name() {
+        return effectiveFormValue() === "text" ? stateProps.name : undefined;
+      },
+    }),
     state,
     () => inputRef,
-    () => buttonRef
+    () => buttonRef,
+    () => 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(),
     isFocusVisible: comboBoxAria.isFocusVisible(),
     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,
-        isOpen: comboBoxAria.isOpen,
-        isFocused: comboBoxAria.isFocused,
-        isFocusVisible: comboBoxAria.isFocusVisible,
-        items: stateProps.items,
-        inputRef: () => inputRef,
-        setInputRef: (el) => { inputRef = el; },
-        buttonRef: () => buttonRef,
-        setButtonRef: (el) => { buttonRef = 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}
@@ -408,44 +564,114 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
           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}
+          slot={local.slot}
         >
-          {/* Hidden input for form submission */}
-          <Show when={stateProps.name}>
+          {/* Hidden input for key-based form submission parity */}
+          <Show when={stateProps.name && effectiveFormValue() === "key"}>
             <input
               type="hidden"
               name={stateProps.name}
-              value={state.selectedKey()?.toString() ?? ''}
+              form={ariaProps.form}
+              value={state.selectedKey()?.toString() ?? ""}
             />
           </Show>
-          {props.children}
+          <ComboBoxChildren />
         </div>
       </ComboBoxStateContext.Provider>
     </ComboBoxContext.Provider>
   );
 }
 
+/**
+ * Label element for a combobox.
+ */
+export function ComboBoxLabel(props: ComboBoxLabelProps): JSX.Element {
+  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");
+  }
+
+  const cleanLabelProps = () => {
+    const { ref: _ref, ...rest } = context.labelProps() as Record<string, unknown>;
+    return rest;
+  };
+
+  return (
+    <label {...domProps} {...cleanLabelProps()} class={local.class} style={local.style}>
+      {local.children}
+    </label>
+  );
+}
+
+/**
+ * Description element for a combobox.
+ */
+export function ComboBoxDescription(props: ComboBoxDescriptionProps): JSX.Element {
+  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");
+  }
+
+  const cleanDescriptionProps = () => {
+    const { ref: _ref, ...rest } = context.descriptionProps() as Record<string, unknown>;
+    return rest;
+  };
+
+  return (
+    <div {...domProps} {...cleanDescriptionProps()} class={local.class} style={local.style}>
+      {local.children}
+    </div>
+  );
+}
+
+/**
+ * Error message element for a combobox.
+ */
+export function ComboBoxErrorMessage(props: ComboBoxErrorMessageProps): JSX.Element {
+  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");
+  }
+
+  const cleanErrorMessageProps = () => {
+    const { ref: _ref, ...rest } = context.errorMessageProps() as Record<string, unknown>;
+    return rest;
+  };
+
+  return (
+    <div {...domProps} {...cleanErrorMessageProps()} class={local.class} style={local.style}>
+      {local.children}
+    </div>
+  );
+}
+
 /**
  * The text input for a combobox.
  */
 export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
-  const [local] = splitProps(props, ['class', 'style', 'slot']);
+  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(),
@@ -455,20 +681,18 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
     inputValue: state.inputValue(),
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
-      children: props.children,
+      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 = () => {
@@ -478,6 +702,7 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
 
   return (
     <input
+      {...domProps}
       ref={(el) => setInputRef(el)}
       {...cleanInputProps()}
       {...cleanHoverProps()}
@@ -493,52 +718,101 @@ 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");
+  }
+
+  const state = context.state;
+  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(
+    {
+      children: props.children,
+      class: props.class,
+      style: props.style,
+      defaultClassName: "solidaria-ComboBox-value",
+    },
+    () => ({
+      textValue: textValue(),
+      isPlaceholder: isPlaceholder(),
+      selectedItems: selectedItems(),
+      selectedText: selectedText(),
+      state: state as ComboBoxState<unknown>,
+    }),
+  );
+
+  return (
+    <span
+      class={renderProps.class()}
+      style={renderProps.style()}
+      data-placeholder={isPlaceholder() || undefined}
+    >
+      {props.children
+        ? renderProps.renderChildren()
+        : isPlaceholder()
+          ? props.placeholder
+          : textValue()}
+    </span>
+  );
+}
+
 /**
  * The trigger button for a combobox.
  */
 export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
-  const [local] = splitProps(props, ['class', 'style', 'slot']);
+  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;
     },
   });
 
-  // Track pressed state
-  let isPressed = false;
-
-  // Render props values
   const renderValues = createMemo<ComboBoxButtonRenderProps>(() => ({
     isOpen: isOpen(),
     isFocused: isFocused(),
     isHovered: isHovered(),
-    isPressed,
+    isPressed: isOpen(),
     isDisabled: state.isDisabled,
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
-      children: props.children,
+      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 = () => {
@@ -548,12 +822,14 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
 
   return (
     <button
+      {...domProps}
       ref={(el) => setButtonRef(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}
@@ -567,29 +843,31 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
  * The listbox popup for a combobox.
  */
 export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element {
-  const [local] = splitProps(props, ['class', 'style', 'slot']);
+  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 } = context;
-  const state = comboBoxState as ComboBoxState<T>;
+  const context = rawContext as ComboBoxContextValue<T>;
+  const { state: comboBoxState, isOpen, inputRef, buttonRef, setListBoxRef } = context;
+  const state = comboBoxState;
 
-  // Ref for the listbox element (for click outside detection)
   let listBoxRef: HTMLUListElement | undefined;
 
-  // Handle click outside to close combobox
   createInteractOutside({
     ref: () => listBoxRef ?? null,
     onInteractOutside: (e) => {
       // Don't close if clicking the input or button
       const target = e.target as HTMLElement;
       const input = inputRef();
+      const button = buttonRef();
       if (input?.contains(target)) {
         return;
       }
+      if (button?.contains(target)) {
+        return;
+      }
       if (isOpen()) {
         state.close();
       }
@@ -601,51 +879,25 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
 
   // Create listbox aria props using ComboBoxState's ListState-compatible interface
   const { listBoxProps } = createListBox(
-    {},
-    {
-      collection: state.collection,
-      focusedKey: state.focusedKey,
-      setFocusedKey: state.setFocusedKey,
-      isFocused: state.isFocused,
-      setFocused: state.setFocused,
-      // Use state's built-in methods
-      selectionMode: state.selectionMode,
-      select: state.select,
-      isSelected: state.isSelected,
-      isDisabled: state.isKeyDisabled,
-      // Additional ListState interface requirements
-      selectedKeys: () => {
-        const key = state.selectedKey();
-        return key != null ? new Set([key]) : new Set();
-      },
-      disallowEmptySelection: () => true,
-      toggleSelection: state.select,
-      replaceSelection: state.select,
-      extendSelection: () => {},
-      selectAll: () => {},
-      clearSelection: () => state.setSelectedKey(null),
-      childFocusStrategy: () => null,
-    } as any
+    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 = () => {
@@ -654,46 +906,53 @@ 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;
+    }
+
+    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
+    );
+  };
 
-  // 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
-  const setupMouseDownHandler = (el: HTMLUListElement) => {
+  const setListBoxElement = (el: HTMLUListElement) => {
     listBoxRef = 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
-    }
+    setListBoxRef(el);
   };
 
+  onCleanup(() => {
+    setListBoxRef(null);
+  });
+
   return (
     <Show when={isOpen()}>
       <ul
-        ref={setupMouseDownHandler}
+        {...domProps}
+        ref={setListBoxElement}
         {...cleanContextProps()}
         {...cleanListBoxProps()}
         class={renderProps.class()}
         style={renderProps.style()}
         data-focused={state.isFocused() || undefined}
       >
-        <Show when={props.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 ? props.children!(node.value) : null}
+            {(node) => {
+              const value = getNodeValue(node);
+              return value != null ? (local.children as Function)!(value) : null;
+            }}
           </For>
         </Show>
       </ul>
@@ -706,119 +965,259 @@ 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"];
       },
-    },
-    {
-      collection: state.collection,
-      focusedKey: state.focusedKey,
-      setFocusedKey: state.setFocusedKey,
-      isFocused: state.isFocused,
-      setFocused: state.setFocused,
-      // Use state's built-in methods
-      selectionMode: state.selectionMode,
-      select: state.select,
-      isSelected: state.isSelected,
-      isDisabled: state.isKeyDisabled,
-      // Additional ListState interface requirements
-      selectedKeys: () => {
-        const key = state.selectedKey();
-        return key != null ? new Set([key]) : new Set();
+      get onAction() {
+        return local.onAction;
       },
-      disallowEmptySelection: () => true,
-      toggleSelection: state.select,
-      replaceSelection: state.select,
-      extendSelection: () => {},
-      selectAll: () => {},
-      clearSelection: () => state.setSelectedKey(null),
-      childFocusStrategy: () => null,
-    } as any
+      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),
   );
 
-  // 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,
   );
 
-  // Remove ref from spread props
+  const selectionIndicatorContext = createMemo<SelectionIndicatorContextValue>(() => ({
+    isSelected: optionAria.isSelected,
+  }));
+
   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()}
+        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}
+      >
+        {renderProps.renderChildren()}
+      </li>
+    </SelectionIndicatorContext.Provider>
+  );
+}
+
+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 (
-    <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-pressed={optionAria.isPressed() || undefined}
-      data-hovered={isHovered() || undefined}
-      data-disabled={optionAria.isDisabled() || undefined}
+    <span
+      class={props.class ?? "solidaria-ComboBox-tag"}
+      style={props.style}
+      data-key={String(props.item.key)}
     >
-      {renderProps.renderChildren()}
-    </li>
+      {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>
   );
 }
 
-// Attach sub-components
 ComboBox.Input = ComboBoxInput;
 ComboBox.Button = ComboBoxButton;
 ComboBox.ListBox = ComboBoxListBox;
 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>();
+  });
+
+  const disabledKeys = createMemo(() => {
+    const keys = new Set<Key>();
+    for (const node of state.collection()) {
+      if (node.isDisabled) keys.add(node.key);
+    }
+    return keys;
+  });
+
+  return {
+    collection: state.collection,
+    isFocused: state.isFocused,
+    setFocused: state.setFocused,
+    focusedKey: state.focusedKey,
+    setFocusedKey: (key) => state.setFocusedKey(key ?? null),
+    childFocusStrategy: () => null,
+    selectionMode: state.selectionMode,
+    selectionBehavior: () => "replace",
+    disallowEmptySelection: () => true,
+    selectedKeys,
+    disabledKeys,
+    disabledBehavior: () => "all",
+    isEmpty: () => selectedKeys().size === 0,
+    isSelectAll: () => false,
+    isSelected: state.isSelected,
+    isDisabled: state.isKeyDisabled,
+    setSelectionBehavior: () => {},
+    toggleSelection: (key) => state.select(key),
+    replaceSelection: (key) => state.select(key),
+    setSelectedKeys: (keys) => {
+      const first = keys[Symbol.iterator]().next().value as Key | undefined;
+      state.setSelectedKey(first ?? null);
+    },
+    selectAll: () => {},
+    clearSelection: () => state.setSelectedKey(null),
+    toggleSelectAll: () => {},
+    extendSelection: (toKey) => state.select(toKey),
+    select: (key) => state.select(key),
+  };
+}