feat(selector): native-like month/year selector mode with keyboard UX polish

README.md

@@ -54,6 +54,71 @@ const formatter = ref({
 </template>
 ```
 
+## Native Scroll Selector Mode
+
+Enable native-like month/year scrolling with `selectorMode` (use `:selector-mode` in templates). Default is `false`.
+
+**Single date**
+
+```vue
+<script setup>
+import { ref } from "vue";
+
+const singleDate = ref("");
+</script>
+
+<template>
+  <vue-tailwind-datepicker v-model="singleDate" as-single :selector-mode="true" />
+</template>
+```
+
+**Range**
+
+```vue
+<script setup>
+import { ref } from "vue";
+
+const rangeDate = ref({
+  startDate: "",
+  endDate: "",
+});
+</script>
+
+<template>
+  <vue-tailwind-datepicker v-model="rangeDate" use-range :selector-mode="true" />
+</template>
+```
+
+**Selector behavior options**
+
+- `selector-year-scroll-mode="boundary"`: clarity-first default; year wheel advances discretely.
+- `selector-year-scroll-mode="fractional"`: continuous month-synced year-wheel drift.
+- `:selector-year-home-jump="100"`: Home key jump size (years) in year wheel mode.
+- `:selector-year-end-jump="100"`: End key jump size (years) in year wheel mode.
+- `:selector-year-page-jump="10"`: PageUp/PageDown jump size (years) in year wheel mode.
+- `:selector-year-page-shift-jump="100"`: Shift+PageUp/Shift+PageDown jump size (years).
+- `:selector-focus-tint="false"`: keeps selector containers neutral while preserving functionality.
+- `:close-on-range-selection="false"`: keeps the popover open after selecting the second range date.
+  Recommended with `selector-mode` when you want a fully native-like keep-open flow.
+  In `no-input` static mode this option is a no-op because there is no popover to close.
+
+```vue
+<vue-tailwind-datepicker
+  v-model="rangeDate"
+  use-range
+  :selector-mode="true"
+  selector-year-scroll-mode="boundary"
+  :selector-year-home-jump="100"
+  :selector-year-end-jump="100"
+  :selector-year-page-jump="10"
+  :selector-year-page-shift-jump="100"
+  :selector-focus-tint="true"
+  :close-on-range-selection="false"
+/>
+```
+
+Selector wheel visuals are also themeable through CSS variables on `.vtd-datepicker` (month/year selected and hover colors, borders, typography, and wheel cell sizing). Calendar range preview colors/opacity are exposed via `--vtd-calendar-range-preview-bg` and `--vtd-calendar-range-preview-bg-dark`. See `docs/theming-options.md` for examples.
+
 ## Theming options
 
 **Light Mode**

docs/props.md

@@ -292,9 +292,9 @@ const formatter = ref({
 </template>
 ```
 
-## Auto apply
-
-Change auto apply, by default `autoApply` is true.
+## Auto apply
+
+Change auto apply, by default `autoApply` is true.
 
 <DemoLayout>
   <VueTailwindDatePicker
@@ -310,10 +310,29 @@ import { ref } from 'vue'
 const dateValue = ref([])
 </script>
 
-<template>
-  <vue-tailwind-datepicker v-model="dateValue" :auto-apply="false" />
-</template>
-```
+<template>
+  <vue-tailwind-datepicker v-model="dateValue" :auto-apply="false" />
+</template>
+```
+
+## Close on range selection
+
+Control whether popover mode closes immediately after selecting the second date in range mode.
+Default is `true`.
+
+When using `selector-mode`, set this to `false` if you want a fully native-like keep-open flow after second-date selection.
+
+In `no-input` static mode this prop is a no-op because there is no popover to close.
+
+```vue
+<template>
+  <vue-tailwind-datepicker
+    v-model="dateValue"
+    use-range
+    :close-on-range-selection="false"
+  />
+</template>
+```
 
 ## Start from
 
@@ -548,7 +567,7 @@ const dateValue = ref([])
 ```
 
 
-## Options
+## Options
 
 Change default options
 
@@ -584,6 +603,95 @@ const options = ref({
     v-model="dateValue"
     :options="options"
     :auto-apply="false"
-  />
-</template>
-```
+  />
+</template>
+```
+
+## Selector Mode
+
+Enable native-like month/year wheel selectors. Default is `false`.
+
+<DemoLayout>
+  <VueTailwindDatePicker
+    v-model="dateValue3"
+    as-single
+    :selector-mode="true"
+  />
+</DemoLayout>
+
+```vue
+<template>
+  <vue-tailwind-datepicker
+    v-model="dateValue"
+    as-single
+    :selector-mode="true"
+  />
+</template>
+```
+
+## Selector Year Scroll Mode
+
+Choose year-wheel sync behavior when selector mode is enabled.
+
+- `boundary` (default): year wheel moves discretely on year boundaries.
+- `fractional`: year wheel drifts continuously with month progress.
+
+<DemoLayout>
+  <VueTailwindDatePicker
+    v-model="dateValue4"
+    as-single
+    use-range
+    :selector-mode="true"
+    selector-year-scroll-mode="fractional"
+  />
+</DemoLayout>
+
+```vue
+<template>
+  <vue-tailwind-datepicker
+    v-model="dateValue"
+    as-single
+    use-range
+    :selector-mode="true"
+    selector-year-scroll-mode="boundary"
+  />
+</template>
+```
+
+## Selector Year Keyboard Jumps
+
+Control keyboard jump distance (in years) for the selector year wheel.
+
+- `selector-year-home-jump` and `selector-year-end-jump` default to `100`.
+- `selector-year-page-jump` defaults to `10`.
+- `selector-year-page-shift-jump` defaults to `100`.
+
+```vue
+<template>
+  <vue-tailwind-datepicker
+    v-model="dateValue"
+    as-single
+    :selector-mode="true"
+    :selector-year-home-jump="50"
+    :selector-year-end-jump="50"
+    :selector-year-page-jump="12"
+    :selector-year-page-shift-jump="120"
+  />
+</template>
+```
+
+## Selector Focus Tint
+
+Control whether the active selector column receives extra focus tint styling.
+Default is `true`.
+
+```vue
+<template>
+  <vue-tailwind-datepicker
+    v-model="dateValue"
+    as-single
+    :selector-mode="true"
+    :selector-focus-tint="false"
+  />
+</template>
+```

docs/theming-options.md

@@ -37,3 +37,60 @@ Light mode color system using custom color `vtd-primary`.
 ## Dark mode
 
 Dark mode color system using color palette `vtd-secondary`. Vue Tailwind Datepicker work it well with Tailwind CSS `dark` mode configuration.
+
+## Selector Wheel Tokens
+
+When `selector-mode` is enabled, month/year wheel visuals can be tuned via CSS variables on `.vtd-datepicker`.
+
+```css
+.vtd-datepicker {
+  --vtd-selector-wheel-cell-height: 40px;
+
+  --vtd-selector-month-font-family: inherit;
+  --vtd-selector-month-font-size: 0.875rem;
+  --vtd-selector-month-font-weight: 500;
+  --vtd-selector-month-line-height: 1.5rem;
+  --vtd-selector-month-text: rgb(163 163 163 / 100%);
+  --vtd-selector-month-hover-bg: rgb(14 165 233 / 10%);
+  --vtd-selector-month-hover-border: rgb(56 189 248 / 45%);
+  --vtd-selector-month-hover-border-width: 0.85px;
+  --vtd-selector-month-hover-text: rgb(14 116 144 / 100%);
+  --vtd-selector-month-selected-bg: rgb(14 165 233 / 13%);
+  --vtd-selector-month-selected-border: rgb(14 165 233 / 62%);
+  --vtd-selector-month-selected-border-width: 0.85px;
+  --vtd-selector-month-selected-text: rgb(56 189 248 / 100%);
+
+  --vtd-selector-year-font-family: inherit;
+  --vtd-selector-year-font-size: 0.875rem;
+  --vtd-selector-year-font-weight: 500;
+  --vtd-selector-year-text: rgb(163 163 163 / 100%);
+  --vtd-selector-year-hover-bg: rgb(14 165 233 / 10%);
+  --vtd-selector-year-hover-border: rgb(56 189 248 / 45%);
+  --vtd-selector-year-hover-border-width: 0.85px;
+  --vtd-selector-year-hover-text: rgb(14 116 144 / 100%);
+  --vtd-selector-year-selected-bg: rgb(14 165 233 / 13%);
+  --vtd-selector-year-selected-border: rgb(14 165 233 / 62%);
+  --vtd-selector-year-selected-border-width: 0.85px;
+  --vtd-selector-year-selected-text: rgb(56 189 248 / 100%);
+
+  /* Advanced year-canvas tuning */
+  --vtd-selector-year-canvas-border-width-scale: 0.5;
+  --vtd-selector-year-canvas-dpr: 4;
+  --vtd-selector-year-text-offset-y: 0px;
+}
+```
+
+## Calendar Range Preview Tokens
+
+You can tune the in-range background (including opacity) without custom selectors:
+
+```css
+.vtd-datepicker {
+  --vtd-calendar-range-preview-bg: rgb(224 242 254 / 60%);
+  --vtd-calendar-range-preview-bg-dark: rgb(55 65 81 / 50%);
+
+  /* Range edge caps (start/end) */
+  --vtd-calendar-range-preview-edge-bg: var(--vtd-calendar-day-selected-bg);
+  --vtd-calendar-range-preview-edge-bg-dark: var(--vtd-calendar-day-selected-bg);
+}
+```