@flood-md/react 0.2.12 → 0.2.13

package/README.md

@@ -57,7 +57,7 @@ the interactive size. It defaults to size; shrinking a supporting glyph must
 not shrink its target or bypass IconSlot with a custom SVG width. Existing glyph
 roles at a 16px root are 2xs=14px, xs/sm=16px and md/lg=20px.
 
-This package documents the **0.2.12** source API. Keep Flood package versions aligned and follow the guide matching
+This package documents the **0.2.13** source API. Keep Flood package versions aligned and follow the guide matching
 your installed declarations; source changes do not modify an existing npm release.
 
 NavigationItem (0.2.11 candidate) is the shared small row for destinations,

package/dist/box-plot.d.ts

@@ -0,0 +1,2 @@
+import { type BoxPlotProps } from "./index.js";
+export declare const DistributionBoxes: import("react").ForwardRefExoticComponent<BoxPlotProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/box-plot.js

@@ -0,0 +1,148 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { Surface, Text, VisuallyHidden } from "./index.js";
+import { placeOverlay } from "./overlay-runtime.js";
+const number = new Intl.NumberFormat("en", { maximumSignificantDigits: 21 });
+const useChartLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+const stats = ["low", "q1", "median", "q3", "high"];
+const defaults = {
+    low: "Lower whisker", q1: "Q1", median: "Median", q3: "Q3", high: "Upper whisker", outliers: "Outliers",
+};
+const tooltipRows = [[2], [1, 3], [0, 4], [5]];
+export const DistributionBoxes = /* @__PURE__ */ forwardRef(function DistributionBoxes({ label, items, domain, formatValue = number.format, formatAxisValue = formatValue, statisticLabels, emptyLabel = "No observations", missingLabel = "No data", navigationLabel = "Use the arrow keys to explore groups, or Home and End to jump.", className, ...props }, ref) {
+    const instructions = useId();
+    const plot = useRef(null);
+    const tooltip = useRef(null);
+    const [cursor, setCursor] = useState(0);
+    const [hover, setHover] = useState();
+    const [touch, setTouch] = useState();
+    const [focused, setFocused] = useState(false);
+    const ids = new Set();
+    let min = Infinity;
+    let max = -Infinity;
+    for (const { id, label: name, summary, outliers = [] } of items) {
+        if (!id.trim() || ids.has(id) || !name.trim())
+            throw new Error("Flood BoxPlot needs unique IDs and nonempty labels");
+        ids.add(id);
+        if (!summary) {
+            if (outliers.length)
+                throw new RangeError("Flood BoxPlot outliers require a summary");
+            continue;
+        }
+        const values = stats.map(key => summary[key]);
+        if (values.some((value, i) => !Number.isFinite(value) || (i > 0 && value < values[i - 1]))) {
+            throw new RangeError("Flood BoxPlot statistics must be finite and ordered from low to high");
+        }
+        min = Math.min(min, summary.low);
+        max = Math.max(max, summary.high);
+        for (const value of outliers) {
+            if (!Number.isFinite(value) || (value >= summary.low && value <= summary.high)) {
+                throw new RangeError("Flood BoxPlot outliers must be finite and outside the whiskers");
+            }
+            min = Math.min(min, value);
+            max = Math.max(max, value);
+        }
+    }
+    if (domain && (!Number.isFinite(domain[0]) || !Number.isFinite(domain[1]) ||
+        domain[0] >= domain[1] || domain[0] > min || domain[1] < max)) {
+        throw new RangeError("Flood BoxPlot domain must have finite increasing bounds containing every observation");
+    }
+    const hasData = min <= max;
+    const [floor, ceiling] = domain ?? [min, max];
+    const span = ceiling - floor;
+    const position = (value) => {
+        if (span === 0)
+            return 50;
+        return 100 * (Number.isFinite(span) ? (value - floor) / span : (value / 2 - floor / 2) / (ceiling / 2 - floor / 2));
+    };
+    const last = items.length - 1;
+    const active = Math.min(hover ?? touch ?? cursor, last);
+    const item = items[active];
+    const summary = item?.summary;
+    const inspecting = hover !== undefined || touch !== undefined || focused;
+    const readouts = summary ? stats.map(key => ({
+        label: statisticLabels?.[key] ?? defaults[key], value: formatValue(summary[key]),
+    })) : [];
+    if (item?.outliers?.length) {
+        readouts.push({ label: statisticLabels?.outliers ?? defaults.outliers, value: number.format(item.outliers.length) });
+    }
+    const valueText = [item?.label, ...(summary ? readouts.map(entry => `${entry.label}: ${entry.value}`) : [missingLabel])].join(", ");
+    useChartLayoutEffect(() => {
+        const panel = tooltip.current;
+        const frame = plot.current;
+        if (!panel || !frame)
+            return;
+        const mark = frame.querySelector("[data-active] .flood-box-plot__median, [data-active] .flood-box-plot__missing");
+        if (!mark)
+            return;
+        const positionTooltip = () => {
+            const bounds = frame.getBoundingClientRect();
+            if (!bounds.width || !frame.offsetWidth)
+                return;
+            const marker = mark.getBoundingClientRect();
+            const scale = bounds.width / frame.offsetWidth;
+            const gap = parseFloat(getComputedStyle(panel).columnGap) * scale;
+            const size = panel.getBoundingClientRect();
+            const x = (marker.left + marker.right) / 2;
+            const y = (marker.top + marker.bottom) / 2;
+            const anchor = { left: x, right: x, top: y, bottom: y, width: 0, height: 0 };
+            const horizontalRoom = size.width + 2 * gap;
+            const side = bounds.right - x >= horizontalRoom ? "right"
+                : x - bounds.left >= horizontalRoom ? "left"
+                    : y - bounds.top < bounds.bottom - y ? "bottom" : "top";
+            const { left, top } = placeOverlay(anchor, size, bounds, side, "center", gap);
+            panel.style.left = `${(left - bounds.left) / scale}px`;
+            panel.style.top = `${(top - bounds.top) / scale}px`;
+            panel.dataset.positioned = "";
+        };
+        positionTooltip();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(positionTooltip);
+        observer.observe(frame);
+        observer.observe(panel);
+        return () => observer.disconnect();
+    }, [active, inspecting, item, formatValue, floor, ceiling]);
+    const navigate = (event) => {
+        let next;
+        switch (event.key) {
+            case "ArrowRight":
+            case "ArrowUp":
+                next = active + 1;
+                break;
+            case "ArrowLeft":
+            case "ArrowDown":
+                next = active - 1;
+                break;
+            case "Home":
+                next = 0;
+                break;
+            case "End":
+                next = last;
+                break;
+            case "Escape":
+                if (inspecting)
+                    event.preventDefault();
+                setHover(undefined);
+                setTouch(undefined);
+                setFocused(false);
+                return;
+            default: return;
+        }
+        event.preventDefault();
+        setHover(undefined);
+        setTouch(undefined);
+        setFocused(true);
+        setCursor(Math.max(0, Math.min(last, next)));
+    };
+    return _jsx("div", { ...props, ref: ref, className: ["flood-box-plot", className].filter(Boolean).join(" "), role: "group", "aria-label": label, children: hasData ? _jsxs(_Fragment, { children: [last > 0 && _jsx(VisuallyHidden, { id: instructions, children: navigationLabel }), _jsxs("div", { ref: plot, className: "flood-box-plot__plot", dir: "ltr", role: last > 0 ? "slider" : "img", tabIndex: last > 0 ? 0 : undefined, "aria-label": last > 0 ? label : `${label}. ${valueText}`, "aria-describedby": last > 0 ? instructions : undefined, "aria-valuemin": last > 0 ? 1 : undefined, "aria-valuemax": last > 0 ? items.length : undefined, "aria-valuenow": last > 0 ? active + 1 : undefined, "aria-valuetext": last > 0 ? valueText : undefined, onFocus: event => setFocused(event.currentTarget.matches(":focus-visible")), onBlur: () => setFocused(false), onKeyDown: navigate, onPointerLeave: () => setHover(undefined), children: [_jsx("div", { className: "flood-box-plot__rows", "aria-hidden": "true", children: items.map(({ id, label: name, summary: values, outliers }, index) => _jsxs("div", { className: "flood-box-plot__row", "data-active": inspecting && index === active || undefined, onPointerEnter: event => { if (event.pointerType !== "touch")
+                                    setHover(index); }, onPointerUp: event => { if (event.pointerType === "touch")
+                                    setTouch(previous => previous === index ? undefined : index); }, children: [_jsx(Text, { className: "flood-box-plot__category", size: "helper", tone: "subtle", dir: "auto", title: name, children: name }), _jsxs("div", { className: "flood-box-plot__track", children: [values && _jsxs(_Fragment, { children: [_jsx("span", { className: "flood-box-plot__whisker", "data-side": "start", style: { left: `${position(values.low)}%`, right: `${100 - position(values.q1)}%` } }), _jsx("span", { className: "flood-box-plot__whisker", "data-side": "end", style: { left: `${position(values.q3)}%`, right: `${100 - position(values.high)}%` } }), _jsx("span", { className: "flood-box-plot__box", style: { left: `${position(values.q1)}%`, right: `${100 - position(values.q3)}%` } }), _jsx("span", { className: "flood-box-plot__median", style: { left: `${position(values.median)}%` } }), outliers?.map((value, i) => _jsx("span", { className: "flood-box-plot__outlier", style: { left: `${position(value)}%` } }, i))] }), !values && _jsx("span", { className: "flood-box-plot__missing" })] })] }, id)) }), _jsxs("div", { className: "flood-box-plot__axis", "aria-hidden": "true", children: [_jsx(Text, { size: "helper", tone: "subtle", children: formatAxisValue(floor) }), floor !== ceiling && _jsxs(_Fragment, { children: [_jsx(Text, { size: "helper", tone: "subtle", children: formatAxisValue(floor / 2 + ceiling / 2) }), _jsx(Text, { size: "helper", tone: "subtle", children: formatAxisValue(ceiling) })] })] }), inspecting && item && _jsxs(Surface, { ref: tooltip, className: "flood-chart__tooltip flood-box-plot__tooltip", "aria-hidden": "true", padding: "2", elevation: "raised", children: [_jsx(Text, { size: "helper", dir: "auto", children: item.label }), summary ? tooltipRows.map(([start, end]) => {
+                                    const first = readouts[start];
+                                    if (!first)
+                                        return null;
+                                    const last = end === undefined ? undefined : readouts[end];
+                                    return _jsxs("div", { className: "flood-box-plot__reading", children: [_jsx(Text, { size: "helper", tone: "subtle", dir: "auto", children: start === 0 ? statisticLabels?.whiskers ?? "Whiskers" :
+                                                    last ? `${first.label}–${last.label}` : first.label }), _jsx(Text, { size: "helper", tone: start === 2 ? "default" : "subtle", children: last ? _jsxs(_Fragment, { children: [_jsxs("span", { children: [first.value, "\u2013"] }), _jsx("wbr", {}), _jsx("span", { children: last.value })] }) : first.value })] }, start);
+                                }) : _jsx(Text, { size: "helper", tone: "subtle", children: missingLabel })] })] })] }) : _jsx(Text, { className: "flood-box-plot__empty", size: "compact", tone: "subtle", children: emptyLabel }) });
+});

package/dist/bullet-chart.d.ts

@@ -0,0 +1,2 @@
+import { type BulletChartProps } from "./index.js";
+export declare const BulletPlot: import("react").ForwardRefExoticComponent<BulletChartProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/bullet-chart.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { Inline, Meter, Stack, Text } from "./index.js";
+const defaultNumber = new Intl.NumberFormat("en", { maximumSignificantDigits: 21 });
+export const BulletPlot = /* @__PURE__ */ forwardRef(function BulletPlot({ label, items, max, formatValue = defaultNumber.format, valueLabel = "Actual", targetLabel = "Target", emptyLabel = "No data", className, ...props }, ref) {
+    const ids = new Set();
+    let largest = 0;
+    for (const { id, label: itemLabel, value, target } of items) {
+        if (!id.trim() || ids.has(id) || !itemLabel.trim()) {
+            throw new Error("Flood BulletChart needs unique IDs and nonempty row labels");
+        }
+        if (!Number.isFinite(value) || value < 0 || !Number.isFinite(target) || target < 0) {
+            throw new RangeError("Flood BulletChart actual and target values must be finite and nonnegative");
+        }
+        ids.add(id);
+        largest = Math.max(largest, value, target);
+    }
+    const limit = max ?? (largest || 1);
+    if (!Number.isFinite(limit) || limit <= 0 || limit < largest) {
+        throw new RangeError("Flood BulletChart max must be finite, positive and at least the largest actual or target");
+    }
+    return _jsx("div", { ...props, ref: ref, className: ["flood-bullet-chart", className].filter(Boolean).join(" "), role: "group", "aria-label": label, children: items.length ? _jsx("ul", { className: "flood-bullet-chart__items", role: "list", children: items.map(item => {
+                const actual = formatValue(item.value);
+                const target = formatValue(item.target);
+                return _jsx("li", { children: _jsxs(Stack, { gap: "2", children: [_jsxs(Inline, { gap: "2", align: "baseline", className: "flood-bullet-chart__caption", "aria-hidden": "true", children: [_jsx(Text, { size: "compact", children: item.label }), _jsxs(Inline, { gap: "2", align: "baseline", className: "flood-bullet-chart__numbers", children: [_jsx(Text, { size: "compact", className: "flood-bullet-chart__actual", children: actual }), _jsxs(Text, { size: "helper", tone: "subtle", children: [targetLabel, " ", target] })] })] }), _jsxs("div", { className: "flood-bullet-chart__plot", "data-zero": item.value === 0 || undefined, children: [_jsx(Meter, { label: item.label, value: item.value, max: limit, tone: "accent", hideLabel: true, valueText: `${valueLabel}: ${actual}, ${targetLabel}: ${target}` }), _jsx("span", { "aria-hidden": "true", className: "flood-bullet-chart__target", style: { "--flood-bullet-target": `${item.target / limit * 100}%` } })] })] }) }, item.id);
+            }) }) : _jsx(Text, { size: "compact", tone: "subtle", children: emptyLabel }) });
+});

package/dist/charts.d.ts

@@ -0,0 +1,6 @@
+import { type BarChartProps, type BarListProps, type DonutChartProps, type HeatmapProps, type LineChartProps } from "./index.js";
+export declare const SeriesPlot: import("react").ForwardRefExoticComponent<LineChartProps & Required<Pick<LineChartProps, "curve" | "emptyLabel" | "missingLabel" | "navigationLabel" | "variant">> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const GroupedBars: import("react").ForwardRefExoticComponent<BarChartProps & Required<Pick<BarChartProps, "emptyLabel" | "missingLabel" | "navigationLabel">> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const ShareRing: import("react").ForwardRefExoticComponent<DonutChartProps & Required<Pick<DonutChartProps, "emptyLabel" | "navigationLabel" | "totalLabel">> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const HeatmapGrid: import("react").ForwardRefExoticComponent<HeatmapProps & Required<Pick<HeatmapProps, "emptyLabel" | "missingLabel">> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const RankedBars: import("react").ForwardRefExoticComponent<BarListProps & import("react").RefAttributes<HTMLDivElement>>;