Cally

https://github.com/wickynilliams/cally
Admin
Cally is a collection of small, feature-rich calendar components for web applications.
Tokens:38,009
Snippets:397
Trust Score:9.5
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### useDayNames Usage Example

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Demonstrates retrieving localized day names with specific formatting and starting days.

```typescript
// English, Monday first, narrow format
useDayNames({ weekday: "narrow" }, 1, "en-US");
// Returns: ["M", "T", "W", "T", "F", "S", "S"]

// German, Sunday first, long format
useDayNames({ weekday: "long" }, 0, "de-DE");
// Returns: ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"]
```

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

### useDateMultiProp Usage Example

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Demonstrates reading and writing multiple dates as a space-separated string.

```typescript
const [dates, setDates] = useDateMultiProp("value");

// Read prop like: "2024-06-15 2024-06-20 2024-07-01"
// Returns: [PlainDate(2024, 6, 15), PlainDate(2024, 6, 20), PlainDate(2024, 7, 1)]

setDates([new PlainDate(2024, 6, 15), new PlainDate(2024, 6, 20)]);
// Sets prop to: "2024-06-15 2024-06-20"
```

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

### useDateFormatter Usage Example

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Demonstrates creating memoized formatters for different locales.

```typescript
const formatter = useDateFormatter({ month: "long", year: "numeric" }, "en-US");
formatter.format(new Date()); // "June 2024"

const deFormatter = useDateFormatter({ month: "long", year: "numeric" }, "de-DE");
deFormatter.format(new Date()); // "Juni 2024"
```

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

### Calendar Component Integration Examples

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-year-month-select.md

Demonstrates standalone usage and combined configurations for year, month, and date picker components.

```html
<!-- Standalone year selector -->
<calendar-select-year maxYears="10"></calendar-select-year>

<!-- Combo: Year/Month dropdowns + Date picker -->
<calendar-select-year></calendar-select-year>
<calendar-select-month></calendar-select-month>
<calendar-date months="1"></calendar-date>

<!-- Full setup: Navigation + Calendar -->
<div class="full-calendar">
  <calendar-select-year maxYears="20"></calendar-select-year>
  <calendar-select-month formatMonth="long"></calendar-select-month>
  <calendar-date months="2"></calendar-date>
</div>
```

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

### Basic Range Picker Implementation

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-range.md

Demonstrates initializing a range picker and listening for start, end, and change events to track user selection.

```html
<calendar-range id="range-picker"></calendar-range>

<script>
const picker = document.querySelector('#range-picker');
let startDate = null;

picker.addEventListener('rangestart', (e) => {
  startDate = e.detail;
  console.log('Range start:', startDate);
});

picker.addEventListener('rangeend', (e) => {
  console.log('Range end:', e.detail);
  console.log('Full range:', startDate, 'to', e.detail);
});

picker.addEventListener('change', () => {
  console.log('Selected range:', picker.getAttribute('value'));
});
</script>
```

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

### Focus Method Usage

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-date.md

Examples of programmatically focusing elements within the calendar.

```typescript
const cal = document.querySelector('calendar-date');

// Focus the currently active day
cal.focus();

// Focus the next button
cal.focus({ target: "next" });

// Focus without scrolling
cal.focus({ target: "day", preventScroll: true });
```

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

### Install Cally via npm

Source: https://github.com/wickynilliams/cally/blob/main/README.md

Use this command to add the Cally package to your project dependencies.

```bash
npm install cally
```

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

### Integrate Cally with Frameworks

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/package-reference.md

Examples for using exported prop types with React and Vue components.

```typescript
// For React integration
import { CalendarDateProps } from "cally";

function MyDatePicker(props: CalendarDateProps) {
  return <calendar-date {...props} />;
}

// For Vue integration
import { CalendarDateProps } from "cally";

export default {
  props: CalendarDateProps,
  template: '<calendar-date v-bind="$props" />'
};
```

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

### Meeting Scheduler Implementation

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-multi.md

Demonstrates a multi-month calendar setup with custom styling for selected dates and a save functionality that sends selected dates to an API.

```html
<div class="scheduler">
  <h2>Select Available Time Slots</h2>
  <calendar-multi 
    id="availability"
    locale="en-US"
    months="2"
    min="2024-06-01"
    max="2024-08-31"
  ></calendar-multi>
  <button id="save">Save Availability</button>
</div>

<style>
  .scheduler {
    padding: 2rem;
    max-width: 600px;
  }
  
  calendar-multi::part(button selected) {
    background: linear-gradient(135deg, #10b981, #34d399);
    color: white;
    border-radius: 4px;
  }
  
  calendar-multi::part(button today) {
    outline: 2px solid #f59e0b;
    outline-offset: -2px;
  }
  
  calendar-multi::part(button outside) {
    opacity: 0.2;
  }
  
  #save {
    margin-top: 2rem;
    padding: 0.75rem 1.5rem;
    background: #2563eb;
    color: white;
    border: none;
    border-radius: 4px;
    cursor: pointer;
    font-size: 1rem;
  }
  
  #save:hover {
    background: #1d4ed8;
  }
</style>

<script>
const cal = document.querySelector('#availability');
const saveBtn = document.querySelector('#save');

cal.addEventListener('change', () => {
  const dates = cal.getAttribute('value');
  const count = dates ? dates.split(/\s+/).length : 0;
  saveBtn.textContent = `Save Availability (${count} dates)`;
});

saveBtn.addEventListener('click', () => {
  const dates = cal.getAttribute('value').split(/\s+/).filter(Boolean);
  console.log('Saving availability:', dates);
  
  fetch('/api/availability', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ dates })
  })
  .then(r => r.json())
  .then(data => alert('Availability saved!'))
  .catch(e => alert('Error: ' + e.message));
});
</script>
```

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

### Implement CalendarHeadingContext Provider

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-heading.md

Examples of providing context for single date views and date range views.

```typescript
// Single date (single month view)
<CalendarHeadingContext.Provider 
  value={{ 
    type: "date", 
    value: new PlainYearMonth(2024, 6),
    locale: "en-US"
  }}
>
  <CalendarHeading month="long" year="numeric" />
  <!-- Output: "June 2024" -->
</CalendarHeadingContext.Provider>

// Date range (multi-month view)
<CalendarHeadingContext.Provider 
  value={{ 
    type: "range", 
    value: { 
      start: new PlainYearMonth(2024, 6),
      end: new PlainYearMonth(2024, 8)
    },
    locale: "en-US"
  }}
>
  <CalendarHeading month="long" year="numeric" />
  <!-- Output: "June 2024 – August 2024" -->
</CalendarHeadingContext.Provider>
```

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

### Custom Hook Usage Example

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Demonstrates usage of date utilities and hooks within a React component.

```typescript
// MyComponent.tsx
import { PlainDate } from "cally";
import { getToday, endOfMonth, getWeekNumber } from "cally/src/utils/date";
import { useDateFormatter, useDateProp } from "cally/src/utils/hooks";

function MyCalendarComponent() {
  const [value, setValue] = useDateProp("value");
  const formatter = useDateFormatter({ month: "long", year: "numeric" });
  
  const today = getToday();
  const monthEnd = endOfMonth(today);
  const week = getWeekNumber(today);
  
  return (
    <div>
      <p>Today: {formatter.format(new Date(today.toString()))}</p>
      <p>Week: {week}</p>
      <p>Month ends: {monthEnd.toString()}</p>
      {value && <p>Selected: {formatter.format(new Date(value.toString()))}</p>}
    </div>
  );
}
```

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

### Flight Search with Year/Month/Day

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-year-month-select.md

Example of a flight booking interface using constrained date ranges and custom layout.

```html
<div class="flight-search">
  <h2>Book Your Flight</h2>
  
  <label>Departure Date</label>
  <div class="date-nav">
    <calendar-select-year maxYears="5"></calendar-select-year>
    <calendar-select-month formatMonth="short"></calendar-select-month>
  </div>
  <calendar-date 
    id="departure"
    locale="en-US"
    min="2024-06-01"
    max="2024-12-31"
  ></calendar-date>
  
  <button id="search">Search Flights</button>
</div>

<style>
  .date-nav {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 1rem;
    margin-bottom: 1.5rem;
  }
  
  calendar-select-year::part(select),
  calendar-select-month::part(select) {
    width: 100%;
    padding: 0.5rem;
  }
  
  #search {
    width: 100%;
    padding: 1rem;
    background: #059669;
    color: white;
    border: none;
    border-radius: 4px;
    font-size: 1rem;
    cursor: pointer;
    margin-top: 2rem;
  }
</style>

<script>
document.querySelector('#search').addEventListener('click', () => {
  const date = document.querySelector('#departure').getAttribute('value');
  if (date) {
    console.log('Searching for flights on:', date);
  }
});
</script>
```

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

### useDateRangeProp Usage Example

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Demonstrates reading and writing a date range property formatted as YYYY-MM-DD/YYYY-MM-DD.

```typescript
const [range, setRange] = useDateRangeProp("value");

// Read prop like: "2024-06-15/2024-06-20"
// Returns: [PlainDate(2024, 6, 15), PlainDate(2024, 6, 20)]

setRange([new PlainDate(2024, 6, 15), new PlainDate(2024, 6, 20)]);
// Sets prop to: "2024-06-15/2024-06-20"
```

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

### Implement a Date Range Picker with Constraints

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/QUICKSTART.md

Use calendar-range to select a start and end date within specified min and max bounds.

```html
<calendar-range
  id="trip"
  min="2024-06-01"
  max="2024-08-31"
  months="2"
  locale="en-US"
></calendar-range>

<script>
  document.querySelector('#trip').addEventListener('change', (e) => {
    const range = e.target.getAttribute('value');
    const [start, end] = range.split('/');
    // Book dates
  });
</script>
```

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

### useDateProp Usage Example

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Demonstrates binding a date property and updating it using the returned setter.

```typescript
const [value, setValue] = useDateProp("value");

// Bind to prop value
// Read: PlainDate or undefined
// Write: PlainDate or undefined
setValue(new PlainDate(2024, 6, 15)); // Sets prop to "2024-06-15"
```

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

### Apply Locale-Specific Formatting

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-heading.md

Examples of using the locale attribute to localize calendar heading output.

```html
<!-- English (US) -->
<calendar-heading month="long" year="numeric"></calendar-heading>
<!-- Output: "June 2024" -->

<!-- German -->
<calendar-heading month="long" year="numeric" locale="de-DE"></calendar-heading>
<!-- Output: "Juni 2024" -->

<!-- French -->
<calendar-heading month="long" year="numeric" locale="fr-FR"></calendar-heading>
<!-- Output: "juin 2024" -->

<!-- Japanese -->
<calendar-heading month="long" year="numeric" locale="ja-JP"></calendar-heading>
<!-- Output: "2024年6月" -->
```

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

### startOfWeek(date, firstDayOfWeek)

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Determines the first day of the week for a given date, with an optional parameter to define the start of the week.

```APIDOC
## startOfWeek(date, firstDayOfWeek)

### Description
Returns the PlainDate representing the first day of the week containing the provided date.

### Parameters
- **date** (PlainDate) - Required - The reference date.
- **firstDayOfWeek** (DaysOfWeek) - Optional - The first day of the week (0=Sunday). Defaults to 0.
```

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

### Value Binding Examples

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-range.md

Demonstrates the ISO 8601 date range format used by the value attribute, noting that the component automatically sorts dates.

```typescript
// No selection
value: ""

// Complete range (automatically sorted)
value: "2024-06-15/2024-06-20"

// If clicked in reverse order, still sorted correctly
// Click 2024-06-20 then 2024-06-15 → value: "2024-06-15/2024-06-20"
```

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

### Integrate Cally with Vue

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/package-reference.md

Uses script setup to bind the value and handle change events for the calendar-date component.

```vue
<template>
  <calendar-date 
    :value="selectedDate"
    @change="onDateChange"
  />
</template>

<script setup>
import { ref } from 'vue';
import 'cally';

const selectedDate = ref('2024-06-15');

function onDateChange(event) {
  selectedDate.value = event.target.getAttribute('value');
}
</script>
```

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

### Import Internal Modules

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/module-structure.md

Examples of internal module imports that are not recommended for external use.

```typescript
import { CalendarMonth } from "cally";  // Available but internal usage
import { useCalendarBase } from "cally/src/calendar-base/useCalendarBase";  // Not exported
import { PlainDate } from "cally/src/utils/temporal";  // Not exported
// ... etc
```

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

### Styling Calendar Range with CSS Parts

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-range.md

Shows how to use CSS ::part selectors to style the start, end, and inner dates of a selected range.

```html
<calendar-range></calendar-range>

<style>
  calendar-range::part(button range-start) {
    background: #2563eb;
    color: white;
    border-radius: 4px 0 0 4px;
  }
  
  calendar-range::part(button range-inner) {
    background: #e0f2fe;
    color: inherit;
  }
  
  calendar-range::part(button range-end) {
    background: #2563eb;
    color: white;
    border-radius: 0 4px 4px 0;
  }
  
  /* Styling during preview (hover while tentative is set) */
  calendar-range::part(button selected) {
    background: #e0f2fe;
  }
</style>
```

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

### Get week boundaries with startOfWeek and endOfWeek

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Calculates the start or end date of the week containing the reference date, with configurable first day of the week.

```typescript
export function startOfWeek(
  date: PlainDate,
  firstDayOfWeek?: DaysOfWeek = 0
): PlainDate
```

```typescript
const date = new PlainDate(2024, 6, 15); // Saturday
startOfWeek(date, 0); // PlainDate(2024, 6, 9) - Sunday
startOfWeek(date, 1); // PlainDate(2024, 6, 10) - Monday
```

```typescript
export function endOfWeek(
  date: PlainDate,
  firstDayOfWeek?: DaysOfWeek = 0
): PlainDate
```

```typescript
const date = new PlainDate(2024, 6, 15);
endOfWeek(date, 0); // PlainDate(2024, 6, 15) - Saturday
endOfWeek(date, 1); // PlainDate(2024, 6, 16) - Sunday
```

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

### View Package Build Output

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/package-reference.md

Structure of the generated distribution files.

```text
dist/
  ├── cally.js           # Main module (ESM)
  ├── cally.d.ts         # TypeScript declarations
  └── cally.js.map       # Source maps
```

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

### Year and Month Quick Navigation

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-year-month-select.md

Demonstrates how to synchronize year and month select components with a calendar-date picker using the focusday event.

```html
<div class="calendar-nav">
  <calendar-select-year 
    id="year-select" 
    maxYears="50"
  ></calendar-select-year>
  
  <calendar-select-month 
    id="month-select" 
    formatMonth="short"
  ></calendar-select-month>
  
  <calendar-date id="picker"></calendar-date>
</div>

<style>
  .calendar-nav {
    display: flex;
    gap: 1rem;
    margin-bottom: 2rem;
  }
  
  calendar-select-year,
  calendar-select-month {
    flex: 1;
  }
  
  calendar-select-year::part(label),
  calendar-select-month::part(label) {
    display: block;
    margin-bottom: 0.5rem;
    font-weight: 600;
    font-size: 0.875rem;
    text-transform: uppercase;
    letter-spacing: 0.05em;
    color: #666;
  }
  
  calendar-select-year::part(select),
  calendar-select-month::part(select) {
    width: 100%;
    padding: 0.75rem;
    border: 2px solid #e5e7eb;
    border-radius: 6px;
    font-size: 1rem;
    background: white;
    cursor: pointer;
  }
  
  calendar-select-year::part(select):hover,
  calendar-select-month::part(select):hover {
    border-color: #2563eb;
  }
</style>

<script>
const picker = document.querySelector('#picker');
const yearSelect = document.querySelector('#year-select');
const monthSelect = document.querySelector('#month-select');

// When year select changes, picker auto-updates via focusday event
yearSelect.addEventListener('focusday', (e) => {
  picker.setAttribute('focusedDate', e.detail);
});

// When month select changes, picker auto-updates
monthSelect.addEventListener('focusday', (e) => {
  picker.setAttribute('focusedDate', e.detail);
});

// Update selectors when picker's focused date changes
picker.addEventListener('focusday', (e) => {
  const date = e.detail;
  const iso = date.toISOString().split('T')[0];
  // Selectors will update based on the new focused date
});
</script>
```

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

### View Project File Structure

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/README.md

Displays the directory layout of the Cally project documentation.

```text
output/
├── README.md                          (this file)
├── QUICKSTART.md                      (essential reference)
├── api-index.md                       (complete API index)
├── calendar-date.md                   (single date picker)
├── calendar-range.md                  (date range picker)
├── calendar-multi.md                  (multiple date picker)
├── calendar-month.md                  (month grid)
├── calendar-heading.md                (heading component)
├── calendar-year-month-select.md      (year/month selectors)
├── calendar-base.md                   (internal base component)
├── types.md                           (type definitions)
├── utilities.md                       (utility functions)
└── package-reference.md               (package information)
```

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

### Initialize Cally components

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/QUICKSTART.md

Import the module to register the custom elements for use in your HTML.

```html
<!-- HTML -->
<script type="module">
  import "cally";
</script>

<!-- Components are now available -->
<calendar-date value="2024-06-15"></calendar-date>
```

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

### Event Dates Selection Implementation

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-multi.md

Shows how to initialize the calendar with pre-selected dates, display them in a list, and allow users to remove dates via the UI.

```html
<div class="event-selector">
  <h3>Select Event Dates</h3>
  <p>You have selected <span id="count">0</span> dates</p>
  <calendar-multi 
    id="events"
    value="2024-07-04 2024-07-11 2024-07-18"
    min="2024-07-01"
    max="2024-07-31"
    showWeekNumbers="true"
  ></calendar-multi>
  <ul id="selected-list"></ul>
</div>

<style>
  .event-selector {
    background: #f9fafb;
    padding: 1.5rem;
    border-radius: 8px;
  }
  
  calendar-multi::part(button selected) {
    background: #f97316;
    color: white;
    border-radius: 50%;
    width: 2.25rem;
    height: 2.25rem;
    display: flex;
    align-items: center;
    justify-content: center;
  }
  
  #selected-list {
    list-style: none;
    padding: 0;
    margin-top: 1rem;
  }
  
  #selected-list li {
    padding: 0.5rem;
    background: white;
    border: 1px solid #e5e7eb;
    border-radius: 4px;
    margin: 0.25rem 0;
  }
</style>

<script>
const cal = document.querySelector('#events');
const count = document.querySelector('#count');
const list = document.querySelector('#selected-list');

function updateDisplay() {
  const dates = cal.getAttribute('value').split(/\s+/).filter(Boolean);
  count.textContent = dates.length;
  
  list.innerHTML = dates.map(date => {
    const d = new Date(date + 'T00:00:00Z');
    const formatted = new Intl.DateTimeFormat('en-US', {
      weekday: 'short',
      month: 'short',
      day: 'numeric'
    }).format(d);
    
    return `<li>${formatted} <button data-date="${date}">×</button></li>`;
  }).join('');
  
  // Add remove listeners
  list.querySelectorAll('button').forEach(btn => {
    btn.addEventListener('click', () => {
      const dateToRemove = btn.dataset.date;
      const current = cal.getAttribute('value').split(/\s+/).filter(Boolean);
      const updated = current.filter(d => d !== dateToRemove).join(' ');
      cal.setAttribute('value', updated);
    });
  });
}

cal.addEventListener('change', updateDisplay);
updateDisplay(); // Initial
</script>
```

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

### Configure Cally components via HTML attributes

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/package-reference.md

Demonstrates setting string, boolean, and numeric attributes, as well as assigning function properties via JavaScript.

```html
<!-- String attributes -->
<calendar-date 
  value="2024-06-15"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-US"
/>

<!-- Boolean attributes -->
<calendar-month 
  showOutsideDays
  showWeekNumbers
/>

<!-- Numeric attributes -->
<calendar-date 
  months="2"
  firstDayOfWeek="1"
/>

<!-- Function properties (set via JavaScript) -->
<script>
  const cal = document.querySelector('calendar-date');
  cal.isDateDisallowed = (date) => date.getUTCDay() === 0;
</script>
```

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

### Apply constraints and custom styling

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-date.md

Configure min/max dates and use CSS shadow parts to style navigation buttons and date states.

```html
<calendar-date
  value="2024-06-15"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-US"
  months="1"
  firstDayOfWeek="0"
></calendar-date>

<style>
  calendar-date {
    display: block;
    margin: 2rem;
  }
  
  /* Style navigation buttons */
  calendar-date::part(button previous),
  calendar-date::part(button next) {
    padding: 0.5rem;
    background: #f0f0f0;
    border: 1px solid #ccc;
    border-radius: 4px;
  }
  
  /* Style selected date */
  calendar-date::part(button selected) {
    background: #0070f3;
    color: white;
    font-weight: bold;
  }
  
  /* Style disabled dates */
  calendar-date::part(button disabled) {
    opacity: 0.5;
    cursor: not-allowed;
  }
</style>
```

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

### Get current date with getToday

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Retrieves the current date as a PlainDate object in the local timezone.

```typescript
export function getToday(): PlainDate
```

```typescript
const today = getToday();
console.log(today.toString()); // "2024-06-15" (today's date)
```

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

### Implement a custom calendar with pagination

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-base.md

Configures a calendar-date element with multi-month pagination and demonstrates how to style internal parts and handle component events.

```html
<calendar-date
  id="my-cal"
  months="2"
  pageBy="months"
  locale="en-US"
  firstDayOfWeek="0"
></calendar-date>

<style>
  calendar-date {
    display: block;
    margin: 2rem;
  }
  
  /* Style header */
  calendar-date::part(container) {
    border: 1px solid #e5e7eb;
    border-radius: 8px;
    padding: 1rem;
  }
  
  /* Style navigation buttons */
  calendar-date::part(header) {
    border-bottom: 2px solid #f0f0f0;
    padding-bottom: 1rem;
    margin-bottom: 1rem;
  }
  
  calendar-date::part(button) {
    padding: 0.5rem 1rem;
    background: #f9fafb;
    border: 1px solid #e5e7eb;
    border-radius: 4px;
    cursor: pointer;
  }
  
  calendar-date::part(button):hover {
    background: #f3f4f6;
  }
  
  calendar-date::part(button disabled) {
    background: #f9fafb;
    cursor: not-allowed;
    opacity: 0.5;
  }
  
  /* Style heading */
  calendar-date::part(heading) {
    text-align: center;
    font-size: 1.5rem;
    font-weight: 600;
  }
  
  /* Style months container */
  calendar-date::part(months) {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 2rem;
  }
</style>

<script>
const cal = document.querySelector('#my-cal');

// Track page changes
cal.addEventListener('pagechange', (e) => {
  console.log(`Showing ${e.detail.start} to ${e.detail.end}`);
});

// Handle selection
cal.addEventListener('change', () => {
  const date = cal.getAttribute('value');
  console.log('Selected:', date);
});

// Keyboard shortcuts
document.addEventListener('keydown', (e) => {
  if (e.key === 'n') {
    // Press 'n' to go to next month
    cal.focus({ target: 'next' });
  }
  if (e.key === 'p') {
    // Press 'p' to go to previous month
    cal.focus({ target: 'previous' });
  }
});
</script>
```

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

### Get end of month with endOfMonth

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/utilities.md

Returns the last day of the specified month, accounting for leap years.

```typescript
export function endOfMonth(date: { year: number; month: number }): PlainDate
```

```typescript
endOfMonth({ year: 2024, month: 6 }); // PlainDate(2024, 6, 30)
endOfMonth({ year: 2024, month: 2 }); // PlainDate(2024, 2, 29) - leap year
endOfMonth({ year: 2023, month: 2 }); // PlainDate(2023, 2, 28)
```

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

### Implement Year and Month Navigation

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/QUICKSTART.md

Combine calendar-select-year and calendar-select-month components for quick navigation.

```html
<div class="date-picker">
  <calendar-select-year maxYears="20"></calendar-select-year>
  <calendar-select-month formatMonth="short"></calendar-select-month>
  <calendar-date months="1"></calendar-date>
</div>

<style>
  .date-picker {
    display: flex;
    gap: 1rem;
  }
  
  calendar-select-year,
  calendar-select-month {
    flex: 1;
  }
</style>
```

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

### Implement Calendar Month Component

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-month.md

Demonstrates basic usage of the calendar-month element, including event handling for user interactions and CSS styling via shadow parts.

```html
<calendar-month offset="0"></calendar-month>

<script>
const month = document.querySelector('calendar-month');

// Listen to date selection
month.addEventListener('selectday', (e) => {
  console.log('Selected date:', e.detail);
});

// Listen to focus changes (keyboard navigation)
month.addEventListener('focusday', (e) => {
  console.log('Focused date:', e.detail);
});

// Programmatically focus first selectable date
month.focus();

// Style with parts
const style = document.createElement('style');
style.textContent = `
  calendar-month::part(button selected) {
    background: #2563eb;
    color: white;
  }
  calendar-month::part(button today) {
    border: 2px solid currentColor;
  }
`;
document.head.appendChild(style);
</script>
```

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

### calendar-range Component Events

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-range.md

The calendar-range component emits events to signal the start, end, and completion of a date range selection.

```APIDOC
## Component Events

### rangestart
Emitted when a user clicks a date to begin a new range selection. The event detail contains the selected Date object.

### rangeend
Emitted when a user clicks a second date to complete a range selection. The event detail contains the selected Date object.

### change
Emitted when the range selection is finalized. The component's `value` attribute is updated to the format "YYYY-MM-DD/YYYY-MM-DD".
```

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

### Define PageChangeDetail interface

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/types.md

Represents the event detail emitted when the calendar page changes, containing UTC start and end dates.

```typescript
interface PageChangeDetail {
  start: Date;  // First day of page in UTC
  end: Date;    // Last day of page in UTC
}
```

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

### Implement a basic date picker

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-date.md

Use the calendar-date element to capture user date selection via the change event.

```html
<calendar-date id="picker" value="2024-06-15"></calendar-date>

<script>
const picker = document.querySelector('#picker');

picker.addEventListener('change', () => {
  const date = picker.getAttribute('value');
  console.log('User selected:', date);
  // Send to server
  fetch('/api/save-date', { 
    method: 'POST', 
    body: JSON.stringify({ date })
  });
});
</script>
```

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

### Configure Holiday Blackout Selection

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-multi.md

Demonstrates how to use getDayParts and isDateDisallowed to mark weekends and disable specific holiday dates.

```html
<calendar-multi
  id="blackout"
  locale="en-US"
  months="6"
></calendar-multi>

<script>
const cal = document.querySelector('#blackout');

// Mark weekends
cal.getDayParts = (date) => {
  const day = date.getUTCDay();
  if (day === 0 || day === 6) return 'weekend';
  return '';
};

// Disable holidays
const holidays = ['2024-07-04', '2024-07-25'];

cal.isDateDisallowed = (date) => {
  const iso = date.toISOString().split('T')[0];
  return holidays.includes(iso);
};

cal.addEventListener('change', () => {
  const selected = cal.getAttribute('value');
  console.log('Blackout dates:', selected);
});
</script>

<style>
  calendar-multi::part(button weekend) {
    color: #666;
    opacity: 0.7;
  }
  
  calendar-multi::part(button selected) {
    background: #dc2626;
    color: white;
  }
  
  calendar-multi::part(button disallowed) {
    opacity: 0.4;
    text-decoration: line-through;
  }
</style>
```

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

### useCalendarBase(options: CalendarBaseOptions)

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-base.md

Initializes the calendar base state and returns navigation controls and view properties.

```APIDOC
## useCalendarBase(options: CalendarBaseOptions)

### Description
Initializes the calendar state, providing pagination logic, focused date management, and navigation methods.

### Parameters
- **months** (number) - Required - Number of months displayed at once.
- **pageBy** ("single" | "months") - Required - How many months to advance per page.
- **locale** (string) - Optional - BCP 47 language tag.
- **focusedDate** (PlainDate | undefined) - Required - Currently focused date.
- **setFocusedDate** (function) - Required - Callback to update focused date.

### Return Value
- **page** (object) - Start and end months of current view.
- **focusedDate** (PlainDate) - Currently focused date.
- **dispatch** (function) - Emit change event.
- **onFocus** (function) - Handle focus changes.
- **min** (PlainDate) - Minimum selectable date.
- **max** (PlainDate) - Maximum selectable date.
- **today** (PlainDate) - Today's date.
- **next** (function) - Go to next page.
- **previous** (function) - Go to previous page.
- **focus** (function) - Programmatically focus an element.
```

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

### Travel Date Booking Flow

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-range.md

Shows how to configure constraints like min/max dates and use CSS shadow parts to style the calendar interface.

```html
<div class="booking">
  <h2>Select Travel Dates</h2>
  <calendar-range 
    id="dates"
    min="2024-06-01"
    max="2024-12-31"
    locale="en-US"
    months="2"
  ></calendar-range>
  <button id="confirm" disabled>Confirm Booking</button>
</div>

<style>
  .booking {
    padding: 2rem;
  }
  
  calendar-range::part(button range-start),
  calendar-range::part(button range-end) {
    background: #10b981;
    color: white;
    font-weight: bold;
  }
  
  calendar-range::part(button range-inner) {
    background: #d1fae5;
  }
  
  calendar-range::part(button today) {
    border: 2px solid currentColor;
  }
  
  calendar-range::part(button outside) {
    opacity: 0.3;
  }
</style>

<script>
const cal = document.querySelector('#dates');
const confirm = document.querySelector('#confirm');

cal.addEventListener('rangestart', () => {
  confirm.disabled = true;
  console.log('Range started');
});

cal.addEventListener('rangeend', (e) => {
  confirm.disabled = false;
  console.log('Range complete, can confirm');
});

confirm.addEventListener('click', () => {
  const range = cal.getAttribute('value');
  const [start, end] = range.split('/');
  console.log(`Booking from ${start} to ${end}`);
  
  // Submit to server
  fetch('/api/book', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ checkIn: start, checkOut: end })
  });
});
</script>
```

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

### Value Binding

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-range.md

The value attribute represents the selected date range as an ISO 8601 string with a forward slash separator. The component automatically sorts the dates so the start date always precedes the end date.

```APIDOC
## Value Binding

### Description
The `value` attribute holds the selected date range as an ISO 8601 string (e.g., "2024-06-15/2024-06-20"). The component automatically sorts the dates regardless of selection order.

### Attribute
- **value** (string) - The selected date range in ISO 8601 format with a forward slash separator.
```

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

### Implement Two-Way Value Binding

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-date.md

Use the value attribute for initial state and listen for the change event to track user updates.

```html
<!-- Set initial value -->
<calendar-date value="2024-06-15"></calendar-date>

<script>
const cal = document.querySelector('calendar-date');

// Read current value
console.log(cal.getAttribute('value')); // "2024-06-15"

// Update value
cal.setAttribute('value', '2024-07-01');

// Listen for changes
cal.addEventListener('change', () => {
  console.log('New value:', cal.getAttribute('value'));
});
</script>
```

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

### Implement a Shift Planner with calendar-multi

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-multi.md

Uses the calendar-multi component to allow users to select multiple working days, with custom styling and submission logic.

```html
<div class="shift-planner">
  <h2>Select Working Days</h2>
  <p>Click to select/deselect days you can work</p>
  
  <calendar-multi
    id="shifts"
    locale="en-US"
    firstDayOfWeek="1"
    showWeekNumbers="true"
    months="3"
  ></calendar-multi>
  
  <div class="summary">
    <p>Total days selected: <strong id="total">0</strong></p>
    <button id="clear">Clear All</button>
    <button id="submit">Submit Schedule</button>
  </div>
</div>

<style>
  .shift-planner {
    padding: 2rem;
  }
  
  calendar-multi::part(button selected) {
    background: #065f46;
    color: white;
    font-weight: bold;
  }
  
  .summary {
    margin-top: 2rem;
    padding: 1rem;
    background: #f0fdf4;
    border: 1px solid #86efac;
    border-radius: 4px;
  }
  
  .summary button {
    margin-right: 0.5rem;
    padding: 0.5rem 1rem;
    border: none;
    border-radius: 4px;
    cursor: pointer;
  }
  
  #submit {
    background: #16a34a;
    color: white;
  }
  
  #submit:hover {
    background: #15803d;
  }
  
  #clear {
    background: #ef4444;
    color: white;
  }
  
  #clear:hover {
    background: #dc2626;
  }
</style>

<script>
const cal = document.querySelector('#shifts');
const totalEl = document.querySelector('#total');
const clearBtn = document.querySelector('#clear');
const submitBtn = document.querySelector('#submit');

function updateSummary() {
  const dates = cal.getAttribute('value').split(/\s+/).filter(Boolean);
  totalEl.textContent = dates.length;
}

cal.addEventListener('change', updateSummary);
updateSummary();

clearBtn.addEventListener('click', () => {
  cal.setAttribute('value', '');
});

submitBtn.addEventListener('click', () => {
  const dates = cal.getAttribute('value').split(/\s+/).filter(Boolean);
  
  if (dates.length === 0) {
    alert('Please select at least one day');
    return;
  }
  
  console.log('Submitting schedule:', dates);
  fetch('/api/schedule', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ workDays: dates })
  })
  .then(() => alert('Schedule submitted!'))
  .catch(e => alert('Error: ' + e.message));
});
</script>
```

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

### Visualize Dependency Graph

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/module-structure.md

A tree representation of the module dependencies within the cally project.

```text
index.ts
 ├─> CalendarDate
 │    └─> calendar-base
 │         ├─> calendar-month
 │         │    ├─> calendar-heading
 │         │    ├─> useCalendarMonth
 │         │    ├─> CalendarMonthContext
 │         │    └─> utils/date, utils/temporal, utils/hooks, utils/styles
 │         ├─> useCalendarBase
 │         ├─> utils/date, utils/temporal, utils/hooks, utils/styles
 │         └─> calendar-heading (via base)
 │    └─> utils/hooks, utils/temporal
 │
 ├─> CalendarRange
 │    └─> calendar-base (see above)
 │    └─> utils/hooks, utils/date, utils/temporal
 │
 ├─> CalendarMulti
 │    └─> calendar-base (see above)
 │    └─> utils/hooks, utils/temporal
 │
 ├─> CalendarMonth
 │    └─> (see calendar-base above)
 │
 ├─> CalendarHeading
 │    └─> (see calendar-base above)
 │
 ├─> CalendarSelectYear
 │    └─> calendar-month -> CalendarContext
 │    └─> utils/temporal
 │
 └─> CalendarSelectMonth
      └─> calendar-month -> CalendarContext
      └─> utils/hooks, utils/temporal
```

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

### Load Cally via CDN

Source: https://github.com/wickynilliams/cally/blob/main/README.md

Include this script tag in your HTML to load the library directly from a CDN.

```html
<script type="module" src="https://unpkg.com/cally"></script>
```

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

### Configure Localization

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/QUICKSTART.md

Set the locale and first day of the week attributes to adapt the calendar to different regions.

```javascript
// English (US)
cal.setAttribute('locale', 'en-US');
cal.setAttribute('firstDayOfWeek', '0'); // Sunday first

// German
cal.setAttribute('locale', 'de-DE');
cal.setAttribute('firstDayOfWeek', '1'); // Monday first

// French
cal.setAttribute('locale', 'fr-FR');

// Japanese
cal.setAttribute('locale', 'ja-JP');
```

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

### Import CalendarHeading

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-heading.md

Import the component from the main package.

```typescript
import { CalendarHeading } from "cally";
```

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

### PlainYearMonth Constructor

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/types.md

Initializes a new instance of the PlainYearMonth class with a specified year and month.

```APIDOC
## constructor(year: number, month: number)

### Description
Creates a new PlainYearMonth object representing a specific year and month.

### Parameters
- **year** (number) - Required - The year (e.g., 2024).
- **month** (number) - Required - The month (1-12).
```

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

### Project Directory Structure

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/module-structure.md

Visual representation of the source code hierarchy and module locations.

```text
src/
├── index.ts                           # Main entry point - exports all public components
├── calendar-base/
│   ├── calendar-base.tsx              # Base component coordinating month views + pagination
│   └── useCalendarBase.ts             # Hook for pagination, focus, page changes
├── calendar-month/
│   ├── calendar-month.tsx             # Month grid display component
│   ├── useCalendarMonth.ts            # Hook for month view state and day properties
│   └── CalendarMonthContext.ts        # Calendar context provider and types
├── calendar-date/
│   └── calendar-date.tsx              # Single date picker
├── calendar-range/
│   └── calendar-range.tsx             # Date range picker
├── calendar-multi/
│   └── calendar-multi.tsx             # Multiple date picker
├── calendar-heading/
│   ├── calendar-heading.tsx           # Localized date/range heading
│   └── CalendarHeadingContext.ts      # Heading context provider and types
├── calendar-year-month/
│   ├── calendar-select-year.tsx       # Year dropdown selector
│   ├── calendar-select-month.tsx      # Month dropdown selector
│   └── calendar-year-month-base.tsx   # Shared SelectBase component and types
├── utils/
│   ├── date.ts                        # Date arithmetic and calendar view generation
│   ├── temporal.ts                    # PlainDate and PlainYearMonth classes
│   ├── hooks.ts                       # Atomico hooks for date binding and formatting
│   ├── styles.ts                      # Shared CSS utilities
│   ├── test.ts                        # Testing utilities
│   └── temporal.test.ts               # Tests for PlainDate/PlainYearMonth
├── globals.d.ts                       # TypeScript global declarations
└── docs/                              # Documentation site (Astro)
```

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

### Implement CalendarHeading in CalendarMonth

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-heading.md

Configure the component for accessibility and visual display within a calendar month view.

```html
<calendar-month>
  <!-- Hidden heading for accessibility -->
  <calendar-heading id="h" month="long" class="vh" />
  
  <!-- Visible heading (can be slotted) -->
  <slot name="heading" part="heading">
    <calendar-heading month="long" aria-hidden="true" />
  </slot>
  
  <!-- Month table labeled to this heading -->
  <table aria-labelledby="h">
    <!-- ... -->
  </table>
</calendar-month>
```

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

### Implement CalendarHeading in CalendarBase

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/calendar-heading.md

Configure the component for the main calendar header with ARIA live regions.

```html
<calendar-base>
  <!-- ARIA heading for screen readers -->
  <calendar-heading 
    id="h" 
    month="long" 
    year="numeric"
    aria-live="polite"
    aria-atomic="true"
  />
  
  <!-- Visible heading -->
  <slot name="heading">
    <calendar-heading year="numeric" aria-hidden="true" />
  </slot>
</calendar-base>
```

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

### Cally Entry Point Exports

Source: https://github.com/wickynilliams/cally/blob/main/_autodocs/package-reference.md

The main entry point exports all calendar components and their associated TypeScript props types.

```typescript
// Component exports
export { CalendarMonth };
export { CalendarDate };
export { CalendarSelectYear };
export { CalendarSelectMonth };
export { CalendarRange };
export { CalendarMulti };
export { CalendarHeading };

// Props type exports for framework integration
export type CalendarMonthProps = ComponentProps<typeof CalendarMonth>;
export type CalendarDateProps = ComponentProps<typeof CalendarDate>;
export type CalendarRangeProps = ComponentProps<typeof CalendarRange>;
export type CalendarMultiProps = ComponentProps<typeof CalendarMulti>;
export type CalendarSelectYearProps = ComponentProps<typeof CalendarSelectYear>;
export type CalendarSelectMonthProps = ComponentProps<typeof CalendarSelectMonth>;
export type CalendarHeadingProps = ComponentProps<typeof CalendarHeading>;
```
Tokens:
Raw