How do I render a month?

I think that is the wrong first question.

A better one is:

What is a calendar before it becomes a user interface?

That distinction sounds philosophical until the same calendar has to survive:

• multiple locales
• Sunday-first and Monday-first weeks
• leap years
• print layouts
• PDFs
• mobile interfaces
• static generation
• server-side rendering
• accessibility requirements
• date-only values
• timezone-aware events

At that point, the calendar is no longer a grid of <div> elements.

It is a domain model.

So I tried something different.

Instead of building another date picker, I built a small calendar compiler.

I call the idea ChronoGrid.

Its job is simple:

Calendar Specification
        ↓
Normalization
        ↓
Temporal Rule Engine
        ↓
Canonical Calendar Model
        ↓
Invariant Validation
        ↓
Render Targets

The renderer comes last.

That one decision changes almost everything.

1. Treat the calendar as source code

A compiler does not begin by drawing pixels.

It begins with input.

So ChronoGrid begins with a declarative specification:

const spec = {
  year: 2027,
  month: 3,
  locale: "en-US",
  weekStartsOn: 1,

  grid: {
    rows: 6,
    columns: 7,
    includeAdjacentDays: false
  }
};

This object is not HTML.

It does not know anything about CSS.

It does not know whether the final output will become:

Web
Print
PDF
SVG
JSON
Mobile

It only describes intent.

That gives us our first architectural boundary:

INPUT ≠ OUTPUT

The calendar specification describes what we want.

The renderer decides how it looks.

2. Normalize before calculating anything

User-facing configuration tends to be messy.

For example, these could all represent the same request:

{
  year: 2027,
  month: 3
}

{
  year: "2027",
  month: "03"
}

{
  year: 2027,
  month: 3,
  weekStartsOn: undefined
}

Instead of letting every downstream function deal with optional values, normalize once.

function normalizeSpec(input) {
  const year = Number(input.year);
  const month = Number(input.month);

  if (!Number.isInteger(year)) {
    throw new TypeError("year must be an integer");
  }

  if (!Number.isInteger(month) || month < 1 || month > 12) {
    throw new RangeError("month must be between 1 and 12");
  }

  const weekStartsOn =
    Number.isInteger(input.weekStartsOn)
      ? input.weekStartsOn
      : 0;

  if (weekStartsOn < 0 || weekStartsOn > 6) {
    throw new RangeError(
      "weekStartsOn must be between 0 and 6"
    );
  }

  return {
    year,
    month,
    locale: input.locale ?? "en-US",
    weekStartsOn,

    grid: {
      rows: input.grid?.rows ?? 6,
      columns: 7,
      includeAdjacentDays:
        input.grid?.includeAdjacentDays ?? false
    }
  };
}

After normalization, the rest of the system receives a stronger guarantee.

That means downstream code does not need to repeatedly ask:

Is month defined?
Is it a string?
Is weekStartsOn missing?
Is the value valid?

Those questions have already been answered.

This is one of the most useful patterns in date-heavy systems:

Make invalid states fail at the boundary.

3. Month navigation is arithmetic, not branching

Calendar code often accumulates January and December special cases.

Something like this:

if (month === 12) {
  year++;
  month = 1;
} else {
  month++;
}

Then a reversed version appears for previous month.

Then again in another component.

Then again inside a date picker.

Instead, convert the calendar position into a linear month index.

function toMonthIndex(year, month) {
  return year * 12 + (month - 1);
}

And convert it back:

function fromMonthIndex(index) {
  const year = Math.floor(index / 12);

  const month =
    ((index % 12) + 12) % 12 + 1;

  return {
    year,
    month
  };
}

Now shifting months becomes:

function shiftMonth(year, month, delta) {
  const index =
    toMonthIndex(year, month) + delta;

  return fromMonthIndex(index);
}

Examples:

shiftMonth(2027, 12, 1);

returns:

{
  year: 2028,
  month: 1
}

And:

shiftMonth(2027, 1, -1);

returns:

{
  year: 2026,
  month: 12
}

December and January are no longer special cases.

They are consequences of arithmetic.

That is an important design signal:

Good domain models often make edge cases disappear into the model itself.

4. Build a canonical intermediate representation

A compiler usually creates some form of intermediate representation.

ChronoGrid does the same.

Instead of rendering dates directly, it produces a canonical calendar model.

For example:

{
  type: "CalendarMonth",
  year: 2027,
  month: 3,

  metadata: {
    firstWeekday: 1,
    daysInMonth: 31,
    weekStartsOn: 1
  },

  cells: [
    {
      type: "Day",
      date: {
        year: 2027,
        month: 3,
        day: 1
      },
      position: 0
    }
  ]
}

This becomes the contract between the calendar engine and every renderer.

The renderer does not calculate dates.

The engine does not generate markup.

That separation is the entire point.

5. Calculate month length without storing month tables

There is no need to maintain:

const days = [
  31,
  28,
  31,
  30
  // ...
];

We can derive the value.

function daysInMonth(year, month) {
  return new Date(
    Date.UTC(year, month, 0)
  ).getUTCDate();
}

Now:

daysInMonth(2027, 2);
// 28

And:

daysInMonth(2028, 2);
// 29

Leap-year behavior comes from the date primitive rather than duplicated business logic.

This is a small function, but it expresses a larger principle:

Derived truth is usually safer than duplicated truth.

6. Calculate the first visible offset

Now we need to know where day 1 belongs.

function firstWeekday(year, month) {
  return new Date(
    Date.UTC(year, month - 1, 1)
  ).getUTCDay();
}

For a Sunday-first calendar, the returned weekday can be used directly.

But if the week begins on Monday, the offset changes.

Normalize it:

function getMonthOffset(
  year,
  month,
  weekStartsOn
) {
  const weekday =
    firstWeekday(year, month);

  return (
    weekday -
    weekStartsOn +
    7
  ) % 7;
}

This works for any valid first weekday.

No separate Monday renderer.

No separate Sunday renderer.

Just configuration.

7. Compile the month into cells

Now the compiler can produce the canonical grid.

function compileMonth(spec) {
  const normalized =
    normalizeSpec(spec);

  const {
    year,
    month,
    weekStartsOn,
    grid
  } = normalized;

  const totalDays =
    daysInMonth(year, month);

  const offset =
    getMonthOffset(
      year,
      month,
      weekStartsOn
    );

  const cellCount =
    grid.rows * grid.columns;

  const cells =
    Array.from(
      { length: cellCount },
      (_, position) => {
        const day =
          position - offset + 1;

        if (
          day < 1 ||
          day > totalDays
        ) {
          return {
            type: "Empty",
            position
          };
        }

        return {
          type: "Day",

          date: {
            year,
            month,
            day
          },

          position
        };
      }
    );

  return {
    type: "CalendarMonth",

    year,
    month,

    metadata: {
      daysInMonth: totalDays,
      firstWeekday:
        firstWeekday(year, month),
      weekStartsOn,
      rows: grid.rows,
      columns: grid.columns
    },

    cells
  };
}

At this point we have a complete month.

But still no HTML.

That is intentional.

8. Why explicit cell types matter

The easiest representation would be:

[
  null,
  null,
  1,
  2,
  3
]

That works.

But explicit states scale better.

Compare:

{
  type: "Empty",
  position: 0
}

with:

{
  type: "Day",

  date: {
    year: 2027,
    month: 3,
    day: 14
  },

  position: 13
}

Later we can safely extend a day:

{
  type: "Day",

  date: {
    year: 2027,
    month: 3,
    day: 14
  },

  position: 13,

  flags: {
    isToday: false,
    isSelected: true,
    isWeekend: false
  }
}

No magic values.

No guessing what null means.

No renderer-specific interpretation.

The data describes itself.

9. A calendar should be validated before it is rendered

This is where the compiler model becomes especially useful.

A UI-first implementation often assumes:

If it rendered, it probably worked.

ChronoGrid assumes the opposite:

Rendering should only happen after the model has been proven internally consistent.

So define invariants.

function validateMonth(model) {
  const {
    cells,
    metadata
  } = model;

  const expectedCellCount =
    metadata.rows *
    metadata.columns;

  if (
    cells.length !==
    expectedCellCount
  ) {
    throw new Error(
      "Invalid cell count"
    );
  }

  const days =
    cells.filter(
      cell =>
        cell.type === "Day"
    );

  if (
    days.length !==
    metadata.daysInMonth
  ) {
    throw new Error(
      "Day count mismatch"
    );
  }

  for (
    let expectedDay = 1;
    expectedDay <=
      metadata.daysInMonth;
    expectedDay++
  ) {
    const found =
      days.some(
        cell =>
          cell.date.day ===
          expectedDay
      );

    if (!found) {
      throw new Error(
        `Missing day: ${expectedDay}`
      );
    }
  }

  return true;
}

Only validated models reach the renderer.

That changes the debugging question from:

Why does the UI look wrong?

to:

Which invariant failed?

The second question is much easier to answer.

10. Test thousands of months instead of twelve examples

Calendar engines are perfect for property-oriented testing.

Let's test every month between 1600 and 2400.

let tested = 0;

for (
  let year = 1600;
  year <= 2400;
  year++
) {
  for (
    let month = 1;
    month <= 12;
    month++
  ) {
    const model =
      compileMonth({
        year,
        month,
        weekStartsOn: 1
      });

    validateMonth(model);

    tested++;
  }
}

console.log(tested);

That tests:

801 years × 12 months
=
9,612 months

We can also test every supported week start:

let tested = 0;

for (
  let year = 1600;
  year <= 2400;
  year++
) {
  for (
    let month = 1;
    month <= 12;
    month++
  ) {
    for (
      let weekStartsOn = 0;
      weekStartsOn < 7;
      weekStartsOn++
    ) {
      const model =
        compileMonth({
          year,
          month,
          weekStartsOn
        });

      validateMonth(model);

      tested++;
    }
  }
}

console.log(tested);

Now we have validated:

9,612 months
×
7 week conventions

=
67,284 compiled calendars

This still runs quickly.

That is much stronger than manually checking a few screenshots.

11. Reversibility is a useful invariant

Month navigation should be reversible.

This:

const next =
  shiftMonth(
    2027,
    12,
    1
  );

followed by:

const original =
  shiftMonth(
    next.year,
    next.month,
    -1
  );

should return:

{
  year: 2027,
  month: 12
}

We can test the property broadly:

for (
  let year = 1600;
  year <= 2400;
  year++
) {
  for (
    let month = 1;
    month <= 12;
    month++
  ) {
    const forward =
      shiftMonth(
        year,
        month,
        1
      );

    const backward =
      shiftMonth(
        forward.year,
        forward.month,
        -1
      );

    if (
      backward.year !== year ||
      backward.month !== month
    ) {
      throw new Error(
        `Transition failure: ${year}-${month}`
      );
    }
  }
}

Notice that we did not write separate tests for:

December → January
January → December

The property covers them automatically.

12. Composition gives us another property

If month shifting behaves like arithmetic, then:

shift(a + b)

should be equivalent to:

shift(a)
then
shift(b)

Let's verify it.

function equalMonth(a, b) {
  return (
    a.year === b.year &&
    a.month === b.month
  );
}

Now:

function shiftTwice(
  year,
  month,
  firstDelta,
  secondDelta
) {
  const first =
    shiftMonth(
      year,
      month,
      firstDelta
    );

  return shiftMonth(
    first.year,
    first.month,
    secondDelta
  );
}

Compare:

const direct =
  shiftMonth(
    2027,
    3,
    17
  );

const composed =
  shiftTwice(
    2027,
    3,
    8,
    9
  );

console.assert(
  equalMonth(
    direct,
    composed
  )
);

This may look academic.

But these properties are exactly what keep navigation logic reliable when the system grows.

At this point, calendar navigation starts behaving like a tiny algebra.

13. Determinism is one of the most valuable features

Given:

compileMonth({
  year: 2027,
  month: 3,
  weekStartsOn: 1
});

the output should always be identical.

It should not depend on:

current clock
browser timezone
screen size
DOM state
network state
user session
random values

That gives us something extremely useful.

A bug report can become:

year = 2027
month = 3
weekStartsOn = 1

And the exact model can be reproduced anywhere.

Deterministic systems are easier to:

• test
• cache
• serialize
• snapshot
• debug
• render on servers
• render on clients
• compare across environments

For date-heavy code, determinism is almost a superpower.

14. Never hide "now" inside the calendar engine

This looks innocent:

function isToday(
  year,
  month,
  day
) {
  const now =
    new Date();

  return (
    year ===
      now.getFullYear() &&
    month ===
      now.getMonth() + 1 &&
    day ===
      now.getDate()
  );
}

But the function has a hidden input:

current time

Its output can change without any explicit argument changing.

Instead, inject the reference date.

function isSameDate(
  a,
  b
) {
  return (
    a.year === b.year &&
    a.month === b.month &&
    a.day === b.day
  );
}

Now:

const today = {
  year: 2027,
  month: 3,
  day: 14
};

can be passed explicitly.

That keeps time-dependent behavior at the boundary of the system.

The core stays deterministic.

15. Date-only values should remain date-only

One of the biggest mistakes in calendar software is assuming every date needs a timestamp.

Consider these values:

Birthday:
March 14

Printed calendar cell:
March 14, 2027

Meeting:
March 14, 2027 at 09:00 in New York

Server event:
2027-03-14T13:00:00Z

They look related.

But they represent different concepts.

The printed calendar cell does not inherently need:

hour
minute
timezone
UTC offset

Adding those concepts too early creates transformations that the domain never asked for.

So the canonical calendar model stores:

{
  year: 2027,
  month: 3,
  day: 14
}

Not:

new Date(...)

unless the domain truly requires a point in time.

This drastically reduces timezone bugs.

16. Renderers should be disposable

Because the compiler creates a neutral intermediate representation, rendering becomes simple.

HTML:

function renderHTML(model) {
  return model.cells
    .map(cell => {
      if (
        cell.type === "Empty"
      ) {
        return `
          <div
            class="calendar-cell calendar-cell--empty"
          ></div>
        `;
      }

      return `
        <div class="calendar-cell">
          <time
            datetime="${cell.date.year}-${String(
              cell.date.month
            ).padStart(2, "0")}-${String(
              cell.date.day
            ).padStart(2, "0")}"
          >
            ${cell.date.day}
          </time>
        </div>
      `;
    })
    .join("");
}

Text output:

function renderText(model) {
  const rows = [];

  for (
    let row = 0;
    row <
      model.metadata.rows;
    row++
  ) {
    const start =
      row *
      model.metadata.columns;

    const cells =
      model.cells.slice(
        start,
        start +
          model.metadata.columns
      );

    rows.push(
      cells
        .map(cell => {
          if (
            cell.type ===
            "Empty"
          ) {
            return "  ";
          }

          return String(
            cell.date.day
          ).padStart(2, " ");
        })
        .join(" ")
    );
  }

  return rows.join("\n");
}

A PDF renderer could consume the same model.

So could SVG.

So could React.

So could server-side HTML.

The engine remains unchanged.

17. Print makes this separation especially valuable

The original motivation for thinking this way came from working with calendar resources at JW Calendar, where the same underlying date model may eventually need to survive responsive web layouts, printable pages, PDFs, localization, and different week conventions.

Screen rendering cares about:

viewport size
interaction
breakpoints
hover states
scrolling
dynamic resizing

Print rendering cares about:

physical dimensions
paper size
orientation
margins
page breaks
print scaling
ink contrast

Those are radically different presentation environments.

But the underlying March 2027 calendar is still March 2027.

That is exactly why the domain model should not contain CSS assumptions.

18. Localization belongs after calendar math

The calendar engine should not hard-code:

[
  "January",
  "February",
  "March"
]

The engine knows:

{
  year: 2027,
  month: 3
}

The presentation layer decides how to label it.

For example:

function getMonthLabel(
  year,
  month,
  locale
) {
  return new Intl.DateTimeFormat(
    locale,
    {
      month: "long",
      year: "numeric",
      timeZone: "UTC"
    }
  ).format(
    new Date(
      Date.UTC(
        year,
        month - 1,
        1
      )
    )
  );
}

Now:

getMonthLabel(
  2027,
  3,
  "en-US"
);

and:

getMonthLabel(
  2027,
  3,
  "de-DE"
);

can produce different labels from the same canonical month.

The calculation remains identical.

19. Serialization becomes trivial

Because the model is plain data:

const model =
  compileMonth({
    year: 2027,
    month: 3,
    weekStartsOn: 1
  });

we can serialize it:

const json =
  JSON.stringify(model);

Store it.

Send it through an API.

Snapshot it during tests.

Compare versions.

Cache it.

Generate static pages from it.

That would be much harder if the domain model contained:

DOM nodes
browser objects
event handlers
framework state

Plain data is incredibly portable.

20. Hashing enables deterministic caching

Once the input is normalized, it can also become a stable cache key.

function createCacheKey(spec) {
  const normalized =
    normalizeSpec(spec);

  return [
    normalized.year,
    normalized.month,
    normalized.weekStartsOn,
    normalized.locale,
    normalized.grid.rows,
    normalized.grid.columns
  ].join(":");
}

Example:

createCacheKey({
  year: 2027,
  month: 3,
  weekStartsOn: 1,
  locale: "en-US"
});

could produce:

2027:3:1:en-US:6:7

If the compiler is deterministic, identical inputs produce identical models.

That means the expensive parts of downstream rendering can be cached safely.

21. The compiler architecture makes new targets cheap

Suppose we later want SVG.

We do not redesign the date engine.

We write:

function renderSVG(model) {
  // consume canonical cells
}

Want PDF?

function renderPDF(model) {
  // consume canonical cells
}

Want an API?

function renderJSON(model) {
  return JSON.stringify(
    model
  );
}

Want a terminal calendar?

Same model.

Different renderer.

That is the architectural payoff.

22. The full pipeline

The system now looks like this:

USER SPECIFICATION
        │
        ↓
┌───────────────────┐
│    NORMALIZER     │
└─────────┬─────────┘
          │
          ↓
┌───────────────────┐
│   TEMPORAL RULES  │
└─────────┬─────────┘
          │
          ↓
┌───────────────────┐
│   CANONICAL IR    │
└─────────┬─────────┘
          │
          ↓
┌───────────────────┐
│     VALIDATOR     │
└─────────┬─────────┘
          │
          ↓
     VALID MODEL
          │
    ┌─────┼─────┬─────┐
    ↓     ↓     ↓     ↓
   WEB  PRINT  PDF   JSON

Each layer has one responsibility.

The normalizer cleans inputs.

The rule engine performs calendar arithmetic.

The intermediate representation stores neutral calendar data.

The validator proves invariants.

Renderers decide how the result should look.

23. What makes this feel like a compiler?

The analogy is stronger than it first appears.

A traditional compiler might have:

Source Code
↓
Parser
↓
AST
↓
Semantic Analysis
↓
Intermediate Representation
↓
Code Generation

ChronoGrid has:

Calendar Specification
↓
Normalization
↓
Rule Evaluation
↓
Canonical Calendar IR
↓
Invariant Validation
↓
Rendering

The renderer is effectively the code generator.

HTML is one target.

Print is another.

PDF is another.

JSON is another.

The calendar itself exists before any of them.

That is the key idea.

24. A calendar is better modeled as a temporal graph

The grid is only one projection of the data.

Consider March 14.

It has relationships:

belongs to → March
belongs to → 2027
follows → March 13
precedes → March 15
belongs to → a weekday
belongs to → a week
belongs to → a quarter
belongs to → a year

That means the visual 7×6 matrix is not necessarily the most fundamental representation.

It is a projection of a richer temporal structure.

This opens up interesting possibilities.

For example:

{
  id: "2027-03-14",

  previous: "2027-03-13",
  next: "2027-03-15",

  month: "2027-03",
  quarter: "2027-Q1",
  year: 2027
}

Now the engine can support more than rectangular calendars.

The same temporal model could power:

month views
week views
year views
timelines
print layouts
planning systems
date navigation

The grid becomes a renderer.

Not the domain.

25. The best calendar engine barely knows about UI

After building this experiment, the thing that surprised me most was how little the core engine actually needs.

It does not need:

React
Vue
Svelte
CSS
DOM APIs
Canvas
SVG
PDF libraries

It needs:

arithmetic
validation
normalization
invariants
plain data

Everything else is a consumer.

That is a useful architecture beyond calendars.

A domain model becomes much more reusable when presentation concerns are allowed to remain outside it.

Final thought

A calendar looks simple because humans have spent thousands of years making the concept familiar.

The software underneath it is not automatically simple.

Once we support:

• multiple week conventions
• leap years
• year transitions
• localization
• print
• PDFs
• accessibility
• deterministic rendering
• server-side generation
• timezone isolation
• multiple output targets

the problem starts looking less like:

Draw 42 boxes.

and more like:

Compile a temporal specification into a verified intermediate representation.

That is why I now prefer this rule:

Never render a calendar before you can prove the calendar model is valid.

The UI should be the final projection of the system.

Not the system itself.

And sometimes the most reliable way to build a calendar is to stop thinking of it as a calendar UI at all.

Treat it like a compiler.

What other deceptively simple UI components do you think would benefit from being modeled as a compiler or state machine first?