@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/date-picker.tsx

@@ -8,82 +8,185 @@ import { Calendar } from "./calendar";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover";
 
 /**
- * Properties for the DatePicker component
+ * Props for DatePicker component (Documentation only - NOT used in component implementation)
  *
- * @type DatePickerProps
- * @since 1.0.0
+ * These types are for documentation generation and should not replace Calendar/Popover inferred types.
+ * Combines date selection functionality with popover positioning and calendar configuration.
+ * All props support both controlled and uncontrolled usage patterns for flexible integration
+ * with forms, state management, and validation systems.
+ *
+ * Extends the base date picker functionality with comprehensive prop documentation.
+ * This component is built on Radix UI Popover and Calendar primitives, inheriting
+ * their accessibility features while providing a simplified, opinionated interface
+ * for common date selection use cases.
+ *
+ * **Inherited Behavior:**
+ * - Popover positioning and collision detection from Radix UI Popover
+ * - Calendar navigation and accessibility from shadcn/ui Calendar
+ * - Button styling and interaction states from shadcn/ui Button
+ * - Portal rendering for proper z-index layering
+ * - Keyboard navigation and ARIA support
+ * - Automatic focus management and restoration
+ *
+ * **Key Features:**
+ * - Controlled and uncontrolled usage patterns
+ * - Automatic date formatting with internationalization
+ * - Form library integration support
+ * - Responsive design with customizable width
+ * - Touch-friendly mobile interface
+ * - High contrast accessibility compliance
  */
-type DatePickerProps = {
+// eslint-disable-next-line unused-imports/no-unused-vars
+type DatePickerDocsProps = {
   /**
-   * The currently selected date value. When undefined, no date is selected.
+   * The currently selected date value
+   *
+   * Controls the date selection state. When undefined, no date is selected and
+   * the placeholder text is displayed. Pass a Date object to show a selected date.
+   * For controlled usage, combine with onDateChange callback.
    *
    * @example
    * ```tsx
+   * // Controlled usage
    * const [selectedDate, setSelectedDate] = useState<Date>();
    * <DatePicker date={selectedDate} onDateChange={setSelectedDate} />
+   *
+   * // Uncontrolled with default
+   * <DatePicker date={new Date()} /> // Shows today
+   *
+   * // No selection
+   * <DatePicker /> // Shows placeholder
    * ```
    */
   date?: Date;
 
   /**
-   * Callback function invoked when the user selects or clears a date.
-   * Receives the selected date or undefined when cleared.
+   * Event handler called when the date selection changes
+   *
+   * Invoked whenever the user selects a new date from the calendar or clears
+   * the current selection. Receives the new date or undefined if cleared.
+   * Essential for controlled usage and form integration.
    *
-   * @param date - The newly selected date or undefined if cleared
+   * @param date - The newly selected date, or undefined if selection was cleared
    *
    * @example
    * ```tsx
-   * <DatePicker onDateChange={(date) => console.log('Selected:', date)} />
+   * // Basic usage with state
+   * <DatePicker onDateChange={(date) => {
+   *   console.log('Selected:', date);
+   *   setFormData(prev => ({ ...prev, selectedDate: date }));
+   * }} />
+   *
+   * // Form integration
+   * <DatePicker onDateChange={(date) => {
+   *   setValue('birthDate', date); // React Hook Form
+   *   validateField('birthDate'); // Validation
+   * }} />
+   *
+   * // Analytics tracking
+   * <DatePicker onDateChange={(date) => {
+   *   if (date) {
+   *     analytics.track('date_selected', { date: date.toISOString() });
+   *   }
+   * }} />
    * ```
    */
   onDateChange?: (date: Date | undefined) => void;
 
   /**
-   * Placeholder text displayed in the trigger button when no date is selected.
-   * Provides context about what kind of date selection is expected.
+   * Placeholder text displayed when no date is selected
+   *
+   * Shows in the trigger button as a prompt to guide users about the expected
+   * date selection. Should be descriptive and context-appropriate to help users
+   * understand what kind of date they should choose.
    *
    * @default "Pick a date"
    *
    * @example
    * ```tsx
+   * // Contextual placeholders
    * <DatePicker placeholder="Select your birthday" />
+   * <DatePicker placeholder="Choose departure date" />
+   * <DatePicker placeholder="Pick appointment time" />
+   * <DatePicker placeholder="Select due date" />
+   *
+   * // With internationalization
+   * <DatePicker placeholder={t('datePicker.placeholder')} />
    * ```
    */
   placeholder?: string;
 
   /**
-   * When true, disables the date picker preventing user interaction.
-   * The trigger button will appear disabled and the popover cannot be opened.
+   * Disables the entire date picker component
+   *
+   * When true, prevents all user interaction including clicking the trigger button,
+   * opening the calendar popover, and keyboard navigation. The component will appear
+   * visually disabled with reduced opacity and appropriate cursor states.
    *
    * @default false
    *
    * @example
    * ```tsx
-   * <DatePicker disabled={true} placeholder="Date locked" />
+   * // Form field disabling
+   * <DatePicker disabled={isSubmitting} placeholder="Loading..." />
+   *
+   * // Conditional disabling based on permissions
+   * <DatePicker disabled={!canEditDates} placeholder="Date locked" />
+   *
+   * // Loading state
+   * <DatePicker disabled={isLoadingData} placeholder="Loading available dates..." />
+   *
+   * // Past date selection disabled
+   * <DatePicker
+   *   disabled={selectedDate && selectedDate < new Date()}
+   *   placeholder="Future dates only"
+   * />
    * ```
    */
   disabled?: boolean;
 
   /**
-   * Additional CSS classes to apply to the trigger button.
-   * Useful for customizing width, spacing, or other styling.
+   * Additional CSS classes for the trigger button
+   *
+   * Applies custom styling to the date picker's trigger button. Commonly used
+   * for width adjustments, spacing, alignment, or integration with form layouts.
+   * Classes are merged with the default button styling.
    *
    * @example
    * ```tsx
+   * // Width customization
    * <DatePicker className="w-full" /> // Full width
    * <DatePicker className="w-[300px]" /> // Fixed width
+   * <DatePicker className="min-w-[200px]" /> // Minimum width
+   *
+   * // Form integration
+   * <DatePicker className="flex-1" /> // Flexible within flex container
+   * <DatePicker className="col-span-2" /> // Grid column spanning
+   *
+   * // Spacing and alignment
+   * <DatePicker className="ml-auto" /> // Right-aligned
+   * <DatePicker className="mx-auto" /> // Center-aligned
+   * <DatePicker className="mb-4" /> // Bottom margin
+   *
+   * // Custom styling
+   * <DatePicker className="border-2 border-blue-500 focus:border-blue-600" />
    * ```
    */
   className?: string;
 };
 
 /**
- * A comprehensive date selection component that combines an accessible button trigger
- * with a full-featured calendar popover for intuitive date picking.
+ * DatePicker - A comprehensive date selection component with popover calendar interface
  *
- * Built on shadcn/ui design principles, this component provides a polished interface
- * for date selection with proper accessibility, keyboard navigation, and visual feedback.
- * The selected date is displayed using date-fns formatting for consistent presentation.
+ * A polished date selection component that combines an accessible trigger button with a
+ * full-featured calendar popover. Built on Radix UI Popover and Calendar primitives with
+ * shadcn/ui styling, providing intuitive date selection with proper accessibility,
+ * keyboard navigation, automatic positioning, and internationalization support.
+ *
+ * The component handles both controlled and uncontrolled usage patterns, integrates
+ * seamlessly with forms and validation systems, and provides consistent date formatting
+ * using date-fns. The popover automatically positions itself to stay within viewport
+ * bounds and includes smooth animations for a polished user experience.
  *
  * @component
  * @example
@@ -133,24 +236,105 @@ type DatePickerProps = {
  * ```
  *
  * @accessibility
- * - **Keyboard Navigation**: Full keyboard support with Tab, Enter, Escape, and arrow keys
- * - **Screen Reader Support**: Proper ARIA labels and live announcements for date changes
- * - **Focus Management**: Focus returns to trigger button when popover closes
- * - **Visual Indicators**: Clear visual states for disabled, selected, and focused elements
- * - **Date Formatting**: Consistent date presentation using localized formatting
+ * - **Keyboard Navigation**:
+ *   - Tab to focus the trigger button
+ *   - Enter/Space to open calendar popover
+ *   - Arrow keys for date navigation within calendar
+ *   - Escape to close popover and return focus to trigger
+ *   - Page Up/Down for month navigation
+ *   - Home/End for week start/end navigation
+ * - **Screen Reader Support**:
+ *   - Proper ARIA labels describing the date picker purpose
+ *   - Live region announcements for date selection changes
+ *   - Calendar grid structure announced correctly
+ *   - Selected date clearly announced with full formatting
+ * - **Focus Management**:
+ *   - Visible focus indicators with 3px ring on trigger button
+ *   - Focus trapped within calendar when popover is open
+ *   - Focus returns to trigger button when popover closes
+ *   - Initial focus on today's date or selected date when opening
+ * - **Visual Indicators**:
+ *   - Clear visual states for disabled, selected, and focused elements
+ *   - High contrast borders and backgrounds meeting WCAG 2.1 AA standards
+ *   - Consistent color coding for different date states
+ *   - Reduced opacity for disabled state with appropriate cursor
+ * - **Date Formatting**:
+ *   - Consistent date presentation using date-fns localized formatting
+ *   - Full date format (e.g., "Wednesday, January 15, 2025") for clarity
+ *   - Placeholder text provides clear guidance about expected input
  *
  * @features
- * - Single date selection with visual confirmation
- * - Popover-based calendar that doesn't interfere with page layout
- * - Automatic popover positioning and collision detection
- * - Internal state management with optional external control
- * - Customizable trigger button styling and width
- * - Date formatting using date-fns for internationalization support
- *
- * @see {@link https://ui.shadcn.com/docs/components/date-picker} shadcn/ui Date Picker patterns
- * @see {@link Calendar} - The underlying calendar component
- * @see {@link Popover} - The popover container component
- * @see {@link Button} - The trigger button component
+ * - **Date Selection**: Single date selection with immediate visual confirmation
+ * - **Popover Interface**: Non-modal calendar popover that doesn't disrupt page layout
+ * - **Smart Positioning**: Automatic positioning with collision detection and boundary awareness
+ * - **State Management**: Flexible controlled/uncontrolled patterns with internal state fallback
+ * - **Customizable Styling**: Full control over trigger button appearance, width, and spacing
+ * - **Internationalization**: Date formatting with date-fns supporting multiple locales
+ * - **Form Integration**: Seamless integration with form libraries and validation systems
+ * - **Performance**: Optimized rendering with minimal re-renders and efficient state updates
+ * - **Animation**: Smooth open/close animations with proper state transitions
+ * - **Mobile Support**: Touch-friendly interface with appropriate sizing and spacing
+ *
+ * @implementation
+ * The DatePicker component is implemented as a composition of:
+ * - **Popover**: Radix UI primitive providing positioning, portal rendering, and focus management
+ * - **PopoverTrigger**: Button element that opens the calendar (uses asChild pattern)
+ * - **PopoverContent**: Container for the calendar with auto-positioning
+ * - **Calendar**: Full-featured calendar component with keyboard navigation
+ * - **Button**: Styled trigger with outline variant and calendar icon
+ *
+ * State is managed internally with React.useState hooks and synchronized with external
+ * props through React.useEffect. The component automatically handles date formatting
+ * using date-fns format function with "PPP" pattern for readable date display.
+ *
+ * @usage-patterns
+ * **Controlled Pattern** (Recommended):
+ * ```tsx
+ * const [date, setDate] = useState<Date>();
+ * <DatePicker date={date} onDateChange={setDate} />
+ * ```
+ *
+ * **Form Library Integration**:
+ * ```tsx
+ * // React Hook Form
+ * <Controller render={({ field }) =>
+ *   <DatePicker date={field.value} onDateChange={field.onChange} />
+ * } />
+ *
+ * // Formik
+ * <Field name="date">
+ *   {({ field, form }) => (
+ *     <DatePicker
+ *       date={field.value}
+ *       onDateChange={(date) => form.setFieldValue('date', date)}
+ *     />
+ *   )}
+ * </Field>
+ * ```
+ *
+ * **Validation Integration**:
+ * ```tsx
+ * const handleDateChange = (date: Date | undefined) => {
+ *   // Validate date before setting
+ *   if (date && isValidDate(date)) {
+ *     setDate(date);
+ *     clearError();
+ *   } else {
+ *     setError('Please select a valid date');
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link Calendar} The underlying calendar component with full date navigation
+ * @see {@link Popover} The popover container component for positioning and portal rendering
+ * @see {@link PopoverTrigger} Trigger element that opens the calendar popover
+ * @see {@link PopoverContent} Content container for the calendar with auto-positioning
+ * @see {@link Button} The styled trigger button with variant support
+ * @see {@link https://ui.shadcn.com/docs/components/date-picker} shadcn/ui Date Picker documentation
+ * @see {@link https://ui.shadcn.com/docs/components/calendar} shadcn/ui Calendar component
+ * @see {@link https://ui.shadcn.com/docs/components/popover} shadcn/ui Popover component
+ * @see {@link https://date-fns.org/docs/format} date-fns formatting documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/popover} Radix UI Popover primitives
  *
  * @since 1.0.0
  */
@@ -160,7 +344,13 @@ function DatePicker({
   placeholder = "Pick a date",
   disabled = false,
   className,
-}: DatePickerProps) {
+}: {
+  date?: Date;
+  onDateChange?: (date: Date | undefined) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+}) {
   // Internal state for uncontrolled usage and popover open/close
   const [internalDate, setInternalDate] = React.useState<Date | undefined>(
     date,