calendar

Use for a value per day where the weekly and seasonal rhythm matters: commits, steps, sales, incidents. One row = one day: x is a YYYY-MM-DD date, y a number. Weeks run left to right, Monday to Sunday top to bottom, one band per year. Position comes from the date, so row order does not matter. A day absent from the table is a faint empty cell; a day with an empty value is hatched as missing, never drawn as zero. Optional min / max fix the color domain so several calendars compare. A malformed or impossible date (2026-02-30), or dates spanning more than five calendar years, → E_BAD_DATE. A repeated date → E_DUP_KEY. series is ignored.

Do not use for a few points in time (line) or for categories that are not days (heatmap).

x YYYY-MM-DD date · y number · series ignored

Rules. One row per day. Position comes from the date, not row order. A day absent from the table is an empty cell; an empty y is a missing cell, not zero. Optional min/max fix the color domain. A malformed or impossible date, or dates spanning more than five calendar years → E_BAD_DATE. A repeated date → E_DUP_KEY.

Example

markvis: 2
type: calendar
title: Runs clustered on weekends in March
unit: km
x: date
y: km

date,km
2026-03-01,12
2026-03-04,5
2026-03-07,14
2026-03-08,10
2026-03-11,6
2026-03-14,16
2026-03-15,
2026-03-21,13
2026-03-22,11
2026-03-28,18
2026-03-29,9

Runs clustered on weekends in March

date	km
2026-03-01	12
2026-03-04	5
2026-03-07	14
2026-03-08	10
2026-03-11	6
2026-03-14	16
2026-03-15
2026-03-21	13
2026-03-22	11
2026-03-28	18
2026-03-29	9

When the block is wrong

The rows stay, with one line that names the error.

markvis: 2
type: calendar
title: Impossible date
x: date
y: km

date,km
2026-02-30,5

date	km
2026-02-30	5

E_BAD_DATE: row 1, column date: "2026-02-30" is not a YYYY-MM-DD date

Generated from packages/types/calendar/ and the type's row in SPEC.md.