@jmruthers/pace-core 0.5.184 → 0.5.185

package/src/components/DateTimeField/DateTimeField.test.tsx

@@ -0,0 +1,358 @@
+/**
+ * @file DateTimeField Component Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DateTimeField/__tests__
+ * @since 0.1.0
+ *
+ * Comprehensive test suite for DateTimeField component.
+ * Tests cover all major functionality, edge cases, and accessibility.
+ */
+
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { DateTimeField } from './DateTimeField';
+
+// Mock timezone utilities
+vi.mock('../../utils/timezone', () => ({
+  toZonedTime: vi.fn((date: Date, tz: string) => {
+    // Simple mock: return date as-is for testing
+    return date;
+  }),
+  fromZonedTime: vi.fn((date: Date, tz: string) => {
+    // Simple mock: return date as-is for testing
+    return date;
+  }),
+  getUserTimeZone: vi.fn(() => 'America/New_York')
+}));
+
+describe('DateTimeField Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders with default props', () => {
+      const onChange = vi.fn();
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} />);
+      
+      expect(screen.getByText('Start Time')).toBeInTheDocument();
+      expect(screen.getByLabelText(/Start Time/)).toBeInTheDocument();
+    });
+
+    it('renders with required indicator', () => {
+      const onChange = vi.fn();
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} required />);
+      
+      const label = screen.getByText('Start Time');
+      expect(label).toBeInTheDocument();
+      // Required indicator should be present
+      expect(screen.getByLabelText(/required/i)).toBeInTheDocument();
+    });
+
+    it('renders with helper text', () => {
+      const onChange = vi.fn();
+      render(
+        <DateTimeField
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+          helperText="Select a start time"
+        />
+      );
+      
+      expect(screen.getByText('Select a start time')).toBeInTheDocument();
+    });
+
+    it('renders with error message', () => {
+      const onChange = vi.fn();
+      render(
+        <DateTimeField
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+          error="Invalid date"
+        />
+      );
+      
+      expect(screen.getByText('Invalid date')).toBeInTheDocument();
+      expect(screen.getByRole('alert')).toBeInTheDocument();
+    });
+
+    it('renders with custom id', () => {
+      const onChange = vi.fn();
+      render(
+        <DateTimeField
+          id="custom-id"
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+        />
+      );
+      
+      expect(screen.getByLabelText(/Start Time/)).toHaveAttribute('id', 'custom-id');
+    });
+  });
+
+  describe('Value Display and Conversion', () => {
+    it('displays ISO string value correctly', () => {
+      const onChange = vi.fn();
+      const value = '2024-01-15T10:00:00Z';
+      render(<DateTimeField label="Start Time" value={value} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      expect(input.value).toBeTruthy();
+    });
+
+    it('displays Date object value correctly', () => {
+      const onChange = vi.fn();
+      const value = new Date('2024-01-15T10:00:00Z');
+      render(<DateTimeField label="Start Time" value={value} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      expect(input.value).toBeTruthy();
+    });
+
+    it('handles undefined value', () => {
+      const onChange = vi.fn();
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      expect(input.value).toBe('');
+    });
+
+    it('displays timezone information when not UTC', () => {
+      const onChange = vi.fn();
+      render(
+        <DateTimeField
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+          timezone="Europe/London"
+        />
+      );
+      
+      expect(screen.getByText('Europe/London')).toBeInTheDocument();
+    });
+
+    it('displays "Local" when timezone matches user timezone', () => {
+      const onChange = vi.fn();
+      render(
+        <DateTimeField
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+          timezone="America/New_York"
+        />
+      );
+      
+      expect(screen.getByText('Local')).toBeInTheDocument();
+    });
+
+    it('does not display timezone for UTC', () => {
+      const onChange = vi.fn();
+      const { container } = render(
+        <DateTimeField
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+          timezone="UTC"
+        />
+      );
+      
+      const timezoneDisplay = container.querySelector('.text-muted-foreground');
+      expect(timezoneDisplay).not.toBeInTheDocument();
+    });
+  });
+
+  describe('onChange Behavior', () => {
+    it('calls onChange with ISO string when returnAsDate is false', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      await user.type(input, '2024-01-15T10:00');
+      
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalled();
+      });
+    });
+
+    it('calls onChange with Date object when returnAsDate is true', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      
+      render(
+        <DateTimeField
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+          returnAsDate
+        />
+      );
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      await user.type(input, '2024-01-15T10:00');
+      
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalled();
+        const callArg = onChange.mock.calls[onChange.mock.calls.length - 1][0];
+        expect(callArg).toBeInstanceOf(Date);
+      });
+    });
+
+    it('calls onChange with undefined when input is cleared', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      
+      // Set an initial value first
+      const { rerender } = render(
+        <DateTimeField label="Start Time" value="2024-01-15T10:00:00Z" onChange={onChange} />
+      );
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      await user.clear(input);
+      
+      // Trigger change event manually to simulate clearing
+      fireEvent.change(input, { target: { value: '' } });
+      
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalledWith(undefined);
+      });
+    });
+  });
+
+  describe('User Editing', () => {
+    it('prevents unwanted conversions during editing', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      const value = '2024-01-15T10:00:00Z';
+      
+      render(<DateTimeField label="Start Time" value={value} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      await user.click(input);
+      await user.type(input, '2024-01-16');
+      
+      // Should not trigger multiple onChange calls during typing
+      await waitFor(() => {
+        expect(onChange).toHaveBeenCalled();
+      });
+    });
+
+    it('handles blur event correctly', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      await user.click(input);
+      await user.tab();
+      
+      // Blur should stop editing mode
+      expect(input).not.toHaveFocus();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles invalid date string gracefully', () => {
+      const onChange = vi.fn();
+      render(<DateTimeField label="Start Time" value="invalid-date" onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      expect(input.value).toBe('');
+    });
+
+    it('handles null value gracefully', () => {
+      const onChange = vi.fn();
+      // @ts-expect-error - Testing edge case
+      render(<DateTimeField label="Start Time" value={null} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      expect(input.value).toBe('');
+    });
+
+    it('handles empty string value', () => {
+      const onChange = vi.fn();
+      render(<DateTimeField label="Start Time" value="" onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      expect(input.value).toBe('');
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('associates label with input via htmlFor', () => {
+      const onChange = vi.fn();
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} />);
+      
+      const label = screen.getByText('Start Time');
+      const input = screen.getByLabelText(/Start Time/);
+      
+      expect(label).toBeInTheDocument();
+      expect(input).toBeInTheDocument();
+      expect(input).toHaveAttribute('id');
+    });
+
+    it('supports keyboard navigation', async () => {
+      const onChange = vi.fn();
+      const user = userEvent.setup();
+      
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} />);
+      
+      const input = screen.getByLabelText(/Start Time/);
+      await user.tab();
+      
+      expect(input).toHaveFocus();
+    });
+
+    it('announces errors to screen readers', () => {
+      const onChange = vi.fn();
+      render(
+        <DateTimeField
+          label="Start Time"
+          value={undefined}
+          onChange={onChange}
+          error="Invalid date"
+        />
+      );
+      
+      const errorMessage = screen.getByRole('alert');
+      expect(errorMessage).toBeInTheDocument();
+      expect(errorMessage).toHaveTextContent('Invalid date');
+    });
+
+    it('indicates required field to screen readers', () => {
+      const onChange = vi.fn();
+      render(<DateTimeField label="Start Time" value={undefined} onChange={onChange} required />);
+      
+      const requiredIndicator = screen.getByLabelText(/required/i);
+      expect(requiredIndicator).toBeInTheDocument();
+    });
+  });
+
+  describe('Controlled vs Uncontrolled', () => {
+    it('works as controlled component', () => {
+      const onChange = vi.fn();
+      const value = '2024-01-15T10:00:00Z';
+      
+      const { rerender } = render(
+        <DateTimeField label="Start Time" value={value} onChange={onChange} />
+      );
+      
+      const input = screen.getByLabelText(/Start Time/) as HTMLInputElement;
+      const initialValue = input.value;
+      
+      rerender(
+        <DateTimeField label="Start Time" value="2024-01-16T10:00:00Z" onChange={onChange} />
+      );
+      
+      expect(input.value).not.toBe(initialValue);
+    });
+  });
+});
+

package/src/components/DateTimeField/DateTimeField.tsx

@@ -0,0 +1,232 @@
+/**
+ * @file DateTimeField Component
+ * @package @jmruthers/pace-core
+ * @module Components/DateTimeField
+ * @since 0.1.0
+ *
+ * Form input component for datetime values with timezone support.
+ * Handles UTC ↔ timezone conversion automatically.
+ *
+ * Features:
+ * - Automatic UTC ↔ timezone conversion
+ * - Prevents unwanted conversions during user editing
+ * - Shows timezone information when not UTC
+ * - Supports both ISO string and Date object values
+ * - Uses native datetime-local input type
+ * - Accessible form field with proper labels
+ *
+ * @example
+ * ```tsx
+ * import { DateTimeField } from '@jmruthers/pace-core/components';
+ * import { useState } from 'react';
+ *
+ * function EventForm() {
+ *   const [startTime, setStartTime] = useState<string>();
+ *
+ *   return (
+ *     <DateTimeField
+ *       label="Start Time"
+ *       value={startTime}
+ *       onChange={setStartTime}
+ *       timezone="America/New_York"
+ *       required
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - Proper label association with htmlFor
+ * - Required field indicators
+ * - Screen reader friendly
+ * - Keyboard navigation support
+ * - Focus management
+ */
+
+import * as React from 'react';
+import { format, parse } from 'date-fns';
+import { Label } from '../Label';
+import { Input } from '../Input';
+import { cn } from '../../utils/core/cn';
+import { toZonedTime, fromZonedTime, getUserTimeZone } from '../../utils/timezone';
+
+/**
+ * Props for the DateTimeField component
+ */
+export interface DateTimeFieldProps {
+  /**
+   * Field label
+   */
+  label: string;
+  /**
+   * UTC date value (ISO string, Date object, or undefined)
+   */
+  value: string | Date | undefined;
+  /**
+   * Change handler that receives UTC value (ISO string or Date object)
+   */
+  onChange: (value: string | Date | undefined) => void;
+  /**
+   * Target timezone for display (default: 'UTC')
+   */
+  timezone?: string;
+  /**
+   * Whether the field is required
+   */
+  required?: boolean;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * If true, onChange returns Date object instead of ISO string
+   */
+  returnAsDate?: boolean;
+  /**
+   * Input id (auto-generated if not provided)
+   */
+  id?: string;
+  /**
+   * Helper text to display below the label
+   */
+  helperText?: string;
+  /**
+   * Error message to display
+   */
+  error?: string;
+}
+
+/**
+ * DateTimeField component
+ * Form input for datetime values with automatic timezone conversion
+ *
+ * @param props - DateTimeField configuration
+ * @returns JSX.Element - The rendered datetime field
+ */
+export function DateTimeField({
+  label,
+  value,
+  onChange,
+  timezone = 'UTC',
+  required = false,
+  className,
+  returnAsDate = false,
+  id,
+  helperText,
+  error
+}: DateTimeFieldProps) {
+  const [isEditing, setIsEditing] = React.useState(false);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const fieldId = id || `datetime-field-${React.useId()}`;
+
+  // Convert UTC value to timezone for display
+  const getDisplayValue = React.useCallback((): string => {
+    if (!value) {
+      return '';
+    }
+
+    try {
+      let dateObj: Date;
+      if (typeof value === 'string') {
+        dateObj = new Date(value);
+      } else {
+        dateObj = value;
+      }
+
+      if (!dateObj || isNaN(dateObj.getTime())) {
+        return '';
+      }
+
+      // Convert UTC to timezone
+      const zonedDate = toZonedTime(dateObj, timezone);
+
+      // Format for datetime-local input (YYYY-MM-DDTHH:mm)
+      return format(zonedDate, "yyyy-MM-dd'T'HH:mm");
+    } catch {
+      return '';
+    }
+  }, [value, timezone]);
+
+  const displayValue = isEditing ? undefined : getDisplayValue();
+
+  // Handle input change
+  const handleChange = React.useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setIsEditing(true);
+    const inputValue = e.target.value;
+
+    if (!inputValue) {
+      onChange(undefined);
+      return;
+    }
+
+    try {
+      // Parse the datetime-local value (in timezone)
+      const localDate = parse(inputValue, "yyyy-MM-dd'T'HH:mm", new Date());
+
+      if (isNaN(localDate.getTime())) {
+        onChange(undefined);
+        return;
+      }
+
+      // Convert from timezone to UTC
+      const utcDate = fromZonedTime(localDate, timezone);
+
+      // Return as ISO string or Date object
+      if (returnAsDate) {
+        onChange(utcDate);
+      } else {
+        onChange(utcDate.toISOString());
+      }
+    } catch {
+      onChange(undefined);
+    }
+  }, [timezone, returnAsDate, onChange]);
+
+  // Handle blur to stop editing mode
+  const handleBlur = React.useCallback(() => {
+    setIsEditing(false);
+  }, []);
+
+  // Get timezone display text
+  const getTimezoneDisplay = React.useCallback((): string => {
+    if (timezone === 'UTC') {
+      return '';
+    }
+
+    const userTz = getUserTimeZone();
+    if (timezone === userTz) {
+      return 'Local';
+    }
+
+    return timezone;
+  }, [timezone]);
+
+  const timezoneDisplay = getTimezoneDisplay();
+
+  return (
+    <div className={cn('space-y-2', className)}>
+      <Label htmlFor={fieldId} required={required} helperText={helperText} error={error}>
+        {label}
+      </Label>
+      <div className="relative">
+        <Input
+          ref={inputRef}
+          id={fieldId}
+          type="datetime-local"
+          value={displayValue}
+          onChange={handleChange}
+          onBlur={handleBlur}
+          required={required}
+          error={!!error}
+          className="w-full"
+        />
+        {timezoneDisplay && (
+          <span className="absolute right-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground pointer-events-none">
+            {timezoneDisplay}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+