Cally

https://wicky.nillia.ms/cally
Admin
Cally provides small, feature-rich, and framework-independent calendar components. It offers...
Tokens:11,992
Snippets:41
Trust Score:7.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### HTML Example for Calendar Date Component Usage

Source: https://wicky.nillia.ms/cally/components/calendar-date

Demonstrates how to integrate the `<calendar-date>` web component into an HTML page, setting initial values for date, range, and locale. It also shows the required nested `<calendar-month>` component.

```HTML
<calendar-date
  value="2024-01-10"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
>
  <calendar-month></calendar-month>
</calendar-date>
```

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

### Install Cally via npm Package Manager

Source: https://wicky.nillia.ms/cally/index

This command demonstrates how to install the Cally package using the Node Package Manager (npm). It's the standard method for integrating Cally into modern JavaScript or TypeScript projects, allowing for local development and dependency management.

```Shell
npm install cally
```

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

### Composing a Date Picker UI with Cally and Shoelace

Source: https://wicky.nillia.ms/cally/guides/usage

This example combines Cally's styled calendar components with Shoelace's `sl-input` and `sl-button` to create the basic UI for a date picker. It includes an input field for date entry and a button with a calendar icon to toggle the calendar view, demonstrating component composition and initial layout for a functional date picker.

```HTML
<style>
  .flex {
    display: flex;
  }
  .gap-xs {
    gap: var(--sl-spacing-x-small);
  }
  .gap-l {
    gap: var(--sl-spacing-large);
  }
  .flex-wrap {
    flex-wrap: wrap;
  }
  .justify-center {
    justify-content: center;
  }
  .flex-1 {
    flex: 1;
  }
  .align-end {
    align-items: end;
  }

  calendar-range {
    &::part(button) {
      border-radius: var(--sl-input-border-radius-small);
      background-color: var(--sl-input-background-color);
      border: 1px solid var(--sl-input-border-color);
      padding: var(--sl-spacing-x-small);
    }
  }

  calendar-month {
    --color-accent: var(--sl-color-primary-600);
    &::part(button) {
      border-radius: var(--sl-input-border-radius-medium);
    }
    &::part(range-inner) {
      border-radius: 0;
    }
    &::part(range-start) {
      border-start-end-radius: 0;
      border-end-end-radius: 0;
    }
    &::part(range-end) {
      border-start-start-radius: 0;
      border-end-start-radius: 0;
    }
    &::part(range-start range-end) {
      border-radius: var(--sl-input-border-radius-medium);
    }
  }
</style>
<div class="flex gap-xs align-end">
  <sl-input label="Date range" class="flex-1"></sl-input>
  <sl-button> <sl-icon name="calendar-range" label="Toggle calendar"></sl-icon> </sl-button>
</div>
<sl-card>
  <calendar-range months="2">
    <sl-icon slot="previous" name="chevron-left" label="Previous"></sl-icon>
    <sl-icon slot="next" name="chevron-right" label="Next"></sl-icon>
    <div class="flex gap-l flex-wrap justify-center">
      <calendar-month></calendar-month> <calendar-month offset="1"></calendar-month>
    </div>
  </calendar-range>
</sl-card>
```

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

### Example Usage of calendar-range Web Component

Source: https://wicky.nillia.ms/cally/components/calendar-range

Demonstrates how to embed and configure the `<calendar-range>` component in HTML, setting an initial date range value, defining minimum and maximum selectable dates, and specifying the locale. It also shows the required child `<calendar-month>` component.

```html
<calendar-range
  value="2024-01-10/2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
>
  <calendar-month></calendar-month>
</calendar-range>
```

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

### Install Cally via HTML Script Tag

Source: https://wicky.nillia.ms/cally/index

This snippet shows the simplest way to include the Cally library directly in an HTML page. By adding this `<script type="module">` tag, the custom calendar components become immediately available for use throughout the document.

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

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

### Import Cally Components using ES Modules

Source: https://wicky.nillia.ms/cally/index

After installing Cally via npm, this JavaScript snippet illustrates how to import the components into your application using ES module syntax. This makes the custom elements available for use in your JavaScript or TypeScript files, enabling modular development.

```JavaScript
import "cally";
```

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

### Integrate Cally Web Components in React

Source: https://wicky.nillia.ms/cally/guides/frameworks

Demonstrates how to use Cally web components directly within a React application, including importing the library, rendering components, and handling custom events via the `onchange` prop. This example sets up a basic calendar range component.

```JavaScript
import { useState } from "react";
import { createRoot } from 'react-dom/client';
import "cally";

function App() {
  const [value, setValue] = useState("");

  return (
    <>
      <p>Value is: {value}</p>
      <calendar-range
        value={value}
        onchange={(event) => setValue(event.target.value)}
      >
        <calendar-month />
        <calendar-month offset={1} />
      </calendar-range>
    </>
  );
}

const root = createRoot(document.getElementById("root"));
root.render(<App />)
```

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

### Integrate Cally Components in Svelte

Source: https://wicky.nillia.ms/cally/guides/frameworks

This Svelte code snippet demonstrates how to import and use Cally components, specifically `calendar-range` and `calendar-month`, within a Svelte application. It shows a basic setup for displaying a multi-month calendar range, leveraging Svelte's native support for web components without additional setup.

```Svelte
<script lang="ts">
  import "cally";
</script>

<calendar-range months={2}>
  <calendar-month></calendar-month>
  <calendar-month offset={1}></calendar-month>
</calendar-range>
```

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

### Implementing an Interactive Date Range Picker Component

Source: https://wicky.nillia.ms/cally/guides/usage

This comprehensive example demonstrates how to build an interactive date range picker using custom HTML elements (`<calendar-range>`, `<calendar-month>`), Shoelace UI components (`<sl-input>`, `<sl-button>`, `<sl-popup>`, `<sl-card>`), and vanilla JavaScript. It covers styling with CSS, structuring the UI with HTML, and adding interactivity through event listeners for opening/closing the calendar popup and synchronizing input values with calendar selections.

```HTML
<style>
  .flex {
    display: flex;
  }
  .gap-xs {
    gap: var(--sl-spacing-x-small);
  }
  .gap-l {
    gap: var(--sl-spacing-large);
  }
  .flex-wrap {
    flex-wrap: wrap;
  }
  .flex-1 {
    flex: 1;
  }
  .align-end {
    align-items: end;
  }
  .justify-center {
    justify-content: center;
  }

  sl-card {
    max-inline-size: calc(var(--auto-size-available-width) - 20px);
  }

  calendar-range {
    &::part(button) {
      border-radius: var(--sl-input-border-radius-small);
      background-color: var(--sl-input-background-color);
      border: 1px solid var(--sl-input-border-color);
      padding: var(--sl-spacing-x-small);
    }
  }

  calendar-month {
    --color-accent: var(--sl-color-primary-600);
    &::part(button) {
      border-radius: var(--sl-input-border-radius-medium);
    }
    &::part(range-inner) {
      border-radius: 0;
    }
    &::part(range-start) {
      border-start-end-radius: 0;
      border-end-end-radius: 0;
    }
    &::part(range-end) {
      border-start-start-radius: 0;
      border-end-start-radius: 0;
    }
    &::part(range-start range-end) {
      border-radius: var(--sl-input-border-radius-medium);
    }
  }
</style>
<div class="flex gap-xs align-end">
  <sl-input label="Date range" class="flex-1"></sl-input>
  <sl-button id="toggle-button">
    <sl-icon name="calendar-range" label="Toggle calendar"></sl-icon>
  </sl-button>
</div>
<sl-popup placement="bottom-end" distance="8" anchor="toggle-button" auto-size="horizontal">
  <sl-card style="max-inline-size: calc(var(--auto-size-available-width) - 20px)">
    <calendar-range months="2">
      <sl-icon slot="previous" name="chevron-left" label="Previous"></sl-icon>
      <sl-icon slot="next" name="chevron-right" label="Next"></sl-icon>
      <div class="flex gap-l flex-wrap justify-center">
        <calendar-month></calendar-month> <calendar-month offset="1"></calendar-month>
      </div>
    </calendar-range>
  </sl-card>
</sl-popup>
<script>
  const root = document.currentScript.closest(".example");

  const input = root.querySelector("sl-input");
  const popup = root.querySelector("sl-popup");
  const toggle = root.querySelector("sl-button");
  const calendar = root.querySelector("calendar-range");

  function open() {
    popup.active = true;
    requestAnimationFrame(() => calendar.focus());
  }

  function close() {
    popup.active = false;
    toggle.focus();
  }

  toggle.addEventListener("click", () => {
    popup.active ? close() : open();
  });

  calendar.addEventListener("keydown", (e) => {
    if (e.key === "Escape") close();
  });

  calendar.addEventListener("change", (e) => {
    input.value = e.target.value;
    close();
  });

  input.addEventListener("input", (e) => {
    calendar.value = e.target.value;
  });
</script>
```

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

### Cally Calendar Range Component HTML Usage

Source: https://wicky.nillia.ms/cally/guides/theming

An HTML example demonstrating the instantiation and configuration of the `calendar-range` web component. It sets initial values, date constraints (min/max), locale, and the number of months to display. SVG elements are used as slotted content for 'previous' and 'next' navigation buttons, and nested `calendar-month` components define the month grid.

```html
<calendar-range
  value="2024-01-10/2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
  months="2"
>
  <svg
    aria-label="Previous"
    slot="previous"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="M15.75 19.5 8.25 12l7.5-7.5"></path>
  </svg>
  <svg
    aria-label="Next"
    slot="next"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="m8.25 4.5 7.5 7.5-7.5 7.5"></path>
  </svg>
  <div class="grid">
    <calendar-month></calendar-month>
    <calendar-month offset="1"></calendar-month>
  </div>
</calendar-range>
```

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

### Integrate Cally Web Components in Vue

Source: https://wicky.nillia.ms/cally/guides/frameworks

Shows the fundamental setup for using Cally web components within a Vue 3 application. It covers importing the Cally library and embedding components directly into a Vue template.

```Vue
<script setup>
import 'cally';
</script>
<template>
  <calendar-range :months="2">
    <calendar-month />
    <calendar-month :offset="1" />
  </calendar-range>
</template>
```

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

### Applying Flexbox Layout to Calendar Months in HTML

Source: https://wicky.nillia.ms/cally/guides/theming

This example shows how to use CSS flexbox within an HTML structure to arrange `calendar-month` components. It wraps the months in a `div` with a `grid` class, enabling horizontal stacking, wrapping, and spacing for responsive layout.

```HTML
<style>
  .grid {
    display: flex;
    gap: 1.5em;
    flex-wrap: wrap;
    justify-content: center;
  }
</style>
<calendar-range
  value="2024-01-10/2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
  months="2"
>
  <div class="grid">
    <calendar-month></calendar-month>
    <calendar-month offset="1"></calendar-month>
  </div>
</calendar-range>
```

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

### Applying Rounded Corners to Calendar Range with CSS Parts

Source: https://wicky.nillia.ms/cally/guides/theming

Building on previous styles, this snippet adds specific border-radius rules to the `calendar-month` component's parts. It targets `range-inner`, `range-start`, and `range-end` parts to achieve rounded corners for the start and end of a selected date range, demonstrating the use of CSS logical properties.

```HTML
<style>
  .grid {
    display: flex;
    gap: 1.5em;
    flex-wrap: wrap;
    justify-content: center;
  }

  calendar-range {
    svg {
      height: 16px;
      width: 16px;
      fill: none;
      stroke: currentColor;
      stroke-width: 1.5;
    }

    path {
      stroke-linecap: round;
      stroke-linejoin: round;
    }

    &::part(button) {
      border: 1px solid #adb5bd;
      background-color: #fff;
      border-radius: 3px;
      width: 26px;
      height: 26px;
    }

    &::part(button):focus-visible {
      outline: 2px solid #7048e8;
    }
  }

  calendar-month {
    --color-accent: #7048e8;
    --color-text-on-accent: #ffffff;

    &::part(button) {
      border-radius: 3px;
    }

    &::part(range-inner) {
      border-radius: 0;
    }

    &::part(range-start) {
      border-start-end-radius: 0;
      border-end-end-radius: 0;
    }

    &::part(range-end) {
      border-start-start-radius: 0;
      border-end-start-radius: 0;
    }

    &::part(range-start range-end) {
      border-radius: 3px;
    }
  }
</style>
<calendar-range
  value="2024-01-10/2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
  months="2"
>
  <svg
    aria-label="Previous"
    slot="previous"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="M15.75 19.5 8.25 12l7.5-7.5"></path>
  </svg>
  <svg
    aria-label="Next"
    slot="next"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="m8.25 4.5 7.5 7.5-7.5 7.5"></path>
  </svg>
  <div class="grid">
    <calendar-month></calendar-month>
    <calendar-month offset="1"></calendar-month>
  </div>
</calendar-range>
```

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

### Styling Calendar Range Component with CSS Parts

Source: https://wicky.nillia.ms/cally/guides/theming

CSS rules applied within the shadow DOM of the `calendar-range` web component. It uses the `&::part()` selector to style specific internal elements like the start and end of a selected date range, and the overall range, applying border-radius and background color.

```css
background-color: #845ef7;
}

&::part(range-start) {
  border-start-end-radius: 0;
  border-end-end-radius: 0;
}

&::part(range-end) {
  border-start-start-radius: 0;
  border-end-start-radius: 0;
}

&::part(range-start range-end) {
  border-radius: 3px;
}
}
```

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

### Display Multiple Calendar Months with Custom CSS Layout

Source: https://wicky.nillia.ms/cally/index

This example demonstrates how to display two calendar months side-by-side within a `calendar-range` component, applying custom CSS for a flexible layout. It configures the `months` attribute and uses `offset` for `calendar-month` components, combined with flexbox for responsive arrangement.

```HTML
<style>
  .grid {
    display: flex;
    gap: 1em;
    justify-content: center;
    flex-wrap: wrap;
  }
</style>
<calendar-range months="2">
  <div class="grid">
    <calendar-month></calendar-month>
    <calendar-month offset="1"></calendar-month>
  </div>
</calendar-range>
```

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

### HTML Structure for Cally Calendar Range Component

Source: https://wicky.nillia.ms/cally/index

This HTML snippet demonstrates the integration of the `calendar-range` component to display two months. It includes SVG elements for navigation controls and utilizes nested `calendar-month` components within a `div` for layout, showcasing a typical setup for a multi-month calendar.

```HTML
<div class="card">
  <calendar-range months="2">
    <svg
      aria-label="Previous"
      slot="previous"
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
    >
      <path d="M15.75 19.5 8.25 12l7.5-7.5"></path>
    </svg>
    <svg
      aria-label="Next"
      slot="next"
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
    >
      <path d="m8.25 4.5 7.5 7.5-7.5 7.5"></path>
    </svg>
    <div class="grid">
      <calendar-month></calendar-month>
      <calendar-month offset="1"></calendar-month>
    </div>
  </calendar-range>
</div>
```

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

### Basic Usage of calendar-multi Component

Source: https://wicky.nillia.ms/cally/components/calendar-multi

Demonstrates the basic HTML structure and attributes for integrating the `<calendar-multi>` web component, allowing selection of multiple dates within specified min/max ranges and locale. It requires a nested `<calendar-month>` component.

```HTML
<calendar-multi
  value="2024-01-10 2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
>
  <calendar-month></calendar-month>
</calendar-multi>
```

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

### calendar-range Web Component API Reference

Source: https://wicky.nillia.ms/cally/components/calendar-range

Comprehensive API documentation for the `<calendar-range>` web component, detailing its configurable properties and attributes, emitted custom events, callable methods, available CSS parts for styling, and slots for content customization.

```APIDOC
Properties and Attributes:

value: string
  - Attribute: value
  - Description: The currently selected range (ISO-8601 range format: YYYY-MM-DD/YYYY-MM-DD).
  - Default: ""
min: string
  - Attribute: min
  - Description: The earliest date that can be selected (ISO-8601 format: YYYY-MM-DD).
  - Default: ""
max: string
  - Attribute: max
  - Description: The latest date that can be selected (ISO-8601 format: YYYY-MM-DD).
  - Default: ""
today: string
  - Attribute: today
  - Description: The date that is considered today (ISO-8601 format: YYYY-MM-DD).
  - Default: ""
focusedDate: string | undefined
  - Attribute: focused-date
  - Description: The date that is considered "focused" by the calendar (ISO-8601 format: YYYY-MM-DD).
  - Default: undefined
tentative: string
  - Attribute: tentative
  - Description: The date that is tentatively selected e.g. the start of a range selection (ISO-8601 format: YYYY-MM-DD).
  - Default: ""
firstDayOfWeek: number
  - Attribute: first-day-of-week
  - Description: The first day of the week, where Sunday is 0, Monday is 1, etc.
  - Default: 1
showOutsideDays: boolean
  - Attribute: show-outside-days
  - Description: Whether to show days outside the month.
  - Default: false
locale: string | undefined
  - Attribute: locale
  - Description: The locale for formatting dates. If not set, will use the browser's locale.
  - Default: undefined
months: number
  - Attribute: months
  - Description: The number of months to display per page.
  - Default: 1
pageBy: "months" | "single"
  - Attribute: page-by
  - Description: Whether next and previous should move by number of months or by a single month at a time.
  - Default: "months"
formatWeekday: "narrow" | "short"
  - Attribute: format-weekday
  - Description: Controls the format of the weekday headers in the month table.
  - Default: "narrow"
isDateDisallowed: (date: Date) => boolean
  - Description: A function that takes a date and returns true if the date should not be selectable.
  - Default: () => false
getDayParts: (date: Date) => string
  - Description: A function that takes a date and returns a string of CSS parts, allowing custom styling for individual dates.
  - Default: () => ""

Events:

change: Event
  - Description: Emitted when the `value` changes via user interaction. Not emitted when `value` is programmatically changed.
focusday: CustomEvent<Date>
  - Description: Emitted when the currently focused day changes. This can happen via keyboard commands, or clicking the next or previous buttons.
rangestart: CustomEvent<Date>
  - Description: Emitted when the user starts selecting a range.
rangeend: CustomEvent<Date>
  - Description: Emitted when the user finished selections a range.

Methods:

focus(options?: FocusOptions & { target: "previous" | "next" | "day" }): void
  - Parameters:
    - options: controls what gets focused, and how.
  - Description: Focuses the `<calendar-month>` containing the currently focused date. `option.target` controls which part of the component gets focused.

CSS Parts:

container: The container for the entire component.
header: The container for `heading` and `button`s.
button: Any button within the component.
previous: The previous page `button`.
next: The next page `button`.
disabled: A `button` that is disabled due to min/max.
heading: The heading that labels the calendar.

Slots:

Default slot:
  - Description: The default slot is where you place your `<calendar-month>` components, along with any other markup. Note `<calendar-month>` does not need to be a direct descendant.
previous:
  - Description: The inner content of the previous page button. By default uses text "Previous". You will likely want to slot an icon here.
next:
  - Description: The inner content of the next page button. By default uses text "Next". You will likely want to slot an icon here.
heading:
  - Description: By default displays the visible heading for the component. You may want to replace this with a year select. A separate visually-hidden heading is always rendered for accessibility purposes.
```

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

### calendar-multi Component API Reference

Source: https://wicky.nillia.ms/cally/components/calendar-multi

Comprehensive API documentation for the `<calendar-multi>` web component, detailing its configurable properties, emitted events, callable methods, available CSS parts for styling, and supported slots for content projection. Dates are expected in ISO-8601 format (YYYY-MM-DD).

```APIDOC
<calendar-multi> Component API

Properties and Attributes:
- value: string (default: "")
  Description: A space-separated list of selected dates.
  Attribute: value
- min: string (default: "")
  Description: The earliest date that can be selected.
  Attribute: min
- max: string (default: "")
  Description: The latest date that can be selected.
  Attribute: max
- today: string (default: "")
  Description: The date that is considered today.
  Attribute: today
- focusedDate: string | undefined (default: undefined)
  Description: The date that is considered "focused" by the calendar.
  Attribute: focused-date
- firstDayOfWeek: number (default: 1)
  Description: The first day of the week, where Sunday is 0, Monday is 1, etc.
  Attribute: first-day-of-week
- showOutsideDays: boolean (default: false)
  Description: Whether to show days outside the month.
  Attribute: show-outside-days
- locale: string | undefined (default: undefined)
  Description: The locale for formatting dates. If not set, will use the browser's locale.
  Attribute: locale
- months: number (default: 1)
  Description: The number of months to display per page.
  Attribute: months
- pageBy: "months" | "single" (default: "months")
  Description: Whether next and previous should move by number of months or by a single month at a time.
  Attribute: page-by
- formatWeekday: "narrow" | "short" (default: "narrow")
  Description: Controls the format of the weekday headers in the month table.
  Attribute: format-weekday
- isDateDisallowed: (date: Date) => boolean (default: () => false)
  Description: A function that takes a date and returns true if the date should not be selectable.
- getDayParts: (date: Date) => string (default: () => "")
  Description: A function that takes a date and returns a string of CSS parts, allowing custom styling for individual dates.

Events:
- change: Event
  Description: Emitted when the value changes via user interaction. Not emitted when value is programmatically changed.
- focusday: CustomEvent<Date>
  Description: Emitted when the currently focused day changes. This can happen via keyboard commands, or clicking the next or previous buttons.

Methods:
- focus(options?: FocusOptions & { target: "previous" | "next" | "day" }): void
  Parameters:
    - options: FocusOptions & { target: "previous" | "next" | "day" }
      Description: Controls what gets focused, and how.
  Description: Focuses the <calendar-month> containing the currently focused date. option.target controls which part of the component gets focused.

CSS Parts:
- container: The container for the entire component.
- header: The container for heading and buttons.
- button: Any button within the component.
- previous: The previous page button.
- next: The next page button.
- disabled: A button that is disabled due to min/max.
- heading: The heading that labels the calendar.

Slots:
- Default slot: The default slot is where you place your <calendar-month> components, along with any other markup. Note <calendar-month> does not need to be a direct descendant.
- previous: The inner content of the previous page button. By default uses text "Previous". You will likely want to slot an icon here.
- next: The inner content of the next page button. By default uses text "Next". You will likely want to slot an icon here.
- heading: By default displays the visible heading for the component. You may want to replace this with a year select. A separate visually-hidden heading is always rendered for accessibility purposes.
```

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

### Calendar Month Component API Reference

Source: https://wicky.nillia.ms/cally/components/calendar-month

Comprehensive API documentation for the <calendar-month> web component, detailing its properties, attributes, CSS custom properties for coarse-grained styling, and CSS parts for fine-grained styling.

```APIDOC
<calendar-month> Component API

Properties and Attributes:
  offset: number (Default: 0)
    Description: In a multi-month view, controls which month is shown relative to the start of the view.

CSS Custom Properties:
  --color-accent: string (Default: black)
    Description: The accent color used throughout.
  --color-text-on-accent: string (Default: white)
    Description: The color used on with --color-accent.

CSS Parts:
  heading
    Description: The heading that labels the month.
  table
    Description: The <table> element.
  tr
    Description: Any row within the table.
  head
    Description: The table's header row.
  week
    Description: The table's body rows.
  th
    Description: The table's header cells.
  td
    Description: The table's body cells.
  button
    Description: Any button used in the component.
  day
    Description: The buttons and headings corresponding to each day in the grid.
  day-0
    Description: The buttons and headings corresponding to Sunday.
  day-1
    Description: The buttons and headings corresponding to Monday.
  day-2
    Description: The buttons and headings corresponding to Tuesday.
  day-3
    Description: The buttons and headings corresponding to Wednesday.
  day-4
    Description: The buttons and headings corresponding to Thursday.
  day-5
    Description: The buttons and headings corresponding to Friday.
  day-6
    Description: The buttons and headings corresponding to Saturday.
  selected
    Description: Any days which are selected.
  today
    Description: Today's day.
  disallowed
    Description: Any day that has been disallowed via isDateDisallowed.
  outside
    Description: Any days which are outside the current month.
  range-start
    Description: The day at the start of a date range.
  range-end
    Description: The day at the end of a date range.
  range-inner
    Description: Any days between the start and end of a date range.
```

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

### Basic Calendar Range Component HTML Structure

Source: https://wicky.nillia.ms/cally/guides/theming

This snippet demonstrates the fundamental HTML structure for integrating the `calendar-range` component. It shows how to define a date range, minimum/maximum dates, locale, and the number of months to display using attributes, with nested `calendar-month` components.

```HTML
<calendar-range
  value="2024-01-10/2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
  months="2"
>
  <calendar-month></calendar-month>
  <calendar-month offset="1"></calendar-month>
</calendar-range>
```

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

### Styling Cally Calendar Components with Shoelace

Source: https://wicky.nillia.ms/cally/guides/usage

This snippet provides CSS styling for Cally's `calendar-range` and `calendar-month` components, applying Shoelace design tokens for `border-radius`, `background-color`, `border`, and `padding`. It also customizes the appearance of range selection parts to match Shoelace's aesthetic, demonstrating how to theme Cally components.

```HTML
<style>
  .flex {
    display: flex;
  }
  .gap-l {
    gap: var(--sl-spacing-large);
  }
  .flex-wrap {
    flex-wrap: wrap;
  }
  .justify-center {
    justify-content: center;
  }

  calendar-range {
    &::part(button) {
      border-radius: var(--sl-input-border-radius-small);
      background-color: var(--sl-input-background-color);
      border: 1px solid var(--sl-input-border-color);
      padding: var(--sl-spacing-x-small);
    }
  }

  calendar-month {
    --color-accent: var(--sl-color-primary-600);

    &::part(button) {
      border-radius: var(--sl-input-border-radius-medium);
    }
    &::part(range-inner) {
      border-radius: 0;
    }
    &::part(range-start) {
      border-start-end-radius: 0;
      border-end-end-radius: 0;
    }
    &::part(range-end) {
      border-start-start-radius: 0;
      border-end-start-radius: 0;
    }
    &::part(range-start range-end) {
      border-radius: var(--sl-input-border-radius-medium);
    }
  }
</style>
<sl-card>
  <calendar-range months="2">
    <sl-icon slot="previous" name="chevron-left" label="Previous"></sl-icon>
    <sl-icon slot="next" name="chevron-right" label="Next"></sl-icon>
    <div class="flex gap-l flex-wrap justify-center">
      <calendar-month></calendar-month> <calendar-month offset="1"></calendar-month>
    </div>
  </calendar-range>
</sl-card>
```

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

### Styling and Structure for Shoelace Calendar Popup

Source: https://wicky.nillia.ms/cally/guides/usage

This snippet provides the CSS styling for layout utilities (flexbox, spacing) and customizes the appearance of Shoelace components like `sl-input`, `sl-button`, and custom `calendar-range` and `calendar-month` elements. It also defines the HTML structure, including an input field, a button to toggle the popup, and the `sl-popup` component containing a `sl-card` with the `calendar-range` and `calendar-month` components.

```HTML
<style>
  .flex {
    display: flex;
  }
  .gap-xs {
    gap: var(--sl-spacing-x-small);
  }
  .gap-l {
    gap: var(--sl-spacing-large);
  }
  .flex-wrap {
    flex-wrap: wrap;
  }
  .justify-center {
    justify-content: center;
  }
  .flex-1 {
    flex: 1;
  }
  .align-end {
    align-items: end;
  }

  calendar-range {
    &::part(button) {
      border-radius: var(--sl-input-border-radius-small);
      background-color: var(--sl-input-background-color);
      border: 1px solid var(--sl-input-border-color);
      padding: var(--sl-spacing-x-small);
    }
  }

  calendar-month {
    --color-accent: var(--sl-color-primary-600);
    &::part(button) {
      border-radius: var(--sl-input-border-radius-medium);
    }
    &::part(range-inner) {
      border-radius: 0;
    }
    &::part(range-start) {
      border-start-end-radius: 0;
      border-end-end-radius: 0;
    }
    &::part(range-end) {
      border-start-start-radius: 0;
      border-end-start-radius: 0;
    }
    &::part(range-start range-end) {
      border-radius: var(--sl-input-border-radius-medium);
    }
  }
</style>
<div class="flex gap-xs align-end">
  <sl-input label="Date range" class="flex-1"></sl-input>
  <sl-button> <sl-icon name="calendar-range" label="Toggle calendar"></sl-icon> </sl-button>
</div>
<sl-popup placement="bottom-end" distance="8" auto-size="horizontal">
  <sl-card>
    <calendar-range months="2">
      <sl-icon slot="previous" name="chevron-left" label="Previous"></sl-icon>
      <sl-icon slot="next" name="chevron-right" label="Next"></sl-icon>
      <div class="flex gap-l flex-wrap justify-center">
        <calendar-month></calendar-month> <calendar-month offset="1"></calendar-month>
      </div>
    </calendar-range>
  </sl-card>
</sl-popup>
```

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

### Handle Cally Web Component Events Manually in Vue

Source: https://wicky.nillia.ms/cally/guides/frameworks

Demonstrates an alternative method for handling events from Cally web components in Vue by manually listening for the `change` event and updating component state, providing explicit control over data flow.

```Vue
<script setup>
import 'cally';

const selected = ref("")
function onChange(event) {
  selected.value = event.target.value
}
</script>
<template>
  <p>Selected range: {{ selected }}</p>

  <calendar-range :months="2" :value="selected" @change="onChange">
    <calendar-month />
    <calendar-month :offset="1" />
  </calendar-range>
</template>
```

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

### Styling Calendar Components with CSS Custom Properties

Source: https://wicky.nillia.ms/cally/guides/theming

This snippet showcases how to define and utilize CSS custom properties (`--color-accent`, `--color-text-on-accent`) within a `<style>` block to style custom web components (`calendar-month`). It also provides the HTML structure for instantiating `calendar-range` and `calendar-month` elements, demonstrating attribute passing (value, min, max, locale, months) and slot usage for SVG icons.

```HTML
<style>
  .grid {
    display: flex;
    gap: 1.5em;
    flex-wrap: wrap;
    justify-content: center;
  }

  calendar-range {
    svg {
      height: 16px;
      width: 16px;
      fill: none;
      stroke: currentColor;
      stroke-width: 1.5;
    }

    path {
      stroke-linecap: round;
      stroke-linejoin: round;
    }
  }

  calendar-month {
    --color-accent: #7048e8;
    --color-text-on-accent: #ffffff;
  }
</style>
<calendar-range
  value="2024-01-10/2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
  months="2"
>
  <svg
    aria-label="Previous"
    slot="previous"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="M15.75 19.5 8.25 12l7.5-7.5"></path>
  </svg>
  <svg
    aria-label="Next"
    slot="next"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="m8.25 4.5 7.5 7.5-7.5 7.5"></path>
  </svg>
  <div class="grid">
    <calendar-month></calendar-month>
    <calendar-month offset="1"></calendar-month>
  </div>
</calendar-range>
```

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

### Calendar Date Component Methods

Source: https://wicky.nillia.ms/cally/components/calendar-date

Details the public methods available on the `<calendar-date>` component for programmatic control and interaction.

```APIDOC
focus(options?: FocusOptions & { target: "previous" | "next" | "day" }): void
  Parameters:
    options: controls what gets focused, and how.
  Description: Focuses the <calendar-month> containing the currently focused date. option.target controls which part of the component gets focused.
```

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

### Calendar Date Component CSS Parts

Source: https://wicky.nillia.ms/cally/components/calendar-date

Lists the CSS parts available for fine-grained styling and theming of the `<calendar-date>` component. These parts can be used in isolation or combined to target specific elements.

```APIDOC
container: The container for the entire component.
header: The container for heading and buttons.
button: Any button within the component.
previous: The previous page button.
next: The next page button.
disabled: A button that is disabled due to min/max.
heading: The heading that labels the calendar.
```

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

### Basic HTML for Single Date Calendar

Source: https://wicky.nillia.ms/cally/index

This HTML snippet provides the fundamental structure for displaying a single date calendar using Cally's components. It wraps a `calendar-month` component within a `calendar-date` container, suitable for single-date selection interfaces.

```HTML
<calendar-date>
  <calendar-month></calendar-month>
</calendar-date>
```

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

### Styling Calendar Component Buttons with CSS Parts

Source: https://wicky.nillia.ms/cally/guides/theming

This snippet demonstrates initial styling for the `calendar-range` and `calendar-month` components. It targets the `button` part of `calendar-range` for general button styling and applies a focus-visible outline. It also sets custom CSS properties for accent colors within `calendar-month`.

```HTML
<style>
  .grid {
    display: flex;
    gap: 1.5em;
    flex-wrap: wrap;
    justify-content: center;
  }

  calendar-range {
    svg {
      height: 16px;
      width: 16px;
      fill: none;
      stroke: currentColor;
      stroke-width: 1.5;
    }

    path {
      stroke-linecap: round;
      stroke-linejoin: round;
    }

    &::part(button) {
      border: 1px solid #adb5bd;
      background-color: #fff;
      border-radius: 3px;
      width: 26px;
      height: 26px;
    }

    &::part(button):focus-visible {
      outline: 2px solid #7048e8;
    }
  }

  calendar-month {
    --color-accent: #7048e8;
    --color-text-on-accent: #ffffff;
  }
</style>
<calendar-range
  value="2024-01-10/2024-01-20"
  min="2024-01-01"
  max="2024-12-31"
  locale="en-GB"
  months="2"
>
  <svg
    aria-label="Previous"
    slot="previous"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="M15.75 19.5 8.25 12l7.5-7.5"></path>
  </svg>
  <svg
    aria-label="Next"
    slot="next"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
  >
    <path d="m8.25 4.5 7.5 7.5-7.5 7.5"></path>
  </svg>
  <div class="grid">
    <calendar-month></calendar-month>
    <calendar-month offset="1"></calendar-month>
  </div>
</calendar-range>
```

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

### Augment React Types for Cally Web Components (TypeScript)

Source: https://wicky.nillia.ms/cally/guides/frameworks

Provides instructions and code for augmenting React's `JSX.IntrinsicElements` in TypeScript. This enables type-checking for Cally web component props and events, improving developer experience. It includes the `d.ts` file content and the necessary `tsconfig.json` update.

```TypeScript
import type {
  CalendarRangeProps,
  CalendarMonthProps,
  CalendarDateProps,
  CalendarMultiProps,
} from "cally";

type MapEvents<T> = {
  [K in keyof T as K extends `on${infer E}` ? `on${Lowercase<E>}` : K]: T[K];
};

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      "calendar-month": MapEvents<CalendarMonthProps> &
        React.HTMLAttributes<HTMLElement>;
      "calendar-range": MapEvents<CalendarRangeProps> &
        React.HTMLAttributes<HTMLElement>;
      "calendar-date": MapEvents<CalendarDateProps> &
        React.HTMLAttributes<HTMLElement>;
      "calendar-multi": MapEvents<CalendarMultiProps> &
        React.HTMLAttributes<HTMLElement>;
    }
  }
}
```

```JSON
{
  "compilerOptions": {
    "types": ["./globals.d.ts"]
  }
}
```
Tokens:
Raw