API

CalendarRange

Every field of the range, its default and what it changes on screen.

Fields

Type

type CalendarRange = {
  view: 'day' | 'week' | 'days' | 'month' | 'agenda'
  currentDate: string
  timeZone: string
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  dayCount?: number
  slotMinutes?: number
  disambiguation?: Disambiguation
}

Field	Type	Default	Description
`view`	`'day' \| 'week' \| 'days' \| 'month' \| 'agenda'`	`—`	The period to draw, and whether it carries a time grid.
`currentDate`	`string`	`—`	The date the calendar is on. The period drawn is the one that contains it — not a selection, and not read as today.
`timeZone`	`string`	`—`	An IANA zone. Every event without one of its own is read in it, and the grid is built in it.
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	`1`	The first day of the week, Sunday being `0`. Used by `week` and by the padding of `month`.
`dayCount`	`number`	`7 / 30`	The span of `days` and `agenda`. Below one throws.
`slotMinutes`	`number`	`60`	The height of one grid row in wall-clock minutes. Outside 1 to 1440 throws.
`disambiguation`	`'compatible' \| 'earlier' \| 'later' \| 'reject'`	`'compatible'`	What a wall time means when a DST transition made it ambiguous or impossible. Temporal’s own option, passed straight through.

Examples

typescript

import { buildCalendar } from '@midstem/chronous'
import type { CalendarRange } from '@midstem/chronous'

const ranges: CalendarRange[] = [
  // Monday 16 to Sunday 22 — the week that contains the 18th
  { view: 'week', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv' },
  // a working week, counted from the anchor
  { view: 'days', dayCount: 5, currentDate: '2026-03-18', timeZone: 'Europe/Kyiv' },
  // March, padded out to whole weeks
  { view: 'month', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv' },
  // the next thirty days as a list
  { view: 'agenda', currentDate: '2026-03-18', timeZone: 'Europe/Kyiv' },
]

for (const range of ranges) {
  const calendar = buildCalendar(range, [])

  console.log(range.view, calendar.days.length, calendar.days[0].date)
}
// week 7 2026-03-16
// days 5 2026-03-18
// month 42 2026-02-23
// agenda 30 2026-03-18

Views & ranges walks through what each view draws and how a DST transition lands in a row.