{
  "schemaVersion": 1,
  "target": "react",
  "name": "calendar",
  "version": "0.1.0",
  "category": "data",
  "title": "Calendar",
  "description": "A month grid with single and range selection, full keyboard navigation, disabled dates, and a today marker, with Intl labels and no date library.",
  "tags": [
    "calendar",
    "date",
    "range",
    "form"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [],
  "docsPath": "/components/calendar",
  "props": [
    {
      "name": "mode",
      "type": "\"single\" | \"range\"",
      "default": "\"single\"",
      "description": "Pick one day, or a from and to range."
    },
    {
      "name": "value / defaultValue / onValueChange",
      "type": "Date | null, or { from, to }",
      "description": "Selection, controlled or not."
    },
    {
      "name": "month / defaultMonth / onMonthChange",
      "type": "Date",
      "description": "The month on screen."
    },
    {
      "name": "disabled",
      "type": "(date) => boolean | Date[]",
      "description": "Days that cannot be picked. They stay focusable so arrow keys pass over them."
    },
    {
      "name": "minDate / maxDate",
      "type": "Date",
      "description": "Pickable bounds; navigation stops at their months."
    },
    {
      "name": "weekStartsOn",
      "type": "0 to 6",
      "description": "First column. Defaults to the locale's first day from Intl.Locale week info."
    },
    {
      "name": "locale",
      "type": "string",
      "description": "BCP 47 locale for month and weekday names."
    },
    {
      "name": "numberOfMonths",
      "type": "1 | 2",
      "default": "1",
      "description": "Months side by side."
    },
    {
      "name": "showOutsideDays",
      "type": "boolean",
      "description": "Shows neighbouring months' days, dimmed. On for one month."
    },
    {
      "name": "today",
      "type": "Date",
      "description": "Overrides today, for example to match a server clock."
    },
    {
      "name": "autoFocus",
      "type": "boolean",
      "default": "false",
      "description": "Focuses the selected day or today on mount."
    }
  ],
  "accessibility": [
    "Each month is a grid named by its month heading; days are buttons with full spoken dates (\"Friday, November 14, 2026\") and today carries aria-current=\"date\".",
    "One roving tab stop: arrows move by day and week, Home and End to the week's edges, Page Up and Page Down by month, with Shift by year; focus follows into the next month.",
    "Disabled days use aria-disabled, are struck through as well as dimmed, and remain reachable by arrow keys.",
    "Selected days set aria-selected on their grid cells; a range never spans a disabled day.",
    "Clicking the month arrows cross-fades the grid in 150ms; keyboard paging switches instantly, and reduced motion removes the fade."
  ],
  "states": [
    "single",
    "range",
    "range preview",
    "today",
    "disabled",
    "outside days",
    "two months"
  ],
  "files": [
    {
      "path": "ui/calendar.tsx",
      "content": "\"use client\";\n\nimport { type KeyboardEvent, type ReactNode, useEffect, useMemo, useRef, useState } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\n// Date helpers. Every date is a local calendar day at midnight; no date library involved.\n\n/** The same calendar day at 00:00 local time. */\nexport function startOfDay(date: Date) {\n  return new Date(date.getFullYear(), date.getMonth(), date.getDate());\n}\n\nexport function addDays(date: Date, days: number) {\n  return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);\n}\n\n/** Moves by whole months, clamping the day so Jan 31 plus one month is the last day of February. */\nexport function addMonths(date: Date, months: number) {\n  const target = new Date(date.getFullYear(), date.getMonth() + months, 1);\n  const last = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();\n  return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), last));\n}\n\nexport function isSameDay(a: Date | null | undefined, b: Date | null | undefined) {\n  return !!a && !!b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();\n}\n\nfunction startOfMonth(date: Date) {\n  return new Date(date.getFullYear(), date.getMonth(), 1);\n}\n\nfunction isSameMonth(a: Date, b: Date) {\n  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();\n}\n\nfunction dayKey(date: Date) {\n  return `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`;\n}\n\n/** The number of days from `from` to `to`, counting both ends. */\nexport function countDays(from: Date, to: Date) {\n  return Math.round((startOfDay(to).getTime() - startOfDay(from).getTime()) / 86_400_000) + 1;\n}\n\n/** First weekday for a locale (0 = Sunday), from `Intl.Locale` week info where the browser has it. */\nfunction localeWeekStart(locale?: string): number {\n  try {\n    const info = new Intl.Locale(locale ?? navigator.language) as Intl.Locale & {\n      getWeekInfo?: () => { firstDay: number };\n      weekInfo?: { firstDay: number };\n    };\n    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay;\n    if (firstDay) return firstDay % 7;\n  } catch {\n    // Older engines: fall through to Sunday.\n  }\n  return 0;\n}\n\nexport type DateRange = { from: Date | null; to: Date | null };\n\ninterface CalendarBaseProps {\n  /** The month on screen (controlled). Any day in the month works. */\n  month?: Date;\n  defaultMonth?: Date;\n  onMonthChange?: (month: Date) => void;\n  /** Days that cannot be picked: a predicate or a list. They stay focusable so arrow keys can pass them. */\n  disabled?: ((date: Date) => boolean) | Date[];\n  /** Earliest pickable day. Navigation stops at its month. */\n  minDate?: Date;\n  /** Latest pickable day. Navigation stops at its month. */\n  maxDate?: Date;\n  /** First column, 0 for Sunday to 6 for Saturday. Defaults to the locale's first day. */\n  weekStartsOn?: number;\n  /** BCP 47 locale for month and weekday names. Defaults to the browser's. */\n  locale?: string;\n  /** Months side by side. Two suits range picking. */\n  numberOfMonths?: 1 | 2;\n  /** Shows the trailing and leading days of the neighbouring months, dimmed. */\n  showOutsideDays?: boolean;\n  /** Overrides \"today\", for example to match a server clock. */\n  today?: Date;\n  /** Focuses the selected day (or today) when the calendar mounts, as inside a popover. */\n  autoFocus?: boolean;\n  className?: string;\n}\n\nexport interface CalendarSingleProps extends CalendarBaseProps {\n  mode?: \"single\";\n  value?: Date | null;\n  defaultValue?: Date | null;\n  onValueChange?: (value: Date | null) => void;\n}\n\nexport interface CalendarRangeProps extends CalendarBaseProps {\n  mode: \"range\";\n  value?: DateRange;\n  defaultValue?: DateRange;\n  onValueChange?: (value: DateRange) => void;\n}\n\nexport type CalendarProps = CalendarSingleProps | CalendarRangeProps;\n\n/**\n * A month grid with single or range selection. Arrow keys move by day and week, Home and End jump\n * to the week's edges, Page Up and Page Down change month (with Shift, year). Labels come from\n * `Intl`, so weekdays and months follow the locale.\n */\nexport function Calendar(props: CalendarProps) {\n  const {\n    mode = \"single\",\n    month: monthProp,\n    defaultMonth,\n    onMonthChange,\n    disabled,\n    minDate,\n    maxDate,\n    weekStartsOn: weekStartsOnProp,\n    locale,\n    numberOfMonths = 1,\n    showOutsideDays = numberOfMonths === 1,\n    today: todayProp,\n    autoFocus = false,\n    className,\n  } = props;\n\n  // Selection, controlled or not. Both modes share one state slot.\n  const [innerSingle, setInnerSingle] = useState<Date | null>(mode === \"single\" ? ((props as CalendarSingleProps).defaultValue ?? null) : null);\n  const [innerRange, setInnerRange] = useState<DateRange>(\n    mode === \"range\" ? ((props as CalendarRangeProps).defaultValue ?? { from: null, to: null }) : { from: null, to: null },\n  );\n  const single = mode === \"single\" ? ((props as CalendarSingleProps).value !== undefined ? (props as CalendarSingleProps).value ?? null : innerSingle) : null;\n  const range = mode === \"range\" ? ((props as CalendarRangeProps).value ?? innerRange) : { from: null, to: null };\n\n  const today = useMemo(() => startOfDay(todayProp ?? new Date()), [todayProp]);\n  const anchor = (mode === \"single\" ? single : range.from) ?? today;\n  const [innerMonth, setInnerMonth] = useState(() => startOfMonth(defaultMonth ?? anchor));\n  const month = startOfMonth(monthProp ?? innerMonth);\n  const [focused, setFocused] = useState<Date>(() => startOfDay(anchor));\n  const [hovered, setHovered] = useState<Date | null>(null);\n  const [weekStartsOn, setWeekStartsOn] = useState(weekStartsOnProp ?? 0);\n  const [input, setInput] = useState<\"pointer\" | \"keyboard\">(\"pointer\");\n  const rootRef = useRef<HTMLDivElement>(null);\n  const shouldFocus = useRef(autoFocus);\n\n  // The locale's week start needs `navigator`, so it resolves after mount.\n  useEffect(() => {\n    if (weekStartsOnProp === undefined) setWeekStartsOn(localeWeekStart(locale));\n    else setWeekStartsOn(weekStartsOnProp);\n  }, [weekStartsOnProp, locale]);\n\n  useEffect(() => {\n    if (!shouldFocus.current) return;\n    shouldFocus.current = false;\n    rootRef.current?.querySelector<HTMLButtonElement>('button[tabindex=\"0\"]')?.focus();\n  });\n\n  const min = minDate ? startOfDay(minDate) : null;\n  const max = maxDate ? startOfDay(maxDate) : null;\n  const disabledKeys = useMemo(() => (Array.isArray(disabled) ? new Set(disabled.map(dayKey)) : null), [disabled]);\n\n  function isDisabled(date: Date) {\n    if (min && date < min) return true;\n    if (max && date > max) return true;\n    if (typeof disabled === \"function\") return disabled(date);\n    return disabledKeys?.has(dayKey(date)) ?? false;\n  }\n\n  function setMonth(next: Date) {\n    const value = startOfMonth(next);\n    if (!monthProp) setInnerMonth(value);\n    onMonthChange?.(value);\n  }\n\n  const lastVisible = addMonths(month, numberOfMonths - 1);\n  const canPrev = !min || startOfMonth(min) < month;\n  const canNext = !max || startOfMonth(max) > lastVisible;\n\n  function moveFocus(next: Date) {\n    let target = next;\n    if (min && target < min) target = min;\n    if (max && target > max) target = max;\n    setFocused(target);\n    if (target < month) setMonth(target);\n    else if (target > new Date(lastVisible.getFullYear(), lastVisible.getMonth() + 1, 0)) setMonth(addMonths(startOfMonth(target), -(numberOfMonths - 1)));\n    shouldFocus.current = true;\n  }\n\n  function select(date: Date) {\n    if (isDisabled(date)) return;\n    setFocused(date);\n    if (!isSameMonth(date, month) && !isSameMonth(date, lastVisible)) setMonth(date < month ? date : addMonths(startOfMonth(date), -(numberOfMonths - 1)));\n    if (mode === \"single\") {\n      const p = props as CalendarSingleProps;\n      if (p.value === undefined) setInnerSingle(date);\n      p.onValueChange?.(date);\n      return;\n    }\n    const p = props as CalendarRangeProps;\n    let next: DateRange;\n    if (!range.from || range.to) next = { from: date, to: null };\n    else if (date < range.from) next = { from: date, to: range.from };\n    else next = { from: range.from, to: date };\n    // A range never spans a disabled day.\n    if (next.from && next.to) {\n      for (let day = next.from; day <= next.to; day = addDays(day, 1)) {\n        if (isDisabled(day)) {\n          next = { from: date, to: null };\n          break;\n        }\n      }\n    }\n    if (p.value === undefined) setInnerRange(next);\n    p.onValueChange?.(next);\n  }\n\n  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {\n    const step: Record<string, () => Date> = {\n      ArrowLeft: () => addDays(focused, -1),\n      ArrowRight: () => addDays(focused, 1),\n      ArrowUp: () => addDays(focused, -7),\n      ArrowDown: () => addDays(focused, 7),\n      Home: () => addDays(focused, -((focused.getDay() - weekStartsOn + 7) % 7)),\n      End: () => addDays(focused, 6 - ((focused.getDay() - weekStartsOn + 7) % 7)),\n      PageUp: () => addMonths(focused, event.shiftKey ? -12 : -1),\n      PageDown: () => addMonths(focused, event.shiftKey ? 12 : 1),\n    };\n    const next = step[event.key];\n    if (!next) return;\n    event.preventDefault();\n    setInput(\"keyboard\");\n    moveFocus(next());\n  }\n\n  const monthFormat = useMemo(() => new Intl.DateTimeFormat(locale, { month: \"long\", year: \"numeric\" }), [locale]);\n  const dayFormat = useMemo(() => new Intl.DateTimeFormat(locale, { weekday: \"long\", month: \"long\", day: \"numeric\", year: \"numeric\" }), [locale]);\n  const weekdays = useMemo(() => {\n    const short = new Intl.DateTimeFormat(locale, { weekday: \"short\" });\n    const long = new Intl.DateTimeFormat(locale, { weekday: \"long\" });\n    // 2023-01-01 was a Sunday.\n    return Array.from({ length: 7 }, (_, index) => {\n      const date = new Date(2023, 0, 1 + ((index + weekStartsOn) % 7));\n      return { short: short.format(date).slice(0, 2), long: long.format(date) };\n    });\n  }, [locale, weekStartsOn]);\n\n  // While picking the end of a range, hovering previews the span.\n  const preview = mode === \"range\" && range.from && !range.to && hovered ? (hovered < range.from ? { from: hovered, to: range.from } : { from: range.from, to: hovered }) : null;\n  const months = Array.from({ length: numberOfMonths }, (_, index) => addMonths(month, index));\n  // The roving tab stop stays on a visible day.\n  const focusTarget = months.some((visible) => isSameMonth(visible, focused)) ? focused : (single && months.some((m) => isSameMonth(m, single)) ? single : month);\n\n  return (\n    <div\n      ref={rootRef}\n      data-slot=\"calendar\"\n      data-mode={mode}\n      className={cx(\"inline-grid gap-4 text-sm text-zinc-950 dark:text-white\", numberOfMonths === 2 && \"sm:grid-cols-2 sm:gap-6\", className)}\n      onPointerDown={() => setInput(\"pointer\")}\n    >\n      {months.map((visible, monthIndex) => {\n        const first = startOfMonth(visible);\n        const offset = (first.getDay() - weekStartsOn + 7) % 7;\n        const gridStart = addDays(first, -offset);\n        const days = Array.from({ length: 42 }, (_, index) => addDays(gridStart, index));\n        const weeks = Array.from({ length: 6 }, (_, row) => days.slice(row * 7, row * 7 + 7));\n        const title = monthFormat.format(visible);\n        const titleId = `${dayKey(first)}-title`;\n        const isFirst = monthIndex === 0;\n        const isLast = monthIndex === numberOfMonths - 1;\n\n        return (\n          <div key={dayKey(first)} className=\"grid w-[17.5rem] gap-2\">\n            <div className=\"relative flex h-8 items-center justify-center\">\n              {isFirst ? (\n                <NavButton label=\"Previous month\" disabled={!canPrev} onClick={() => setMonth(addMonths(month, -1))} className=\"absolute left-0\">\n                  <path d=\"M10 3.5 5.5 8l4.5 4.5\" />\n                </NavButton>\n              ) : null}\n              <h2 id={titleId} aria-live=\"polite\" className=\"text-sm font-semibold\">\n                {title}\n              </h2>\n              {isLast ? (\n                <NavButton label=\"Next month\" disabled={!canNext} onClick={() => setMonth(addMonths(month, 1))} className=\"absolute right-0\">\n                  <path d=\"M6 3.5 10.5 8 6 12.5\" />\n                </NavButton>\n              ) : null}\n            </div>\n            <div\n              role=\"grid\"\n              aria-labelledby={titleId}\n              aria-multiselectable={mode === \"range\" || undefined}\n              onKeyDown={onKeyDown}\n              onPointerLeave={() => setHovered(null)}\n              className=\"grid gap-0.5\"\n            >\n              <div role=\"row\" className=\"grid grid-cols-7\">\n                {weekdays.map((weekday) => (\n                  <div key={weekday.long} role=\"columnheader\" aria-label={weekday.long} className=\"flex h-8 items-center justify-center text-xs font-normal text-zinc-500\">\n                    {weekday.short}\n                  </div>\n                ))}\n              </div>\n              <div\n                key={`${dayKey(first)}-body`}\n                className={cx(\n                  \"grid gap-0.5\",\n                  // Clicking the arrows cross-fades the month; keyboard paging switches instantly.\n                  input === \"pointer\" && \"transition-opacity duration-150 ease-out motion-reduce:transition-none starting:opacity-0\",\n                )}\n              >\n                {weeks.map((week, row) => (\n                  <div key={row} role=\"row\" className=\"grid grid-cols-7\">\n                    {week.map((date, column) => {\n                      const outside = !isSameMonth(date, visible);\n                      if (outside && !showOutsideDays) return <div key={dayKey(date)} role=\"gridcell\" aria-hidden=\"true\" className=\"h-9\" />;\n                      const blocked = isDisabled(date);\n                      const isToday = isSameDay(date, today);\n                      const span = preview ?? (range.from && range.to ? range : null);\n                      const isStart = mode === \"range\" && isSameDay(date, span?.from ?? range.from);\n                      const isEnd = mode === \"range\" && isSameDay(date, span?.to ?? null);\n                      const inSpan = !!span?.from && !!span.to && date >= span.from && date <= span.to;\n                      const committed = !preview;\n                      const isSelected = mode === \"single\" ? isSameDay(date, single) : isSameDay(date, range.from) || isSameDay(date, range.to);\n                      const solid = mode === \"single\" ? isSelected : (isStart || isEnd) && (committed || isSameDay(date, range.from));\n                      const tabbable = isSameDay(date, focusTarget) && !outside;\n                      const bandStart = isStart || column === 0 || date.getDate() === 1;\n                      const bandEnd = isEnd || column === 6 || isSameDay(date, new Date(date.getFullYear(), date.getMonth() + 1, 0));\n\n                      return (\n                        <div\n                          key={dayKey(date)}\n                          role=\"gridcell\"\n                          aria-selected={mode === \"range\" ? inSpan && committed : isSelected}\n                          className={cx(\n                            \"relative flex h-9 items-center justify-center\",\n                            inSpan && !outside && cx(\n                              \"before:absolute before:inset-y-0 before:inset-x-0\",\n                              committed ? \"before:bg-zinc-950/[0.06] dark:before:bg-white/[0.09]\" : \"before:bg-zinc-950/[0.035] dark:before:bg-white/[0.05]\",\n                              bandStart && \"before:rounded-l-lg\",\n                              bandEnd && \"before:rounded-r-lg\",\n                            ),\n                          )}\n                        >\n                          <button\n                            type=\"button\"\n                            tabIndex={tabbable ? 0 : -1}\n                            aria-disabled={blocked || undefined}\n                            aria-current={isToday ? \"date\" : undefined}\n                            aria-label={dayFormat.format(date)}\n                            onClick={() => select(date)}\n                            onPointerEnter={() => mode === \"range\" && setHovered(date)}\n                            onFocus={() => setFocused(date)}\n                            className={cx(\n                              \"relative z-[1] flex size-9 flex-col items-center justify-center rounded-lg text-sm tabular-nums\",\n                              \"transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none\",\n                              \"focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-sky-500\",\n                              solid\n                                ? \"bg-zinc-950 font-medium text-white dark:bg-white dark:text-black\"\n                                : blocked\n                                  ? \"cursor-not-allowed text-zinc-400 line-through decoration-zinc-950/25 dark:text-zinc-600 dark:decoration-white/25\"\n                                  : cx(\n                                      outside\n                                        ? \"text-zinc-400 dark:text-zinc-600\"\n                                        : inSpan || isToday\n                                          ? \"text-zinc-950 dark:text-white\"\n                                          : \"text-zinc-700 dark:text-zinc-300\",\n                                      \"hover:bg-zinc-950/[0.05] hover:text-zinc-950 dark:hover:bg-white/[0.08] dark:hover:text-white\",\n                                    ),\n                              isToday && !solid && \"font-semibold\",\n                            )}\n                          >\n                            {date.getDate()}\n                            {isToday ? (\n                              <span\n                                aria-hidden=\"true\"\n                                className={cx(\"absolute bottom-1.5 size-1 rounded-full\", solid ? \"bg-white dark:bg-black\" : \"bg-sky-500\")}\n                              />\n                            ) : null}\n                          </button>\n                        </div>\n                      );\n                    })}\n                  </div>\n                ))}\n              </div>\n            </div>\n          </div>\n        );\n      })}\n    </div>\n  );\n}\n\nfunction NavButton({\n  label,\n  disabled,\n  onClick,\n  className,\n  children,\n}: {\n  label: string;\n  disabled?: boolean;\n  onClick: () => void;\n  className?: string;\n  children: ReactNode;\n}) {\n  return (\n    <button\n      type=\"button\"\n      aria-label={label}\n      disabled={disabled}\n      onClick={onClick}\n      className={cx(\n        \"inline-flex size-8 items-center justify-center rounded-lg text-zinc-600 dark:text-zinc-400\",\n        \"transition-[background-color,color,scale] duration-150 ease-out active:duration-100 motion-safe:active:scale-[0.94] motion-reduce:transition-none\",\n        \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n        \"focus-visible:outline-2 focus-visible:outline-offset-0 focus-visible:outline-sky-500\",\n        \"disabled:pointer-events-none disabled:opacity-35\",\n        className,\n      )}\n    >\n      <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" className=\"size-4\">\n        {children}\n      </svg>\n    </button>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport { addDays, Calendar, type DateRange, startOfDay } from \"@/components/shaken/ui/calendar\";\n\nexport default function CalendarExample() {\n  const today = startOfDay(new Date());\n  const [date, setDate] = useState<Date | null>(addDays(today, 2));\n  const [range, setRange] = useState<DateRange>({ from: addDays(today, -3), to: addDays(today, 3) });\n  // Weekends are closed for scheduled deploys.\n  const weekend = (day: Date) => day.getDay() === 0 || day.getDay() === 6;\n  const format = new Intl.DateTimeFormat(\"en-US\", { month: \"short\", day: \"numeric\" });\n\n  return (\n    <div className=\"flex flex-wrap items-start justify-center gap-6\">\n      <div className=\"grid gap-2 rounded-xl border border-zinc-950/10 p-3 dark:border-white/10\">\n        <Calendar value={date} onValueChange={setDate} disabled={weekend} />\n        <p className=\"px-1 text-xs text-zinc-500\">{date ? `Deploy on ${format.format(date)}` : \"Pick a weekday to deploy\"}</p>\n      </div>\n      <div className=\"grid gap-2 rounded-xl border border-zinc-950/10 p-3 dark:border-white/10\">\n        <Calendar mode=\"range\" value={range} onValueChange={setRange} />\n        <p className=\"px-1 text-xs text-zinc-500\">\n          {range.from && range.to ? `Logs from ${format.format(range.from)} to ${format.format(range.to)}` : \"Pick an end date\"}\n        </p>\n      </div>\n    </div>\n  );\n}\n"
  }
}
