### Event Handling Example (HTML)

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Shows how to listen for events emitted by the Alpine Calendar component using Alpine.js's `@` syntax. This allows for reacting to changes in selection or navigation.

```html
<div x-data="calendar({ ... })"
     @calendar:change="console.log($event.detail)"
     @calendar:navigate="console.log($event.detail)">
</div>
```

--------------------------------

### Presetting Multiple Date Values

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This example shows how to set multiple initial dates for the calendar. The `value` option takes a comma-separated string of dates, pre-selecting '2026-03-10', '2026-03-15', and '2026-03-20'.

```html
<div x-data="calendar({ mode: 'multiple', value: '2026-03-10, 2026-03-15, 2026-03-20' })"></div>
```

--------------------------------

### Programmatic Control Example (HTML)

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Demonstrates how to programmatically control the Alpine Calendar component using its exposed methods via `$refs`. This allows for setting dates or clearing the selection from external HTML elements.

```html
<div x-data="calendar({ ... })" x-ref="cal">
  <button @click="$refs.cal.setValue('2025-06-15')">Set Date</button>
  <button @click="$refs.cal.clear()">Clear</button>
</div>
```

--------------------------------

### Presetting Single Date Value

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This example shows how to set an initial single date value for the calendar. The `value` option in the `calendar()` configuration is used to pre-select '2026-03-15' when the calendar is initialized.

```html
<div x-data="calendar({ mode: 'single', value: '2026-03-15' })"></div>
```

--------------------------------

### Initialize Alpine Calendar Plugin

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This snippet demonstrates how to import and register the calendar plugin with Alpine.js. It requires Alpine.js to be installed.

```javascript
import Alpine from 'alpinejs'
import { calendarPlugin } from '../src/index.ts'

Alpine.plugin(calendarPlugin)
Alpine.start()
```

--------------------------------

### Alpine Calendar: Sunday Start Day Configuration

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Explains how to override the default Monday start day to Sunday using the `firstDay: 0` option. This is useful for regions where the week traditionally starts on Sunday.

```html
<div x-data="calendar({ mode: 'single', firstDay: 0 })"></div>
```

--------------------------------

### Configure Calendar in Year-Month Wizard Mode

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This configuration starts the wizard mode from the year view, then proceeds to month selection, and finally day selection. It's activated using `wizard: 'year-month'`.

```html
<div x-data="calendar({
      mode: 'single',
      wizard: 'year-month'
    })"></div>
```

--------------------------------

### Install Alpine Calendar with npm/pnpm and Initialize AlpineJS

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This snippet shows how to add the Alpine Calendar package using npm or pnpm and then initialize AlpineJS with the calendar plugin. It ensures the calendar's CSS is also imported for proper styling.

```bash
pnpm add @reachweb/alpine-calendar
# or
npm install @reachweb/alpine-calendar
```

```javascript
import Alpine from 'alpinejs'
import { calendarPlugin } from '@reachweb/alpine-calendar'
import '@reachweb/alpine-calendar/css'

Alpine.plugin(calendarPlugin)
Alpine.start()
```

--------------------------------

### Configure Calendar with Static Date Metadata (Room Pricing)

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This example shows how to attach metadata like pricing and availability to specific dates using a static object. Dates can be styled based on their metadata, such as showing price labels or indicating availability.

```html
<div x-data="calendar({
      mode: 'single',
      dateMetadata: {
        '2026-03-01': { label: '$120', availability: 'available' },
        '2026-03-03': { label: '$150', availability: 'available', color: '#16a34a' },
        '2026-03-05': { label: '$180', availability: 'available', color: '#ea580c' },
        '2026-03-06': { availability: 'unavailable' },
        '2026-03-07': { label: 'Sold', availability: 'unavailable' },
        '2026-03-09': { label: '$99', availability: 'available', color: '#2563eb' },
      }
    })"></div>
```

--------------------------------

### Range Presets Setup with JavaScript

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Imports predefined functions for generating common date range presets like 'Today', 'Last 7 Days', and 'This Month'. These presets can be used to quickly populate the calendar's range selection.

```javascript
import {
  presetToday,
  presetYesterday,
  presetLastNDays,
  presetThisWeek,
  presetLastWeek,
  presetThisMonth,
  presetLastMonth,
  presetThisYear,
  presetLastYear,
} from '@reachweb/alpine-calendar'
```

--------------------------------

### Configure Calendar in Popup Wizard Mode

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This setup displays the full wizard mode within a popup dropdown, triggered by interacting with an input field. It combines `wizard: true` with `display: 'popup'`.

```html
<div x-data="calendar({
      mode: 'single',
      wizard: true,
      display: 'popup'
    })">
      <input x-ref="rc-input" type="text" class="rc-input"
             placeholder="Birth date...">
    </div>
```

--------------------------------

### Listen to Calendar Events (HTML & JavaScript)

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Illustrates how to listen for various calendar events such as 'change', 'navigate', 'open', 'close', and 'view-change' using Alpine.js directives. It provides example JavaScript functions to handle the event details.

```html
<div x-data="calendar({ mode: 'single', display: 'popup' })"
  @calendar:change="handleChange($event.detail)"
  @calendar:navigate="handleNavigate($event.detail)"
  @calendar:open="console.log('Calendar opened')"
  @calendar:close="console.log('Calendar closed')"
  @calendar:view-change="console.log('View changed to:', $event.detail.view)">
  <input x-ref="rc-input" type="text">
</div>

<script>
function handleChange(detail) {
  console.log('ISO value:', detail.value)       // "2025-06-15" or "2025-06-01 – 2025-06-15"
  console.log('ISO array:', detail.dates)       // ["2025-06-15"] or ["2025-06-01", "2025-06-15"]
  console.log('Formatted:', detail.formatted)   // "15/06/2025" or "01/06/2025 – 15/06/2025"
}

function handleNavigate(detail) {
  console.log('Year:', detail.year)   // 2025
  console.log('Month:', detail.month) // 6
  console.log('View:', detail.view)   // "days", "months", or "years"
}
</script>
```

--------------------------------

### Configure Calendar with Disabled/Enabled Date Exceptions

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This example demonstrates how to disable weekends by default but then selectively enable specific dates and disable others within a given period. It uses `disabledDaysOfWeek`, `enabledDates`, and `disabledDates` for fine-grained control.

```html
<div x-data="calendar({
      mode: 'single',
      disabledDaysOfWeek: [0, 6],
      enabledDates: ['2026-03-07', '2026-03-08'],
      disabledDates: ['2026-03-09', '2026-03-10', '2026-03-11'],
    })"></div>
```

--------------------------------

### Development Commands for Alpine Calendar

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Lists common pnpm commands used for developing and maintaining the Alpine Calendar project. These commands cover dependency installation, running the development server, executing tests, type checking, linting, formatting, and building different bundle outputs.

```bash
pnpm install          # Install dependencies
pnpm dev              # Start dev server with demo
pnpm test             # Run tests
pnpm test:watch       # Run tests in watch mode
pnpm test:coverage    # Run tests with coverage report
pnpm typecheck        # Type-check without emitting
pnpm lint             # Lint source files
pnpm lint:fix         # Lint and auto-fix
pnpm format           # Format source files with Prettier
pnpm build            # Build all bundles (ESM + UMD + CDN + CSS + types)
pnpm build:lib        # Build ESM + UMD only
pnpm build:cdn        # Build CDN/IIFE bundle only

# Full verification chain before release:
pnpm typecheck && pnpm lint && pnpm test && pnpm build
```

--------------------------------

### Livewire Integration for Alpine Calendar

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Shows how to integrate Alpine Calendar with Livewire, including adding necessary CSS and JavaScript files via `@push` directives and using `wire:ignore` to prevent Livewire from interfering with the calendar's DOM manipulation. This setup allows for seamless use of the calendar within Livewire applications.

```php
@push('styles')
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@reachweb/alpine-calendar/dist/alpine-calendar.css">
@endpush
@push('scripts')
  <script src="https://cdn.jsdelivr.net/npm/@reachweb/alpine-calendar/dist/alpine-calendar.cdn.js"></script>
@endpush

<div wire:ignore>
  <div x-data="calendar({ mode: 'single', display: 'popup' })"
       @calendar:change="$wire.set('date', $event.detail.value)">
    <input x-ref="rc-input" type="text" class="rc-input">
  </div>
</div>
```

--------------------------------

### Install Alpine Calendar via CDN

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This snippet demonstrates how to include the Alpine Calendar component using Content Delivery Network (CDN) links. It includes the necessary CSS and JavaScript files for both AlpineJS and the calendar plugin, suitable for projects without a bundler.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@reachweb/alpine-calendar/dist/alpine-calendar.css">
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@reachweb/alpine-calendar/dist/alpine-calendar.cdn.js"></script>
```

--------------------------------

### Popup Calendar with Input Binding

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This example demonstrates setting up a popup calendar that binds to an input field. The calendar is configured for single date selection and uses `x-ref="rc-input"` to link with the input element, enabling automatic input masking and ARIA attributes.

```html
<div x-data="calendar({ mode: 'single', display: 'popup' })">
  <input x-ref="rc-input" type="text" class="rc-input">
</div>
```

--------------------------------

### Theming with TailwindCSS 4 (CSS)

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Provides an example of how to theme the Alpine Calendar component using CSS custom properties, specifically demonstrating overrides compatible with TailwindCSS 4. This allows for easy visual customization of the calendar's appearance.

```css
@theme {
  --color-calendar-bg: var(--color-white);
  --color-calendar-text: var(--color-gray-900);
  --color-calendar-primary: var(--color-indigo-600);
  --color-calendar-primary-text: var(--color-white);
  --color-calendar-hover: var(--color-gray-100);
  --color-calendar-disabled: var(--color-gray-300);
  --color-calendar-range: var(--color-indigo-50);
  --color-calendar-today-ring: var(--color-indigo-400);
  --color-calendar-border: var(--color-gray-200);
  --color-calendar-other-month: var(--color-gray-400);
  --color-calendar-weekday: var(--color-gray-500);
  --color-calendar-focus-ring: var(--color-indigo-600);
  --color-calendar-overlay: oklch(0 0 0 / 0.2);
  --radius-calendar: var(--radius-lg);
  --shadow-calendar: var(--shadow-lg);
  --font-calendar: system-ui, -apple-system, sans-serif;
}
```

--------------------------------

### Range Date Selection Model - JavaScript

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Handles date range selection, supporting a start and end date. It allows for incremental range building, checking if a date falls within the selected range, and provides methods to get the start date, check for partial or complete ranges, and retrieve the range as a formatted string. It also supports direct range assignment.

```javascript
import { RangeSelection, CalendarDate } from '@reachweb/alpine-calendar'

const selection = new RangeSelection()

// First click sets start
selection.toggle(new CalendarDate(2025, 6, 10))
console.log(selection.isPartial())   // true
console.log(selection.getStart())    // CalendarDate(2025, 6, 10)

// Second click sets end (auto-swaps if before start)
selection.toggle(new CalendarDate(2025, 6, 20))
console.log(selection.isComplete())  // true
console.log(selection.toValue())     // "2025-06-10 – 2025-06-20"

// Check if date is in range (inclusive)
console.log(selection.isInRange(new CalendarDate(2025, 6, 15)))  // true

// Hover preview for range building
const hoverDate = new CalendarDate(2025, 6, 25)
console.log(selection.isInRange(new CalendarDate(2025, 6, 22), hoverDate))  // depends on state

// Third click restarts with new start
selection.toggle(new CalendarDate(2025, 7, 1))
console.log(selection.isPartial())   // true

// Direct assignment (bypasses toggle semantics)
selection.setRange(
  new CalendarDate(2025, 8, 1),
  new CalendarDate(2025, 8, 1)  // Same-day range
)
console.log(selection.toValue())     // "2025-08-01 – 2025-08-01"
```

--------------------------------

### Presetting Range Date Values

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This HTML snippet demonstrates how to set an initial date range for the calendar. The `value` option accepts a string representing the start and end dates, separated by ' - ', to pre-select the range '2026-03-10' to '2026-03-20'.

```html
<div x-data="calendar({ mode: 'range', value: '2026-03-10 - 2026-03-20' })"></div>
```

--------------------------------

### Alpine Calendar: Basic Range Selection

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Shows how to configure Alpine Calendar for range selection, allowing users to pick a start and end date. Hovering over dates previews the selected range.

```html
<div x-data="calendar({ mode: 'range' })"></div>
```

--------------------------------

### Alpine Calendar Component: Single Date Selection (Inline)

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Shows how to implement an inline calendar for single date selection using Alpine.js. Includes examples for basic configuration and advanced options like value binding, date constraints, and formatting.

```html
<!-- Basic inline calendar -->
<div x-data="calendar({ mode: 'single', firstDay: 1 })"></div>

<!-- With initial value and constraints -->
<div x-data="calendar({
  mode: 'single',
  value: '2025-06-15',
  minDate: '2025-01-01',
  maxDate: '2025-12-31',
  disabledDaysOfWeek: [0, 6],
  format: 'DD/MM/YYYY',
  locale: 'en-GB'
})"
  @calendar:change="console.log('Selected:', $event.detail.value)">
</div>
```

--------------------------------

### Set Global Calendar Defaults (JavaScript)

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Configures global default settings for all instances of the Alpine.js calendar component using the `calendarPlugin.defaults()` method. This example sets the first day of the week to Monday (1) and the locale to Greek ('el'). The plugin is then registered with Alpine.js.

```javascript
import { calendarPlugin } from '@reachweb/alpine-calendar'

calendarPlugin.defaults({ firstDay: 1, locale: 'el' })
Alpine.plugin(calendarPlugin)
```

--------------------------------

### Server-Rendered Date Value with Blade

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This example shows how to pass a server-side variable, such as a date from a Blade template, directly into the Alpine Calendar configuration. The `{{ $date }}` syntax injects the backend variable into the `value` option.

```html
<div x-data="calendar({ mode: 'single', value: '{{ $date }}' })"></div>
```

--------------------------------

### Birth Date Wizard Configuration with HTML

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Configures the calendar to function as a wizard for selecting birth dates, optimizing the selection process by starting with year, then month, then day. It supports full wizard mode, year-month only, or month-day only selection.

```html
<!-- Full wizard: Year → Month → Day -->
<div x-data="calendar({ mode: 'single', wizard: true })"></div>

<!-- Year-Month only wizard -->
<div x-data="calendar({ mode: 'single', wizard: 'year-month' })"></div>

<!-- Month-Day only wizard -->
<div x-data="calendar({ mode: 'single', wizard: 'month-day' })"></div>
```

--------------------------------

### Configure Calendar for 3-Month Inline Display

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This setup displays three months of the calendar inline within a scrollable container, which is useful for longer booking flows. The `months: 3` option controls the number of months displayed.

```html
<div x-data="calendar({
      mode: 'single',
      months: 3
    })"></div>
```

--------------------------------

### Calendar Integration with Form Submission

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This example shows how to integrate the Alpine Calendar with an HTML form for submission. By setting the `name` attribute in the calendar configuration, hidden input fields are automatically generated for the selected date(s), facilitating form data handling.

```html
<form>
  <div x-data="calendar({ mode: 'single', name: 'date' })"></div>
  <button type="submit">Submit</button>
</form>
```

--------------------------------

### Apply Custom Green Theme to Calendar using CSS

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This CSS example shows how to customize the calendar's primary accent color to green. It overrides `--color-calendar-primary`, `--color-calendar-primary-text`, `--color-calendar-today-ring`, and `--color-calendar-range` for a branded look.

```css
.green-theme {
  --color-calendar-primary: #059669;
  --color-calendar-primary-text: #ffffff;
  --color-calendar-today-ring: #34d399;
  --color-calendar-range: #ecfdf5;
}
```

--------------------------------

### Alpine Calendar: Popup Range Selection with 3 Months

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Illustrates a popup range picker configured to display three months (`months: 3`) for enhanced usability. This setup is ideal for selecting check-in and check-out dates.

```html
<div x-data="calendar({
  mode: 'range',
  months: 3,
  display: 'popup'})">
  <input x-ref="rc-input" type="text" class="rc-input"
         placeholder="Check-in — Check-out">
</div>
```

--------------------------------

### Create Reusable Date Constraint Functions (JavaScript)

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Provides a JavaScript example using `@reachweb/alpine-calendar` to create a reusable date constraint function. This function validates dates against various criteria like min/max dates, disabled days/dates/months, and enabled years/dates, outside of the calendar component itself.

```javascript
import { createDateConstraint, CalendarDate } from '@reachweb/alpine-calendar'

const isDisabled = createDateConstraint({
  minDate: new CalendarDate(2025, 1, 1),
  maxDate: new CalendarDate(2025, 12, 31),
  disabledDaysOfWeek: [0, 6],             // Disable weekends
  disabledDates: [                         // Specific holidays
    new CalendarDate(2025, 7, 4),
    new CalendarDate(2025, 12, 25)
  ],
  enabledDates: [                          // Force-enable exceptions
    new CalendarDate(2025, 7, 5)           // Override weekend
  ],
  disabledMonths: [8],                     // Disable August
  enabledYears: [2025, 2026]               // Only allow 2025-2026
})

// Check individual dates
console.log(isDisabled(new CalendarDate(2025, 6, 15)))  // false (valid weekday)
console.log(isDisabled(new CalendarDate(2025, 6, 14)))  // true (Saturday)
console.log(isDisabled(new CalendarDate(2025, 7, 4)))   // true (holiday)
```

--------------------------------

### Alpine Calendar: Form Submission with Hidden Inputs

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Demonstrates how Alpine Calendar automatically generates hidden inputs for form submission when a `name` is provided. This example shows a basic form submission handler.

```html
<form @submit.prevent="handleSubmit">
  <div x-data="calendar({
    mode: 'single',
    name: 'appointment'
  })"></div>
  <button type="submit">Submit</button>
</form>
```

--------------------------------

### Integrate Alpine Calendar with Laravel Livewire

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Provides instructions for integrating the Alpine Calendar with Laravel Livewire applications. It emphasizes using `wire:ignore` to prevent DOM morphing conflicts and demonstrates how to manage calendar state with `@entangle` for two-way data binding.

```php
{{-- In your Blade view --}}
@push('styles')
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@reachweb/alpine-calendar/dist/alpine-calendar.css">
@endpush

@push('scripts')
  <script src="https://cdn.jsdelivr.net/npm/@reachweb/alpine-calendar/dist/alpine-calendar.cdn.js"></script>
@endpush

{{-- Wire:ignore prevents Livewire from morphing the calendar DOM --}}
<div wire:ignore>
  <div x-data="calendar({
    mode: 'single',
    display: 'popup',
    value: '{{ $date }}'
  })"
    @calendar:change="$wire.set('date', $event.detail.value)">
    <input x-ref="rc-input" type="text" class="rc-input">
  </div>
</div>

{{-- With @entangle for two-way binding --}}
<div wire:ignore>
  <div x-data="calendar({
    mode: 'single',
    value: @entangle('selectedDate')
  })">
  </div>
</div>
```

--------------------------------

### Configure Calendar in Month-Day Wizard Mode

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This wizard mode begins with month selection and then proceeds to day selection. It is configured using `wizard: 'month-day'`.

```html
<div x-data="calendar({
      mode: 'single',
      wizard: 'month-day'
    })"></div>
```

--------------------------------

### Configure Calendar with Dynamic Date Metadata (Computed Pricing)

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This configuration uses a callback function to dynamically determine metadata for each date, such as calculating pricing based on the day of the week and availability. Weekends are marked as unavailable, while weekdays display a computed price.

```html
<div x-data="calendar({
      mode: 'range',
      dateMetadata: (date) => {
        const d = date.toNativeDate().getDay()
        if (d === 0 || d === 6)
          return { availability: 'unavailable' }
        return {
          label: '$' + (100 + date.day * 3),
          availability: 'available'
        }
      }
    })"></div>
```

--------------------------------

### Configure Alpine Calendar with Period-Specific Rules (HTML)

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This HTML snippet demonstrates how to configure the Alpine.js calendar component using `x-data`. It specifically shows the use of `minRange` and `rules` for defining period-specific date constraints, allowing for different validation logic based on date ranges.

```html
<div x-data="calendar({
  mode: 'range',
  minRange: 3,
  rules: [
    {
      from: '2025-06-01',
      to: '2025-08-31',
      minRange: 7,
      disabledDaysOfWeek: [0, 6]
    }
  ]
})">
```

--------------------------------

### Event Handling

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Listen for various calendar events such as date changes, navigation, and view updates to integrate calendar interactions with your application's logic.

```APIDOC
## Events

### Description
Listen for calendar events to integrate with your application logic. Events are dispatched using Alpine.js's event system.

### Method
Event listeners attached to the calendar element.

### Endpoint
N/A (Client-side event handling)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```html
<div x-data="calendar({ mode: 'single', display: 'popup' })"
  @calendar:change="handleChange($event.detail)"
  @calendar:navigate="handleNavigate($event.detail)"
  @calendar:open="console.log('Calendar opened')"
  @calendar:close="console.log('Calendar closed')"
  @calendar:view-change="console.log('View changed to:', $event.detail.view)">
  <input x-ref="rc-input" type="text">
</div>

<script>
function handleChange(detail) {
  console.log('ISO value:', detail.value)       // "2025-06-15" or "2025-06-01 – 2025-06-15"
  console.log('ISO array:', detail.dates)       // ["2025-06-15"] or ["2025-06-01", "2025-06-15"]
  console.log('Formatted:', detail.formatted)   // "15/06/2025" or "01/06/2025 – 15/06/2025"
}

function handleNavigate(detail) {
  console.log('Year:', detail.year)   // 2025
  console.log('Month:', detail.month) // 6
  console.log('View:', detail.view)   // "days", "months", or "years"
}
</script>
```

### Response
#### Success Response (N/A)
Event details are passed as `$event.detail` to the handler functions.

#### Response Example
Event detail object structure varies based on the event. For `calendar:change`, it includes `value`, `dates`, and `formatted`. For `calendar:navigate`, it includes `year`, `month`, and `view`.
```

--------------------------------

### TypeScript Imports for Alpine Calendar

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Demonstrates how to import core functionalities and types from the '@reachweb/alpine-calendar' package. This is useful for integrating the calendar component into TypeScript projects, enabling type safety and autocompletion.

```typescript
import {
  calendarPlugin,
  CalendarDate,
  getISOWeekNumber,
  SingleSelection,
  MultipleSelection,
  RangeSelection,
  createCalendarData,
  parseDate,
  formatDate,
  createMask,
  computePosition,
  autoUpdate,
  generateMonth,
  generateMonths,
  generateMonthGrid,
  generateYearGrid,
  createDateConstraint,
  createRangeValidator,
  createDisabledReasons,
  isDateDisabled,
  presetToday,
  presetYesterday,
  presetLastNDays,
  presetThisWeek,
  presetLastWeek,
  presetThisMonth,
  presetLastMonth,
  presetThisYear,
  presetLastYear,
} from '@reachweb/alpine-calendar'

import type {
  CalendarConfig,
  CalendarConfigRule,
  RangePreset,
  DayCell,
  MonthCell,
  YearCell,
  Selection,
  Placement,
  PositionOptions,
  DateConstraintOptions,
  DateConstraintProperties,
  DateConstraintRule,
  ConstraintMessages,
  InputMask,
  MaskEventHandlers,
} from '@reachweb/alpine-calendar'
```

--------------------------------

### Alpine Calendar Configuration

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Configuration options for the Alpine Calendar component, passed via `x-data='calendar({...})'`.

```APIDOC
## Configuration

All options are passed via `x-data="calendar({ ... })"`.

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `mode` | `'single' | 'multiple' | 'range'` | `'single'` | Selection mode |
| `display` | `'inline' | 'popup'` | `'inline'` | Inline calendar or popup with input |
| `format` | `string` | `'DD/MM/YYYY'` | Date format (tokens: `DD`, `MM`, `YYYY`, `D`, `M`, `YY`) |
| `months` | `number` | `1` | Months to display (1=single, 2=dual side-by-side, 3+=scrollable) |
| `firstDay` | `0–6` | `1` | First day of week (0=Sun, 1=Mon, ...) |
| `mask` | `boolean` | `true` | Enable input masking |
| `value` | `string` | — | Initial value (ISO or formatted string) |
| `name` | `string` | `''` | Input name attribute for form submission |
| `locale` | `string` | — | BCP 47 locale for month/day names |
| `timezone` | `string` | — | IANA timezone for resolving "today" |
| `closeOnSelect` | `boolean` | `true` | Close popup after selection |
| `wizard` | `boolean | 'year-month' | 'month-day'` | `false` | Birth date wizard mode |
| `beforeSelect` | `(date, ctx) => boolean` | — | Custom validation before selection |
| `showWeekNumbers` | `boolean` | `false` | Show ISO 8601 week numbers alongside the day grid |
| `inputId` | `string` | — | ID for the popup input (allows external `<label for="...">`) |
| `inputRef` | `string` | `'rc-input'` | Alpine `x-ref` name for the input element |
| `scrollHeight` | `number` | `400` | Max height (px) of scrollable container when `months >= 3` |
| `presets` | `RangePreset[]` | — | Predefined date range shortcuts (see [Range Presets](#range-presets)) |
| `constraintMessages` | `ConstraintMessages` | — | Custom tooltip strings for disabled dates |
| `template` | `boolean` | `true` | Auto-render template when no `.rc-calendar` exists |

### Date Constraints

| Option | Type | Description |
|---|---|---|
| `minDate` | `string` | Earliest selectable date (ISO) |
| `maxDate` | `string` | Latest selectable date (ISO) |
| `disabledDates` | `string[]` | Specific dates to disable (ISO) |
| `disabledDaysOfWeek` | `number[]` | Days of week to disable (0=Sun, 6=Sat) |
| `enabledDates` | `string[]` | Force-enable specific dates (overrides day-of-week rules) |
| `enabledDaysOfWeek` | `number[]` | Only these days are selectable |
| `disabledMonths` | `number[]` | Months to disable (1=Jan, 12=Dec) |
| `enabledMonths` | `number[]` | Only these months are selectable |
| `disabledYears` | `number[]` | Specific years to disable |
| `enabledYears` | `number[]` | Only these years are selectable |
| `minRange` | `number` | Minimum range length in days (inclusive) |
| `maxRange` | `number` | Maximum range length in days (inclusive) |
| `rules` | `CalendarConfigRule[]` | Period-specific constraint overrides |

### Period-Specific Rules

Override constraints for specific date ranges. First matching rule wins; unmatched dates use global constraints.

```html
<div x-data="calendar({
  mode: 'range',
  minRange: 3,
  rules: [
    {
      from: '2025-06-01',
      to: '2025-08-31',
      minRange: 7,
      disabledDaysOfWeek: [0, 6]
    }
  ]
})">
```
```

--------------------------------

### Create and Use Input Masks with Alpine Calendar

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Enables guided user input for date fields by applying format masks. It automatically inserts separators and handles non-digit characters, ensuring data integrity. The mask can be attached to DOM elements and later detached.

```javascript
import { createMask, attachMask, parseFormatToSlots } from '@reachweb/alpine-calendar'

// Create a mask from format string
const mask = createMask('DD/MM/YYYY')

console.log(mask.pattern)    // "99/99/9999"
console.log(mask.maxDigits)  // 8
console.log(mask.length)     // 10

// Apply mask to raw input
console.log(mask.apply('15062025'))     // "15/06/2025"
console.log(mask.apply('150'))          // "15/0"
console.log(mask.apply('abc123def45'))  // "12/34/5" (non-digits stripped)

// Attach mask to DOM element
const input = document.querySelector('#date-input')
const detach = attachMask(input, 'MM/DD/YYYY')

// Later: remove mask handlers
detach()

// Inspect slot definitions
const slots = parseFormatToSlots('DD/MM/YYYY')
// [
//   { type: 'digit', char: '9' },   // D
//   { type: 'digit', char: '9' },   // D
//   { type: 'literal', char: '/' }, // /
//   { type: 'digit', char: '9' },   // M
//   { type: 'digit', char: '9' },   // M
//   { type: 'literal', char: '/' }, // /
//   { type: 'digit', char: '9' },   // Y
//   { type: 'digit', char: '9' },   // Y
//   { type: 'digit', char: '9' },   // Y
//   { type: 'digit', char: '9' },   // Y
// ]
```

--------------------------------

### Configure Calendar in Full Wizard Mode (Birth Date)

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Enables a step-by-step date selection process (Year → Month → Day), which is useful for selecting birth dates or historical dates. The `wizard: true` option activates this mode.

```html
<div x-data="calendar({
      mode: 'single',
      wizard: true})"></div>
```

--------------------------------

### CalendarDate Class: Creating and Manipulating Dates

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Demonstrates the creation and manipulation of timezone-safe dates using the CalendarDate class. It covers factory methods, direct creation, serialization, comparison, arithmetic, and formatting.

```javascript
import { CalendarDate } from '@reachweb/alpine-calendar'

// Factory methods
const today = CalendarDate.today()                          // Browser's local timezone
const todayTZ = CalendarDate.today('America/New_York')      // Specific timezone
const fromISO = CalendarDate.fromISO('2025-06-15')          // From ISO string
const fromNative = CalendarDate.fromNativeDate(new Date())  // From native Date

// Create directly
const date = new CalendarDate(2025, 6, 15)  // June 15, 2025

// Serialization
console.log(date.toISO())         // "2025-06-15"
console.log(date.toKey())         // "2025-06-15" (for Sets/Maps)
console.log(date.toNativeDate())  // Native Date at midnight local time

// Comparison methods
const other = new CalendarDate(2025, 7, 20)
console.log(date.isSame(other))     // false
console.log(date.isBefore(other))   // true
console.log(date.isAfter(other))    // false
console.log(date.isBetween(
  new CalendarDate(2025, 6, 1),
  new CalendarDate(2025, 6, 30)
))                                  // true
console.log(date.diffDays(other))   // 35 (days between dates)

// Arithmetic (immutable - returns new CalendarDate)
const nextWeek = date.addDays(7)           // June 22, 2025
const nextMonth = date.addMonths(1)        // July 15, 2025
const nextYear = date.addYears(1)          // June 15, 2026
const monthStart = date.startOfMonth()     // June 1, 2025
const monthEnd = date.endOfMonth()         // June 30, 2025

// Formatting with Intl.DateTimeFormat
console.log(date.format({ month: 'long', year: 'numeric' }, 'en-US'))
// "June 2025"
```

--------------------------------

### Configure Calendar for Range Selection with Min/Max Days

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This configuration sets up a date range selection where the selected range must be between a minimum of 3 days and a maximum of 10 days. Invalid endpoints are visually indicated on hover.

```html
<div x-data="calendar({
      mode: 'range',
      minRange: 3,
      maxRange: 10,
    })"></div>
```

--------------------------------

### Alpine Calendar: 2-Month Display Configuration

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Demonstrates how to display two months side-by-side for easier range selection using the `months: 2` option. This enhances usability for picking date ranges.

```html
<div x-data="calendar({ mode: 'range', months: 2 })"></div>
```

--------------------------------

### Multiple Date Selection with HTML

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Enables the selection of multiple individual dates, suitable for scheduling or marking several events. It allows for pre-setting dates and includes a `beforeSelect` callback for custom validation, such as limiting the number of selectable dates.

```html
<div x-data="calendar({
  mode: 'multiple',
  value: '2025-06-10, 2025-06-15, 2025-06-20',
  format: 'YYYY-MM-DD'
})">
  </div>

<!-- With custom validation callback -->
<div x-data="calendar({
  mode: 'multiple',
  beforeSelect(date, { mode, selectedDates, action }) {
    // Limit to maximum 5 dates
    if (action === 'select' && selectedDates.length >= 5) {
      alert('Maximum 5 dates allowed')
      return false
    }
    return true
  }
})"></div>
```

--------------------------------

### Alpine Calendar: Basic Single Date Selection

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Demonstrates the basic configuration for a single date selection mode in Alpine Calendar. This is the simplest way to initialize the calendar.

```html
<div x-data="calendar({ mode: 'single' })"></div>
```

--------------------------------

### Configure Range Presets for Calendar (JavaScript & HTML)

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Sets up an Alpine.js calendar in 'range' mode with predefined quick-select buttons for common date ranges. It imports and utilizes built-in preset factory functions like `presetToday()`, `presetLastNDays(7)`, etc. Custom presets can also be defined.

```javascript
import {
  presetToday,
  presetYesterday,
  presetLastNDays,
  presetThisWeek,
  presetLastWeek,
  presetThisMonth,
  presetLastMonth,
  presetThisYear,
  presetLastYear,
} from '@reachweb/alpine-calendar'

const customPreset = {
  label: 'Next 30 Days',
  value: () => {
    const today = CalendarDate.today()
    return [today, today.addDays(29)]
  }
}
```

```html
<div x-data="calendar({
  mode: 'range',
  presets: [
    presetToday(),
    presetLastNDays(7),
    presetThisWeek(),
    presetThisMonth(),
    presetLastMonth()
  ]
})"></div>
```

--------------------------------

### Range Presets Integration with HTML

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Integrates predefined and custom range presets into the calendar component, allowing users to select common date ranges with a single click. The `presets` array accepts preset objects generated by imported functions or custom-defined objects.

```html
<div x-data="calendar({
  mode: 'range',
  presets: [
    presetToday(),
    presetYesterday(),
    presetLastNDays(7),
    presetLastNDays(30, 'Last 30 Days'),
    presetThisWeek('This Week', 1),  // Weeks start Monday
    presetLastWeek('Last Week', 1),
    presetThisMonth(),
    presetLastMonth(),
    presetThisYear(),
    presetLastYear()
  ]
})"></div>

<!-- Custom preset -->
<script>
const customPreset = {
  label: 'Next 30 Days',
  value: () => {
    const today = CalendarDate.today()
    return [today, today.addDays(29)]
  }
}
</script>
```

--------------------------------

### Alpine Calendar: Dynamic setValue() and clear() Methods

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

Shows how to programmatically control the calendar's selected date using `setValue()` and `clear()` methods. Buttons are provided to trigger these actions on the calendar instance.

```html
<div x-data="calendar({ mode: 'single' })" x-ref="cal"></div>
<button @click="$refs.cal.setValue('2026-06-15')">Set June 15</button>
<button @click="$refs.cal.setValue('2026-12-25')">Set Dec 25</button>
<button @click="$refs.cal.clear()">Clear</button>
```

--------------------------------

### Configure Calendar with Period-Specific Rules (Seasonal Booking)

Source: https://github.com/reachweb/alpine-calendar/blob/main/demo/index.html

This advanced configuration allows different range and day-of-week constraints for specific date periods, ideal for seasonal booking systems. It defines global rules and then overrides them for summer and holiday periods using the `rules` array.

```html
<div x-data="calendar({
      mode: 'range',
      months: 2,
      minRange: 2,
      maxRange: 14,
      disabledDaysOfWeek: [0],
      rules: [
        {
          from: '2026-06-01', to: '2026-08-31',
          minRange: 7, maxRange: 21,
          disabledDaysOfWeek: [],
        },
        {
          from: '2026-12-20', to: '2027-01-05',
          minRange: 3, maxRange: 7,
          enabledDaysOfWeek: [1, 2, 3, 4, 5, 6, 0],
        }
      ],
    })"></div>
```

--------------------------------

### Date Range Selection with HTML

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Facilitates the selection of a date range with visual highlighting, hover previews, and constraints on the minimum and maximum selectable range. It supports multi-month displays and scrollable views for larger date ranges.

```html
<!-- Basic range selection with dual-month display -->
<div x-data="calendar({
  mode: 'range',
  months: 2,
  firstDay: 1
})">
</div>

<!-- Range with constraints -->
<div x-data="calendar({
  mode: 'range',
  months: 2,
  minRange: 3,
  maxRange: 14,
  minDate: '2025-01-01',
  maxDate: '2025-12-31',
  disabledDaysOfWeek: [0, 6]
})"></div>

<!-- Scrollable multi-month (3+ months) -->
<div x-data="calendar({
  mode: 'range',
  months: 6,
  scrollHeight: 500
})"></div>
```

--------------------------------

### Enable Week Numbers in Calendar (HTML)

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

Renders an Alpine.js calendar instance configured to display ISO 8601 week numbers. The `showWeekNumbers: true` option adds a narrow column to the left of the day grid for displaying these numbers. The `firstDay` option is also set.

```html
<div x-data="calendar({ mode: 'single', showWeekNumbers: true, firstDay: 1 })"></div>
```

--------------------------------

### Single Date Selection (Popup) with HTML

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Configures a calendar for single date selection that appears as a popup when an input field gains focus. It supports automatic input masking and ARIA attributes for accessibility. The `inputRef` option allows for custom referencing of the input element.

```html
<div x-data="calendar({
  mode: 'single',
  display: 'popup',
  format: 'MM/DD/YYYY',
  closeOnSelect: true
})">
  <label for="date-input">Select Date:</label>
  <input x-ref="rc-input" id="date-input" type="text" class="rc-input" placeholder="mm/dd/yyyy">
</div>

<!-- With custom input ref name -->
<div x-data="calendar({ display: 'popup', inputRef: 'myDateField' })">
  <input x-ref="myDateField" type="text" class="my-custom-input">
</div>
```

--------------------------------

### CalendarDate Class: Helper Functions

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Provides utility functions for date calculations, including determining the number of days in a month and calculating the ISO 8601 week number.

```javascript
import { daysInMonth, getISOWeekNumber, CalendarDate } from '@reachweb/alpine-calendar'

// Get days in a specific month
console.log(daysInMonth(2025, 2))   // 28 (February 2025)
console.log(daysInMonth(2024, 2))   // 29 (February 2024 - leap year)

// Get ISO 8601 week number (weeks start Monday, week 1 contains first Thursday)
const date = new CalendarDate(2025, 1, 6)
console.log(getISOWeekNumber(date))  // 2
```

--------------------------------

### Runtime Constraint Updates

Source: https://context7.com/reachweb/alpine-calendar/llms.txt

Dynamically update date constraints for the calendar after initialization without needing to recreate the component. This allows for real-time adjustments to min/max dates and disabled days of the week.

```APIDOC
## Runtime Constraint Updates

### Description
Update date constraints dynamically after initialization without recreating the calendar. This allows for real-time adjustments to `minDate`, `maxDate`, and `disabledDaysOfWeek`.

### Method
JavaScript method call on the calendar instance.

### Endpoint
N/A (Client-side JavaScript method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**updateConstraints** (object) - Required - An object containing the constraints to update.
- **minDate** (string) - Optional - The new minimum date in 'YYYY-MM-DD' format.
- **maxDate** (string) - Optional - The new maximum date in 'YYYY-MM-DD' format.
- **disabledDaysOfWeek** (array) - Optional - An array of numbers representing days of the week to disable (0 for Sunday, 6 for Saturday).

### Request Example
```javascript
// Assuming 'cal' is a reference to the calendar instance
$refs.cal.updateConstraints({
  minDate: '2025-06-01',
  maxDate: '2025-08-31',
  disabledDaysOfWeek: [0, 6]
});

// To remove all restrictions:
$refs.cal.updateConstraints({
  minDate: undefined,
  maxDate: undefined,
  disabledDaysOfWeek: undefined
});
```

### Response
#### Success Response (N/A)
This method does not return a value but updates the calendar's state.

#### Response Example
N/A
```

--------------------------------

### Dynamically Setting and Clearing Calendar Values

Source: https://github.com/reachweb/alpine-calendar/blob/main/README.md

This snippet demonstrates how to dynamically update and clear the calendar's selected date(s) after initialization using JavaScript methods. The `setValue()` method sets a specific date, and `clear()` removes any selection.

```html
<div x-data="calendar({ mode: 'single' })" x-ref="cal">
  <button @click="$refs.cal.setValue('2026-06-15')">Set June 15</button>
  <button @click="$refs.cal.clear()">Clear</button>
</div>
```