From c1681bc7275c5266fd370b94d5cd4d97f78eeaaf Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Fri, 24 Oct 2025 09:28:16 -0400
Subject: [PATCH 1/5] Add Month component (WIP)

---
 .changeset/plain-rings-itch.md                |   5 +
 .../src/lib/components/Month.svelte           | 321 ++++++++++++++++
 .../layerchart/src/lib/components/index.ts    |   2 +
 .../layerchart/src/routes/_NavMenu.svelte     |   1 +
 .../routes/docs/components/Month/+page.svelte | 346 ++++++++++++++++++
 .../src/routes/docs/components/Month/+page.ts |  14 +
 6 files changed, 689 insertions(+)
 create mode 100644 .changeset/plain-rings-itch.md
 create mode 100644 packages/layerchart/src/lib/components/Month.svelte
 create mode 100644 packages/layerchart/src/routes/docs/components/Month/+page.svelte
 create mode 100644 packages/layerchart/src/routes/docs/components/Month/+page.ts

diff --git a/.changeset/plain-rings-itch.md b/.changeset/plain-rings-itch.md
new file mode 100644
index 000000000..df28d97fd
--- /dev/null
+++ b/.changeset/plain-rings-itch.md
@@ -0,0 +1,5 @@
+---
+'layerchart': patch
+---
+
+feat: Add Month component
diff --git a/packages/layerchart/src/lib/components/Month.svelte b/packages/layerchart/src/lib/components/Month.svelte
new file mode 100644
index 000000000..dc85e7eda
--- /dev/null
+++ b/packages/layerchart/src/lib/components/Month.svelte
@@ -0,0 +1,321 @@
+<script lang="ts" module>
+  export type MonthCell = {
+    x: number;
+    y: number;
+    color: any;
+    data: any;
+    date: Date;
+  };
+
+  export type MonthPropsWithoutHTML = {
+    /**
+     * The start year to display.
+     *
+     * @default current year
+     */
+    startYear?: number;
+
+    /**
+     * The end year to display (inclusive).
+     *
+     * @default current year
+     */
+    endYear?: number;
+
+    /**
+     * Size of the cell in the calendar.
+     *
+     * @default 25
+     */
+    cellSize?: number;
+
+    /**
+     * Number of months to display per row. If undefined, automatically calculated based on available width.
+     */
+    monthsPerRow?: number;
+
+    /**
+     * Padding multiplier between months (relative to cellSize).
+     *
+     * @default 1.2
+     */
+    monthPadding?: number;
+
+    /**
+     * Vertical spacing multiplier between month rows (in number of cell heights).
+     *
+     * @default 8
+     */
+    rowSpacing?: number;
+
+    /**
+     * Whether to show the day number in each cell.
+     *
+     * @default true
+     */
+    showDayNumber?: boolean;
+
+    /**
+     * Whether to show month labels.
+     *
+     * @default true
+     */
+    showMonthLabel?: boolean;
+
+    /**
+     * Whether to show year labels.
+     *
+     * @default true
+     */
+    showYearLabel?: boolean;
+
+    /**
+     * Props to pass to the `<text>` element for month labels.
+     */
+    monthLabelProps?: Partial<ComponentProps<typeof Text>>;
+
+    /**
+     * Props to pass to the `<text>` element for year labels.
+     */
+    yearLabelProps?: Partial<ComponentProps<typeof Text>>;
+
+    /**
+     * Props to pass to the `<text>` element for day numbers.
+     */
+    dayNumberProps?: Partial<ComponentProps<typeof Text>>;
+
+    /**
+     * Tooltip context to setup mouse events to show tooltip for related data
+     */
+    tooltipContext?: TooltipContextValue;
+
+    children?: Snippet<[{ cells: MonthCell[]; cellSize: number }]>;
+  } & Omit<
+    RectPropsWithoutHTML,
+    'children' | 'x' | 'y' | 'width' | 'height' | 'fill' | 'onpointermove' | 'onpointerleave'
+  >;
+
+  export type MonthProps = MonthPropsWithoutHTML &
+    Without<SVGAttributes<SVGRectElement>, MonthPropsWithoutHTML>;
+</script>
+
+<script lang="ts">
+  import { type ComponentProps, type Snippet } from 'svelte';
+  import { timeDays, timeMonths, timeWeek } from 'd3-time';
+  import { index } from 'd3-array';
+  import { format } from '@layerstack/utils';
+
+  import Rect, { type RectPropsWithoutHTML } from './Rect.svelte';
+  import type { TooltipContextValue } from './tooltip/TooltipContext.svelte';
+  import Group from './Group.svelte';
+  import Text from './Text.svelte';
+  import { chartDataArray } from '../utils/common.js';
+  import { getChartContext } from './Chart.svelte';
+  import type { SVGAttributes } from 'svelte/elements';
+  import type { Without } from '$lib/utils/types.js';
+  import { extractLayerProps } from '$lib/utils/attributes.js';
+
+  const DAYS_PER_WEEK = 7;
+
+  let {
+    startYear = new Date().getFullYear(),
+    endYear = new Date().getFullYear(),
+    cellSize = 25,
+    monthPadding = 1.2,
+    rowSpacing = 8,
+    showDayNumber = true,
+    showMonthLabel = true,
+    showYearLabel = true,
+    monthLabelProps = {},
+    yearLabelProps = {},
+    dayNumberProps = {},
+    tooltipContext: tooltip,
+    children,
+    ...restProps
+  }: MonthPropsWithoutHTML = $props();
+
+  const ctx = getChartContext();
+
+  // Calculate monthsPerRow based on the actual space taken by each month
+  // Each month (except the last in a row) takes: (monthPadding * cellSize * DAYS_PER_WEEK)
+  // The calculation accounts for n-1 padded months plus one unpadded month
+  // Formula: (n-1) * monthPadding * width + width = totalWidth
+  // Solving for n: n = (totalWidth + (monthPadding - 1) * width) / (monthPadding * width)
+  const monthsPerRow = $derived(
+    Math.floor(
+      (ctx.width + (monthPadding - 1) * cellSize * DAYS_PER_WEEK) /
+        (monthPadding * cellSize * DAYS_PER_WEEK)
+    )
+  );
+
+  // Generate data indexed by date (using date object as key)
+  const dataByDate = $derived(
+    ctx.data && ctx.config.x ? index(chartDataArray(ctx.data), (d) => ctx.x(d)) : new Map()
+  );
+
+  // Generate cells for all years
+  const allCells = $derived.by(() => {
+    const cells: MonthCell[] = [];
+
+    for (let year = startYear; year <= endYear; year++) {
+      const firstDayOfYear = new Date(year, 0, 1);
+      const lastDayOfYear = new Date(year + 1, 0, 1);
+      const yearDays = timeDays(firstDayOfYear, lastDayOfYear);
+
+      yearDays.forEach((day) => {
+        const firstDayOfMonth = new Date(day.getFullYear(), day.getMonth(), 1);
+        const cellData = dataByDate.get(day) ?? { date: day };
+
+        const monthIndex = day.getMonth();
+        const monthCol = monthIndex % monthsPerRow;
+        const monthRow = Math.floor(monthIndex / monthsPerRow);
+
+        const monthPaddingOffset = monthPadding * cellSize * DAYS_PER_WEEK * monthCol;
+        const weekDiff = timeWeek.count(firstDayOfMonth, day);
+        const rowLevel = monthRow + 1;
+
+        cells.push({
+          x: day.getDay() * cellSize + monthPaddingOffset,
+          y: weekDiff * cellSize + rowLevel * cellSize * rowSpacing - cellSize / 2,
+          color: ctx.config.c ? ctx.cGet(cellData) : 'transparent',
+          data: cellData,
+          date: day,
+        });
+      });
+    }
+
+    return cells;
+  });
+
+  // Generate month labels
+  const monthLabels = $derived.by(() => {
+    const labels: Array<{ x: number; y: number; text: string; year: number }> = [];
+
+    for (let year = startYear; year <= endYear; year++) {
+      const firstDayOfYear = new Date(year, 0, 1);
+      const lastDayOfYear = new Date(year + 1, 0, 1);
+      const yearMonths = timeMonths(firstDayOfYear, lastDayOfYear);
+
+      yearMonths.forEach((firstDayOfMonth) => {
+        const monthIndex = firstDayOfMonth.getMonth();
+        const monthCol = monthIndex % monthsPerRow;
+        const monthRow = Math.floor(monthIndex / monthsPerRow);
+
+        const monthPaddingOffset = monthPadding * cellSize * DAYS_PER_WEEK * monthCol;
+        const rowLevel = monthRow + 1;
+
+        labels.push({
+          x: monthPaddingOffset,
+          y: rowLevel * cellSize * rowSpacing - cellSize,
+          text: format(firstDayOfMonth, 'month'),
+          year,
+        });
+      });
+    }
+
+    return labels;
+  });
+
+  // Calculate year label positions
+  const yearLabels = $derived.by(() => {
+    const labels: Array<{ x: number; y: number; text: string }> = [];
+
+    for (let year = startYear; year <= endYear; year++) {
+      labels.push({
+        x: ctx.width / 2,
+        y: cellSize * 5.5,
+        text: String(year),
+      });
+    }
+
+    return labels;
+  });
+</script>
+
+<Group y={-cellSize * 4}>
+  <!-- Cells -->
+  {#if children}
+    {@render children({ cells: allCells, cellSize })}
+  {:else}
+    {#each allCells as cell}
+      <Rect
+        x={cell.x}
+        y={cell.y}
+        width={cellSize}
+        height={cellSize}
+        fill={cell.color}
+        onpointermove={(e) => tooltip?.show(e, cell.data)}
+        onpointerleave={(e) => tooltip?.hide()}
+        {...extractLayerProps(restProps, 'lc-month-cell')}
+      />
+
+      {#if showDayNumber}
+        <Text
+          x={cell.x + cellSize / 2}
+          y={cell.y + cellSize / 2}
+          lineHeight="0.8em"
+          value={cell.date.getDate()}
+          textAnchor="middle"
+          verticalAnchor="middle"
+          class="lc-month-day-number"
+          {...dayNumberProps}
+        />
+      {/if}
+    {/each}
+  {/if}
+
+  <!-- Month labels -->
+  {#if showMonthLabel}
+    {#each monthLabels as label}
+      <Text
+        x={label.x}
+        y={label.y}
+        value={label.text}
+        class="lc-month-month-label"
+        {...monthLabelProps}
+      />
+    {/each}
+  {/if}
+
+  <!-- Year labels -->
+  {#if showYearLabel}
+    {#each yearLabels as label}
+      <Text
+        x={label.x}
+        y={label.y}
+        value={label.text}
+        class="lc-month-year-label"
+        {...yearLabelProps}
+      />
+    {/each}
+  {/if}
+</Group>
+
+<style>
+  @layer components {
+    :global(:where(.lc-month-cell)) {
+      stroke-width: 1;
+      --stroke-color: color-mix(
+        in oklab,
+        var(--color-surface-content, currentColor) 20%,
+        transparent
+      );
+    }
+
+    :global(:where(.lc-month-day-number)) {
+      font-size: 10px;
+      pointer-events: none;
+      stroke: var(--color-surface-100, light-dark(white, black));
+      stroke-width: 1px;
+      font-weight: 600;
+    }
+
+    :global(:where(.lc-month-month-label)) {
+      font-size: 1.1em;
+    }
+
+    :global(:where(.lc-month-year-label)) {
+      font-size: 1.5em;
+    }
+  }
+</style>
diff --git a/packages/layerchart/src/lib/components/index.ts b/packages/layerchart/src/lib/components/index.ts
index 48e14a6fd..29618840c 100644
--- a/packages/layerchart/src/lib/components/index.ts
+++ b/packages/layerchart/src/lib/components/index.ts
@@ -93,6 +93,8 @@ export { default as Link } from './Link.svelte';
 export * from './Link.svelte';
 export { default as MotionPath } from './MotionPath.svelte';
 export * from './MotionPath.svelte';
+export { default as Month } from './Month.svelte';
+export * from './Month.svelte';
 export { default as Pack } from './Pack.svelte';
 export * from './Pack.svelte';
 export { default as Partition } from './Partition.svelte';
diff --git a/packages/layerchart/src/routes/_NavMenu.svelte b/packages/layerchart/src/routes/_NavMenu.svelte
index 5faa8e2ac..a2159e980 100644
--- a/packages/layerchart/src/routes/_NavMenu.svelte
+++ b/packages/layerchart/src/routes/_NavMenu.svelte
@@ -91,6 +91,7 @@
       'Hull',
       'Labels',
       'Link',
+      'Month',
       'Pie',
       'Points',
       'Spline',
diff --git a/packages/layerchart/src/routes/docs/components/Month/+page.svelte b/packages/layerchart/src/routes/docs/components/Month/+page.svelte
new file mode 100644
index 000000000..02b18eaa1
--- /dev/null
+++ b/packages/layerchart/src/routes/docs/components/Month/+page.svelte
@@ -0,0 +1,346 @@
+<script lang="ts">
+  import { scaleThreshold } from 'd3-scale';
+
+  import { Month, Chart, Tooltip, Layer } from 'layerchart';
+
+  import Preview from '$lib/docs/Preview.svelte';
+  import { createDateSeries } from '$lib/utils/genData.js';
+  import { shared } from '../../shared.svelte.js';
+
+  const data = createDateSeries({ count: 365 * 4, min: 10, max: 100, value: 'integer' }).map(
+    (d) => {
+      return {
+        ...d,
+        value: Math.random() > 0.2 ? d.value : null, // set null for some values
+      };
+    }
+  );
+
+  const startYear = new Date().getFullYear() - 4;
+  const endYear = new Date().getFullYear();
+</script>
+
+<h1>Examples</h1>
+
+<h2>Single year</h2>
+
+<Preview {data}>
+  <div class="h-[900px] p-4 border rounded-sm">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month startYear={endYear} {endYear} tooltipContext={context.tooltip} />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview>
+
+<h2>Multiple years (default)</h2>
+
+<Preview {data}>
+  <div class="h-[900px] p-4 border rounded-sm overflow-auto">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month {startYear} {endYear} tooltipContext={context.tooltip} />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview>
+
+<!--
+
+<h2>Custom cell size</h2>
+
+<Preview {data}>
+  <div class="h-[800px] p-4 border rounded-sm overflow-auto">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month {startYear} {endYear} cellSize={30} tooltipContext={context.tooltip} />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview>
+
+<h2>Custom months per row</h2>
+
+<Preview {data}>
+  <div class="h-[1200px] p-4 border rounded-sm overflow-auto">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month {startYear} {endYear} monthsPerRow={4} tooltipContext={context.tooltip} />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview>
+
+<h2>Without day numbers</h2>
+
+<Preview {data}>
+  <div class="h-[600px] p-4 border rounded-sm overflow-auto">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month {startYear} {endYear} showDayNumber={false} tooltipContext={context.tooltip} />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview>
+
+<h2>Custom label styles</h2>
+
+<Preview {data}>
+  <div class="h-[600px] p-4 border rounded-sm overflow-auto">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month
+            {startYear}
+            {endYear}
+            tooltipContext={context.tooltip}
+            monthLabelProps={{
+              class: 'text-primary-500 font-bold',
+            }}
+            yearLabelProps={{
+              class: 'text-primary-700 font-bold',
+            }}
+          />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview>
+
+<h2>Minimal (no labels)</h2>
+
+<Preview {data}>
+  <div class="h-[600px] p-4 border rounded-sm overflow-auto">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month
+            {startYear}
+            {endYear}
+            showDayNumber={false}
+            showMonthLabel={false}
+            showYearLabel={false}
+            tooltipContext={context.tooltip}
+          />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview>
+
+<h2>Current year</h2>
+
+<Preview {data}>
+  <div class="h-[400px] p-4 border rounded-sm">
+    <Chart
+      {data}
+      x="date"
+      c="value"
+      cScale={scaleThreshold().unknown('transparent')}
+      cDomain={[25, 50, 75]}
+      cRange={[
+        'var(--color-primary-100)',
+        'var(--color-primary-300)',
+        'var(--color-primary-500)',
+        'var(--color-primary-700)',
+      ]}
+    >
+      {#snippet children({ context })}
+        <Layer type={shared.renderContext}>
+          <Month tooltipContext={context.tooltip} />
+        </Layer>
+
+        <Tooltip.Root>
+          {#snippet children({ data })}
+            <Tooltip.Header value={data.date} format="day" />
+
+            {#if data.value != null}
+              <Tooltip.List>
+                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
+              </Tooltip.List>
+            {/if}
+          {/snippet}
+        </Tooltip.Root>
+      {/snippet}
+    </Chart>
+  </div>
+</Preview> -->
diff --git a/packages/layerchart/src/routes/docs/components/Month/+page.ts b/packages/layerchart/src/routes/docs/components/Month/+page.ts
new file mode 100644
index 000000000..e90988ada
--- /dev/null
+++ b/packages/layerchart/src/routes/docs/components/Month/+page.ts
@@ -0,0 +1,14 @@
+import api from '$lib/components/Month.svelte?raw&sveld';
+import source from '$lib/components/Month.svelte?raw';
+import pageSource from './+page.svelte?raw';
+
+export async function load() {
+  return {
+    meta: {
+      api,
+      source,
+      pageSource,
+      supportedContexts: ['svg', 'canvas', 'html'],
+    },
+  };
+}

From 5b32c77f9d7b8f357c935a79b0d1bbeed0cdaa77 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Fri, 24 Oct 2025 09:47:59 -0400
Subject: [PATCH 2/5] Support start/end that do not align on year boundaries
 (ex. last 90 days)

---
 .../src/lib/components/Month.svelte           | 184 +++++++-----------
 .../routes/docs/components/Month/+page.svelte | 134 +++----------
 2 files changed, 95 insertions(+), 223 deletions(-)

diff --git a/packages/layerchart/src/lib/components/Month.svelte b/packages/layerchart/src/lib/components/Month.svelte
index dc85e7eda..301ebfbf1 100644
--- a/packages/layerchart/src/lib/components/Month.svelte
+++ b/packages/layerchart/src/lib/components/Month.svelte
@@ -9,18 +9,14 @@
 
   export type MonthPropsWithoutHTML = {
     /**
-     * The start year to display.
-     *
-     * @default current year
+     * The start date of the calendar.
      */
-    startYear?: number;
+    start: Date;
 
     /**
-     * The end year to display (inclusive).
-     *
-     * @default current year
+     * The end date of the calendar.
      */
-    endYear?: number;
+    end: Date;
 
     /**
      * Size of the cell in the calendar.
@@ -55,29 +51,10 @@
      */
     showDayNumber?: boolean;
 
-    /**
-     * Whether to show month labels.
-     *
-     * @default true
-     */
-    showMonthLabel?: boolean;
-
-    /**
-     * Whether to show year labels.
-     *
-     * @default true
-     */
-    showYearLabel?: boolean;
-
     /**
      * Props to pass to the `<text>` element for month labels.
      */
-    monthLabelProps?: Partial<ComponentProps<typeof Text>>;
-
-    /**
-     * Props to pass to the `<text>` element for year labels.
-     */
-    yearLabelProps?: Partial<ComponentProps<typeof Text>>;
+    monthLabel?: boolean | Partial<ComponentProps<typeof Text>>;
 
     /**
      * Props to pass to the `<text>` element for day numbers.
@@ -118,16 +95,14 @@
   const DAYS_PER_WEEK = 7;
 
   let {
-    startYear = new Date().getFullYear(),
-    endYear = new Date().getFullYear(),
+    start,
+    end,
     cellSize = 25,
+    monthsPerRow: monthsPerRowProp,
     monthPadding = 1.2,
     rowSpacing = 8,
     showDayNumber = true,
-    showMonthLabel = true,
-    showYearLabel = true,
-    monthLabelProps = {},
-    yearLabelProps = {},
+    monthLabel = true,
     dayNumberProps = {},
     tooltipContext: tooltip,
     children,
@@ -136,16 +111,23 @@
 
   const ctx = getChartContext();
 
+  const rangeDays = $derived(timeDays(start, end));
+  const rangeMonths = $derived(timeMonths(start, end));
+
+  // Space needed for month labels at the top
+  const monthLabelHeight = $derived(cellSize);
+
   // Calculate monthsPerRow based on the actual space taken by each month
   // Each month (except the last in a row) takes: (monthPadding * cellSize * DAYS_PER_WEEK)
   // The calculation accounts for n-1 padded months plus one unpadded month
   // Formula: (n-1) * monthPadding * width + width = totalWidth
   // Solving for n: n = (totalWidth + (monthPadding - 1) * width) / (monthPadding * width)
   const monthsPerRow = $derived(
-    Math.floor(
-      (ctx.width + (monthPadding - 1) * cellSize * DAYS_PER_WEEK) /
-        (monthPadding * cellSize * DAYS_PER_WEEK)
-    )
+    monthsPerRowProp ??
+      Math.floor(
+        (ctx.width + (monthPadding - 1) * cellSize * DAYS_PER_WEEK) /
+          (monthPadding * cellSize * DAYS_PER_WEEK)
+      )
   );
 
   // Generate data indexed by date (using date object as key)
@@ -153,86 +135,66 @@
     ctx.data && ctx.config.x ? index(chartDataArray(ctx.data), (d) => ctx.x(d)) : new Map()
   );
 
-  // Generate cells for all years
+  // Generate cells for the date range
   const allCells = $derived.by(() => {
     const cells: MonthCell[] = [];
-
-    for (let year = startYear; year <= endYear; year++) {
-      const firstDayOfYear = new Date(year, 0, 1);
-      const lastDayOfYear = new Date(year + 1, 0, 1);
-      const yearDays = timeDays(firstDayOfYear, lastDayOfYear);
-
-      yearDays.forEach((day) => {
-        const firstDayOfMonth = new Date(day.getFullYear(), day.getMonth(), 1);
-        const cellData = dataByDate.get(day) ?? { date: day };
-
-        const monthIndex = day.getMonth();
-        const monthCol = monthIndex % monthsPerRow;
-        const monthRow = Math.floor(monthIndex / monthsPerRow);
-
-        const monthPaddingOffset = monthPadding * cellSize * DAYS_PER_WEEK * monthCol;
-        const weekDiff = timeWeek.count(firstDayOfMonth, day);
-        const rowLevel = monthRow + 1;
-
-        cells.push({
-          x: day.getDay() * cellSize + monthPaddingOffset,
-          y: weekDiff * cellSize + rowLevel * cellSize * rowSpacing - cellSize / 2,
-          color: ctx.config.c ? ctx.cGet(cellData) : 'transparent',
-          data: cellData,
-          date: day,
-        });
+    // Create a map of month index to track which months we've seen
+    const monthIndexMap = new Map<string, number>();
+    let currentMonthIndex = 0;
+
+    rangeDays.forEach((day) => {
+      const firstDayOfMonth = new Date(day.getFullYear(), day.getMonth(), 1);
+      const monthKey = `${day.getFullYear()}-${day.getMonth()}`;
+
+      // Assign a sequential index to each unique month in the range
+      if (!monthIndexMap.has(monthKey)) {
+        monthIndexMap.set(monthKey, currentMonthIndex);
+        currentMonthIndex++;
+      }
+
+      const monthIndex = monthIndexMap.get(monthKey)!;
+      const cellData = dataByDate.get(day) ?? { date: day };
+
+      const monthCol = monthIndex % monthsPerRow;
+      const monthRow = Math.floor(monthIndex / monthsPerRow);
+
+      const monthPaddingOffset = monthPadding * cellSize * DAYS_PER_WEEK * monthCol;
+      const weekDiff = timeWeek.count(firstDayOfMonth, day);
+
+      cells.push({
+        x: day.getDay() * cellSize + monthPaddingOffset,
+        y: weekDiff * cellSize + monthRow * cellSize * rowSpacing + monthLabelHeight,
+        color: ctx.config.c ? ctx.cGet(cellData) : 'transparent',
+        data: cellData,
+        date: day,
       });
-    }
+    });
 
     return cells;
   });
 
   // Generate month labels
   const monthLabels = $derived.by(() => {
-    const labels: Array<{ x: number; y: number; text: string; year: number }> = [];
-
-    for (let year = startYear; year <= endYear; year++) {
-      const firstDayOfYear = new Date(year, 0, 1);
-      const lastDayOfYear = new Date(year + 1, 0, 1);
-      const yearMonths = timeMonths(firstDayOfYear, lastDayOfYear);
-
-      yearMonths.forEach((firstDayOfMonth) => {
-        const monthIndex = firstDayOfMonth.getMonth();
-        const monthCol = monthIndex % monthsPerRow;
-        const monthRow = Math.floor(monthIndex / monthsPerRow);
-
-        const monthPaddingOffset = monthPadding * cellSize * DAYS_PER_WEEK * monthCol;
-        const rowLevel = monthRow + 1;
-
-        labels.push({
-          x: monthPaddingOffset,
-          y: rowLevel * cellSize * rowSpacing - cellSize,
-          text: format(firstDayOfMonth, 'month'),
-          year,
-        });
-      });
-    }
+    const labels: Array<{ x: number; y: number; text: string }> = [];
 
-    return labels;
-  });
+    rangeMonths.forEach((firstDayOfMonth, index) => {
+      const monthCol = index % monthsPerRow;
+      const monthRow = Math.floor(index / monthsPerRow);
 
-  // Calculate year label positions
-  const yearLabels = $derived.by(() => {
-    const labels: Array<{ x: number; y: number; text: string }> = [];
+      const monthPaddingOffset = monthPadding * cellSize * DAYS_PER_WEEK * monthCol;
 
-    for (let year = startYear; year <= endYear; year++) {
       labels.push({
-        x: ctx.width / 2,
-        y: cellSize * 5.5,
-        text: String(year),
+        x: monthPaddingOffset,
+        y: monthRow * cellSize * rowSpacing,
+        text: format(firstDayOfMonth, 'month'),
       });
-    }
+    });
 
     return labels;
   });
 </script>
 
-<Group y={-cellSize * 4}>
+<Group>
   <!-- Cells -->
   {#if children}
     {@render children({ cells: allCells, cellSize })}
@@ -265,27 +227,15 @@
   {/if}
 
   <!-- Month labels -->
-  {#if showMonthLabel}
+  {#if monthLabel}
     {#each monthLabels as label}
       <Text
         x={label.x}
         y={label.y}
         value={label.text}
+        verticalAnchor="start"
         class="lc-month-month-label"
-        {...monthLabelProps}
-      />
-    {/each}
-  {/if}
-
-  <!-- Year labels -->
-  {#if showYearLabel}
-    {#each yearLabels as label}
-      <Text
-        x={label.x}
-        y={label.y}
-        value={label.text}
-        class="lc-month-year-label"
-        {...yearLabelProps}
+        {...extractLayerProps(monthLabel, 'lc-month-month-label')}
       />
     {/each}
   {/if}
@@ -311,11 +261,7 @@
     }
 
     :global(:where(.lc-month-month-label)) {
-      font-size: 1.1em;
-    }
-
-    :global(:where(.lc-month-year-label)) {
-      font-size: 1.5em;
+      font-size: 16px;
     }
   }
 </style>
diff --git a/packages/layerchart/src/routes/docs/components/Month/+page.svelte b/packages/layerchart/src/routes/docs/components/Month/+page.svelte
index 02b18eaa1..3c3dae09f 100644
--- a/packages/layerchart/src/routes/docs/components/Month/+page.svelte
+++ b/packages/layerchart/src/routes/docs/components/Month/+page.svelte
@@ -1,11 +1,13 @@
 <script lang="ts">
   import { scaleThreshold } from 'd3-scale';
+  import { timeYear } from 'd3-time';
 
   import { Month, Chart, Tooltip, Layer } from 'layerchart';
 
   import Preview from '$lib/docs/Preview.svelte';
   import { createDateSeries } from '$lib/utils/genData.js';
   import { shared } from '../../shared.svelte.js';
+  import { endOfInterval, intervalOffset, startOfInterval } from '@layerstack/utils';
 
   const data = createDateSeries({ count: 365 * 4, min: 10, max: 100, value: 'integer' }).map(
     (d) => {
@@ -16,13 +18,16 @@
     }
   );
 
-  const startYear = new Date().getFullYear() - 4;
-  const endYear = new Date().getFullYear();
+  const now = new Date();
+  const firstDayOfYear = timeYear.floor(now);
+  const lastDayOfYear = endOfInterval('year', now);
+  const ninetyDaysAgo = intervalOffset('day', now, -90);
+  const threeYearsAgo = intervalOffset('year', now, -3);
 </script>
 
 <h1>Examples</h1>
 
-<h2>Single year</h2>
+<h2>Current year</h2>
 
 <Preview {data}>
   <div class="h-[900px] p-4 border rounded-sm">
@@ -41,45 +46,7 @@
     >
       {#snippet children({ context })}
         <Layer type={shared.renderContext}>
-          <Month startYear={endYear} {endYear} tooltipContext={context.tooltip} />
-        </Layer>
-
-        <Tooltip.Root>
-          {#snippet children({ data })}
-            <Tooltip.Header value={data.date} format="day" />
-
-            {#if data.value != null}
-              <Tooltip.List>
-                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
-              </Tooltip.List>
-            {/if}
-          {/snippet}
-        </Tooltip.Root>
-      {/snippet}
-    </Chart>
-  </div>
-</Preview>
-
-<h2>Multiple years (default)</h2>
-
-<Preview {data}>
-  <div class="h-[900px] p-4 border rounded-sm overflow-auto">
-    <Chart
-      {data}
-      x="date"
-      c="value"
-      cScale={scaleThreshold().unknown('transparent')}
-      cDomain={[25, 50, 75]}
-      cRange={[
-        'var(--color-primary-100)',
-        'var(--color-primary-300)',
-        'var(--color-primary-500)',
-        'var(--color-primary-700)',
-      ]}
-    >
-      {#snippet children({ context })}
-        <Layer type={shared.renderContext}>
-          <Month {startYear} {endYear} tooltipContext={context.tooltip} />
+          <Month start={firstDayOfYear} end={lastDayOfYear} tooltipContext={context.tooltip} />
         </Layer>
 
         <Tooltip.Root>
@@ -98,12 +65,10 @@
   </div>
 </Preview>
 
-<!--
-
-<h2>Custom cell size</h2>
+<h2>Last 90 days</h2>
 
 <Preview {data}>
-  <div class="h-[800px] p-4 border rounded-sm overflow-auto">
+  <div class="h-[400px] p-4 border rounded-sm">
     <Chart
       {data}
       x="date"
@@ -119,7 +84,7 @@
     >
       {#snippet children({ context })}
         <Layer type={shared.renderContext}>
-          <Month {startYear} {endYear} cellSize={30} tooltipContext={context.tooltip} />
+          <Month start={ninetyDaysAgo} end={now} tooltipContext={context.tooltip} />
         </Layer>
 
         <Tooltip.Root>
@@ -138,10 +103,10 @@
   </div>
 </Preview>
 
-<h2>Custom months per row</h2>
+<h2>Multiple years</h2>
 
 <Preview {data}>
-  <div class="h-[1200px] p-4 border rounded-sm overflow-auto">
+  <div class="h-[600px] p-4 border rounded-sm overflow-auto">
     <Chart
       {data}
       x="date"
@@ -157,7 +122,7 @@
     >
       {#snippet children({ context })}
         <Layer type={shared.renderContext}>
-          <Month {startYear} {endYear} monthsPerRow={4} tooltipContext={context.tooltip} />
+          <Month start={threeYearsAgo} end={now} tooltipContext={context.tooltip} />
         </Layer>
 
         <Tooltip.Root>
@@ -176,7 +141,7 @@
   </div>
 </Preview>
 
-<h2>Without day numbers</h2>
+<h2>Custom cell size</h2>
 
 <Preview {data}>
   <div class="h-[600px] p-4 border rounded-sm overflow-auto">
@@ -195,7 +160,12 @@
     >
       {#snippet children({ context })}
         <Layer type={shared.renderContext}>
-          <Month {startYear} {endYear} showDayNumber={false} tooltipContext={context.tooltip} />
+          <Month
+            start={firstDayOfYear}
+            end={lastDayOfYear}
+            cellSize={20}
+            tooltipContext={context.tooltip}
+          />
         </Layer>
 
         <Tooltip.Root>
@@ -214,7 +184,7 @@
   </div>
 </Preview>
 
-<h2>Custom label styles</h2>
+<h2>Without day numbers</h2>
 
 <Preview {data}>
   <div class="h-[600px] p-4 border rounded-sm overflow-auto">
@@ -234,15 +204,10 @@
       {#snippet children({ context })}
         <Layer type={shared.renderContext}>
           <Month
-            {startYear}
-            {endYear}
+            start={firstDayOfYear}
+            end={lastDayOfYear}
+            showDayNumber={false}
             tooltipContext={context.tooltip}
-            monthLabelProps={{
-              class: 'text-primary-500 font-bold',
-            }}
-            yearLabelProps={{
-              class: 'text-primary-700 font-bold',
-            }}
           />
         </Layer>
 
@@ -262,7 +227,7 @@
   </div>
 </Preview>
 
-<h2>Minimal (no labels)</h2>
+<h2>Without month labels</h2>
 
 <Preview {data}>
   <div class="h-[600px] p-4 border rounded-sm overflow-auto">
@@ -282,11 +247,10 @@
       {#snippet children({ context })}
         <Layer type={shared.renderContext}>
           <Month
-            {startYear}
-            {endYear}
+            start={firstDayOfYear}
+            end={lastDayOfYear}
             showDayNumber={false}
-            showMonthLabel={false}
-            showYearLabel={false}
+            monthLabel={false}
             tooltipContext={context.tooltip}
           />
         </Layer>
@@ -306,41 +270,3 @@
     </Chart>
   </div>
 </Preview>
-
-<h2>Current year</h2>
-
-<Preview {data}>
-  <div class="h-[400px] p-4 border rounded-sm">
-    <Chart
-      {data}
-      x="date"
-      c="value"
-      cScale={scaleThreshold().unknown('transparent')}
-      cDomain={[25, 50, 75]}
-      cRange={[
-        'var(--color-primary-100)',
-        'var(--color-primary-300)',
-        'var(--color-primary-500)',
-        'var(--color-primary-700)',
-      ]}
-    >
-      {#snippet children({ context })}
-        <Layer type={shared.renderContext}>
-          <Month tooltipContext={context.tooltip} />
-        </Layer>
-
-        <Tooltip.Root>
-          {#snippet children({ data })}
-            <Tooltip.Header value={data.date} format="day" />
-
-            {#if data.value != null}
-              <Tooltip.List>
-                <Tooltip.Item label="value" value={data.value} valueAlign="right" />
-              </Tooltip.List>
-            {/if}
-          {/snippet}
-        </Tooltip.Root>
-      {/snippet}
-    </Chart>
-  </div>
-</Preview> -->

From 81fa7db10b0135a9397b4e701a866e5a4017c718 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Fri, 24 Oct 2025 09:51:27 -0400
Subject: [PATCH 3/5] Refactor Month component to remove unused rangeMonths and
 enhance month label generation

---
 .../src/lib/components/Month.svelte           | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/packages/layerchart/src/lib/components/Month.svelte b/packages/layerchart/src/lib/components/Month.svelte
index 301ebfbf1..6071d1a12 100644
--- a/packages/layerchart/src/lib/components/Month.svelte
+++ b/packages/layerchart/src/lib/components/Month.svelte
@@ -112,7 +112,6 @@
   const ctx = getChartContext();
 
   const rangeDays = $derived(timeDays(start, end));
-  const rangeMonths = $derived(timeMonths(start, end));
 
   // Space needed for month labels at the top
   const monthLabelHeight = $derived(cellSize);
@@ -170,14 +169,22 @@
       });
     });
 
-    return cells;
+    return { cells, monthIndexMap };
   });
 
-  // Generate month labels
+  // Generate month labels based on the actual months encountered in the cells
   const monthLabels = $derived.by(() => {
     const labels: Array<{ x: number; y: number; text: string }> = [];
+    const monthIndexMap = allCells.monthIndexMap;
+
+    // Convert the map to an array of [monthKey, index] pairs and sort by index
+    const monthEntries = Array.from(monthIndexMap.entries()).sort((a, b) => a[1] - b[1]);
+
+    monthEntries.forEach(([monthKey, index]) => {
+      // Parse the monthKey to get the year and month
+      const [year, month] = monthKey.split('-').map(Number);
+      const firstDayOfMonth = new Date(year, month, 1);
 
-    rangeMonths.forEach((firstDayOfMonth, index) => {
       const monthCol = index % monthsPerRow;
       const monthRow = Math.floor(index / monthsPerRow);
 
@@ -197,9 +204,9 @@
 <Group>
   <!-- Cells -->
   {#if children}
-    {@render children({ cells: allCells, cellSize })}
+    {@render children({ cells: allCells.cells, cellSize })}
   {:else}
-    {#each allCells as cell}
+    {#each allCells.cells as cell}
       <Rect
         x={cell.x}
         y={cell.y}

From 5b2f3b4b37a6bde1dcf063a651901e88a5b84f22 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Fri, 24 Oct 2025 09:54:24 -0400
Subject: [PATCH 4/5] Update monthLabelHeight calculation to conditionally
 account for label visibility

---
 packages/layerchart/src/lib/components/Month.svelte | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/layerchart/src/lib/components/Month.svelte b/packages/layerchart/src/lib/components/Month.svelte
index 6071d1a12..ea5e40141 100644
--- a/packages/layerchart/src/lib/components/Month.svelte
+++ b/packages/layerchart/src/lib/components/Month.svelte
@@ -113,8 +113,8 @@
 
   const rangeDays = $derived(timeDays(start, end));
 
-  // Space needed for month labels at the top
-  const monthLabelHeight = $derived(cellSize);
+  // Space needed for month labels at the top (only if labels are shown)
+  const monthLabelHeight = $derived(monthLabel ? cellSize : 0);
 
   // Calculate monthsPerRow based on the actual space taken by each month
   // Each month (except the last in a row) takes: (monthPadding * cellSize * DAYS_PER_WEEK)

From 12170d9c07a16f151ad6a59050c0fc40e7ce0104 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Fri, 24 Oct 2025 09:56:34 -0400
Subject: [PATCH 5/5] Update Month component to use current date as end date
 instead of last day of year

---
 .../layerchart/src/routes/docs/components/Month/+page.svelte  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/layerchart/src/routes/docs/components/Month/+page.svelte b/packages/layerchart/src/routes/docs/components/Month/+page.svelte
index 3c3dae09f..35c43c42b 100644
--- a/packages/layerchart/src/routes/docs/components/Month/+page.svelte
+++ b/packages/layerchart/src/routes/docs/components/Month/+page.svelte
@@ -205,7 +205,7 @@
         <Layer type={shared.renderContext}>
           <Month
             start={firstDayOfYear}
-            end={lastDayOfYear}
+            end={now}
             showDayNumber={false}
             tooltipContext={context.tooltip}
           />
@@ -248,7 +248,7 @@
         <Layer type={shared.renderContext}>
           <Month
             start={firstDayOfYear}
-            end={lastDayOfYear}
+            end={now}
             showDayNumber={false}
             monthLabel={false}
             tooltipContext={context.tooltip}