@proyecto-viviana/solidaria-components 0.2.5 → 0.2.9

package/src/ComboBox.tsx

@@ -10,6 +10,7 @@ import {
   type Accessor,
   createContext,
   createMemo,
+  onCleanup,
   splitProps,
   useContext,
   For,
@@ -22,12 +23,14 @@ import {
   createHover,
   createInteractOutside,
   type AriaComboBoxProps,
+  type AriaListBoxProps,
   type AriaOptionProps,
 } from '@proyecto-viviana/solidaria';
 import {
   createComboBoxState,
   defaultContainsFilter,
   type ComboBoxState,
+  type ListState,
   type Key,
   type FilterFn,
   type MenuTriggerAction,
@@ -40,6 +43,10 @@ import {
   useRenderProps,
   filterDOMProps,
 } from './utils';
+import {
+  SelectionIndicatorContext,
+  type SelectionIndicatorContextValue,
+} from './SelectionIndicator';
 
 // ============================================
 // TYPES
@@ -56,6 +63,8 @@ export interface ComboBoxRenderProps {
   isDisabled: boolean;
   /** Whether the combobox is required. */
   isRequired: boolean;
+  /** Whether the combobox is invalid. */
+  isInvalid: boolean;
   /** Whether a value is selected. */
   isSelected: boolean;
   /** The current input value. */
@@ -103,6 +112,14 @@ export interface ComboBoxProps<T>
   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;
   /** The CSS className for the element. */
@@ -135,6 +152,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 +192,17 @@ export interface ComboBoxButtonRenderProps {
   isDisabled: boolean;
 }
 
+export interface ComboBoxValueRenderProps {
+  textValue: string;
+  isPlaceholder: boolean;
+}
+
+export interface ComboBoxValueProps extends SlotProps {
+  children?: RenderChildren<ComboBoxValueRenderProps>;
+  class?: ClassNameOrFunction<ComboBoxValueRenderProps>;
+  style?: StyleOrFunction<ComboBoxValueRenderProps>;
+}
+
 export interface ComboBoxButtonProps extends SlotProps {
   /** The children of the button. */
   children?: RenderChildren<ComboBoxButtonRenderProps>;
@@ -213,6 +268,8 @@ interface ComboBoxContextValue<T> {
   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,10 +278,13 @@ interface ComboBoxContextValue<T> {
   setInputRef: (el: HTMLInputElement | null) => void;
   buttonRef: () => HTMLElement | null;
   setButtonRef: (el: HTMLElement | null) => void;
+  listBoxRef: () => HTMLElement | null;
+  setListBoxRef: (el: HTMLElement | null) => void;
 }
 
 export const ComboBoxContext = createContext<ComboBoxContextValue<unknown> | null>(null);
 export const ComboBoxStateContext = createContext<ComboBoxState<unknown> | null>(null);
+export const ComboBoxValueContext = ComboBoxContext;
 
 // ============================================
 // COMPONENTS
@@ -236,7 +296,7 @@ export const ComboBoxStateContext = createContext<ComboBoxState<unknown> | null>
 export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
   const [local, stateProps, ariaProps] = splitProps(
     props,
-    ['class', 'style', 'slot'],
+    ['class', 'style', 'slot', 'children'],
     [
       'items',
       'getKey',
@@ -257,12 +317,14 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
       'allowsEmptyCollection',
       'menuTrigger',
       'name',
+      'formValue',
     ]
   );
 
   // Refs
   let inputRef: HTMLInputElement | null = null;
   let buttonRef: HTMLElement | null = null;
+  let listBoxRef: HTMLElement | null = null;
 
   // Create combobox state
   const state = createComboBoxState<T>({
@@ -331,12 +393,25 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     },
   });
 
+  const effectiveFormValue = createMemo<'key' | 'text'>(() => {
+    if (stateProps.allowsCustomValue) {
+      return 'text';
+    }
+    return stateProps.formValue ?? 'key';
+  });
+
   // Create combobox aria props
   const comboBoxAria = createComboBox<T>(
-    ariaProps,
+    {
+      ...ariaProps,
+      get name() {
+        return effectiveFormValue() === 'text' ? stateProps.name : undefined;
+      },
+    },
     state,
     () => inputRef,
-    () => buttonRef
+    () => buttonRef,
+    () => listBoxRef
   );
 
   // Create hover for wrapper
@@ -353,6 +428,7 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
     isFocusVisible: comboBoxAria.isFocusVisible(),
     isDisabled: !!ariaProps.isDisabled,
     isRequired: !!ariaProps.isRequired,
+    isInvalid: !!ariaProps.isInvalid,
     isSelected: state.selectedKey() != null,
     inputValue: state.inputValue(),
   }));
@@ -387,6 +463,8 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
         buttonProps: comboBoxAria.buttonProps,
         listBoxProps: comboBoxAria.listBoxProps,
         labelProps: comboBoxAria.labelProps,
+        descriptionProps: comboBoxAria.descriptionProps,
+        errorMessageProps: comboBoxAria.errorMessageProps,
         isOpen: comboBoxAria.isOpen,
         isFocused: comboBoxAria.isFocused,
         isFocusVisible: comboBoxAria.isFocusVisible,
@@ -395,6 +473,8 @@ export function ComboBox<T>(props: ComboBoxProps<T>): JSX.Element {
         setInputRef: (el) => { inputRef = el; },
         buttonRef: () => buttonRef,
         setButtonRef: (el) => { buttonRef = el; },
+        listBoxRef: () => listBoxRef,
+        setListBoxRef: (el) => { listBoxRef = el; },
       }}
     >
       <ComboBoxStateContext.Provider value={state}>
@@ -408,28 +488,113 @@ 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-hovered={isHovered() || undefined}
         >
-          {/* 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() ?? ''}
             />
           </Show>
-          {props.children}
+          {local.children}
         </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);
@@ -458,7 +623,7 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
   // Resolve render props
   const renderProps = useRenderProps(
     {
-      children: props.children,
+      children: local.children,
       class: local.class,
       style: local.style,
       defaultClassName: 'solidaria-ComboBox-input',
@@ -478,6 +643,7 @@ export function ComboBoxInput(props: ComboBoxInputProps): JSX.Element {
 
   return (
     <input
+      {...domProps}
       ref={(el) => setInputRef(el)}
       {...cleanInputProps()}
       {...cleanHoverProps()}
@@ -493,11 +659,45 @@ 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 textValue = createMemo(() => 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(),
+    })
+  );
+
+  return (
+    <span
+      class={renderProps.class()}
+      style={renderProps.style()}
+      data-placeholder={isPlaceholder() || undefined}
+    >
+      {props.children ? renderProps.renderChildren() : 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);
@@ -513,22 +713,19 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
     },
   });
 
-  // 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',
@@ -548,6 +745,7 @@ export function ComboBoxButton(props: ComboBoxButtonProps): JSX.Element {
 
   return (
     <button
+      {...domProps}
       ref={(el) => setButtonRef(el)}
       {...cleanButtonProps()}
       {...cleanHoverProps()}
@@ -567,14 +765,21 @@ 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 { listBoxProps: contextListBoxProps, state: comboBoxState, isOpen, inputRef } = context;
+  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)
@@ -587,9 +792,13 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
       // 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,31 +810,8 @@ 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
+    contextListBoxProps as unknown as AriaListBoxProps,
+    createComboBoxListStateAdapter(state)
   );
 
   // Render props values
@@ -659,8 +845,14 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
   // 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;
+
     listBoxRef = el;
+    setListBoxRef(el);
     if (el) {
       const mouseHandler = (e: MouseEvent) => {
         e.preventDefault();
@@ -670,12 +862,22 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
       };
       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);
+  });
+
   return (
     <Show when={isOpen()}>
       <ul
+        {...domProps}
         ref={setupMouseDownHandler}
         {...cleanContextProps()}
         {...cleanListBoxProps()}
@@ -683,7 +885,7 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
         style={renderProps.style()}
         data-focused={state.isFocused() || undefined}
       >
-        <Show when={props.children} fallback={
+        <Show when={local.children} fallback={
           <For each={items()}>
             {(node) => (
               <ComboBoxOption id={node.key}>
@@ -693,7 +895,7 @@ export function ComboBoxListBox<T>(props: ComboBoxListBoxProps<T>): JSX.Element
           </For>
         }>
           <For each={items()}>
-            {(node) => node.value != null ? props.children!(node.value) : null}
+            {(node) => node.value != null ? (local.children as Function)!(node.value) : null}
           </For>
         </Show>
       </ul>
@@ -732,30 +934,7 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
         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();
-      },
-      disallowEmptySelection: () => true,
-      toggleSelection: state.select,
-      replaceSelection: state.select,
-      extendSelection: () => {},
-      selectAll: () => {},
-      clearSelection: () => state.setSelectedKey(null),
-      childFocusStrategy: () => null,
-    } as any
+    createComboBoxListStateAdapter(state)
   );
 
   // Create hover
@@ -786,6 +965,10 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
     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>;
@@ -797,20 +980,22 @@ export function ComboBoxOption<T>(props: ComboBoxOptionProps<T>): JSX.Element {
   };
 
   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}
-    >
-      {renderProps.renderChildren()}
-    </li>
+    <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-pressed={optionAria.isPressed() || undefined}
+        data-hovered={isHovered() || undefined}
+        data-disabled={optionAria.isDisabled() || undefined}
+      >
+        {renderProps.renderChildren()}
+      </li>
+    </SelectionIndicatorContext.Provider>
   );
 }
 
@@ -819,6 +1004,55 @@ ComboBox.Input = ComboBoxInput;
 ComboBox.Button = ComboBoxButton;
 ComboBox.ListBox = ComboBoxListBox;
 ComboBox.Option = ComboBoxOption;
+ComboBox.Label = ComboBoxLabel;
+ComboBox.Description = ComboBoxDescription;
+ComboBox.ErrorMessage = ComboBoxErrorMessage;
 
 // Re-export filter function for convenience
 export { defaultContainsFilter };
+
+function createComboBoxListStateAdapter<T>(state: ComboBoxState<T>): ListState<T> {
+  const selectedKeys = createMemo(() => {
+    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),
+  };
+}