# DatePicker & DateTimePicker Components

A comprehensive date and time selection component library built with Svelte, providing flexible date and datetime picking functionality with various display modes and configurations.

## Features

- **DatePicker**: Simple date selection with calendar popup
- **DateTimePicker**: Date and time selection with calendar and time panel
- Multiple visual variants (plain, outlined, filled)
- Keyboard navigation support
- Min/max date restrictions
- Mandatory field support
- Readonly and disabled states
- Display-only mode for read-only presentation
- International date formatting
- Accessible design with ARIA support

## Installation

```bash
npm install @ticatec/uniface-element
```

```typescript
import DatePicker from '@ticatec/uniface-element/DatePicker';
import DateTimePicker from '@ticatec/uniface-element/DateTimePicker';
```

Or if using within the same project:
```typescript
import DatePicker from '$lib/date-picker';
import { DateTimePicker } from '$lib/date-picker';
```

## DatePicker

### Basic Usage

```svelte
<script>
  import DatePicker from '$lib/date-picker';
  
  let selectedDate = null;
</script>

<DatePicker bind:value={selectedDate} placeholder="Select date" />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date \| null` | `null` | Selected date value |
| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Visual style variant |
| `disabled` | `boolean` | `false` | Disables the picker |
| `readonly` | `boolean` | `false` | Makes the picker read-only |
| `compact` | `boolean` | `false` | Compact display mode |
| `mandatory` | `boolean` | `false` | Required field (hides clear button) |
| `style` | `string` | `''` | Custom CSS styles |
| `placeholder` | `string` | `""` | Input placeholder text |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode (Edit/View) |
| `min` | `UniDate` | `null` | Minimum selectable date |
| `max` | `UniDate` | `null` | Maximum selectable date |
| `onchange` | `OnChangeHandler<Date>` | `null` | Change event handler |
| `onfocus` | `() => void` | `null` | Focus event handler |
| `onblur` | `() => void` | `null` | Blur event handler |

### Methods

| Method | Description |
|--------|-------------|
| `setFocus()` | Programmatically focus the picker |

### Examples

#### Basic Date Picker
```svelte
<DatePicker bind:value={enrolmentDate} placeholder="Select enrolment date" />
```

#### Outlined Mandatory Date Picker
```svelte
<DatePicker 
  variant="outlined" 
  mandatory 
  bind:value={birthday} 
  placeholder="Date of birth (required)" 
/>
```

#### Filled Date Picker
```svelte
<DatePicker 
  variant="filled" 
  bind:value={admissionDate} 
  placeholder="Admission date" 
/>
```

#### Date Picker with Min/Max Restrictions
```svelte
<!-- Only allow dates up to today -->
<DatePicker 
  variant="filled" 
  max={new Date()} 
  bind:value={completedDate} 
  placeholder="Completion date" 
/>

<!-- Only allow dates from tomorrow onwards -->
<DatePicker 
  variant="filled" 
  min={new Date()} 
  bind:value={bookFrom} 
  placeholder="Booking start date" 
/>
```

#### Disabled and Readonly States
```svelte
<!-- Disabled -->
<DatePicker variant="filled" disabled bind:value={admissionDate} />

<!-- Readonly -->
<DatePicker variant="filled" readonly bind:value={admissionDate} />

<!-- Display only mode -->
<DatePicker 
  displayMode={DisplayMode.View} 
  variant="filled" 
  readonly 
  bind:value={admissionDate} 
/>
```

## DateTimePicker

### Basic Usage

```svelte
<script>
  import { DateTimePicker } from '$lib/date-picker';
  
  let selectedDateTime = null;
</script>

<DateTimePicker bind:value={selectedDateTime} placeholder="Select date and time" />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UniDate` | `null` | Selected datetime value |
| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Visual style variant |
| `disabled` | `boolean` | `false` | Disables the picker |
| `readonly` | `boolean` | `false` | Makes the picker read-only |
| `compact` | `boolean` | `false` | Compact display mode |
| `mandatory` | `boolean` | `false` | Required field (hides clear button) |
| `style` | `string` | `''` | Custom CSS styles |
| `placeholder` | `string` | `""` | Input placeholder text |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode (Edit/View) |
| `min` | `UniDate` | `null` | Minimum selectable date |
| `max` | `UniDate` | `null` | Maximum selectable date |
| `precision` | `"H" \| "M" \| "S"` | `"M"` | Time precision (Hour/Minute/Second) |
| `onchange` | `OnChangeHandler<Date>` | `null` | Change event handler |
| `onfocus` | `() => void` | `null` | Focus event handler |
| `onblur` | `() => void` | `null` | Blur event handler |

### Methods

| Method | Description |
|--------|-------------|
| `setFocus()` | Programmatically focus the picker |

### Examples

#### Basic DateTime Picker
```svelte
<DateTimePicker bind:value={cutoffTime} placeholder="Select cutoff time" />
```

#### DateTime Picker with Second Precision
```svelte
<DateTimePicker 
  variant="outlined" 
  precision="S" 
  mandatory 
  bind:value={releaseDate} 
  placeholder="Release datetime (to seconds)" 
/>
```

#### DateTime Picker with Hour Precision
```svelte
<DateTimePicker 
  variant="filled" 
  precision="H" 
  bind:value={appointmentTime} 
  placeholder="Appointment time (hour precision)" 
/>
```

## Time Precision

The `precision` prop in DateTimePicker controls the time granularity:

- **"H"**: Hour precision (YYYY-MM-DD HH:00)
- **"M"**: Minute precision (YYYY-MM-DD HH:mm) - Default
- **"S"**: Second precision (YYYY-MM-DD HH:mm:ss)

## Display Modes

Both components support different display modes via the `displayMode` prop:

- **`DisplayMode.Edit`**: Full editing capabilities (default)
- **`DisplayMode.View`**: Read-only display mode

## Variants

Both components support multiple visual styles:

- **Default** (`''`): Basic styling
- **`'plain'`**: Minimal styling
- **`'outlined'`**: Outlined border style
- **`'filled'`**: Filled background style

## Keyboard Navigation

Both components support keyboard navigation:

- **Backspace/Delete**: Clear the selected date/time
- **Escape**: Close the popup
- **Tab**: Navigate through the interface
- **Enter**: Confirm selection (in DateTimePicker)

## Accessibility

- Full ARIA support for screen readers
- Keyboard navigation
- Focus management
- Proper labeling and descriptions

## Date Formats

- **DatePicker**: YYYY-MM-DD
- **DateTimePicker**: 
  - Hour precision: YYYY-MM-DD HH:mm
  - Minute precision: YYYY-MM-DD HH:mm
  - Second precision: YYYY-MM-DD HH:mm:ss

## Event Handling

```svelte
<script>
  function handleDateChange(date) {
    console.log('Date selected:', date);
  }
  
  function handleFocus() {
    console.log('Picker focused');
  }
  
  function handleBlur() {
    console.log('Picker blurred');
  }
</script>

<DatePicker 
  bind:value={selectedDate}
  onchange={handleDateChange}
  onfocus={handleFocus}
  onblur={handleBlur}
/>
```

## Styling

Both components inherit styling from the Uniface design system and can be customized with CSS variables:

```css
.uniface-date-time-editor {
  --uniface-inside-border-color: #f0f0f0;
  /* Add custom styling */
}
```

## Integration with Forms

Both components work seamlessly with FormField:

```svelte
<script>
  import FormField from '$lib/form-field';
  import DatePicker, { DateTimePicker } from '$lib/date-picker';
</script>

<FormField label="Date of Birth">
  <DatePicker variant="outlined" mandatory bind:value={dateOfBirth} />
</FormField>

<FormField label="Appointment Time">
  <DateTimePicker variant="filled" precision="M" bind:value={appointmentTime} />
</FormField>
```

## Type Definitions

```typescript
type UniDate = Date | dayjs.Dayjs | string | null;
type OnChangeHandler<T> = (value: T | null) => void;

enum DisplayMode {
  Edit = 'edit',
  View = 'view'
}
```

## Notes

- The components use Day.js internally for date manipulation
- Values are always returned as native JavaScript Date objects
- The calendar popup automatically closes when a date is selected
- The DateTime picker requires confirmation before applying the selection
- Min/max date restrictions are enforced in the calendar view
- The clear button is hidden when `mandatory` is true