@dashforge/calendar-core

@dashforge/calendar-core is the headless engine behind the Dashforge date picker suite. It is pure logic — a React hook and a set of dependency-free date functions — with no UI and no styling of its own.

Both calendar skins build on it: the MUI <Calendar> / <DatePicker> in @dashforge/ui and the Tailwind <Calendar> / <DatePicker> in @dashforge/tw render the same useCalendar view-model with their own markup. If you need a calendar that matches neither skin, consume the engine directly and render whatever you like.

Installation

npm install @dashforge/calendar-core

React 18 or 19 is a peer dependency. If you already use @dashforge/ui or @dashforge/tw, the package is installed for you as a transitive dependency — import from it directly when you need the headless API.

useCalendar

The hook turns a set of options into a render-ready month-grid view-model plus action callbacks. It holds the displayed month and the roving-focus cell as internal state — both can be controlled.

import { useCalendar } from '@dashforge/calendar-core';

function MiniCalendar() {
  const cal = useCalendar({ defaultMonth: 5, defaultYear: 2026 });

  return (
    <div>
      <header>
        <button onClick={cal.goToPreviousMonth} aria-label="Previous month">‹</button>
        <strong>{cal.monthLabel}</strong>
        <button onClick={cal.goToNextMonth} aria-label="Next month">›</button>
      </header>

      <div role="grid">
        <div role="row">
          {cal.weekdayNames.map((name) => (
            <span role="columnheader" key={name}>{name}</span>
          ))}
        </div>
        {cal.weeks.map((week) => (
          <div role="row" key={week.key}>
            {week.days.map((day) => (
              <button
                key={day.iso}
                role="gridcell"
                aria-selected={day.isSelected}
                aria-current={day.isToday ? 'date' : undefined}
                disabled={day.isDisabled}
                onClick={() => cal.selectDate(day.iso)}
              >
                {day.day}
              </button>
            ))}
          </div>
        ))}
      </div>
    </div>
  );
}

Every cell in weeks arrives with its render flags pre-computed — isSelected, isToday, isDisabled, isSiblingMonth, isFocused — so the skin never has to re-derive them.

Options — UseCalendarOptions

Result — UseCalendarResult

useDateRange

useDateRange builds on useCalendar to add range selection — a { start, end } pair. It layers a small state machine on the month grid: the first selectDate sets the range start, the second sets the end (auto-swapped if it lands earlier), a third restarts. While only a start is picked, hoverDate drives a live preview band. It renders one or two consecutive months (monthCount), so a skin can show a single calendar or a side-by-side dual-month range picker.

import { useDateRange } from '@dashforge/calendar-core';

function MiniRange() {
  const cal = useDateRange({ monthCount: 2, defaultMonth: 5, defaultYear: 2026 });

  return (
    <div style={{ display: 'flex', gap: 16 }}>
      {cal.months.map((month) => (
        <div key={`${month.year}-${month.month}`}>
          <strong>{month.monthLabel}</strong>
          {month.weeks.map((week) => (
            <div role="row" key={week.key}>
              {week.days.map((day) => (
                <button
                  key={day.iso}
                  aria-pressed={day.isRangeStart || day.isRangeEnd}
                  data-in-range={day.isInRange || day.isRangePreview}
                  onClick={() => cal.selectDate(day.iso)}
                  onMouseEnter={() => cal.hoverDate(day.iso)}
                >
                  {day.day}
                </button>
              ))}
            </div>
          ))}
        </div>
      ))}
    </div>
  );
}

Each cell extends CalendarDay with four range flags — isRangeStart, isRangeEnd, isInRange (the committed band) and isRangePreview (the hovered band).

Options — UseDateRangeOptions

Result — UseDateRangeResult

Pure date utilities

The core/ layer is a flat set of pure, dependency-free functions. They take and return ISODate strings (YYYY-MM-DD) or DateParts objects — never JavaScript Date instances at the boundary — so there are no time-zone or mutation surprises.

ISO parsing & formatting

Arithmetic

Comparison

Month grid

Localization

Time

The time helpers back the upcoming TimePicker — strings are HH:mm / HH:mm:ss, never Date objects.

Keyboard

Types

Notes

• Zero dependencies. The package ships pure TypeScript; React is the only peer. Nothing else is pulled into your bundle.
• No Date at the boundary. Inputs and outputs are ISODate strings or DateParts. Date.UTC is used only internally for arithmetic, so a stored YYYY-MM-DD never drifts across time zones or DST.
• Headless by design. useCalendar renders nothing. For a ready-made UI use <Calendar> / <DatePicker> from @dashforge/ui or @dashforge/tw; reach for the hook only when you need a bespoke presentation.