@thilakbhat/heatmap-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thilak Bhat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,471 @@
+# heatmap-ui
+
+![heatmap-ui playground preview](docs/cover.png)
+
+[![CI](https://github.com/tb962/heatmap-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/tb962/heatmap-ui/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@thilakbhat/heatmap-ui.svg)](https://www.npmjs.com/package/@thilakbhat/heatmap-ui)
+[![license](https://img.shields.io/npm/l/@thilakbhat/heatmap-ui.svg)](LICENSE)
+
+A headless heatmap toolkit for React. Eight cell shapes, an interactive 3D mode
+that runs on plain SVG, and control over every colour, size and label on the
+grid.
+
+**[Try it in the playground →](https://tb962.github.io/heatmap-ui/)**
+
+```bash
+npm install @thilakbhat/heatmap-ui
+```
+
+```tsx
+import { CalendarHeatmap } from "@thilakbhat/heatmap-ui";
+import "@thilakbhat/heatmap-ui/styles.css";
+
+<CalendarHeatmap values={days} weeks={20} showLegend />;
+```
+
+## What you get
+
+Five entry points: `Heatmap` for any grid, `CalendarHeatmap` for dates, their
+`Heatmap3D` and `CalendarHeatmap3D` counterparts, and `renderHeatmap3DSvg`,
+which returns an SVG string without React or a DOM.
+
+Everything below is a prop. None of it needs a wrapper, a fork, or a stylesheet
+override.
+
+| | |
+| --- | --- |
+| Cell shapes | `rounded`, `square`, `circle`, `diamond`, `hexagon`, `plus`, `bar`, `ring` |
+| 3D forms | `rectangle`, `circle` (cylinder), `bar` (slender column) |
+| 3D block styles | `solid`, `lego` (studs), `building` (windowed facades) |
+| 3D themes | `color` (your ramp), `night`, `seasonal`, `rainbow` |
+| Surfaces | flat fills, or SVG bitmap patterns you define per colour level |
+| Intensity | colour, cell size, or both |
+| Shading | `linear`, `quantile`, `log`, or a function you supply |
+| Colour | any ramp, palest first, with separate colours for zero and for no data |
+| Labels | row and column labels, tooltips, and arbitrary content inside cells |
+| Layout | cell size, gap, corner radius, and a predicate for hiding slots |
+
+### The 3D mode
+
+`Heatmap3D` draws an isometric scene in SVG. No WebGL, no canvas, no 3D library,
+and no second bundle: it ships in the same package as the flat grid and takes
+the same data, labels, tooltips, click handlers and legend props.
+
+Height comes from the value itself rather than from its colour band, so a 40
+is twice as tall as a 20. Blocks can be plain solids, LEGO bricks with
+studs sized to fit, or buildings with lit windows. You can drive the camera
+yourself or let the reader drag it. If you would rather ship a picture,
+`renderHeatmap3DSvg` renders the identical scene to a string for an email or a
+README.
+
+### Customisation
+
+Colour is a prop, not a theme file. Pass any ramp and the bands follow it. Pass
+`faceColor` and you control the top, left and right fills of every 3D block
+independently. Pass `patterns` and each colour level gets its own SVG bitmap,
+written as binary or hexadecimal rows.
+
+The stylesheet only handles structure and four CSS variables, so you are not
+fighting a design system to make the chart look like yours.
+
+### Data that stays honest
+
+A slot with no observation is not a slot with a zero. Pass `known: false` and it
+renders at reduced opacity and announces "No data" to a screen reader, instead
+of quietly reading as a day off. Ragged grids are supported through
+`isSlotHidden`, so a cohort table missing its future quarters does not have to
+invent them.
+
+Colour alone is invisible to roughly one reader in twelve, so `encode="size"`
+and `encode="both"` carry intensity redundantly.
+
+## The core
+
+```tsx
+import { Heatmap } from "@thilakbhat/heatmap-ui";
+
+<Heatmap rows={24} columns={7} values={matrix} />;
+```
+
+You can pass `values` in either form:
+
+```ts
+// Dense. null means no data; 0 means measured and empty.
+values={[[3, 0, null], [1, 5, 2]]}
+
+// Sparse. Anything not listed has no data.
+values={[{ row: 0, column: 0, value: 3, known: true, meta: anything }]}
+```
+
+| Prop | Default | |
+| --- | --- | --- |
+| `rows`, `columns` | required | Grid size. |
+| `values` | `[]` | Matrix or sparse cells. |
+| `scale` | `"linear"` | `"linear"`, `"quantile"`, `"log"`, or `(value, all) => 0..1`. |
+| `levels` | `colors.length` | Number of shade bands. |
+| `thresholds` | none | Explicit band ceilings; skips `scale`. |
+| `shape` | `"rounded"` | See below. |
+| `encode` | `"color"` | `"color"`, `"size"`, or `"both"`. |
+| `cellSize` | `13` | Pixels. |
+| `gap` | `3` | Pixels. |
+| `radius` | none | Overrides the shape's corner rounding. |
+| `colors` | GitHub green | The ramp, palest first. |
+| `emptyColor` | `#ebedf0` | A known value of zero. |
+| `unknownOpacity` | `0.5` | Applied to slots with no data. |
+| `isSlotHidden` | none | `(row, column) => boolean` for ragged grids. |
+| `rowLabels`, `columnLabels` | none | Positioned against the grid. |
+| `tooltip` | none | `(cell) => ReactNode`; opens on hover and focus. |
+| `cellContent` | none | Optional visual React node centred inside each cell; values are hidden unless provided. |
+| `cellLabel` | none | `(cell) => string`; the accessible name for a cell. |
+| `onCellClick` | none | Makes cells buttons. |
+| `showLegend` | `false` | less/more key, plus "no data" when relevant. |
+
+### Shading
+
+`scale="linear"` is the default. Bands are cut at even fractions of the largest
+value, which is what GitHub and most other heatmaps do, so a reader who knows
+one chart can read yours without relearning it.
+
+Switch to `quantile` when the data has a long tail. Ranking the active values
+keeps every band populated whatever the unit. On one real dataset, linear
+banding put 58% of active days in the first band while quantile banding put 25%
+in each:
+
+```
+linear    ████████████████████████████ ▓▓▓▓▓▓▓▓▓▓▓▓ ▒▒▒ ░░░░░
+quantile  ████████████ ▓▓▓▓▓▓▓▓▓▓▓▓ ▒▒▒▒▒▒▒▒▒▒▒▒ ░░░░░░░░░░░░
+```
+
+`log` suits values spanning orders of magnitude. A function gets the value and
+the full set and returns 0..1, and `thresholds` skips the whole question by
+naming the band ceilings yourself.
+
+## 3D heatmaps
+
+Use `Heatmap3D` for any grid, or `CalendarHeatmap3D` for dates. Both render a
+shaded, interactive SVG scene without WebGL.
+
+```tsx
+import { Heatmap3D, CalendarHeatmap3D } from "@thilakbhat/heatmap-ui";
+import "@thilakbhat/heatmap-ui/styles.css";
+
+<Heatmap3D
+  rows={2}
+  columns={3}
+  values={[[20, 40, 80], [0, null, 60]]}
+  shape="rectangle"
+  blockStyle="lego"
+  maxHeight={75}
+  showLegend
+  tooltip={cell => cell.known ? `${cell.value} events` : "No data"}
+/>;
+
+<CalendarHeatmap3D values={days} weeks={20} blockStyle="building" />;
+```
+
+### Playground previews
+
+**2D calendar view**
+
+![2D calendar heatmap preview in the playground.](docs/playground-2d.png)
+
+**3D calendar view**
+
+![3D calendar heatmap preview in the playground, with height-based values and orbit controls.](docs/playground-3d.png)
+
+Height is proportional to the actual value: with the default domain, 40 is
+twice as tall as 20. The `scale`, `levels`, and `thresholds` props only affect
+colour bands. LEGO studs fit inside that height. Measured zeroes are flat
+tiles. Missing slots get an outline, and hidden slots are omitted.
+
+| Prop | Default | Behaviour |
+| --- | --- | --- |
+| `shape` | `"rectangle"` | `"rectangle"`, `"circle"` (cylinder), or `"bar"` (slender column). |
+| `blockStyle` | `"solid"` | `"solid"`, `"lego"` (studs), or `"building"` (windowed facades). |
+| `theme` | `"color"` | `"color"` paints with `colors` and sets only the face-aware neutrals around it. `"night"`, `"seasonal"`, and `"rainbow"` bring their own ramp, so leave `colors` unset with those. |
+| `material` | `"solid"` | `"solid"` or `"pattern"`; pattern material uses SVG bitmap marks over each face. |
+| `patterns` | built-in | Optional `{ top, side }` arrays of `{ width, bitmap, background, foreground }`, indexed by colour level. |
+| `faceColor` | preset shading | `(args) => string` resolver for different top, left, and right fills. |
+| `animation` | `"none"` | `"grow"` adds a staggered entrance; reduced motion uses a fade instead. |
+| `maxHeight` | `100` | Maximum elevation in the same grid units as cell size and gap. |
+| `heightDomain` | `[0, largest positive value]` | Fixed numeric domain for comparisons across charts. Out-of-range values clamp. |
+| `yaw`, `pitch`, `zoom` | `-35`, `38`, `1` | Camera orbit, elevation, and magnification. |
+| `onCameraChange` | none | Receives `{ yaw, pitch, zoom }` after camera interactions. |
+| `interactive` | `true` | Enables pointer dragging and keyboard camera control. |
+| `showControls` | `true` | Shows zoom and camera-reset buttons. |
+
+3D accepts the same data, labels, tooltips, click callbacks, and legend props.
+`encode`, `radius`, and `minScale` belong to the 2D component. Negative values
+keep their labels but render at the zero plane. The 3D component is intended
+for nonnegative activity and magnitude data.
+
+Drag to orbit the scene. Focus the chart to use the arrow keys, `+` / `-`, or
+`Home` to rotate, zoom, or reset it. Cells expose their values to assistive
+technology. Click handlers also respond to Enter and Space.
+
+### Patterns, themes, and static SVG
+
+The built-in patterns are small and repeatable. A row can be a number, a
+hexadecimal string, or a binary string. The most-significant bit is drawn on
+the left:
+
+```tsx
+<Heatmap3D
+  rows={1}
+  columns={3}
+  values={[[2, 8, 20]]}
+  theme="night"
+  material="pattern"
+  animation="grow"
+  patterns={{
+    top: [{ width: 4, bitmap: ["1000", "0100", "0010", "0001"] }],
+    side: [{ width: 2, bitmap: ["10", "01"] }],
+  }}
+/>
+```
+
+For an email, README image, or scheduled asset, use the same scene without React
+or a DOM:
+
+```ts
+import { renderHeatmap3DSvg } from "@thilakbhat/heatmap-ui";
+
+const svg = renderHeatmap3DSvg({
+  rows: 1,
+  columns: 3,
+  values: [[2, 8, 20]],
+  theme: "seasonal",
+  material: "pattern",
+  showLegend: true,
+});
+```
+
+`renderHeatmap3DSvg` uses the same height domain, geometry, face visibility,
+paint order, themes, and pattern definitions as `Heatmap3D`. It returns an
+accessible, non-interactive SVG snapshot.
+
+## Shapes
+
+| | |
+| --- | --- |
+| `rounded` `square` `circle` | The basic shapes. |
+| `diamond` | A 45° square. Reads denser over long ranges. |
+| `hexagon` | Offset rows, honeycomb. The standard form for hex-binned data. |
+| `plus` | Stays legible at sizes where circles turn to mush. |
+| `bar` | Height tracks the value; colour stays flat. |
+| `ring` | Stroke thickness tracks the value. Works on any ground. |
+
+## Encoding without colour
+
+Colour alone is not enough for roughly one reader in twelve.
+
+```tsx
+<Heatmap encode="both" ... />
+```
+
+With `"size"`, each cell scales within its slot, so intensity still reads in
+greyscale. `"both"` uses colour and size. `minScale` sets the smallest size for
+the weakest cell.
+
+### Values inside cells
+
+Use `cellContent` for short values, counts, or other compact content. It is
+separate from `cellLabel`, so a dense visual can still have a complete
+accessible description:
+
+```tsx
+<Heatmap
+  rows={7}
+  columns={20}
+  values={activity}
+  cellContent={(cell) => cell.known && cell.value > 0 ? cell.value : null}
+  cellLabel={(cell) => cell.known ? `${cell.value} events` : "No data"}
+/>
+```
+
+The content is decorative to assistive technology; use `cellLabel` for its
+meaning. This option belongs to the flat grid. The 3D component keeps values in
+labels and tooltips, so it stays an SVG renderer without an HTML overlay.
+
+## Calendar
+
+```tsx
+<CalendarHeatmap
+  values={[{ date: "2026-09-07", value: 12 }]}
+  to="2026-09-07"
+  weeks={20}
+  weekStart={1}
+  showMonthLabels
+  showWeekdayLabels
+  unitLabel="commits"
+  tooltip={(day) => `${day.date}: ${day.value}`}
+/>
+```
+
+`weeks` defaults to 53 when omitted.
+
+The calendar adapter handles date mapping, month labels, weekday labels, and a
+default accessible name for each day. It hides days after `to` instead of
+drawing them as missing, so a final partial column stays partial. Every
+`Heatmap` prop passes through.
+
+## Recipes
+
+Most heatmap variants are just different grid dimensions. Each example below
+uses `Heatmap`; the playground can generate the same code from its current
+settings.
+
+### Punchcard: hours down, weekdays across
+
+```tsx
+const hourLabels = Array.from({ length: 24 }, (_, i) => (i % 6 === 0 ? `${i}:00` : ""));
+const dayLabels = ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"]
+  .map((text, column) => ({ column, text }));
+
+<Heatmap
+  rows={24}
+  columns={7}
+  values={commits}                    // number[24][7]
+  rowLabels={hourLabels}
+  columnLabels={dayLabels}
+  ariaLabel="Commits by hour and weekday"
+  tooltip={(cell) => `${cell.row}:00 — ${cell.value}`}
+/>
+```
+
+### Cohort retention: a ragged grid
+
+A cohort that signed up last week has no week-10 number until ten weeks pass.
+That slot does not exist, so `isSlotHidden` removes it from the grid. This
+differs from `known: false`, which represents an existing slot that was not
+measured.
+
+```tsx
+<Heatmap
+  rows={cohorts.length}
+  columns={12}
+  values={retention}                  // { row, column, value }[]
+  isSlotHidden={(row, column) => column >= cohorts.length - row}
+  rowLabels={cohorts}                 // ["Jul 6", "Jul 13", …]
+  columnLabels={Array.from({ length: 12 }, (_, column) => ({ column, text: `W${column}` }))}
+  ariaLabel="Retention by signup cohort"
+  tooltip={(cell) => `Week ${cell.column} — ${cell.value}% retained`}
+/>
+```
+
+### Uptime: wide and short, with days that were never collected
+
+This is the other kind of gap: the slots exist, but nobody was watching them.
+
+```tsx
+<Heatmap
+  rows={services.length}
+  columns={30}
+  values={uptime}                     // { row, column, value, known }[]
+  rowLabels={services}                // ["api", "web", …]
+  columnLabels={dayLabels}
+  ariaLabel="Service uptime by day"
+  tooltip={(cell) =>
+    cell.known ? `${cell.value}% up` : "not monitored"}
+/>
+```
+
+### Co-occurrence: symmetric, diagonal removed
+
+The diagonal compares each label with itself, so it adds noise at full strength.
+Hide it instead of letting it dominate the scale.
+
+```tsx
+<Heatmap
+  rows={topics.length}
+  columns={topics.length}
+  values={overlap}                    // symmetric: value(i, j) === value(j, i)
+  isSlotHidden={(row, column) => row === column}
+  rowLabels={topics}
+  columnLabels={topics.map((text, column) => ({ column, text }))}
+  ariaLabel="Label co-occurrence"
+/>
+```
+
+### A note on label density
+
+`Heatmap` positions the labels you provide, but it cannot measure their width.
+A label such as `"Wednesday"` can run into a neighbouring 16px column. Decide
+how many labels fit in the calling code. Use shorter labels or thin them:
+
+```tsx
+// Keep only as many labels as the column stride can hold.
+function thinLabels(texts, stride) {
+  const widest = Math.max(...texts.map((t) => t.length)) * 6 + 8; // ~6px/char at 10px
+  const step = Math.max(1, Math.ceil(widest / stride));
+  return texts
+    .map((text, column) => ({ column, text }))
+    .filter((_, i) => i % step === 0);
+}
+
+columnLabels={thinLabels(dates, cellSize + gap)}
+```
+
+`CalendarHeatmap` already thins month labels when one would land too close to
+the previous label.
+
+## Accessibility
+
+- The grid uses a labelled `group`, not `role="img"`, so the cells inside it can
+  still receive focus.
+- Cells receive focus only when they carry information, such as a `cellLabel`,
+  `tooltip`, or `onCellClick`.
+- Tooltips open on focus as well as hover, after a 300ms delay, and are wired
+  with `aria-describedby`.
+- `encode` lets you carry intensity without relying on colour alone.
+- Hover and focus scaling is dropped under `prefers-reduced-motion`.
+
+## Styling
+
+The stylesheet handles structure. Props provide the colour, and the stylesheet
+defines four variables you can override:
+
+```css
+.heatmap {
+  --heatmap-tooltip-bg: …;
+  --heatmap-tooltip-text: …;
+  --heatmap-label: …;
+  --heatmap-cell-content-color: …;
+}
+```
+
+Tooltip colours follow `prefers-color-scheme`. Set
+`data-heatmap-theme="light" | "dark"` to pin them.
+
+## Playground
+
+**<https://tb962.github.io/heatmap-ui/>**. No install required.
+
+To run it from your working copy:
+
+```bash
+npm run build
+npx serve .
+```
+
+Open `examples/playground.html`. You can switch between 2D and 3D, choose Solid,
+LEGO, or Skyline cells, and orbit the scene. The graph choices include calendar,
+punchcard, cohort retention, co-occurrence, and uptime. Adjust a prop and the
+panel below the chart shows the exact code for the current view, including its
+imports.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+For contribution details, see [CONTRIBUTING.md](CONTRIBUTING.md). To report a
+vulnerability, see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT.

package/dist/calendar.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from "react";
+import type { Heatmap3DProps, HeatmapProps, ResolvedCell } from "./types.js";
+export type CalendarDay = {
+    /** ISO date, YYYY-MM-DD. */
+    date: string;
+    value: number;
+    /** false when the day is outside what the source could observe. */
+    known?: boolean;
+    meta?: unknown;
+};
+type CalendarOptions = {
+    values?: ReadonlyArray<CalendarDay>;
+    /** Last day shown. Defaults to today. */
+    to?: string | Date;
+    /** Columns to render. Defaults to 53. */
+    weeks?: number;
+    /** 0 = Sunday (default), 1 = Monday. */
+    weekStart?: 0 | 1;
+    showMonthLabels?: boolean;
+    showWeekdayLabels?: boolean;
+    /** Which weekday rows to label. Defaults to every other one. */
+    weekdayLabelRows?: readonly number[];
+    unitLabel?: string;
+    tooltip?: (day: CalendarCell) => ReactNode;
+    cellLabel?: (day: CalendarCell) => string;
+};
+type CalendarManagedProps = "rows" | "columns" | "values" | "rowLabels" | "columnLabels" | "tooltip" | "cellLabel";
+export type CalendarHeatmapProps = Omit<HeatmapProps, CalendarManagedProps> & CalendarOptions;
+/** A calendar whose values rise into 3D columns, bricks or buildings. */
+export type CalendarHeatmap3DProps = Omit<Heatmap3DProps, CalendarManagedProps> & CalendarOptions;
+/** A resolved cell with its calendar date attached. */
+export type CalendarCell = ResolvedCell & {
+    date: string;
+};
+/** Lays days onto a flat grid, with one column per week. */
+export declare function CalendarHeatmap(props: CalendarHeatmapProps): import("react").JSX.Element;
+/** Lays the same calendar onto a rotatable 3D grid, with height encoding value. */
+export declare function CalendarHeatmap3D(props: CalendarHeatmap3DProps): import("react").JSX.Element;
+export default CalendarHeatmap;
+//# sourceMappingURL=calendar.d.ts.map

package/dist/calendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../src/calendar.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAe,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS1F,MAAM,MAAM,WAAW,GAAG;IACxB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,MAAM,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACpC,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,SAAS,CAAC;IAC3C,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,MAAM,CAAC;CAC3C,CAAC;AAEF,KAAK,oBAAoB,GACrB,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,YAAY,EAAE,oBAAoB,CAAC,GAAG,eAAe,CAAC;AAE9F,yEAAyE;AACzE,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,cAAc,EAAE,oBAAoB,CAAC,GAAG,eAAe,CAAC;AAElG,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AA8I3D,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,+BAG1D;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,+BAG9D;AAED,eAAe,eAAe,CAAC"}

package/dist/calendar.js

@@ -0,0 +1,136 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { Heatmap } from "./heatmap.js";
+import { Heatmap3D } from "./heatmap3d.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MONTHS = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+function toUtcMidnight(value) {
+    const date = typeof value === "string" ? parseIsoDate(value) : value;
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+}
+function parseIsoDate(value) {
+    const [year, month, day] = value.split("-").map(Number);
+    return new Date(Date.UTC(year, (month ?? 1) - 1, day ?? 1));
+}
+function isoKey(date) {
+    return date.toISOString().slice(0, 10);
+}
+/**
+ * Lays days onto the grid: one column per week, one row per weekday. This is
+ * the only place in the package that knows what a date is.
+ */
+function useCalendarProps({ values = [], to, weeks = 53, weekStart = 0, showMonthLabels = true, showWeekdayLabels = false, weekdayLabelRows = [1, 3, 5], unitLabel = "", tooltip, cellLabel, ...heatmapProps }) {
+    const end = useMemo(() => toUtcMidnight(to ?? new Date()), [to]);
+    const { cells, columnLabels, dates, hidden } = useMemo(() => {
+        const byDate = new Map(values.map((day) => [day.date, day]));
+        // The grid ends on the week containing `end`, so the last column is
+        // partial whenever today is not the last day of the week.
+        const endWeekday = (end.getUTCDay() - weekStart + 7) % 7;
+        const lastColumnStart = new Date(end.getTime() - endWeekday * DAY_MS);
+        const firstColumnStart = new Date(lastColumnStart.getTime() - (weeks - 1) * 7 * DAY_MS);
+        const resolved = [];
+        const dateByKey = new Map();
+        const hiddenSlots = new Set();
+        const labels = [];
+        let previousMonth = -1;
+        for (let column = 0; column < weeks; column += 1) {
+            // Which month a column belongs to is a property of the calendar, not of
+            // the data, so the label is derived from the date before any value is
+            // looked up. Deriving it inside the cell loop lost the label whenever
+            // the caller had supplied nothing for that column's first day.
+            const columnMonth = new Date(firstColumnStart.getTime() + column * 7 * DAY_MS).getUTCMonth();
+            if (columnMonth !== previousMonth) {
+                labels.push({ column, text: MONTHS[columnMonth] });
+                previousMonth = columnMonth;
+            }
+            for (let row = 0; row < 7; row += 1) {
+                const date = new Date(firstColumnStart.getTime() + (column * 7 + row) * DAY_MS);
+                // Days after `end` are not "no data", they simply do not exist yet.
+                if (date.getTime() > end.getTime()) {
+                    hiddenSlots.add(row + ":" + column);
+                    continue;
+                }
+                const key = isoKey(date);
+                dateByKey.set(row + ":" + column, key);
+                const day = byDate.get(key);
+                if (!day)
+                    continue;
+                resolved.push({
+                    row,
+                    column,
+                    value: day.value,
+                    known: day.known !== false,
+                    meta: day.meta,
+                });
+            }
+        }
+        return { cells: resolved, columnLabels: labels, dates: dateByKey, hidden: hiddenSlots };
+    }, [values, end, weeks, weekStart]);
+    // A three-letter month is about 24px at the label's 10px font. When a month
+    // starts too few columns after the previous label there is no room for both,
+    // so the later one is dropped rather than drawn on top of its neighbour.
+    const monthLabels = useMemo(() => {
+        const stride = (heatmapProps.cellSize ?? 13) + (heatmapProps.gap ?? 3);
+        const minColumns = Math.ceil(30 / stride);
+        const kept = [];
+        let lastColumn = Number.NEGATIVE_INFINITY;
+        for (const label of columnLabels) {
+            if (label.column - lastColumn < minColumns)
+                continue;
+            kept.push(label);
+            lastColumn = label.column;
+        }
+        return kept;
+    }, [columnLabels, heatmapProps.cellSize, heatmapProps.gap]);
+    const withDate = (cell) => ({
+        ...cell,
+        date: dates.get(cell.row + ":" + cell.column) ?? "",
+    });
+    const rowLabels = showWeekdayLabels
+        ? Array.from({ length: 7 }, (_, row) => weekdayLabelRows.includes(row) ? WEEKDAYS[(row + weekStart) % 7] : "")
+        : undefined;
+    return {
+        rows: 7,
+        columns: weeks,
+        values: cells,
+        isSlotHidden: (row, column) => hidden.has(row + ":" + column),
+        rowLabels,
+        columnLabels: showMonthLabels ? monthLabels : undefined,
+        tooltip: tooltip ? (cell) => tooltip(withDate(cell)) : undefined,
+        cellLabel: (cell) => {
+            const resolved = withDate(cell);
+            if (cellLabel)
+                return cellLabel(resolved);
+            if (!resolved.date)
+                return "";
+            const readable = parseIsoDate(resolved.date).toLocaleDateString("en-US", {
+                weekday: "long",
+                day: "numeric",
+                month: "long",
+                year: "numeric",
+                timeZone: "UTC",
+            });
+            if (!resolved.known)
+                return readable + ". No data.";
+            return readable + ". " + resolved.value + (unitLabel ? " " + unitLabel : "");
+        },
+        ...heatmapProps,
+    };
+}
+/** Lays days onto a flat grid, with one column per week. */
+export function CalendarHeatmap(props) {
+    const heatmapProps = useCalendarProps(props);
+    return _jsx(Heatmap, { ...heatmapProps });
+}
+/** Lays the same calendar onto a rotatable 3D grid, with height encoding value. */
+export function CalendarHeatmap3D(props) {
+    const heatmapProps = useCalendarProps(props);
+    return _jsx(Heatmap3D, { ...heatmapProps });
+}
+export default CalendarHeatmap;
+//# sourceMappingURL=calendar.js.map

package/dist/calendar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.js","sourceRoot":"","sources":["../src/calendar.tsx"],"names":[],"mappings":"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"}