@kind-ui/charts 0.1.0

package/dist/heatmap.js

@@ -0,0 +1,366 @@
+"use client";
+import { createElement as _createElement } from "react";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { animateMini, animate as animateValue } from "motion/react";
+import { createContext, use, useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { createHeatmapModel, } from "./heatmap-model.js";
+import { TooltipNumber } from "./tooltip-number.js";
+const HeatmapContext = createContext(null);
+function useHeatmap() {
+    const value = use(HeatmapContext);
+    if (!value)
+        throw new Error("Heatmap components require HeatmapChart");
+    return value;
+}
+const reducedQuery = "(prefers-reduced-motion: reduce)";
+function subscribeReduced(change) {
+    const media = window.matchMedia(reducedQuery);
+    media.addEventListener("change", change);
+    return () => media.removeEventListener("change", change);
+}
+const reducedSnapshot = () => window.matchMedia(reducedQuery).matches;
+const reducedServerSnapshot = () => true;
+const number = (value) => String(value);
+const keyOf = (cell) => JSON.stringify([cell.row, cell.column]);
+const pointerPosition = (event) => ({
+    pointerId: event.pointerId,
+    pointerType: event.pointerType,
+    clientX: event.clientX,
+    clientY: event.clientY,
+});
+const samePointer = (a, b) => a !== null &&
+    a.pointerId === b.pointerId &&
+    a.pointerType === b.pointerType &&
+    a.clientX === b.clientX &&
+    a.clientY === b.clientY;
+const labelOf = (cell, context) => `${cell.row}, ${cell.column}: ${cell.value === null ? context.missingLabel : context.formatValue(cell.value)}`;
+/** Native table layout owns categorical geometry. No numeric scatter approximation or SVG overlay. */
+export function HeatmapChart({ rows, columns, data, duplicates, scale, formatValue = number, missingLabel = "Missing", animate = false, children, onPointerLeave, ...props }) {
+    const model = useMemo(() => createHeatmapModel({ rows, columns, data, ...(duplicates ? { duplicates } : {}) }), [rows, columns, data, duplicates]);
+    const [active, updateActive] = useState(null);
+    const pointer = useRef(null);
+    const dismissed = useRef(false);
+    const setActive = useCallback((key) => {
+        if (key)
+            dismissed.current = false;
+        updateActive(key);
+    }, []);
+    const dismiss = useCallback(() => {
+        dismissed.current = true;
+        updateActive(null);
+    }, []);
+    const inspectPointer = useCallback((event, key) => {
+        const stationary = samePointer(pointer.current, event);
+        pointer.current = pointerPosition(event);
+        if (dismissed.current && stationary)
+            return;
+        setActive(key);
+    }, [setActive]);
+    const tooltipId = useId();
+    const [tooltipMounted, setTooltipMounted] = useState(false);
+    const reduced = useSyncExternalStore(subscribeReduced, reducedSnapshot, reducedServerSnapshot);
+    const [finished, setFinished] = useState(false);
+    const interrupt = useCallback(() => setFinished(true), []);
+    const enabled = animate && !reduced;
+    const entrance = enabled && !finished;
+    const root = useRef(null);
+    useEffect(() => {
+        if (!tooltipMounted)
+            return;
+        // Keep the Escape baseline current even before focus/hover activates a cell.
+        // Layout/scroll can send boundary events without new pointer input. Only actual
+        // movement clears dismissal, including movement outside or within an entered cell.
+        const move = (event) => {
+            const stationary = samePointer(pointer.current, event);
+            pointer.current = pointerPosition(event);
+            if (!dismissed.current || stationary)
+                return;
+            dismissed.current = false;
+            const target = event.target instanceof Element ? event.target.closest("td[data-cell-key]") : null;
+            if (!target || !root.current?.contains(target))
+                return;
+            const cell = model.cells
+                .flat()
+                .find((item) => keyOf(item) === target.getAttribute("data-cell-key"));
+            if (cell)
+                setActive([cell.row, cell.column]);
+        };
+        document.addEventListener("pointermove", move, true);
+        return () => document.removeEventListener("pointermove", move, true);
+    }, [tooltipMounted, model, setActive]);
+    const consumerRef = props.ref;
+    const ref = useCallback((node) => {
+        root.current = node;
+        if (typeof consumerRef === "function")
+            return consumerRef(node);
+        if (consumerRef)
+            consumerRef.current = node;
+    }, [consumerRef]);
+    useLayoutEffect(() => {
+        const node = root.current;
+        if (!node || !entrance)
+            return;
+        const initial = node.getBoundingClientRect();
+        const observer = new ResizeObserver(() => {
+            const next = node.getBoundingClientRect();
+            if (next.width !== initial.width || next.height !== initial.height)
+                interrupt();
+        });
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, [entrance, interrupt]);
+    const previous = useRef([model, scale, children]);
+    const previousEnabled = useRef(enabled);
+    useLayoutEffect(() => {
+        const inputs = [model, scale, children];
+        if (inputs.some((value, index) => value !== previous.current[index]) ||
+            (previousEnabled.current && !enabled))
+            interrupt();
+        previous.current = inputs;
+        previousEnabled.current = enabled;
+    });
+    useLayoutEffect(() => {
+        if (!entrance)
+            return;
+        const controls = animateValue(0, 1, { duration: 0.8, onComplete: interrupt });
+        return () => controls.stop();
+    }, [entrance, interrupt]);
+    useEffect(() => {
+        if (!active || !tooltipMounted)
+            return;
+        const keydown = (event) => {
+            if (event.key === "Escape" && !event.defaultPrevented)
+                dismiss();
+        };
+        document.addEventListener("keydown", keydown);
+        return () => document.removeEventListener("keydown", keydown);
+    }, [active, tooltipMounted, dismiss]);
+    return (_jsx(HeatmapContext, { value: {
+            model,
+            entrance,
+            scale,
+            formatValue,
+            missingLabel,
+            active,
+            setActive,
+            dismiss,
+            inspectPointer,
+            tooltipId,
+            tooltipMounted,
+            setTooltipMounted,
+        }, children: _jsx("div", { ...props, ref: ref, "data-kind-ui": "heatmap", onFocusCapture: (event) => {
+                props.onFocusCapture?.(event);
+                interrupt();
+            }, onPointerMoveCapture: (event) => {
+                props.onPointerMoveCapture?.(event);
+                interrupt();
+            }, onPointerDownCapture: (event) => {
+                props.onPointerDownCapture?.(event);
+                interrupt();
+            }, onKeyDownCapture: (event) => {
+                props.onKeyDownCapture?.(event);
+                interrupt();
+            }, onPointerLeave: (event) => {
+                onPointerLeave?.(event);
+                if (!active)
+                    return;
+                const focused = document.activeElement;
+                const cell = event.currentTarget.contains(focused)
+                    ? model.cells.flat().find((item) => keyOf(item) === focused?.dataset.cellKey)
+                    : undefined;
+                setActive(cell ? [cell.row, cell.column] : null);
+            }, children: _jsx("div", { "data-kind-ui": "heatmap-entrance", children: children }) }) }));
+}
+// A native cell keeps its styles, ref and handlers. Motion temporarily multiplies its opacity.
+function EntranceCell({ diagonal, ...props }) {
+    const { entrance, model } = useHeatmap();
+    const cell = useRef(null);
+    const consumerRef = props.ref;
+    const ref = useCallback((node) => {
+        cell.current = node;
+        if (typeof consumerRef === "function")
+            return consumerRef(node);
+        if (consumerRef)
+            consumerRef.current = node;
+    }, [consumerRef]);
+    const latestOpacity = useRef(props.style?.opacity);
+    latestOpacity.current = props.style?.opacity;
+    useLayoutEffect(() => {
+        const node = cell.current;
+        if (!node || !entrance)
+            return;
+        const original = node.style.opacity;
+        const declaredOpacity = props.style?.opacity;
+        const opacity = Number(getComputedStyle(node).opacity);
+        const delay = (diagonal / Math.max(1, model.rows.length + model.columns.length - 2)) * 0.55;
+        const controls = animateMini(node, { opacity: [0, opacity] }, { delay, duration: 0.25, ease: "easeOut" });
+        return () => {
+            controls.stop();
+            node.style.opacity = Object.is(latestOpacity.current, declaredOpacity)
+                ? original
+                : latestOpacity.current === undefined
+                    ? ""
+                    : String(latestOpacity.current);
+        };
+    }, [entrance, diagonal, model, props.style?.opacity]);
+    return _jsx("td", { ...props, ref: ref, "data-kind-ui": "heatmap-cell-entrance" });
+}
+export function HeatmapCellContent({ fill, formattedValue }) {
+    const channels = /^#[0-9a-f]{6}$/i.test(fill)
+        ? [1, 3, 5].map((i) => {
+            const value = Number.parseInt(fill.slice(i, i + 2), 16) / 255;
+            return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+        })
+        : [1, 1, 1];
+    const luminance = (channels[0] ?? 1) * 0.2126 + (channels[1] ?? 1) * 0.7152 + (channels[2] ?? 1) * 0.0722;
+    return (_jsx("span", { style: {
+            color: /^#[0-9a-f]{6}$/i.test(fill)
+                ? luminance > 0.179
+                    ? "#000000"
+                    : "#ffffff"
+                : "var(--heatmap-missing-foreground, #172033)",
+        }, children: formattedValue }));
+}
+export function HeatmapGrid({ caption, material = "plain", layout, Cell = HeatmapCellContent, cellProps, rowLabel, columnLabel, onKeyDown, onBlur, onPointerLeave, style, ...props }) {
+    const context = useHeatmap();
+    const headerId = useId();
+    for (const [name, value] of [
+        ["cellSize", layout?.cellSize],
+        ["gap", layout?.gap],
+    ]) {
+        if (typeof value === "number" &&
+            (!Number.isFinite(value) || (name === "cellSize" ? value <= 0 : value < 0))) {
+            throw new Error(`HeatmapGrid layout.${name} must be finite and ${name === "cellSize" ? "positive" : "nonnegative"}`);
+        }
+    }
+    const length = (value) => typeof value === "number" ? `${value}px` : value;
+    const { model, scale, active, setActive, tooltipId } = context;
+    const [focusedKey, setFocusedKey] = useState(null);
+    const table = useRef(null);
+    const focused = model.cells.flat().find((cell) => keyOf(cell) === focusedKey) ?? model.cells[0]?.[0];
+    const tabKey = focused ? keyOf(focused) : null;
+    function move(event) {
+        onKeyDown?.(event);
+        if (event.defaultPrevented)
+            return;
+        const target = event.target;
+        if (!(target instanceof HTMLTableCellElement) || target.dataset.cellKey === undefined)
+            return;
+        const cell = model.cells.flat().find((item) => keyOf(item) === target.dataset.cellKey);
+        if (!cell)
+            return;
+        let r = cell.rowIndex;
+        let c = cell.columnIndex;
+        switch (event.key) {
+            case "ArrowRight":
+                c++;
+                break;
+            case "ArrowLeft":
+                c--;
+                break;
+            case "ArrowDown":
+                r++;
+                break;
+            case "ArrowUp":
+                r--;
+                break;
+            case "Home":
+                c = 0;
+                if (event.ctrlKey)
+                    r = 0;
+                break;
+            case "End":
+                c = model.columns.length - 1;
+                if (event.ctrlKey)
+                    r = model.rows.length - 1;
+                break;
+            case "Escape":
+                context.dismiss();
+                event.preventDefault();
+                return;
+            default:
+                return;
+        }
+        event.preventDefault();
+        r = Math.max(0, Math.min(r, model.rows.length - 1));
+        c = Math.max(0, Math.min(c, model.columns.length - 1));
+        const next = model.cells[r]?.[c];
+        if (next) {
+            const element = Array.from(table.current?.querySelectorAll("td[data-cell-key]") ?? []).find((td) => td.dataset.cellKey === keyOf(next));
+            if (element) {
+                setActive([next.row, next.column]);
+                element.focus();
+            }
+        }
+    }
+    return (_jsxs("div", { "data-kind-ui": "heatmap-scroll", children: [_jsxs("table", { ...props, ref: (node) => {
+                    table.current = node;
+                    if (typeof props.ref === "function")
+                        return props.ref(node);
+                    if (props.ref)
+                        props.ref.current = node;
+                }, 
+                // biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: WAI-ARIA APG data grid uses a native table with roving cell focus.
+                role: "grid", "aria-label": caption, "data-kind-ui": "heatmap-grid", "data-cell-sizing": layout?.cellSize === undefined ? undefined : "fixed", "data-row-labels": layout?.rowLabels, "data-column-labels": layout?.columnLabels, style: {
+                    "--heatmap-columns": model.columns.length,
+                    ...(layout?.cellSize === undefined
+                        ? {}
+                        : { "--heatmap-cell-size": length(layout.cellSize) }),
+                    ...(layout?.gap === undefined ? {} : { "--heatmap-gap": length(layout.gap) }),
+                    ...style,
+                }, onKeyDown: move, onBlur: (event) => {
+                    onBlur?.(event);
+                    if (!event.currentTarget.contains(event.relatedTarget))
+                        setActive(null);
+                }, onPointerLeave: onPointerLeave, children: [_jsx("caption", { children: caption }), layout?.cellSize === undefined ? null : (_jsxs("colgroup", { children: [_jsx("col", { "data-kind-ui": "heatmap-row-column" }), model.columns.map((column) => (_jsx("col", {}, column)))] })), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Row / column" }), model.columns.map((column, c) => (_jsx("th", { scope: "col", id: `${headerId}-column-${c}`, children: columnLabel?.(column) ?? column }, column)))] }) }), _jsx("tbody", { children: model.rows.map((row, r) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", id: `${headerId}-row-${r}`, children: _jsx("span", { "data-kind-ui": "heatmap-row-label", title: row, children: rowLabel?.(row) ?? row }) }), model.cells[r]?.map((cell, c) => {
+                                    const extra = cellProps?.(cell) ?? {};
+                                    const fill = cell.value === null ? "var(--heatmap-missing, #e5e7eb)" : scale.color(cell.value);
+                                    const formattedValue = cell.value === null ? context.missingLabel : context.formatValue(cell.value);
+                                    return (_createElement(EntranceCell, { diagonal: r + c, ...extra, key: cell.column, role: "gridcell", headers: `${headerId}-row-${r} ${headerId}-column-${c}`, "data-cell-key": keyOf(cell), "data-missing": cell.value === null ? "true" : "false", "data-material": cell.value === null ? undefined : material, tabIndex: keyOf(cell) === tabKey ? 0 : -1, "aria-label": labelOf(cell, context), "aria-describedby": context.tooltipMounted &&
+                                            active?.[0] === cell.row &&
+                                            active[1] === cell.column
+                                            ? tooltipId
+                                            : undefined, style: { ...extra.style, backgroundColor: fill }, onFocus: (event) => {
+                                            extra.onFocus?.(event);
+                                            setFocusedKey(keyOf(cell));
+                                            setActive([cell.row, cell.column]);
+                                        }, onPointerDown: (event) => {
+                                            extra.onPointerDown?.(event);
+                                            // A press is deliberate even at the dismissed pointer position.
+                                            setActive([cell.row, cell.column]);
+                                        }, onPointerEnter: (event) => {
+                                            extra.onPointerEnter?.(event);
+                                            context.inspectPointer(event, [cell.row, cell.column]);
+                                        } },
+                                        _jsx(Cell, { cell: cell, fill: fill, formattedValue: formattedValue })));
+                                })] }, row))) })] }), model.rows.length === 0 || model.columns.length === 0 ? (_jsx("p", { "data-kind-ui": "heatmap-empty", children: "No cells in the selected domains." })) : null] }));
+}
+/** In-flow tooltip stays within narrow containers and remains available for hover, focus and touch. */
+export function HeatmapTooltip({ Content, valueAnimation, ...props }) {
+    const context = useHeatmap();
+    useEffect(() => {
+        context.setTooltipMounted(true);
+        return () => context.setTooltipMounted(false);
+    }, [context.setTooltipMounted]);
+    const cell = context.model.cells
+        .flat()
+        .find((item) => item.row === context.active?.[0] && item.column === context.active[1]);
+    return (_jsx("div", { ...props, id: context.tooltipId, role: "tooltip", "data-kind-ui": "heatmap-tooltip", hidden: !cell, children: cell ? (Content ? (_jsx(Content, { cell: cell, fill: cell.value === null
+                ? "var(--heatmap-missing, #e5e7eb)"
+                : context.scale.color(cell.value), formattedValue: cell.value === null ? context.missingLabel : context.formatValue(cell.value) })) : valueAnimation === "shuffle" && cell.value !== null && Number.isFinite(cell.value) ? (_jsxs(_Fragment, { children: [`${cell.row}, ${cell.column}: `, _jsx(TooltipNumber, { value: context.formatValue(cell.value) })] })) : (labelOf(cell, context))) : null }));
+}
+export function HeatmapLegend({ label, ...props }) {
+    const { scale, formatValue, missingLabel } = useHeatmap();
+    const [min, max] = scale.domain;
+    return (_jsxs("fieldset", { ...props, "data-kind-ui": "heatmap-legend", "aria-label": `${label}: ${formatValue(min)} to ${formatValue(max)}; ${missingLabel}`, children: [_jsx("legend", { children: label }), _jsx("div", { "data-kind-ui": "heatmap-ramp", "aria-hidden": "true", style: {
+                    background: min === max
+                        ? scale.color(min)
+                        : `linear-gradient(to right in srgb, ${scale.colors.join(", ")})`,
+                }, children: min < 0 && max > 0 ? (_jsx("i", { "data-kind-ui": "heatmap-zero-marker", style: { left: `${(-min / (max - min)) * 100}%` } })) : null }), _jsxs("div", { "data-kind-ui": "heatmap-ticks", children: [_jsx("span", { children: formatValue(min) }), _jsx("span", { children: formatValue(max) })] }), min < 0 && max > 0 ? (_jsxs("span", { "data-kind-ui": "heatmap-zero-label", children: ["Zero marker: ", formatValue(0)] })) : null, _jsxs("span", { "data-kind-ui": "heatmap-missing-key", children: [_jsx("i", { "aria-hidden": "true" }), missingLabel] })] }));
+}
+/** Independent static native table; the host decides whether it is visible or in a details disclosure. */
+export function HeatmapDataTable({ caption, ...props }) {
+    const context = useHeatmap();
+    const { model, formatValue, missingLabel } = context;
+    return (_jsx("div", { "data-kind-ui": "heatmap-scroll", children: _jsxs("table", { ...props, "data-kind-ui": "heatmap-data-table", children: [_jsx("caption", { children: caption }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Row / column" }), model.columns.map((column) => (_jsx("th", { scope: "col", children: column }, column)))] }) }), _jsx("tbody", { children: model.rows.map((row, r) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: row }), model.cells[r]?.map((cell) => (_jsx("td", { children: cell.value === null ? missingLabel : formatValue(cell.value) }, cell.column)))] }, row))) })] }) }));
+}

package/dist/histogram-chart.d.ts

@@ -0,0 +1,14 @@
+import { type ComponentProps } from "react";
+import { XAxis, YAxis } from "recharts";
+import { type BarChartProps } from "./bar-chart.js";
+import { type HistogramBin, type HistogramMeasure } from "./histogram-data.js";
+export type HistogramChartProps = Omit<BarChartProps, "data" | "layout" | "stackOffset" | "barSize" | "barCategoryGap" | "barGap" | "reverseStackOrder"> & {
+    bins: readonly HistogramBin[];
+    /** Required: count height or normalized probability density (area sums to one). */
+    measure: HistogramMeasure;
+    xAxisProps?: Omit<ComponentProps<typeof XAxis>, "dataKey" | "type" | "domain" | "scale" | "xAxisId" | "allowDataOverflow" | "reversed">;
+    yAxisProps?: Omit<ComponentProps<typeof YAxis>, "dataKey" | "type" | "domain" | "scale" | "yAxisId" | "allowDataOverflow" | "reversed">;
+};
+export declare const HistogramContext: import("react").Context<HistogramMeasure | null>;
+/** Bounded vertical histogram; quantitative axes are owned here, native children compose. */
+export declare function HistogramChart({ bins, measure, xAxisProps, yAxisProps, children, ...props }: HistogramChartProps): import("react").JSX.Element;

package/dist/histogram-chart.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useMemo } from "react";
+import { XAxis, YAxis } from "recharts";
+import { BarChart } from "./bar-chart.js";
+import { validateHistogram } from "./histogram-data.js";
+export const HistogramContext = createContext(null);
+/** Bounded vertical histogram; quantitative axes are owned here, native children compose. */
+export function HistogramChart({ bins, measure, xAxisProps, yAxisProps, children, ...props }) {
+    const total = validateHistogram(bins);
+    if (measure !== "count" && measure !== "density")
+        throw new Error("Histogram requires count or density measure");
+    const data = useMemo(() => bins.map((bin) => {
+        const value = measure === "count"
+            ? bin.count
+            : total === 0
+                ? 0
+                : bin.count / total / (bin.upper - bin.lower);
+        if (!Number.isFinite(value) || (bin.count > 0 && value === 0))
+            throw new Error("Histogram density exceeds finite positive numeric range");
+        return { ...bin, midpoint: bin.lower + (bin.upper - bin.lower) / 2, value };
+    }), [bins, measure, total]);
+    const domain = bins.length ? [bins[0]?.lower ?? 0, bins[bins.length - 1]?.upper ?? 1] : [0, 1];
+    if (!Number.isFinite((domain[1] ?? 1) - (domain[0] ?? 0)))
+        throw new Error("Histogram domain must have a finite span");
+    return (_jsx(HistogramContext, { value: measure, children: _jsxs(BarChart, { ...props, data: data, layout: "horizontal", barCategoryGap: 0, barGap: 0, children: [_jsx(XAxis, { ...xAxisProps, xAxisId: 0, dataKey: "midpoint", type: "number", scale: "linear", domain: domain, allowDataOverflow: true, reversed: false }), _jsx(YAxis, { ...yAxisProps, yAxisId: 0, type: "number", scale: "linear", domain: [0, "dataMax"], reversed: false }), children] }) }));
+}

package/dist/histogram-data.d.ts

@@ -0,0 +1,17 @@
+/** One pre-aggregated interval. Counts are nonnegative safe integers. */
+export type HistogramBin = Readonly<{
+    lower: number;
+    upper: number;
+    count: number;
+}>;
+export type HistogramMeasure = "count" | "density";
+export type HistogramBinningResult = Readonly<{
+    bins: readonly HistogramBin[];
+    accepted: number;
+    missing: number;
+    nonfinite: number;
+    outOfRange: number;
+}>;
+/** Explicit edges only; no inferred domain, rounding, coercion or statistical estimator. */
+export declare function binHistogram(samples: readonly (number | null | undefined)[], edges: readonly number[]): HistogramBinningResult;
+export declare function validateHistogram(bins: readonly HistogramBin[]): number;

package/dist/histogram-data.js

@@ -0,0 +1,66 @@
+/** Explicit edges only; no inferred domain, rounding, coercion or statistical estimator. */
+export function binHistogram(samples, edges) {
+    if (edges.length < 2)
+        throw new Error("Histogram requires at least two edges");
+    const bins = edges.slice(0, -1).map((lower, index) => ({
+        lower,
+        upper: edges[index + 1],
+        count: 0,
+    }));
+    validateHistogram(bins);
+    let accepted = 0;
+    let missing = 0;
+    let nonfinite = 0;
+    let outOfRange = 0;
+    const first = edges[0];
+    const last = edges[edges.length - 1];
+    for (const sample of samples) {
+        if (sample == null) {
+            missing++;
+            continue;
+        }
+        if (typeof sample !== "number" || !Number.isFinite(sample)) {
+            nonfinite++;
+            continue;
+        }
+        if (sample < first || sample > last) {
+            outOfRange++;
+            continue;
+        }
+        // Upper-bound search assigns an interior edge to its right-hand bin.
+        let low = 0;
+        let high = edges.length;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if (sample < edges[middle])
+                high = middle;
+            else
+                low = middle + 1;
+        }
+        const bin = bins[Math.min(low - 1, bins.length - 1)];
+        if (bin)
+            bin.count++;
+        accepted++;
+    }
+    return { bins, accepted, missing, nonfinite, outOfRange };
+}
+export function validateHistogram(bins) {
+    let total = 0;
+    let previousUpper;
+    for (const bin of bins) {
+        if (!Number.isFinite(bin.lower) ||
+            !Number.isFinite(bin.upper) ||
+            !(bin.upper > bin.lower) ||
+            !Number.isFinite(bin.upper - bin.lower))
+            throw new Error("Histogram bounds must be finite with positive finite width");
+        if (previousUpper !== undefined && bin.lower < previousUpper)
+            throw new Error("Histogram bins must be ordered and nonoverlapping");
+        if (!Number.isSafeInteger(bin.count) || bin.count < 0)
+            throw new Error("Histogram counts must be nonnegative safe integers");
+        total += bin.count;
+        if (!Number.isSafeInteger(total))
+            throw new Error("Histogram total exceeds safe integer range");
+        previousUpper = bin.upper;
+    }
+    return total;
+}

package/dist/histogram-material.d.ts

@@ -0,0 +1,13 @@
+import type { BarMaterial } from "./bar-material.js";
+/** Reuse bar surface paint, with no cast shade across quantitative interval edges. */
+export declare function HistogramMaterialFilter({ material, id, bounds, padding, }: {
+    material: Exclude<BarMaterial, "plain">;
+    id: string;
+    padding: number;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}): import("react").JSX.Element;

package/dist/histogram-material.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { BarClay } from "./bar-clay.js";
+import { BarPaper } from "./bar-paper.js";
+/** Reuse bar surface paint, with no cast shade across quantitative interval edges. */
+export function HistogramMaterialFilter({ material, id, bounds, padding, }) {
+    return (_jsx("filter", { id: id, filterUnits: "userSpaceOnUse", primitiveUnits: "userSpaceOnUse", x: bounds.x - padding, y: bounds.y - padding, width: bounds.width + padding * 2, height: bounds.height + padding * 2, colorInterpolationFilters: "sRGB", children: material === "paper" ? (_jsx(BarPaper, {})) : material === "clay" ? (_jsxs(_Fragment, { children: [_jsx(BarClay, { horizontal: false }), _jsx("feComposite", { in2: "footprint", operator: "in" })] })) : (_jsxs(_Fragment, { children: [_jsx("feComponentTransfer", { in: "SourceAlpha", result: "footprint", children: _jsx("feFuncA", { type: "linear", slope: 100000 }) }), _jsx("feGaussianBlur", { in: "SourceGraphic", stdDeviation: 2.5, result: "halo" }), _jsx("feFlood", { floodOpacity: "var(--kind-ui-bar-glow-opacity, 0.6)", result: "strength" }), _jsx("feComposite", { in: "halo", in2: "strength", operator: "in", result: "softHalo" }), _jsx("feComposite", { in: "softHalo", in2: "footprint", operator: "out", result: "unpaintedHalo" }), _jsx("feFlood", { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height, floodColor: "#fff", result: "binBounds" }), _jsx("feComposite", { in: "unpaintedHalo", in2: "binBounds", operator: "out", result: "exteriorHalo" }), _jsx("feMorphology", { in: "footprint", operator: "erode", radius: 1.5, result: "inside" }), _jsx("feComposite", { in: "footprint", in2: "inside", operator: "out", result: "edge" }), _jsx("feFlood", { floodColor: "var(--kind-ui-bar-glow-light, #fff)", floodOpacity: 0.75 }), _jsx("feComposite", { in2: "edge", operator: "in", result: "light" }), _jsx("feComposite", { in: "light", in2: "SourceGraphic", operator: "atop", result: "body" }), _jsx("feGaussianBlur", { in: "light", stdDeviation: 1.5, result: "innerLight" }), _jsx("feComposite", { in: "innerLight", in2: "body", operator: "atop", result: "litBody" }), _jsxs("feMerge", { children: [_jsx("feMergeNode", { in: "exteriorHalo" }), _jsx("feMergeNode", { in: "litBody" })] })] })) }));
+}

package/dist/histogram-series.d.ts

@@ -0,0 +1,16 @@
+import { type ReactElement } from "react";
+import { type BarShapeProps } from "recharts";
+import type { BarMaterial } from "./bar-material.js";
+import { type BarSeriesProps } from "./bar-series.js";
+import type { HistogramBin } from "./histogram-data.js";
+export type HistogramShapeProps = BarShapeProps & {
+    bin: HistogramBin;
+};
+export type HistogramSeriesProps = Omit<BarSeriesProps, "data" | "dataKey" | "shape" | "activeBar" | "background" | "stackId" | "minPointSize" | "maxBarSize" | "barSize" | "xAxisId" | "yAxisId" | "material" | "label"> & {
+    /** Static finish on corrected native bin rectangles; custom paint retains ownership. */
+    material?: BarMaterial | undefined;
+    /** Native shape extension with corrected quantitative x/width and original bin. */
+    shape?: ((props: HistogramShapeProps) => ReactElement) | undefined;
+};
+/** Reuses Bar visibility, native events/Cells, shared tooltip and interrupted/reduced Motion. */
+export declare function HistogramSeries({ shape, material, seriesKey, ...props }: HistogramSeriesProps): import("react").JSX.Element;

package/dist/histogram-series.js

@@ -0,0 +1,67 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cloneElement, use, useId, useLayoutEffect, useRef, useState, } from "react";
+import { Rectangle, useXAxisScale } from "recharts";
+import { BarSeries } from "./bar-series.js";
+import { HistogramContext } from "./histogram-chart.js";
+import { HistogramMaterialFilter } from "./histogram-material.js";
+/** Resolve native CSS paint extent before the browser paints the material. */
+function HistogramPaint({ rectangle, material, bounds, }) {
+    const id = `kind-ui-histogram-${useId().replace(/[^a-zA-Z0-9_-]/g, "_")}-material`;
+    const group = useRef(null);
+    const [padding, setPadding] = useState(8);
+    useLayoutEffect(() => {
+        const path = group.current?.querySelector("path");
+        if (!path)
+            return;
+        const stroke = getComputedStyle(path).strokeWidth;
+        let width = Number.parseFloat(stroke);
+        if (stroke.endsWith("%")) {
+            const svg = path.ownerSVGElement;
+            const viewBox = svg?.viewBox.baseVal;
+            const width = viewBox?.width || svg?.clientWidth || 0;
+            const height = viewBox?.height || svg?.clientHeight || 0;
+            const diagonal = Math.hypot(width, height) / Math.SQRT2;
+            // SVG percentage stroke widths use the normalized viewport diagonal.
+            const percentage = Number.parseFloat(stroke);
+            const resolved = (percentage / 100) * diagonal;
+            setPadding(8 + (Number.isFinite(resolved) ? Math.max(0, resolved) / 2 : 0));
+        }
+        else {
+            width = Number.isFinite(width) ? Math.max(0, width) : 0;
+            setPadding(8 + width / 2);
+        }
+    });
+    return (_jsxs("g", { ref: group, children: [_jsx("defs", { "data-kind-ui": "histogram-material", "data-material": material, pointerEvents: "none", children: _jsx(HistogramMaterialFilter, { material: material, id: id, bounds: bounds, padding: padding }) }), cloneElement(rectangle, { filter: `url(#${id})` })] }));
+}
+function HistogramShape({ shape, material, ...props }) {
+    const scale = useXAxisScale(0);
+    const bin = props.payload;
+    const start = scale?.(bin.lower);
+    const end = scale?.(bin.upper);
+    if (start === undefined || end === undefined || !Number.isFinite(start) || !Number.isFinite(end))
+        return null;
+    const geometry = { ...props, x: Math.min(start, end), width: Math.abs(end - start), bin };
+    if (shape)
+        return shape(geometry);
+    const materialized = material !== undefined &&
+        material !== "plain" &&
+        props.filter === undefined &&
+        props.style?.filter === undefined &&
+        (props.height ?? 0) > 0 &&
+        geometry.width > 0;
+    const rectangle = (_jsx(Rectangle, { ...props, x: geometry.x, width: geometry.width, radius: 0, "data-kind-ui": "histogram-bin", "data-lower": bin.lower, "data-upper": bin.upper, "data-count": bin.count }));
+    return materialized ? (_jsx(HistogramPaint, { rectangle: rectangle, material: material, bounds: { x: geometry.x, y: props.y ?? 0, width: geometry.width, height: props.height ?? 0 } })) : (rectangle);
+}
+/** Reuses Bar visibility, native events/Cells, shared tooltip and interrupted/reduced Motion. */
+export function HistogramSeries({ shape, material = "plain", seriesKey = "count", ...props }) {
+    const measure = use(HistogramContext);
+    if (measure === null)
+        throw new Error("HistogramSeries requires HistogramChart");
+    const materialized = material !== "plain" &&
+        shape === undefined &&
+        props.filter === undefined &&
+        props.style?.filter === undefined;
+    const renderShape = (native) => (_jsx(HistogramShape, { ...native, shape: shape, material: materialized ? material : undefined }));
+    return (_jsx(BarSeries, { ...props, seriesKey: seriesKey, dataKey: "value", xAxisId: 0, yAxisId: 0, minPointSize: 0, shape: renderShape, activeBar: renderShape }));
+}