@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/DateTimePicker/ai-documentation.md

@@ -1,400 +0,0 @@
-# DateTimePicker - AI Documentation
-
-> Auto-generated AI agent documentation for DateTimePicker component system
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-
-**Components:** DateTimePicker, DatePicker, DatePickerField, DateTimePickerField
-**Import Path:** `import { DateTimePicker, DatePicker, DatePickerField, DateTimePickerField } from '@pushwoosh/dumb-components'`
-**Files:** Complex nested structure with multiple components, helpers, and styles
-**Type:** Form Component / Date Input Component
-**Description:** Comprehensive date and time picking system with multiple components for different use cases
-
-## TypeScript Interfaces
-
-```typescript
-// Main DateTimePicker
-interface DateTimePickerProps {
-  value: string;
-  userInputDay?: string;
-  onChange: (day: string) => void;
-}
-
-// DatePickerField for form inputs
-interface DatePickerFieldProps {
-  value: string;
-  error?: boolean;
-  allowedPlacements?: Placement[];
-  zIndex?: number;
-  closeOnSelect?: boolean;
-  onChange: (day: string) => void;
-}
-
-// Common types
-type Period = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second';
-
-interface RangeOptions {
-  value: Date;
-  minDate?: Date | string;
-  maxDate?: Date | string;
-}
-```
-
-## Import & Usage
-
-**Import:**
-```typescript
-import { 
-  DateTimePicker, 
-  DatePicker, 
-  DatePickerField, 
-  DateTimePickerField 
-} from '@pushwoosh/dumb-components';
-```
-
-**Basic Usage:**
-```tsx
-function App() {
-  const [dateTime, setDateTime] = useState('');
-
-  return (
-    <DateTimePicker 
-      value={dateTime}
-      onChange={setDateTime}
-    />
-  );
-}
-```
-
-## Component Variants
-
-### 1. DateTimePicker - Full Date and Time Selection
-```tsx
-// Complete date and time picker with hours, minutes, seconds
-<DateTimePicker 
-  value={dateTimeString}
-  onChange={(utcString) => setDateTime(utcString)}
-  userInputDay="2024-12-13"
-/>
-```
-
-### 2. DatePicker - Date Only Selection
-```tsx
-// Date selection without time
-<DatePicker 
-  value={dateString}
-  onChange={(date) => setDate(date)}
-/>
-```
-
-### 3. DatePickerField - Form Input Field
-```tsx
-// Input field that opens date picker on click
-<DatePickerField 
-  value={selectedDate}
-  onChange={setSelectedDate}
-  error={hasValidationError}
-  closeOnSelect={true}
-/>
-```
-
-### 4. DateTimePickerField - Form Input for DateTime
-```tsx
-// Input field for date and time selection
-<DateTimePickerField 
-  value={selectedDateTime}
-  onChange={setSelectedDateTime}
-  zIndex={2000}
-/>
-```
-
-## Advanced Examples
-
-```tsx
-// Form integration with validation
-function DateForm() {
-  const [startDate, setStartDate] = useState('');
-  const [endDate, setEndDate] = useState('');
-  const [errors, setErrors] = useState({});
-
-  const validateDates = () => {
-    const newErrors = {};
-    if (!startDate) newErrors.startDate = true;
-    if (!endDate) newErrors.endDate = true;
-    if (startDate && endDate && new Date(startDate) > new Date(endDate)) {
-      newErrors.dateRange = true;
-    }
-    setErrors(newErrors);
-  };
-
-  return (
-    <form>
-      <div>
-        <label>Start Date:</label>
-        <DatePickerField 
-          value={startDate}
-          onChange={setStartDate}
-          error={errors.startDate}
-          closeOnSelect={true}
-        />
-      </div>
-      
-      <div>
-        <label>End Date:</label>
-        <DatePickerField 
-          value={endDate}
-          onChange={setEndDate}
-          error={errors.endDate || errors.dateRange}
-          closeOnSelect={true}
-        />
-      </div>
-      
-      <Button onClick={validateDates}>Validate</Button>
-    </form>
-  );
-}
-
-// Event scheduling with precise time
-function EventScheduler() {
-  const [eventDateTime, setEventDateTime] = useState('');
-  
-  return (
-    <div>
-      <h3>Schedule Event</h3>
-      <DateTimePicker 
-        value={eventDateTime}
-        onChange={(dateTime) => {
-          setEventDateTime(dateTime);
-          console.log('Event scheduled for:', new Date(dateTime));
-        }}
-      />
-    </div>
-  );
-}
-
-// Date range selector
-function DateRangePicker() {
-  const [startDate, setStartDate] = useState('');
-  const [endDate, setEndDate] = useState('');
-
-  return (
-    <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
-      <DatePickerField 
-        value={startDate}
-        onChange={setStartDate}
-        closeOnSelect={true}
-      />
-      <span>to</span>
-      <DatePickerField 
-        value={endDate}
-        onChange={setEndDate}
-        closeOnSelect={true}
-      />
-    </div>
-  );
-}
-
-// With custom positioning
-<DatePickerField 
-  value={date}
-  onChange={setDate}
-  allowedPlacements={['top-start', 'top-end']}
-  zIndex={9999}
-/>
-
-// DateTime with specific format handling
-function AppointmentBooking() {
-  const [appointmentTime, setAppointmentTime] = useState('');
-  
-  const handleTimeChange = (utcString: string) => {
-    // Convert UTC to local time for display
-    const localDate = new Date(utcString);
-    setAppointmentTime(utcString);
-    
-    // You can format for display
-    const displayTime = localDate.toLocaleString();
-    console.log('Appointment set for:', displayTime);
-  };
-
-  return (
-    <DateTimePicker 
-      value={appointmentTime}
-      onChange={handleTimeChange}
-    />
-  );
-}
-```
-
-## Props Reference
-
-### DateTimePicker
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| value | string | required | Date/time value in UTC string format |
-| onChange | (day: string) => void | required | Callback when date/time changes |
-| userInputDay | string | undefined | Specific day input for user interaction |
-
-### DatePickerField
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| value | string | required | Selected date string |
-| onChange | (day: string) => void | required | Date selection callback |
-| error | boolean | false | Whether field shows error state |
-| closeOnSelect | boolean | false | Whether picker closes after selection |
-| allowedPlacements | Placement[] | bottom/top positions | Floating UI placement options |
-| zIndex | number | 1000 | Z-index for picker overlay |
-
-## Date Format Handling
-
-The components work with UTC strings and provide utilities for formatting:
-
-```tsx
-// Working with different date formats
-function DateUtils() {
-  const [date, setDate] = useState('');
-  
-  const handleDateChange = (utcString: string) => {
-    setDate(utcString);
-    
-    // Convert to different formats as needed
-    const dateObj = new Date(utcString);
-    const localString = dateObj.toLocaleString();
-    const isoString = dateObj.toISOString();
-    const timestamp = dateObj.getTime();
-    
-    console.log({
-      utc: utcString,
-      local: localString,
-      iso: isoString,
-      timestamp
-    });
-  };
-
-  return (
-    <DateTimePicker 
-      value={date}
-      onChange={handleDateChange}
-    />
-  );
-}
-```
-
-## AI Agent Guidelines
-
-### ✅ Recommended Patterns
-- Use `DatePickerField` for form inputs that need date selection
-- Use `DateTimePicker` when precise time is needed
-- Handle UTC strings properly - convert to local time for display
-- Set `closeOnSelect={true}` for better UX in forms
-- Use error states for validation feedback
-- Consider `zIndex` when used in modals or overlays
-
-### ❌ Common Mistakes to Avoid
-- Don't forget to handle UTC vs local time conversion
-- Don't use DateTimePicker when only date is needed (use DatePicker)
-- Avoid missing onChange handlers - components won't work without them
-- Don't ignore error states in forms
-- Avoid hardcoded zIndex values in complex layouts
-
-### Integration Tips
-- Works well with form libraries like react-hook-form
-- Can be combined with validation libraries
-- Good for booking systems, scheduling interfaces
-- Use consistent date formatting across your app
-- Consider timezone handling for global applications
-
-## Common Use Cases
-
-### 1. Event Booking System
-```tsx
-function EventBooking() {
-  const [eventDate, setEventDate] = useState('');
-  const [bookingData, setBookingData] = useState({});
-
-  return (
-    <form>
-      <h3>Book Event</h3>
-      <DateTimePickerField 
-        value={eventDate}
-        onChange={(date) => {
-          setEventDate(date);
-          setBookingData(prev => ({ ...prev, eventDate: date }));
-        }}
-      />
-      {/* Other booking fields */}
-    </form>
-  );
-}
-```
-
-### 2. Date Range Filtering
-```tsx
-function DataFilter() {
-  const [startDate, setStartDate] = useState('');
-  const [endDate, setEndDate] = useState('');
-
-  const applyFilter = () => {
-    // Filter data between dates
-    const filtered = data.filter(item => {
-      const itemDate = new Date(item.date);
-      return itemDate >= new Date(startDate) && itemDate <= new Date(endDate);
-    });
-  };
-
-  return (
-    <div>
-      <DatePickerField value={startDate} onChange={setStartDate} />
-      <DatePickerField value={endDate} onChange={setEndDate} />
-      <Button onClick={applyFilter}>Apply Filter</Button>
-    </div>
-  );
-}
-```
-
-### 3. Scheduling Interface
-```tsx
-function ScheduleManager() {
-  const [schedules, setSchedules] = useState([]);
-
-  const addSchedule = () => {
-    setSchedules(prev => [...prev, { 
-      id: Date.now(), 
-      dateTime: '', 
-      title: '' 
-    }]);
-  };
-
-  return (
-    <div>
-      {schedules.map(schedule => (
-        <div key={schedule.id}>
-          <input 
-            placeholder="Event title"
-            onChange={(e) => updateSchedule(schedule.id, 'title', e.target.value)}
-          />
-          <DateTimePicker 
-            value={schedule.dateTime}
-            onChange={(date) => updateSchedule(schedule.id, 'dateTime', date)}
-          />
-        </div>
-      ))}
-      <Button onClick={addSchedule}>Add Schedule</Button>
-    </div>
-  );
-}
-```
-
-## Accessibility Features
-- **Keyboard Navigation**: Full keyboard support for date selection
-- **Screen Reader Support**: Proper ARIA labels and announcements
-- **Focus Management**: Logical tab order and focus handling
-- **High Contrast**: Works with high contrast themes
-
-## Related Components
-- Input - for simple date text input
-- Button - for picker actions
-- Modal - often contains date pickers
-- Popover - similar floating behavior
-
----