The Open Standard for Generative UI
import { useMemo, useRef } from "react";
import type { ChartColorPalette } from "../../../ThemeProvider";
import { useTheme } from "../../../ThemeProvider";
import type { FunnelOrientation } from "../../FunnelChart/parts/funnelGeometry";
import { formatFunnelPercentage, funnelPercentage } from "../../FunnelChart/parts/funnelGeometry";
import type { TooltipItem } from "../../shared/core/PortalTooltip/ChartTooltip";
import type { ChartData, LegendItem } from "../../types";
import { buildContainerStyle } from "../../utils/buildContainerStyle";
import { DEFAULT_CHART_HEIGHT } from "../../utils/constants";
import { buildColumnKeys } from "../../utils/heatmapUtils";
import { parseLineHeight } from "../../utils/labelWrap";
import { resolvePalette } from "../../utils/paletteUtils";
import { MAX_X_AXIS_HEIGHT_SHARE } from "../../utils/xAxisLabelLayout";
import { useCanvasContextForLabelSize } from "../core/useCanvasContextForLabelSize";
import { useChartShell } from "../core/useChartShell";
import { usePerElementHover } from "../core/usePerElementHover";
import { useSeriesVisibility } from "../core/useSeriesVisibility";
import { useAutoAngleCalculation } from "./useAutoAngleCalculation";
import { useMaxLabelWidth } from "./useMaxLabelWidth";
// Gap between the funnel plot and its label band/column.
const LABEL_GAP = 6;
// The vertical label column is at most this fraction of the container width…
const MAX_LABEL_COL_RATIO = 0.34;
// …but the cap never drops below this floor (so a tiny container still leaves a
// usable column). NOTE: this floors the CAP, not the column — short labels
// produce a narrower content-fit column.
const MAX_LABEL_COL_FLOOR = 64;
/** A stage's numeric value; non-numeric / missing collapses to 0 (no taper). */
const funnelStageValue = (raw: string | number | undefined): number => {
const value = Number(raw);
return Number.isFinite(value) ? value : 0;
};
export interface FunnelStage {
/** Unique React key (duplicate labels disambiguated); NOT for display. */
key: string;
label: string;
value: number;
color: string;
/** value / geometry-max, clamped to [0, 1] — the cell's leading-edge ratio. */
norm: number;
/** The NEXT visible stage's norm — the cell's trailing-edge ratio (taper). */
normEnd: number;
/** Percentage relative to the FIRST visible stage (retention). */
pct: number;
}
export interface UseFunnelChartOrchestratorParams<T extends ChartData> {
data: T;
categoryKey: keyof T[number];
dataKey: keyof T[number];
themePaletteName: keyof ChartColorPalette;
customPalette?: string[];
orientation: FunnelOrientation;
/** Gap between stage cells (px) — matches the painter so the label-angle
* threshold uses the painter's true cell width. */
gap: number;
/** Whether labels render — gates the reserved label band/column. */
showLabels: boolean;
showLegend: boolean;
height?: number | string;
width?: number | string;
fitLegendInHeight?: boolean;
}
/**
* Orchestrator for the funnel: a single-series chart of stacked tapering
* stages. Standalone fit-only layout (heatmap/scatter precedent) — no axes, so
* the plot is simply the container minus the legend. The palette is consumed
* as an ORDERED ramp via resolvePalette (one hue per stage, by INPUT order —
* never getDistributedColors, which value-sorts + center-out picks). Stage
* colors are keyed to the ORIGINAL data index so toggling a stage in the
* legend never recolors the others. Hover is per-stage (the painter owns the
* mouse handlers; mouse-only, like pie/heatmap).
*/
export function useFunnelChartOrchestrator<T extends ChartData>({
data,
categoryKey,
dataKey,
themePaletteName,
customPalette,
orientation,
gap,
showLabels,
showLegend,
height,
width,
fitLegendInHeight,
}: UseFunnelChartOrchestratorParams<T>) {
const containerRef = useRef<HTMLDivElement>(null);
const legendRef = useRef<HTMLDivElement>(null);
const {
hovered: hoveredIndex,
mousePos,
handleMouseMove,
handleMouseLeave,
} = usePerElementHover();
const {
isPrinting,
containerWidth,
containerHeight,
isEmpty,
legendHeight,
shouldFitLegend,
isLegendExpanded,
setIsLegendExpanded,
} = useChartShell({
data,
showLegend,
containerRef,
legendRef,
width,
height,
fitLegendInHeight,
});
// For the label line-height (sizing the reserved band). Hydration-safe (SSR
// stub through the hydration render), so no server/client mismatch.
const context = useCanvasContextForLabelSize(containerRef);
const { theme } = useTheme();
const catKey = String(categoryKey);
const valKey = String(dataKey);
// Ordered ramp, one hue per stage by INPUT order.
const ramp = useMemo(
() => resolvePalette(theme, themePaletteName, customPalette),
[theme, themePaletteName, customPalette],
);
// Every stage with its stable color (keyed to original index so a legend
// toggle never recolors the rest).
const allStages = useMemo(
() =>
data.map((row, i) => ({
label: String(row[catKey]),
value: funnelStageValue(row[valKey]),
color: ramp[i % ramp.length] ?? "#000000",
})),
[data, catKey, valKey, ramp],
);
const stageLabels = useMemo(() => allStages.map((s) => s.label), [allStages]);
const { hiddenSeries: hiddenStages, toggleSeries: toggleStage } =
useSeriesVisibility(stageLabels);
// Visible stages (input order preserved) + the parallel original rows for
// onClick. norms are computed over the VISIBLE sequence: the geometry-max is
// the largest visible value (guarantees rings fit, even for non-monotonic
// edge data) while the percentage reference is the FIRST visible stage.
const { visibleStages, visibleRows } = useMemo(() => {
const rows: T[number][] = [];
const kept = allStages.filter((s, i) => {
if (hiddenStages.has(s.label)) return false;
rows.push(data[i]!);
return true;
});
const geomMax = Math.max(1, ...kept.map((s) => Math.max(0, s.value)));
// `||`, NOT `??`: a first-stage value of 0 (e.g. a partial streamed row
// whose value field hasn't parsed yet) must fall back to the geometry-max
// — `??` only catches null/undefined, so a real 0 would make every
// percentage read 0%. Falsy-0 is exactly the case to catch here.
const pctRef = kept[0]?.value || geomMax;
// Unique React keys for duplicate stage labels (LLMs re-emit categories) —
// a NUL-suffixed occurrence counter, like the heatmap's columns. Stable
// across streamed appends so existing stages never re-key (no entrance
// replay). `label` stays the display string.
const renderKeys = buildColumnKeys(kept.map((s) => s.label));
const stages: FunnelStage[] = kept.map((s, i) => {
// The trailing edge tapers toward the next stage; the last stage is a
// flat rect (its "next" is itself, so normEnd === norm).
const nextIdx = Math.min(i + 1, kept.length - 1);
return {
key: renderKeys[i]!,
label: s.label,
value: s.value,
color: s.color,
norm: Math.max(0, s.value) / geomMax,
normEnd: Math.max(0, kept[nextIdx]!.value) / geomMax,
pct: funnelPercentage(s.value, pctRef),
};
});
return { visibleStages: stages, visibleRows: rows };
}, [allStages, hiddenStages, data]);
// --- Tooltip: value + retention for the hovered stage ---
const tooltipPayload = useMemo(() => {
if (hoveredIndex === null) return null;
const stage = visibleStages[hoveredIndex];
if (!stage) return null;
const items: TooltipItem[] = [
{ name: "Value", value: stage.value, color: stage.color },
{
name: "Of first stage",
value: formatFunnelPercentage(stage.pct),
color: stage.color,
},
];
return { label: stage.label, items };
}, [hoveredIndex, visibleStages]);
// --- Legend: one item per stage (all stages, so hidden ones can return) ---
const legendItems: LegendItem[] = useMemo(
() => allStages.map((s) => ({ key: s.label, label: s.label, color: s.color })),
[allStages],
);
// --- Dimensions (the stage labels are a reserved axis: a bottom band for
// horizontal, a right column for vertical — like the heatmap's X/Y axes) ---
const effectiveHeight = containerHeight || (typeof height === "number" ? height : 0);
const totalHeight = effectiveHeight || DEFAULT_CHART_HEIGHT;
const legendDeduction = showLegend && shouldFitLegend ? legendHeight : 0;
const W = containerWidth || 0;
const H = Math.max(0, totalHeight - legendDeduction);
const horizontal = orientation === "horizontal";
// Max label width over ALL stages (not just visible) so toggling a stage in
// the legend never reflows the axis band.
const maxLabelWidth = useMaxLabelWidth(data, catKey);
const visibleCount = Math.max(1, visibleStages.length);
// Each horizontal label gets one cell's width before it must angle — the
// SAME width the painter tiles to (gap-subtracted), or the angle threshold
// and the painter's truncation disagree.
const perStageWidth =
horizontal && W > 0 ? Math.max(0, (W - gap * (visibleCount - 1)) / visibleCount) : 0;
const { angle: labelAngle, height: angledHeight } = useAutoAngleCalculation(
maxLabelWidth,
showLabels && horizontal && maxLabelWidth > perStageWidth,
perStageWidth,
);
// Single-line band height from the theme's label line-height (not a magic
// number) so a larger label font doesn't clip the bottom of the labels.
const singleLineLabelHeight = Math.ceil(parseLineHeight(context.font));
// Reserved label band (horizontal: bottom) / column (vertical: right). No
// reservation when labels are hidden — the funnel reclaims the full area.
// The band never takes more than half the height, so the funnel keeps the
// rest; angled labels that don't fit it are truncated.
const maxLabelBandHeight = Math.max(
singleLineLabelHeight + LABEL_GAP,
Math.floor(H * MAX_X_AXIS_HEIGHT_SHARE),
);
const labelBandHeight =
!showLabels || !horizontal
? 0
: Math.min(
maxLabelBandHeight,
(labelAngle !== 0
? Math.max(angledHeight, singleLineLabelHeight)
: singleLineLabelHeight) + LABEL_GAP,
);
// Longest angled label the band holds: text of width L rotated by the angle
// spans L·sin + lineHeight·cos vertically.
const angleRad = (Math.abs(labelAngle) * Math.PI) / 180;
const angledLabelMaxWidth =
labelAngle === 0
? Infinity
: Math.max(
0,
(labelBandHeight - LABEL_GAP - singleLineLabelHeight * Math.cos(angleRad)) /
Math.sin(angleRad),
);
const labelColWidth =
!showLabels || horizontal
? 0
: Math.min(
Math.ceil(maxLabelWidth) + LABEL_GAP * 2,
Math.max(MAX_LABEL_COL_FLOOR, Math.round(W * MAX_LABEL_COL_RATIO)),
);
// The funnel plot (rings + value + pct) lives in the area the labels don't.
const ringW = horizontal ? W : Math.max(0, W - labelColWidth);
const ringH = horizontal ? Math.max(0, H - labelBandHeight) : H;
const containerStyle = useMemo(() => buildContainerStyle({}, width, height), [width, height]);
return {
refs: { containerRef, legendRef },
isPrinting,
isEmpty,
data: {
visibleStages,
visibleRows,
hiddenStages,
toggleStage,
legendItems,
},
dimensions: {
containerWidth,
W,
H,
ringW,
ringH,
labelBandHeight,
labelColWidth,
labelAngle,
angledLabelMaxWidth,
},
hover: { hoveredIndex, mousePos, handleMouseMove, handleMouseLeave },
legend: { isLegendExpanded, setIsLegendExpanded },
tooltip: { tooltipPayload },
style: { containerStyle },
};
}