@flikk/ui 1.0.0-beta.30 → 1.0.0-beta.32

package/dist/components/charts/Heatmap/Heatmap.js

@@ -1,21 +1,24 @@
 "use client";
-import { jsxs, jsx } from 'react/jsx-runtime';
-import { useRef, useMemo } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { useRef, useId, useMemo } from 'react';
 import { motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { useTooltipPosition } from '../hooks/useTooltipPosition.js';
 import { useOptionalChart } from '../ChartContainer.js';
-import { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
+import { ChartTooltip } from '../../core/shared/ChartTooltip/ChartTooltip.js';
 import { HeatmapCell } from './HeatmapCell.js';
 import { processHeatmapData, createGridMatrix, calculateIntensity, getDefaultTooltipContent } from './utils/heatmapUtils.js';
 import { HeatmapLegend } from './HeatmapLegend.js';
 import { heatmapTheme } from './Heatmap.theme.js';
+import { HEATMAP_CELL_FADE_DURATION, heatmapCellDelay } from '../utils/animation-utils.js';
+import { useMediaQuery } from '../../../hooks/useMediaQuery.js';
 
 /**
  * Heatmap component for visualizing data in a grid format with color intensity
  * Supports weekly, monthly, hourly views and custom data structures
  */
-const Heatmap = ({ data: dataProp, config: configProp, color = 'primary', colorScale = { steps: 10, minOpacity: 0.1 }, layout = { gap: 6 }, axis = { showXAxis: true, showYAxis: true }, tooltip = { enabled: true }, legend = { enabled: true }, valueRange, onCellClick, cellRenderer, className, variant = 'default', children, ...props }) => {
+const Heatmap = ({ data: dataProp, config: configProp, color = 'primary', variant = 'default', showXAxis = true, showYAxis = true, xAxisFormatter, yAxisFormatter, legend = 'bottom', legendLabels, minValue: minValueProp, maxValue: maxValueProp, cellGap = 6, minOpacity = 0.1, showTooltip = true, tooltipFormatter, onCellClick, cellRenderer, className, width, height, title, description, children, }) => {
+    var _a;
     // Get data and config from context if not provided as props. `data`/`config`
     // are documented as directly-passable — Heatmap must also work standalone,
     // with no wrapping <ChartContainer>, so the context read is optional here
@@ -24,18 +27,20 @@ const Heatmap = ({ data: dataProp, config: configProp, color = 'primary', colorS
     const data = dataProp || (chartContext === null || chartContext === void 0 ? void 0 : chartContext.data) || [];
     const config = configProp || (chartContext === null || chartContext === void 0 ? void 0 : chartContext.config) || {};
     const containerRef = useRef(null);
-    // Detect if device is mobile/touch
-    const isMobile = typeof window !== 'undefined' &&
-        ('ontouchstart' in window || navigator.maxTouchPoints > 0);
+    // §11: no window access in the render body. A coarse pointer is the touch signal.
+    const isMobile = useMediaQuery('(pointer: coarse)');
     // Use the new tooltip positioning hook
     const { tooltipData, tooltipRef, handleMouseEnter, handleMouseMove, handleMouseLeave, } = useTooltipPosition({
         containerRef,
         isMobile,
     });
+    const descriptionId = useId();
+    const xAxisDescriptionId = useId();
+    const yAxisDescriptionId = useId();
     // Process data
     const processedData = useMemo(() => {
-        return processHeatmapData(data, valueRange);
-    }, [data, valueRange]);
+        return processHeatmapData(data, minValueProp, maxValueProp);
+    }, [data, minValueProp, maxValueProp]);
     const { xCategories, yCategories, minValue, maxValue } = processedData;
     // Create grid matrix
     const gridMatrix = useMemo(() => {
@@ -62,24 +67,22 @@ const Heatmap = ({ data: dataProp, config: configProp, color = 'primary', colorS
         return `var(--color-${color})`;
     };
     const cellColor = getCellColor();
-    // Handle cell hover using new tooltip system
-    const handleCellHover = (data, event) => {
-        if (!tooltip.enabled)
+    const seriesLabel = (_a = config === null || config === void 0 ? void 0 : config.value) === null || _a === void 0 ? void 0 : _a.label;
+    const handleCellHover = (cell, event) => {
+        if (!showTooltip)
             return;
-        const content = tooltip.formatter
-            ? tooltip.formatter(data)
-            : getDefaultTooltipContent(data);
+        const content = tooltipFormatter
+            ? tooltipFormatter(cell)
+            : getDefaultTooltipContent(cell, seriesLabel);
         handleMouseEnter(event, content);
     };
-    // Handle cell mouse move using new tooltip system
-    const handleCellMouseMove = (data, event) => {
-        if (!tooltip.enabled || !tooltipData)
+    const handleCellMouseMove = (_cell, event) => {
+        if (!showTooltip || !tooltipData)
             return;
         handleMouseMove(event);
     };
-    // Handle cell leave using new tooltip system
     const handleCellLeave = () => {
-        if (!tooltip.enabled)
+        if (!showTooltip)
             return;
         handleMouseLeave();
     };
@@ -88,38 +91,42 @@ const Heatmap = ({ data: dataProp, config: configProp, color = 'primary', colorS
         display: 'grid',
         gridTemplateColumns: `repeat(${xCategories.length}, 1fr)`,
         gridTemplateRows: `repeat(${yCategories.length}, 1fr)`,
-        gap: typeof layout.gap === 'number' ? `${layout.gap}px` : layout.gap,
+        gap: typeof cellGap === 'number' ? `${cellGap}px` : cellGap,
         width: '100%',
         height: '100%',
     };
     // Render axis labels - using theme for base styles
     const renderXAxisLabels = () => {
-        if (!axis.showXAxis)
+        if (!showXAxis)
             return null;
-        return (jsxs("div", { className: cn("flex justify-between items-center px-1 py-2", heatmapTheme.axisLabelStyle), style: { gridColumn: `1 / -1` }, role: xCategories.length > 0 ? "list" : undefined, "aria-label": "X-axis labels", "aria-describedby": "heatmap-x-axis-description", children: [xCategories.map((category, index) => (jsx("div", { className: "flex-1 text-center px-1", style: {
-                        transform: axis.xAxisRotation ? `rotate(${axis.xAxisRotation}deg)` : undefined
-                    }, role: "listitem", "aria-label": `X-axis label: ${axis.xAxisFormatter
-                        ? axis.xAxisFormatter(category, index)
-                        : String(category)}`, children: axis.xAxisFormatter
-                        ? axis.xAxisFormatter(category, index)
-                        : String(category) }, category))), jsxs("span", { id: "heatmap-x-axis-description", className: "sr-only", children: ["X-axis contains ", xCategories.length, " categories representing the horizontal dimension of the heatmap"] })] }));
+        return (jsxs("div", { className: cn("flex justify-between items-center px-1 py-2", heatmapTheme.axisLabelStyle), style: { gridColumn: `1 / -1` }, role: xCategories.length > 0 ? "list" : undefined, "aria-label": "X-axis labels", "aria-describedby": xAxisDescriptionId, children: [xCategories.map((category, index) => {
+                    const label = xAxisFormatter ? xAxisFormatter(category, index) : String(category);
+                    return (jsx("div", { className: "flex-1 text-center px-1", role: "listitem", "aria-label": `X-axis label: ${label}`, children: label }, category));
+                }), jsxs("span", { id: xAxisDescriptionId, className: "sr-only", children: ["X-axis contains ", xCategories.length, " categories representing the horizontal dimension of the heatmap"] })] }));
     };
     const renderYAxisLabels = () => {
-        if (!axis.showYAxis)
+        if (!showYAxis)
             return null;
         return (jsxs("div", { className: cn("grid pr-3", heatmapTheme.axisLabelStyle), style: {
                 gridTemplateRows: `repeat(${yCategories.length}, 1fr)`,
-                gap: typeof layout.gap === 'number' ? `${layout.gap}px` : layout.gap,
+                gap: typeof cellGap === 'number' ? `${cellGap}px` : cellGap,
                 height: '100%',
-            }, role: yCategories.length > 0 ? "list" : undefined, "aria-label": "Y-axis labels", "aria-describedby": "heatmap-y-axis-description", children: [yCategories.map((category, index) => (jsx("div", { className: "flex items-center justify-end", style: {
-                        transform: axis.yAxisRotation ? `rotate(${axis.yAxisRotation}deg)` : undefined
-                    }, role: "listitem", "aria-label": `Y-axis label: ${axis.yAxisFormatter
-                        ? axis.yAxisFormatter(category, index)
-                        : String(category)}`, children: axis.yAxisFormatter
-                        ? axis.yAxisFormatter(category, index)
-                        : String(category) }, category))), jsxs("span", { id: "heatmap-y-axis-description", className: "sr-only", children: ["Y-axis contains ", yCategories.length, " categories representing the vertical dimension of the heatmap"] })] }));
+            }, role: yCategories.length > 0 ? "list" : undefined, "aria-label": "Y-axis labels", "aria-describedby": yAxisDescriptionId, children: [yCategories.map((category, index) => {
+                    const label = yAxisFormatter ? yAxisFormatter(category, index) : String(category);
+                    return (jsx("div", { className: "flex items-center justify-end", role: "listitem", "aria-label": `Y-axis label: ${label}`, children: label }, category));
+                }), jsxs("span", { id: yAxisDescriptionId, className: "sr-only", children: ["Y-axis contains ", yCategories.length, " categories representing the vertical dimension of the heatmap"] })] }));
     };
-    return (jsxs("div", { ref: containerRef, className: cn(heatmapTheme.containerStyle, variant === 'bordered' && 'border border-gray-200 dark:border-gray-700 rounded-lg p-4', variant === 'minimal' && 'p-2', className), ...props, children: [jsxs("div", { className: "flex flex-1 min-h-0", children: [axis.showYAxis && (jsxs("div", { className: "flex-shrink-0 w-16 flex flex-col", children: [axis.showXAxis && jsx("div", { className: "flex-shrink-0 h-8" }), jsx("div", { className: "flex-1", children: renderYAxisLabels() })] })), jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [axis.showXAxis && (jsx("div", { className: "flex-shrink-0 h-8", children: renderXAxisLabels() })), jsx("div", { className: "flex-1 relative min-h-0", children: jsx(motion.div, { style: gridStyles, initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: 0.5, ease: 'easeOut' }, className: heatmapTheme.gridStyle, role: "grid", "aria-label": `Heatmap grid, ${yCategories.length} rows by ${xCategories.length} columns`, children: gridMatrix.map((rowCells, rowIndex) => (
+    const legendNode = legend !== 'none' ? (jsx("div", { className: "flex-shrink-0", children: jsx(HeatmapLegend, { color: cellColor, labels: legendLabels, 
+            // heatmapTheme.legendStyle's `mt-3` assumes the legend sits below the
+            // grid (the default, bottom position). Above the grid, that top
+            // margin is backwards — cancel it and add the matching bottom margin
+            // instead so the gap is always between the legend and the grid, not
+            // duplicated on one side and missing on the other.
+            className: legend === 'top' ? 'mt-0 mb-3' : undefined }) })) : null;
+    return (jsxs("div", { ref: containerRef, className: cn(heatmapTheme.containerStyle, heatmapTheme.variants[variant], className), style: {
+            width: width !== undefined ? (typeof width === 'number' ? `${width}px` : width) : undefined,
+            height: height !== undefined ? (typeof height === 'number' ? `${height}px` : height) : undefined,
+        }, children: [legend === 'top' && legendNode, jsxs("div", { className: "flex flex-1 min-h-0", children: [showYAxis && (jsxs("div", { className: "flex-shrink-0 w-16 flex flex-col", children: [showXAxis && jsx("div", { className: "flex-shrink-0 h-8" }), jsx("div", { className: "flex-1", children: renderYAxisLabels() })] })), jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [showXAxis && (jsx("div", { className: "flex-shrink-0 h-8", children: renderXAxisLabels() })), jsx("div", { className: "flex-1 relative min-h-0", children: jsx(motion.div, { style: gridStyles, initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: HEATMAP_CELL_FADE_DURATION, ease: 'easeOut' }, className: heatmapTheme.gridStyle, role: "grid", "aria-label": title !== null && title !== void 0 ? title : `Heatmap grid, ${yCategories.length} rows by ${xCategories.length} columns`, "aria-describedby": description ? descriptionId : undefined, children: gridMatrix.map((rowCells, rowIndex) => (
                                     // `role="row"` groups each grid-matrix row for ARIA purposes
                                     // (satisfies aria-required-parent on the gridcells below and
                                     // aria-required-children on the grid above) without affecting
@@ -131,11 +138,11 @@ const Heatmap = ({ data: dataProp, config: configProp, color = 'primary', colorS
                                             const index = rowIndex * rowCells.length + colIndex;
                                             // Skip null values entirely
                                             if (cellData.value === null) {
-                                                return (jsx("div", { className: "bg-transparent" }, `${cellData.x}-${cellData.y}-${index}`));
+                                                return (jsx("div", { className: heatmapTheme.cellNullStyle }, `${cellData.x}-${cellData.y}-${index}`));
                                             }
                                             const CellComponent = cellRenderer || HeatmapCell;
-                                            return (jsx(CellComponent, { data: cellData, intensity: intensity, minOpacity: colorScale === null || colorScale === void 0 ? void 0 : colorScale.minOpacity, color: cellColor, onClick: onCellClick, onHover: handleCellHover, onMouseMove: handleCellMouseMove, onLeave: handleCellLeave, className: "rounded-sm" }, `${cellData.x}-${cellData.y}-${index}`));
-                                        }) }, `row-${rowIndex}`))) }) })] })] }), ((legend === null || legend === void 0 ? void 0 : legend.enabled) !== false) && (jsx("div", { className: "flex-shrink-0 mt-2", children: jsx(HeatmapLegend, { colorKey: "value", color: cellColor, minValue: minValue, maxValue: maxValue, labels: legend === null || legend === void 0 ? void 0 : legend.labels }) })), tooltip.enabled && (jsx(ChartTooltip, { content: tooltipData === null || tooltipData === void 0 ? void 0 : tooltipData.content, active: !!tooltipData, position: tooltipData ? { x: tooltipData.x, y: tooltipData.y } : { x: 0, y: 0 }, tooltipRef: tooltipRef })), children] }));
+                                            return (jsx(CellComponent, { data: cellData, intensity: intensity, minOpacity: minOpacity, color: cellColor, delay: heatmapCellDelay(rowIndex, colIndex), onClick: onCellClick, onHover: handleCellHover, onMouseMove: handleCellMouseMove, onLeave: handleCellLeave }, `${cellData.x}-${cellData.y}-${index}`));
+                                        }) }, `row-${rowIndex}`))) }) })] })] }), legend === 'bottom' && legendNode, showTooltip && (jsx(ChartTooltip, { content: tooltipData === null || tooltipData === void 0 ? void 0 : tooltipData.content, active: !!tooltipData, position: tooltipData ? { x: tooltipData.x, y: tooltipData.y } : { x: 0, y: 0 }, tooltipRef: tooltipRef })), description && (jsx("span", { id: descriptionId, className: "sr-only", children: description })), children] }));
 };
 
 export { Heatmap };

package/dist/components/charts/Heatmap/Heatmap.theme.d.ts

@@ -1,11 +1,15 @@
 /**
- * Heatmap theme configuration
- * Uses production-ready CSS variables from global.scss
+ * Heatmap theme configuration.
+ * CSS variables only (CLAUDE.md §3) — no raw Tailwind greys.
  */
+import type { HeatmapVariant } from "./Heatmap.types";
 export interface HeatmapTheme {
     containerStyle: string;
+    variants: Record<HeatmapVariant, string>;
     gridStyle: string;
     cellBaseStyle: string;
+    cellNullStyle: string;
+    cellOverlayStyle: string;
     axisLabelStyle: string;
     legendStyle: string;
 }

package/dist/components/charts/Heatmap/Heatmap.theme.js

@@ -1,17 +1,29 @@
 /**
- * Heatmap theme configuration
- * Uses production-ready CSS variables from global.scss
+ * Heatmap theme configuration.
+ * CSS variables only (CLAUDE.md §3) — no raw Tailwind greys.
  */
 const heatmapTheme = {
-    // Container with variants handled inline
     containerStyle: "relative w-full h-full min-h-[200px] flex flex-col",
-    // Grid container (applied via inline styles for CSS Grid)
+    // `default` adds nothing; `minimal` tightens the frame.
+    variants: {
+        default: "",
+        minimal: "p-2",
+    },
+    // Grid container (CSS Grid template comes from inline styles).
     gridStyle: "absolute inset-0",
-    // Base cell styles (individual cells add opacity via inline styles)
-    cellBaseStyle: "relative w-full h-full cursor-pointer border border-transparent transition-all duration-500 animate-[flicker_0.6s_ease-out_forwards]",
-    // Axis labels using CSS variables for dark mode support
+    // Cells: motion owns opacity and transform, so the CSS transition lists
+    // background-color only — a `transition-all` here re-interpolates the
+    // hover/tap scale every frame (CLAUDE.md §12).
+    cellBaseStyle: "relative w-full h-full rounded-sm border border-transparent transition-[background-color] duration-[var(--motion-duration-fast)]",
+    // Missing data: a hairline well, never a painted cell. `border` supplies the
+    // width — `border-[var(--color-border)]` alone only sets border-color, and
+    // Tailwind's preflight zeroes border-width by default, so without it this
+    // painted nothing (this style is applied standalone by the parent's null
+    // branch, not merged with cellBaseStyle's own `border` utility).
+    cellNullStyle: "bg-transparent border border-[var(--color-border)]",
+    // Optional content rendered inside a cell.
+    cellOverlayStyle: "absolute inset-0 flex items-center justify-center text-sm font-medium text-[var(--color-text-primary)]",
     axisLabelStyle: "text-xs text-[var(--color-text-secondary)] font-medium select-none",
-    // Legend using correct CSS variables
     legendStyle: "w-full space-y-1.5 mt-3",
 };
 

package/dist/components/charts/Heatmap/Heatmap.types.d.ts

@@ -1,9 +1,8 @@
 import { ReactNode } from 'react';
-import { BaseChartProps, ChartConfig } from '../types/chart.types';
-/**
- * Semantic color options for the heatmap
- */
-export type SemanticColor = 'primary' | 'success' | 'warning' | 'danger';
+import { BaseChartProps, ChartConfig, ChartLegendPosition, StandardChartDisplayProps } from '../types/chart.types';
+import type { SemanticColor } from '../../../utils/colorUtils';
+/** Heatmap has no gradient fill, so it narrows the family's ChartVariant. */
+export type HeatmapVariant = 'default' | 'minimal';
 /**
  * Heatmap data point structure
  * @property {string | number} x - X-axis category (e.g., day, month, hour)
@@ -25,6 +24,8 @@ export interface HeatmapCellProps {
     intensity: number;
     minOpacity?: number;
     color?: string;
+    /** Entrance delay in seconds, computed by the parent from the cell's grid position */
+    delay?: number;
     className?: string;
     onClick?: (data: HeatmapDataPoint) => void;
     onHover?: (data: HeatmapDataPoint, event: React.MouseEvent) => void;
@@ -33,93 +34,59 @@ export interface HeatmapCellProps {
     children?: ReactNode;
 }
 /**
- * Color scale configuration
- */
-export interface HeatmapColorScale {
-    /** Custom color steps from light to dark */
-    colors?: string[];
-    /** Number of color steps (default: 10) */
-    steps?: number;
-    /** Minimum opacity for null/zero values */
-    minOpacity?: number;
-}
-/**
- * Heatmap layout configuration
- */
-export interface HeatmapLayout {
-    /** Gap between cells */
-    gap?: number | string;
-}
-/**
- * Heatmap axis configuration
+ * 🔴 `Pick` of StandardChartDisplayProps, never `extends` — see the rule on
+ * StandardVisualProps in chart.types.ts. `showGrid`/`theme` are meaningless
+ * here and `variant` is narrowed below, so none of the three are picked.
+ *
+ * `enableKeyboardNavigation` is omitted from BaseChartProps: the grid has no
+ * arrow-key roving navigation, so advertising the prop would promise behaviour
+ * the component doesn't have — exactly the failure mode that rule describes.
+ * (Individual cells remain Enter/Space activatable via native `tabIndex`/
+ * `onKeyDown` when `onCellClick` is set — that part is unrelated to this prop,
+ * which is specifically about grid-level arrow-key navigation.)
  */
-export interface HeatmapAxisConfig {
-    /** Show X-axis labels */
-    showXAxis?: boolean;
-    /** Show Y-axis labels */
-    showYAxis?: boolean;
+export interface HeatmapProps extends Omit<BaseChartProps, 'data' | 'config' | 'enableKeyboardNavigation'>, Pick<StandardChartDisplayProps, 'showXAxis' | 'showYAxis' | 'minValue' | 'maxValue'> {
+    /**
+     * Colour-ramp legend position. Same union as every other chart, but redeclared
+     * rather than picked so it carries Heatmap's own documentation: this legend is
+     * a continuous ramp (see HeatmapLegend), not the series swatches `config`
+     * drives elsewhere, and it defaults to `'bottom'` rather than resolving to
+     * `'none'` for a single-series config — the ramp IS a heatmap's value key.
+     * @default 'bottom'
+     */
+    legend?: ChartLegendPosition;
+    /** Heatmap data array — optional when using ChartContainer context */
+    data?: HeatmapDataPoint[];
+    /** Chart configuration — optional when using ChartContainer context */
+    config?: ChartConfig;
+    /** Semantic colour for heatmap cells @default 'primary' */
+    color?: SemanticColor;
+    /** Visual variant @default 'default' */
+    variant?: HeatmapVariant;
     /** X-axis label formatter */
     xAxisFormatter?: (value: string | number, index: number) => string;
     /** Y-axis label formatter */
     yAxisFormatter?: (value: string | number, index: number) => string;
-    /** X-axis label rotation */
-    xAxisRotation?: number;
-    /** Y-axis label rotation */
-    yAxisRotation?: number;
-}
-/**
- * Heatmap tooltip configuration
- */
-export interface HeatmapTooltipConfig {
-    /** Show tooltip on hover */
-    enabled?: boolean;
-    /** Custom tooltip formatter */
-    formatter?: (data: HeatmapDataPoint) => ReactNode;
-    /** Tooltip delay in ms */
-    delay?: number;
-}
-/**
- * Heatmap legend configuration
- */
-export interface HeatmapLegendConfig {
-    /** Show legend */
-    enabled?: boolean;
-    /** Custom labels for min and max values */
-    labels?: {
+    /**
+     * Captions at each end of the colour ramp.
+     * @default { min: 'Low activity', max: 'High activity' }
+     */
+    legendLabels?: {
         min?: string;
         max?: string;
     };
-}
-/**
- * Main Heatmap component props
- */
-export interface HeatmapProps extends Omit<BaseChartProps, 'data' | 'config' | 'variant' | 'theme'> {
-    /** Heatmap data array - optional when using ChartContainer context */
-    data?: HeatmapDataPoint[];
-    /** Chart configuration - optional when using ChartContainer context */
-    config?: ChartConfig;
-    /** Semantic color for heatmap cells (primary, success, warning, danger) */
-    color?: SemanticColor;
-    /** Color scale configuration */
-    colorScale?: HeatmapColorScale;
-    /** Layout configuration */
-    layout?: HeatmapLayout;
-    /** Axis configuration */
-    axis?: HeatmapAxisConfig;
-    /** Tooltip configuration */
-    tooltip?: HeatmapTooltipConfig;
-    /** Legend configuration */
-    legend?: HeatmapLegendConfig;
-    /** Custom value range [min, max] - if not provided, will be calculated from data */
-    valueRange?: [number, number];
-    /** Cell click handler */
-    onCellClick?: (data: HeatmapDataPoint) => void;
+    /** Gap between cells @default 6 */
+    cellGap?: number | string;
+    /** Opacity floor for zero/lowest-intensity cells @default 0.1 */
+    minOpacity?: number;
     /** Custom cell renderer */
     cellRenderer?: (props: HeatmapCellProps) => ReactNode;
-    /** Additional CSS classes */
-    className?: string;
-    /** Chart variant */
-    variant?: 'default' | 'minimal' | 'bordered';
+    /** Cell click handler */
+    onCellClick?: (data: HeatmapDataPoint) => void;
+    /** Show the hover tooltip @default true */
+    showTooltip?: boolean;
+    /** Custom tooltip content */
+    tooltipFormatter?: (data: HeatmapDataPoint) => ReactNode;
 }
 /**
  * Processed heatmap data with calculated values

package/dist/components/charts/Heatmap/HeatmapCell.js

@@ -1,95 +1,44 @@
 "use client";
 import { jsx } from 'react/jsx-runtime';
-import React__default, { useRef } from 'react';
-import { motion } from 'motion/react';
+import React__default from 'react';
+import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { heatmapTheme } from './Heatmap.theme.js';
+import { HEATMAP_CELL_TAP_TRANSITION, HEATMAP_CELL_HOVER_TRANSITION, HEATMAP_CELL_FADE_DURATION } from '../utils/animation-utils.js';
 
 /**
- * Individual heatmap cell component with hover animations and color intensity
+ * Individual heatmap cell — colour intensity plus a deterministic fade-in.
+ *
+ * The resting opacity is the animation target (not an inline style), so motion
+ * owns it end to end; `data-intensity-opacity` publishes the resolved value for
+ * consumers and tests.
  */
-const HeatmapCellInner = ({ data, intensity, minOpacity = 0.1, color = 'var(--color-primary)', // Default to primary color (correct CSS variable)
-className, onClick, onHover, onMouseMove, onLeave, children, }) => {
-    // Calculate cell color and opacity based on intensity
-    const getColorStyle = (intensity) => {
-        // Only return empty object for null values (will use CSS class)
-        if (data.value === null) {
-            return {};
-        }
-        // Calculate base opacity from intensity
-        let baseOpacity;
-        // For 0 values, use minOpacity
-        if (data.value === 0) {
-            baseOpacity = minOpacity;
-        }
-        else {
-            // Map intensity (0-1) to opacity levels (minOpacity-1.0) in 10% increments
-            const opacityStep = Math.ceil(intensity * 10) / 10; // Round up to nearest 10%
-            baseOpacity = Math.max(minOpacity, Math.min(1.0, opacityStep));
-        }
-        // Use the passed color prop with calculated opacity
-        return {
-            backgroundColor: color,
-            opacity: baseOpacity
-        };
-    };
-    const getColorClass = (intensity) => {
-        // Only use gray colors for null values (missing data)
-        if (data.value === null) {
-            return 'bg-transparent border border-gray-200/80';
-        }
-        // For non-null values, we'll use inline styles
-        return '';
-    };
-    const handleClick = () => {
-        if (onClick) {
-            onClick(data);
-        }
-    };
-    const handleMouseEnter = (event) => {
-        if (onHover) {
-            onHover(data, event);
-        }
-    };
-    const handleMouseMove = (event) => {
-        if (onMouseMove) {
-            onMouseMove(data, event);
-        }
-    };
-    const handleMouseLeave = () => {
-        if (onLeave) {
-            onLeave();
-        }
-    };
-    const handleAnimationEnd = () => {
-        // Remove animation class after flicker completes to prevent interference with opacity
-        if (containerRef.current) {
-            containerRef.current.classList.remove('animate-[flicker_0.6s_ease-out_forwards]');
-        }
-    };
-    const containerRef = useRef(null);
-    const flickerDelayRef = useRef(`${Math.random() * 0.3}s`);
-    return (jsx(motion.div, { ref: containerRef, className: cn(heatmapTheme.cellBaseStyle, getColorClass(), onClick && 'cursor-pointer', className), style: {
-            ...getColorStyle(intensity),
-            // CSS custom properties for the animation
-            '--flicker-delay': flickerDelayRef.current,
-            animationDelay: `var(--flicker-delay)`,
-        }, onAnimationEnd: handleAnimationEnd, onClick: handleClick, onMouseEnter: handleMouseEnter, onMouseMove: handleMouseMove, onMouseLeave: handleMouseLeave, 
-        // Framer Motion animations (just for hover/tap, not initial load)
-        whileHover: {
-            scale: 1.025,
-            transition: { duration: 0.15, ease: 'easeOut' }
-        }, whileTap: {
-            scale: 0.95,
-            transition: { duration: 0.1, ease: 'easeOut' }
-        }, 
-        // Accessibility
-        role: "gridcell", tabIndex: onClick ? 0 : -1, "aria-label": `Value: ${data.value}, X: ${data.x}, Y: ${data.y}`, onKeyDown: (e) => {
+const HeatmapCellInner = ({ data, intensity, minOpacity = 0.1, color = 'var(--color-primary)', delay = 0, className, onClick, onHover, onMouseMove, onLeave, children, }) => {
+    const shouldReduceMotion = useReducedMotion();
+    const isNull = data.value === null;
+    // Map intensity (0-1) onto [minOpacity, 1] in 10% steps; a 0 value pins to
+    // minOpacity so an empty cell still reads as "measured, but nothing here".
+    const resolvedOpacity = isNull
+        ? 0
+        : data.value === 0
+            ? minOpacity
+            : Math.max(minOpacity, Math.min(1, Math.ceil(intensity * 10) / 10));
+    const handleClick = () => onClick === null || onClick === void 0 ? void 0 : onClick(data);
+    const handleMouseEnter = (event) => onHover === null || onHover === void 0 ? void 0 : onHover(data, event);
+    const handleMouseMove = (event) => onMouseMove === null || onMouseMove === void 0 ? void 0 : onMouseMove(data, event);
+    const handleMouseLeave = () => onLeave === null || onLeave === void 0 ? void 0 : onLeave();
+    return (jsx(motion.div, { "data-heatmap-cell": "", "data-intensity-opacity": resolvedOpacity, className: cn(heatmapTheme.cellBaseStyle, isNull && heatmapTheme.cellNullStyle, onClick && 'cursor-pointer', className), style: isNull ? undefined : { backgroundColor: color }, initial: shouldReduceMotion ? false : { opacity: 0 }, animate: { opacity: resolvedOpacity }, transition: shouldReduceMotion
+            ? { duration: 0 }
+            : { duration: HEATMAP_CELL_FADE_DURATION, delay, ease: 'easeOut' }, onClick: handleClick, onMouseEnter: handleMouseEnter, onMouseMove: handleMouseMove, onMouseLeave: handleMouseLeave, whileHover: shouldReduceMotion
+            ? undefined
+            : { scale: 1.025, transition: HEATMAP_CELL_HOVER_TRANSITION }, whileTap: shouldReduceMotion
+            ? undefined
+            : { scale: 0.95, transition: HEATMAP_CELL_TAP_TRANSITION }, role: "gridcell", tabIndex: onClick ? 0 : -1, "aria-label": `Value: ${data.value}, X: ${data.x}, Y: ${data.y}`, onKeyDown: (e) => {
             if ((e.key === 'Enter' || e.key === ' ') && onClick) {
                 e.preventDefault();
                 onClick(data);
             }
-        }, children: children && (jsx("div", { className: "absolute inset-0 flex items-center justify-center text-sm font-medium text-gray-700 dark:text-gray-300", children: children })) }));
+        }, children: children && (jsx("div", { className: heatmapTheme.cellOverlayStyle, children: children })) }));
 };
 const HeatmapCell = React__default.memo(HeatmapCellInner);
 

package/dist/components/charts/Heatmap/HeatmapLegend.d.ts

@@ -1,13 +1,14 @@
 import React from 'react';
+/**
+ * The ramp is a purely visual scale: it renders the two end captions, never the
+ * numeric bounds. `minValue`/`maxValue` used to sit here and were never read —
+ * the same advertise-a-prop-you-ignore trap the flat-API refactor removed from
+ * `HeatmapProps`. If the numbers are ever wanted beside the ramp, that is a
+ * deliberate feature with its own rendering, not two dormant props.
+ */
 export interface HeatmapLegendProps {
-    /** Base color key from chart config (e.g., 'value', 'activity') */
-    colorKey?: string;
     /** Color to use for the gradient */
     color?: string;
-    /** Minimum value for the legend */
-    minValue?: number;
-    /** Maximum value for the legend */
-    maxValue?: number;
     /** Custom labels for min and max */
     labels?: {
         min?: string;

package/dist/components/charts/Heatmap/HeatmapLegend.js

@@ -2,16 +2,16 @@ import { jsxs, jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
 import { heatmapTheme } from './Heatmap.theme.js';
 
-const HeatmapLegend = ({ colorKey = 'value', color = 'var(--color-primary)', // Correct CSS variable
-minValue = 0, maxValue = 100, labels = {
-    min: 'Low activity',
-    max: 'High activity'
-}, className }) => {
+const HeatmapLegend = ({ color = 'var(--color-primary)', // Correct CSS variable
+labels, className }) => {
+    var _a, _b;
+    const min = (_a = labels === null || labels === void 0 ? void 0 : labels.min) !== null && _a !== void 0 ? _a : 'Low activity';
+    const max = (_b = labels === null || labels === void 0 ? void 0 : labels.max) !== null && _b !== void 0 ? _b : 'High activity';
     // Create gradient using passed color (supports CSS variables and hex)
     const gradientStyle = {
         background: `linear-gradient(to right, color-mix(in srgb, ${color} 20%, transparent), ${color})`
     };
-    return (jsxs("div", { className: cn(heatmapTheme.legendStyle, className), children: [jsx("div", { className: "w-full h-1.5 rounded-full", style: gradientStyle }), jsxs("div", { className: "flex items-center justify-between text-sm font-medium text-[var(--color-text-secondary)]", children: [jsx("div", { children: labels.min }), jsx("div", { children: labels.max })] })] }));
+    return (jsxs("div", { className: cn(heatmapTheme.legendStyle, className), children: [jsx("div", { className: "w-full h-1.5 rounded-full", style: gradientStyle }), jsxs("div", { className: "flex items-center justify-between text-xs font-medium text-[var(--color-text-secondary)]", children: [jsx("div", { children: min }), jsx("div", { children: max })] })] }));
 };
 
 export { HeatmapLegend };

package/dist/components/charts/Heatmap/index.d.ts

@@ -2,6 +2,6 @@ export { Heatmap } from './Heatmap';
 export { HeatmapCell } from './HeatmapCell';
 export { HeatmapLegend } from './HeatmapLegend';
 export { heatmapTheme } from './Heatmap.theme';
-export type { HeatmapProps, HeatmapDataPoint, HeatmapCellProps, SemanticColor } from './Heatmap.types';
+export type { HeatmapProps, HeatmapDataPoint, HeatmapCellProps, HeatmapVariant } from './Heatmap.types';
 export * from './Heatmap.types';
 export * from './utils/heatmapUtils';

package/dist/components/charts/Heatmap/utils/heatmapUtils.d.ts

@@ -1,8 +1,10 @@
 import type { HeatmapDataPoint, ProcessedHeatmapData } from '../Heatmap.types';
 /**
- * Process raw heatmap data and calculate necessary values
+ * Process raw heatmap data and calculate necessary values.
+ * `minValue`/`maxValue` are the flat family-standard bounds; either may be
+ * omitted, in which case it is derived from the data.
  */
-export declare function processHeatmapData(data: HeatmapDataPoint[], valueRange?: [number, number]): ProcessedHeatmapData;
+export declare function processHeatmapData(data: HeatmapDataPoint[], minValue?: number, maxValue?: number): ProcessedHeatmapData;
 /**
  * Calculate intensity (0-1) for a given value within the range
  */
@@ -13,18 +15,11 @@ export declare function calculateIntensity(value: number | null, minValue: numbe
  */
 export declare function createGridMatrix(data: HeatmapDataPoint[], xCategories: (string | number)[], yCategories: (string | number)[]): HeatmapDataPoint[][];
 /**
- * Generate default tooltip content for a data point
+ * Default tooltip content for a data point. `label` is the series label from
+ * `config[key].label` — the family contract every other chart already honours.
  */
-export declare function getDefaultTooltipContent(data: HeatmapDataPoint): string;
+export declare function getDefaultTooltipContent(data: HeatmapDataPoint, label?: string): string;
 /**
  * Format axis labels with common patterns
  */
 export declare function formatAxisLabel(value: string | number, type?: 'day' | 'month' | 'hour' | 'date' | 'number' | 'default'): string;
-/**
- * Calculate responsive cell size based on container dimensions
- */
-export declare function calculateCellSize(containerWidth: number, containerHeight: number, xCount: number, yCount: number, gap?: number, minSize?: number, maxSize?: number): number;
-/**
- * Generate sample heatmap data for testing/examples
- */
-export declare function generateSampleData(type?: 'weekly' | 'monthly' | 'hourly'): HeatmapDataPoint[];