@objectifthunes/whiteboard
DATES

Date helpers

buildMonthGrid, toISODate, addMonths and friends — local-time date maths with no date library.


PREVIEW
Arithmetic that clamps
addMonths(31 Jan, 1)
2026-02-28
addMonths(31 Jan, 13)
2027-02-28
addDays(31 Jan, 1)
2026-02-01
startOfMonth
2026-01-01
endOfMonth
2026-01-31
Formatting and parsing
toISODate
2026-01-31
formatDate
31 Jan 2026
monthLabel
January 2026
fromISODate('2026-02-31')
null
fromISODate('2026-02-28')
2026-02-28
Grids
buildMonthGrid rows
6
first cell
2026-07-27
last cell
2026-09-06
weekdayLabels(1)
Mon Tue Wed Thu Fri Sat Sun
weekdayLabels(0)
Sun Mon Tue Wed Thu Fri Sat
buildWeek(31 Jan)
26 27 28 29 30 31 1
isSameDay(D, D)
true
SOURCE
import {
  startOfDay, startOfMonth, endOfMonth,
  addDays, addMonths,
  isSameDay, isSameMonth, isWithin, clampDate,
  toISODate, fromISODate,
  buildMonthGrid, buildWeek, weekdayLabels, monthLabel, formatDate,
} from '@objectifthunes/whiteboard'

buildMonthGrid(new Date(2026, 7, 1))  // Date[6][7], always six rows
toISODate(new Date(2026, 0, 31))      // '2026-01-31' from LOCAL fields
fromISODate('2026-02-31')             // null — rejected, not rolled over
addMonths(new Date(2026, 0, 31), 1)   // 28 Feb, clamped
NOTES

Plain Date maths, no date library. The package ships with no runtime dependencies and a month grid does not justify adding one.

Everything works in local time. toISODate reads the local calendar fields rather than going through toISOString(), which converts to UTC and can hand you the wrong day either side of midnight. That single detail is why this module exists instead of inline formatting.

addMonths clamps rather than overflowing: 31 January plus one month is 28 February, not 3 March. fromISODate rejects impossible dates like 2026-02-31 instead of silently rolling them into March.

buildMonthGrid always returns six rows, which is what keeps a Calendar one fixed height across months. weekdayLabels derives its names from Intl using a reference week, so it follows the locale with no hardcoded list.

On server rendering. The Intl helpers — formatDate, monthLabel, weekdayLabels — resolve to whatever locale the rendererhas. Under SSR, or a static export where the "server" is the build machine, that is not the reader's locale: the server writes "Aug 20, 2026" where a British reader should see "20 Aug 2026".

useIsHydrated is the fix, and Calendar, DatePicker, DateRangePicker and WeekView all use it. It returns false on the server and on the first client render, then true — and you put it in the key of the element holding the text, not just anywhere:

<span key={hydrated ? 'client' : 'server'} suppressHydrationWarning>

The key is load-bearing. suppressHydrationWarningon its own silences the warning but also tells React to keep the server's DOM text, and React then records theclientstring as the current value — so on every later render it sees no change and never writes the DOM. The server's format would stay on screen for good. Flipping the key remounts the node, which forces the client string in. Pass an explicit locale if you would rather both passes agree and skip the correction.