@jmruthers/pace-core 0.4.1 → 0.5.3

package/src/components/Checkbox/Checkbox.test.tsx

@@ -0,0 +1,461 @@
+/**
+ * @file Checkbox Component Tests
+ * @description Comprehensive tests for Checkbox component
+ * @package @jmruthers/pace-core
+ */
+
+import React from 'react';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Checkbox } from './Checkbox';
+import { renderWithProviders } from '../../__tests__/helpers/test-utils';
+
+describe('Checkbox Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders with default props', () => {
+      renderWithProviders(<Checkbox />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toBeInTheDocument();
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it('renders with custom className', () => {
+      renderWithProviders(<Checkbox className="custom-checkbox" />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveClass('custom-checkbox');
+    });
+
+    it('renders with custom id', () => {
+      renderWithProviders(<Checkbox id="test-checkbox" />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('id', 'test-checkbox');
+    });
+
+    it('renders with custom name (Radix UI handles this internally)', () => {
+      renderWithProviders(<Checkbox name="test-name" />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toBeInTheDocument();
+      // Note: Radix UI Checkbox doesn't expose name attribute directly
+    });
+
+    it('renders with value prop', () => {
+      renderWithProviders(<Checkbox value="test-value" />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('value', 'test-value');
+    });
+
+    it('forwards ref correctly', () => {
+      const ref = React.createRef<HTMLButtonElement>();
+      renderWithProviders(<Checkbox ref={ref} />);
+      expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+    });
+
+    it('applies all HTML attributes', () => {
+      renderWithProviders(
+        <Checkbox 
+          data-testid="test-checkbox" 
+          aria-label="Test checkbox"
+          title="Test title"
+        />
+      );
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('data-testid', 'test-checkbox');
+      expect(checkbox).toHaveAttribute('aria-label', 'Test checkbox');
+      expect(checkbox).toHaveAttribute('title', 'Test title');
+    });
+  });
+
+  describe('State Management', () => {
+    it('renders as unchecked by default', () => {
+      renderWithProviders(<Checkbox />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it('renders as checked when checked prop is true', () => {
+      renderWithProviders(<Checkbox checked={true} />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toBeChecked();
+    });
+
+    it('renders as unchecked when checked prop is false', () => {
+      renderWithProviders(<Checkbox checked={false} />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it('handles controlled state changes', () => {
+      const handleCheckedChange = vi.fn();
+      renderWithProviders(
+        <Checkbox 
+          checked={false} 
+          onCheckedChange={handleCheckedChange} 
+        />
+      );
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it('handles indeterminate state', () => {
+      renderWithProviders(<Checkbox checked="indeterminate" />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('aria-checked', 'mixed');
+    });
+  });
+
+  describe('Disabled State', () => {
+    it('renders as disabled when disabled prop is true', () => {
+      renderWithProviders(<Checkbox disabled={true} />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toBeDisabled();
+    });
+
+    it('renders as enabled when disabled prop is false', () => {
+      renderWithProviders(<Checkbox disabled={false} />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).not.toBeDisabled();
+    });
+
+    it('applies disabled styling', () => {
+      renderWithProviders(<Checkbox disabled={true} />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveClass('disabled:cursor-not-allowed', 'disabled:opacity-50');
+    });
+  });
+
+  describe('Event Handling', () => {
+    it('handles click events', async () => {
+      const handleCheckedChange = vi.fn();
+      const user = userEvent.setup();
+      
+      renderWithProviders(
+        <Checkbox onCheckedChange={handleCheckedChange} />
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      await user.click(checkbox);
+      
+      expect(handleCheckedChange).toHaveBeenCalledTimes(1);
+      expect(handleCheckedChange).toHaveBeenCalledWith(true);
+    });
+
+    it('handles keyboard events (Space)', async () => {
+      const handleCheckedChange = vi.fn();
+      const user = userEvent.setup();
+      
+      renderWithProviders(
+        <Checkbox onCheckedChange={handleCheckedChange} />
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      checkbox.focus();
+      await user.keyboard(' ');
+      
+      expect(handleCheckedChange).toHaveBeenCalledTimes(1);
+      expect(handleCheckedChange).toHaveBeenCalledWith(true);
+    });
+
+    it('handles keyboard events (Enter - Radix UI uses Space)', async () => {
+      const handleCheckedChange = vi.fn();
+      const user = userEvent.setup();
+      
+      renderWithProviders(
+        <Checkbox onCheckedChange={handleCheckedChange} />
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      checkbox.focus();
+      await user.keyboard('{Enter}');
+      
+      // Note: Radix UI Checkbox primarily uses Space key, Enter may not trigger
+      // This test documents the expected behavior
+      expect(handleCheckedChange).toHaveBeenCalledTimes(0);
+    });
+
+    it('toggles state on click', async () => {
+      const handleCheckedChange = vi.fn();
+      const user = userEvent.setup();
+      
+      const { rerender } = renderWithProviders(
+        <Checkbox checked={false} onCheckedChange={handleCheckedChange} />
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      await user.click(checkbox);
+      
+      expect(handleCheckedChange).toHaveBeenCalledWith(true);
+      
+      // Simulate state change
+      rerender(<Checkbox checked={true} onCheckedChange={handleCheckedChange} />);
+      expect(checkbox).toBeChecked();
+      
+      await user.click(checkbox);
+      expect(handleCheckedChange).toHaveBeenCalledWith(false);
+    });
+
+    it('does not trigger events when disabled', async () => {
+      const handleCheckedChange = vi.fn();
+      const user = userEvent.setup();
+      
+      renderWithProviders(
+        <Checkbox disabled={true} onCheckedChange={handleCheckedChange} />
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      await user.click(checkbox);
+      
+      expect(handleCheckedChange).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('has proper ARIA attributes', () => {
+      renderWithProviders(<Checkbox />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('type', 'button');
+    });
+
+    it('supports aria-label', () => {
+      renderWithProviders(<Checkbox aria-label="Accept terms" />);
+      const checkbox = screen.getByRole('checkbox', { name: 'Accept terms' });
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    it('supports aria-labelledby', () => {
+      renderWithProviders(
+        <div>
+          <label id="terms-label">Accept terms and conditions</label>
+          <Checkbox aria-labelledby="terms-label" />
+        </div>
+      );
+      const checkbox = screen.getByRole('checkbox', { name: 'Accept terms and conditions' });
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    it('supports aria-describedby', () => {
+      renderWithProviders(
+        <div>
+          <Checkbox aria-describedby="terms-help" />
+          <div id="terms-help">Please read the terms carefully</div>
+        </div>
+      );
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('aria-describedby', 'terms-help');
+    });
+
+    it('announces state changes to screen readers', () => {
+      const { rerender } = renderWithProviders(<Checkbox checked={false} />);
+      let checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('aria-checked', 'false');
+      
+      rerender(<Checkbox checked={true} />);
+      checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveAttribute('aria-checked', 'true');
+    });
+
+    it('is keyboard accessible', () => {
+      renderWithProviders(<Checkbox />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).not.toHaveAttribute('tabindex', '-1');
+    });
+
+    it('has focus visible styles', () => {
+      renderWithProviders(<Checkbox />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveClass('focus-visible:outline-none', 'focus-visible:ring-2');
+    });
+  });
+
+  describe('Visual States', () => {
+    it('applies checked state styling', () => {
+      renderWithProviders(<Checkbox checked={true} />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveClass('data-[state=checked]:bg-primary', 'data-[state=checked]:text-primary-foreground');
+    });
+
+    it('shows check icon when checked', () => {
+      renderWithProviders(<Checkbox checked={true} />);
+      const checkbox = screen.getByRole('checkbox');
+      // The check icon is rendered by Radix UI internally
+      // We can verify the checkbox is checked instead
+      expect(checkbox).toBeChecked();
+    });
+
+    it('has proper sizing', () => {
+      renderWithProviders(<Checkbox />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveClass('h-4', 'w-4');
+    });
+
+    it('has proper border and background styling', () => {
+      renderWithProviders(<Checkbox />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toHaveClass('rounded-sm', 'border', 'border-primary');
+    });
+  });
+
+  describe('Form Integration', () => {
+    it('works with form labels', () => {
+      renderWithProviders(
+        <div>
+          <label htmlFor="terms-checkbox">Accept terms and conditions</label>
+          <Checkbox id="terms-checkbox" />
+        </div>
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      const label = screen.getByText('Accept terms and conditions');
+      
+      expect(checkbox).toHaveAttribute('id', 'terms-checkbox');
+      expect(label).toHaveAttribute('for', 'terms-checkbox');
+    });
+
+    it('works with form submission', async () => {
+      const handleSubmit = vi.fn((e) => e.preventDefault());
+      const user = userEvent.setup();
+      
+      renderWithProviders(
+        <form onSubmit={handleSubmit}>
+          <Checkbox name="terms" />
+          <button type="submit">Submit</button>
+        </form>
+      );
+      
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      expect(handleSubmit).toHaveBeenCalledTimes(1);
+    });
+
+    it('works with form validation', () => {
+      renderWithProviders(
+        <Checkbox 
+          aria-invalid={true}
+          aria-describedby="error-message"
+        />
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      // Radix UI Checkbox doesn't support required attribute directly
+      expect(checkbox).toHaveAttribute('aria-invalid', 'true');
+      expect(checkbox).toHaveAttribute('aria-describedby', 'error-message');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('handles missing onCheckedChange gracefully', () => {
+      renderWithProviders(<Checkbox checked={true} />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toBeChecked();
+    });
+
+    it('handles invalid props gracefully', () => {
+      // @ts-expect-error Testing invalid prop
+      renderWithProviders(<Checkbox invalidProp="test" />);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toBeInTheDocument();
+    });
+
+    it('handles null children gracefully', () => {
+      renderWithProviders(<Checkbox>{null}</Checkbox>);
+      const checkbox = screen.getByRole('checkbox');
+      expect(checkbox).toBeInTheDocument();
+    });
+  });
+
+  describe('Integration', () => {
+    it('works with multiple checkboxes', () => {
+      renderWithProviders(
+        <div>
+          <Checkbox id="option1" />
+          <Checkbox id="option2" />
+          <Checkbox id="option3" />
+        </div>
+      );
+      
+      expect(screen.getAllByRole('checkbox')).toHaveLength(3);
+    });
+
+    it('works with checkbox groups', () => {
+      renderWithProviders(
+        <fieldset>
+          <legend>Select your preferences</legend>
+          <Checkbox id="email" value="email" />
+          <label htmlFor="email">Email notifications</label>
+          <Checkbox id="sms" value="sms" />
+          <label htmlFor="sms">SMS notifications</label>
+        </fieldset>
+      );
+      
+      const checkboxes = screen.getAllByRole('checkbox');
+      expect(checkboxes).toHaveLength(2);
+      // Radix UI Checkbox doesn't expose name attribute directly
+      expect(checkboxes[0]).toHaveAttribute('id', 'email');
+      expect(checkboxes[1]).toHaveAttribute('id', 'sms');
+    });
+
+    it('works with controlled state management', async () => {
+      const TestComponent = () => {
+        const [checked, setChecked] = React.useState(false);
+        return (
+          <div>
+            <Checkbox 
+              checked={checked} 
+              onCheckedChange={setChecked}
+            />
+            <span data-testid="status">{checked ? 'checked' : 'unchecked'}</span>
+          </div>
+        );
+      };
+      
+      const user = userEvent.setup();
+      renderWithProviders(<TestComponent />);
+      
+      const checkbox = screen.getByRole('checkbox');
+      const status = screen.getByTestId('status');
+      
+      expect(status).toHaveTextContent('unchecked');
+      
+      await user.click(checkbox);
+      expect(status).toHaveTextContent('checked');
+    });
+
+    it('works with external state management', async () => {
+      const externalState = { checked: false };
+      const handleChange = vi.fn((checked) => {
+        externalState.checked = checked;
+      });
+      
+      const user = userEvent.setup();
+      renderWithProviders(
+        <Checkbox 
+          checked={externalState.checked} 
+          onCheckedChange={handleChange}
+        />
+      );
+      
+      const checkbox = screen.getByRole('checkbox');
+      await user.click(checkbox);
+      
+      expect(handleChange).toHaveBeenCalledWith(true);
+    });
+  });
+
+  describe('Performance', () => {
+    it('renders efficiently with many checkboxes', () => {
+      const checkboxes = Array.from({ length: 100 }, (_, i) => (
+        <Checkbox key={i} id={`checkbox-${i}`} />
+      ));
+      
+      const startTime = performance.now();
+      renderWithProviders(<div>{checkboxes}</div>);
+      const endTime = performance.now();
+      
+      expect(screen.getAllByRole('checkbox')).toHaveLength(100);
+      expect(endTime - startTime).toBeLessThan(1000); // Should render in under 1 second
+    });
+  });
+});

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,75 @@
+/**
+ * @file Checkbox Component
+ * @package @jmruthers/pace-core
+ * @module Components
+ * @since 0.1.0
+ *
+ * An accessible checkbox component built on top of Radix UI's Checkbox primitive.
+ * Provides a customizable checkbox input with proper keyboard and screen reader support.
+ *
+ * Features:
+ * - Customizable styling via className
+ * - Built-in focus and hover states
+ * - Disabled state support
+ * - Checked state indicator
+ * - Full keyboard navigation
+ * - Screen reader support
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Checkbox />
+ *
+ * // With label
+ * <div className="flex items-center space-x-2">
+ *   <Checkbox id="terms" />
+ *   <label htmlFor="terms">Accept terms and conditions</label>
+ * </div>
+ *
+ * // Disabled state
+ * <Checkbox disabled />
+ *
+ * // Controlled component
+ * const [checked, setChecked] = React.useState(false);
+ * <Checkbox 
+ *   checked={checked}
+ *   onCheckedChange={setChecked}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Uses Radix UI's accessible checkbox primitive
+ * - Proper keyboard navigation (Space to toggle)
+ * - Screen reader announcements for state changes
+ * - Focus visible styles for keyboard users
+ * - ARIA attributes handled automatically
+ */
+
+import * as React from "react"
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox"
+import { Check } from "lucide-react"
+
+import { cn } from "../../utils/cn"
+
+const Checkbox = React.forwardRef<
+  React.ElementRef<typeof CheckboxPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <CheckboxPrimitive.Root
+    ref={ref}
+    className={cn(
+      "peer h-4 w-4 shrink-0 rounded-sm border border-primary ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
+      className
+    )}
+    {...props}
+  >
+    <CheckboxPrimitive.Indicator
+      className={cn("flex items-center justify-center text-current")}
+    >
+      <Check className="h-4 w-4" />
+    </CheckboxPrimitive.Indicator>
+  </CheckboxPrimitive.Root>
+))
+Checkbox.displayName = CheckboxPrimitive.Root.displayName
+
+export { Checkbox }

package/src/components/Checkbox/__mocks__/Checkbox.tsx

@@ -0,0 +1,2 @@
+import React from 'react';
+export const Checkbox = (props: any) => <input data-testid="checkbox-component" type="checkbox" {...props} />; 

package/src/components/Checkbox/index.ts

@@ -0,0 +1,2 @@
+
+export { Checkbox } from './Checkbox';