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

package/dist/components/charts/LollipopChart/LollipopChart.js

@@ -0,0 +1,361 @@
+"use client";
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { useId, useState, useEffect, useMemo, useRef } from 'react';
+import { useReducedMotion, motion, AnimatePresence } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { contrastTone } from '../../../utils/colorUtils.js';
+import { useChartDimensions } from '../hooks/useChartDimensions.js';
+import { useChartValidation } from '../hooks/useChartValidation.js';
+import { useChartAccessibility } from '../hooks/useChartAccessibility.js';
+import { useTooltipPosition } from '../hooks/useTooltipPosition.js';
+import { ChartErrorBoundary } from '../shared/ChartErrorBoundary/ChartErrorBoundary.js';
+import { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
+import { HorizontalGrid } from '../shared/ChartGrid/HorizontalGrid.js';
+import { YAxis } from '../shared/ChartAxis/YAxis.js';
+import { XAxis } from '../shared/ChartAxis/XAxis.js';
+import { CARTESIAN_ENTRANCE_DURATION, LINE_DOT_STAGGER, dotEntranceTransition, RISE_FROM_BASELINE, barEntranceTransition, BAR_GROUP_STAGGER } from '../utils/animation-utils.js';
+import { springs } from '../../../theme/animations.js';
+import { X_AXIS_MARGIN } from '../types/chart.types.js';
+import { LOLLIPOP_CHART_DEFAULTS } from './LollipopChart.types.js';
+import { Warning } from '@phosphor-icons/react';
+
+/** Top margin reserved so the selected mark's pill has clearance from the top edge. */
+const LOLLIPOP_TOP_MARGIN = 48;
+const LollipopChart = ({ data, config, showGrid = LOLLIPOP_CHART_DEFAULTS.showGrid, showXAxis = LOLLIPOP_CHART_DEFAULTS.showXAxis, showYAxis = LOLLIPOP_CHART_DEFAULTS.showYAxis, minValue: propMinValue, maxValue: propMaxValue, dotRadius = LOLLIPOP_CHART_DEFAULTS.dotRadius, stemWidth = LOLLIPOP_CHART_DEFAULTS.stemWidth, color, showAnimation = LOLLIPOP_CHART_DEFAULTS.showAnimation, enableKeyboardNavigation = LOLLIPOP_CHART_DEFAULTS.enableKeyboardNavigation, showValidationWarnings = process.env.NODE_ENV === "development", darkMode = false, selectedIndex: selectedIndexProp, defaultSelectedIndex = LOLLIPOP_CHART_DEFAULTS.defaultSelectedIndex, onSelectedIndexChange, valueFormatter, className, title, description, width, height, ...props }) => {
+    var _a, _b, _c;
+    const chartId = useId().replace(/[^a-zA-Z0-9_-]/g, "");
+    const shouldReduceMotion = useReducedMotion();
+    const [hasAnimated, setHasAnimated] = useState(false);
+    useEffect(() => {
+        setHasAnimated(true);
+    }, [shouldReduceMotion, showAnimation]);
+    // Single-series only: warn (dev-only) if the caller passes more than one
+    // config key, and always render the first.
+    const dataKeys = useMemo(() => Object.keys(config || {}), [config]);
+    if (process.env.NODE_ENV !== "production" &&
+        dataKeys.length > 1) {
+        console.warn("[LollipopChart]: `config` should have exactly one key — LollipopChart is single-series only. " +
+            `Rendering "${dataKeys[0]}" and ignoring the rest.`);
+    }
+    const dataKey = dataKeys[0];
+    const isSelectionControlled = selectedIndexProp !== undefined;
+    const [internalSelectedIndex, setInternalSelectedIndex] = useState(defaultSelectedIndex);
+    const resolvedSelectedIndex = isSelectionControlled ? selectedIndexProp : internalSelectedIndex;
+    if (process.env.NODE_ENV !== "production") {
+        if (isSelectionControlled && defaultSelectedIndex !== LOLLIPOP_CHART_DEFAULTS.defaultSelectedIndex) {
+            console.warn("[LollipopChart]: both `selectedIndex` and `defaultSelectedIndex` were provided — `selectedIndex` (controlled) wins.");
+        }
+        if (isSelectionControlled && !onSelectedIndexChange) {
+            console.warn("[LollipopChart]: `selectedIndex` was provided without `onSelectedIndexChange` — the chart will not be able to update selection.");
+        }
+    }
+    const handleSelect = (index) => {
+        if (!isSelectionControlled) {
+            setInternalSelectedIndex(index);
+        }
+        onSelectedIndexChange === null || onSelectedIndexChange === void 0 ? void 0 : onSelectedIndexChange(index);
+    };
+    const formatValue = (value, item) => valueFormatter ? valueFormatter(value, item) : String(value);
+    const { validation, sanitizedData, isValid, hasWarnings, safeScale, safeMath, } = useChartValidation(data, config, { autoSanitize: true });
+    const seriesColor = (_b = color !== null && color !== void 0 ? color : (dataKey && ((_a = config[dataKey]) === null || _a === void 0 ? void 0 : _a.color))) !== null && _b !== void 0 ? _b : "var(--color-primary)";
+    const containerRef = useRef(null);
+    const { dimensions, measured } = useChartDimensions(containerRef);
+    const isMobile = typeof window !== "undefined" &&
+        ("ontouchstart" in window || navigator.maxTouchPoints > 0);
+    const { tooltipData, tooltipRef, handleMouseEnter, handleMouseMove, handleMouseLeave, } = useTooltipPosition({ containerRef, isMobile });
+    const { chartAccessibilityProps, descriptionProps, focusedElementIndex, isKeyboardMode, handleMouseInteraction, } = useChartAccessibility({
+        chartType: "lollipop",
+        data: sanitizedData,
+        config,
+        title,
+        description,
+        enableKeyboardNavigation,
+    });
+    const [hoveredIndex, setHoveredIndex] = useState(null);
+    const activeIndex = hoveredIndex !== null
+        ? hoveredIndex
+        : isKeyboardMode && focusedElementIndex >= 0
+            ? focusedElementIndex
+            : null;
+    const isAnyActive = activeIndex !== null;
+    const margin = useMemo(() => ({
+        top: LOLLIPOP_TOP_MARGIN,
+        right: showYAxis ? 20 : 16,
+        bottom: showXAxis ? X_AXIS_MARGIN : 0,
+        left: showYAxis ? 60 : 16,
+    }), [showXAxis, showYAxis]);
+    const innerWidth = Math.max(0, dimensions.width - margin.left - margin.right);
+    const innerHeight = Math.max(0, dimensions.height - margin.top - margin.bottom);
+    const scaleRange = safeScale.calculateRange({
+        minValue: propMinValue,
+        maxValue: propMaxValue,
+        includeZero: true,
+    });
+    const { min: minValue, max: maxValue, hasValidData } = scaleRange;
+    useEffect(() => {
+        var _a, _b;
+        if (isKeyboardMode &&
+            focusedElementIndex >= 0 &&
+            focusedElementIndex < sanitizedData.length &&
+            dataKey) {
+            const item = sanitizedData[focusedElementIndex];
+            const rawValue = item[dataKey];
+            if (typeof rawValue === "number" && isFinite(rawValue)) {
+                const categoryGap = 24;
+                const totalGap = Math.max(0, (sanitizedData.length - 1) * categoryGap);
+                const categoryWidth = safeMath.divide(Math.max(0, innerWidth - totalGap), sanitizedData.length, 0);
+                const cx = margin.left + focusedElementIndex * (categoryWidth + categoryGap) + categoryWidth / 2;
+                const range = maxValue - minValue;
+                const scaledZero = range > 0 ? safeMath.scale(0, minValue, maxValue, 0, innerHeight) : 0;
+                const zeroY = margin.top + innerHeight - scaledZero;
+                const scaledValue = range > 0 ? safeMath.scale(rawValue, minValue, maxValue, 0, innerHeight) : 0;
+                const isNeg = rawValue < 0;
+                const dotY = isNeg
+                    ? zeroY + Math.abs(scaledValue - scaledZero)
+                    : zeroY - Math.abs(scaledValue - scaledZero);
+                const syntheticEvent = new MouseEvent("mouseenter", { clientX: cx, clientY: dotY });
+                handleMouseEnter(syntheticEvent, {
+                    category: ((_a = item.name) !== null && _a !== void 0 ? _a : `Category ${focusedElementIndex + 1}`).toString(),
+                    series: [
+                        { key: dataKey, label: ((_b = config[dataKey]) === null || _b === void 0 ? void 0 : _b.label) || dataKey, value: rawValue, color: seriesColor },
+                    ],
+                }, { x: cx, y: dotY, dimensions });
+            }
+        }
+        else if (isKeyboardMode && focusedElementIndex === -1) {
+            handleMouseLeave();
+        }
+    }, [
+        isKeyboardMode, focusedElementIndex, sanitizedData, config, dimensions, margin,
+        innerWidth, innerHeight, minValue, maxValue, handleMouseEnter, handleMouseLeave,
+        dataKey, seriesColor, safeMath,
+    ]);
+    // --- Every hook above this line runs unconditionally, every render — same
+    // discipline BarChart documents (BarChart.tsx ~line 674): a chart going
+    // from populated -> empty/invalid data must never change its hook count.
+    if (!isValid) {
+        return (jsxs("div", { className: cn("chart-container flex flex-col items-center justify-center p-6 border border-[var(--color-border)] rounded-lg text-2xl", className), role: "alert", "aria-live": "polite", ...props, children: [jsxs("div", { className: "flex flex-col items-center gap-4 mb-1", children: [jsx(Warning, { className: "size-6 text-[var(--color-danger)]" }), jsx("div", { className: "text-base font-semibold text-[var(--color-text-secondary)]", children: "Invalid Chart Data" })] }), jsx("p", { className: "text-base text-[var(--color-text-secondary)]/70 mb-2", children: ((_c = validation.errors[0]) === null || _c === void 0 ? void 0 : _c.message) ||
+                        "Unable to render chart due to data validation errors" })] }));
+    }
+    if (!sanitizedData || sanitizedData.length === 0) {
+        return (jsx("div", { className: cn("chart-container flex items-center justify-center text-[var(--color-text-muted)]", className), role: "img", "aria-label": "Empty lollipop chart", ...props, children: jsx("span", { children: "No data available" }) }));
+    }
+    if (!hasValidData) {
+        return (jsx("div", { className: cn("chart-container flex items-center justify-center text-[var(--color-text-muted)]", className), role: "img", "aria-label": "Empty lollipop chart - no valid data", ...props, children: jsx("span", { children: "No valid numeric data available" }) }));
+    }
+    return (jsx(ChartErrorBoundary, { className: className, showErrorDetails: process.env.NODE_ENV === "development", children: jsxs("div", { ref: containerRef, className: cn("chart-container w-full h-full flex flex-col", darkMode && "dark", className), style: {
+                width: width !== undefined
+                    ? typeof width === "number"
+                        ? `${width}px`
+                        : width
+                    : undefined,
+                height: height !== undefined
+                    ? typeof height === "number"
+                        ? `${height}px`
+                        : height
+                    : undefined,
+            }, ...chartAccessibilityProps, onKeyDown: (e) => {
+                chartAccessibilityProps.onKeyDown(e);
+                if ((e.key === "Enter" || e.key === " ") && isKeyboardMode && focusedElementIndex >= 0) {
+                    e.preventDefault();
+                    handleSelect(resolvedSelectedIndex === focusedElementIndex ? null : focusedElementIndex);
+                }
+            }, onMouseEnter: handleMouseInteraction, onMouseMove: handleMouseInteraction, ...props, children: [descriptionProps && jsx("div", { ...descriptionProps }), showValidationWarnings && hasWarnings && (jsxs("div", { className: "absolute top-2 left-2 right-2 z-10 p-2 bg-[var(--color-warning-50)] border border-[var(--color-warning-200)] rounded text-sm text-[var(--color-warning)] shadow-sm", children: [jsx("strong", { children: "Chart Warnings:" }), jsx("ul", { className: "mt-1", children: validation.warnings.map((warning, index) => (jsxs("li", { children: ["\u2022 ", warning.message] }, index))) })] })), jsx("div", { className: "relative flex-1 min-h-0", children: jsxs("svg", { width: "100%", height: "100%", viewBox: `0 0 ${dimensions.width} ${dimensions.height}`, style: { overflow: "visible" }, children: [jsxs("defs", { children: [jsxs("linearGradient", { id: `${chartId}-lollipop-stem-gradient`, gradientUnits: "userSpaceOnUse", x1: 0, y1: margin.top, x2: 0, y2: margin.top + innerHeight, children: [jsx("stop", { offset: "0%", stopColor: seriesColor, stopOpacity: 1 }), jsx("stop", { offset: "100%", stopColor: seriesColor, stopOpacity: 0.4 })] }), jsx("filter", { id: `${chartId}-lollipop-stem-glow`, filterUnits: "userSpaceOnUse", x: -20, y: margin.top - 20, width: dimensions.width + 40, height: innerHeight + 40, colorInterpolationFilters: "sRGB", children: jsx("feDropShadow", { dx: "0", dy: "0", stdDeviation: "4", floodColor: seriesColor, floodOpacity: "0.45" }) })] }), jsx(HorizontalGrid, { show: showGrid, x: margin.left, y: margin.top, width: innerWidth, height: innerHeight, lineCount: 5 }), jsx(YAxis, { show: showYAxis, min: minValue, max: maxValue, x: margin.left, y: margin.top, height: innerHeight, showGrid: false, gridWidth: innerWidth }), (() => {
+                                const categoryGap = 24;
+                                const totalGap = Math.max(0, (sanitizedData.length - 1) * categoryGap);
+                                const categoryWidth = safeMath.divide(Math.max(0, innerWidth - totalGap), sanitizedData.length, 0);
+                                return (jsx(XAxis, { show: showXAxis, data: sanitizedData, x: margin.left, y: margin.top + innerHeight, width: innerWidth, categoryWidth: categoryWidth, categoryGap: categoryGap }));
+                            })(), measured &&
+                                (() => {
+                                    const categoryGap = 24;
+                                    const totalGap = Math.max(0, (sanitizedData.length - 1) * categoryGap);
+                                    const categoryWidth = safeMath.divide(Math.max(0, innerWidth - totalGap), sanitizedData.length, 0);
+                                    const range = maxValue - minValue;
+                                    const scaledZero = range > 0 ? safeMath.scale(0, minValue, maxValue, 0, innerHeight) : 0;
+                                    const zeroY = margin.top + innerHeight - scaledZero;
+                                    return (jsx("g", { className: "chart-lollipops", children: sanitizedData.map((item, index) => {
+                                            const rawValue = item[dataKey];
+                                            const value = typeof rawValue === "number" && isFinite(rawValue) ? rawValue : 0;
+                                            const isNull = rawValue === null ||
+                                                rawValue === undefined ||
+                                                (typeof rawValue === "number" && !isFinite(rawValue));
+                                            const cx = margin.left + index * (categoryWidth + categoryGap) + categoryWidth / 2;
+                                            // Hoisted above the null gate on purpose: these depend only on the
+                                            // index, never on the value, and the null marker must dim off the
+                                            // SAME expression as every other mark. Recomputing it inline there
+                                            // drifted — `isAnyActive ? 0.35 : 1` misses the
+                                            // !isCurrentActiveOrSelected term, so a null sitting under an
+                                            // explicit `defaultSelectedIndex` dimmed while a real mark wouldn't.
+                                            const isSelected = resolvedSelectedIndex === index;
+                                            const isCurrentActiveOrSelected = index === activeIndex || index === resolvedSelectedIndex;
+                                            const lineOpacity = isAnyActive && !isCurrentActiveOrSelected ? 0.35 : 1;
+                                            // A null category has nothing to plot, so it gets a marker resting on
+                                            // the baseline and no stem — the axis label then anchors to something
+                                            // instead of hanging under empty space.
+                                            //
+                                            // 🔴 This is deliberately INDISTINGUISHABLE from a real `value: 0`,
+                                            // whose dot also lands on the baseline (dotY === zeroY once
+                                            // scaledValue === scaledZero). That collision is a known, accepted
+                                            // trade-off — don't "fix" it by nudging this marker off the axis.
+                                            //
+                                            // No hit area, stem, tooltip or selection: there is no value to
+                                            // report, so the marker is presentational only, and null stays
+                                            // skipped everywhere it would have to state a number.
+                                            if (isNull) {
+                                                return (jsx(motion.g, { 
+                                                    // initial/animate/transition mirror the real mark's motion.g
+                                                    // exactly — same springs, same opacity timing — only `y` differs
+                                                    // (pinned to the baseline instead of a plotted markerY). Keep
+                                                    // them in lockstep: every past divergence here was invisible in
+                                                    // a screenshot and only showed up in motion.
+                                                    initial: showAnimation && !shouldReduceMotion
+                                                        ? { x: cx, y: zeroY, scale: 0, opacity: 0 }
+                                                        : { x: cx, y: zeroY, scale: 1, opacity: 1 }, animate: {
+                                                        x: cx,
+                                                        y: zeroY,
+                                                        scale: 1,
+                                                        opacity: lineOpacity,
+                                                    }, transition: {
+                                                        ...dotEntranceTransition(index, shouldReduceMotion),
+                                                        // x/y ride springs.snappy so the marker tracks a resize or a
+                                                        // data change identically to its neighbours; left to the
+                                                        // entrance spring it lagged behind them.
+                                                        x: springs.snappy,
+                                                        y: springs.snappy,
+                                                        // Opacity needs its own transition too. Left to the entrance
+                                                        // spring it inherits that spring's per-index stagger delay and
+                                                        // the hover dim crawls — measured at 0.58 a full second in,
+                                                        // while every real mark had long since settled on 0.35.
+                                                        opacity: {
+                                                            delay: hasAnimated
+                                                                ? 0
+                                                                : shouldReduceMotion
+                                                                    ? 0
+                                                                    : CARTESIAN_ENTRANCE_DURATION + index * LINE_DOT_STAGGER,
+                                                            duration: 0.2,
+                                                        },
+                                                    }, style: {
+                                                        originX: "50%",
+                                                        originY: "50%",
+                                                        transformBox: "fill-box",
+                                                    }, children: jsx("rect", { x: -dotRadius, y: -dotRadius, width: dotRadius * 2, height: dotRadius * 2, rx: dotRadius, fill: seriesColor, stroke: "var(--color-surface)", strokeWidth: 2 }) }, index));
+                                            }
+                                            const scaledValue = range > 0
+                                                ? safeMath.scale(value, minValue, maxValue, 0, innerHeight)
+                                                : 0;
+                                            const isNeg = value < 0;
+                                            const dotY = isNeg
+                                                ? zeroY + Math.abs(scaledValue - scaledZero)
+                                                : zeroY - Math.abs(scaledValue - scaledZero);
+                                            const delay = index * BAR_GROUP_STAGGER;
+                                            return (jsxs("g", { onClick: () => handleSelect(isSelected ? null : index), onMouseEnter: (e) => {
+                                                    var _a, _b;
+                                                    setHoveredIndex(index);
+                                                    if (isSelected)
+                                                        return;
+                                                    handleMouseEnter(e, {
+                                                        category: ((_a = item.name) !== null && _a !== void 0 ? _a : `Category ${index + 1}`).toString(),
+                                                        series: [
+                                                            {
+                                                                key: dataKey,
+                                                                label: ((_b = config[dataKey]) === null || _b === void 0 ? void 0 : _b.label) || dataKey,
+                                                                value,
+                                                                color: seriesColor,
+                                                            },
+                                                        ],
+                                                    }, { x: cx, y: dotY, dimensions });
+                                                }, onMouseMove: (e) => {
+                                                    if (isSelected)
+                                                        return;
+                                                    handleMouseMove(e, { x: cx, y: dotY, dimensions });
+                                                }, onMouseLeave: () => {
+                                                    setHoveredIndex(null);
+                                                    if (isSelected)
+                                                        return;
+                                                    handleMouseLeave();
+                                                }, style: { cursor: "pointer" }, children: [jsx("rect", { x: cx - categoryWidth / 2, y: margin.top, width: categoryWidth, height: innerHeight, fill: "transparent" }), jsx(motion.line, { x1: cx, x2: cx, y1: zeroY, y2: dotY, stroke: `url(#${chartId}-lollipop-stem-gradient)`, strokeWidth: stemWidth, 
+                                                        // butt, not round: a round cap overhangs BOTH ends by
+                                                        // strokeWidth/2, so the stem bled past the baseline and sat
+                                                        // visibly below the axis rule. Butt terminates it exactly on
+                                                        // the axis. The flat top costs nothing — the dot marker
+                                                        // covers it.
+                                                        strokeLinecap: "butt", filter: `url(#${chartId}-lollipop-stem-glow)`, initial: showAnimation && !shouldReduceMotion
+                                                            ? { scaleY: 0 }
+                                                            : { scaleY: 1 }, animate: {
+                                                            scaleY: 1,
+                                                            x1: cx,
+                                                            x2: cx,
+                                                            y1: zeroY,
+                                                            y2: dotY,
+                                                            opacity: lineOpacity,
+                                                        }, transition: showAnimation && !shouldReduceMotion
+                                                            ? {
+                                                                scaleY: barEntranceTransition(delay, hasAnimated),
+                                                                x1: springs.premium,
+                                                                x2: springs.premium,
+                                                                y1: springs.premium,
+                                                                y2: springs.premium,
+                                                                opacity: { duration: 0.2 },
+                                                            }
+                                                            : undefined, style: { ...RISE_FROM_BASELINE, transformBox: "fill-box" } }), (() => {
+                                                        // The selected mark morphs from a small dot into a
+                                                        // pill showing the value, in place of the old
+                                                        // separate floating badge — same seriesColor on
+                                                        // both shapes so the swap reads as one mark
+                                                        // changing shape, not a switch to a different
+                                                        // element. Pill dimensions clamp to the plot's
+                                                        // vertical bounds so a very high/low value's pill
+                                                        // never clips past the top or into the axis row.
+                                                        const badgeText = formatValue(value, item);
+                                                        const pillWidth = Math.max(56, badgeText.length * 9 + 24);
+                                                        const pillHeight = 28;
+                                                        const pillCenterY = Math.min(Math.max(dotY, margin.top + pillHeight / 2), margin.top + innerHeight - pillHeight / 2);
+                                                        const markerY = isSelected ? pillCenterY : dotY;
+                                                        // When seriesColor is the (default) primary token,
+                                                        // reuse the design system's own vetted contrast
+                                                        // pairing — the same one every other filled-primary
+                                                        // surface (Button, Badge, ...) uses — rather than a
+                                                        // runtime luminance heuristic. A custom per-series
+                                                        // `color`/config color isn't necessarily primary,
+                                                        // so it still falls back to `contrastTone()`.
+                                                        const pillTextFill = seriesColor === "var(--color-primary)"
+                                                            ? "var(--color-primary-contrast)"
+                                                            : contrastTone(seriesColor) === "dark"
+                                                                ? "var(--color-mono-950)"
+                                                                : "var(--color-mono-50)";
+                                                        return (jsxs(motion.g, { initial: showAnimation && !shouldReduceMotion
+                                                                ? { x: cx, y: markerY, scale: 0, opacity: 0 }
+                                                                : { x: cx, y: markerY, scale: 1, opacity: 1 }, animate: {
+                                                                x: cx,
+                                                                y: markerY,
+                                                                scale: 1,
+                                                                opacity: lineOpacity,
+                                                            }, transition: {
+                                                                ...dotEntranceTransition(index, shouldReduceMotion),
+                                                                x: springs.snappy,
+                                                                y: springs.snappy,
+                                                                opacity: {
+                                                                    delay: hasAnimated
+                                                                        ? 0
+                                                                        : shouldReduceMotion
+                                                                            ? 0
+                                                                            : CARTESIAN_ENTRANCE_DURATION + index * LINE_DOT_STAGGER,
+                                                                    duration: 0.2,
+                                                                },
+                                                            }, style: {
+                                                                originX: "50%",
+                                                                originY: "50%",
+                                                                transformBox: "fill-box",
+                                                            }, children: [jsx(motion.rect, { animate: {
+                                                                        width: isSelected ? pillWidth : dotRadius * 2,
+                                                                        height: isSelected ? pillHeight : dotRadius * 2,
+                                                                        rx: isSelected ? pillHeight / 2 : dotRadius,
+                                                                        x: isSelected ? -pillWidth / 2 : -dotRadius,
+                                                                        y: isSelected ? -pillHeight / 2 : -dotRadius,
+                                                                    }, transition: springs.snappy, fill: seriesColor, stroke: "var(--color-surface)", strokeWidth: 2 }), jsx(AnimatePresence, { children: isSelected && (jsx(motion.text, { initial: { opacity: 0, scale: 0.6 }, animate: { opacity: 1, scale: 1 }, exit: { opacity: 0, scale: 0.6 }, transition: springs.snappy, x: 0, y: 0, textAnchor: "middle", dominantBaseline: "central", className: "text-sm font-semibold select-none pointer-events-none", fill: pillTextFill, children: badgeText }, "text")) })] }));
+                                                    })()] }, index));
+                                        }) }));
+                                })()] }) }), jsx(ChartTooltip, { tooltipRef: tooltipRef, content: tooltipData === null || tooltipData === void 0 ? void 0 : tooltipData.content, active: !!tooltipData, position: tooltipData ? { x: tooltipData.x, y: tooltipData.y } : { x: 0, y: 0 } })] }) }));
+};
+
+export { LollipopChart };

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

@@ -0,0 +1,42 @@
+import { BaseChartProps, ChartConfig, ChartDataPoint } from "../types/chart.types";
+export interface LollipopChartProps extends BaseChartProps {
+    config: ChartConfig;
+    showGrid?: boolean;
+    showXAxis?: boolean;
+    showYAxis?: boolean;
+    minValue?: number;
+    maxValue?: number;
+    /** Controlled selected category index. `null`/`undefined` = no selection. */
+    selectedIndex?: number | null;
+    /** Uncontrolled initial selection. */
+    defaultSelectedIndex?: number | null;
+    /** Payload is the index, not the event (CLAUDE.md §9 naming convention). */
+    onSelectedIndexChange?: (index: number | null) => void;
+    /** Formats the pinned badge's value text. Defaults to `String(value)`. */
+    valueFormatter?: (value: number, item: ChartDataPoint) => string;
+    dotRadius?: number;
+    stemWidth?: number;
+    /** Series color for the dot + stem. Falls back to the single `config` key's
+     * `color`, then `var(--color-primary)`. */
+    color?: string;
+    showAnimation?: boolean;
+    enableKeyboardNavigation?: boolean;
+    showValidationWarnings?: boolean;
+    darkMode?: boolean;
+    className?: string;
+    title?: string;
+    description?: string;
+    width?: string | number;
+    height?: string | number;
+}
+export declare const LOLLIPOP_CHART_DEFAULTS: {
+    readonly showGrid: false;
+    readonly showXAxis: true;
+    readonly showYAxis: false;
+    readonly dotRadius: 6;
+    readonly stemWidth: 3;
+    readonly defaultSelectedIndex: number | null;
+    readonly showAnimation: true;
+    readonly enableKeyboardNavigation: true;
+};
+export type LollipopChartData = ChartDataPoint;

package/dist/components/charts/LollipopChart/LollipopChart.types.js

@@ -0,0 +1,12 @@
+const LOLLIPOP_CHART_DEFAULTS = {
+    showGrid: false,
+    showXAxis: true,
+    showYAxis: false,
+    dotRadius: 6,
+    stemWidth: 3,
+    defaultSelectedIndex: null,
+    showAnimation: true,
+    enableKeyboardNavigation: true,
+};
+
+export { LOLLIPOP_CHART_DEFAULTS };

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

@@ -0,0 +1,3 @@
+export { LollipopChart } from "./LollipopChart";
+export type { LollipopChartProps, LollipopChartData } from "./LollipopChart.types";
+export { LOLLIPOP_CHART_DEFAULTS } from "./LollipopChart.types";

package/dist/components/charts/ScatterPlot/ScatterPlot.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 { ChartTooltip } from '../shared/ChartTooltip/ChartTooltip.js';
-import { ChartLegend } from '../shared/ChartLegend/ChartLegend.js';
+import { resolveLegendPosition, ChartLegend } from '../shared/ChartLegend/ChartLegend.js';
 import { SCATTER_PLOT_DEFAULTS } from './ScatterPlot.types.js';
 import { getCategoryColor, scatterPlotTheme } from './ScatterPlot.theme.js';
 import { SCATTER_POINT_DURATION, SCATTER_POINT_STAGGER } from '../utils/animation-utils.js';
@@ -21,7 +21,7 @@ import { SCATTER_POINT_DURATION, SCATTER_POINT_STAGGER } from '../utils/animatio
  * Now uses shared axis components with tick marks and value labels like other charts.
  */
 const ScatterPlot = ({ data, xLabel, yLabel, dotRadius: propDotRadius, pointSize, // @deprecated
-showGrid = SCATTER_PLOT_DEFAULTS.showGrid, showXAxis = SCATTER_PLOT_DEFAULTS.showXAxis, showYAxis = SCATTER_PLOT_DEFAULTS.showYAxis, showTooltip = SCATTER_PLOT_DEFAULTS.showTooltip, colors, minValue: propMinValue, maxValue: propMaxValue, theme: themeOverrides, className, svgClassName, dotClassName, gridClassName, axisClassName, title, description, enableKeyboardNavigation = SCATTER_PLOT_DEFAULTS.enableKeyboardNavigation, width, height, ...props }) => {
+showGrid = SCATTER_PLOT_DEFAULTS.showGrid, showXAxis = SCATTER_PLOT_DEFAULTS.showXAxis, showYAxis = SCATTER_PLOT_DEFAULTS.showYAxis, showTooltip = SCATTER_PLOT_DEFAULTS.showTooltip, legend, colors, minValue: propMinValue, maxValue: propMaxValue, theme: themeOverrides, className, svgClassName, dotClassName, gridClassName, axisClassName, title, description, enableKeyboardNavigation = SCATTER_PLOT_DEFAULTS.enableKeyboardNavigation, width, height, ...props }) => {
     var _a;
     const theme = { ...scatterPlotTheme, ...(themeOverrides || {}) };
     const chartColors = colors || theme.colors || scatterPlotTheme.colors;
@@ -114,6 +114,7 @@ showGrid = SCATTER_PLOT_DEFAULTS.showGrid, showXAxis = SCATTER_PLOT_DEFAULTS.sho
         label: cat,
         color: getCategoryColor(chartColors, idx),
     })), [categories, chartColors]);
+    const resolvedLegendPosition = resolveLegendPosition(legend, config);
     const chartDataForAccessibility = useMemo(() => {
         return validData.map((point) => ({
             category: point.category || 'Point',
@@ -155,7 +156,7 @@ showGrid = SCATTER_PLOT_DEFAULTS.showGrid, showXAxis = SCATTER_PLOT_DEFAULTS.sho
             minHeight: height === undefined ? '400px' : undefined,
             width: width !== undefined ? (typeof width === "number" ? `${width}px` : width) : undefined,
             height: height !== undefined ? (typeof height === "number" ? `${height}px` : height) : undefined,
-        }, ...chartAccessibilityProps, ...props, children: [jsxs("svg", { width: dimensions.width, height: dimensions.height, className: cn(theme.svgStyle, svgClassName), ...descriptionProps, children: [jsx(YAxis, { show: showYAxis, min: yMin, max: yMax, x: margin.left, y: margin.top, height: innerHeight, showGrid: showGrid, gridWidth: innerWidth, tickCount: 5, className: cn(axisClassName) }), measured &&
+        }, ...chartAccessibilityProps, ...props, children: [resolvedLegendPosition === 'top' && (jsx(ChartLegend, { items: legendItems, className: "shrink-0 mb-4" })), jsxs("svg", { width: dimensions.width, height: dimensions.height, className: cn(theme.svgStyle, svgClassName), ...descriptionProps, children: [jsx(YAxis, { show: showYAxis, min: yMin, max: yMax, x: margin.left, y: margin.top, height: innerHeight, showGrid: showGrid, gridWidth: innerWidth, gridClassName: gridClassName, tickCount: 5, className: cn(axisClassName) }), measured &&
                         validData.map((point, index) => {
                             const cx = scaleX(point.x);
                             const cy = scaleY(point.y);
@@ -200,7 +201,7 @@ showGrid = SCATTER_PLOT_DEFAULTS.showGrid, showXAxis = SCATTER_PLOT_DEFAULTS.sho
                                     }
                                     handleMouseInteraction();
                                 }, onMouseMove: handleMouseMove, onMouseLeave: handleMouseLeave }, index));
-                        }), jsx(XAxis, { show: showXAxis, data: xAxisData, x: margin.left, y: margin.top + innerHeight, width: innerWidth, categoryWidth: innerWidth / (xAxisData.length - 1), categoryGap: 0, alignWithEdge: true, className: cn(axisClassName) }), xLabel && showXAxis && (jsx("text", { x: margin.left + innerWidth / 2, y: dimensions.height - 5, textAnchor: "middle", className: "text-sm fill-[var(--color-text-secondary)]", children: xLabel })), yLabel && showYAxis && (jsx("text", { x: 15, y: margin.top + innerHeight / 2, textAnchor: "middle", className: "text-sm fill-[var(--color-text-secondary)]", transform: `rotate(-90 15 ${margin.top + innerHeight / 2})`, children: yLabel }))] }), jsx(ChartLegend, { items: legendItems, className: "mt-4" }), showTooltip && (jsx(ChartTooltip, { active: !!tooltipData, position: tooltipData ? { x: tooltipData.x, y: tooltipData.y } : { x: 0, y: 0 }, tooltipRef: tooltipRef, content: tooltipData === null || tooltipData === void 0 ? void 0 : tooltipData.content, chartType: "scatter" }))] }));
+                        }), jsx(XAxis, { show: showXAxis, data: xAxisData, x: margin.left, y: margin.top + innerHeight, width: innerWidth, categoryWidth: innerWidth / (xAxisData.length - 1), categoryGap: 0, alignWithEdge: true, className: cn(axisClassName) }), xLabel && showXAxis && (jsx("text", { x: margin.left + innerWidth / 2, y: dimensions.height - 5, textAnchor: "middle", className: "text-sm fill-[var(--color-text-secondary)]", children: xLabel })), yLabel && showYAxis && (jsx("text", { x: 15, y: margin.top + innerHeight / 2, textAnchor: "middle", className: "text-sm fill-[var(--color-text-secondary)]", transform: `rotate(-90 15 ${margin.top + innerHeight / 2})`, children: yLabel }))] }), resolvedLegendPosition === 'bottom' && (jsx(ChartLegend, { items: legendItems, className: "shrink-0 mt-4" })), showTooltip && (jsx(ChartTooltip, { active: !!tooltipData, position: tooltipData ? { x: tooltipData.x, y: tooltipData.y } : { x: 0, y: 0 }, tooltipRef: tooltipRef, content: tooltipData === null || tooltipData === void 0 ? void 0 : tooltipData.content, chartType: "scatter" }))] }));
 };
 ScatterPlot.displayName = 'ScatterPlot';
 

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

@@ -16,8 +16,13 @@ export interface ScatterPlotDataPoint {
 }
 /**
  * ScatterPlot props - extends standardized chart props
+ *
+ * 🔴 `variant` is Omitted, not inherited: scatter points are flat, single-colour marks —
+ * there is no gradient/minimal treatment to select. Leaving the inherited prop in place
+ * would publish a control that silently does nothing (and would reach the generative
+ * schema, where an LLM would emit it). Add it back only alongside an implementation.
  */
-export interface ScatterPlotProps extends StandardChartDisplayProps, Omit<BaseChartProps, 'data' | 'config'> {
+export interface ScatterPlotProps extends Omit<StandardChartDisplayProps, 'variant'>, Omit<BaseChartProps, 'data' | 'config'> {
     /** Data points */
     data: ScatterPlotDataPoint[];
     /** X-axis label */
@@ -38,28 +43,18 @@ export interface ScatterPlotProps extends StandardChartDisplayProps, Omit<BaseCh
     axisClassName?: string;
 }
 /**
- * Default values using centralized defaults
+ * Default values using centralized defaults.
+ *
+ * 🔴 Picks explicitly rather than spreading `...CHART_DEFAULTS` — the spread pulled in a
+ * default for every other chart's props, so this object advertised values ScatterPlot
+ * never reads. List only what the component actually consumes.
  */
 export declare const SCATTER_PLOT_DEFAULTS: {
-    readonly dotRadius: 4;
-    readonly pointSize: 4;
-    readonly showTooltip: true;
     readonly showGrid: true;
     readonly showXAxis: true;
     readonly showYAxis: true;
-    readonly barRadius: 32;
-    readonly cellRadius: 4;
-    readonly radius: 20;
-    readonly strokeWidth: 2;
-    readonly gap: 4;
-    readonly categoryGap: 16;
-    readonly curved: true;
-    readonly curveType: import("..").CurveType;
-    readonly fillOpacity: 0.3;
-    readonly showStroke: true;
-    readonly showDots: false;
-    readonly orientation: "vertical" | "horizontal";
-    readonly stacked: false;
-    readonly variant: import("..").ChartVariant;
     readonly enableKeyboardNavigation: true;
+    readonly dotRadius: 4;
+    readonly pointSize: 4;
+    readonly showTooltip: true;
 };

package/dist/components/charts/ScatterPlot/ScatterPlot.types.js

@@ -1,10 +1,17 @@
 import { CHART_DEFAULTS } from '../types/chart.types.js';
 
 /**
- * Default values using centralized defaults
+ * Default values using centralized defaults.
+ *
+ * 🔴 Picks explicitly rather than spreading `...CHART_DEFAULTS` — the spread pulled in a
+ * default for every other chart's props, so this object advertised values ScatterPlot
+ * never reads. List only what the component actually consumes.
  */
 const SCATTER_PLOT_DEFAULTS = {
-    ...CHART_DEFAULTS,
+    showGrid: CHART_DEFAULTS.showGrid,
+    showXAxis: CHART_DEFAULTS.showXAxis,
+    showYAxis: CHART_DEFAULTS.showYAxis,
+    enableKeyboardNavigation: CHART_DEFAULTS.enableKeyboardNavigation,
     dotRadius: 4,
     showTooltip: true,
 };