@jmruthers/pace-core 0.5.193 → 0.6.2

package/src/components/Select/Select.tsx

@@ -14,425 +14,35 @@
 
 import * as React from "react";
 import { Search, X, ChevronDown, Check } from "lucide-react";
-import { Button, type ButtonProps } from "../Button/Button";
+import { Button } from "../Button/Button";
 import { cn } from "../../utils/core/cn";
-
-// ============================================================================
-// TYPES AND INTERFACES
-// ============================================================================
-
-export interface SelectState {
-  value: string;
-  selectedText: string;
-  open: boolean;
-  disabled: boolean;
-}
-
-export interface SelectActions {
-  setValue: (value: string, text: string) => void;
-  setOpen: (open: boolean) => void;
-  setSelectedText: (text: string) => void;
-}
-
-export interface SelectEventHandlers {
-  onValueChange?: (value: string) => void;
-  onOpenChange?: (open: boolean) => void;
-}
-
-export interface UseSelectStateProps {
-  value?: string;
-  defaultValue?: string;
-  selectedText?: string;
-  open?: boolean;
-  defaultOpen?: boolean;
-  disabled?: boolean;
-  onValueChange?: (value: string) => void;
-  onOpenChange?: (open: boolean) => void;
-}
-
-export interface UseSelectEventsProps {
-  state: SelectState;
-  actions: SelectActions;
-  selectRef: React.RefObject<HTMLElement>;
-}
-
-export interface UseSelectSearchProps {
-  children: React.ReactNode;
-  searchable?: boolean;
-  searchTerm?: string;
-  onSearchChange?: (term: string) => void;
-}
-
-export interface SelectContextValue extends SelectState {
-  actions: SelectActions;
-  registerItem?: (value: string, text: string) => void;
-  unregisterItem?: (value: string) => void;
-  direction?: 'up' | 'down';
-}
-
-export interface SelectProps extends Omit<React.HTMLAttributes<HTMLFormElement>, 'onChange' | 'onKeyDown' | 'onFocus' | 'onBlur'> {
-  children: React.ReactNode;
-  className?: string;
-  direction?: 'up' | 'down';
-  // State props are in UseSelectStateProps (via & intersection)
-}
-
-export interface SelectTriggerProps extends Omit<ButtonProps, 'onClick' | 'onKeyDown'> {
-  children: React.ReactNode;
-  asChild?: boolean;
-}
-
-export interface SelectValueProps {
-  placeholder?: string;
-  children?: React.ReactNode;
-}
-
-export interface SelectContentProps {
-  children: React.ReactNode;
-  className?: string;
-  searchable?: boolean;
-  searchPlaceholder?: string;
-  maxHeight?: string;
-  style?: React.CSSProperties;
-}
-
-export interface SelectItemProps {
-  value: string;
-  children: React.ReactNode;
-  disabled?: boolean;
-  className?: string;
-  onClick?: (e: React.MouseEvent) => void;
-}
-
-// ============================================================================
-// HOOKS
-// ============================================================================
-
-// State Management Hook
-export const useSelectState = ({
-  value: controlledValue,
-  defaultValue = '',
-  selectedText: controlledSelectedText,
-  open: controlledOpen,
-  defaultOpen = false,
-  disabled = false,
-  onValueChange,
-  onOpenChange,
-}: UseSelectStateProps) => {
-  // Internal state for uncontrolled mode
-  const [internalValue, setInternalValue] = React.useState(defaultValue);
-  const [internalSelectedText, setInternalSelectedText] = React.useState('');
-  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
-
-  // Computed values (controlled vs uncontrolled)
-  const value = controlledValue !== undefined ? controlledValue : internalValue;
-  const selectedText = controlledSelectedText !== undefined ? controlledSelectedText : internalSelectedText;
-  const open = controlledOpen !== undefined ? controlledOpen : internalOpen;
-
-  // Actions
-  const setValue = React.useCallback((newValue: string, newText: string) => {
-    if (controlledValue === undefined) {
-      setInternalValue(newValue);
-      setInternalSelectedText(newText);
-    }
-    onValueChange?.(newValue);
-    
-    // Close dropdown after selection (for uncontrolled mode)
-    if (controlledOpen === undefined) {
-      setInternalOpen(false);
-    }
-    onOpenChange?.(false);
-  }, [controlledValue, onValueChange, controlledOpen, onOpenChange]);
-
-  const setOpen = React.useCallback((newOpen: boolean) => {
-    if (disabled) {
-      return;
-    }
-    
-    // Close all other select dropdowns when opening this one
-    if (newOpen) {
-      const allTriggers = document.querySelectorAll('[data-testid="select-trigger"]');
-      allTriggers.forEach(trigger => {
-        if (trigger.getAttribute('aria-expanded') === 'true') {
-          const selectRoot = trigger.closest('[data-testid="select-root"]');
-          if (selectRoot) {
-            const closeEvent = new CustomEvent('closeSelect');
-            selectRoot.dispatchEvent(closeEvent);
-          }
-        }
-      });
-    }
-    
-    if (controlledOpen === undefined) {
-      setInternalOpen(newOpen);
-    }
-    onOpenChange?.(newOpen);
-  }, [controlledOpen, onOpenChange, disabled]);
-
-  const setSelectedText = React.useCallback((newText: string) => {
-    if (controlledSelectedText === undefined) {
-      setInternalSelectedText(newText);
-    }
-  }, [controlledSelectedText]);
-
-  const state: SelectState = {
-    value,
-    selectedText,
-    open,
-    disabled,
-  };
-
-  const actions: SelectActions = {
-    setValue,
-    setOpen,
-    setSelectedText,
-  };
-
-  return { state, actions };
-};
-
-// Event Handling Hook
-export const useSelectEvents = ({ state, actions, selectRef }: UseSelectEventsProps) => {
-  const [isSelecting, setIsSelecting] = React.useState(false);
-
-  // Listen for close events from other selects
-  React.useEffect(() => {
-    const handleCloseSelect = () => {
-      actions.setOpen(false);
-    };
-
-    const selectElement = selectRef.current as HTMLElement;
-    if (selectElement) {
-      selectElement.addEventListener('closeSelect', handleCloseSelect);
-      return () => {
-        selectElement.removeEventListener('closeSelect', handleCloseSelect);
-      };
-    }
-  }, [actions, selectRef]);
-
-  // Handle click outside to close dropdown
-  React.useEffect(() => {
-    if (!state.open) return;
-
-    const handleClickOutside = (event: MouseEvent) => {
-      const selectElement = selectRef.current;
-      if (!selectElement) return;
-      
-      const target = event.target as Node;
-      
-      // Close if clicking outside the select element
-      if (!selectElement.contains(target) && !isSelecting) {
-        actions.setOpen(false);
-      }
-    };
-
-    // Add a small delay to avoid closing immediately when opening
-      // The delay ensures the click event that opened the dropdown has fully processed
-      const timeoutId = setTimeout(() => {
-        document.addEventListener('click', handleClickOutside, true); // Use capture phase
-      }, 100); // Small delay to let the opening click complete
-    
-      return () => {
-        clearTimeout(timeoutId);
-        document.removeEventListener('click', handleClickOutside, true);
-      };
-  }, [state.open, actions, selectRef, isSelecting]);
-
-  // Handle SelectItem mousedown events
-  React.useEffect(() => {
-    let timeoutId: NodeJS.Timeout | null = null;
-    let isMounted = true;
-    
-    const handleSelectItemMouseDown = () => {
-      if (!isMounted) return;
-      
-      setIsSelecting(true);
-      timeoutId = setTimeout(() => {
-        if (isMounted) {
-          setIsSelecting(false);
-        }
-      }, 150);
-    };
-
-    document.addEventListener('selectItemMouseDown', handleSelectItemMouseDown as EventListener);
-    return () => {
-      isMounted = false;
-      document.removeEventListener('selectItemMouseDown', handleSelectItemMouseDown as EventListener);
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-      }
-    };
-  }, []);
-
-  return { isSelecting };
-};
-
-// Search Functionality Hook
-export const useSelectSearch = ({ 
-  children, 
-  searchable = false, 
-  searchTerm: controlledSearchTerm,
-  onSearchChange 
-}: UseSelectSearchProps) => {
-  const [internalSearchTerm, setInternalSearchTerm] = React.useState('');
-  const [filteredChildren, setFilteredChildren] = React.useState<React.ReactNode>(children);
-  const searchInputRef = React.useRef<HTMLInputElement>(null);
-
-  const searchTerm = controlledSearchTerm !== undefined ? controlledSearchTerm : internalSearchTerm;
-
-  const setSearchTerm = React.useCallback((term: string) => {
-    if (controlledSearchTerm === undefined) {
-      setInternalSearchTerm(term);
-    }
-    onSearchChange?.(term);
-  }, [controlledSearchTerm, onSearchChange]);
-
-  // Filter children based on search term
-  React.useEffect(() => {
-    if (!searchable || !searchTerm) {
-      setFilteredChildren(children);
-      return;
-    }
-
-    const filterChildren = (nodes: React.ReactNode): React.ReactNode => {
-      return React.Children.map(nodes, (child) => {
-        if (!React.isValidElement(child)) return child;
-
-        // Check if this is a SelectItem by looking for the data-testid or value prop
-        const isSelectItem = child.props && 
-          (child.props['data-testid'] === 'select-item' || 
-           child.props.value !== undefined);
-
-        if (isSelectItem) {
-          const childText = React.Children.toArray(child.props.children).join(' ').toLowerCase();
-          const searchLower = searchTerm.toLowerCase();
-          
-          if (childText.includes(searchLower)) {
-            return child;
-          }
-          return null;
-        }
-
-        if (child.props.children) {
-          const filteredChildChildren = filterChildren(child.props.children);
-          if (React.Children.count(filteredChildChildren) > 0) {
-            return React.cloneElement(child, {}, filteredChildChildren);
-          }
-          return null;
-        }
-
-        return child;
-      });
-    };
-
-    const filtered = filterChildren(children);
-    setFilteredChildren(filtered);
-  }, [children, searchTerm, searchable]);
-
-  return {
-    searchTerm,
-    setSearchTerm,
-    filteredChildren,
-    searchInputRef,
-  };
-};
-
-// ============================================================================
-// CONTEXT
-// ============================================================================
-
-const SelectContext = React.createContext<SelectContextValue | null>(null);
-
-const useSelectContext = () => {
-  const context = React.useContext(SelectContext);
-  if (!context) {
-    throw new Error('Select components must be used within a Select');
-  }
-  return context;
-};
+import { SelectContext, useSelectContext } from "./context";
+import { useSelectEvents } from "./hooks/useSelectEvents";
+import { useSelectSearch } from "./hooks/useSelectSearch";
+import { useSelectState } from "./hooks/useSelectState";
+import type {
+  SelectContentProps,
+  SelectContextValue,
+  SelectItemProps,
+  SelectProps,
+  SelectTriggerProps,
+  SelectValueProps,
+  UseSelectStateProps,
+} from "./types";
+import { getTextContent } from "./utils/text";
 
 // ============================================================================
 // ROOT COMPONENT
 // ============================================================================
 
-// Helper function to extract text from React children
-const getTextContent = (children: React.ReactNode): string => {
-  if (typeof children === 'string') return children;
-  if (typeof children === 'number') return children.toString();
-  if (React.isValidElement(children) && children.props.children) {
-    return getTextContent(children.props.children);
-  }
-  if (Array.isArray(children)) {
-    return children.map(getTextContent).join('');
-  }
-  return '';
-};
-
-// Helper function to find SelectItem by value in React children tree
-const findSelectItemText = (children: React.ReactNode, targetValue: string): string | null => {
-  if (!children) return null;
-  
-  // Handle arrays directly (common when using .map())
-  if (Array.isArray(children)) {
-    for (const child of children) {
-      if (!child) continue;
-      const found = findSelectItemText(child, targetValue);
-      if (found) return found;
-    }
-    return null;
-  }
-  
-  // Handle React elements directly if it's a single element
-  if (React.isValidElement(children)) {
-    const props = (children as React.ReactElement<{ value?: string; children?: React.ReactNode }>).props;
-    
-    // Check if this is a SelectItem
-    if (props && props.value !== undefined && typeof props.value === 'string' && props.value === targetValue) {
-      const text = getTextContent(props.children);
-      if (text && text.trim()) {
-        return text.trim();
-      }
-    }
-    
-    // Recurse into children
-    if (props && props.children !== undefined && props.children !== null) {
-      const found = findSelectItemText(props.children, targetValue);
-      if (found) return found;
-    }
-    return null;
-  }
-  
-  // Handle multiple children using React.Children utilities
-  const childrenArray = React.Children.toArray(children);
-  
-  for (const child of childrenArray) {
-    if (!React.isValidElement(child)) continue;
-    
-    const props = (child as React.ReactElement<{ value?: string; children?: React.ReactNode }>).props;
-    
-    // Check if this is a SelectItem by checking for value prop
-    // SelectItem components always have a value prop
-    if (props && props.value !== undefined && typeof props.value === 'string' && props.value === targetValue) {
-      const text = getTextContent(props.children);
-      if (text && text.trim()) {
-        return text.trim();
-      }
-    }
-    
-    // Recursively search in children
-    // Need to check both props.children and handle null/undefined
-    if (props) {
-      const childChildren = props.children;
-      if (childChildren !== undefined && childChildren !== null) {
-        const found = findSelectItemText(childChildren, targetValue);
-        if (found) return found;
-      }
-    }
-  }
-  
-  return null;
-};
-
+/**
+ * Select component root.
+ * Provides select dropdown functionality with search, keyboard navigation, and accessibility.
+ * 
+ * @param props - Select configuration
+ * @param ref - Forwarded ref to the form element
+ * @returns The rendered select component
+ */
 export const Select = React.forwardRef<HTMLFormElement, SelectProps & UseSelectStateProps>(
   ({ 
     children,
@@ -443,7 +53,7 @@ export const Select = React.forwardRef<HTMLFormElement, SelectProps & UseSelectS
     const internalRef = React.useRef<HTMLFormElement>(null);
     const selectRef = React.useMemo(() => {
       if (ref && typeof ref === 'object' && 'current' in ref) {
-        return ref as React.RefObject<HTMLFormElement>;
+        return ref as React.RefObject<HTMLFormElement | null>;
       }
       return internalRef;
     }, [ref]);
@@ -614,13 +224,21 @@ Select.displayName = "Select";
 // TRIGGER COMPONENT
 // ============================================================================
 
+/**
+ * Select trigger button component.
+ * Opens/closes the select dropdown and displays the selected value.
+ * 
+ * @param props - Select trigger configuration
+ * @param ref - Forwarded ref to the button element
+ * @returns The rendered select trigger
+ */
 export const SelectTrigger = React.forwardRef<HTMLButtonElement, SelectTriggerProps>(
   ({ children, className, variant = "outline", size = "default", asChild = false, ...props }, ref) => {
     const { open, disabled, value, actions, direction = 'down' } = useSelectContext();
     const opensUpward = direction === 'up';
 
     // Use ref to store the latest handleClick to avoid re-creating the effect
-    const handleClickRef = React.useRef<(e: React.MouseEvent) => void>();
+    const handleClickRef = React.useRef<(e: React.MouseEvent) => void>(undefined);
     
     const handleClick = React.useCallback((e: React.MouseEvent) => {
       if (disabled) {
@@ -687,22 +305,26 @@ export const SelectTrigger = React.forwardRef<HTMLButtonElement, SelectTriggerPr
     };
 
     if (asChild) {
-      const childChildren = React.Children.toArray((children as React.ReactElement).props.children);
-      const hasChevron = childChildren.some(child => 
-        React.isValidElement(child) && 
-        (child.type === ChevronDown || 
-         (child.type === 'svg' && child.props['data-testid'] === 'chevron-down') ||
-         (typeof child === 'object' && 'type' in child && typeof child.type === 'function' && child.type.name === 'ChevronDown'))
-      );
+      const childElement = children as React.ReactElement<{ children?: React.ReactNode; [key: string]: unknown }>;
+      const childChildren = React.Children.toArray(childElement.props.children);
+      const hasChevron = childChildren.some(child => {
+        if (React.isValidElement(child)) {
+          const childProps = child.props as { 'data-testid'?: string; [key: string]: unknown };
+          return child.type === ChevronDown || 
+                 (child.type === 'svg' && childProps['data-testid'] === 'chevron-down') ||
+                 (typeof child === 'object' && 'type' in child && typeof child.type === 'function' && child.type.name === 'ChevronDown');
+        }
+        return false;
+      });
 
       // Merge child's className with triggerProps className
-      const childClassName = (children as React.ReactElement).props.className;
+      const childClassName = (children as React.ReactElement<any>).props.className;
       const mergedClassName = cn(
         triggerProps.className,
         childClassName
       );
 
-      return React.cloneElement(children as React.ReactElement, {
+      return React.cloneElement(children as React.ReactElement<any>, {
         ...triggerProps,
         className: mergedClassName,
         children: hasChevron ? childChildren : [
@@ -776,6 +398,14 @@ SelectTrigger.displayName = "SelectTrigger";
 // VALUE COMPONENT
 // ============================================================================
 
+/**
+ * Select value display component.
+ * Shows the selected value or placeholder text.
+ * 
+ * @param props - Select value configuration
+ * @param ref - Forwarded ref to the span element
+ * @returns The rendered select value display
+ */
 export const SelectValue = React.forwardRef<HTMLSpanElement, SelectValueProps>(
   ({ placeholder = "Select an option...", children }, ref) => {
     const { selectedText } = useSelectContext();
@@ -798,6 +428,14 @@ SelectValue.displayName = "SelectValue";
 // CONTENT COMPONENT
 // ============================================================================
 
+/**
+ * Select content/dropdown component.
+ * Contains the list of selectable options.
+ * 
+ * @param props - Select content configuration
+ * @param ref - Forwarded ref to the list element
+ * @returns The rendered select content
+ */
 export const SelectContent = React.forwardRef<HTMLUListElement, SelectContentProps>(
   ({ 
     children, 
@@ -906,24 +544,19 @@ SelectContent.displayName = "SelectContent";
 // ITEM COMPONENT
 // ============================================================================
 
+/**
+ * Select item component.
+ * Represents a single selectable option in the dropdown.
+ * 
+ * @param props - Select item configuration
+ * @param ref - Forwarded ref to the list item element
+ * @returns The rendered select item
+ */
 export const SelectItem = React.forwardRef<HTMLLIElement, SelectItemProps>(
   ({ value, children, disabled = false, className, onClick }, ref) => {
     const { value: selectedValue, actions, registerItem, unregisterItem } = useSelectContext();
     const isSelected = selectedValue === value;
-    
-    // Extract text content from children for display
-    const getTextContent = (children: React.ReactNode): string => {
-      if (typeof children === 'string') return children;
-      if (typeof children === 'number') return children.toString();
-      if (React.isValidElement(children) && children.props.children) {
-        return getTextContent(children.props.children);
-      }
-      if (Array.isArray(children)) {
-        return children.map(getTextContent).join('');
-      }
-      return '';
-    };
-    
+
     const itemText = getTextContent(children);
 
     // Register this item when it mounts or text changes
@@ -1014,6 +647,14 @@ SelectItem.displayName = "SelectItem";
 // ADDITIONAL COMPONENTS (for backward compatibility)
 // ============================================================================
 
+/**
+ * Select group component.
+ * Groups related select items together.
+ * 
+ * @param props - Select group configuration
+ * @param ref - Forwarded ref to the div element
+ * @returns The rendered select group
+ */
 export const SelectGroup = React.forwardRef<HTMLDivElement, { children: React.ReactNode; className?: string }>(
   ({ children, className }, ref) => {
     return (
@@ -1025,6 +666,14 @@ export const SelectGroup = React.forwardRef<HTMLDivElement, { children: React.Re
 );
 SelectGroup.displayName = "SelectGroup";
 
+/**
+ * Select label component.
+ * Provides a label for a group of select items.
+ * 
+ * @param props - Select label configuration
+ * @param ref - Forwarded ref to the div element
+ * @returns The rendered select label
+ */
 export const SelectLabel = React.forwardRef<HTMLDivElement, { children: React.ReactNode; className?: string }>(
   ({ children, className }, ref) => {
     return (
@@ -1036,6 +685,14 @@ export const SelectLabel = React.forwardRef<HTMLDivElement, { children: React.Re
 );
 SelectLabel.displayName = "SelectLabel";
 
+/**
+ * Select separator component.
+ * Provides visual separation between groups of select items.
+ * 
+ * @param props - Select separator configuration
+ * @param ref - Forwarded ref to the div element
+ * @returns The rendered select separator
+ */
 export const SelectSeparator = React.forwardRef<HTMLDivElement, { className?: string }>(
   ({ className }, ref) => {
     return (

package/src/components/Select/context.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+import type { SelectContextValue } from "./types";
+
+/**
+ * Select context for sharing state between Select components.
+ */
+export const SelectContext =
+  React.createContext<SelectContextValue | null>(null);
+
+/**
+ * Hook to access Select context.
+ * Must be used within a Select component.
+ * 
+ * @returns Select context value
+ * @throws Error if used outside Select component
+ */
+export const useSelectContext = () => {
+  const context = React.useContext(SelectContext);
+  if (!context) {
+    throw new Error("Select components must be used within a Select");
+  }
+  return context;
+};