@umbra.ui/core 0.1.0

package/src/components/pickers/DatePicker/README.md

@@ -0,0 +1,1195 @@
+# DatePicker
+
+A comprehensive date picker component built with Vue 3 Composition API and TypeScript. The DatePicker provides an intuitive interface for selecting dates with support for both compact and full calendar views, smart positioning using Floating UI, and smooth scrolling through months.
+
+## Installation/Import
+
+```typescript
+import { DatePicker } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @floating-ui/vue (for positioning)
+- @umbra-ui/icons (for calendar and chevron icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { DatePicker } from "@umbra-ui/core";
+
+const selectedDate = ref(new Date());
+
+const handleDateChange = (date: Date) => {
+  console.log("Selected date:", date);
+  console.log("Formatted date:", date.toLocaleDateString());
+};
+</script>
+
+<template>
+  <div class="app">
+    <h2>Select a Date</h2>
+
+    <DatePicker v-model:date="selectedDate" @update:date="handleDateChange" />
+
+    <div v-if="selectedDate" class="date-info">
+      <p>Selected: {{ selectedDate.toLocaleDateString() }}</p>
+      <p>ISO String: {{ selectedDate.toISOString() }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.app {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.date-info {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f8f9fa;
+  border-radius: 8px;
+}
+
+.date-info p {
+  margin: 0 0 8px 0;
+  color: #495057;
+}
+
+.date-info p:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+## Props
+
+| Prop Name | Type   | Required | Default      | Description             |
+| --------- | ------ | -------- | ------------ | ----------------------- |
+| `date`    | `Date` | Yes      | `new Date()` | Currently selected date |
+
+## Events
+
+| Event Name    | Payload Type | Description                     |
+| ------------- | ------------ | ------------------------------- |
+| `update:date` | `Date`       | Emitted when a date is selected |
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.date-picker {
+  --picker-button-bg: #ffffff;
+  --picker-button-border: 1px solid #e9ecef;
+  --picker-button-hover-bg: #f8f9fa;
+  --picker-button-hover-border: 1px solid #dee2e6;
+  --picker-button-hover-shadow: rgba(0, 0, 0, 0.1);
+  --picker-button-hover-inset-shadow: rgba(255, 255, 255, 0.1);
+  --picker-button-selected-bg: #e3f2fd;
+  --picker-picker-bg: #ffffff;
+  --picker-picker-border: 1px solid #e9ecef;
+  --picker-picker-shadow: rgba(0, 0, 0, 0.1);
+  --picker-picker-inset-shadow: rgba(255, 255, 255, 0.1);
+  --picker-bg-subtle: #f8f9fa;
+  --picker-border-light: #e9ecef;
+  --picker-text-primary: #212529;
+  --picker-text-secondary: #6c757d;
+  --picker-bg-hover: #f8f9fa;
+  --picker-overlay-bg: rgba(0, 0, 0, 0.1);
+  --datepicker-weekdays-opacity: 0.5;
+  --datepicker-day-selected-bg: #acd8fc;
+  --datepicker-day-selected-border: #5eb1ef;
+}
+```
+
+### Container Styling
+
+```css
+.date-picker {
+  display: flex;
+  flex-direction: column;
+  gap: 0.235rem;
+  align-items: start;
+}
+```
+
+### Button Styling
+
+```css
+.date-picker .button {
+  padding: 0.588rem;
+  border-radius: 0.353rem;
+  cursor: default;
+  user-select: none;
+  display: flex;
+  align-items: center;
+  gap: 0.588rem;
+  transition: all 0.3s ease;
+  background-color: var(--picker-button-bg);
+  border: var(--picker-button-border);
+}
+```
+
+### Calendar Styling
+
+```css
+.date-picker .picker {
+  position: absolute;
+  background-color: var(--picker-picker-bg);
+  border-radius: 0.353rem;
+  overflow: hidden;
+  box-shadow: var(--picker-picker-shadow);
+  border: var(--picker-picker-border);
+  z-index: 1000;
+}
+
+.date-picker .days {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  gap: 0;
+  align-items: center;
+  max-height: 32rem;
+  overflow: auto;
+  color: var(--picker-text-primary);
+}
+```
+
+## Examples
+
+### Event Date Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { DatePicker } from "@umbra-ui/core";
+
+const eventDate = ref(new Date());
+const eventTitle = ref("");
+
+const handleDateChange = (date: Date) => {
+  console.log("Event date changed to:", date);
+};
+
+const isDateInPast = (date: Date) => {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  return date < today;
+};
+</script>
+
+<template>
+  <div class="event-planner">
+    <div class="planner-header">
+      <h3>Event Planner</h3>
+      <p>Schedule your next event</p>
+    </div>
+
+    <div class="form-section">
+      <label class="form-label">Event Title</label>
+      <input
+        v-model="eventTitle"
+        type="text"
+        placeholder="Enter event title..."
+        class="form-input"
+      />
+    </div>
+
+    <div class="form-section">
+      <label class="form-label">Event Date</label>
+      <DatePicker v-model:date="eventDate" @update:date="handleDateChange" />
+
+      <div v-if="isDateInPast(eventDate)" class="warning">
+        ⚠️ This date is in the past
+      </div>
+    </div>
+
+    <div class="event-preview">
+      <h4>Event Preview</h4>
+      <div class="preview-card">
+        <h5>{{ eventTitle || "Untitled Event" }}</h5>
+        <p>
+          {{
+            eventDate.toLocaleDateString("en-US", {
+              weekday: "long",
+              year: "numeric",
+              month: "long",
+              day: "numeric",
+            })
+          }}
+        </p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.event-planner {
+  padding: 24px;
+  max-width: 500px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.planner-header {
+  margin-bottom: 32px;
+}
+
+.planner-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.planner-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.form-section {
+  margin-bottom: 24px;
+}
+
+.form-label {
+  display: block;
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  margin-bottom: 8px;
+}
+
+.form-input {
+  width: 100%;
+  padding: 12px;
+  border: 1px solid #d1d5db;
+  border-radius: 6px;
+  font-size: 14px;
+  transition: border-color 0.2s ease;
+}
+
+.form-input:focus {
+  outline: none;
+  border-color: #3b82f6;
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+}
+
+.warning {
+  margin-top: 8px;
+  padding: 8px 12px;
+  background: #fef3c7;
+  color: #92400e;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.event-preview {
+  margin-top: 32px;
+}
+
+.event-preview h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-card {
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+  border-left: 4px solid #3b82f6;
+}
+
+.preview-card h5 {
+  font-size: 16px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 8px 0;
+}
+
+.preview-card p {
+  color: #4a5568;
+  margin: 0;
+}
+</style>
+```
+
+### Appointment Scheduler
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { DatePicker } from "@umbra-ui/core";
+
+const appointmentDate = ref(new Date());
+const appointmentTime = ref("09:00");
+const appointmentType = ref("consultation");
+
+const availableTimes = [
+  "09:00",
+  "09:30",
+  "10:00",
+  "10:30",
+  "11:00",
+  "11:30",
+  "14:00",
+  "14:30",
+  "15:00",
+  "15:30",
+  "16:00",
+  "16:30",
+];
+
+const isWeekend = computed(() => {
+  const day = appointmentDate.value.getDay();
+  return day === 0 || day === 6; // Sunday or Saturday
+});
+
+const isDateInPast = computed(() => {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  return appointmentDate.value < today;
+});
+
+const canSchedule = computed(() => {
+  return !isWeekend.value && !isDateInPast.value && appointmentTime.value;
+});
+
+const handleDateChange = (date: Date) => {
+  console.log("Appointment date changed to:", date);
+};
+</script>
+
+<template>
+  <div class="appointment-scheduler">
+    <div class="scheduler-header">
+      <h3>Schedule Appointment</h3>
+      <p>Book your appointment with us</p>
+    </div>
+
+    <div class="form-section">
+      <label class="form-label">Appointment Type</label>
+      <select v-model="appointmentType" class="form-select">
+        <option value="consultation">Consultation</option>
+        <option value="follow-up">Follow-up</option>
+        <option value="checkup">Checkup</option>
+        <option value="emergency">Emergency</option>
+      </select>
+    </div>
+
+    <div class="form-section">
+      <label class="form-label">Date</label>
+      <DatePicker
+        v-model:date="appointmentDate"
+        @update:date="handleDateChange"
+      />
+
+      <div v-if="isWeekend" class="error">
+        ❌ We don't schedule appointments on weekends
+      </div>
+      <div v-else-if="isDateInPast" class="error">
+        ❌ Cannot schedule appointments in the past
+      </div>
+    </div>
+
+    <div class="form-section">
+      <label class="form-label">Time</label>
+      <div class="time-grid">
+        <button
+          v-for="time in availableTimes"
+          :key="time"
+          :class="['time-btn', { active: appointmentTime === time }]"
+          @click="appointmentTime = time"
+        >
+          {{ time }}
+        </button>
+      </div>
+    </div>
+
+    <div class="appointment-summary">
+      <h4>Appointment Summary</h4>
+      <div class="summary-card">
+        <div class="summary-item">
+          <span class="label">Type:</span>
+          <span class="value">{{ appointmentType }}</span>
+        </div>
+        <div class="summary-item">
+          <span class="label">Date:</span>
+          <span class="value">{{ appointmentDate.toLocaleDateString() }}</span>
+        </div>
+        <div class="summary-item">
+          <span class="label">Time:</span>
+          <span class="value">{{ appointmentTime }}</span>
+        </div>
+      </div>
+
+      <button :disabled="!canSchedule" class="schedule-btn">
+        {{ canSchedule ? "Schedule Appointment" : "Select Valid Date & Time" }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.appointment-scheduler {
+  padding: 24px;
+  max-width: 600px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.scheduler-header {
+  margin-bottom: 32px;
+}
+
+.scheduler-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.scheduler-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.form-section {
+  margin-bottom: 24px;
+}
+
+.form-label {
+  display: block;
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  margin-bottom: 8px;
+}
+
+.form-select {
+  width: 100%;
+  padding: 12px;
+  border: 1px solid #d1d5db;
+  border-radius: 6px;
+  font-size: 14px;
+  background: white;
+  cursor: pointer;
+}
+
+.error {
+  margin-top: 8px;
+  padding: 8px 12px;
+  background: #fee2e2;
+  color: #dc2626;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.time-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(80px, 1fr));
+  gap: 8px;
+}
+
+.time-btn {
+  padding: 8px 12px;
+  border: 1px solid #d1d5db;
+  border-radius: 6px;
+  background: white;
+  color: #374151;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.time-btn:hover {
+  border-color: #3b82f6;
+  background: #f0f9ff;
+}
+
+.time-btn.active {
+  background: #3b82f6;
+  color: white;
+  border-color: #3b82f6;
+}
+
+.appointment-summary {
+  margin-top: 32px;
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.appointment-summary h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.summary-card {
+  background: #f7fafc;
+  border-radius: 8px;
+  padding: 16px;
+  margin-bottom: 16px;
+}
+
+.summary-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 8px;
+}
+
+.summary-item:last-child {
+  margin-bottom: 0;
+}
+
+.label {
+  font-weight: 500;
+  color: #4a5568;
+}
+
+.value {
+  color: #2d3748;
+  font-weight: 600;
+}
+
+.schedule-btn {
+  width: 100%;
+  padding: 12px;
+  background: #3b82f6;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  font-size: 16px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.schedule-btn:hover:not(:disabled) {
+  background: #2563eb;
+}
+
+.schedule-btn:disabled {
+  background: #9ca3af;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Date Range Selector
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { DatePicker } from "@umbra-ui/core";
+
+const startDate = ref(new Date());
+const endDate = ref(new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)); // 7 days from now
+
+const dateRange = computed(() => {
+  const diffTime = Math.abs(
+    endDate.value.getTime() - startDate.value.getTime()
+  );
+  const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+  return diffDays;
+});
+
+const isValidRange = computed(() => {
+  return endDate.value >= startDate.value;
+});
+
+const handleStartDateChange = (date: Date) => {
+  startDate.value = date;
+  // Ensure end date is not before start date
+  if (endDate.value < startDate.value) {
+    endDate.value = new Date(startDate.value.getTime() + 24 * 60 * 60 * 1000);
+  }
+};
+
+const handleEndDateChange = (date: Date) => {
+  endDate.value = date;
+};
+</script>
+
+<template>
+  <div class="date-range-selector">
+    <div class="selector-header">
+      <h3>Date Range Selector</h3>
+      <p>Select your travel dates</p>
+    </div>
+
+    <div class="date-inputs">
+      <div class="date-input">
+        <label class="form-label">Check-in Date</label>
+        <DatePicker
+          v-model:date="startDate"
+          @update:date="handleStartDateChange"
+        />
+      </div>
+
+      <div class="date-input">
+        <label class="form-label">Check-out Date</label>
+        <DatePicker v-model:date="endDate" @update:date="handleEndDateChange" />
+      </div>
+    </div>
+
+    <div v-if="!isValidRange" class="error">
+      ❌ Check-out date must be after check-in date
+    </div>
+
+    <div v-else class="range-summary">
+      <h4>Booking Summary</h4>
+      <div class="summary-grid">
+        <div class="summary-item">
+          <span class="label">Check-in:</span>
+          <span class="value">{{ startDate.toLocaleDateString() }}</span>
+        </div>
+        <div class="summary-item">
+          <span class="label">Check-out:</span>
+          <span class="value">{{ endDate.toLocaleDateString() }}</span>
+        </div>
+        <div class="summary-item">
+          <span class="label">Duration:</span>
+          <span class="value"
+            >{{ dateRange }} {{ dateRange === 1 ? "day" : "days" }}</span
+          >
+        </div>
+      </div>
+
+      <button :disabled="!isValidRange" class="book-btn">
+        Book for {{ dateRange }} {{ dateRange === 1 ? "day" : "days" }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.date-range-selector {
+  padding: 24px;
+  max-width: 600px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.selector-header {
+  margin-bottom: 32px;
+}
+
+.selector-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.date-inputs {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 24px;
+  margin-bottom: 24px;
+}
+
+.date-input {
+  text-align: center;
+}
+
+.form-label {
+  display: block;
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  margin-bottom: 12px;
+}
+
+.error {
+  margin-bottom: 24px;
+  padding: 12px;
+  background: #fee2e2;
+  color: #dc2626;
+  border-radius: 6px;
+  text-align: center;
+  font-weight: 500;
+}
+
+.range-summary {
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.range-summary h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.summary-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.summary-item {
+  text-align: center;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.label {
+  display: block;
+  font-size: 12px;
+  font-weight: 500;
+  color: #6b7280;
+  margin-bottom: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.value {
+  display: block;
+  font-size: 16px;
+  font-weight: 600;
+  color: #1f2937;
+}
+
+.book-btn {
+  width: 100%;
+  padding: 16px;
+  background: #059669;
+  color: white;
+  border: none;
+  border-radius: 8px;
+  font-size: 16px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.book-btn:hover:not(:disabled) {
+  background: #047857;
+}
+
+.book-btn:disabled {
+  background: #9ca3af;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Birthday Selector
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { DatePicker } from "@umbra-ui/core";
+
+const birthday = ref(new Date(1990, 0, 1)); // Default to January 1, 1990
+
+const age = computed(() => {
+  const today = new Date();
+  const birthDate = new Date(birthday.value);
+  let age = today.getFullYear() - birthDate.getFullYear();
+  const monthDiff = today.getMonth() - birthDate.getMonth();
+
+  if (
+    monthDiff < 0 ||
+    (monthDiff === 0 && today.getDate() < birthDate.getDate())
+  ) {
+    age--;
+  }
+
+  return age;
+});
+
+const zodiacSign = computed(() => {
+  const month = birthday.value.getMonth() + 1;
+  const day = birthday.value.getDate();
+
+  const signs = [
+    { name: "Capricorn", start: [12, 22], end: [1, 19] },
+    { name: "Aquarius", start: [1, 20], end: [2, 18] },
+    { name: "Pisces", start: [2, 19], end: [3, 20] },
+    { name: "Aries", start: [3, 21], end: [4, 19] },
+    { name: "Taurus", start: [4, 20], end: [5, 20] },
+    { name: "Gemini", start: [5, 21], end: [6, 20] },
+    { name: "Cancer", start: [6, 21], end: [7, 22] },
+    { name: "Leo", start: [7, 23], end: [8, 22] },
+    { name: "Virgo", start: [8, 23], end: [9, 22] },
+    { name: "Libra", start: [9, 23], end: [10, 22] },
+    { name: "Scorpio", start: [10, 23], end: [11, 21] },
+    { name: "Sagittarius", start: [11, 22], end: [12, 21] },
+  ];
+
+  for (const sign of signs) {
+    const [startMonth, startDay] = sign.start;
+    const [endMonth, endDay] = sign.end;
+
+    if (
+      (month === startMonth && day >= startDay) ||
+      (month === endMonth && day <= endDay) ||
+      (startMonth > endMonth && (month > startMonth || month < endMonth))
+    ) {
+      return sign.name;
+    }
+  }
+
+  return "Unknown";
+});
+
+const isFutureDate = computed(() => {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  return birthday.value > today;
+});
+
+const handleBirthdayChange = (date: Date) => {
+  birthday.value = date;
+  console.log("Birthday changed to:", date);
+};
+</script>
+
+<template>
+  <div class="birthday-selector">
+    <div class="selector-header">
+      <h3>Birthday Information</h3>
+      <p>Tell us about your special day</p>
+    </div>
+
+    <div class="form-section">
+      <label class="form-label">Birthday</label>
+      <DatePicker v-model:date="birthday" @update:date="handleBirthdayChange" />
+
+      <div v-if="isFutureDate" class="warning">
+        ⚠️ This date is in the future
+      </div>
+    </div>
+
+    <div class="birthday-info">
+      <h4>Your Birthday Details</h4>
+      <div class="info-grid">
+        <div class="info-item">
+          <span class="label">Age</span>
+          <span class="value">{{ age }} years old</span>
+        </div>
+        <div class="info-item">
+          <span class="label">Zodiac Sign</span>
+          <span class="value">{{ zodiacSign }}</span>
+        </div>
+        <div class="info-item">
+          <span class="label">Birthday</span>
+          <span class="value">{{
+            birthday.toLocaleDateString("en-US", {
+              weekday: "long",
+              year: "numeric",
+              month: "long",
+              day: "numeric",
+            })
+          }}</span>
+        </div>
+      </div>
+
+      <div class="birthday-message">
+        <p>🎉 Your birthday is a special day worth celebrating!</p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.birthday-selector {
+  padding: 24px;
+  max-width: 500px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.selector-header {
+  margin-bottom: 32px;
+}
+
+.selector-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.form-section {
+  margin-bottom: 32px;
+}
+
+.form-label {
+  display: block;
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  margin-bottom: 12px;
+}
+
+.warning {
+  margin-top: 8px;
+  padding: 8px 12px;
+  background: #fef3c7;
+  color: #92400e;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.birthday-info {
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.birthday-info h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 20px 0;
+}
+
+.info-grid {
+  display: grid;
+  gap: 16px;
+  margin-bottom: 24px;
+}
+
+.info-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.label {
+  font-weight: 500;
+  color: #4a5568;
+}
+
+.value {
+  color: #2d3748;
+  font-weight: 600;
+}
+
+.birthday-message {
+  text-align: center;
+  padding: 20px;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border-radius: 8px;
+}
+
+.birthday-message p {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 500;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Custom Date Validation
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { DatePicker } from "@umbra-ui/core";
+
+const selectedDate = ref(new Date());
+const minDate = new Date(2024, 0, 1); // January 1, 2024
+const maxDate = new Date(2024, 11, 31); // December 31, 2024
+
+const isDateValid = computed(() => {
+  return selectedDate.value >= minDate && selectedDate.value <= maxDate;
+});
+
+const validationMessage = computed(() => {
+  if (selectedDate.value < minDate) {
+    return `Date must be after ${minDate.toLocaleDateString()}`;
+  }
+  if (selectedDate.value > maxDate) {
+    return `Date must be before ${maxDate.toLocaleDateString()}`;
+  }
+  return "Date is valid";
+});
+
+const handleDateChange = (date: Date) => {
+  selectedDate.value = date;
+  console.log("Date validation:", isDateValid.value);
+};
+</script>
+
+<template>
+  <div class="date-validation">
+    <h3>Date Validation Example</h3>
+
+    <div class="form-section">
+      <label class="form-label">Select Date (2024 only)</label>
+      <DatePicker v-model:date="selectedDate" @update:date="handleDateChange" />
+
+      <div
+        :class="[
+          'validation-message',
+          {
+            valid: isDateValid,
+            invalid: !isDateValid,
+          },
+        ]"
+      >
+        {{ validationMessage }}
+      </div>
+    </div>
+
+    <div class="date-info">
+      <p><strong>Selected:</strong> {{ selectedDate.toLocaleDateString() }}</p>
+      <p><strong>Valid:</strong> {{ isDateValid ? "Yes" : "No" }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.date-validation {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.form-section {
+  margin-bottom: 24px;
+}
+
+.form-label {
+  display: block;
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  margin-bottom: 12px;
+}
+
+.validation-message {
+  margin-top: 8px;
+  padding: 8px 12px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.validation-message.valid {
+  background: #d1fae5;
+  color: #065f46;
+}
+
+.validation-message.invalid {
+  background: #fee2e2;
+  color: #dc2626;
+}
+
+.date-info {
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.date-info p {
+  margin: 0 0 8px 0;
+  color: #4a5568;
+}
+
+.date-info p:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+## Performance Considerations
+
+- **Floating UI**: Smart positioning with automatic updates and cleanup
+- **Teleport**: Overlay and picker are teleported to body for proper z-index management
+- **Event Cleanup**: Proper cleanup of auto-update listeners on unmount
+- **Lazy Loading**: Months are generated on-demand during scrolling
+- **Smooth Scrolling**: Optimized scroll handling with debouncing
+
+## Accessibility
+
+- **Keyboard Navigation**: Support for keyboard interaction
+- **Screen Reader Support**: Proper ARIA labels and semantic structure
+- **Focus Management**: Focus is properly managed during interactions
+- **Date Information**: Displays formatted date strings for clarity
+- **High Contrast**: Supports high contrast mode with appropriate styling
+
+## Browser Support
+
+- **Modern Browsers**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
+- **Mobile Browsers**: iOS Safari 14+, Chrome Mobile 88+
+- **CSS Features**: Uses CSS Grid and modern layout features
+- **JavaScript**: Requires ES2020+ support
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Picker not positioning correctly**: Ensure the trigger button has proper positioning context
+2. **Date not updating**: Check that the v-model binding is correctly set up
+3. **Calendar not showing**: Verify that the showPopover state is properly managed
+4. **Scrolling issues**: Ensure the scroll container has proper height constraints
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { DatePicker } from "@umbra-ui/core";
+
+const selectedDate = ref(new Date());
+
+// Watch for changes
+watch(selectedDate, (newDate) => {
+  console.log("Selected date changed:", newDate);
+  console.log("Date string:", newDate.toLocaleDateString());
+});
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `v-model` prop is now `v-model:date`
+- Event names have been updated to use kebab-case
+- Calendar system has been improved with better scrolling
+- Floating UI integration has been enhanced
+
+### Breaking Changes
+
+- Removed `value` prop in favor of `v-model:date`
+- Changed event names from camelCase to kebab-case
+- Updated date prop to use Date object instead of string
+- Modified CSS class naming convention