heatmap-builder 0.2.0 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf666db73abc3356f19fea3869f4a6bb4af21c28a2036f2926c811250636c904
-  data.tar.gz: 6ba3349f270af6ef2216d7501888187aa39e2c11d8b874d084e861cf3f41ef8b
+  metadata.gz: 6493e6ea0c3c5fd533269a55e6cb18c8df0a65ddad86aab5061c6d5cf57c5586
+  data.tar.gz: fd5ae27f32ec084c3414d8f26a7def6c45bedef66b7266423ddd9fc3ec3df458
 SHA512:
-  metadata.gz: 65f06b77aeeda0e45054bbfe402b9d344bf2996a7a5423ca17ab005f79a2aaced93a656eb830294d021b46c2c7ad3c01338553d7d8ece9259d7208ace6ece1b9
-  data.tar.gz: 5fdb4ea1d6c8ff1f7d4966cadd13f6cbeb06916754bdd1e68e553b58632cbc6d49a154f7629f8fc1bb127513dc848831ae87c6d26503f94c29510d8772ee0e08
+  metadata.gz: 1424b3fc448ef0d2a0afac402f87617fc981a179cc5fad4a6883585950f41a885b052680da36ec203bc071fab010c336b9c362b6c72ecbbc5680643f47d938ff
+  data.tar.gz: 8702e0d38c802162393f0185b6e485e504203a119115f4d92e43e72b583d32202bf61c6264b7e5df9ae3a6b77ac7526d92d2b21a253ac0893695ef0348109e7f

data/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.0', '3.1', '3.2', '3.3', '3.4']
+        ruby-version: ['3.3', '3.4', '4.0']
 
     steps:
     - uses: actions/checkout@v4
@@ -23,10 +23,7 @@ jobs:
         bundler-cache: true
 
     - name: Run tests
-      run: |
-        bundle exec ruby -Ilib:test test/heatmap_builder_test.rb
-        bundle exec ruby -Ilib:test test/calendar_heatmap_builder_test.rb
-        bundle exec ruby -Ilib:test test/linear_heatmap_builder_test.rb
+      run: bundle exec rake test
 
   lint:
     runs-on: ubuntu-latest

data/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-06-15
+
+### Fixed
+- Calendar month labels now always sit above the first full week of the month.
+  Previously, with `month_spacing: 0`, a label could land on the straddling
+  column shared by two months; the label position is now derived from each
+  week's `week_start`, so straddling weeks defer the label to the next full week.
+- A month is no longer labeled when its only visible week is incomplete (a
+  leading or trailing sliver at the edge of the data range). Previously such a
+  label could overlap the next month's label when the partial month occupied a
+  single column. Labels are now placed only on a fully visible week.
+
+## [0.4.2] - 2026-06-15
+
+### Added
+- New `border_lightness_factor` option controls how the cell border color is derived
+  from each cell's color by scaling its OKLCH lightness. Setting it to `1` makes
+  the border match the cell color, in which case the (now invisible) border is
+  omitted from the SVG entirely. Defaults to `0.9`, preserving previous output.
+
+## [0.4.1] - 2026-06-13
+
+### Changed
+- Default value-to-score conversion now reserves score `0` for empty cells
+  (zero or missing values) and maps every non-zero value into the `1..max_score`
+  range, so the smallest amount of activity is always visually distinct from an
+  empty day. Regenerated `examples/*.svg` to reflect the new bucketing.
+- Auto-calculated `value_min` now anchors on the smallest non-zero value instead
+  of zero. Because zero is the reserved empty bucket, this keeps the lightest
+  activity color reachable rather than stranding it on values that never occur.
+
+### Fixed
+- Example calendar heatmaps misrendered high-activity days. The generator passed
+  raw values straight through as `scores:`, so any value beyond the palette's
+  color count wrapped around via modulo (`score_to_color`) and the busiest days
+  could render as nearly empty cells. The examples now feed values through the
+  bucketing conversion, so cell intensity increases monotonically with the
+  underlying value.
+
+## [0.4.0] - 2026-06-12
+
+### Added
+- Tooltip support for calendar cells via the `tooltip:` option. Accepts a callable
+  invoked per active cell with `date:`, `score:`, and `value:` keyword arguments;
+  the return value becomes the tooltip text.
+- Native SVG `<title>` element is always emitted as a zero-JS browser fallback.
+- `tooltip_attribute:` option (default `"data-tooltip"`) controls which `data-*`
+  attribute is written on the cell's `<g>` wrapper for JS tooltip library pickup.
+  Set to `nil` to suppress the data attribute and use only the native fallback.
+
+## [0.3.1] - 2026-06-11
+
+### Changed
+- Relaxed `rake` and `minitest` development dependency constraints from `~>` to `>=` to allow future major versions
+
+## [0.3.0] - 2026-06-11
+
+### Changed
+- Dropped support for Ruby 3.0, 3.1, and 3.2 (all EOL); minimum required version is now 3.3
+- Updated all dependencies to latest stable versions
+- Updated Bundler constraint from `~> 2.0` to `>= 2.0`; locked to Bundler 4.0.14
+- CI matrix updated to Ruby 3.3, 3.4, and 4.0
+
 ## [0.2.0] - 2025-10-02
 
 ### Added
@@ -32,7 +95,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Automatic corner radius clamping to valid range
 
 ### Deprecated
-- `HeatmapBuilder.generate(scores, options)` - use `HeatmapBuilder.build_linear(scores: scores, **options)` instead
 - `HeatmapBuilder.generate_calendar(scores, options)` - use `HeatmapBuilder.build_calendar(scores: scores, **options)` instead
 - Old API still works with deprecation warnings for backward compatibility
 
@@ -41,13 +103,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Initial release with core heatmap visualization capabilities.
 
 ### Added
-- Linear heatmap generation with `HeatmapBuilder.generate()`
 - Calendar heatmap generation with `HeatmapBuilder.generate_calendar()`
 - GitHub-style color schemes and styling
 - Customizable cell size, spacing, colors, and fonts
 - Support for custom start of week (Monday/Sunday)
 - SVG output format for perfect scaling
 
-[Unreleased]: https://github.com/dreikanter/heatmap-builder/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/dreikanter/heatmap-builder/compare/v0.4.3...HEAD
+[0.4.3]: https://github.com/dreikanter/heatmap-builder/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/dreikanter/heatmap-builder/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/dreikanter/heatmap-builder/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/dreikanter/heatmap-builder/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/dreikanter/heatmap-builder/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/dreikanter/heatmap-builder/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/dreikanter/heatmap-builder/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/dreikanter/heatmap-builder/releases/tag/v0.1.0

data/Gemfile.lock

@@ -1,44 +1,47 @@
 PATH
   remote: .
   specs:
-    heatmap-builder (0.2.0)
+    heatmap-builder (0.4.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
     docile (1.4.1)
-    json (2.14.1)
+    drb (2.2.3)
+    json (2.19.9)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    minitest (5.25.5)
-    parallel (1.27.0)
-    parser (3.3.9.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    parallel (2.1.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
-    prism (1.5.1)
+    prism (1.9.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
-    regexp_parser (2.11.3)
-    rubocop (1.80.2)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rubocop (1.87.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.46.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
@@ -46,33 +49,33 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    standard (1.51.1)
+    standard (1.55.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.80.2)
+      rubocop (~> 1.87.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
+      rubocop-performance (~> 1.26.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   arm64-darwin-24
   ruby
 
 DEPENDENCIES
-  bundler (~> 2.0)
+  bundler (>= 2.0)
   heatmap-builder!
-  minitest (~> 5.0)
-  rake (~> 13.0)
+  minitest (>= 5.0)
+  rake (>= 13.0)
   simplecov (~> 0.22)
   standard (~> 1.0)
 
 BUNDLED WITH
-   2.5.22
+  4.0.9

data/README.md

@@ -1,13 +1,12 @@
 # HeatmapBuilder
 
-A Ruby gem that generates embeddable SVG heatmap visualizations with GitHub-style calendar layouts and linear progress indicators. Perfect for Rails applications and any project that needs to display activity data in a visual format.
+A Ruby gem that generates embeddable SVG heatmap visualizations with GitHub-style calendar layouts. Perfect for Rails applications and any project that needs to display activity data in a visual format.
 
 ![GitHub-style Calendar](examples/calendar_github_style.svg)
 
 ## Features
 
 - GitHub-style calendar layouts for date-based data.
-- Linear heatmaps.
 - Vector-based output (SVG) for crisp rendering at any resolution.
 - Optional numeric values displayed in each cell.
 - **Use pre-calculated scores or raw numeric values** - automatic mapping to color scales.
@@ -16,6 +15,7 @@ A Ruby gem that generates embeddable SVG heatmap visualizations with GitHub-styl
 - Rounded corners (and circular cells, if you're into that kind of thing).
 - Dynamic palette generation from two colors or manually-specified colors.
 - OKLCH color interpolation for clean color transitions and perceptual uniformity.
+- Tooltip support with native browser fallback and JS library integration hooks.
 - **Zero dependencies.**
 
 ## Installation
@@ -36,29 +36,14 @@ Or install it yourself as:
 
 ## Usage
 
-### Linear Heatmaps
-
-```ruby
-require 'heatmap-builder'
-
-# Generate SVG for daily scores
-scores = [0, 1, 2, 3, 4, 5, 2, 1]
-svg = HeatmapBuilder.build_linear(scores: scores)
-
-# In a Rails view
-<%= raw HeatmapBuilder.build_linear(scores: @daily_scores) %>
-```
-
-![Weekly Progress](examples/weekly_progress.svg)
-
 ### Calendar Heatmaps
 
 ```ruby
 # GitHub-style calendar heatmap
 scores_by_date = {
-  '2024-01-01' => 2,
-  '2024-01-02' => 4,
-  '2024-01-03' => 1,
+  '2026-01-01' => 2,
+  '2026-01-02' => 4,
+  '2026-01-03' => 1,
   # ... more dates
 }
 
@@ -67,34 +52,6 @@ svg = HeatmapBuilder.build_calendar(scores: scores_by_date)
 
 ![GitHub-style Calendar](examples/calendar_github_style.svg)
 
-### Linear Heatmap Options
-
-You must provide either `scores:` or `values:` (but not both). All other options are optional keyword arguments with sensible defaults.
-
-**Data options:**
-
-- `scores` - Array of pre-calculated scores (integers from 0 to number of colors minus 1). Required if `values` is not provided.
-- `values` - Array of arbitrary numeric values to be automatically mapped to scores. Required if `scores` is not provided. See [Using Raw Values Instead of Scores](#using-raw-values-instead-of-scores).
-
-**Value-to-score conversion options** (only used with `values:`):
-
-- `value_min` - Minimum boundary for value-to-score mapping. Defaults to the minimum value in your data.
-- `value_max` - Maximum boundary for value-to-score mapping. Defaults to the maximum value in your data.
-- `value_to_score` - Custom callable for value-to-score conversion. Receives `value:`, `index:`, `min:`, `max:`, `max_score:` parameters and must return an integer between 0 and `max_score`. See [Custom Scoring Logic](#custom-scoring-logic) for details.
-
-**Appearance options:**
-
-- `cell_size` - Size of each square in pixels. Defaults to 10.
-- `cell_spacing` - Space between squares in pixels. Defaults to 1.
-- `font_size` - Font size for score text in pixels. Defaults to 8.
-- `border_width` - Border width around each cell in pixels. Defaults to 1.
-- `corner_radius` - Corner radius for rounded cells. Must be between 0 (square corners) and `floor(cell_size/2)` (circular cells). Values outside this range are automatically clamped. Defaults to 0.
-- `text_color` - Color of score text as a hex string. Defaults to `"#000000"` (black).
-
-**Color options:**
-
-- `colors` - Color palette for the heatmap. Can be a predefined palette constant (e.g., `HeatmapBuilder::GITHUB_GREEN`), an array of hex color strings (e.g., `%w[#ebedf0 #9be9a8 #40c463]`), or a hash for OKLCH interpolation (e.g., `{ from: "#ebedf0", to: "#216e39", steps: 5 }`). Defaults to `HeatmapBuilder::GITHUB_GREEN`. See [Predefined Color Palettes](#predefined-color-palettes) and [Dynamic Palettes Generation](#dynamic-palettes-generation).
-
 ### Calendar Heatmap Options
 
 You must provide either `scores:` or `values:` (but not both). All other options are optional keyword arguments with sensible defaults.
@@ -116,21 +73,26 @@ You must provide either `scores:` or `values:` (but not both). All other options
 - `cell_spacing` - Space between squares in pixels. Defaults to 1.
 - `font_size` - Font size for labels in pixels. Defaults to 8.
 - `border_width` - Border width around each cell in pixels. Defaults to 1.
+- `border_lightness_factor` - Controls the border color, derived from each cell's color by scaling its lightness (in OKLCH) by this factor. Values below 1 produce a darker border; a value of 1 makes the border match the cell color, in which case the border is omitted entirely. Must be positive. Defaults to 0.9.
 - `corner_radius` - Corner radius for rounded cells. Must be between 0 (square corners) and `floor(cell_size/2)` (circular cells). Values outside this range are automatically clamped. Defaults to 0.
-- `text_color` - Color of label text as a hex string. Defaults to `"#000000"` (black).
 
 **Color options:**
 
-- `colors` - Color palette for the heatmap. Can be a predefined palette constant (e.g., `HeatmapBuilder::GITHUB_GREEN`), an array of hex color strings (e.g., `%w[#ebedf0 #9be9a8 #40c463]`), or a hash for OKLCH interpolation (e.g., `{ from: "#ebedf0", to: "#216e39", steps: 5 }`). Defaults to `HeatmapBuilder::GITHUB_GREEN`. See [Predefined Color Palettes](#predefined-color-palettes) and [Dynamic Palettes Generation](#dynamic-palettes-generation).
+- `colors` - Color palette for the heatmap. Can be a predefined palette constant (e.g., `HeatmapBuilder::Calendar::GITHUB_GREEN`), an array of hex color strings (e.g., `%w[#ebedf0 #9be9a8 #40c463]`), or a hash for OKLCH interpolation (e.g., `{ from: "#ebedf0", to: "#216e39", steps: 5 }`). Defaults to `HeatmapBuilder::Calendar::GITHUB_GREEN`. See [Predefined Color Palettes](#predefined-color-palettes) and [Dynamic Palettes Generation](#dynamic-palettes-generation).
 
 **Calendar-specific options:**
 
 - `start_of_week` - First day of the week. One of `:sunday`, `:monday`, `:tuesday`, `:wednesday`, `:thursday`, `:friday`, `:saturday`. Defaults to `:monday`.
-- `month_spacing` - Extra horizontal space between months in pixels. Defaults to 5.
+- `month_spacing` - Extra horizontal space between months in pixels. Defaults to 0.
 - `show_month_labels` - Show month names at the top of the calendar. Defaults to `true`.
 - `show_day_labels` - Show day abbreviations on the left side of the calendar. Defaults to `true`.
 - `show_outside_cells` - Show cells outside the date range with inactive styling. Defaults to `false`.
 
+**Tooltip options:**
+
+- `tooltip` - Callable invoked per active cell with `date:`, `score:`, and `value:` keyword arguments. Return value is used as the tooltip text. Emits a native SVG `<title>` element (browser fallback) and a data attribute (JS library hook). Defaults to `nil` (no tooltip markup).
+- `tooltip_attribute` - Name of the `data-*` attribute written on each cell's `<g>` wrapper for JS tooltip library pickup. Defaults to `"data-tooltip"`. Set to `nil` to suppress the data attribute and use only the native `<title>` fallback. See [Tooltips](#tooltips).
+
 **Internationalization options:**
 
 - `day_labels` - Array of day abbreviations starting from Sunday (7 elements). Defaults to `%w[S M T W T F S]`. See [I18n](#i18n).
@@ -143,19 +105,11 @@ A **score** is an integer (0 to N-1) that maps directly to a color in your palet
 Instead of pre-calculating scores, you can provide raw numeric values (like 45.2, 78, 1000) and let the builder automatically map them to scores using linear distribution:
 
 ```ruby
-# Linear heatmap with automatic score calculation
-values = [10, 25, 50, 75, 100]
-svg = HeatmapBuilder.build_linear(
-  values: values,
-  value_min: 0,    # Optional: explicitly set minimum (defaults to actual min)
-  value_max: 100   # Optional: explicitly set maximum (defaults to actual max)
-)
-
 # Calendar heatmap with automatic score calculation
 values_by_date = {
-  Date.new(2024, 1, 1) => 45.2,
-  Date.new(2024, 1, 2) => 78.5,
-  Date.new(2024, 1, 3) => 12.0
+  Date.new(2026, 1, 1) => 45.2,
+  Date.new(2026, 1, 2) => 78.5,
+  Date.new(2026, 1, 3) => 12.0
 }
 
 svg = HeatmapBuilder.build_calendar(
@@ -177,30 +131,17 @@ By default, values are mapped to scores using linear distribution. You can provi
 
 The callable receives these parameters:
 - `value:` - The current value being converted
-- `index:` or `date:` - The position in the data (linear heatmaps use `index:`, calendar heatmaps use `date:`)
+- `date:` - The date for the data point
 - `min:` - The minimum boundary value
 - `max:` - The maximum boundary value
 - `max_score:` - The maximum valid score (color palette length minus 1)
 
 The function must return an integer between 0 and `max_score`.
 
-Custom scoring logic - linear distribution example:
+Custom scoring logic - logarithmic scale for data with wide range (e.g., 1 to 10000):
 
 ```ruby
-linear_formula = ->(value:, index:, min:, max:, max_score:) {
-  ((value - min) / (max - min) * max_score).round
-}
-
-svg = HeatmapBuilder.build_linear(
-  values: [10, 20, 30],
-  value_to_score: linear_formula
-)
-```
-
-Logarithmic scale for data with wide range (e.g., 1 to 10000):
-
-```ruby
-logarithmic_formula = ->(value:, index:, min:, max:, max_score:) {
+logarithmic_formula = ->(value:, date:, min:, max:, max_score:) {
   return 0 if value <= 0 || min <= 0
 
   log_value = Math.log10(value)
@@ -210,8 +151,8 @@ logarithmic_formula = ->(value:, index:, min:, max:, max_score:) {
   ((log_value - log_min) / (log_max - log_min) * max_score).round.clamp(0, max_score)
 }
 
-svg = HeatmapBuilder.build_linear(
-  values: [1, 10, 100, 1000, 10000],
+svg = HeatmapBuilder.build_calendar(
+  values: values_by_date,
   value_to_score: logarithmic_formula
 )
 ```
@@ -221,13 +162,7 @@ svg = HeatmapBuilder.build_linear(
 #### GitHub Green (Default)
 
 ```ruby
-HeatmapBuilder.build_linear(scores: scores, colors: HeatmapBuilder::GITHUB_GREEN)
-```
-
-![GitHub Green Linear](examples/linear_github_green.svg)
-
-```ruby
-HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::GITHUB_GREEN)
+HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::Calendar::GITHUB_GREEN)
 ```
 
 ![Default Calendar](examples/calendar_default.svg)
@@ -235,13 +170,7 @@ HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::GIT
 #### Blue Ocean
 
 ```ruby
-HeatmapBuilder.build_linear(scores: scores, colors: HeatmapBuilder::BLUE_OCEAN)
-```
-
-![Blue Ocean Linear](examples/linear_blue_ocean.svg)
-
-```ruby
-HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::BLUE_OCEAN)
+HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::Calendar::BLUE_OCEAN)
 ```
 
 ![Blue Ocean Calendar](examples/calendar_blue_ocean.svg)
@@ -249,13 +178,7 @@ HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::BLU
 #### Warm Sunset
 
 ```ruby
-HeatmapBuilder.build_linear(scores: scores, colors: HeatmapBuilder::WARM_SUNSET)
-```
-
-![Warm Sunset Linear](examples/linear_warm_sunset.svg)
-
-```ruby
-HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::WARM_SUNSET)
+HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::Calendar::WARM_SUNSET)
 ```
 
 ![Warm Sunset Calendar](examples/calendar_warm_sunset.svg)
@@ -263,13 +186,7 @@ HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::WAR
 #### Purple Vibes
 
 ```ruby
-HeatmapBuilder.build_linear(scores: scores, colors: HeatmapBuilder::PURPLE_VIBES)
-```
-
-![Purple Vibes Linear](examples/linear_purple_vibes.svg)
-
-```ruby
-HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::PURPLE_VIBES)
+HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::Calendar::PURPLE_VIBES)
 ```
 
 ![Purple Vibes Calendar](examples/calendar_purple_vibes.svg)
@@ -277,13 +194,7 @@ HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::PUR
 #### Red to Green
 
 ```ruby
-HeatmapBuilder.build_linear(scores: scores, colors: HeatmapBuilder::RED_TO_GREEN)
-```
-
-![Red to Green Linear](examples/linear_red_to_green.svg)
-
-```ruby
-HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::RED_TO_GREEN)
+HeatmapBuilder.build_calendar(scores: calendar_data, colors: HeatmapBuilder::Calendar::RED_TO_GREEN)
 ```
 
 ![Red to Green Calendar](examples/calendar_red_to_green.svg)
@@ -300,44 +211,46 @@ neon_gradient = {
   steps: 5
 }
 
-svg = HeatmapBuilder.build_linear(scores: scores, colors: neon_gradient)
+svg = HeatmapBuilder.build_calendar(scores: calendar_data, colors: neon_gradient)
 ```
 
-![Neon Gradient Linear](examples/linear_neon_gradient.svg)
-
 The OKLCH color space ensures perceptually uniform color transitions, making gradients appear smooth and natural to the human eye.
 
-### Rounded Corners
+### Cell Borders
 
-Both linear and calendar heatmaps support rounded corners using the `corner_radius` option.
+Each cell has a border whose color is derived from the cell's own color. The `border_width` option sets its thickness, and `border_lightness_factor` controls its shade: the cell color's OKLCH lightness is multiplied by this factor, so values below `1` produce a darker border (the default `0.9` is a subtle darkening).
 
-A typical value is around 2 pixels for a subtle rounded effect:
+Setting `border_lightness_factor` to `1` keeps the border color identical to the cell color. In that case the border is invisible, so it is omitted from the SVG entirely.
 
 ```ruby
-# Linear heatmap with rounded corners
-HeatmapBuilder.build_linear(
-  scores: scores,
-  corner_radius: 2,
-  cell_size: 18
+HeatmapBuilder.build_calendar(
+  scores: calendar_data,
+  border_width: 1,
+  border_lightness_factor: 0.7
 )
 ```
 
-![Linear Rounded Corners](examples/linear_rounded_corners.svg)
+![Calendar with Cell Borders](examples/calendar_cell_borders.svg)
 
-The `corner_radius` value must be between 0 (square corners) and `floor(cell_size/2)`. Values outside this range are automatically clamped to the valid range (negative values become 0, values exceeding the maximum become `floor(cell_size/2)`). Maximum radius values render circular cells:
+With `border_lightness_factor` set to `1`, the border is omitted entirely, leaving cells edge to edge:
 
 ```ruby
-# Linear heatmap with max radius rounded corners - circular cells
-HeatmapBuilder.build_linear(
-  scores: scores,
-  corner_radius: 9,
-  cell_size: 18
+HeatmapBuilder.build_calendar(
+  scores: calendar_data,
+  border_width: 1,
+  border_lightness_factor: 1
 )
 ```
 
-![Linear Rounded Corners](examples/linear_rounded_corners_max_radius.svg)
+![Calendar with No Cell Borders](examples/calendar_no_borders.svg)
+
+### Rounded Corners
 
-Calendar heatmap examples:
+Calendar heatmaps support rounded corners using the `corner_radius` option.
+
+The `corner_radius` value must be between 0 (square corners) and `floor(cell_size/2)`. Values outside this range are automatically clamped to the valid range (negative values become 0, values exceeding the maximum become `floor(cell_size/2)`).
+
+A typical value is around 2 pixels for a subtle rounded effect:
 
 ```ruby
 # Calendar heatmap with rounded corners
@@ -350,6 +263,8 @@ HeatmapBuilder.build_calendar(
 
 ![Calendar Rounded Corners](examples/calendar_rounded_corners.svg)
 
+Maximum radius values render circular cells:
+
 ```ruby
 # Calendar heatmap with max radius rounded corners - circular cells
 HeatmapBuilder.build_calendar(
@@ -361,6 +276,61 @@ HeatmapBuilder.build_calendar(
 
 ![Calendar Rounded Corners](examples/calendar_rounded_corners_max_radius.svg)
 
+### Month Spacing
+
+Add visual separation between months using the `month_spacing` option. This adds horizontal gaps at month boundaries, making it easier to distinguish individual months:
+
+```ruby
+HeatmapBuilder.build_calendar(
+  scores: calendar_data,
+  cell_size: 14,
+  month_spacing: 10,
+  corner_radius: 3
+)
+```
+
+![Calendar with Month Spacing](examples/calendar_month_spacing_rounded.svg)
+
+### Tooltips
+
+The `tooltip:` option accepts a callable that is invoked once per active cell. It receives `date:`, `score:`, and `value:` keyword arguments and should return the tooltip text string. `value:` is the original input value when `values:` mode is used, and `nil` when `scores:` mode is used.
+
+```ruby
+HeatmapBuilder.build_calendar(
+  scores: calendar_data,
+  tooltip: ->(date:, score:, value: nil) { "#{date.strftime('%b %-d')}: #{score} contributions" }
+)
+```
+
+When `tooltip:` is set, each active cell is wrapped in an SVG `<g>` element containing a `<title>` child. The `<title>` element is the standard SVG mechanism for native browser tooltips — it works out of the box in any browser that renders inline SVG, with no JavaScript required.
+
+```xml
+<g data-tooltip="Jan 15: 4 contributions">
+  <title>Jan 15: 4 contributions</title>
+  <rect fill="#40c463" .../>
+</g>
+```
+
+The `tooltip_attribute:` option (default: `"data-tooltip"`) controls which `data-*` attribute is emitted on the `<g>` wrapper. This attribute is the hook for any JS tooltip library:
+
+```js
+// Tippy.js — one line of initialization
+tippy('[data-tooltip]', { content: el => el.dataset.tooltip })
+```
+
+Set `tooltip_attribute: nil` to suppress the data attribute and rely solely on the native `<title>` fallback. Use any other attribute name to match your tooltip library's expected selector:
+
+```ruby
+# Matches data-tippy-content used by some Tippy.js configurations
+HeatmapBuilder.build_calendar(
+  scores: calendar_data,
+  tooltip: ->(date:, score:, value: nil) { "#{date}: #{score}" },
+  tooltip_attribute: "data-tippy-content"
+)
+```
+
+Outside cells rendered via `show_outside_cells: true` never receive tooltip markup.
+
 ### I18n
 
 Calendar heatmaps support internationalization by customizing the `day_labels` and `month_labels` options: