@siyahi/ui 0.1.9-next.3 → 0.1.9-next.30

package/dist/components/registry/dashboardcn/sparkline.js

@@ -0,0 +1,117 @@
+import { cn } from "../../../lib/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React$1 from "react";
+import { Area, AreaChart, Line, LineChart, ResponsiveContainer, YAxis } from "recharts";
+//#region src/components/registry/dashboardcn/sparkline.tsx
+const reducedMotionQuery = "(prefers-reduced-motion: reduce)";
+function subscribeToReducedMotion(onChange) {
+	const query = window.matchMedia(reducedMotionQuery);
+	query.addEventListener("change", onChange);
+	return () => query.removeEventListener("change", onChange);
+}
+function getReducedMotionSnapshot() {
+	return window.matchMedia(reducedMotionQuery).matches;
+}
+function getReducedMotionServerSnapshot() {
+	return true;
+}
+function Sparkline({ data, variant = "area", color = "var(--chart-1)", curve = "linear", strokeWidth = 1.25, animate = true, animationDuration = 500, className, ...props }) {
+	const id = React$1.useId();
+	const reducedMotion = React$1.useSyncExternalStore(subscribeToReducedMotion, getReducedMotionSnapshot, getReducedMotionServerSnapshot);
+	const animationActive = animate && !reducedMotion;
+	const points = React$1.useMemo(() => data.map((y, i) => ({
+		i,
+		y,
+		now: i >= data.length - 2 ? y : void 0
+	})), [data]);
+	const margin = {
+		top: 3,
+		right: 3,
+		bottom: 3,
+		left: 0
+	};
+	const axis = /* @__PURE__ */ jsx(YAxis, {
+		hide: true,
+		domain: ["dataMin", "dataMax"]
+	});
+	const now = /* @__PURE__ */ jsx(Line, {
+		className: "sparkline-now",
+		type: curve,
+		dataKey: "now",
+		stroke: color,
+		strokeWidth: 2,
+		dot: (dot) => dot.index === data.length - 1 ? /* @__PURE__ */ jsx("circle", {
+			cx: dot.cx,
+			cy: dot.cy,
+			r: 3,
+			fill: color
+		}, "now") : /* @__PURE__ */ jsx("g", {}, dot.index),
+		isAnimationActive: animationActive,
+		animationBegin: animationDuration,
+		animationDuration: 150
+	});
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "sparkline",
+		"aria-hidden": "true",
+		className: cn("h-10 w-full", className),
+		...props,
+		children: /* @__PURE__ */ jsx(ResponsiveContainer, {
+			width: "100%",
+			height: "100%",
+			children: variant === "line" ? /* @__PURE__ */ jsxs(LineChart, {
+				data: points,
+				margin,
+				children: [
+					axis,
+					/* @__PURE__ */ jsx(Line, {
+						type: curve,
+						dataKey: "y",
+						stroke: "var(--muted-foreground)",
+						strokeWidth,
+						dot: false,
+						isAnimationActive: animationActive,
+						animationDuration,
+						animationEasing: "ease-out"
+					}),
+					now
+				]
+			}) : /* @__PURE__ */ jsxs(AreaChart, {
+				data: points,
+				margin,
+				children: [
+					axis,
+					/* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsxs("linearGradient", {
+						id,
+						x1: "0",
+						y1: "0",
+						x2: "0",
+						y2: "1",
+						children: [/* @__PURE__ */ jsx("stop", {
+							offset: "0%",
+							stopColor: color,
+							stopOpacity: .18
+						}), /* @__PURE__ */ jsx("stop", {
+							offset: "100%",
+							stopColor: color,
+							stopOpacity: 0
+						})]
+					}) }),
+					/* @__PURE__ */ jsx(Area, {
+						type: curve,
+						dataKey: "y",
+						stroke: "var(--muted-foreground)",
+						strokeWidth,
+						fill: `url(#${id})`,
+						dot: false,
+						isAnimationActive: animationActive,
+						animationDuration,
+						animationEasing: "ease-out"
+					}),
+					now
+				]
+			})
+		})
+	});
+}
+//#endregion
+export { Sparkline };

package/dist/components/registry/heatmap/calendar-heatmap.d.ts

@@ -32,6 +32,10 @@ export type CalendarHeatmapProps = HTMLAttributes<HTMLDivElement> & {
   blockAspectRatio?: number;
   levels?: number;
   isNormalized?: boolean;
+  /** Colour each day green or red by its sign, deeper the larger it is, for a daily gain or loss. */
+  signed?: boolean;
+  /** With signed: the size that takes the deepest step. Defaults to the largest day's. */
+  range?: number;
   colors?: ColorConfig;
   locale?: Locale;
   labels?: Labels;
@@ -75,8 +79,10 @@ export type CalendarHeatmapProps = HTMLAttributes<HTMLDivElement> & {
  * @param levels - Total number of legend cells (including empty when not normalized). Default: 5
  * @param isNormalized - When true, uses min-max normalization across the dataset (suitable for signed values). When false (default), treats 0 as empty and scales from 0 to max.
  */
-export declare const CalendarHeatmap: ({ data, weekStart, continuousMonths, hasEmptyColumn, blockSize, blockMargin, blockRadius, blockAspectRatio, levels: levelsProp, isNormalized, colors, locale, labels: labelsProp, fontSize, emptyState, totalCount: totalCountProp, style, className, children, ...props }: CalendarHeatmapProps) => string | number | bigint | true | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null;
+export declare const CalendarHeatmap: ({ data, weekStart, continuousMonths, hasEmptyColumn, blockSize: blockSizeProp, blockMargin, blockRadius, blockAspectRatio, levels: levelsProp, isNormalized, signed, range, colors, locale, labels: labelsProp, fontSize, emptyState, totalCount: totalCountProp, style, className, children, ...props }: CalendarHeatmapProps) => string | number | bigint | true | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null;
 export type CalendarHeatmapBlockProps = HTMLAttributes<SVGRectElement> & {
+  /** The cell the page has picked: drawn with a ring and announced as pressed. */
+  selected?: boolean;
   activity: ActivityWithLevel;
   dayIndex: number;
   weekIndex: number;
@@ -84,7 +90,7 @@ export type CalendarHeatmapBlockProps = HTMLAttributes<SVGRectElement> & {
   onCellClick?: (activity: ActivityWithLevel) => void;
   onCellHover?: (activity: ActivityWithLevel | null) => void;
 };
-export declare function CalendarHeatmapBlock({ ref, activity, dayIndex, weekIndex, highlighted, onCellClick, onCellHover, onClick, onKeyDown, onMouseEnter, onMouseLeave, className, style: styleProp, ...props }: CalendarHeatmapBlockProps & {
+export declare function CalendarHeatmapBlock({ ref, activity, dayIndex, weekIndex, highlighted, selected, onCellClick, onCellHover, onClick, onKeyDown, onMouseEnter, onMouseLeave, className, style: styleProp, ...props }: CalendarHeatmapBlockProps & {
   ref?: React.RefObject<SVGRectElement | null>;
 }): import("react").JSX.Element;
 export declare namespace CalendarHeatmapBlock {
@@ -125,10 +131,12 @@ export type CalendarHeatmapLegendProps = Omit<HTMLAttributes<HTMLFieldSetElement
     less?: string;
     more?: string;
   };
+  /** A signed heatmap's figures in the legend's scale line, such as useFormat().money. */
+  valueFormatter?: (value: number) => string;
   children?: (props: {
     level: number;
   }) => ReactNode;
 };
-export declare const CalendarHeatmapLegend: ({ labels: labelsProp, className, children, ...props }: CalendarHeatmapLegendProps) => import("react").JSX.Element;
+export declare const CalendarHeatmapLegend: ({ labels: labelsProp, valueFormatter, className, children, ...props }: CalendarHeatmapLegendProps) => import("react").JSX.Element;
 //#endregion
 export {};

package/dist/components/registry/heatmap/calendar-heatmap.js

@@ -1,16 +1,18 @@
 import { cn } from "../../../lib/utils.js";
+import { useElementWidth } from "../../../lib/use-element-width.js";
+import { useHeatmapNavigation } from "../../../lib/heatmap-navigation.js";
+import { heat, heatFill } from "../../../lib/heat.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { Fragment as Fragment$1, createContext, use, useMemo } from "react";
+import { Fragment as Fragment$1, createContext, use, useLayoutEffect, useMemo } from "react";
 import { differenceInCalendarDays, eachDayOfInterval, format, formatISO, getDay, getMonth, getYear, nextDay, parseISO, subWeeks } from "date-fns";
 //#region src/components/registry/heatmap/calendar-heatmap.tsx
 const colorStepCount = (levels, isNormalized) => Math.max(1, isNormalized ? levels : levels - 1);
-const getLevelFill = (level, levels, isNormalized, highlighted = false, colors) => {
+const getLevelFill = (level, levels, isNormalized, colors) => {
 	const emptyColor = colors?.empty ?? "var(--color-secondary)";
 	const scaleColor = colors?.scale ?? "var(--color-chart-1)";
 	if (level === 0) return emptyColor;
 	const steps = colorStepCount(levels, isNormalized);
-	const opacity = steps === 1 ? 100 : Math.round(20 + (level - 1) * 80 / (steps - 1));
-	return `color-mix(in oklch, ${scaleColor} ${highlighted ? Math.round(opacity * .6) : opacity}%, transparent)`;
+	return `color-mix(in oklch, ${scaleColor} ${steps === 1 ? 100 : Math.round(20 + (level - 1) * 80 / (steps - 1))}%, transparent)`;
 };
 const calculateLevel = (value, minValue, maxValue, levels, isNormalized) => {
 	const steps = colorStepCount(levels, isNormalized);
@@ -38,8 +40,22 @@ const generateWeekdayLabels = (locale) => {
 		return date.toLocaleString("en-US", { weekday: "short" });
 	});
 };
+/** How a signed day is drawn: its heat tint, the edge that carries its sign's colour, and whether it is round. */
+const signedMark = (value) => {
+	const known = Number.isFinite(value) ? value : 0;
+	return {
+		stroke: known > 0 ? "var(--positive)" : known < 0 ? "var(--negative)" : "var(--input)",
+		round: known < 0
+	};
+};
 const EMPTY_STYLE = {};
 const LABEL_MARGIN = 8;
+const WEEKDAY_LABEL_WIDTH = 40;
+const STROKE_PADDING = 3;
+const LEGEND_SWATCH = 12;
+const MIN_FITTED_BLOCK = 10;
+const MAX_FITTED_BLOCK = 20;
+const DEFAULT_BLOCK = 12;
 const CalendarHeatmapContext = createContext(null);
 const useCalendarHeatmap = () => {
 	const context = use(CalendarHeatmapContext);
@@ -131,26 +147,18 @@ const groupContinuous = (activities, weekStart = 0) => {
 	const padded = [...new Array(leadingPad).fill(void 0), ...normalizedActivities];
 	const numberOfWeeks = Math.ceil(padded.length / 7);
 	const allWeeks = new Array(numberOfWeeks).fill(void 0).map((_, i) => padded.slice(i * 7, i * 7 + 7));
-	const yearMap = /* @__PURE__ */ new Map();
-	for (const week of allWeeks) {
-		const firstActivity = week.find((a) => a !== void 0);
-		const year = firstActivity ? getYear(parseISO(firstActivity.date)) : void 0;
-		if (year !== void 0) {
-			if (!yearMap.has(year)) yearMap.set(year, []);
-			yearMap.get(year)?.push(week);
-		}
-	}
-	return Array.from(yearMap.entries()).sort(([a], [b]) => a - b).map(([year, weeks]) => ({
-		year,
+	return [{
+		year: getYear(firstDate),
 		startMonth: 0,
-		weeks
-	}));
+		weeks: allWeeks
+	}];
 };
-const getMonthLabels = (weeks, monthNames = generateMonthLabels()) => {
-	return weeks.reduce((labels, week, weekIndex) => {
+const getMonthLabels = (weeks, monthNames = generateMonthLabels(), yearTicks = false) => {
+	const ticks = weeks.reduce((labels, week, weekIndex) => {
 		const firstActivity = week.find((activity) => activity !== void 0);
 		if (!firstActivity) return labels;
-		const month = monthNames[getMonth(parseISO(firstActivity.date))];
+		const date = parseISO(firstActivity.date);
+		const month = monthNames[getMonth(date)];
 		if (!month) {
 			const monthName = new Date(firstActivity.date).toLocaleString("en-US", { month: "short" });
 			throw new Error(`Unexpected error: undefined month label for ${monthName}.`);
@@ -158,7 +166,8 @@ const getMonthLabels = (weeks, monthNames = generateMonthLabels()) => {
 		const prevLabel = labels.at(-1);
 		if (weekIndex === 0 || !prevLabel || prevLabel.label !== month) return labels.concat({
 			weekIndex,
-			label: month
+			label: month,
+			year: getMonth(date) === 0 ? getYear(date) : void 0
 		});
 		return labels;
 	}, []).filter(({ weekIndex }, index, labels) => {
@@ -167,6 +176,22 @@ const getMonthLabels = (weeks, monthNames = generateMonthLabels()) => {
 		if (index === labels.length - 1) return weeks.slice(weekIndex).length >= minWeeks;
 		return true;
 	});
+	if (!yearTicks) return ticks;
+	const hasJanuary = ticks.some(({ year }) => year !== void 0);
+	return ticks.map((tick, index) => {
+		if (tick.year !== void 0) return {
+			...tick,
+			label: String(tick.year)
+		};
+		if (index === 0 && !hasJanuary) {
+			const week = weeks[tick.weekIndex]?.find((activity) => activity !== void 0);
+			return week ? {
+				...tick,
+				label: `${tick.label} ${getYear(parseISO(week.date))}`
+			} : tick;
+		}
+		return tick;
+	});
 };
 /**
 * Calendar Heatmap
@@ -201,8 +226,9 @@ const getMonthLabels = (weeks, monthNames = generateMonthLabels()) => {
 * @param levels - Total number of legend cells (including empty when not normalized). Default: 5
 * @param isNormalized - When true, uses min-max normalization across the dataset (suitable for signed values). When false (default), treats 0 as empty and scales from 0 to max.
 */
-const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmptyColumn = false, blockSize = 12, blockMargin = 4, blockRadius = 2, blockAspectRatio = 1, levels: levelsProp = 5, isNormalized = false, colors, locale, labels: labelsProp, fontSize = 14, emptyState, totalCount: totalCountProp, style = EMPTY_STYLE, className, children, ...props }) => {
+const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmptyColumn = false, blockSize: blockSizeProp, blockMargin = 4, blockRadius = 2, blockAspectRatio = 1, levels: levelsProp = 5, isNormalized = false, signed = false, range, colors, locale, labels: labelsProp, fontSize = 14, emptyState, totalCount: totalCountProp, style = EMPTY_STYLE, className, children, ...props }) => {
 	const levels = Math.max(1, levelsProp);
+	const [rootRef, rootWidth] = useElementWidth();
 	const dataWithLevels = useMemo(() => {
 		if (data.length === 0) return [];
 		const maxCount = data.reduce((max, d) => Math.max(max, d.value), 1);
@@ -223,6 +249,15 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 		continuousMonths
 	]);
 	const weeks = useMemo(() => yearRows.flatMap((r) => r.weeks), [yearRows]);
+	const signedRange = useMemo(() => {
+		if (!signed) return null;
+		if (range !== void 0 && Number.isFinite(range) && range > 0) return range;
+		return Math.max(0, ...data.map((d) => Number.isFinite(d.value) ? Math.abs(d.value) : 0));
+	}, [
+		signed,
+		range,
+		data
+	]);
 	const labels = useMemo(() => ({
 		months: generateMonthLabels(locale),
 		weekdays: generateWeekdayLabels(locale),
@@ -235,6 +270,8 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 	const labelHeight = fontSize + LABEL_MARGIN;
 	const year = data.length > 0 ? getYear(parseISO(data[0].date)) : (/* @__PURE__ */ new Date()).getFullYear();
 	const totalCount = typeof totalCountProp === "number" ? totalCountProp : dataWithLevels.reduce((sum, activity) => sum + activity.value, 0);
+	const fitted = (rootWidth - WEEKDAY_LABEL_WIDTH - 6 + blockMargin) / Math.max(weeks.length, 1) - blockMargin;
+	const blockSize = blockSizeProp ?? (rootWidth > 0 ? Math.min(MAX_FITTED_BLOCK, Math.max(MIN_FITTED_BLOCK, fitted)) / blockAspectRatio : DEFAULT_BLOCK);
 	const blockWidth = blockSize * blockAspectRatio;
 	const width = weeks.length * (blockWidth + blockMargin) - blockMargin;
 	const height = labelHeight + (blockSize + blockMargin) * 7 - blockMargin;
@@ -260,7 +297,8 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 		hasEmptyColumn,
 		continuousMonths,
 		locale,
-		colors
+		colors,
+		signedRange
 	}), [
 		dataWithLevels,
 		weeks,
@@ -283,14 +321,16 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 		hasEmptyColumn,
 		continuousMonths,
 		locale,
-		colors
+		colors,
+		signedRange
 	]);
 	if (data.length === 0) return emptyState ? emptyState : null;
 	return /* @__PURE__ */ jsx(CalendarHeatmapContext, {
 		value: contextValue,
 		children: /* @__PURE__ */ jsx("div", {
+			ref: rootRef,
 			"data-slot": "calendar-heatmap",
-			className: cn("flex w-max max-w-full flex-col gap-2 p-4", className),
+			className: cn("flex flex-col gap-2", blockSizeProp === void 0 ? "w-full" : "w-max max-w-full", className),
 			style: {
 				fontSize,
 				...style
@@ -300,29 +340,34 @@ const CalendarHeatmap = ({ data, weekStart = 0, continuousMonths = true, hasEmpt
 		})
 	});
 };
-const CalendarHeatmapBlock = ({ ref, activity, dayIndex, weekIndex, highlighted = false, onCellClick, onCellHover, onClick, onKeyDown, onMouseEnter, onMouseLeave, className, style: styleProp, ...props }) => {
-	const { blockSize, blockWidth, blockMargin, blockRadius, labelHeight, labels, levels, isNormalized, colors } = useCalendarHeatmap();
+const CalendarHeatmapBlock = ({ ref, activity, dayIndex, weekIndex, highlighted = false, selected = false, onCellClick, onCellHover, onClick, onKeyDown, onMouseEnter, onMouseLeave, className, style: styleProp, ...props }) => {
+	const { blockSize, blockWidth, blockMargin, blockRadius, labelHeight, labels, levels, isNormalized, colors, signedRange } = useCalendarHeatmap();
 	const level = Math.max(0, Math.min(colorStepCount(levels, isNormalized), activity.level));
+	const mark = signedRange === null ? null : signedMark(activity.value);
 	const ariaLabel = (labels.cellLabel ?? "{{date}}: {{value}} contributions").replace("{{date}}", activity.date).replace("{{value}}", String(activity.value));
 	return /* @__PURE__ */ jsx("rect", {
 		ref,
 		"data-slot": "calendar-heatmap-block",
 		role: onCellClick ? "button" : "img",
+		"aria-pressed": onCellClick ? selected : void 0,
 		tabIndex: onCellClick ? 0 : -1,
 		"aria-label": ariaLabel,
-		className: cn("motion-safe:transition-opacity motion-safe:hover:opacity-70", onCellClick && "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", className),
+		className: cn("hover:stroke-foreground hover:stroke-1", highlighted && "stroke-foreground stroke-1", selected && "stroke-foreground stroke-2 hover:stroke-2", onCellClick && "cursor-pointer", className),
 		"data-value": activity.value,
 		"data-date": activity.date,
 		"data-level": level,
 		"data-highlighted": highlighted || void 0,
+		"data-selected": selected || void 0,
 		height: blockSize,
-		rx: blockRadius,
-		ry: blockRadius,
+		rx: mark?.round ? blockSize / 2 : blockRadius,
+		ry: mark?.round ? blockSize / 2 : blockRadius,
 		width: blockWidth,
+		stroke: mark?.stroke,
+		strokeWidth: mark ? 1 : void 0,
 		x: (blockWidth + blockMargin) * weekIndex,
 		y: labelHeight + (blockSize + blockMargin) * dayIndex,
 		style: {
-			fill: getLevelFill(level, levels, isNormalized, highlighted, colors),
+			fill: signedRange === null ? getLevelFill(level, levels, isNormalized, colors) : heat(activity.value, signedRange),
 			...styleProp
 		},
 		onClick: (event) => {
@@ -349,17 +394,18 @@ const CalendarHeatmapBlock = ({ ref, activity, dayIndex, weekIndex, highlighted
 };
 CalendarHeatmapBlock.displayName = "CalendarHeatmapBlock";
 const CalendarHeatmapBody = ({ hideMonthLabels = false, hideWeekdayLabels = false, hideYearLabels = false, className, labelClassName, yearClassName, children, renderYearFooter, ...props }) => {
-	const { yearRows, blockSize, blockWidth, blockMargin, labels, labelHeight, fontSize, weekStart, data } = useCalendarHeatmap();
-	const weekdayLabelWidth = hideWeekdayLabels ? 0 : 40;
-	const strokePadding = 3;
+	const navigation = useHeatmapNavigation();
+	const { yearRows, blockSize, blockWidth, blockMargin, labels, labelHeight, fontSize, weekStart, continuousMonths } = useCalendarHeatmap();
+	const weekdayLabelWidth = hideWeekdayLabels ? 0 : WEEKDAY_LABEL_WIDTH;
+	const strokePadding = STROKE_PADDING;
 	const rowData = useMemo(() => {
 		return yearRows.map((yearRow) => {
 			return {
 				yearRow,
 				width: yearRow.weeks.length * (blockWidth + blockMargin) - blockMargin,
 				height: labelHeight + (blockSize + blockMargin) * 7 - blockMargin,
-				monthLabels: getMonthLabels(yearRow.weeks, labels.months),
-				yearTotalCount: data.filter((activity) => getYear(parseISO(activity.date)) === yearRow.year).reduce((sum, activity) => sum + activity.value, 0)
+				monthLabels: getMonthLabels(yearRow.weeks, labels.months, continuousMonths),
+				yearTotalCount: yearRow.weeks.flat().reduce((sum, activity) => sum + (activity?.value ?? 0), 0)
 			};
 		});
 	}, [
@@ -369,15 +415,28 @@ const CalendarHeatmapBody = ({ hideMonthLabels = false, hideWeekdayLabels = fals
 		blockMargin,
 		labelHeight,
 		labels.months,
-		data
+		continuousMonths
 	]);
 	const totalWidth = weekdayLabelWidth + Math.max(...rowData.map((r) => r.width)) + 6;
+	const scroller = navigation.ref;
+	useLayoutEffect(() => {
+		if (continuousMonths && scroller.current) scroller.current.scrollLeft = scroller.current.scrollWidth;
+	}, [
+		continuousMonths,
+		scroller,
+		totalWidth
+	]);
 	return /* @__PURE__ */ jsx("div", {
 		"data-slot": "calendar-heatmap-body",
+		ref: navigation.ref,
 		className: cn("flex max-w-full flex-col gap-6 overflow-x-auto overflow-y-hidden py-4", className),
 		...props,
+		onKeyDown: (event) => {
+			props.onKeyDown?.(event);
+			if (!event.defaultPrevented) navigation.onKeyDown(event);
+		},
 		children: rowData.map(({ yearRow, height, monthLabels, yearTotalCount }) => /* @__PURE__ */ jsxs("div", { children: [
-			!hideYearLabels && /* @__PURE__ */ jsx("div", {
+			!hideYearLabels && !continuousMonths && /* @__PURE__ */ jsx("div", {
 				className: cn("mb-2 text-muted-foreground", yearClassName),
 				children: yearRow.year
 			}),
@@ -457,8 +516,14 @@ const CalendarHeatmapStat = ({ compute, label, className, children, ...props })
 		children: template.replace("{{value}}", String(value)).replace("{{year}}", String(year))
 	});
 };
-const CalendarHeatmapLegend = ({ labels: labelsProp, className, children, ...props }) => {
-	const { levels, isNormalized, blockSize, blockWidth, blockRadius, colors, labels } = useCalendarHeatmap();
+const CalendarHeatmapLegend = ({ labels: labelsProp, valueFormatter, className, children, ...props }) => {
+	const { levels, isNormalized, blockRadius, colors, labels, signedRange } = useCalendarHeatmap();
+	if (signedRange !== null) return /* @__PURE__ */ jsx(SignedLegend, {
+		labels: labelsProp,
+		valueFormatter,
+		className,
+		...props
+	});
 	const lessLabel = labelsProp?.less ?? "Less";
 	const moreLabel = labelsProp?.more ?? "More";
 	const legendLevels = Array.from({ length: levels }, (_, i) => isNormalized ? i + 1 : i);
@@ -475,15 +540,15 @@ const CalendarHeatmapLegend = ({ labels: labelsProp, className, children, ...pro
 			legendLevels.map((level) => children ? /* @__PURE__ */ jsx(Fragment$1, { children: children({ level }) }, `legend-level-${level}`) : /* @__PURE__ */ jsx("svg", {
 				role: "img",
 				"aria-label": (labels.legendLevelLabel ?? "{{level}} contributions").replace("{{level}}", String(level)),
-				height: blockSize,
-				width: blockWidth,
+				height: LEGEND_SWATCH,
+				width: LEGEND_SWATCH,
 				children: /* @__PURE__ */ jsx("rect", {
 					"data-level": level,
-					height: blockSize,
+					height: LEGEND_SWATCH,
 					rx: blockRadius,
 					ry: blockRadius,
-					width: blockWidth,
-					style: { fill: getLevelFill(level, levels, isNormalized, false, colors) }
+					width: LEGEND_SWATCH,
+					style: { fill: getLevelFill(level, levels, isNormalized, colors) }
 				})
 			}, `legend-level-${level}`)),
 			/* @__PURE__ */ jsx("span", {
@@ -493,5 +558,59 @@ const CalendarHeatmapLegend = ({ labels: labelsProp, className, children, ...pro
 		]
 	});
 };
+/** A signed heatmap's scale: round loss steps deepest first, no change, square gain steps, and what they span. */
+const SignedLegend = ({ labels: labelsProp, valueFormatter = String, className, ...props }) => {
+	const { blockRadius, labels, signedRange } = useCalendarHeatmap();
+	const steps = Array.from({ length: 5 }, (_, i) => i + 1);
+	const swatch = (key, fill, value) => {
+		const { stroke, round } = signedMark(value);
+		const corner = round ? 11 / 2 : blockRadius;
+		return /* @__PURE__ */ jsx("svg", {
+			"aria-hidden": "true",
+			height: LEGEND_SWATCH,
+			width: LEGEND_SWATCH,
+			children: /* @__PURE__ */ jsx("rect", {
+				x: .5,
+				y: .5,
+				height: 11,
+				width: 11,
+				rx: corner,
+				ry: corner,
+				stroke,
+				style: { fill }
+			})
+		}, key);
+	};
+	return /* @__PURE__ */ jsxs("fieldset", {
+		"data-slot": "calendar-heatmap-legend",
+		"aria-label": labels.legendLabel ?? "Activity intensity legend",
+		className: cn("ml-auto flex flex-col items-end gap-1 text-muted-foreground", className),
+		...props,
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-center gap-1",
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					className: "mr-1 font-medium text-xs",
+					children: labelsProp?.less ?? "Loss"
+				}),
+				steps.toReversed().map((step) => swatch(`loss-${step}`, heatFill("negative", step), -1)),
+				swatch("none", heat(null), 0),
+				steps.map((step) => swatch(`gain-${step}`, heatFill("positive", step), 1)),
+				/* @__PURE__ */ jsx("span", {
+					className: "ml-1 font-medium text-xs",
+					children: labelsProp?.more ?? "Gain"
+				})
+			]
+		}), /* @__PURE__ */ jsxs("p", {
+			"data-slot": "calendar-heatmap-legend-scale",
+			className: "text-xs",
+			children: [
+				"Deepest at ±",
+				valueFormatter(signedRange ?? 0),
+				". Round days lost, square days gained; grey days had no change."
+			]
+		})]
+	});
+};
 //#endregion
 export { CalendarHeatmap, CalendarHeatmapBlock, CalendarHeatmapBody, CalendarHeatmapFooter, CalendarHeatmapLegend, CalendarHeatmapStat };

package/dist/components/registry/heatmap/status-heatmap.d.ts

@@ -69,11 +69,13 @@ export type StatusHeatmapProps = HTMLAttributes<HTMLDivElement> & {
  *
  * @param data - Array of activities with date (YYYY-MM-DD) and status value (0-3)
  * @param dateFormat - Date format string for tooltips. Default: "MMM d"
- * @param blockAspectRatio - Width/height ratio of blocks. Default: 0.2 (narrow vertical bars)
+ * @param blockAspectRatio - Width/height ratio of blocks. Default: bars share the full width
  * @param colors - Custom colors for critical, degraded, and healthy states
  */
-export declare const StatusHeatmap: ({ data, dateFormat, blockSize, blockMargin, blockRadius, blockAspectRatio, colors, locale, labels: labelsProp, fontSize, emptyState, statusValues, healthyValue, style, className, children, ...props }: StatusHeatmapProps) => string | number | bigint | true | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null;
+export declare const StatusHeatmap: ({ data, dateFormat, blockSize, blockMargin, blockRadius, blockAspectRatio: blockAspectRatioProp, colors, locale, labels: labelsProp, fontSize, emptyState, statusValues, healthyValue, style, className, children, ...props }: StatusHeatmapProps) => string | number | bigint | true | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null;
 export type StatusHeatmapBlockProps = HTMLAttributes<SVGRectElement> & {
+  /** The cell the page has picked: drawn with a ring and announced as pressed. */
+  selected?: boolean;
   activity: StatusActivity;
   dayIndex: number;
   highlighted?: boolean;
@@ -81,7 +83,7 @@ export type StatusHeatmapBlockProps = HTMLAttributes<SVGRectElement> & {
   onCellHover?: (activity: StatusActivity | null) => void;
   className?: string;
 };
-export declare function StatusHeatmapBlock({ ref, activity, dayIndex, highlighted, onCellClick, onCellHover, onClick, onKeyDown, onMouseEnter, onMouseLeave, className, style: styleProp, ...props }: StatusHeatmapBlockProps & {
+export declare function StatusHeatmapBlock({ ref, activity, dayIndex, highlighted, selected, onCellClick, onCellHover, onClick, onKeyDown, onMouseEnter, onMouseLeave, className, style: styleProp, ...props }: StatusHeatmapBlockProps & {
   ref?: React.RefObject<SVGRectElement | null>;
 }): import("react").JSX.Element;
 export declare namespace StatusHeatmapBlock {