@cronus-ui/ui 0.6.0

package/dist/charts/bar-depth.js

@@ -0,0 +1,586 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Bar 3D depth + glass surfaces — drop-in layers for `<BarChart>`.
+ *
+ * Adds a head-on perspective and a glossy glass-block sheen to the bars in
+ * any `<BarChart>`. Bars left of chart center expose their RIGHT side face;
+ * bars right of center expose their LEFT — the vanishing point sits at the
+ * chart's horizontal middle, so the row reads like vertical glass blocks
+ * viewed straight on.
+ *
+ * Three surfaces per bar:
+ *   1. Side face — a parallelogram on the depth side, lit at the front edge
+ *      with a horizontal black gradient and shaded toward the back.
+ *   2. Top face — a parallelogram lid above the bar's top edge, with a
+ *      bright catch at the front lip fading to soft white at the back.
+ *   3. Glass overlay — a vertical white-to-dark gradient on the bar's front
+ *      face (sharp top reflection, transparent middle, faint bottom shadow).
+ *
+ * Usage (purely additive — no changes to `<Bar>`):
+ *
+ *   <BarChart data={data} xDataKey="month">
+ *     <Grid horizontal />
+ *     <BarDepthBack dataKey="value" color="var(--chart-1)" />  // before <Bar>
+ *     <Bar dataKey="value" fill="var(--chart-1)" />
+ *     <BarDepthFront dataKey="value" />                        // after <Bar>
+ *   </BarChart>
+ *
+ * Both depth layers read geometry from `useChart()` and figure out the
+ * perspective themselves. The only configuration is the bar color
+ * (`color` / `colorAccessor`) and, for stacked bars, a `segmentsAccessor`
+ * supplied via `<BarDepthProvider>`.
+ *
+ * An optional `<BarPulse>` paints a looping vertical sweep over a single
+ * "active" bar (selected by `activeIndex`) — useful for highlighting a live
+ * or in-progress value. Render it AFTER `<BarDepthFront>`.
+ *
+ * Behavior notes:
+ *   - Negative values are supported: a bar whose value is below zero grows
+ *     downward from the baseline, with the lid sitting on the baseline.
+ *     (This requires the host `<BarChart>` to use a value scale whose
+ *     domain includes negatives.)
+ *   - Zero-value bars are skipped by default; set `minBarHeight` on
+ *     `<BarDepthProvider>` (and `<Bar>`) to floor them to a short visible bar.
+ *
+ * Performance:
+ *   - Three shared SVG gradients per layer instance (ID-collision-safe via
+ *     `useId()`).
+ *   - A per-bar `<clipPath>` for the side face animates from the baseline so
+ *     the static side path is revealed bottom-up in lockstep with the bar.
+ *     Only used where depth ≥ 0.5px.
+ *   - At high bar density the column gap clamps depth below the 0.5px
+ *     threshold; the back surfaces skip rendering and only the cheap glass
+ *     rect remains.
+ *   - `useBarDepthEntries` is memoized, so the Back/Front/Pulse layers
+ *     compute geometry at most once per render between them.
+ */
+import { motion } from "motion/react";
+import { createContext, useContext, useId, useMemo } from "react";
+import { barDepthAndRise, barDepthMaxDepth } from "./bar-depth-geometry.js";
+import { useChartHover, useChartStable } from "./chart-context.js";
+import { transitionWithDelay } from "./motion-utils.js";
+// ─── Constants ───────────────────────────────────────────────────────
+/** Below this depth the back surfaces don't render — saves elements for
+ * dead-center bars and dense charts where perspective is sub-pixel. */
+const BAR_DEPTH_MIN_PX = 0.5;
+/** Mirrors `Bar`'s default `fadedOpacity` so depth/glass dim in step with
+ * their bar when a sibling bar is hovered. */
+const BAR_FADED_OPACITY = 0.3;
+/** Default bar color when neither `color` nor `colorAccessor` is provided. */
+const DEFAULT_BAR_COLOR = "var(--chart-line-primary)";
+/** Default opacity of the baseline "contact shadow" that grounds each bar at
+ * the zero line. Configurable via `<BarDepthProvider groundShadow>`. */
+const DEFAULT_GROUND_SHADOW = 0.26;
+/** Peak opacity of the white reflection catch at each bar's tip. Kept here so
+ * the front/side glass and the solid lid highlight all use the same value. */
+const GLASS_TIP_OPACITY = 0.2;
+// `BarPulse` — vertical sweep wave constants. The wave is a tall translucent
+// rect with a centered bright band; it translates from below the bar's bottom
+// edge to above the lid's back edge on a loop, clipped to the bar's full 3D
+// silhouette.
+/** Wave height = max(barHeight × this, PULSE_WAVE_HEIGHT_MIN_PX). 0.55 puts
+ * the bright band's peak in the middle of the bar at mid-travel. */
+const PULSE_WAVE_HEIGHT_RATIO = 0.55;
+/** Minimum wave height in px so short bars still pulse on a steady cadence —
+ * the wave is taller than the bar so the bright band sweeps through cleanly
+ * instead of flashing for one frame. */
+const PULSE_WAVE_HEIGHT_MIN_PX = 36;
+/** Seconds per sweep (bottom → above the lid). 2.4s reads as a deliberate
+ * heartbeat; faster feels frantic, slower feels laggy. */
+const PULSE_WAVE_DURATION_S = 2.4;
+/** Peak opacity of the wave's brightest gradient stop. White at 0.85 is
+ * bright enough to register over saturated bar colors while the bell-curve
+ * stops around it keep the falloff soft so the bar's hue still dominates. */
+const PULSE_WAVE_PEAK_OPACITY = 0.85;
+const BAR_HOVER_TRANSITION = { duration: 0.15, ease: "easeOut" };
+function resolveColor(datum, index, color, colorAccessor) {
+    return colorAccessor?.(datum, index) ?? color;
+}
+/** Side-face parallelogram between two screen-Y edges, on the depth side of
+ * the bar (left of the bar for right-of-center bars, right for left-of). */
+function sideFacePath(e, topEdge, bottomEdge) {
+    const rise = e.perspectiveRise;
+    if (e.isRightOfCenter) {
+        const x = e.bandX;
+        return `M ${x} ${topEdge} L ${x - e.depth} ${topEdge - rise} L ${x - e.depth} ${bottomEdge - rise} L ${x} ${bottomEdge} Z`;
+    }
+    const x = e.bandX + e.bandWidth;
+    return `M ${x} ${topEdge} L ${x + e.depth} ${topEdge - rise} L ${x + e.depth} ${bottomEdge - rise} L ${x} ${bottomEdge} Z`;
+}
+/** Lid (top face) parallelogram above the bar's top edge. */
+function lidFacePath(e) {
+    const rise = e.perspectiveRise;
+    const left = e.bandX;
+    const right = e.bandX + e.bandWidth;
+    if (e.isRightOfCenter) {
+        return `M ${left} ${e.topY} L ${right} ${e.topY} L ${right - e.depth} ${e.topY - rise} L ${left - e.depth} ${e.topY - rise} Z`;
+    }
+    return `M ${left} ${e.topY} L ${right} ${e.topY} L ${right + e.depth} ${e.topY - rise} L ${left + e.depth} ${e.topY - rise} Z`;
+}
+/**
+ * Build the side-face parallelograms for a bar. Without segments it's a single
+ * piece in `baseColor`; with segments each gets its natural scaled height
+ * `(seg.value/total) * naturalHeight` and only the topmost has `topYTrim`
+ * removed — matching exactly how `<Bar>` stacks segments, so the side seams
+ * line up with the front face.
+ */
+function buildSidePieces(e, visibleSegments, baseColor) {
+    if (!(visibleSegments && visibleSegments.length > 0)) {
+        return [{ path: sideFacePath(e, e.topY, e.bottomY), color: baseColor }];
+    }
+    const totalValue = visibleSegments.reduce((sum, s) => sum + s.value, 0);
+    const pieces = [];
+    let cursorY = e.bottomY;
+    for (let i = 0; i < visibleSegments.length; i++) {
+        const seg = visibleSegments[i];
+        if (!seg) {
+            continue;
+        }
+        const isTopmost = i === visibleSegments.length - 1;
+        const segScaledHeight = (seg.value / totalValue) * e.naturalHeight;
+        const segHeight = isTopmost ? Math.max(0, segScaledHeight - e.topYTrim) : segScaledHeight;
+        const segBottomY = cursorY;
+        const segTopY = cursorY - segHeight;
+        cursorY = segTopY;
+        pieces.push({
+            path: sideFacePath(e, segTopY, segBottomY),
+            color: seg.color,
+        });
+    }
+    return pieces;
+}
+const BarDepthContext = createContext({});
+/**
+ * Provides shared bar-depth configuration to every depth surface beneath it.
+ * Wrap a `<BarChart>` whose children include `<BarDepthBack>` /
+ * `<BarDepthFront>` / `<BarPulse>` with this provider to:
+ *   - split stacked bars into per-segment side faces (`segmentsAccessor`),
+ *   - tune the baseline contact shadow (`groundShadow`, default 0.26; 0 = off),
+ *   - floor short/zero bars so they stay visible (`minBarHeight`; pair with the
+ *     same value on `<Bar minBarHeight>`).
+ *
+ * Because the glass gradient is chart-wide (one Y-anchored ramp shared by the
+ * front face and the side glass), the provider is the single source of truth —
+ * so the surfaces can never disagree.
+ */
+export function BarDepthProvider({ segmentsAccessor, groundShadow, minBarHeight, children, }) {
+    // Memoize so consumers don't re-render when the config is stable.
+    const value = useMemo(() => ({ segmentsAccessor, groundShadow, minBarHeight }), [segmentsAccessor, groundShadow, minBarHeight]);
+    return _jsx(BarDepthContext.Provider, { value: value, children: children });
+}
+BarDepthProvider.displayName = "BarDepthProvider";
+/**
+ * Stop list for a POSITIVE bar's glass (0% = tip, 100% = baseline): a sharp
+ * white reflection catch at the tip falling off fast to transparent, then the
+ * contact shadow at the base.
+ */
+function buildPosBarStops(groundShadow) {
+    return [
+        { offset: "0%", color: "white", opacity: String(GLASS_TIP_OPACITY) },
+        { offset: "3%", color: "white", opacity: "0.09" },
+        { offset: "8%", color: "white", opacity: "0.02" },
+        { offset: "55%", color: "white", opacity: "0" },
+        { offset: "100%", color: "black", opacity: String(groundShadow) },
+    ];
+}
+/**
+ * Mirror of `buildPosBarStops` for NEGATIVE bars (which grow downward): the
+ * contact shadow sits at the top (the baseline) and the reflection catch at
+ * the bottom (the bar's tip).
+ */
+function buildNegBarStops(groundShadow) {
+    return [
+        { offset: "0%", color: "black", opacity: String(groundShadow) },
+        { offset: "45%", color: "white", opacity: "0" },
+        { offset: "92%", color: "white", opacity: "0.02" },
+        { offset: "97%", color: "white", opacity: "0.09" },
+        { offset: "100%", color: "white", opacity: String(GLASS_TIP_OPACITY) },
+    ];
+}
+/**
+ * Build both per-bar glass stop lists from the current `groundShadow`. Each
+ * depth surface picks `posStops` or `negStops` by the bar's direction and
+ * paints it objectBoundingBox, so the gloss is identical across bar heights.
+ */
+function useGlassStops() {
+    const { groundShadow = DEFAULT_GROUND_SHADOW } = useContext(BarDepthContext);
+    return useMemo(() => ({
+        posStops: buildPosBarStops(groundShadow),
+        negStops: buildNegBarStops(groundShadow),
+    }), [groundShadow]);
+}
+function readBarValue(d, key) {
+    const v = key ? d[key] : undefined;
+    return typeof v === "number" ? v : 0;
+}
+// ─── Hooks ───────────────────────────────────────────────────────────
+/**
+ * Compute per-bar 3D depth geometry from chart context.
+ *
+ * Memoized on the chart's scales + data, so calling this from sibling layers
+ * within the same chart is essentially free after the first settles. Returns
+ * one entry per renderable bar; bars with no resolvable height are excluded.
+ *
+ * Negative-value bars are kept — `isNegative` flips the entry's geometry so
+ * the side parallelogram and lid render in the correct direction.
+ *
+ * Exported for advanced consumers that want to render custom layers aligned
+ * with the same geometry (e.g. labels above each bar's top face).
+ */
+export function useBarDepthEntries(dataKey, activeIndex) {
+    const { data, barScale, bandWidth, yScale, innerHeight, innerWidth, barXAccessor } = useChartStable();
+    // Read shared config from `<BarDepthProvider>`. Outside a provider these are
+    // the defaults (no segmentation, no floor) — correct for simple charts.
+    const { segmentsAccessor, minBarHeight = 0 } = useContext(BarDepthContext);
+    return useMemo(() => {
+        if (!(barScale && bandWidth && barXAccessor)) {
+            return [];
+        }
+        const centerX = innerWidth / 2;
+        const zeroY = yScale(0) ?? innerHeight;
+        // d3-scaleBand exposes step() (= bandwidth + gap); the shared helper caps
+        // depth below the gap so a side face never spills past the next bar.
+        const step = barScale.step?.() ?? bandWidth;
+        const maxDepth = barDepthMaxDepth(step, bandWidth);
+        // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: per-bar 3D geometry (direction, perspective trim, segment scaling) reads clearest as one pass
+        return data.flatMap((d, dataIndex) => {
+            // Stacked bars: the bar's value is the SUM of its segments (so the depth
+            // height matches the host BarChart's stacked total). Single bars: the
+            // `dataKey` column. `segmentsAccessor` comes from `<BarDepthProvider>`.
+            const visibleSegs = segmentsAccessor?.(d)?.filter((s) => s.value > 0) ?? null;
+            const value = visibleSegs && visibleSegs.length > 0
+                ? visibleSegs.reduce((sum, s) => sum + s.value, 0)
+                : readBarValue(d, dataKey);
+            const isActive = activeIndex != null && dataIndex === activeIndex;
+            const isNegative = value < 0;
+            const label = barXAccessor(d);
+            const bandX = barScale(label) ?? 0;
+            const cx = bandX + bandWidth / 2;
+            // `Math.abs` so negative bars produce a positive height — direction is
+            // captured by `isNegative`. Non-negative bars are floored to
+            // `minBarHeight` so short/zero values stay visible (mirrors
+            // `<Bar minBarHeight>`); a floored bar skips the perspective trim so its
+            // tiny front face and lid stay aligned. With the default floor of 0,
+            // zero-value bars produce no height and are skipped.
+            const valuePos = yScale(value) ?? innerHeight;
+            const rawHeight = Math.abs(zeroY - valuePos);
+            const naturalHeight = isNegative ? rawHeight : Math.max(rawHeight, minBarHeight);
+            if (naturalHeight <= 0) {
+                return [];
+            }
+            const isFloored = !isNegative && rawHeight < naturalHeight;
+            const offsetFromCenter = centerX > 0 ? (cx - centerX) / centerX : 0;
+            const isRightOfCenter = offsetFromCenter > 0;
+            const absOffset = Math.min(1, Math.abs(offsetFromCenter));
+            const { depth, perspectiveRise: rawRise } = barDepthAndRise(absOffset, naturalHeight, maxDepth);
+            // Perspective lift applies only to positive bars. For negative bars a
+            // lift would raise the lid's back edge above the baseline (a visible
+            // "lip" at the chart edges), so it's forced to 0 — degenerating the lid
+            // and flattening the side into a rectangle flush with the baseline.
+            const perspectiveRise = isNegative ? 0 : rawRise;
+            // Perspective trim — positive value-bearing bars only. The lid's back
+            // edge sits `perspectiveRise` above `topY`. Without trim the silhouette
+            // top would vary with depth (bars further from center look taller).
+            // Trim shifts `topY` DOWN by `perspectiveRise` so the lid's back edge
+            // lands on `yScale(value)` regardless of depth. The clamp denominator
+            // is the topmost segment's scaled height (for stacked bars) or the whole
+            // bar's natural height, matching how `<Bar>` stacks segments.
+            let trimClampReference = naturalHeight;
+            if (visibleSegs && visibleSegs.length > 0) {
+                const segTotal = visibleSegs.reduce((sum, s) => sum + s.value, 0);
+                const topmost = visibleSegs.at(-1);
+                if (segTotal > 0 && topmost) {
+                    trimClampReference = (topmost.value / segTotal) * naturalHeight;
+                }
+            }
+            const isValueBar = naturalHeight > 0 && !isNegative && !isFloored;
+            const topYTrim = isValueBar
+                ? Math.min(perspectiveRise, Math.max(0, trimClampReference - 1))
+                : 0;
+            // Direction-aware top/bottom: positive bars hang ABOVE the baseline;
+            // negative bars hang BELOW it. The lid always lives at `topY` so for
+            // negative bars it sits on the baseline.
+            const topY = isNegative ? zeroY : zeroY - naturalHeight + topYTrim;
+            const bottomY = isNegative ? zeroY + naturalHeight : zeroY;
+            const barHeight = bottomY - topY;
+            return [
+                {
+                    label,
+                    dataIndex,
+                    datum: d,
+                    isActive,
+                    isNegative,
+                    baselineY: zeroY,
+                    bandX,
+                    bandWidth,
+                    topY,
+                    bottomY,
+                    barHeight,
+                    naturalHeight,
+                    topYTrim,
+                    depth,
+                    perspectiveRise,
+                    isRightOfCenter,
+                },
+            ];
+        });
+    }, [
+        data,
+        barScale,
+        bandWidth,
+        yScale,
+        innerHeight,
+        innerWidth,
+        barXAccessor,
+        segmentsAccessor,
+        minBarHeight,
+        dataKey,
+        activeIndex,
+    ]);
+}
+function useBarDepthStagger() {
+    const { data, animationDuration } = useChartStable();
+    // Mirror `Bar`'s stagger formula so each depth surface enters in lockstep
+    // with its front face (`Bar` uses `animationDuration * 0.4 / count`).
+    const total = animationDuration || 1100;
+    return data.length > 1 ? (total * 0.4) / 1000 / data.length : 0;
+}
+/**
+ * Renders the back surfaces (side + top faces) of the 3D bar effect.
+ *
+ * Place BEFORE the `<Bar>` elements in `<BarChart>` children so the bar's
+ * solid front face occludes any depth that would extend into an adjacent
+ * column. Skips bars at chart center (depth ≈ 0) and dense charts.
+ *
+ * For stacked bars, wrap the `<BarChart>` in a
+ * `<BarDepthProvider segmentsAccessor={...}>` so the side face splits into
+ * per-segment parallelograms and the lid color matches the topmost segment.
+ */
+export function BarDepthBack({ dataKey, color = DEFAULT_BAR_COLOR, colorAccessor, }) {
+    const { isLoaded, enterTransition, revealEpoch = 0 } = useChartStable();
+    const { hoveredBarIndex } = useChartHover();
+    const { segmentsAccessor } = useContext(BarDepthContext);
+    const entries = useBarDepthEntries(dataKey);
+    const stagger = useBarDepthStagger();
+    const { posStops: glassStops, negStops: glassNegStops } = useGlassStops();
+    const idPrefix = useId().replace(/[^a-z0-9]/gi, "_");
+    // Two horizontal black gradients (one per depth direction) shade the side
+    // from front-edge (lit) to back-edge (in shadow). A single vertical white
+    // gradient on the lid: bright catch at the front lip → soft white at the
+    // back. The vertical glass gradient layered on top of the side adds the same
+    // bright-tip / dark-baseline curve as the front face for continuity.
+    const sideShadeRtl = `bdb-side-rtl-${idPrefix}`;
+    const sideShadeLtr = `bdb-side-ltr-${idPrefix}`;
+    const topShade = `bdb-top-${idPrefix}`;
+    const sideGlass = `bdb-glass-${idPrefix}`;
+    // Per-bar bbox variant used only for bars that extend below the baseline.
+    const sideGlassNeg = `bdb-glass-neg-${idPrefix}`;
+    return (_jsxs("g", { className: "bar-depth-back", pointerEvents: "none", children: [_jsxs("defs", { children: [_jsxs("linearGradient", { id: sideShadeRtl, x1: "1", x2: "0", y1: "0", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: "black", stopOpacity: "0.05" }), _jsx("stop", { offset: "100%", stopColor: "black", stopOpacity: "0.55" })] }), _jsxs("linearGradient", { id: sideShadeLtr, x1: "0", x2: "1", y1: "0", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: "black", stopOpacity: "0.05" }), _jsx("stop", { offset: "100%", stopColor: "black", stopOpacity: "0.55" })] }), _jsxs("linearGradient", { id: topShade, x1: "0", x2: "0", y1: "1", y2: "0", children: [_jsx("stop", { offset: "0%", stopColor: "black", stopOpacity: "0" }), _jsx("stop", { offset: "100%", stopColor: "black", stopOpacity: "0.18" })] }), _jsx("linearGradient", { id: sideGlass, x1: "0", x2: "0", y1: "0", y2: "1", children: glassStops.map((stop) => (_jsx("stop", { offset: stop.offset, stopColor: stop.color, stopOpacity: stop.opacity }, `${stop.offset}-${stop.opacity}`))) }), _jsx("linearGradient", { id: sideGlassNeg, x1: "0", x2: "0", y1: "0", y2: "1", children: glassNegStops.map((stop) => (_jsx("stop", { offset: stop.offset, stopColor: stop.color, stopOpacity: stop.opacity }, `${stop.offset}-${stop.opacity}`))) })] }), entries.map((e) => {
+                if (e.depth < BAR_DEPTH_MIN_PX) {
+                    return null;
+                }
+                // Resolve stacked segments for this bar. Filter to non-zero so a
+                // missing segment doesn't paint an invisible 0-height piece or quietly
+                // become the lid color.
+                const rawSegments = segmentsAccessor?.(e.datum);
+                const visibleSegments = rawSegments?.filter((s) => s.value > 0) ?? null;
+                const baseColor = resolveColor(e.datum, e.dataIndex, color, colorAccessor);
+                const sidePieces = buildSidePieces(e, visibleSegments, baseColor);
+                // Full-side path for the vertical glass overlay — drawn once per bar
+                // so the brightness curve sweeps across the entire side as one layer.
+                const fullSidePath = sideFacePath(e, e.topY, e.bottomY);
+                // Lid is one parallelogram regardless of segmentation — colored by the
+                // topmost visible segment so it matches the front face's top section.
+                const topPath = lidFacePath(e);
+                const topColor = visibleSegments?.at(-1)?.color ?? baseColor;
+                const delay = e.dataIndex * stagger;
+                // Grow uses the SAME enter transition + stagger as `<Bar>` so the side
+                // and lid rise at the exact speed of the front face. Post-load geometry
+                // changes get a quick settle instead.
+                const growTransition = isLoaded
+                    ? { duration: 0.3, ease: "easeOut" }
+                    : transitionWithDelay(enterTransition, delay);
+                const isFaded = hoveredBarIndex != null && hoveredBarIndex !== e.dataIndex;
+                const sideShadeId = e.isRightOfCenter ? sideShadeRtl : sideShadeLtr;
+                const safeId = e.label.replace(/[^a-z0-9]/gi, "_");
+                const clipId = `bdb-clip-${idPrefix}-${safeId}`;
+                // Lid ENTRANCE only (hover-dim is owned by the wrapping group below, so
+                // the lid can never dim differently from the side). Positive lids
+                // translate up from the baseline riding the growing top edge; negative
+                // lids already sit at the baseline, so they fade in instead.
+                let lidEntrance = {
+                    initial: false,
+                    animate: { y: 0 },
+                    transition: { y: growTransition },
+                };
+                if (!isLoaded && e.isNegative) {
+                    lidEntrance = {
+                        initial: { y: 0, opacity: 0 },
+                        animate: { y: 0, opacity: 1 },
+                        transition: { y: growTransition, opacity: growTransition },
+                    };
+                }
+                else if (!isLoaded) {
+                    lidEntrance = {
+                        initial: { y: e.barHeight },
+                        animate: { y: 0 },
+                        transition: { y: growTransition },
+                    };
+                }
+                return (_jsxs(motion.g, { animate: { opacity: isFaded ? BAR_FADED_OPACITY : 1 }, initial: false, transition: BAR_HOVER_TRANSITION, children: [_jsx("defs", { children: _jsx("clipPath", { id: clipId, children: _jsx(motion.rect, { animate: {
+                                        y: e.topY - e.perspectiveRise,
+                                        height: e.barHeight + e.perspectiveRise,
+                                    }, initial: isLoaded ? false : { y: e.baselineY, height: 0 }, transition: growTransition, width: e.bandWidth + 2 * e.depth + 2, x: e.bandX - e.depth - 1 }, `${clipId}-${revealEpoch}-${isLoaded}`) }) }), _jsxs("g", { clipPath: `url(#${clipId})`, children: [sidePieces.map((piece) => (_jsx("path", { d: piece.path, fill: piece.color }, piece.path))), _jsx("path", { d: fullSidePath, fill: `url(#${sideShadeId})` }), _jsx("path", { d: fullSidePath, fill: `url(#${e.isNegative ? sideGlassNeg : sideGlass})` })] }), _jsxs(motion.g, { animate: lidEntrance.animate, initial: lidEntrance.initial, transition: lidEntrance.transition, children: [_jsx("path", { d: topPath, fill: topColor }), _jsx("path", { d: topPath, fill: "white", fillOpacity: GLASS_TIP_OPACITY }), _jsx("path", { d: topPath, fill: `url(#${topShade})` })] }, `lid-${safeId}-${revealEpoch}-${isLoaded}`)] }, e.label));
+            })] }));
+}
+BarDepthBack.displayName = "BarDepthBack";
+// Mark as a non-series layer so `BarChart` doesn't count it as a bar (it
+// carries a `dataKey` to pair with a Bar). Mirrors `ChartMarkers`'
+// `__isChartMarkers` flag — a static property is minification-safe, unlike
+// matching on `displayName`.
+BarDepthBack.__isBarDepthLayer = true;
+/**
+ * Renders the front surface: a glossy glass sheen over the bar's solid fill.
+ * Place AFTER the `<Bar>` elements in `<BarChart>` children so the gradient
+ * sits on top of the bar.
+ *
+ * Reads `segmentsAccessor` from the surrounding `<BarDepthProvider>` (if any)
+ * via `useBarDepthEntries`, so the glass rectangle's `topY` automatically
+ * matches the lid+side's trim. No prop wiring required.
+ */
+export function BarDepthFront({ dataKey }) {
+    const { isLoaded, enterTransition, revealEpoch = 0 } = useChartStable();
+    const { hoveredBarIndex } = useChartHover();
+    const entries = useBarDepthEntries(dataKey);
+    const stagger = useBarDepthStagger();
+    const { posStops: glassStops, negStops: glassNegStops } = useGlassStops();
+    const idPrefix = useId().replace(/[^a-z0-9]/gi, "_");
+    const glassId = `bdf-glass-${idPrefix}`;
+    const glassIdNeg = `bdf-glass-neg-${idPrefix}`;
+    return (_jsxs("g", { className: "bar-depth-front", pointerEvents: "none", children: [_jsxs("defs", { children: [_jsx("linearGradient", { id: glassId, x1: "0", x2: "0", y1: "0", y2: "1", children: glassStops.map((stop) => (_jsx("stop", { offset: stop.offset, stopColor: stop.color, stopOpacity: stop.opacity }, `${stop.offset}-${stop.opacity}`))) }), _jsx("linearGradient", { id: glassIdNeg, x1: "0", x2: "0", y1: "0", y2: "1", children: glassNegStops.map((stop) => (_jsx("stop", { offset: stop.offset, stopColor: stop.color, stopOpacity: stop.opacity }, `${stop.offset}-${stop.opacity}`))) })] }), entries.map((e) => {
+                const delay = e.dataIndex * stagger;
+                // Same enter transition + stagger as `<Bar>` so the glass rises in
+                // lockstep with the front face.
+                const baseTransition = isLoaded
+                    ? { duration: 0.3, ease: "easeOut" }
+                    : transitionWithDelay(enterTransition, delay);
+                const isFaded = hoveredBarIndex != null && hoveredBarIndex !== e.dataIndex;
+                return (_jsx(motion.rect, { animate: {
+                        y: e.topY,
+                        height: e.barHeight,
+                        opacity: isFaded ? BAR_FADED_OPACITY : 1,
+                    }, fill: `url(#${e.isNegative ? glassIdNeg : glassId})`, 
+                    // Anchor the grow at the baseline (not bottomY) so the glass grows
+                    // outward in whichever direction the bar extends. Keyed on
+                    // revealEpoch so it replays the grow on every reveal, like `<Bar>`.
+                    initial: isLoaded ? false : { y: e.baselineY, height: 0 }, transition: { ...baseTransition, opacity: BAR_HOVER_TRANSITION }, width: e.bandWidth, x: e.bandX }, `${e.label}-${revealEpoch}-${isLoaded}`));
+            })] }));
+}
+BarDepthFront.displayName = "BarDepthFront";
+BarDepthFront.__isBarDepthLayer = true;
+// ─── BarPulse ─────────────────────────────────────────────────────────
+/**
+ * Builds the SVG path tracing the silhouette of a 3D bar — the unioned
+ * outline of front face + visible side parallelogram + lid parallelogram.
+ * Used as the clip region for `BarPulse`'s wave so the gradient only paints
+ * inside the bar's visible 3D shape. For dead-center bars (`depth <= 0`) the
+ * silhouette degenerates to just the front rectangle.
+ */
+function buildBarSilhouettePath(e) {
+    const { bandX, bandWidth, topY, bottomY, depth, perspectiveRise, isRightOfCenter } = e;
+    if (depth <= 0) {
+        return [
+            `M ${bandX} ${topY}`,
+            `L ${bandX + bandWidth} ${topY}`,
+            `L ${bandX + bandWidth} ${bottomY}`,
+            `L ${bandX} ${bottomY}`,
+            "Z",
+        ].join(" ");
+    }
+    if (isRightOfCenter) {
+        // Side face on LEFT — back shifted (-depth, -perspectiveRise).
+        return [
+            `M ${bandX - depth} ${topY - perspectiveRise}`,
+            `L ${bandX + bandWidth - depth} ${topY - perspectiveRise}`,
+            `L ${bandX + bandWidth} ${topY}`,
+            `L ${bandX + bandWidth} ${bottomY}`,
+            `L ${bandX} ${bottomY}`,
+            `L ${bandX - depth} ${bottomY - perspectiveRise}`,
+            "Z",
+        ].join(" ");
+    }
+    // Side face on RIGHT — back shifted (+depth, -perspectiveRise).
+    return [
+        `M ${bandX} ${topY}`,
+        `L ${bandX + depth} ${topY - perspectiveRise}`,
+        `L ${bandX + bandWidth + depth} ${topY - perspectiveRise}`,
+        `L ${bandX + bandWidth + depth} ${bottomY - perspectiveRise}`,
+        `L ${bandX + bandWidth} ${bottomY}`,
+        `L ${bandX} ${bottomY}`,
+        "Z",
+    ].join(" ");
+}
+/**
+ * Vertical wave that sweeps from a bar's root (baseline) toward its tip on a
+ * continuous loop, painted across the bar's full 3D silhouette (front face +
+ * lid + visible side). Reads as a heartbeat pulse flowing up the column for
+ * positive bars and down for negative bars — useful for marking a live or
+ * in-progress value without adding any fixed element.
+ *
+ * Select the bar via `activeIndex`. Set `pulsePaused` to freeze it. Place
+ * AFTER `<BarDepthFront />` so the wave brightens on top of the glass.
+ *
+ * Performance: at most one clipped `<motion.rect>` with a single Y translate
+ * per frame (no per-frame paint of gradient stops, no SVG filters).
+ */
+export function BarPulse({ dataKey, activeIndex, pulsePaused }) {
+    const { isLoaded } = useChartStable();
+    const { hoveredBarIndex } = useChartHover();
+    const entries = useBarDepthEntries(dataKey, activeIndex);
+    const idPrefix = useId().replace(/[^a-z0-9]/gi, "_");
+    const activeEntries = useMemo(() => entries.filter((e) => e.isActive), [entries]);
+    if (activeEntries.length === 0 || pulsePaused) {
+        return null;
+    }
+    // Hold the wave until bars finish growing — the silhouette clip is computed
+    // at the final geometry, so painting it mid-grow would reveal a wave inside
+    // an area the bar hasn't reached yet.
+    if (!isLoaded) {
+        return null;
+    }
+    return (_jsxs("g", { className: "bar-pulse", pointerEvents: "none", children: [_jsx("defs", { children: activeEntries.flatMap((e) => {
+                    const safeId = e.label.replace(/[^a-z0-9]/gi, "_");
+                    const clipId = `bar-pulse-clip-${idPrefix}-${safeId}`;
+                    const gradId = `bar-pulse-grad-${idPrefix}-${safeId}`;
+                    return [
+                        _jsx("clipPath", { id: clipId, children: _jsx("path", { d: buildBarSilhouettePath(e) }) }, `clip-${safeId}`),
+                        _jsxs("linearGradient", { id: gradId, x1: "0", x2: "0", y1: "1", y2: "0", children: [_jsx("stop", { offset: "0%", stopColor: "white", stopOpacity: "0" }), _jsx("stop", { offset: "10%", stopColor: "white", stopOpacity: "0" }), _jsx("stop", { offset: "22%", stopColor: "white", stopOpacity: PULSE_WAVE_PEAK_OPACITY * 0.18 }), _jsx("stop", { offset: "34%", stopColor: "white", stopOpacity: PULSE_WAVE_PEAK_OPACITY * 0.5 }), _jsx("stop", { offset: "44%", stopColor: "white", stopOpacity: PULSE_WAVE_PEAK_OPACITY * 0.85 }), _jsx("stop", { offset: "50%", stopColor: "white", stopOpacity: PULSE_WAVE_PEAK_OPACITY }), _jsx("stop", { offset: "56%", stopColor: "white", stopOpacity: PULSE_WAVE_PEAK_OPACITY * 0.85 }), _jsx("stop", { offset: "66%", stopColor: "white", stopOpacity: PULSE_WAVE_PEAK_OPACITY * 0.5 }), _jsx("stop", { offset: "78%", stopColor: "white", stopOpacity: PULSE_WAVE_PEAK_OPACITY * 0.18 }), _jsx("stop", { offset: "90%", stopColor: "white", stopOpacity: "0" }), _jsx("stop", { offset: "100%", stopColor: "white", stopOpacity: "0" })] }, `grad-${safeId}`),
+                    ];
+                }) }), activeEntries.map((e) => {
+                const safeId = e.label.replace(/[^a-z0-9]/gi, "_");
+                const clipId = `bar-pulse-clip-${idPrefix}-${safeId}`;
+                const gradId = `bar-pulse-grad-${idPrefix}-${safeId}`;
+                const waveHeight = Math.max(e.barHeight * PULSE_WAVE_HEIGHT_RATIO, PULSE_WAVE_HEIGHT_MIN_PX);
+                // Travel always flows root → tip. Positive bars sweep up (root =
+                // bottomY); negative bars sweep down (root = topY, the baseline). The
+                // gradient is symmetric, so reversing the endpoints reverses direction.
+                const yAboveLid = e.topY - e.perspectiveRise - waveHeight;
+                const yBelowFloor = e.bottomY;
+                const yStart = e.isNegative ? yAboveLid : yBelowFloor;
+                const yEnd = e.isNegative ? yBelowFloor : yAboveLid;
+                const isFaded = hoveredBarIndex != null && hoveredBarIndex !== e.dataIndex;
+                return (_jsx(motion.g, { animate: { opacity: isFaded ? BAR_FADED_OPACITY : 1 }, clipPath: `url(#${clipId})`, initial: false, transition: BAR_HOVER_TRANSITION, children: _jsx(motion.rect, { animate: { y: yEnd }, fill: `url(#${gradId})`, height: waveHeight, initial: { y: yStart }, transition: {
+                            duration: PULSE_WAVE_DURATION_S,
+                            ease: "easeInOut",
+                            repeat: Number.POSITIVE_INFINITY,
+                            repeatType: "loop",
+                        }, 
+                        // Span wide enough to cover the bar plus its depth on either
+                        // side; the clipPath crops anything outside the silhouette.
+                        width: e.bandWidth + 2 * e.depth + 2, x: e.bandX - e.depth - 1 }) }, e.label));
+            })] }));
+}
+BarPulse.displayName = "BarPulse";
+BarPulse.__isBarDepthLayer = true;
+//# sourceMappingURL=bar-depth.js.map

package/dist/charts/bar-squares-layout.d.ts

@@ -0,0 +1,28 @@
+export interface SquareColumnLayout {
+    /** Number of squares in the column */
+    count: number;
+    /** Top-left Y of each square, bottom square first (relative to bar top at 0) */
+    positions: number[];
+    /** Quantized column height in pixels */
+    columnHeight: number;
+    squareSize: number;
+    /** Effective gap between squares (may differ when fit mode redistributes) */
+    gap: number;
+}
+export interface SquareColumnInput {
+    /** Raw bar length in pixels (baseline − value) */
+    barLengthPx: number;
+    /** Square width/height — typically equals bar width */
+    squareSize: number;
+    /** Gap between stacked squares in pixels */
+    gap: number;
+    /** When true, redistribute gap so column height matches barLengthPx exactly */
+    fit?: boolean;
+}
+/** Quantize bar length into a stack of square cells. */
+export declare function computeSquareColumn({ barLengthPx, squareSize, gap, fit, }: SquareColumnInput): SquareColumnLayout;
+/** Y center of the topmost square in a vertical column. */
+export declare function topSquareCenterY({ baselineY, barLengthPx, squareSize, gap, fit, }: SquareColumnInput & {
+    baselineY: number;
+}): number;
+//# sourceMappingURL=bar-squares-layout.d.ts.map

package/dist/charts/bar-squares-layout.js

@@ -0,0 +1,47 @@
+/** Quantize bar length into a stack of square cells. */
+export function computeSquareColumn({ barLengthPx, squareSize, gap, fit = false, }) {
+    if (barLengthPx <= 0 || squareSize <= 0) {
+        return { count: 0, positions: [], columnHeight: 0, squareSize, gap };
+    }
+    if (fit) {
+        const count = Math.max(1, Math.floor((barLengthPx + gap) / (squareSize + gap)));
+        const effectiveGap = count > 1 ? Math.max(0, (barLengthPx - count * squareSize) / (count - 1)) : 0;
+        const step = squareSize + effectiveGap;
+        const columnHeight = barLengthPx;
+        const positions = [];
+        for (let i = 0; i < count; i++) {
+            positions.push(columnHeight - squareSize - i * step);
+        }
+        return {
+            count,
+            positions,
+            columnHeight,
+            squareSize,
+            gap: effectiveGap,
+        };
+    }
+    const step = squareSize + gap;
+    const count = Math.max(1, Math.round(barLengthPx / step));
+    const columnHeight = count * squareSize + Math.max(0, count - 1) * gap;
+    const positions = [];
+    for (let i = 0; i < count; i++) {
+        const offsetFromBottom = i * step;
+        positions.push(columnHeight - squareSize - offsetFromBottom);
+    }
+    return { count, positions, columnHeight, squareSize, gap };
+}
+/** Y center of the topmost square in a vertical column. */
+export function topSquareCenterY({ baselineY, barLengthPx, squareSize, gap, fit = false, }) {
+    const { count, squareSize: size, columnHeight, } = computeSquareColumn({
+        barLengthPx,
+        squareSize,
+        gap,
+        fit,
+    });
+    if (count === 0) {
+        return baselineY;
+    }
+    const topY = baselineY - columnHeight;
+    return topY + size / 2;
+}
+//# sourceMappingURL=bar-squares-layout.js.map