Building a timezone-safe 52-week planning grid in React

A while ago I had to build a year-at-a-glance planning board: 52 weeks across the
top, grouped program rows down the side, each cell showing whether something is
scheduled that week. The kind of grid a field-service team, an agronomist, or a
maintenance crew plans a whole year on.

It looks like a table. It is not a table. It ate the better part of three weeks,
and almost none of that time went where I expected. Here are the parts that are
genuinely hard, with the approaches that finally worked — useful whether you're
building one yourself or just curious why "just a grid" is a trap.

1. There is no such thing as "52 weeks"

The first instinct is to render 52 columns. But a planning year is organised by
month, and months don't divide into weeks cleanly. You immediately hit two
different, equally valid models:

ISO-8601 weeks — real weeks, Monday-start, where a week belongs to the month that holds its Thursday. Accurate, but months get 4 or 5 weeks unevenly, and it shifts year to year.
A simple 4-4-5 pattern — the accounting-style calendar where each quarter is 4 + 4 + 5 weeks (52 total), identical every year. Predictable, but not "real" dates.

Different users want different ones, so the week count per month has to be a
strategy, not a constant:

type WeekStrategy = 'iso' | 'simple'

function weeksInMonth(monthIndex: number, cfg: PlannerConfig): number {
  if (cfg.weekStrategy === 'simple') {
    const pattern = cfg.simplePattern ?? [4, 4, 5]
    return pattern[monthIndex % pattern.length]
  }
  return isoWeeksInMonth(cfg.year, monthIndex) // 4 or 5, computed from dates
}

The moment "52" stops being hard-coded, the rest of the grid has to stop
assuming it too — column widths, headers, and cell lookups all derive from this.

2. The year doesn't start in January

Plenty of planning years don't start in January. A Southern-Hemisphere turf
program starts in July. A retailer's fiscal year might start in February. So the
column order can't be a fixed ['Jan', 'Feb', ...] array — it has to rotate from
a configurable start month:

interface PlannerConfig {
  year: number
  startMonth: number        // 1–12
  weekStrategy: WeekStrategy
  simplePattern?: number[]
  locale?: string
}

function buildColumns(cfg: PlannerConfig) {
  const cols = []
  for (let i = 0; i < 12; i++) {
    const monthOffset = cfg.startMonth - 1 + i
    const month = (monthOffset % 12) + 1
    const year = cfg.year + Math.floor(monthOffset / 12) // rolls into next year
    cols.push({ month, year, weeks: weeksInMonth(i, cfg) })
  }
  return cols
}

And the month labels should never be a hand-typed array either — that's a
localisation bug waiting to happen. Let the platform do it:

const label = new Intl.DateTimeFormat(cfg.locale ?? 'en', { month: 'short' })
  .format(new Date(year, month - 1, 1))

Now "July-start, en-AU" and "February-start, de-DE" both just work, and you
haven't written a single month name.

3. Never read the clock inside your logic

Here's the bug that will bite you in production but never in development:
highlighting the current week.

// ❌ reads the clock deep inside a pure-looking function
function isCurrentWeek(week: Week) {
  return week.start <= new Date() && new Date() < week.end
}

This breaks two ways. On the server (SSR / React Server Components) it computes a
different "now" than the client, and you get a hydration mismatch. And it makes
the function impossible to test deterministically — you can't unit-test "what
does week 12 look like on this date" if the function secretly asks the OS.

The fix is boring and powerful: inject "today" as a parameter. Your entire
date/week engine becomes pure — same inputs, same output, forever.

// ✅ deterministic and SSR-safe
function isCurrentWeek(week: Week, today: Date) {
  return week.start <= today && today < week.end
}

Push the single new Date() to the very edge of the app (one prop at the top),
and everything below it is testable and timezone-safe.

4. Season bands wrap around the year boundary

If you colour the header by season, you hit a subtle one. In a July-start year,
"Winter" might be June–August. But June is the last column and July–August are
the first two. So a single season band has to render as two segments — one
at each end of the grid — without you special-casing it.

The trick is to define a band by the set of months it covers, then let the
column builder place segments wherever those months landed after rotation:

interface SeasonBand { id: string; label: string; months: number[]; color: string }

// After buildColumns(), group *contiguous runs* of columns whose month is in the
// band. A band split by the fiscal boundary naturally yields two runs.

Define seasons as data, derive the visual segments from the rotated columns, and
the wrap-around handles itself. Hard-code the spans and you'll be patching edge
cases forever.

5. Sticky headers, and not re-rendering 4,000 cells

Two performance/UX notes that cost real time:

Sticky in two axes at once. Row labels stick left, the season/month/week header sticks top, and they have to cooperate while scrolling. Getting position: sticky to behave in both directions across Chrome, Safari, and Firefox is fiddlier than it sounds — test all three early.
Don't re-render the whole grid on one cell change. A 60-row × 64-week board is ~4,000 cells. If toggling one cell re-renders all of them, dragging feels awful. Memoise at the row level and key cells stably so a single edit touches a single row.

6. Print is a feature, not an afterthought

The thing users actually asked for, that I budgeted zero time for: a printable
wall chart. A superintendent wants to pin the whole year to the shed wall.

Print is its own layout problem. You want an @page setup for A3/A4 in portrait
and landscape, column density tuned so a full year fits the page width, and
section rows that never split across a page break:

@media print {
  @page { size: A3 landscape; }
  .section-group { break-inside: avoid; }
  .app-chrome { display: none; }   /* hide nav/buttons; print only the board */
}

It demos beautifully and it's the part people remember — but it's a day of work
on its own, separate from the on-screen grid.

The principle underneath all of it

The thing that made the whole build sane: separate the logic from the
presentation. All the week math, column rotation, season banding, and status
logic live in pure functions with no JSX, no DOM, and no clock reads. The React
components are a thin rendering layer on top. That split is what makes the engine
testable (I got the core to ~99% coverage), SSR-safe, and reusable across totally
different domains — the same grid renders a turf program, a pest-control route
schedule, or a maintenance plan, just from different data.

If you're building one of these, budget for the six things above — they're where
the time actually goes.

I packaged this grid engine as a commercial Next.js template called
SeasonBoard — config-driven, type-safe, with the print layout and headless core described here.

🔗 Live demo (click around, switch datasets, hit Print): https://seasonboard.vercel.app/
📦 Get it on Gumroad (Solo & Team licences): https://5376434736463.gumroad.com/l/djdfba/osvog2b

If you'd rather not spend the three weeks, it'll save you most of them. Either
way, I hope the breakdown above saves you some pain.

推荐订阅源

DEV Community