maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-date-picker.md

@@ -0,0 +1,791 @@
+---
+title: "MazDatePicker"
+description: "A powerful and flexible date picker component with support for single dates, date ranges, time selection, and extensive customization options"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-date-picker"
+---
+
+# MazDatePicker
+
+> A powerful and flexible date picker component with support for single dates, date ranges, time selection, and extensive customization options
+
+- Package: `maz-ui`
+- Import: `import MazDatePicker from 'maz-ui/components/MazDatePicker'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-date-picker
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Tip:**
+
+This component can be translated globally using the [MazUi](../ecosystem/translations.md) plugin.
+
+## Table of Contents
+
+- Basic Usage
+- Date Formats
+- Date Selection
+- Custom Trigger
+- Time Selection
+- Range Selection
+- Internationalization
+- Validation & Constraints
+- Types
+- Props
+- Events
+- Slots
+
+## Basic Usage
+
+The simplest way to use MazDatePicker:
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="date"
+    label="Select a date"
+    placeholder="Choose your date"
+    format="YYYY-MM-DD"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date = ref()
+</script>
+```
+
+## Date Formats
+
+Understanding date formats is crucial for using MazDatePicker effectively. The component uses two different format concepts:
+
+### 1. Data Format (`format` prop)
+
+This controls how dates are stored and transmitted in your `v-model`. Default is `'YYYY-MM-DD'`.
+
+### 2. Display Format (`input-date-format` prop)
+
+This controls how dates appear in the input field using `Intl.DateTimeFormatOptions`.
+
+```vue
+<template>
+  <!-- ISO Format (recommended) -->
+  <MazDatePicker
+    v-model="date1"
+    label="ISO Format (YYYY-MM-DD)"
+    format="YYYY-MM-DD"
+    :input-date-format="{ dateStyle: 'medium' }"
+  />
+
+  <!-- US Format -->
+  <MazDatePicker
+    v-model="date2"
+    label="US Format (MM/DD/YYYY)"
+    format="MM/DD/YYYY"
+    :input-date-format="{ dateStyle: 'short' }"
+  />
+
+  <!-- European Format -->
+  <MazDatePicker
+    v-model="date3"
+    label="European Format (DD-MM-YYYY)"
+    format="DD-MM-YYYY"
+    :input-date-format="{ dateStyle: 'medium' }"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date1 = ref('2024-03-15')        // ISO format
+const date2 = ref('03/15/2024')        // US format
+const date3 = ref('15-03-2024')        // European format
+</script>
+```
+
+### Custom Display Transformation
+
+Use `inputDateTransformer` to completely customize how dates appear in the input:
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="date"
+    label="Custom Display Format"
+    :input-date-transformer="transformDate"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import dayjs from 'dayjs'
+
+const date = ref()
+
+const transformDate = ({ value }) => {
+  return value ? `📅 ${dayjs(value).format('dddd, MMMM Do YYYY')}` : ''
+}
+</script>
+```
+
+## Date Selection
+
+### Standard Date Picker
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="date"
+    label="Select Date"
+    color="primary"
+    auto-close
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date = ref()
+</script>
+```
+
+### Inline Date Picker
+
+Perfect for dashboards or when you want the calendar always visible:
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="date"
+    inline
+    color="secondary"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date = ref()
+</script>
+```
+
+### Double Calendar
+
+Show two months at once for better date selection:
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="date"
+    label="Double Calendar"
+    double
+    color="success"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date = ref()
+</script>
+```
+
+## Custom Trigger
+
+By default MazDatePicker renders a readonly `MazInput` as the field that opens the calendar. Use the `#trigger` slot to replace it with your own element - a button, a custom input, an icon... Clicking the slotted element opens the calendar automatically (no `@click` needed), and the slot exposes the current open state plus functions for programmatic control.
+
+### Slot bindings
+
+| Binding | Type | Description |
+| --- | --- | --- |
+| `is-open` | `boolean` | Whether the calendar is currently open |
+| `open` | `() => void` | Open the calendar programmatically |
+| `close` | `() => void` | Close the calendar programmatically |
+| `toggle` | `() => void` | Toggle the calendar programmatically |
+
+```vue
+<template>
+  <MazDatePicker v-model="date" auto-close>
+    <!-- Clicking the button opens the picker automatically. -->
+    <template #trigger="{ isOpen }">
+      <MazBtn color="secondary" :class="{ 'ring-2 ring-secondary': isOpen }">
+        {{ date || 'Pick a date' }}
+      </MazBtn>
+    </template>
+  </MazDatePicker>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date = ref()
+</script>
+```
+
+**Tip:**
+
+The model value is not passed through the slot - use your own `v-model` ref (here `date`) to display the selected value in your custom trigger. The exposed `open` / `close` / `toggle` functions are only needed when you want to drive the picker from your own logic.
+
+> In `inline` mode the calendar is always visible, so the `trigger` slot is not rendered. To open the picker from an element rendered outside the component, use the `custom-element-selector` prop instead.
+
+## Time Selection
+
+### Date + Time (24h format)
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="dateTime"
+    label="Date & Time (24h)"
+    format="YYYY-MM-DD HH:mm"
+    time
+    color="info"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const dateTime = ref()
+</script>
+```
+
+### Date + Time (12h format)
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="dateTime"
+    label="Date & Time (12h)"
+    format="YYYY-MM-DD hh:mm a"
+    time
+    color="warning"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const dateTime = ref()
+</script>
+```
+
+### Time Only Selection
+
+```vue
+<template>
+  <!-- 24h format -->
+  <MazDatePicker
+    v-model="time24"
+    label="Time Only (24h)"
+    format="HH:mm"
+    only-time
+    color="accent"
+  />
+
+  <!-- 12h format -->
+  <MazDatePicker
+    v-model="time12"
+    label="Time Only (12h)"
+    format="hh:mm a"
+    only-time
+    color="destructive"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const time24 = ref('14:30')
+const time12 = ref('02:30 pm')
+</script>
+```
+
+### Custom Minute Intervals
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="time1"
+    label="5min intervals"
+    format="HH:mm"
+    :minute-interval="5"
+    only-time
+  />
+
+  <MazDatePicker
+    v-model="time2"
+    label="15min intervals"
+    format="HH:mm"
+    :minute-interval="15"
+    only-time
+  />
+
+  <MazDatePicker
+    v-model="time3"
+    label="30min intervals"
+    format="HH:mm"
+    :minute-interval="30"
+    only-time
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const time1 = ref()
+const time2 = ref()
+const time3 = ref()
+</script>
+```
+
+## Range Selection
+
+For selecting date ranges, pass an object with `start` and `end` properties:
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="range"
+    label="Select Date Range"
+    range
+    double
+    auto-close
+    color="primary"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const range = ref({
+  start: undefined,
+  end: undefined
+})
+</script>
+```
+
+### Range with Shortcuts
+
+Provide predefined shortcuts for common date ranges:
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="range"
+    label="Range with Shortcuts"
+    range
+    double
+    :shortcuts="shortcuts"
+    color="secondary"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import dayjs from 'dayjs'
+
+const range = ref({
+  start: undefined,
+  end: undefined
+})
+
+const shortcuts = [
+  {
+    label: 'Today',
+    identifier: 'today',
+    value: {
+      start: dayjs().format('YYYY-MM-DD'),
+      end: dayjs().format('YYYY-MM-DD')
+    }
+  },
+  {
+    label: 'Last 7 days',
+    identifier: 'last7days',
+    value: {
+      start: dayjs().subtract(6, 'day').format('YYYY-MM-DD'),
+      end: dayjs().format('YYYY-MM-DD')
+    }
+  },
+  {
+    label: 'This month',
+    identifier: 'thisMonth',
+    value: {
+      start: dayjs().startOf('month').format('YYYY-MM-DD'),
+      end: dayjs().endOf('month').format('YYYY-MM-DD')
+    }
+  }
+]
+</script>
+```
+
+### Property `shortcuts`
+
+#### Model
+
+```ts
+interface MazDatePickerShortcut {
+  identifier: string // should be uniq
+  label: string
+  value: {
+    start: string
+    end: string
+  }
+}
+
+type MazDatePickerShortcuts = MazDatePickerShortcut[]
+```
+
+#### Example
+
+```ts
+import type { MazDatePickerShortcut } from 'maz-ui/components'
+
+const shortcuts: MazDatePickerShortcut[] = [{
+  label: 'Next month',
+  identifier: 'nextMonth',
+  value: {
+    start: dayjs().add(1, 'month').set('date', 1).format('YYYY-MM-DD'),
+    end: dayjs()
+      .add(1, 'month')
+      .set('date', dayjs().add(1, 'month').daysInMonth())
+      .format('YYYY-MM-DD'),
+  },
+}]
+```
+
+**Details: View default shortcuts**
+
+```ts
+const shortcuts = [
+  {
+    label: 'Last 7 days',
+    identifier: 'last7Days',
+    value: {
+      start: dayjs().subtract(6, 'day').format('YYYY-MM-DD'),
+      end: dayjs().format('YYYY-MM-DD'),
+    },
+  },
+  {
+    label: 'Last 30 days',
+    identifier: 'last30Days',
+    value: {
+      start: dayjs().subtract(29, 'day').format('YYYY-MM-DD'),
+      end: dayjs().format('YYYY-MM-DD'),
+    },
+  },
+  {
+    label: 'This week',
+    identifier: 'thisWeek',
+    value: {
+      start: dayjs().startOf('week').format('YYYY-MM-DD'),
+      end: dayjs().endOf('week').format('YYYY-MM-DD'),
+    },
+  },
+  {
+    label: 'Last week',
+    identifier: 'lastWeek',
+    value: {
+      start: dayjs()
+        .subtract(1, 'week')
+        .startOf('week')
+        .format('YYYY-MM-DD'),
+      end: dayjs().subtract(1, 'week').endOf('week').format('YYYY-MM-DD'),
+    },
+  },
+  {
+    label: 'This month',
+    identifier: 'thisMonth',
+    value: {
+      start: dayjs().set('date', 1).format('YYYY-MM-DD'),
+      end: dayjs()
+        .set('date', dayjs().daysInMonth())
+        .format('YYYY-MM-DD'),
+    },
+  },
+  {
+    label: 'This year',
+    identifier: 'thisYear',
+    value: {
+      start: dayjs().startOf('year').format('YYYY-MM-DD'),
+      end: dayjs().endOf('year').format('YYYY-MM-DD'),
+    },
+  },
+  {
+    label: 'Last year',
+    identifier: 'lastYear',
+    value: {
+      start: dayjs()
+        .subtract(1, 'year')
+        .startOf('year')
+        .format('YYYY-MM-DD'),
+      end: dayjs().subtract(1, 'year').endOf('year').format('YYYY-MM-DD'),
+    },
+  },
+]
+```
+
+## Validation & Constraints
+
+### Min/Max Dates
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="date"
+    label="Limited Date Range"
+    :min-date="minDate"
+    :max-date="maxDate"
+    color="info"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import dayjs from 'dayjs'
+
+const date = ref()
+const minDate = dayjs().subtract(30, 'day').format('YYYY-MM-DD')
+const maxDate = dayjs().add(30, 'day').format('YYYY-MM-DD')
+</script>
+```
+
+#### Property `min-max-auto`
+
+Disable min-max auto check to not change the value when it is out of range
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="date"
+    label="Not auto date range"
+    :min-date="minDate"
+    :max-date="maxDate"
+    :min-max-auto="false"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import dayjs from 'dayjs'
+
+const date = ref()
+const minDate = dayjs().subtract(30, 'day').format('YYYY-MM-DD')
+const maxDate = dayjs().add(30, 'day').format('YYYY-MM-DD')
+</script>
+```
+
+### Disabled Days & Dates
+
+```vue
+<template>
+  <!-- Disable weekends -->
+  <MazDatePicker
+    v-model="date1"
+    label="Weekends Disabled"
+    :disabled-weekly="[0, 6]"
+    color="warning"
+  />
+
+  <!-- Disable specific dates -->
+  <MazDatePicker
+    v-model="date2"
+    label="Holidays Disabled"
+    :disabled-dates="holidays"
+    color="destructive"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date1 = ref()
+const date2 = ref()
+
+// 0 = Sunday, 6 = Saturday
+const weekends = [0, 6]
+
+// Specific holiday dates
+const holidays = [
+  dayjs().subtract(2, 'day').format('YYYY-MM-DD'),
+  dayjs().subtract(1, 'day').format('YYYY-MM-DD'),
+  dayjs().format('YYYY-MM-DD'),
+  dayjs().add(1, 'day').format('YYYY-MM-DD'),
+  dayjs().add(2, 'day').format('YYYY-MM-DD'),
+  dayjs().add(3, 'day').format('YYYY-MM-DD'),
+  dayjs().add(4, 'day').format('YYYY-MM-DD'),
+]
+</script>
+```
+
+### Disabled Hours
+
+```vue
+<template>
+  <MazDatePicker
+    v-model="dateTime"
+    format="YYYY-MM-DD hh:mm a"
+    time
+    label="Disabled Hours"
+    :disabled-hours="disabledHours"
+    color="info"
+  />
+
+  <MazDatePicker
+    v-model="time"
+    format="HH:mm"
+    only-time
+    label="Disabled Hours"
+    :disabled-hours="disabledHours"
+    color="info"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date = ref()
+const time = ref()
+
+const disabledHours = [0, 1, 2, 11, 22, 23]
+</script>
+```
+
+## Internationalization
+
+MazDatePicker supports full internationalization. **By default, it uses the locale from the [MazUiTranslations](../ecosystem/translations.md) plugin**, but you can override it:
+
+```vue
+<template>
+  <!-- French -->
+  <MazDatePicker
+    v-model="frenchDate"
+    label="French Locale"
+    locale="fr-FR"
+    :first-day-of-week="1"
+    color="primary"
+  />
+
+  <!-- German -->
+  <MazDatePicker
+    v-model="germanDate"
+    label="German Locale"
+    locale="de-DE"
+    :first-day-of-week="1"
+    color="secondary"
+  />
+
+  <!-- Japanese -->
+  <MazDatePicker
+    v-model="japaneseDate"
+    label="Japanese Locale"
+    locale="ja-JP"
+    color="accent"
+  />
+
+  <!-- Arabic -->
+  <MazDatePicker
+    v-model="arabicDate"
+    label="Arabic Locale"
+    locale="ar-SA"
+    :first-day-of-week="6"
+    color="warning"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const frenchDate = ref()
+const germanDate = ref()
+const japaneseDate = ref()
+const arabicDate = ref()
+</script>
+```
+
+## Types
+
+```typescript
+// Value types
+type MazDatePickerValue = string | undefined | MazDatePickerPartialRangeValue
+
+interface MazDatePickerRangeValue {
+  start: string
+  end: string
+}
+
+type MazDatePickerPartialRangeValue = Partial<MazDatePickerRangeValue>
+
+// Shortcut type
+interface MazDatePickerShortcut {
+  identifier: string
+  label: string
+  value: {
+    start: string
+    end: string
+  }
+}
+```
+
+## Accessibility
+
+- The input is a `combobox` opening a `dialog` (`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`).
+- Each month is a `grid` labelled by the month and the year, the days of the week are its column headers and each day has its full date as label (`aria-current="date"` for today, `aria-selected` on the selected days).
+- **Keyboard** in the calendar: only one day is in the tab sequence, the arrows move by day (← →) and by week (↑ ↓), Home / End go to the start / end of the week, Page Up / Page Down to the previous / next month (with Shift: year). Disabled days are skipped and the calendar follows the focus to the displayed month.
+- The navigation buttons labels come from `@maz-ui/translations` (`aria` namespace).
+
+## MazDatePicker API
+
+`import MazDatePicker from 'maz-ui/components/MazDatePicker'`
+
+### Props
+
+- `id` (`string`): The unique identifier of the component.
+- `input-props` (`MazInputProps<MazInputValue>`): The props to apply to the input component.
+- `model-value` (`MazDatePickerValue`, `v-model`): The value of the date picker component If an object is provided, the picker will be a range picker.
+- `format` (`string`, default: `"YYYY-MM-DD"`): The format pattern for date display and parsing.
+- `open` (`boolean`, default: `false`, `v-model:open`): Controls whether the picker window is open.
+- `label` (`string`): The label text displayed above the input field.
+- `placeholder` (`string`): The placeholder text shown when no value is selected.
+- `input-date-format` (`Intl.DateTimeFormatOptions`, default: `{ dateStyle: "medium", timeStyle: "short" }`): The Intl.DateTimeFormatOptions for styling the input date display.
+- `input-date-transformer` (`((payload: { formattedDate?: string | undefined; value?: MazDatePickerValue; locale: string; }) => string)`): Custom function to transform the formatted date display.
+- `locale` (`string`, default: `""`, `v-model:locale`): The locale string for date formatting and localization.
+- `hide-header` (`boolean`, default: `false`): Controls whether the calendar header is hidden.
+- `disabled` (`boolean`, default: `false`): Controls whether the component is disabled.
+- `first-day-of-week` (`0 | 1 | 2 | 3 | 4 | 5 | 6`, default: `0`): The first day of the week in the calendar. Values: `'0'`, `'1'`, `'2'`, `'3'`, `'4'`, `'5'`, `'6'` (non exhaustive).
+- `auto-close` (`boolean`, default: `false`): Controls whether the picker closes automatically after date selection.
+- `custom-element-selector` (`string`): CSS selector for a custom element that triggers the picker.
+- `double` (`boolean`, default: `false`): Controls whether the picker displays two months side by side.
+- `inline` (`boolean`, default: `false`): Controls whether the picker is displayed inline without input field.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color theme of the component.
+- `picker-position` (`MazPopoverPosition`, default: `"auto"`): The position where the picker popover should appear. Values: `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-end'`, `'bottom-end'`, `'left-end'`, `'right-end'`, `'top-start'`, `'bottom-start'`, `'left-start'`, `'right-start'` (non exhaustive).
+- `picker-prefer-position` (`MazPopoverPreferPosition`, default: `"bottom-start"`): The preferred position of the picker popover. Values: `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-end'`, `'bottom-end'`, `'left-end'`, `'right-end'`, `'top-start'`, `'bottom-start'`, `'left-start'`, `'right-start'` (non exhaustive).
+- `picker-fallback-position` (`MazPopoverFallbackPosition`, default: `"top-start"`): The fallback position of the picker popover. Values: `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-end'`, `'bottom-end'`, `'left-end'`, `'right-end'`, `'top-start'`, `'bottom-start'`, `'left-start'`, `'right-start'` (non exhaustive).
+- `time` (`boolean`, default: `false`): Controls whether the picker includes a time selector.
+- `only-time` (`boolean`, default: `false`): Controls whether the picker shows only time selection (no date).
+- `minute-interval` (`number`, default: `5`): The interval in minutes for the time picker minute selection. Values: `'1'`, `'5'`, `'10'`, `'15'`, `'30'` (non exhaustive).
+- `use-browser-locale` (`boolean`, default: `true`): Controls whether to automatically detect and use the browser's locale.
+- `fetch-local` (`boolean`, default: `true`): Controls whether to fetch locale data dynamically.
+- `shortcuts` (`boolean | MazDatePickerShortcut[]`, default: `true`): Array of predefined date range shortcuts or false to disable.
+- `shortcut` (`string`): The identifier of the currently selected shortcut.
+- `min-date` (`string`): The minimum selectable date in ISO format.
+- `max-date` (`string`): The maximum selectable date in ISO format.
+- `min-max-auto` (`boolean`, default: `true`): When minDate or maxDate are provided, if the current date is not between minDate and maxDate, the current date will be set to the minDate or maxDate.
+- `disabled-weekly` (`number[]`, default: `[]`): Array of weekday numbers to disable (0 = Sunday, 6 = Saturday).
+- `disabled-dates` (`string[]`, default: `[]`): Array of specific dates to disable in ISO format.
+- `disabled-hours` (`number[]`, default: `[]`): Array of hour numbers to disable in the time picker (0-23).
+- `block` (`boolean`, default: `false`): Controls whether the input displays in full width.
+- `range` (`boolean`, default: `false`): Controls whether the picker operates in range selection mode.
+- `transition` (`string`, default: `"scale-fade"`): The transition name of the popover.
+
+### Events
+
+- `@update:model-value` (payload: `value: MazDatePickerValue`): Emitted when the picker value changes
+- `@close` (payload: `(void | undefined)?`): Emitted when the picker closes
+- `@update:locale` (payload: `value: string`)
+- `@update:open` (payload: `value: boolean`)
+
+### Slots
+
+- `#trigger`: Replace the default input with your own element Bindings: `isOpen: boolean` (Current open state of the popover), `close: () => void` (Function to close the popover), `open: () => void` (Function to open the popover), `toggle: () => void` (Function to toggle the popover).