@jmruthers/pace-core 0.5.184 → 0.5.186

package/src/components/DatePickerWithTimezone/DatePickerWithTimezone.tsx

@@ -0,0 +1,126 @@
+/**
+ * @file DatePickerWithTimezone Component
+ * @package @jmruthers/pace-core
+ * @module Components/DatePickerWithTimezone
+ * @since 0.1.0
+ *
+ * Date picker component that displays timezone information alongside the calendar.
+ * Provides a calendar interface with timezone context for date selection.
+ *
+ * Features:
+ * - Calendar date selection
+ * - Timezone display (shows "Local" when matches user timezone)
+ * - Optional "Done" button
+ * - Accessible date selection
+ * - Keyboard navigation support
+ *
+ * @example
+ * ```tsx
+ * import { DatePickerWithTimezone } from '@jmruthers/pace-core/components';
+ * import { useState } from 'react';
+ *
+ * function DateSelector() {
+ *   const [date, setDate] = useState<Date>();
+ *
+ *   return (
+ *     <DatePickerWithTimezone
+ *       selected={date}
+ *       onSelect={setDate}
+ *       timezone="America/New_York"
+ *       onDone={() => console.log('Date selected')}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - WCAG 2.1 AA compliant
+ * - Keyboard navigation support
+ * - Screen reader friendly
+ * - Focus management
+ * - Proper ARIA attributes
+ */
+
+import * as React from 'react';
+import { Calendar } from '../Calendar';
+import { Button } from '../Button';
+import { Clock } from 'lucide-react';
+import { getUserTimeZone } from '../../utils/timezone';
+import { cn } from '../../utils/core/cn';
+
+/**
+ * Props for the DatePickerWithTimezone component
+ */
+export interface DatePickerWithTimezoneProps {
+  /**
+   * Currently selected date
+   */
+  selected?: Date;
+  /**
+   * Date selection handler
+   */
+  onSelect: (date: Date | undefined) => void;
+  /**
+   * Optional callback when "Done" button is clicked
+   */
+  onDone?: () => void;
+  /**
+   * Timezone to display (defaults to user's timezone)
+   */
+  timezone?: string;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+/**
+ * DatePickerWithTimezone component
+ * Date picker with timezone information display
+ *
+ * @param props - DatePickerWithTimezone configuration
+ * @returns JSX.Element - The rendered date picker with timezone
+ */
+export function DatePickerWithTimezone({
+  selected,
+  onSelect,
+  onDone,
+  timezone,
+  className
+}: DatePickerWithTimezoneProps) {
+  const userTimezone = getUserTimeZone();
+  const displayTimezone = timezone || userTimezone;
+  const timezoneDisplay = displayTimezone === userTimezone ? 'Local' : displayTimezone;
+
+  return (
+    <div className={cn('flex flex-col', className)}>
+      <div className="p-3">
+        <Calendar
+          mode="single"
+          selected={selected}
+          onSelect={onSelect}
+          initialFocus
+          captionLayout="dropdown-buttons"
+          fromYear={1900}
+          toYear={2100}
+          className="p-0"
+        />
+      </div>
+
+      <div className="flex items-center justify-between border-t border-border px-3 py-2">
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Clock className="h-4 w-4" aria-hidden="true" />
+          <span>
+            Timezone: <span aria-label={`Timezone ${timezoneDisplay}`}>{timezoneDisplay}</span>
+          </span>
+        </div>
+        {onDone && (
+          <Button onClick={onDone} size="sm" className="h-8">
+            Done
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+

package/src/components/DatePickerWithTimezone/README.md

@@ -0,0 +1,135 @@
+# DatePickerWithTimezone Component
+
+Date picker component that displays timezone information alongside the calendar.
+
+## Overview
+
+The `DatePickerWithTimezone` component provides a calendar interface for date selection with timezone context. It displays the timezone information below the calendar and optionally includes a "Done" button.
+
+## Features
+
+- Calendar date selection
+- Timezone display (shows "Local" when matches user timezone)
+- Optional "Done" button
+- Accessible date selection
+- Keyboard navigation support
+- Integration with pace-core Calendar component
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { DatePickerWithTimezone } from '@jmruthers/pace-core/components';
+import { useState } from 'react';
+
+function DateSelector() {
+  const [date, setDate] = useState<Date>();
+
+  return (
+    <DatePickerWithTimezone
+      selected={date}
+      onSelect={setDate}
+      timezone="America/New_York"
+    />
+  );
+}
+```
+
+### With Done Button
+
+```tsx
+<DatePickerWithTimezone
+  selected={date}
+  onSelect={setDate}
+  timezone="America/New_York"
+  onDone={() => {
+    console.log('Date selected:', date);
+    // Close dialog or perform other actions
+  }}
+/>
+```
+
+### Using User's Timezone
+
+```tsx
+// When timezone is not provided, uses user's browser timezone
+<DatePickerWithTimezone
+  selected={date}
+  onSelect={setDate}
+/>
+```
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selected` | `Date \| undefined` | - | Currently selected date |
+| `onSelect` | `(date: Date \| undefined) => void` | **required** | Date selection handler |
+| `onDone` | `() => void` | - | Optional callback when "Done" button is clicked |
+| `timezone` | `string` | User's timezone | Timezone to display (IANA timezone string) |
+| `className` | `string` | - | Additional CSS classes |
+
+## Behavior
+
+### Timezone Display
+
+- When `timezone` is not provided: Uses the user's browser timezone
+- When `timezone` matches user's timezone: Shows "Local"
+- When `timezone` is different: Shows the timezone name (e.g., "America/New_York")
+
+### Date Selection
+
+The component uses the pace-core `Calendar` component for date selection. Selected dates are passed directly to `onSelect` without timezone conversion (dates are timezone-agnostic).
+
+### Done Button
+
+When `onDone` is provided, a "Done" button appears in the footer. Clicking it calls the `onDone` callback without affecting the selected date.
+
+## Accessibility
+
+- WCAG 2.1 AA compliant
+- Keyboard navigation support (via Calendar component)
+- Screen reader friendly
+- Proper ARIA labels for timezone information
+- Focus management
+
+## Integration
+
+### With Dialog
+
+```tsx
+import { Dialog, DatePickerWithTimezone } from '@jmruthers/pace-core/components';
+
+function DatePickerDialog() {
+  const [date, setDate] = useState<Date>();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogContent>
+        <DatePickerWithTimezone
+          selected={date}
+          onSelect={setDate}
+          onDone={() => setOpen(false)}
+        />
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+## Edge Cases
+
+- **Undefined selected date**: Calendar displays with no date selected
+- **Null selected date**: Treated as undefined
+
+## Dependencies
+
+- `@jmruthers/pace-core/components/Calendar` - Calendar component
+- `@jmruthers/pace-core/components/Button` - Button component
+- `lucide-react` - Clock icon
+- `@jmruthers/pace-core/utils/timezone` - Timezone utilities
+

package/src/components/DatePickerWithTimezone/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @file DatePickerWithTimezone Component Exports
+ * @package @jmruthers/pace-core
+ * @module Components/DatePickerWithTimezone
+ * @since 0.1.0
+ */
+
+export { DatePickerWithTimezone } from './DatePickerWithTimezone';
+export type { DatePickerWithTimezoneProps } from './DatePickerWithTimezone';
+

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);
+    });
+  });
+});
+