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

package/dist/components/charts/ActivityRings/ActivityRings.js

@@ -7,7 +7,7 @@ import { activityRingsTheme } from './ActivityRings.theme.js';
 import { ACTIVITY_RINGS_DEFAULTS } from './ActivityRings.types.js';
 import { Warning } from '@phosphor-icons/react';
 import { useTooltipPosition } from '../hooks/useTooltipPosition.js';
-import { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
+import { ChartTooltip } from '../../core/shared/ChartTooltip/ChartTooltip.js';
 import { getSpringAnimation, CIRCULAR_CHART_ANIMATIONS, getStaggerDelay } from '../utils/animation-utils.js';
 
 const RingElement = React__default.memo(({ ring, index, radius, center, svgSize, strokeWidth, ringColor, hasAnimated, showAnimation, shouldReduceMotion, animationDelay, handleMouseEnter, handleMouseMove, handleMouseLeave, }) => {
@@ -39,7 +39,7 @@ const RingElement = React__default.memo(({ ring, index, radius, center, svgSize,
     }, [index, ring.label, ring.value, ringColor, center, radius, svgSize, handleMouseEnter]);
     const onMouseMove = useCallback((e) => handleMouseMove(e), [handleMouseMove]);
     const onMouseLeave = useCallback(() => handleMouseLeave(), [handleMouseLeave]);
-    return (jsxs("g", { children: [jsx("circle", { cx: center, cy: center, r: radius, fill: "none", stroke: "var(--color-chart-track)", strokeWidth: strokeWidth, strokeLinecap: "round", className: "cursor-pointer", transform: `rotate(-90 ${center} ${center})`, onMouseEnter: onMouseEnter, onMouseMove: onMouseMove, onMouseLeave: onMouseLeave }), jsx(motion.circle, { cx: center, cy: center, r: radius, fill: "none", stroke: ringColor, strokeWidth: strokeWidth, strokeLinecap: "round", strokeDasharray: circumference, className: "cursor-pointer transition-opacity duration-200", initial: { strokeDashoffset: circumference }, animate: hasAnimated ? { strokeDashoffset: offset } : {}, transition: showAnimation && !shouldReduceMotion
+    return (jsxs("g", { children: [jsx("circle", { cx: center, cy: center, r: radius, fill: "none", stroke: "var(--color-chart-track)", strokeWidth: strokeWidth, strokeLinecap: "round", className: "cursor-pointer", transform: `rotate(-90 ${center} ${center})`, onMouseEnter: onMouseEnter, onMouseMove: onMouseMove, onMouseLeave: onMouseLeave }), jsx(motion.circle, { cx: center, cy: center, r: radius, fill: "none", stroke: ringColor, strokeWidth: strokeWidth, strokeLinecap: "round", strokeDasharray: circumference, className: "cursor-pointer transition-opacity duration-[var(--motion-duration-base)]", initial: { strokeDashoffset: circumference }, animate: hasAnimated ? { strokeDashoffset: offset } : {}, transition: showAnimation && !shouldReduceMotion
                     ? getSpringAnimation(CIRCULAR_CHART_ANIMATIONS.activityRings.preset, shouldReduceMotion, animationDelay)
                     : { duration: 0 }, transform: `rotate(-90 ${center} ${center})`, onMouseEnter: onMouseEnter, onMouseMove: onMouseMove, onMouseLeave: onMouseLeave })] }));
 });

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

@@ -4,7 +4,7 @@
  * Follows the established chart theming pattern with CSS variables
  */
 const activityRingsTheme = {
-    baseStyle: "relative flex items-center justify-center transition-all duration-300 cursor-default",
+    baseStyle: "relative flex items-center justify-center transition-all duration-[var(--motion-duration-slow)] cursor-default",
     svgStyle: "overflow-visible relative",
     ringDefaults: {
         strokeWidth: 8,

package/dist/components/charts/AreaChart/AreaChart.js

@@ -9,7 +9,7 @@ import { useChartDimensions } from '../hooks/useChartDimensions.js';
 import { XAxis } from '../shared/ChartAxis/XAxis.js';
 import { YAxis } from '../shared/ChartAxis/YAxis.js';
 import { HorizontalGrid } from '../shared/ChartGrid/HorizontalGrid.js';
-import { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
+import { ChartTooltip } from '../../core/shared/ChartTooltip/ChartTooltip.js';
 import { resolveLegendPosition, ChartLegend } from '../shared/ChartLegend/ChartLegend.js';
 import { ChartMarker } from '../shared/ChartMarker/ChartMarker.js';
 import { ChartCrosshair } from '../shared/ChartCrosshair/ChartCrosshair.js';
@@ -279,14 +279,14 @@ svgClassName, areaClassName, lineClassName, gridClassName, axisClassName, width,
                                         // so `originY:1` anchors scaleY to the group's fill-box BOTTOM.
                                         // The invisible rect below pins that bottom to the plot baseline,
                                         // so the series grows UP from the x-axis — not from its own mid-height.
-                                        style: RISE_FROM_BASELINE, children: [jsx("rect", { x: margin.left, y: margin.top, width: innerWidth, height: innerHeight, fill: "none", stroke: "none", style: { pointerEvents: "none" } }), jsx("path", { d: paths.areaPath, fill: `url(#${getAreaGradientId(keyIndex)})`, className: "transition-colors duration-200", filter: isGradientVariant ? undefined : `url(#${shadowFilterId})`, transform: isGradientVariant
+                                        style: RISE_FROM_BASELINE, children: [jsx("rect", { x: margin.left, y: margin.top, width: innerWidth, height: innerHeight, fill: "none", stroke: "none", style: { pointerEvents: "none" } }), jsx("path", { d: paths.areaPath, fill: `url(#${getAreaGradientId(keyIndex)})`, className: "transition-colors duration-[var(--motion-duration-base)]", filter: isGradientVariant ? undefined : `url(#${shadowFilterId})`, transform: isGradientVariant
                                                     ? `translate(0 ${gradientAreaGap})`
                                                     : undefined }), showStroke && (jsxs(Fragment, { children: [isGradientVariant && (jsx(motion.path, { d: paths.linePath, initial: { opacity: 1 }, animate: { opacity: 1 }, fill: "none", stroke: resolveSeriesColor(keyIndex, key, config, chartTheme.baseStyle.colors.series), strokeWidth: gradientStrokeWidth + 1, strokeLinecap: "round", strokeLinejoin: "round", 
                                                         // Stroke width must ignore the group's scaleY rise, else
                                                         // it squashes flat at the start of the animation.
                                                         vectorEffect: "non-scaling-stroke", opacity: 0.08, filter: `url(#${getLineGlowId(keyIndex)})`, style: { pointerEvents: "none" } })), jsx(motion.path, { d: paths.linePath, initial: { opacity: 1 }, animate: { opacity: 1 }, fill: "none", stroke: ((_a = config[key]) === null || _a === void 0 ? void 0 : _a.color) ? resolveSeriesColor(keyIndex, key, config, []) : (isGradientVariant ? resolveSeriesColor(keyIndex, undefined, undefined, chartTheme.baseStyle.colors.series) : undefined), strokeWidth: isGradientVariant ? gradientStrokeWidth : strokeWidth, strokeLinecap: "round", strokeLinejoin: "round", 
                                                         // Constant stroke width through the scaleY rise (no squash).
-                                                        vectorEffect: "non-scaling-stroke", className: cn("transition-colors duration-200", !isGradientVariant &&
+                                                        vectorEffect: "non-scaling-stroke", className: cn("transition-colors duration-[var(--motion-duration-base)]", !isGradientVariant &&
                                                             (colorClass
                                                                 .split(" ")
                                                                 .find((cls) => cls.startsWith("stroke-")) || ""), lineClassName), style: { stroke: ((_b = config[key]) === null || _b === void 0 ? void 0 : _b.color) ? resolveSeriesColor(keyIndex, key, config, []) : undefined } })] }))] }, `${key}${shouldReduceMotion ? "" : `-${dataSignature}`}`));

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

@@ -7,11 +7,11 @@
  */
 const areaChartTheme = {
     // Main container with transition utilities for hover states
-    containerStyle: "chart-container w-full h-full relative [&_.chart-areas]:transition-opacity [&_.chart-areas]:duration-300 [&_.chart-hover-areas]:cursor-pointer [&_.chart-hover-markers]:transition-all [&_.chart-hover-markers]:duration-200",
+    containerStyle: "chart-container w-full h-full relative [&_.chart-areas]:transition-opacity [&_.chart-areas]:duration-[var(--motion-duration-slow)] [&_.chart-hover-areas]:cursor-pointer [&_.chart-hover-markers]:transition-all [&_.chart-hover-markers]:duration-[var(--motion-duration-base)]",
     // SVG container with overflow and transition utilities
-    svgStyle: "overflow-visible [&_.chart-areas_path]:transition-all [&_.chart-areas_path]:duration-200",
+    svgStyle: "overflow-visible [&_.chart-areas_path]:transition-all [&_.chart-areas_path]:duration-[var(--motion-duration-base)]",
     // Area group styling with drop shadows
-    areaGroupStyle: "chart-areas [&_path]:drop-shadow-sm [&_path]:transition-all [&_path]:duration-200",
+    areaGroupStyle: "chart-areas [&_path]:drop-shadow-sm [&_path]:transition-all [&_path]:duration-[var(--motion-duration-base)]",
     // Empty state text color using correct CSS variable
     emptyStateStyle: "chart-container flex items-center justify-center text-[var(--color-text-placeholder)]",
 };

package/dist/components/charts/BarChart/BarChart.js

@@ -11,7 +11,7 @@ import { ChartErrorBoundary } from '../shared/ChartErrorBoundary/ChartErrorBound
 import { XAxis } from '../shared/ChartAxis/XAxis.js';
 import { YAxis } from '../shared/ChartAxis/YAxis.js';
 import { HorizontalGrid } from '../shared/ChartGrid/HorizontalGrid.js';
-import { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
+import { ChartTooltip } from '../../core/shared/ChartTooltip/ChartTooltip.js';
 import { resolveLegendPosition, ChartLegend } from '../shared/ChartLegend/ChartLegend.js';
 import { BAR_CHART_DEFAULTS } from './BarChart.types.js';
 import { X_AXIS_MARGIN } from '../types/chart.types.js';
@@ -313,7 +313,7 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
                     : { scaleY: 1, opacity: 1 }, animate: {
                     scaleY: 1,
                     opacity: 1,
-                }, transition: { ...BAR_SPRING, delay }, className: "transition-opacity duration-200", style: {
+                }, transition: { ...BAR_SPRING, delay }, className: "transition-opacity duration-[var(--motion-duration-base)]", style: {
                     originY: 1,
                     transformOrigin: "bottom",
                     fill: `url(#${hatchPatternId})`,
@@ -345,8 +345,8 @@ className, title, description, enableKeyboardNavigation = BAR_CHART_DEFAULTS.ena
                         // plain style values at mount and ignores re-render changes
                         opacity: barDimOpacity(shouldReduceOpacity, isGradientVariant),
                     }, transition: commonTransition, className: cn(isGradientVariant
-                        ? "transition-all duration-300 ease-out"
-                        : "transition-colors duration-200", !isNull && "cursor-pointer", isFocused && "stroke-2"), style: {
+                        ? "transition-all duration-[var(--motion-duration-slow)] ease-out"
+                        : "transition-colors duration-[var(--motion-duration-base)]", !isNull && "cursor-pointer", isFocused && "stroke-2"), style: {
                         originY: isNegative ? 0 : 1,
                         transformOrigin: isNegative ? "top" : "bottom",
                         fill: barFill({

package/dist/components/charts/ComboChart/BarRenderer.js

@@ -163,8 +163,8 @@ const BarRenderer = ({ data, config, scales, dimensions, margin, stacked = false
                     }, transition: isStacked
                         ? stackedSegmentTransition(delay, hasAnimated)
                         : barEntranceTransition(delay, hasAnimated), className: cn(isGradientVariant
-                        ? "transition-all duration-300 ease-out"
-                        : "transition-colors duration-200", !isNull && "cursor-pointer", isFocused && "stroke-2"), style: {
+                        ? "transition-all duration-[var(--motion-duration-slow)] ease-out"
+                        : "transition-colors duration-[var(--motion-duration-base)]", !isNull && "cursor-pointer", isFocused && "stroke-2"), style: {
                         originY: isNegative ? 0 : 1,
                         transformOrigin: isNegative ? "top" : "bottom",
                         fill: barFill({

package/dist/components/charts/ComboChart/BarRenderer.types.d.ts

@@ -1,7 +1,7 @@
 import type { ChartDataPoint, ChartConfig } from '../types/chart.types';
 import type { ChartScales } from '../hooks/useChartScales';
 import type { ChartDimensions, ChartMargins } from './ComboChartCanvas.types';
-import type { MultiSeriesData } from '../shared/ChartTooltip';
+import type { MultiSeriesData } from '../../core/shared/ChartTooltip';
 export interface BarRendererProps {
     /**
      * Chart data

package/dist/components/charts/ComboChart/ComboChartCanvas.js

@@ -9,7 +9,7 @@ import { ChartErrorBoundary } from '../shared/ChartErrorBoundary/ChartErrorBound
 import { XAxis } from '../shared/ChartAxis/XAxis.js';
 import { YAxis } from '../shared/ChartAxis/YAxis.js';
 import { HorizontalGrid } from '../shared/ChartGrid/HorizontalGrid.js';
-import { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
+import { ChartTooltip } from '../../core/shared/ChartTooltip/ChartTooltip.js';
 
 const ComboChartContext = createContext(null);
 /**

package/dist/components/charts/ComboChart/LineRenderer.js

@@ -106,7 +106,7 @@ const LineRenderer = ({ data, config, scales, dimensions, margin, strokeWidth =
             const appliedColorClass = customColor ? undefined : fallbackClass;
             return (jsxs("g", { children: [jsxs(motion.g, { initial: { scaleY: shouldReduceMotion ? 1 : 0 }, animate: { scaleY: 1 }, transition: riseTransition, style: RISE_FROM_BASELINE, children: [jsx("rect", { x: margin.left, y: margin.top, width: innerWidth, height: innerHeight, fill: "none", stroke: "none", style: { pointerEvents: "none" } }), jsx("path", { d: targetPath, fill: "none", strokeWidth: strokeWidth, strokeLinecap: "round", 
                                 // Constant stroke width through the scaleY rise (no squash).
-                                vectorEffect: "non-scaling-stroke", className: cn("transition-all duration-200", appliedColorClass), stroke: customColor, filter: "url(#line-shadow)" })] }, shouldReduceMotion ? "line-static" : dataSignature), showDots &&
+                                vectorEffect: "non-scaling-stroke", className: cn("transition-all duration-[var(--motion-duration-base)]", appliedColorClass), stroke: customColor, filter: "url(#line-shadow)" })] }, shouldReduceMotion ? "line-static" : dataSignature), showDots &&
                         data.map((item, dataIndex) => {
                             const rawValue = item[key];
                             const isNull = rawValue === null || rawValue === undefined;

package/dist/components/charts/ComboChart/LineRenderer.types.d.ts

@@ -1,7 +1,7 @@
 import type { ChartDataPoint, ChartConfig, CurveType } from '../types/chart.types';
 import type { ChartScales } from '../hooks/useChartScales';
 import type { ChartDimensions, ChartMargins } from './ComboChartCanvas.types';
-import type { MultiSeriesData } from '../shared/ChartTooltip';
+import type { MultiSeriesData } from '../../core/shared/ChartTooltip';
 export interface LineRendererProps {
     /**
      * Chart data

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

@@ -3,15 +3,15 @@
  */
 const donutChartTheme = {
     // Base container styles
-    baseStyle: "relative flex items-center justify-center transition-all duration-300 cursor-default",
+    baseStyle: "relative flex items-center justify-center transition-all duration-[var(--motion-duration-slow)] cursor-default",
     // Background track styling
     track: "text-[var(--color-border)]",
     // Progress arc styling
-    progress: "text-[var(--color-primary)] transition-all duration-300",
+    progress: "text-[var(--color-primary)] transition-all duration-[var(--motion-duration-slow)]",
     // Text styling
     text: {
-        label: "text-xl font-bold text-[var(--color-text-primary)] transition-colors duration-300 tracking-tight",
-        subtitle: "text-sm text-[var(--color-text-secondary)] mt-1 transition-colors duration-300",
+        label: "text-xl font-bold text-[var(--color-text-primary)] transition-colors duration-[var(--motion-duration-slow)] tracking-tight",
+        subtitle: "text-sm text-[var(--color-text-secondary)] mt-1 transition-colors duration-[var(--motion-duration-slow)]",
     },
     // Default color palette (CSS variables for dark mode support)
     // Note: These are resolved at runtime via getComputedStyle

package/dist/components/charts/DonutChart/MultiSegmentDonutChart.theme.js

@@ -3,7 +3,7 @@
  */
 const multiSegmentDonutChartTheme = {
     // Base container styles
-    baseStyle: "relative flex items-center justify-center transition-all duration-300",
+    baseStyle: "relative flex items-center justify-center transition-all duration-[var(--motion-duration-slow)]",
     // Background track styling
     track: "text-[var(--color-border)]",
     // Legend styling

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