@jmruthers/pace-core 0.5.181 → 0.5.182

package/src/components/Select/Select.tsx

@@ -16,19 +16,53 @@ import * as React from "react";
 import { Search, X, ChevronDown, Check } from "lucide-react";
 import { Button, type ButtonProps } from "../Button/Button";
 import { cn } from "../../utils/core/cn";
-import { 
-  useSelectState, 
-  useSelectEvents, 
-  useSelectSearch,
-  type SelectState,
-  type SelectActions,
-  type UseSelectStateProps
-} from "./hooks";
 
 // ============================================================================
 // 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;
@@ -70,6 +104,231 @@ export interface SelectItemProps {
   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(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      const selectElement = selectRef.current;
+      const clickedElement = event.target as Element;
+      const isSelectItem = clickedElement?.closest('[data-testid="select-item"]');
+      const isSearchInput = clickedElement?.closest('[data-testid="select-search-input"]');
+      const isSelectContent = clickedElement?.closest('[data-testid="select-content"]');
+      
+      if (state.open && selectElement && !selectElement.contains(event.target as Node) && !isSelectItem && !isSearchInput && !isSelectContent && !isSelecting) {
+        actions.setOpen(false);
+      }
+    };
+
+    if (state.open) {
+      document.addEventListener('mousedown', handleClickOutside);
+      return () => {
+        document.removeEventListener('mousedown', handleClickOutside);
+      };
+    }
+  }, [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
 // ============================================================================
@@ -117,7 +376,7 @@ const findSelectItemText = (children: React.ReactNode, targetValue: string): str
   
   // Handle React elements directly if it's a single element
   if (React.isValidElement(children)) {
-    const props = (children as React.ReactElement).props as any;
+    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) {
@@ -141,7 +400,7 @@ const findSelectItemText = (children: React.ReactNode, targetValue: string): str
   for (const child of childrenArray) {
     if (!React.isValidElement(child)) continue;
     
-    const props = child.props as any;
+    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
@@ -660,7 +919,14 @@ export const SelectItem = React.forwardRef<HTMLLIElement, SelectItemProps>(
         case ' ':
           e.preventDefault();
           if (onClick) {
-            onClick(e as any);
+            // Create a synthetic mouse event for onClick handler compatibility
+            const syntheticEvent = {
+              ...e,
+              type: 'click',
+              currentTarget: e.currentTarget,
+              target: e.target,
+            } as unknown as React.MouseEvent;
+            onClick(syntheticEvent);
           }
           actions.setValue(value, itemText);
           // Note: setValue already handles closing the dropdown

package/src/components/Select/index.ts

@@ -1,2 +1 @@
-export * from './Select';
-// Note: hooks.ts is intentionally not exported (internal implementation detail) 
+export * from './Select'; 

package/src/components/SessionRestorationLoader/SessionRestorationLoader.test.tsx

@@ -0,0 +1,232 @@
+/**
+ * @file SessionRestorationLoader Component Tests
+ * @package @jmruthers/pace-core
+ * @module Components/SessionRestorationLoader
+ * @since 0.1.0
+ *
+ * Comprehensive test suite for the SessionRestorationLoader component.
+ * Tests cover rendering, accessibility, styling, and edge cases.
+ */
+
+import React from 'react';
+import { screen } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SessionRestorationLoader, SessionRestorationLoaderProps } from './SessionRestorationLoader';
+import { renderWithProviders } from '../../__tests__/helpers/test-utils';
+
+// Mock the LoadingSpinner component
+vi.mock('../LoadingSpinner/LoadingSpinner', () => ({
+  LoadingSpinner: ({ size, className }: { size?: string; className?: string }) => (
+    <div data-testid="loading-spinner" data-size={size} className={className}>
+      Loading Spinner
+    </div>
+  )
+}));
+
+describe('SessionRestorationLoader Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders with default props', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const container = screen.getByRole('status');
+      expect(container).toBeInTheDocument();
+      expect(screen.getByText('Restoring session...')).toBeInTheDocument();
+      expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
+    });
+
+    it('renders with custom message', () => {
+      const customMessage = 'Restoring your session...';
+      renderWithProviders(<SessionRestorationLoader message={customMessage} />);
+
+      expect(screen.getByText(customMessage)).toBeInTheDocument();
+    });
+
+    it('renders with custom className', () => {
+      const customClass = 'custom-loader';
+      renderWithProviders(<SessionRestorationLoader className={customClass} />);
+
+      const container = screen.getByRole('status');
+      expect(container).toHaveClass(customClass);
+    });
+
+    it('has proper DOM structure', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const container = screen.getByRole('status');
+      expect(container).toBeInTheDocument();
+      expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
+      expect(screen.getByText('Restoring session...')).toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('has proper status role for screen readers', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const container = screen.getByRole('status');
+      expect(container).toBeInTheDocument();
+    });
+
+    it('has aria-live attribute for dynamic updates', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const container = screen.getByRole('status');
+      expect(container).toHaveAttribute('aria-live', 'polite');
+    });
+
+    it('has aria-label with the message', () => {
+      const message = 'Restoring your session...';
+      renderWithProviders(<SessionRestorationLoader message={message} />);
+
+      const container = screen.getByRole('status');
+      expect(container).toHaveAttribute('aria-label', message);
+    });
+
+    it('is accessible to screen readers', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const container = screen.getByRole('status');
+      expect(container).toHaveAttribute('role', 'status');
+      expect(container).toHaveAttribute('aria-live', 'polite');
+    });
+  });
+
+  describe('Styling and CSS Classes', () => {
+    it('applies base container classes', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const container = screen.getByRole('status');
+      expect(container).toHaveClass(
+        'flex',
+        'flex-col',
+        'items-center',
+        'justify-center',
+        'h-screen',
+        'w-full',
+        'gap-4',
+        'text-center',
+        'p-4',
+        'bg-background'
+      );
+    });
+
+    it('applies custom className alongside default classes', () => {
+      renderWithProviders(<SessionRestorationLoader className="custom-class" />);
+
+      const container = screen.getByRole('status');
+      expect(container).toHaveClass('custom-class');
+      expect(container).toHaveClass('flex', 'flex-col'); // Base classes still present
+    });
+
+    it('applies correct message styling', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const messageElement = screen.getByText('Restoring session...');
+      expect(messageElement).toHaveClass('text-sm', 'text-sec-600');
+    });
+
+    it('passes size prop to LoadingSpinner', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const spinner = screen.getByTestId('loading-spinner');
+      expect(spinner).toHaveAttribute('data-size', 'lg');
+    });
+  });
+
+  describe('Component Behavior', () => {
+    it('is a pure component with no side effects', () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      renderWithProviders(<SessionRestorationLoader />);
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+
+      consoleSpy.mockRestore();
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('does not produce any warnings or errors', () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      renderWithProviders(<SessionRestorationLoader />);
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+
+      consoleWarnSpy.mockRestore();
+      consoleErrorSpy.mockRestore();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles empty message gracefully', () => {
+      renderWithProviders(<SessionRestorationLoader message="" />);
+
+      const container = screen.getByRole('status');
+      expect(container).toBeInTheDocument();
+      expect(container).toHaveAttribute('aria-label', '');
+      // The message div should exist even if empty
+      const messageDiv = container.querySelector('.text-sm.text-sec-600');
+      expect(messageDiv).toBeInTheDocument();
+    });
+
+    it('handles very long messages', () => {
+      const longMessage = 'A'.repeat(500);
+      renderWithProviders(<SessionRestorationLoader message={longMessage} />);
+
+      expect(screen.getByText(longMessage)).toBeInTheDocument();
+    });
+
+    it('handles special characters in message', () => {
+      const specialMessage = 'Restoring session... <>&"\'';
+      renderWithProviders(<SessionRestorationLoader message={specialMessage} />);
+
+      expect(screen.getByText(specialMessage)).toBeInTheDocument();
+    });
+
+    it('handles undefined className gracefully', () => {
+      renderWithProviders(<SessionRestorationLoader className={undefined} />);
+
+      const container = screen.getByRole('status');
+      expect(container).toBeInTheDocument();
+      expect(container).toHaveClass('flex', 'flex-col');
+    });
+
+    it('handles empty className gracefully', () => {
+      renderWithProviders(<SessionRestorationLoader className="" />);
+
+      const container = screen.getByRole('status');
+      expect(container).toBeInTheDocument();
+      expect(container).toHaveClass('flex', 'flex-col');
+    });
+  });
+
+  describe('Integration', () => {
+    it('works with LoadingSpinner component', () => {
+      renderWithProviders(<SessionRestorationLoader />);
+
+      const spinner = screen.getByTestId('loading-spinner');
+      expect(spinner).toBeInTheDocument();
+      expect(spinner).toHaveAttribute('data-size', 'lg');
+    });
+
+    it('maintains consistent structure across re-renders', () => {
+      const { rerender } = renderWithProviders(<SessionRestorationLoader message="Message 1" />);
+
+      expect(screen.getByText('Message 1')).toBeInTheDocument();
+
+      rerender(<SessionRestorationLoader message="Message 2" />);
+
+      expect(screen.getByText('Message 2')).toBeInTheDocument();
+      expect(screen.queryByText('Message 1')).not.toBeInTheDocument();
+    });
+  });
+});
+

package/src/components/SessionRestorationLoader/SessionRestorationLoader.tsx

@@ -6,41 +6,62 @@
  *
  * Displays a consistent loading state while the authentication service
  * restores the Supabase session from persistent storage.
+ *
+ * Features:
+ * - Full-screen loading state
+ * - Accessible with proper ARIA attributes
+ * - Screen reader friendly
+ * - Customizable message
+ * - Uses LoadingSpinner component
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <SessionRestorationLoader />
+ *
+ * // With custom message
+ * <SessionRestorationLoader message="Restoring your session..." />
+ * ```
+ *
+ * @accessibility
+ * - WCAG 2.1 AA compliant
+ * - Proper ARIA role="status"
+ * - Screen reader announcement
+ * - High contrast support
+ *
+ * @dependencies
+ * - React 18+ - Component framework
+ * - LoadingSpinner - Spinner component
+ * - Tailwind CSS - Styling
  */
 
 import React from 'react';
 import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
+import { cn } from '../../utils/core/cn';
 
 export interface SessionRestorationLoaderProps {
   /** Customise the status message displayed under the spinner */
   message?: string;
+  /** Additional CSS classes for styling */
+  className?: string;
 }
 
 export const SessionRestorationLoader: React.FC<SessionRestorationLoaderProps> = ({
-  message = 'Restoring session...'
+  message = 'Restoring session...',
+  className
 }) => {
   return (
     <div
-      style={{
-        display: 'flex',
-        flexDirection: 'column',
-        alignItems: 'center',
-        justifyContent: 'center',
-        height: '100vh',
-        width: '100%',
-        gap: '1rem',
-        textAlign: 'center',
-        padding: '1rem',
-        background: 'var(--background, transparent)'
-      }}
+      className={cn(
+        'flex flex-col items-center justify-center h-screen w-full gap-4 text-center p-4 bg-background',
+        className
+      )}
+      role="status"
+      aria-live="polite"
+      aria-label={message}
     >
       <LoadingSpinner size="lg" />
-      <div
-        style={{
-          fontSize: '0.95rem',
-          color: 'var(--muted-foreground, #6b7280)'
-        }}
-      >
+      <div className="text-sm text-sec-600">
         {message}
       </div>
     </div>