kasy-cli 1.18.0 → 1.19.1

package/templates/firebase/lib/components/kasy_date_picker.dart

@@ -1,5 +1,9 @@
 import 'package:flutter/material.dart';
+import 'package:kasy_kit/components/kasy_bottom_sheet.dart';
+import 'package:kasy_kit/components/kasy_dialog.dart';
+import 'package:kasy_kit/components/kasy_text_field.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_hover.dart';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Data helpers
@@ -17,11 +21,63 @@ const List<String> _kWeekdayAbbreviations = [
 /// Returns the number of days in [month] of [year].
 int _daysInMonth(int year, int month) => DateTime(year, month + 1, 0).day;
 
-/// Formats [date] as "mm / dd / yyyy".
-String _formatDate(DateTime date) =>
-    '${date.month.toString().padLeft(2, '0')} / '
-    '${date.day.toString().padLeft(2, '0')} / '
-    '${date.year}';
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyDateFormat — built-in regional formatting presets
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Built-in date display formats. Pick the one that matches the user's region,
+/// or pass [KasyDatePicker.formatDate] for a fully custom layout.
+enum KasyDateFormat {
+  /// MM / DD / YYYY — United States (en-US).
+  us,
+
+  /// DD / MM / YYYY — South America, UK, France, Italy, Spain, Portugal, and
+  /// most of Europe. Default for the [KasyDatePickerLocale.es] and
+  /// [KasyDatePickerLocale.pt] locales.
+  southAmerican,
+
+  /// DD.MM.YYYY — Germany, Austria, Switzerland, Netherlands.
+  european,
+
+  /// YYYY-MM-DD — ISO 8601 international standard, common in APIs and logs.
+  iso,
+
+  /// YYYY / MM / DD — Japan, China, Korea (East Asian convention).
+  eastAsian,
+}
+
+String _formatWithPreset(DateTime date, KasyDateFormat preset) {
+  final String mm = date.month.toString().padLeft(2, '0');
+  final String dd = date.day.toString().padLeft(2, '0');
+  final String yyyy = date.year.toString();
+  switch (preset) {
+    case KasyDateFormat.us:
+      return '$mm / $dd / $yyyy';
+    case KasyDateFormat.southAmerican:
+      return '$dd / $mm / $yyyy';
+    case KasyDateFormat.european:
+      return '$dd.$mm.$yyyy';
+    case KasyDateFormat.iso:
+      return '$yyyy-$mm-$dd';
+    case KasyDateFormat.eastAsian:
+      return '$yyyy / $mm / $dd';
+  }
+}
+
+String _placeholderFor(KasyDateFormat preset) {
+  switch (preset) {
+    case KasyDateFormat.us:
+      return 'mm / dd / yyyy';
+    case KasyDateFormat.southAmerican:
+      return 'dd / mm / yyyy';
+    case KasyDateFormat.european:
+      return 'dd.mm.yyyy';
+    case KasyDateFormat.iso:
+      return 'yyyy-mm-dd';
+    case KasyDateFormat.eastAsian:
+      return 'yyyy / mm / dd';
+  }
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // _DayData — internal model for a single calendar cell
@@ -49,14 +105,16 @@ List<_DayData> _buildDayGrid(
   DateTime viewMonth, {
   DateTime? minDate,
   DateTime? maxDate,
+  int weekStartDay = 0,
 }) {
   final DateTime today = DateTime.now();
   final int daysInCurrent = _daysInMonth(viewMonth.year, viewMonth.month);
 
-  // Grid starts on Sunday (index 0).
-  // Dart weekday: 1=Mon … 7=Sun → sunday offset = weekday % 7.
+  // Dart weekday: Mon=1 … Sun=7.
+  // Convert to Sunday-origin (Sun=0, Mon=1, …, Sat=6), then shift by weekStartDay.
+  // weekStartDay 0 = Sunday-first, 1 = Monday-first.
   final DateTime firstOfMonth = DateTime(viewMonth.year, viewMonth.month);
-  final int offset = firstOfMonth.weekday % 7;
+  final int offset = (firstOfMonth.weekday % 7 - weekStartDay + 7) % 7;
 
   // Previous-month fill.
   final int prevYear =
@@ -128,25 +186,7 @@ bool _isSameDay(DateTime a, DateTime b) =>
 // Design constants (from Figma variable defs)
 // ─────────────────────────────────────────────────────────────────────────────
 
-// DateField: 3 drop-shadow layers — offset(0,2)blur:4, offset(0,1)blur:2, offset(0,0)blur:1
-const List<BoxShadow> _kFieldShadows = [
-  BoxShadow(
-    color: Color(0x0A000000), // field/shadow  rgba(0,0,0,0.04)
-    blurRadius: 4,
-    offset: Offset(0, 2),
-  ),
-  BoxShadow(
-    color: Color(0x0F000000), // field/shadow-2 rgba(0,0,0,0.06)
-    blurRadius: 2,
-    offset: Offset(0, 1),
-  ),
-  BoxShadow(
-    color: Color(0x0F000000), // field/shadow-2 rgba(0,0,0,0.06)
-    blurRadius: 1,
-  ),
-];
-
-// Calendar overlay: shadow-overlay from Figma variable defs.
+// Calendar overlay shadow — from Figma variable defs (3 layers).
 const List<BoxShadow> _kCalendarShadows = [
   BoxShadow(
     color: Color(0x14000000), // rgba(0,0,0,0.08)
@@ -154,7 +194,7 @@ const List<BoxShadow> _kCalendarShadows = [
     offset: Offset(0, 14),
   ),
   BoxShadow(
-    color: Color(0x08000000), // rgba(0,0,0,0.03)
+    color: Color(0x07000000), // rgba(0,0,0,0.027)
     blurRadius: 12,
     offset: Offset(0, -6),
   ),
@@ -165,14 +205,200 @@ const List<BoxShadow> _kCalendarShadows = [
   ),
 ];
 
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyDatePickerLocale — calendar display locale
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Controls month names, weekday labels, week start, and month/year separator
+/// inside the [KasyDatePicker] calendar overlay.
+///
+/// Two built-in presets are provided: [KasyDatePickerLocale.en] and
+/// [KasyDatePickerLocale.es]. For other locales, construct a custom instance.
+class KasyDatePickerLocale {
+  const KasyDatePickerLocale({
+    required this.monthNames,
+    required this.weekdayAbbreviations,
+    this.weekStartDay = 0,
+    this.monthYearSeparator = ' ',
+    this.defaultDateFormat = KasyDateFormat.us,
+  });
+
+  /// Full month names — 12 entries (January … December order).
+  final List<String> monthNames;
+
+  /// Weekday header abbreviations — 7 entries ordered from [weekStartDay].
+  /// For Sunday-start: Sun Mon Tue Wed Thu Fri Sat.
+  /// For Monday-start: Mon Tue Wed Thu Fri Sat Sun.
+  final List<String> weekdayAbbreviations;
+
+  /// First day of the week shown in the calendar grid.
+  /// 0 = Sunday (default, en-US), 1 = Monday (most of the world).
+  final int weekStartDay;
+
+  /// String inserted between the month name and year in the calendar header.
+  /// English: ' ' → "May 2026". Spanish: ' de ' → "mayo de 2026".
+  final String monthYearSeparator;
+
+  /// Region-appropriate display format used when [KasyDatePicker.dateFormat]
+  /// and [KasyDatePicker.formatDate] are both null. Defaults to
+  /// [KasyDateFormat.us] for English and [KasyDateFormat.southAmerican] for
+  /// Spanish and Portuguese.
+  final KasyDateFormat defaultDateFormat;
+
+  /// English locale — Sunday-first week, US date format.
+  static const KasyDatePickerLocale en = KasyDatePickerLocale(
+    monthNames: _kMonthNames,
+    weekdayAbbreviations: _kWeekdayAbbreviations,
+  );
+
+  /// Spanish locale — Monday-first week, South-American date format.
+  static const KasyDatePickerLocale es = KasyDatePickerLocale(
+    monthNames: [
+      'enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio',
+      'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre',
+    ],
+    weekdayAbbreviations: ['lun', 'mar', 'mié', 'jue', 'vie', 'sáb', 'dom'],
+    weekStartDay: 1,
+    monthYearSeparator: ' de ',
+    defaultDateFormat: KasyDateFormat.southAmerican,
+  );
+
+  /// Portuguese (Brazil) locale — Monday-first week, South-American date format.
+  static const KasyDatePickerLocale pt = KasyDatePickerLocale(
+    monthNames: [
+      'janeiro', 'fevereiro', 'março', 'abril', 'maio', 'junho',
+      'julho', 'agosto', 'setembro', 'outubro', 'novembro', 'dezembro',
+    ],
+    weekdayAbbreviations: ['seg', 'ter', 'qua', 'qui', 'sex', 'sáb', 'dom'],
+    weekStartDay: 1,
+    monthYearSeparator: ' de ',
+    defaultDateFormat: KasyDateFormat.southAmerican,
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyDatePickerNavStyle — header layout of the calendar's nav row
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Visual layout for the calendar's month-navigation row.
+enum KasyDatePickerNavStyle {
+  /// Arrows on the outer edges, month/year centered between them
+  /// ("‹ December 2025 ›"). Default — matches modern desktop calendars
+  /// (Airbnb, Google Calendar) and is also used as the multi-month layout
+  /// where arrows wrap the row of month captions.
+  multi,
+
+  /// Month/year on the left, prev/next arrows clustered on the right
+  /// ("December 2025 … ‹ ›"). Compact, mirrors iOS native pickers.
+  single,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyDatePickerPresentation — controls how the calendar is shown
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Controls how the calendar is presented when the date field is tapped.
+enum KasyDatePickerPresentation {
+  /// Floating overlay anchored below the trigger field (default).
+  popover,
+
+  /// Modal dialog centered on screen.
+  dialog,
+
+  /// Modal bottom sheet sliding up from the bottom.
+  bottomSheet,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KasyDateSelectionMode + KasyDateRange — single vs. start/end selection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// How the user selects dates inside the calendar.
+enum KasyDateSelectionMode {
+  /// One tap commits a single date (default — back-compat with [value]).
+  single,
+
+  /// Two taps commit a start + end date (Airbnb-style range selection). The
+  /// calendar stays open until both endpoints are picked, then auto-closes.
+  range,
+}
+
+/// Immutable start/end pair used in [KasyDateSelectionMode.range]. Either
+/// endpoint can be null while the user is still picking.
+class KasyDateRange {
+  const KasyDateRange({this.start, this.end});
+
+  final DateTime? start;
+  final DateTime? end;
+
+  /// True when both endpoints are set — used by the picker to know it can
+  /// close the calendar.
+  bool get isComplete => start != null && end != null;
+
+  /// True when at least the start is set.
+  bool get hasStart => start != null;
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is KasyDateRange && other.start == start && other.end == end;
+
+  @override
+  int get hashCode => Object.hash(start, end);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// _CalendarViewMode — month grid vs. year picker
+// ─────────────────────────────────────────────────────────────────────────────
+
+enum _CalendarViewMode { month, year }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// _RangePosition — where a day sits inside a [KasyDateRange]
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Drives the Airbnb-style highlight:
+//   none    → no background, default text color
+//   start   → primary circle + soft bar extending to the right edge
+//   middle  → soft bar full-width (no cell radius, connects start↔end)
+//   end     → primary circle + soft bar extending to the left edge
+//   single  → primary circle alone (single-date pick OR range with start==end)
+enum _RangePosition { none, start, middle, end, single }
+
+_RangePosition _positionFor(DateTime day, KasyDateRange? range) {
+  if (range == null || range.start == null) return _RangePosition.none;
+  final DateTime start = range.start!;
+  final DateTime? end = range.end;
+  if (end == null) {
+    return _isSameDay(day, start) ? _RangePosition.single : _RangePosition.none;
+  }
+  if (_isSameDay(start, end)) {
+    return _isSameDay(day, start) ? _RangePosition.single : _RangePosition.none;
+  }
+  if (_isSameDay(day, start)) return _RangePosition.start;
+  if (_isSameDay(day, end)) return _RangePosition.end;
+  // Strictly between — use day-only comparison so time components don't break.
+  final DateTime d = DateTime(day.year, day.month, day.day);
+  final DateTime s = DateTime(start.year, start.month, start.day);
+  final DateTime e = DateTime(end.year, end.month, end.day);
+  if (d.isAfter(s) && d.isBefore(e)) return _RangePosition.middle;
+  return _RangePosition.none;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // KasyDatePicker
 // ─────────────────────────────────────────────────────────────────────────────
 
 /// Date picker combining a text-field trigger with a floating calendar overlay.
 ///
-/// Tapping the field opens a calendar below the trigger. Selecting a day
-/// calls [onChanged] and closes the calendar.
+/// The trigger reuses [KasyTextField] in read-only mode so it inherits the
+/// design-system input look (label, hint, suffix-icon slot, padding, border,
+/// shadow). Any change made to [KasyTextField] (e.g. label or placeholder
+/// styling) propagates automatically to this component. Tapping the field
+/// opens a calendar below the trigger via [OverlayPortal] (popover mode),
+/// inside a [showKasyDialog] (dialog mode) or [showKasyBottomSheet] (bottom
+/// sheet mode). Selecting a day calls [onChanged] and closes the calendar.
 ///
 /// Usage:
 /// ```dart
@@ -188,21 +414,53 @@ class KasyDatePicker extends StatefulWidget {
     this.label,
     this.value,
     this.onChanged,
+    this.range,
+    this.onRangeChanged,
+    this.selectionMode = KasyDateSelectionMode.single,
     this.minDate,
     this.maxDate,
     this.enabled = true,
-    this.placeholder = 'mm / dd / yyyy',
+    this.placeholder,
+    this.presentation = KasyDatePickerPresentation.popover,
+    this.showRequiredIndicator = false,
+    this.errorText,
+    this.isInvalid = false,
+    this.description,
+    this.dateFormat,
+    this.formatDate,
+    this.locale = KasyDatePickerLocale.en,
+    this.variant = KasyTextFieldVariant.primary,
+    this.focusBorder = true,
+    this.showSuffix = true,
+    this.showBarrier = true,
+    this.monthsToShow,
   });
 
   /// Label displayed above the field. Omit to hide.
   final String? label;
 
-  /// Currently selected date. Pass null for no selection.
+  /// Currently selected date — only used in [KasyDateSelectionMode.single].
+  /// Pass null for no selection.
   final DateTime? value;
 
-  /// Called when the user picks a date.
+  /// Called when the user picks a date in [KasyDateSelectionMode.single].
   final ValueChanged<DateTime>? onChanged;
 
+  /// Currently selected start/end pair — only used in
+  /// [KasyDateSelectionMode.range]. Pass null for no selection. The picker
+  /// keeps the calendar open while the range is still being built, then
+  /// closes once both endpoints are set.
+  final KasyDateRange? range;
+
+  /// Called when the user updates the range. Fires twice: once with only
+  /// [KasyDateRange.start] set (after the first tap), then again with both
+  /// endpoints (after the second tap, just before the popover closes).
+  final ValueChanged<KasyDateRange>? onRangeChanged;
+
+  /// Whether the picker selects a single date or a start/end range.
+  /// Defaults to [KasyDateSelectionMode.single].
+  final KasyDateSelectionMode selectionMode;
+
   /// Earliest selectable date (inclusive).
   final DateTime? minDate;
 
@@ -211,8 +469,72 @@ class KasyDatePicker extends StatefulWidget {
 
   final bool enabled;
 
-  /// Placeholder text shown when no date is selected.
-  final String placeholder;
+  /// Placeholder text shown when no date is selected. When null, the
+  /// placeholder is derived from the active [KasyDateFormat] preset
+  /// (e.g. "mm / dd / yyyy" for [KasyDateFormat.us]).
+  final String? placeholder;
+
+  /// How the calendar is presented when the field is tapped.
+  final KasyDatePickerPresentation presentation;
+
+  /// When true, shows a red `*` after the label.
+  final bool showRequiredIndicator;
+
+  /// Error message displayed below the field. Also triggers red border.
+  final String? errorText;
+
+  /// When true, shows a red border without an error message.
+  final bool isInvalid;
+
+  /// Helper text displayed below the field in muted color.
+  final String? description;
+
+  /// Built-in regional format preset. When null (default), falls back to
+  /// [KasyDatePickerLocale.defaultDateFormat] so the date follows the locale's
+  /// regional convention. Ignored when [formatDate] is provided.
+  final KasyDateFormat? dateFormat;
+
+  /// Fully custom date formatter. When provided, overrides [dateFormat] and
+  /// the locale default.
+  final String Function(DateTime)? formatDate;
+
+  /// Calendar display locale — controls month names, weekday labels, week
+  /// start day, and the regional [defaultDateFormat]. Defaults to
+  /// [KasyDatePickerLocale.en] (English, Sunday-first, US date format).
+  final KasyDatePickerLocale locale;
+
+  /// Visual variant of the trigger field. Defaults to
+  /// [KasyTextFieldVariant.primary] (white surface + soft shadow on mobile).
+  /// Use [KasyTextFieldVariant.secondary] for a flat filled look without
+  /// shadow, matching the "filled" KasyTextField style.
+  final KasyTextFieldVariant variant;
+
+  /// When true (default), the trigger field shows a focus border while the
+  /// calendar is open — mirroring the [KasyTextField] focus affordance so
+  /// the user clearly sees the field is "active". Set to false to suppress
+  /// the focus border in every state.
+  final bool focusBorder;
+
+  /// When true (default), the calendar icon is rendered in the trigger's
+  /// suffix slot. Set to false to hide the icon (useful for very compact
+  /// layouts where the field width is the only affordance).
+  final bool showSuffix;
+
+  /// Popover only: when true (default), a dimmed scrim is shown behind the
+  /// calendar (matching the dialog/bottom-sheet barriers). Set to false for
+  /// a lighter, "tooltip"-style overlay with no backdrop — the page stays
+  /// visible and tap-outside still closes the popover.
+  final bool showBarrier;
+
+  /// Number of calendar months shown side by side. Defaults to a single
+  /// month on every platform — pass an explicit 2 or 3 to opt in to the
+  /// multi-month layout (typical on wide web canvases).
+  ///
+  /// The nav-row layout follows automatically: a single-month picker uses
+  /// the compact "month/year left, arrows clustered right" style; a
+  /// multi-month picker uses "one arrow per edge, captions centered above
+  /// each grid". Callers don't choose the nav style explicitly.
+  final int? monthsToShow;
 
   @override
   State<KasyDatePicker> createState() => _KasyDatePickerState();
@@ -226,11 +548,50 @@ class _KasyDatePickerState extends State<KasyDatePicker>
   // Unique ID so TapRegion knows "field + calendar" form one group.
   final Object _tapGroupId = Object();
 
+  // Key on the trigger field — used to measure its width when opening the popover.
+  final GlobalKey _fieldKey = GlobalKey();
+
+  // Focus node owned by the trigger field. We want focus so the
+  // KasyTextField paints its focus border while the calendar is open — but
+  // the underlying TextField runs in readOnly mode, so no soft keyboard
+  // appears even when focused.
+  final FocusNode _fieldFocusNode = FocusNode();
+
+  // Controller backing the trigger KasyTextField — text mirrors the formatted
+  // date (or stays empty so the hint renders).
+  late final TextEditingController _displayController;
+
   // Month currently displayed in the calendar (always first of the month).
   late DateTime _viewMonth;
 
   bool _isOpen = false;
 
+  // Selection picked inside the popover but not yet committed to the parent.
+  // We keep it parked while the close animation runs so the cell does NOT
+  // flip to its primary state mid-fade — the press feedback stays visible on
+  // the original (non-selected) cell, matching the dialog/bottom sheet UX.
+  // The actual commit happens at the end of the fade-out, so no artificial
+  // delay is introduced (we just piggy-back on the existing 180ms animation).
+  DateTime? _pendingPopoverSelection;
+
+  /// Same trick as [_pendingPopoverSelection] but for range-mode completion:
+  /// we park the completed range and commit it only after the fade-out so the
+  /// press feedback stays visible on the second-tap cell during the close.
+  KasyDateRange? _pendingPopoverRange;
+
+  // Width of the trigger field, read at open time.
+  double _calendarWidth = 288;
+
+  // When true, the popover renders ABOVE the trigger instead of below.
+  // Computed at open time based on available space.
+  bool _openUp = false;
+
+  // Conservative estimate of the calendar panel height. Kept on the high side
+  // (real layout measures ~460px) so the flip-up logic in _open() errs on the
+  // safe side — if there's any doubt, prefer opening above to avoid being
+  // clipped by the bottom of the screen.
+  static const double _kEstimatedCalendarHeight = 460;
+
   late final AnimationController _animCtrl;
   late final Animation<double> _fadeAnim;
   late final Animation<double> _scaleAnim;
@@ -238,7 +599,8 @@ class _KasyDatePickerState extends State<KasyDatePicker>
   @override
   void initState() {
     super.initState();
-    _viewMonth = _monthOf(widget.value ?? DateTime.now());
+    _viewMonth = _monthOf(_initialAnchorDate() ?? DateTime.now());
+    _displayController = TextEditingController(text: _displayText());
     _animCtrl = AnimationController(
       vsync: this,
       duration: const Duration(milliseconds: 180),
@@ -256,46 +618,314 @@ class _KasyDatePickerState extends State<KasyDatePicker>
   @override
   void didUpdateWidget(KasyDatePicker old) {
     super.didUpdateWidget(old);
-    if (old.value != widget.value && widget.value != null) {
-      _viewMonth = _monthOf(widget.value!);
+    final bool selectionChanged = old.value != widget.value ||
+        old.range != widget.range ||
+        old.selectionMode != widget.selectionMode;
+    // Re-format the displayed text whenever the formatting inputs change too,
+    // not just the value — otherwise switching dateFormat/formatDate/locale
+    // leaves the field showing the previous format's string.
+    final bool formatChanged = old.dateFormat != widget.dateFormat ||
+        old.formatDate != widget.formatDate ||
+        old.locale != widget.locale;
+    if (!selectionChanged && !formatChanged) return;
+    if (selectionChanged) {
+      final DateTime? anchor = _initialAnchorDate();
+      if (anchor != null) _viewMonth = _monthOf(anchor);
     }
+    _displayController.text = _displayText();
   }
 
   @override
   void dispose() {
+    _displayController.dispose();
+    _fieldFocusNode.dispose();
     _animCtrl.dispose();
     super.dispose();
   }
 
   DateTime _monthOf(DateTime d) => DateTime(d.year, d.month);
 
+  /// Resolved formatting preset: respects an explicit override on the widget
+  /// and falls back to the locale's regional default.
+  KasyDateFormat get _resolvedFormat =>
+      widget.dateFormat ?? widget.locale.defaultDateFormat;
+
+  /// Unified selection. In single mode the picked [value] is wrapped in a
+  /// range with `start == end == value` so the calendar tree only deals
+  /// with one shape ([KasyDateRange]) regardless of selectionMode.
+  KasyDateRange? get _effectiveRange {
+    if (widget.selectionMode == KasyDateSelectionMode.range) {
+      return widget.range;
+    }
+    if (widget.value == null) return null;
+    return KasyDateRange(start: widget.value, end: widget.value);
+  }
+
+  String _formatDate(DateTime date) =>
+      widget.formatDate?.call(date) ?? _formatWithPreset(date, _resolvedFormat);
+
+  /// Picks the most relevant date for opening the calendar view: the single
+  /// value if present, otherwise the range start (range mode), otherwise
+  /// null (the calendar then anchors on today).
+  DateTime? _initialAnchorDate() {
+    if (widget.selectionMode == KasyDateSelectionMode.range) {
+      return widget.range?.start;
+    }
+    return widget.value;
+  }
+
+  /// Text shown in the trigger field. Single mode renders the picked date;
+  /// range mode renders "start - end" once both endpoints are set, or just
+  /// "start - ..." while waiting for the end so the user sees progress.
+  String _displayText() {
+    if (widget.selectionMode == KasyDateSelectionMode.range) {
+      final KasyDateRange? r = widget.range;
+      if (r == null || r.start == null) return '';
+      final String startStr = _formatDate(r.start!);
+      if (r.end == null) return '$startStr  -  ...';
+      return '$startStr  -  ${_formatDate(r.end!)}';
+    }
+    if (widget.value == null) return '';
+    return _formatDate(widget.value!);
+  }
+
+  /// Placeholder shown when no date is picked. Uses the explicit
+  /// [KasyDatePicker.placeholder] when provided, otherwise derives the hint
+  /// from the active preset so it matches what the user will eventually see.
+  String get _resolvedPlaceholder =>
+      widget.placeholder ?? _placeholderFor(_resolvedFormat);
+
   // ── Calendar toggle ────────────────────────────────────────────────────────
 
   void _toggleCalendar() {
     if (!widget.enabled) return;
-    if (_isOpen) {
-      _close();
+    if (widget.presentation == KasyDatePickerPresentation.popover) {
+      if (_isOpen) {
+        _close();
+      } else {
+        _open();
+      }
+    } else if (widget.presentation == KasyDatePickerPresentation.dialog) {
+      _openDialog();
     } else {
-      _open();
+      _openBottomSheet();
     }
   }
 
   void _open() {
+    // Read the actual field width and global position so the calendar matches
+    // it and we can decide whether to open above or below the trigger.
+    final RenderBox? fieldBox =
+        _fieldKey.currentContext?.findRenderObject() as RenderBox?;
+    _calendarWidth = fieldBox?.size.width ?? 288;
+
+    bool openUp = false;
+    if (fieldBox != null) {
+      final Offset fieldTopLeft = fieldBox.localToGlobal(Offset.zero);
+      final Size viewport = MediaQuery.sizeOf(context);
+      // viewPaddingOf returns the system safe-area insets even when an
+      // ancestor SafeArea has already consumed them — paddingOf would
+      // return 0 in that case and overestimate the available room.
+      final EdgeInsets safe = MediaQuery.viewPaddingOf(context);
+      final double fieldBottom = fieldTopLeft.dy + fieldBox.size.height;
+      final double spaceBelow = viewport.height - safe.bottom - fieldBottom;
+      final double spaceAbove = fieldTopLeft.dy - safe.top;
+      // Flip up only when below doesn't fit AND above fits better.
+      if (spaceBelow < _kEstimatedCalendarHeight + 8 &&
+          spaceAbove > spaceBelow) {
+        openUp = true;
+      }
+    }
+    _openUp = openUp;
+
     _portalController.show();
     _animCtrl.forward();
+    // Focus so the trigger field paints its focus border while the calendar
+    // is open (only when focusBorder is enabled — otherwise we skip to avoid
+    // the field announcing focus to assistive tech for no visual reason).
+    if (widget.focusBorder) _fieldFocusNode.requestFocus();
     setState(() => _isOpen = true);
   }
 
   void _close() {
     _animCtrl.reverse().then((_) {
-      if (mounted) _portalController.hide();
+      if (!mounted) return;
+      _portalController.hide();
+      // Commit any selection picked inside the popover only after the fade-out
+      // completes. This keeps the press feedback on the original cell during
+      // the close, instead of flashing the cell to primary mid-animation.
+      final DateTime? pendingSingle = _pendingPopoverSelection;
+      if (pendingSingle != null) {
+        _pendingPopoverSelection = null;
+        widget.onChanged?.call(pendingSingle);
+      }
+      final KasyDateRange? pendingRange = _pendingPopoverRange;
+      if (pendingRange != null) {
+        _pendingPopoverRange = null;
+        widget.onRangeChanged?.call(pendingRange);
+      }
+      _fieldFocusNode.unfocus();
     });
     setState(() => _isOpen = false);
   }
 
+  /// Unified entry point for a day tap. Branches on selectionMode:
+  /// - single: commit immediately (or defer to fade-out in popover mode).
+  /// - range: build the start/end pair incrementally; only close after the
+  ///   end is picked. A tap earlier than the current start restarts the
+  ///   range with that earlier date as the new start.
   void _selectDate(DateTime date) {
+    if (widget.selectionMode == KasyDateSelectionMode.range) {
+      _handleRangeSelection(date);
+      return;
+    }
+    if (widget.presentation == KasyDatePickerPresentation.popover) {
+      // Park the selection and start the close animation immediately — no
+      // artificial delay. The actual onChanged commit fires from _close()
+      // when the existing fade-out finishes.
+      _pendingPopoverSelection = date;
+      _close();
+      return;
+    }
     widget.onChanged?.call(date);
-    _close();
+    _closeOverlayRoute();
+  }
+
+  void _handleRangeSelection(DateTime date) {
+    final KasyDateRange current = widget.range ?? const KasyDateRange();
+    final bool isFirstPick = current.start == null ||
+        current.isComplete ||
+        date.isBefore(current.start!);
+    if (isFirstPick) {
+      // Start (or restart) the range. Calendar stays open waiting for end.
+      widget.onRangeChanged?.call(KasyDateRange(start: date));
+      return;
+    }
+    // Closing tap — the user just picked the end. Commit + close.
+    final KasyDateRange completed =
+        KasyDateRange(start: current.start, end: date);
+    if (widget.presentation == KasyDatePickerPresentation.popover) {
+      _pendingPopoverRange = completed;
+      _close();
+      return;
+    }
+    widget.onRangeChanged?.call(completed);
+    _closeOverlayRoute();
+  }
+
+  /// Pops the dialog/bottom sheet route opened by this picker. No-op for
+  /// popover mode (which closes via [_close]).
+  void _closeOverlayRoute() {
+    if (widget.presentation == KasyDatePickerPresentation.popover) return;
+    Navigator.of(context, rootNavigator: true).maybePop();
+  }
+
+  void _openDialog() {
+    // Local copies of the calendar's mutable state. The dialog lives on a
+    // separate route, so setState in the parent does NOT rebuild it — we
+    // mirror viewMonth AND range here and refresh via setDialogState so the
+    // user sees their picks immediately (mirrors the popover/bottom sheet
+    // behavior in range mode, where the first tap must paint the start
+    // endpoint right away).
+    DateTime dialogViewMonth = _viewMonth;
+    KasyDateRange? dialogRange = _effectiveRange;
+    if (widget.focusBorder) _fieldFocusNode.requestFocus();
+
+    showKasyDialog<void>(
+      context: context,
+      builder: (ctx) => StatefulBuilder(
+        builder: (ctx, setDialogState) {
+          // Handles taps inside the dialog. Mirrors [_handleRangeSelection]
+          // and [_selectDate] but updates dialogRange via setDialogState so
+          // the visual selection updates immediately while still notifying
+          // the parent via onChanged/onRangeChanged.
+          void onDateTapped(DateTime date) {
+            if (widget.selectionMode == KasyDateSelectionMode.range) {
+              final KasyDateRange current =
+                  dialogRange ?? const KasyDateRange();
+              final bool isFirstPick = current.start == null ||
+                  current.isComplete ||
+                  date.isBefore(current.start!);
+              if (isFirstPick) {
+                final KasyDateRange started = KasyDateRange(start: date);
+                setDialogState(() => dialogRange = started);
+                widget.onRangeChanged?.call(started);
+                return;
+              }
+              final KasyDateRange completed =
+                  KasyDateRange(start: current.start, end: date);
+              setDialogState(() => dialogRange = completed);
+              widget.onRangeChanged?.call(completed);
+              Navigator.of(ctx).pop();
+              return;
+            }
+            widget.onChanged?.call(date);
+            Navigator.of(ctx).pop();
+          }
+
+          return _CalendarPanel(
+            // Omit calendarWidth so the panel stretches to the basic dialog's
+            // natural inset (showKasyDialog uses KasySpacing.lg horizontal
+            // insetPadding). Matches the "basic dialog" proportion.
+            viewMonth: dialogViewMonth,
+            range: dialogRange,
+            monthsToShow: widget.monthsToShow,
+            onDateSelected: onDateTapped,
+            onPreviousMonth: () {
+              setDialogState(() {
+                dialogViewMonth = DateTime(
+                  dialogViewMonth.month == 1
+                      ? dialogViewMonth.year - 1
+                      : dialogViewMonth.year,
+                  dialogViewMonth.month == 1 ? 12 : dialogViewMonth.month - 1,
+                );
+              });
+            },
+            onNextMonth: () {
+              setDialogState(() {
+                dialogViewMonth = DateTime(
+                  dialogViewMonth.month == 12
+                      ? dialogViewMonth.year + 1
+                      : dialogViewMonth.year,
+                  dialogViewMonth.month == 12 ? 1 : dialogViewMonth.month + 1,
+                );
+              });
+            },
+            onYearSelected: (year) {
+              setDialogState(() {
+                dialogViewMonth = DateTime(year, dialogViewMonth.month);
+              });
+            },
+            minDate: widget.minDate,
+            maxDate: widget.maxDate,
+            locale: widget.locale,
+          );
+        },
+      ),
+    ).whenComplete(() {
+      if (mounted) _fieldFocusNode.unfocus();
+    });
+  }
+
+  void _openBottomSheet() {
+    if (widget.focusBorder) _fieldFocusNode.requestFocus();
+    showKasyBottomSheet<void>(
+      context: context,
+      isScrollControlled: true,
+      builder: (_) => _BottomSheetContent(
+        initialViewMonth: _viewMonth,
+        initialRange: _effectiveRange,
+        selectionMode: widget.selectionMode,
+        onChanged: widget.onChanged,
+        onRangeChanged: widget.onRangeChanged,
+        minDate: widget.minDate,
+        maxDate: widget.maxDate,
+        locale: widget.locale,
+        monthsToShow: widget.monthsToShow,
+      ),
+    ).whenComplete(() {
+      if (mounted) _fieldFocusNode.unfocus();
+    });
   }
 
   void _previousMonth() {
@@ -320,177 +950,591 @@ class _KasyDatePickerState extends State<KasyDatePicker>
 
   @override
   Widget build(BuildContext context) {
-    return TapRegion(
-      groupId: _tapGroupId,
-      child: OverlayPortal(
-        controller: _portalController,
-        overlayChildBuilder: _buildOverlay,
-        child: CompositedTransformTarget(
-          link: _layerLink,
-          child: GestureDetector(
-            onTap: _toggleCalendar,
-            child: _buildField(context),
-          ),
+    // For popover presentation, wrap with OverlayPortal.
+    // For dialog/bottomSheet, just the field — no overlay portal needed.
+    if (widget.presentation == KasyDatePickerPresentation.popover) {
+      return TapRegion(
+        groupId: _tapGroupId,
+        child: OverlayPortal(
+          controller: _portalController,
+          overlayChildBuilder: _buildOverlay,
+          child: _buildField(context),
         ),
-      ),
-    );
+      );
+    }
+
+    return _buildField(context);
   }
 
   // ── DateField trigger ──────────────────────────────────────────────────────
+  //
+  // Label and footer (description / errorText) are rendered HERE — not passed
+  // into KasyTextField — so the CompositedTransformTarget can wrap only the
+  // KasyTextField's field rectangle. This way the popover anchors to the
+  // input box itself, not to the full widget area (which would push the
+  // calendar below the helper text).
+  //
+  // Visual styling for label/footer mirrors KasyTextField's own rendering so
+  // the trigger keeps looking like any other input in the kit.
 
   Widget _buildField(BuildContext context) {
     final KasyColors c = context.colors;
-    final DateTime? date = widget.value;
-    final bool hasDate = date != null;
+    final bool isDisabled = !widget.enabled;
+    final bool hasErrorText =
+        widget.errorText != null && widget.errorText!.isNotEmpty;
+    final bool hasInvalidState = widget.isInvalid || hasErrorText;
+    final String? footerText =
+        hasErrorText ? widget.errorText : widget.description;
+    final Color labelColor = hasInvalidState ? c.error : c.fieldLabel;
 
     return Column(
       crossAxisAlignment: CrossAxisAlignment.start,
       mainAxisSize: MainAxisSize.min,
       children: [
-        if (widget.label != null) ...[
-          Text(
-            widget.label!,
-            style: context.textTheme.labelLarge?.copyWith(
-              color: c.onSurface,
-              fontWeight: FontWeight.w500,
-              fontSize: 14,
-            ),
-          ),
-          // 4px gap between label and field — per Figma spec.
-          const SizedBox(height: 4),
-        ],
-        AnimatedContainer(
-          duration: const Duration(milliseconds: 150),
-          // Field height: 36px — per Figma spec (dimensions/spacing/9).
-          height: 36,
-          decoration: BoxDecoration(
-            color: c.surface,
-            // 12px radius — per Figma spec (field/radius: 12).
-            borderRadius: BorderRadius.circular(KasyRadius.md),
-            // Border is always 1px transparent — the focus ring uses
-            // box-shadow spread (not border-width) so layout never shifts.
-            border: Border.all(color: Colors.transparent),
-            // Open: solid 2px primary ring only (no field shadows while
-            // focused — matches Figma focus-ring-field token).
-            // Closed: three-layer depth shadow only (no ring).
-            boxShadow: _isOpen
-                ? [
-                    BoxShadow(
-                      color: c.primary,
-                      spreadRadius: 2,
-                    ),
-                  ]
-                : _kFieldShadows,
-          ),
-          child: Row(
-            children: [
-              // 12px left padding — per Figma spec (dimensions/spacing/3).
-              const SizedBox(width: 12),
-              Expanded(
-                child: Text(
-                  hasDate ? _formatDate(date) : widget.placeholder,
-                  style: context.textTheme.labelLarge?.copyWith(
-                    color: hasDate ? c.onSurface : c.muted,
-                    fontWeight:
-                        hasDate ? FontWeight.w500 : FontWeight.w400,
-                    fontSize: 14,
+        if (widget.label != null && widget.label!.trim().isNotEmpty) ...[
+          Padding(
+            padding: const EdgeInsets.only(left: KasySpacing.sm - 2),
+            child: Row(
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                Text(
+                  widget.label!,
+                  style: context.textTheme.bodyMedium?.copyWith(
+                    color: isDisabled
+                        ? labelColor.withValues(alpha: 0.46)
+                        : labelColor,
+                    fontWeight: FontWeight.w500,
                   ),
                 ),
-              ),
-              // Calendar icon suffix — 12px padding per Figma spec.
-              SizedBox(
-                width: 40,
-                height: 36,
-                child: Center(
-                  child: Opacity(
-                    opacity: widget.enabled ? 1.0 : 0.4,
-                    child: Icon(
-                      KasyIcons.calendar,
-                      size: 16,
-                      color: c.muted,
+                if (widget.showRequiredIndicator)
+                  Text(
+                    ' *',
+                    style: context.textTheme.bodyMedium?.copyWith(
+                      color: c.error,
+                      fontWeight: FontWeight.w500,
                     ),
                   ),
+              ],
+            ),
+          ),
+          const SizedBox(height: KasySpacing.xs),
+        ],
+        // Only this rectangle is the popover anchor — label and footer are
+        // siblings, so they don't shift the calendar's open position.
+        CompositedTransformTarget(
+          link: _layerLink,
+          child: MouseRegion(
+            // The trigger looks like a text input but BEHAVES like a button —
+            // override the I-beam cursor that the inner [TextField] would
+            // otherwise show on web/desktop. The IgnorePointer below already
+            // blocks taps from reaching the field, so the GestureDetector
+            // wrapping us owns the click.
+            cursor: widget.enabled
+                ? SystemMouseCursors.click
+                : SystemMouseCursors.basic,
+            child: GestureDetector(
+              behavior: HitTestBehavior.opaque,
+              onTap: _toggleCalendar,
+              child: IgnorePointer(
+                child: KasyTextField(
+                  key: _fieldKey,
+                  controller: _displayController,
+                  focusNode: _fieldFocusNode,
+                  readOnly: true,
+                  enabled: widget.enabled,
+                  hint: _resolvedPlaceholder,
+                  isInvalid: hasInvalidState,
+                  variant: widget.variant,
+                  focusBorder: widget.focusBorder,
+                  // No caret, no selection handles, no "blue text" when the
+                  // trigger is focused while the calendar is open — keeps the
+                  // field reading as a button, not an editable input.
+                  enableInteractiveSelection: false,
+                  suffix:
+                      widget.showSuffix ? const Icon(KasyIcons.calendar) : null,
                 ),
               ),
-            ],
+            ),
           ),
         ),
+        if (footerText != null) ...[
+          const SizedBox(height: KasySpacing.xs),
+          Padding(
+            padding: const EdgeInsets.symmetric(
+              horizontal: KasySpacing.sm - 2,
+            ),
+            child: Text(
+              footerText,
+              style: context.textTheme.bodySmall?.copyWith(
+                color: (hasErrorText ? c.error : c.muted).withValues(
+                  // Match KasyTextField's disabled description fade (0.34)
+                  // so the helper text dims along with the field.
+                  alpha: isDisabled ? 0.34 : 1,
+                ),
+              ),
+            ),
+          ),
+        ],
       ],
     );
   }
 
-  // ── Calendar overlay ───────────────────────────────────────────────────────
+  // ── Calendar overlay (popover only) ───────────────────────────────────────
 
   Widget _buildOverlay(BuildContext context) {
+    // Same barrier tone as KasyDialog so the popover backdrop matches the
+    // dialog/bottom-sheet behavior (the field "lifts" above a dimmed scrim).
+    final bool dark = Theme.of(context).brightness == Brightness.dark;
+    final Color barrierColor = Colors.black.withValues(
+      alpha: dark ? 0.58 : 0.42,
+    );
+
     return TapRegion(
       groupId: _tapGroupId,
       onTapOutside: (_) => _close(),
-      child: CompositedTransformFollower(
-        link: _layerLink,
-        targetAnchor: Alignment.bottomLeft,
-        // 8px gap between field bottom and calendar top — per Figma spec.
-        offset: const Offset(0, 8),
-        child: Align(
-          alignment: Alignment.topLeft,
-          child: FadeTransition(
-            opacity: _fadeAnim,
-            child: ScaleTransition(
-              scale: _scaleAnim,
-              alignment: Alignment.topCenter,
-              child: _CalendarPanel(
-                viewMonth: _viewMonth,
-                selectedDate: widget.value,
-                onDateSelected: _selectDate,
-                onPreviousMonth: _previousMonth,
-                onNextMonth: _nextMonth,
-                minDate: widget.minDate,
-                maxDate: widget.maxDate,
+      child: Stack(
+        children: [
+          // Dimmed backdrop — fades in/out with the calendar. Suppressed when
+          // [showBarrier] is false so the popover floats over the page like a
+          // tooltip; tap-outside still closes via the surrounding TapRegion.
+          if (widget.showBarrier)
+            Positioned.fill(
+              child: FadeTransition(
+                opacity: _fadeAnim,
+                child: GestureDetector(
+                  behavior: HitTestBehavior.opaque,
+                  onTap: _close,
+                  child: ColoredBox(color: barrierColor),
+                ),
+              ),
+            ),
+          // Smart positioning: anchor the panel BELOW the field by default,
+          // or ABOVE it when there isn't enough room below (see _open()).
+          CompositedTransformFollower(
+            link: _layerLink,
+            targetAnchor:
+                _openUp ? Alignment.topLeft : Alignment.bottomLeft,
+            followerAnchor:
+                _openUp ? Alignment.bottomLeft : Alignment.topLeft,
+            // 8px gap between trigger edge and calendar — per Figma spec.
+            offset: _openUp ? const Offset(0, -8) : const Offset(0, 8),
+            child: FadeTransition(
+              opacity: _fadeAnim,
+              child: ScaleTransition(
+                scale: _scaleAnim,
+                // Grow from the edge closest to the trigger so the open
+                // animation reads correctly in both directions.
+                alignment:
+                    _openUp ? Alignment.bottomCenter : Alignment.topCenter,
+                child: _CalendarPanel(
+                  calendarWidth: _calendarWidth,
+                  viewMonth: _viewMonth,
+                  range: _effectiveRange,
+                  monthsToShow: widget.monthsToShow,
+                  onDateSelected: _selectDate,
+                  onPreviousMonth: _previousMonth,
+                  onNextMonth: _nextMonth,
+                  onYearSelected: (year) => setState(() {
+                    _viewMonth = DateTime(year, _viewMonth.month);
+                  }),
+                  minDate: widget.minDate,
+                  maxDate: widget.maxDate,
+                  locale: widget.locale,
+                ),
               ),
             ),
           ),
-        ),
+        ],
       ),
     );
   }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// _CalendarPanel
+// _BottomSheetContent — KasyBottomSheet-style wrapper for the calendar
 // ─────────────────────────────────────────────────────────────────────────────
 
-class _CalendarPanel extends StatelessWidget {
+class _BottomSheetContent extends StatefulWidget {
+  const _BottomSheetContent({
+    required this.initialViewMonth,
+    required this.initialRange,
+    required this.selectionMode,
+    this.onChanged,
+    this.onRangeChanged,
+    this.minDate,
+    this.maxDate,
+    this.locale = KasyDatePickerLocale.en,
+    this.monthsToShow,
+  });
+
+  final DateTime initialViewMonth;
+
+  /// Initial selection — used as a seed for the local state inside the sheet
+  /// (subsequent taps update that state and notify the parent through the
+  /// callbacks below).
+  final KasyDateRange? initialRange;
+
+  final KasyDateSelectionMode selectionMode;
+  final ValueChanged<DateTime>? onChanged;
+  final ValueChanged<KasyDateRange>? onRangeChanged;
+  final DateTime? minDate;
+  final DateTime? maxDate;
+  final KasyDatePickerLocale locale;
+  final int? monthsToShow;
+
+  @override
+  State<_BottomSheetContent> createState() => _BottomSheetContentState();
+}
+
+class _BottomSheetContentState extends State<_BottomSheetContent> {
+  late DateTime _viewMonth;
+
+  KasyDateRange? _range;
+
+  @override
+  void initState() {
+    super.initState();
+    _viewMonth = widget.initialViewMonth;
+    _range = widget.initialRange;
+  }
+
+  void _previousMonth() {
+    setState(() {
+      _viewMonth = DateTime(
+        _viewMonth.month == 1 ? _viewMonth.year - 1 : _viewMonth.year,
+        _viewMonth.month == 1 ? 12 : _viewMonth.month - 1,
+      );
+    });
+  }
+
+  void _nextMonth() {
+    setState(() {
+      _viewMonth = DateTime(
+        _viewMonth.month == 12 ? _viewMonth.year + 1 : _viewMonth.year,
+        _viewMonth.month == 12 ? 1 : _viewMonth.month + 1,
+      );
+    });
+  }
+
+  /// Handles a day tap inside the sheet. In range mode, paints the start
+  /// endpoint immediately on the first tap (so the user gets feedback), and
+  /// closes the sheet only after the end is picked. Single mode closes on
+  /// the first tap.
+  void _onDateTapped(DateTime date) {
+    if (widget.selectionMode == KasyDateSelectionMode.range) {
+      final KasyDateRange current = _range ?? const KasyDateRange();
+      final bool isFirstPick = current.start == null ||
+          current.isComplete ||
+          date.isBefore(current.start!);
+      if (isFirstPick) {
+        final KasyDateRange started = KasyDateRange(start: date);
+        setState(() => _range = started);
+        widget.onRangeChanged?.call(started);
+        return;
+      }
+      final KasyDateRange completed =
+          KasyDateRange(start: current.start, end: date);
+      setState(() => _range = completed);
+      widget.onRangeChanged?.call(completed);
+      Navigator.of(context).pop();
+      return;
+    }
+    widget.onChanged?.call(date);
+    Navigator.of(context).pop();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyColors c = context.colors;
+    final double bottomInset = MediaQuery.paddingOf(context).bottom;
+
+    return Material(
+      color: c.surface,
+      borderRadius: const BorderRadius.vertical(
+        top: Radius.circular(KasyRadius.xl),
+      ),
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          // Drag handle — matches KasyBottomSheet._DragHandle exactly.
+          Padding(
+            padding: const EdgeInsets.only(top: KasySpacing.smd),
+            child: Center(
+              child: Container(
+                width: 36,
+                height: 4,
+                decoration: BoxDecoration(
+                  color: c.outline.withValues(alpha: 0.35),
+                  borderRadius: BorderRadius.circular(KasyRadius.full),
+                ),
+              ),
+            ),
+          ),
+          // Calendar content — no card decoration (sheet surface is already white).
+          Padding(
+            padding: EdgeInsets.only(
+              left: KasySpacing.md,
+              right: KasySpacing.md,
+              top: KasySpacing.sm,
+              bottom: KasySpacing.md + bottomInset,
+            ),
+            child: _CalendarPanel(
+              bare: true,
+              viewMonth: _viewMonth,
+              range: _range,
+              monthsToShow: widget.monthsToShow,
+              onDateSelected: _onDateTapped,
+              onPreviousMonth: _previousMonth,
+              onNextMonth: _nextMonth,
+              onYearSelected: (year) => setState(() {
+                _viewMonth = DateTime(year, _viewMonth.month);
+              }),
+              minDate: widget.minDate,
+              maxDate: widget.maxDate,
+              locale: widget.locale,
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// _CalendarPanel — now StatefulWidget to manage view mode (month / year)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class _CalendarPanel extends StatefulWidget {
   const _CalendarPanel({
     required this.viewMonth,
-    required this.selectedDate,
+    required this.range,
     required this.onDateSelected,
     required this.onPreviousMonth,
     required this.onNextMonth,
+    required this.onYearSelected,
+    this.calendarWidth,
     this.minDate,
     this.maxDate,
+    this.bare = false,
+    this.locale = KasyDatePickerLocale.en,
+    this.monthsToShow,
   });
 
+  /// Number of months to render side-by-side. Defaults to 1 — multi-month
+  /// is opt-in via [KasyDatePicker.monthsToShow].
+  final int? monthsToShow;
+
   final DateTime viewMonth;
-  final DateTime? selectedDate;
+
+  /// Current selection. In single-date mode, the parent wraps the picked
+  /// value in a [KasyDateRange] with `start == end` so the same widget tree
+  /// renders both modes (single = single circle; range = start + bar + end).
+  final KasyDateRange? range;
   final ValueChanged<DateTime> onDateSelected;
   final VoidCallback onPreviousMonth;
   final VoidCallback onNextMonth;
+
+  /// Called when the user selects a year in year-picker mode.
+  final ValueChanged<int> onYearSelected;
+
+  /// Width of the panel. Defaults to [double.infinity] when null.
+  final double? calendarWidth;
   final DateTime? minDate;
   final DateTime? maxDate;
 
+  /// When true, skips the card decoration (no Material wrapper, no
+  /// background, no shadow). Use when the parent (e.g. bottom sheet)
+  /// already provides the surface background.
+  final bool bare;
+
+  /// Calendar display locale — month names, weekday labels, week start day.
+  final KasyDatePickerLocale locale;
+
+  @override
+  State<_CalendarPanel> createState() => _CalendarPanelState();
+}
+
+class _CalendarPanelState extends State<_CalendarPanel> {
+  _CalendarViewMode _viewMode = _CalendarViewMode.month;
+
+  /// Resolves the actual number of months to render side by side. Defaults
+  /// to a single month on every platform; the multi-month layout is opt-in
+  /// via [KasyDatePicker.monthsToShow] (1, 2 or 3).
+  int _resolvedMonthCount() =>
+      widget.monthsToShow?.clamp(1, 3) ?? 1;
+
+  Widget _buildContent() {
+    if (_viewMode == _CalendarViewMode.year) {
+      return Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          _CalendarNavRow(
+            viewMonth: widget.viewMonth,
+            viewMode: _viewMode,
+            onToggleMode: _toggleMode,
+            // Arrows disabled in year mode — user picks via the scroll list.
+            onPrevious: null,
+            onNext: null,
+            locale: widget.locale,
+            // Style follows the layout: single-month uses the compact iOS-ish
+            // style (label left, arrows clustered right); multi-month uses
+            // the edge-arrows layout (rendered below as a custom row), so a
+            // single-month panel always gets KasyDatePickerNavStyle.single.
+            style: KasyDatePickerNavStyle.single,
+          ),
+          _YearPickerContent(
+            currentYear: widget.viewMonth.year,
+            onYearSelected: (year) {
+              widget.onYearSelected(year);
+              setState(() => _viewMode = _CalendarViewMode.month);
+            },
+          ),
+        ],
+      );
+    }
+
+    final int months = _resolvedMonthCount();
+
+    return Builder(
+      builder: (context) {
+        if (months == 1) {
+          return Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              _CalendarNavRow(
+                viewMonth: widget.viewMonth,
+                viewMode: _viewMode,
+                onToggleMode: _toggleMode,
+                onPrevious: widget.onPreviousMonth,
+                onNext: widget.onNextMonth,
+                locale: widget.locale,
+                // Style follows the layout: single-month uses the compact iOS-ish
+            // style (label left, arrows clustered right); multi-month uses
+            // the edge-arrows layout (rendered below as a custom row), so a
+            // single-month panel always gets KasyDatePickerNavStyle.single.
+            style: KasyDatePickerNavStyle.single,
+              ),
+              _MonthGrid(
+                viewMonth: widget.viewMonth,
+                range: widget.range,
+                onDateSelected: widget.onDateSelected,
+                minDate: widget.minDate,
+                maxDate: widget.maxDate,
+                locale: widget.locale,
+                // Single-month layout already has the title in the nav row
+                // above, so the grid omits its own header.
+                showHeader: false,
+              ),
+            ],
+          );
+        }
+
+        // Multi-month layout: arrows live on the outer edges, the month
+        // captions sit between them on the same row, and the grids align
+        // perfectly below their captions because both rows share the same
+        // column proportions (an arrow-wide SizedBox + Expanded grids +
+        // arrow-wide SizedBox).
+        const double navArrowWidth = 28;
+        final TextStyle? headerStyle =
+            context.textTheme.labelLarge?.copyWith(
+          color: context.colors.onSurface,
+          fontWeight: FontWeight.w700,
+          fontSize: 14,
+        );
+
+        return Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            SizedBox(
+              height: 56,
+              child: Row(
+                children: [
+                  _NavArrowButton(
+                    icon: KasyIcons.arrowBackIos,
+                    onTap: widget.onPreviousMonth,
+                  ),
+                  for (int i = 0; i < months; i++) ...[
+                    if (i > 0) const SizedBox(width: KasySpacing.lg),
+                    Expanded(
+                      child: Center(
+                        child: Text(
+                          _monthYearLabel(
+                            _shiftMonth(widget.viewMonth, i),
+                            widget.locale,
+                          ),
+                          style: headerStyle,
+                        ),
+                      ),
+                    ),
+                  ],
+                  _NavArrowButton(
+                    icon: KasyIcons.arrowForwardIos,
+                    onTap: widget.onNextMonth,
+                  ),
+                ],
+              ),
+            ),
+            Row(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                const SizedBox(width: navArrowWidth),
+                for (int i = 0; i < months; i++) ...[
+                  if (i > 0) const SizedBox(width: KasySpacing.lg),
+                  Expanded(
+                    child: _MonthGrid(
+                      viewMonth: _shiftMonth(widget.viewMonth, i),
+                      range: widget.range,
+                      onDateSelected: widget.onDateSelected,
+                      minDate: widget.minDate,
+                      maxDate: widget.maxDate,
+                      locale: widget.locale,
+                      // Header lives on the row above, between the arrows.
+                      showHeader: false,
+                    ),
+                  ),
+                ],
+                const SizedBox(width: navArrowWidth),
+              ],
+            ),
+          ],
+        );
+      },
+    );
+  }
+
+  /// Returns [base] shifted forward by [delta] months.
+  DateTime _shiftMonth(DateTime base, int delta) {
+    final int total = base.month - 1 + delta;
+    final int year = base.year + (total ~/ 12);
+    final int month = (total % 12) + 1;
+    return DateTime(year, month);
+  }
+
+  /// Builds the "December 2025" / "diciembre de 2025" caption for a given
+  /// month, respecting the locale's month name list and month/year separator.
+  String _monthYearLabel(DateTime m, KasyDatePickerLocale locale) =>
+      '${locale.monthNames[m.month - 1]}${locale.monthYearSeparator}${m.year}';
+
+  void _toggleMode() {
+    setState(() {
+      _viewMode = _viewMode == _CalendarViewMode.month
+          ? _CalendarViewMode.year
+          : _CalendarViewMode.month;
+    });
+  }
+
   @override
   Widget build(BuildContext context) {
     final KasyColors c = context.colors;
-    final List<_DayData> days = _buildDayGrid(
-      viewMonth,
-      minDate: minDate,
-      maxDate: maxDate,
-    );
+    final Widget content = _buildContent();
+
+    // Bare mode: no card decoration. The parent surface provides the background.
+    if (widget.bare) return content;
 
     return Material(
       color: Colors.transparent,
       child: Container(
-        // Width matches the DateField — 288px per Figma spec.
-        width: 288,
+        width: widget.calendarWidth ?? double.infinity,
         decoration: BoxDecoration(
           color: c.surface,
           // 24px radius — per Figma spec (dimensions/radius/rounded-3xl: 24).
@@ -498,36 +1542,89 @@ class _CalendarPanel extends StatelessWidget {
           boxShadow: _kCalendarShadows,
         ),
         child: Padding(
-          // 16px all sides — per Figma spec (dimensions/spacing/4: 16).
-          padding: const EdgeInsets.all(KasySpacing.md),
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            children: [
-              // Navigation row (month/year + prev/next arrows).
-              _CalendarNavRow(
-                viewMonth: viewMonth,
-                onPrevious: onPreviousMonth,
-                onNext: onNextMonth,
-              ),
-              // Weekday abbreviation headers.
-              const _WeekdayHeaderRow(),
-              // Day grid: 6 rows × 7 columns, 2px gap between rows.
-              for (int row = 0; row < 6; row++) ...[
-                if (row > 0) const SizedBox(height: 2),
-                _DayRow(
-                  days: days.sublist(row * 7, row * 7 + 7),
-                  selectedDate: selectedDate,
-                  onDateSelected: onDateSelected,
-                ),
-              ],
-            ],
+          // Figma: no top padding — nav row provides its own internal spacing.
+          padding: const EdgeInsets.only(
+            left: KasySpacing.md,
+            right: KasySpacing.md,
+            bottom: KasySpacing.md,
           ),
+          child: content,
         ),
       ),
     );
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// _MonthGrid — one month worth of day cells (optionally with month/year header)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class _MonthGrid extends StatelessWidget {
+  const _MonthGrid({
+    required this.viewMonth,
+    required this.range,
+    required this.onDateSelected,
+    required this.locale,
+    required this.showHeader,
+    this.minDate,
+    this.maxDate,
+  });
+
+  final DateTime viewMonth;
+  final KasyDateRange? range;
+  final ValueChanged<DateTime> onDateSelected;
+  final KasyDatePickerLocale locale;
+
+  /// When true, the grid prints its own "December 2025" caption above the
+  /// weekday row. Used in multi-month layouts where the global nav row only
+  /// owns the prev/next arrows and each month labels itself.
+  final bool showHeader;
+
+  final DateTime? minDate;
+  final DateTime? maxDate;
+
+  @override
+  Widget build(BuildContext context) {
+    final List<_DayData> days = _buildDayGrid(
+      viewMonth,
+      minDate: minDate,
+      maxDate: maxDate,
+      weekStartDay: locale.weekStartDay,
+    );
+    final String monthYear =
+        '${locale.monthNames[viewMonth.month - 1]}${locale.monthYearSeparator}${viewMonth.year}';
+
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        if (showHeader)
+          Padding(
+            padding: const EdgeInsets.only(bottom: 4),
+            child: Text(
+              monthYear,
+              style: context.textTheme.labelLarge?.copyWith(
+                color: context.colors.onSurface,
+                fontWeight: FontWeight.w700,
+                fontSize: 14,
+              ),
+            ),
+          ),
+        _WeekdayHeaderRow(locale: locale),
+        // 8px gap between weekday header and first day row — Figma spec.
+        const SizedBox(height: 8),
+        for (int row = 0; row < 6; row++) ...[
+          if (row > 0) const SizedBox(height: 2),
+          _DayRow(
+            days: days.sublist(row * 7, row * 7 + 7),
+            range: range,
+            onDateSelected: onDateSelected,
+          ),
+        ],
+      ],
+    );
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // _CalendarNavRow — Month/year header with prev/next navigation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -535,61 +1632,91 @@ class _CalendarPanel extends StatelessWidget {
 class _CalendarNavRow extends StatelessWidget {
   const _CalendarNavRow({
     required this.viewMonth,
+    required this.viewMode,
+    required this.onToggleMode,
     required this.onPrevious,
     required this.onNext,
+    required this.locale,
+    this.style = KasyDatePickerNavStyle.multi,
   });
 
   final DateTime viewMonth;
-  final VoidCallback onPrevious;
-  final VoidCallback onNext;
+  final _CalendarViewMode viewMode;
+  final VoidCallback onToggleMode;
+
+  /// Null in year mode — arrows render disabled and the user picks the year
+  /// by scrolling the year list.
+  final VoidCallback? onPrevious;
+  final VoidCallback? onNext;
+  final KasyDatePickerLocale locale;
+  final KasyDatePickerNavStyle style;
 
   @override
   Widget build(BuildContext context) {
     final KasyColors c = context.colors;
+    final String monthYear =
+        '${locale.monthNames[viewMonth.month - 1]}${locale.monthYearSeparator}${viewMonth.year}';
+
+    // Month/year text + chevron used to toggle the year picker — shared by
+    // both nav styles, only its position in the row changes.
+    final Widget monthLabel = GestureDetector(
+      onTap: onToggleMode,
+      behavior: HitTestBehavior.opaque,
+      child: Row(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Text(
+            monthYear,
+            style: context.textTheme.labelLarge?.copyWith(
+              color: c.onSurface,
+              fontWeight: FontWeight.w700,
+              fontSize: 14,
+            ),
+          ),
+          const SizedBox(width: 4),
+          Icon(
+            viewMode == _CalendarViewMode.month
+                ? KasyIcons.chevronRight
+                : KasyIcons.chevronDown,
+            size: 18,
+            weight: 700,
+            color: c.primary,
+          ),
+        ],
+      ),
+    );
 
+    // Multi style: ‹  December 2025  ›  (arrows on the edges, label centered)
+    if (style == KasyDatePickerNavStyle.multi) {
+      return SizedBox(
+        height: 56,
+        child: Row(
+          children: [
+            _NavArrowButton(
+              icon: KasyIcons.arrowBackIos,
+              onTap: onPrevious,
+            ),
+            Expanded(child: Center(child: monthLabel)),
+            _NavArrowButton(
+              icon: KasyIcons.arrowForwardIos,
+              onTap: onNext,
+            ),
+          ],
+        ),
+      );
+    }
+
+    // Single style: December 2025 …  ‹ ›  (label left, arrows clustered right)
     return SizedBox(
-      // Navigation row height: 56px (16px padding top+bottom) — Figma spec.
       height: 56,
       child: Row(
         children: [
-          // Month + Year text.
-          Expanded(
-            child: Row(
-              children: [
-                Text(
-                  _kMonthNames[viewMonth.month - 1],
-                  style: context.textTheme.labelLarge?.copyWith(
-                    color: c.onSurface,
-                    fontWeight: FontWeight.w500,
-                    fontSize: 14,
-                  ),
-                ),
-                const SizedBox(width: 6),
-                Text(
-                  viewMonth.year.toString(),
-                  style: context.textTheme.labelLarge?.copyWith(
-                    color: c.onSurface,
-                    fontWeight: FontWeight.w500,
-                    fontSize: 14,
-                  ),
-                ),
-                const SizedBox(width: 4),
-                // Expand chevron (right arrow, 12px) — indicates year picker.
-                Icon(
-                  KasyIcons.chevronRight,
-                  size: 12,
-                  color: c.muted,
-                ),
-              ],
-            ),
-          ),
-          // Previous-month arrow button.
+          Expanded(child: monthLabel),
           _NavArrowButton(
             icon: KasyIcons.arrowBackIos,
             onTap: onPrevious,
           ),
-          const SizedBox(width: 4),
-          // Next-month arrow button.
+          const SizedBox(width: 12),
           _NavArrowButton(
             icon: KasyIcons.arrowForwardIos,
             onTap: onNext,
@@ -601,49 +1728,175 @@ class _CalendarNavRow extends StatelessWidget {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// _NavArrowButton — 24×24 rounded navigation arrow
+// _NavArrowButton — 28×28 rounded navigation arrow
 // ─────────────────────────────────────────────────────────────────────────────
 
-class _NavArrowButton extends StatefulWidget {
+class _NavArrowButton extends StatelessWidget {
   const _NavArrowButton({required this.icon, required this.onTap});
 
   final IconData icon;
-  final VoidCallback onTap;
+
+  /// When null the button is rendered disabled: muted icon color, no hover
+  /// affordance, no tap action. Used in the year picker mode where year
+  /// selection happens via the scrollable list, not the arrows.
+  final VoidCallback? onTap;
 
   @override
-  State<_NavArrowButton> createState() => _NavArrowButtonState();
+  Widget build(BuildContext context) {
+    final KasyColors c = context.colors;
+    final bool disabled = onTap == null;
+
+    final Widget body = SizedBox(
+      // Button size: 28×28 — per Figma spec (20px icon + 4px padding each side).
+      width: 28,
+      height: 28,
+      child: Center(
+        child: Icon(
+          icon,
+          size: 20,
+          weight: 700,
+          color: disabled ? c.muted.withValues(alpha: 0.45) : c.primary,
+        ),
+      ),
+    );
+
+    if (disabled) return body;
+
+    // 4px padding → 6px radius — per Figma (rounded-md: 6).
+    return KasyHover(
+      onTap: onTap!,
+      borderRadius: BorderRadius.circular(6),
+      child: body,
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// _YearPickerContent — scrollable 3-column year list (1900–2099)
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Sized to match the month grid's intrinsic height (weekday header 36 + 8 gap
+// + 6 day rows × 36 + 5 inter-row gaps × 2 = 270) so the panel height stays
+// constant when toggling between month and year modes.
+
+class _YearPickerContent extends StatefulWidget {
+  const _YearPickerContent({
+    required this.currentYear,
+    required this.onYearSelected,
+  });
+
+  /// The year shown in the nav row (widget.viewMonth.year).
+  final int currentYear;
+
+  /// Called when the user taps a year cell.
+  final ValueChanged<int> onYearSelected;
+
+  @override
+  State<_YearPickerContent> createState() => _YearPickerContentState();
 }
 
-class _NavArrowButtonState extends State<_NavArrowButton> {
-  bool _hovered = false;
+class _YearPickerContentState extends State<_YearPickerContent> {
+  static const int _kFirstYear = 1900;
+  static const int _kLastYear = 2099;
+  static const int _kCols = 3;
+  static const double _kRowHeight = 36;
+  static const double _kViewportHeight = 270;
+
+  late final ScrollController _scrollController;
+
+  @override
+  void initState() {
+    super.initState();
+    // Center the current year's row on first paint.
+    final int index = widget.currentYear - _kFirstYear;
+    final int row = index ~/ _kCols;
+    final double targetOffset =
+        (row * _kRowHeight) - (_kViewportHeight - _kRowHeight) / 2;
+    final int totalRows =
+        ((_kLastYear - _kFirstYear + 1) / _kCols).ceil();
+    final double maxOffset =
+        (totalRows * _kRowHeight) - _kViewportHeight;
+    final double clampedOffset = targetOffset.clamp(0.0, maxOffset);
+    _scrollController = ScrollController(initialScrollOffset: clampedOffset);
+  }
+
+  @override
+  void dispose() {
+    _scrollController.dispose();
+    super.dispose();
+  }
 
   @override
   Widget build(BuildContext context) {
     final KasyColors c = context.colors;
+    const int totalYears = _kLastYear - _kFirstYear + 1;
+    final int rowCount = (totalYears / _kCols).ceil();
 
-    return GestureDetector(
-      onTap: widget.onTap,
-      onTapDown: (_) => setState(() => _hovered = true),
-      onTapUp: (_) => setState(() => _hovered = false),
-      onTapCancel: () => setState(() => _hovered = false),
-      child: AnimatedContainer(
-        duration: const Duration(milliseconds: 100),
-        // Button size: 24×24 — per Figma spec.
-        width: 24,
-        height: 24,
-        // 4px padding → 6px radius — per Figma (rounded-md: 6).
-        decoration: BoxDecoration(
-          color: _hovered ? c.avatarFallbackFill : Colors.transparent,
-          borderRadius: BorderRadius.circular(6),
-        ),
-        child: Center(
-          child: Icon(
-            widget.icon,
-            size: 16,
-            color: c.onSurface,
-          ),
+    return Container(
+      height: _kViewportHeight,
+      decoration: BoxDecoration(
+        borderRadius: BorderRadius.circular(KasyRadius.md),
+        border: Border.all(
+          color: c.outline.withValues(alpha: 0.35),
         ),
       ),
+      clipBehavior: Clip.antiAlias,
+      child: ListView.builder(
+        controller: _scrollController,
+        padding: const EdgeInsets.symmetric(vertical: 8),
+        itemCount: rowCount,
+        itemExtent: _kRowHeight,
+        itemBuilder: (context, row) {
+          return Row(
+            children: List.generate(_kCols, (col) {
+              final int index = row * _kCols + col;
+              if (index >= totalYears) {
+                return const Expanded(child: SizedBox.shrink());
+              }
+              final int year = _kFirstYear + index;
+              final bool isCurrent = year == widget.currentYear;
+
+              final BorderRadius yearRadius =
+                  BorderRadius.circular(KasyRadius.xl);
+
+              return Expanded(
+                child: Padding(
+                  padding: const EdgeInsets.symmetric(
+                    horizontal: 4,
+                    vertical: 2,
+                  ),
+                  child: KasyHover(
+                    onTap: () => widget.onYearSelected(year),
+                    borderRadius: yearRadius,
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        color: isCurrent ? c.primary : Colors.transparent,
+                        borderRadius: yearRadius,
+                        // Same subtle lift as the selected day cell so the
+                        // current-year pill reads as elevated.
+                        boxShadow:
+                            isCurrent ? [KasyShadows.component(context)] : null,
+                      ),
+                      child: Center(
+                        child: Text(
+                          year.toString(),
+                          style: context.textTheme.labelLarge?.copyWith(
+                            color: isCurrent
+                                ? const Color(0xFFFCFCFC)
+                                : c.onSurface,
+                            fontWeight: FontWeight.w600,
+                            fontSize: 14,
+                          ),
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              );
+            }),
+          );
+        },
+      ),
     );
   }
 }
@@ -653,14 +1906,16 @@ class _NavArrowButtonState extends State<_NavArrowButton> {
 // ─────────────────────────────────────────────────────────────────────────────
 
 class _WeekdayHeaderRow extends StatelessWidget {
-  const _WeekdayHeaderRow();
+  const _WeekdayHeaderRow({required this.locale});
+
+  final KasyDatePickerLocale locale;
 
   @override
   Widget build(BuildContext context) {
     final KasyColors c = context.colors;
 
     return Row(
-      children: _kWeekdayAbbreviations.map((abbr) {
+      children: locale.weekdayAbbreviations.map((abbr) {
         return Expanded(
           child: SizedBox(
             height: 36,
@@ -668,10 +1923,10 @@ class _WeekdayHeaderRow extends StatelessWidget {
               child: Text(
                 abbr,
                 style: context.textTheme.labelMedium?.copyWith(
-                  // 12px/w500 — per Figma spec (Body xs medium: text-xs).
                   color: c.muted,
-                  fontSize: 12,
-                  fontWeight: FontWeight.w500,
+                  fontSize: 14,
+                  fontWeight: FontWeight.w600,
+                  height: 1.43,
                 ),
               ),
             ),
@@ -689,27 +1944,24 @@ class _WeekdayHeaderRow extends StatelessWidget {
 class _DayRow extends StatelessWidget {
   const _DayRow({
     required this.days,
-    required this.selectedDate,
+    required this.range,
     required this.onDateSelected,
   });
 
   final List<_DayData> days;
-  final DateTime? selectedDate;
+  final KasyDateRange? range;
   final ValueChanged<DateTime> onDateSelected;
 
   @override
   Widget build(BuildContext context) {
     return Row(
       children: days.map((day) {
-        final bool isSelected =
-            selectedDate != null && _isSameDay(day.date, selectedDate!);
+        final _RangePosition position = _positionFor(day.date, range);
         return Expanded(
           child: _DayCell(
             data: day,
-            isSelected: isSelected,
-            onTap: (day.isDisabled || !day.isCurrentMonth && day.isDisabled)
-                ? null
-                : () => onDateSelected(day.date),
+            position: position,
+            onTap: day.isDisabled ? null : () => onDateSelected(day.date),
           ),
         );
       }).toList(),
@@ -721,114 +1973,201 @@ class _DayRow extends StatelessWidget {
 // _DayCell — individual calendar day
 // ─────────────────────────────────────────────────────────────────────────────
 
-class _DayCell extends StatefulWidget {
+class _DayCell extends StatelessWidget {
   const _DayCell({
     required this.data,
-    required this.isSelected,
+    required this.position,
     required this.onTap,
   });
 
   final _DayData data;
-  final bool isSelected;
+
+  /// Where this day sits relative to the current selection. In single-date
+  /// mode the picker wraps the [value] in a range with `start == end`, so
+  /// the same component handles both modes.
+  final _RangePosition position;
   final VoidCallback? onTap;
 
-  @override
-  State<_DayCell> createState() => _DayCellState();
-}
+  bool get _isEndpoint =>
+      position == _RangePosition.start ||
+      position == _RangePosition.end ||
+      position == _RangePosition.single;
 
-class _DayCellState extends State<_DayCell> {
-  bool _pressed = false;
+  bool get _isInRange => position != _RangePosition.none;
 
   @override
   Widget build(BuildContext context) {
     final KasyColors c = context.colors;
-    final _DayData day = widget.data;
-
-    // ── Color determination ────────────────────────────────────────────────
+    final BorderRadius cellRadius = BorderRadius.circular(KasyRadius.xl);
 
+    // ── Text color ─────────────────────────────────────────────────────────
     final Color textColor;
-    final Color? bgColor;
-
-    if (widget.isSelected) {
-      textColor = const Color(0xFFFCFCFC); // accent/accent-foreground
-      bgColor = c.primary;
-    } else if (day.isToday) {
-      textColor = c.primary; // accent/accent-soft-foreground
-      bgColor = _pressed ? c.avatarFallbackFill : null;
-    } else if (!day.isCurrentMonth) {
-      textColor = c.muted; // out-of-month
-      bgColor = _pressed ? c.avatarFallbackFill : null;
-    } else if (day.isDisabled) {
+    if (_isEndpoint) {
+      textColor = const Color(0xFFFCFCFC); // on primary
+    } else if (position == _RangePosition.middle) {
+      textColor = c.onSurface; // dark over soft tint
+    } else if (data.isToday) {
+      textColor = c.primary;
+    } else if (!data.isCurrentMonth || data.isDisabled) {
       textColor = c.muted;
-      bgColor = null;
     } else {
-      textColor = c.onSurface; // default
-      bgColor = _pressed ? c.avatarFallbackFill : null;
+      textColor = c.onSurface;
     }
 
-    // ── Today indicator dot ────────────────────────────────────────────────
-    // 3px dot, positioned 4px from bottom — Figma spec.
-    // Hidden when the day is selected (blue circle already communicates
-    // selection clearly — dot would be redundant).
-    final bool showDot = day.isToday && !widget.isSelected;
-    final Color dotColor = widget.isSelected
-        ? const Color(0xFFFCFCFC)
-        : c.muted;
-
-    // ── Opacity ────────────────────────────────────────────────────────────
-    // Out-of-month and disabled cells use 50% opacity — Figma spec.
+    // ── Today dot ──────────────────────────────────────────────────────────
+    final bool showDot = data.isToday;
+    final Color dotColor = _isEndpoint ? const Color(0xFFFCFCFC) : c.muted;
+
+    // ── Out-of-month / disabled fade ───────────────────────────────────────
     final double opacity =
-        (!day.isCurrentMonth || day.isDisabled) ? 0.5 : 1.0;
+        (!data.isCurrentMonth || data.isDisabled) ? 0.5 : 1.0;
+
+    // ── Range bar (only for start/middle/end — single is just the circle) ─
+    // The bar is the soft primary tint that connects start ↔ middle ↔ end.
+    //
+    // Geometry trick: instead of building the bar from a half-column
+    // rectangle PLUS a pill behind the endpoint (which leaves visible square
+    // corners above/below the ball), we use a single padded ColoredBox per
+    // cell whose LEFT/RIGHT inset is exactly the column's "side gutter"
+    // (column width minus 36, divided by two). The bar then starts/ends at
+    // the ball's vertical tangent and carries a radius of 18 (= ball radius)
+    // on the side touching the endpoint — that radius matches the ball's
+    // curvature exactly, so the bar visually "hugs" the primary circle with
+    // no stray corners on top or bottom.
+    Widget? rangeBar;
+    if (_isInRange && position != _RangePosition.single) {
+      final Color barColor = c.primary.withValues(alpha: 0.10);
+      const double ballSize = 36;
+      const Radius ballR = Radius.circular(ballSize / 2);
+
+      rangeBar = LayoutBuilder(
+        builder: (context, constraints) {
+          // Side gutter = the empty space between the column's edge and the
+          // endpoint circle. Clamped to 0 in case the cell is smaller than
+          // the ball (defensive — shouldn't happen in practice).
+          final double sideGutter =
+              ((constraints.maxWidth - ballSize) / 2).clamp(0.0, double.infinity);
+
+          switch (position) {
+            case _RangePosition.start:
+              return Padding(
+                padding: EdgeInsets.only(left: sideGutter),
+                child: DecoratedBox(
+                  decoration: BoxDecoration(
+                    color: barColor,
+                    borderRadius: const BorderRadius.only(
+                      topLeft: ballR,
+                      bottomLeft: ballR,
+                    ),
+                  ),
+                ),
+              );
+            case _RangePosition.end:
+              return Padding(
+                padding: EdgeInsets.only(right: sideGutter),
+                child: DecoratedBox(
+                  decoration: BoxDecoration(
+                    color: barColor,
+                    borderRadius: const BorderRadius.only(
+                      topRight: ballR,
+                      bottomRight: ballR,
+                    ),
+                  ),
+                ),
+              );
+            case _RangePosition.middle:
+              return ColoredBox(color: barColor);
+            case _RangePosition.single:
+            case _RangePosition.none:
+              return const SizedBox.shrink();
+          }
+        },
+      );
+    }
 
-    final Widget cell = AnimatedContainer(
-      duration: const Duration(milliseconds: 100),
-      // Cell size: 36×36 — Figma spec (dimensions/spacing/9: 36).
-      width: 36,
-      height: 36,
-      decoration: BoxDecoration(
-        color: bgColor,
-        // 24px radius → pill/circle — Figma spec (rounded-3xl: 24).
-        borderRadius: BorderRadius.circular(KasyRadius.xl),
+    // ── Endpoint circle (start / end / single) ─────────────────────────────
+    Widget? endpoint;
+    if (_isEndpoint) {
+      endpoint = Container(
+        width: 36,
+        height: 36,
+        decoration: BoxDecoration(
+          color: c.primary,
+          borderRadius: cellRadius,
+          boxShadow: [KasyShadows.component(context)],
+        ),
+      );
+    }
+
+    final Widget textAndDot = Stack(
+      alignment: Alignment.center,
+      children: [
+        Text(
+          data.date.day.toString(),
+          style: context.textTheme.labelLarge?.copyWith(
+            color: textColor,
+            fontWeight: FontWeight.w600,
+            fontSize: 14,
+            height: 1.43,
+          ),
+        ),
+        if (showDot)
+          Positioned(
+            bottom: 4,
+            child: Container(
+              width: 3,
+              height: 3,
+              decoration: BoxDecoration(
+                color: dotColor,
+                borderRadius: BorderRadius.circular(12),
+              ),
+            ),
+          ),
+      ],
+    );
+
+    // Inner cell content: endpoint circle (if any) + text. Stays 36×36 so it
+    // can be wrapped by a circular hover overlay.
+    final Widget cellInner = Stack(
+      alignment: Alignment.center,
+      children: [
+        if (endpoint != null) endpoint,
+        textAndDot,
+      ],
+    );
+
+    // The interactive bit: always a 36×36 centered circle. Hover/press
+    // feedback from [KasyHover] therefore always renders as a perfect bola,
+    // never an oval or square — even on range cells where the background
+    // bar extends past the circle.
+    final Widget interactive = Center(
+      child: SizedBox(
+        width: 36,
+        height: 36,
+        child: onTap == null
+            ? cellInner
+            : KasyHover(
+                onTap: onTap!,
+                borderRadius: cellRadius,
+                child: cellInner,
+              ),
       ),
+    );
+
+    final Widget composed = SizedBox(
+      height: 36,
       child: Stack(
         alignment: Alignment.center,
         children: [
-          // Day number.
-          Text(
-            day.date.day.toString(),
-            style: context.textTheme.labelLarge?.copyWith(
-              color: textColor,
-              fontWeight: FontWeight.w500,
-              fontSize: 14,
-            ),
-          ),
-          // Today indicator dot — 3px circle at bottom center.
-          if (showDot)
-            Positioned(
-              bottom: 4,
-              child: Container(
-                width: 3,
-                height: 3,
-                decoration: BoxDecoration(
-                  color: dotColor,
-                  borderRadius: BorderRadius.circular(12),
-                ),
-              ),
-            ),
+          // Range bar sits behind everything else and is not interactive on
+          // its own (the 36×36 [interactive] above owns the gesture region).
+          if (rangeBar != null) Positioned.fill(child: rangeBar),
+          interactive,
         ],
       ),
     );
 
-    if (widget.onTap == null) {
-      return Opacity(opacity: opacity, child: Center(child: cell));
-    }
-
-    return GestureDetector(
-      onTap: widget.onTap,
-      onTapDown: (_) => setState(() => _pressed = true),
-      onTapUp: (_) => setState(() => _pressed = false),
-      onTapCancel: () => setState(() => _pressed = false),
-      child: Opacity(opacity: opacity, child: Center(child: cell)),
-    );
+    return Opacity(opacity: opacity, child: composed);
   }
 }
+