npm package: @sekiro/vue-datepicker
Description: A shadcn/ui-inspired datepicker for Vue 3 with TypeScript support. Single date & range modes, format/valueFormat props, year→month→day drill-down navigation.
Latest version: 1.1.0

# @sekiro/vue-datepicker

A **shadcn/ui-inspired** datepicker component for **Vue 3 + TypeScript**.

- Single date & date-range modes
- `format` / `valueFormat` props for display vs emitted value
- Year → Month → Day drill-down navigation
- **5 built-in locales**: English, Russian, Uzbek, Uzbek Cyrillic, Qaraqalpaqsha
- Custom locale support
- Light theme by default, auto dark mode via `prefers-color-scheme`
- Clear button & Today shortcut
- Zero dependencies (only peer-depends on Vue 3)
- Fully typed with TypeScript declarations

---

## Install

```bash
npm install @sekiro/vue-datepicker
```

## Setup

### Option A — Global plugin

```ts
import { createApp } from 'vue'
import App from './App.vue'
import { VueDatePickerPlugin } from '@sekiro/vue-datepicker'
import '@sekiro/vue-datepicker/style.css'

createApp(App).use(VueDatePickerPlugin).mount('#app')
```

### Option B — Local import

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { DatePicker } from '@sekiro/vue-datepicker'
import '@sekiro/vue-datepicker/style.css'

const date = ref<string | null>(null)
</script>

<template>
  <DatePicker v-model="date" format="DD.MM.YYYY" value-format="YYYY-MM-DD" />
</template>
```

---

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `modelValue` | `string \| RangeValue \| null` | `null` | v-model binding |
| `placeholder` | `string` | `'Pick a date'` | Placeholder text |
| `format` | `string` | `'DD.MM.YYYY'` | Display format (`DD`, `MM`, `YYYY` tokens) |
| `valueFormat` | `string` | `'YYYY-MM-DD'` | Emitted value format |
| `mode` | `'single' \| 'range'` | `'single'` | Single date or range selection |
| `disabled` | `boolean` | `false` | Disable the picker |
| `locale` | `string \| VdpLocale` | `'en'` | Locale key or custom locale object |

### Format tokens

| Token | Output | Example |
|-------|--------|---------|
| `DD` | Day, zero-padded | `05`, `24` |
| `MM` | Month, zero-padded | `01`, `12` |
| `YYYY` | Full year | `2026` |

---

## Locales

Built-in locale keys:

| Key | Language |
|-----|----------|
| `en` | English |
| `ru` | Русский (Russian) |
| `uz` | O'zbekcha (Uzbek Latin) |
| `uz-Cyrl` | Ўзбекча (Uzbek Cyrillic) |
| `kaa` | Qaraqalpaqsha (Karakalpak) |

```vue
<!-- Russian -->
<DatePicker v-model="date" locale="ru" />

<!-- Uzbek -->
<DatePicker v-model="date" locale="uz" />

<!-- Uzbek Cyrillic -->
<DatePicker v-model="date" locale="uz-Cyrl" />

<!-- Qaraqalpaqsha -->
<DatePicker v-model="date" locale="kaa" />
```

### Custom locale

```vue
<script setup lang="ts">
import type { VdpLocale } from '@sekiro/vue-datepicker'

const myLocale: VdpLocale = {
  weekdays: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
  months: ['January', 'February', /* ... */],
  monthsShort: ['Jan', 'Feb', /* ... */],
  today: 'Today',
  clear: 'Clear',
}
</script>

<template>
  <DatePicker v-model="date" :locale="myLocale" />
</template>
```

---

## Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:modelValue` | `string` (single) or `{ start, end }` (range) or `null` (clear) | Emitted on selection or clear |

---

## Examples

### Single date

```vue
<DatePicker
  v-model="birthday"
  placeholder="Date of birth"
  format="DD.MM.YYYY"
  value-format="YYYY-MM-DD"
  locale="ru"
/>
```

### Date range

```vue
<DatePicker
  v-model="tripDates"
  mode="range"
  placeholder="Select dates"
  format="DD.MM.YYYY"
  value-format="YYYY-MM-DD"
  locale="uz"
/>
```

---

## Theming

Light theme is the default. Dark mode activates automatically via `prefers-color-scheme: dark`.

To force dark mode, add the `vdp-dark` class:

```vue
<DatePicker class="vdp-dark" v-model="date" />
```

Override CSS custom properties on `.vdp-wrap` for full control:

```css
.vdp-wrap {
  --vdp-bg: #ffffff;
  --vdp-bg-input: #ffffff;
  --vdp-bg-popover: #ffffff;
  --vdp-bg-hover: rgba(0, 0, 0, 0.04);
  --vdp-border: #e4e4e7;
  --vdp-text: #09090b;
  --vdp-muted: #a1a1aa;
  --vdp-accent: #18181b;
  --vdp-ring: rgba(24, 24, 27, 0.15);
  --vdp-range-bg: rgba(24, 24, 27, 0.06);
  --vdp-range-bg-hover: rgba(24, 24, 27, 0.1);
  --vdp-radius: 8px;
  --vdp-font: -apple-system, sans-serif;
}
```

---

## License

MIT