Bar Depth

1"use client";
2 
3/**
4 * Bar 3D depth + glass surfaces — drop-in layers for `<BarChart>`.
5 *
6 * Adds a head-on perspective and a glossy glass-block sheen to the bars in
7 * any `<BarChart>`. Bars left of chart center expose their RIGHT side face;
8 * bars right of center expose their LEFT — the vanishing point sits at the
9 * chart's horizontal middle, so the row reads like vertical glass blocks
10 * viewed straight on.
11 *
12 * Three surfaces per bar:
13 *   1. Side face — a parallelogram on the depth side, lit at the front edge
14 *      with a horizontal black gradient and shaded toward the back.
15 *   2. Top face — a parallelogram lid above the bar's top edge, with a
16 *      bright catch at the front lip fading to soft white at the back.
17 *   3. Glass overlay — a vertical white-to-dark gradient on the bar's front
18 *      face (sharp top reflection, transparent middle, faint bottom shadow).
19 *
20 * Usage (purely additive — no changes to `<Bar>`):
21 *
22 *   <BarChart data={data} xDataKey="month">
23 *     <Grid horizontal />
24 *     <BarDepthBack dataKey="value" color="var(--chart-1)" />  // before <Bar>
25 *     <Bar dataKey="value" fill="var(--chart-1)" />
26 *     <BarDepthFront dataKey="value" />                        // after <Bar>
27 *   </BarChart>
28 *
29 * Both depth layers read geometry from `useChart()` and figure out the
30 * perspective themselves. The only configuration is the bar color
31 * (`color` / `colorAccessor`) and, for stacked bars, a `segmentsAccessor`
32 * supplied via `<BarDepthProvider>`.
33 *
34 * An optional `<BarPulse>` paints a looping vertical sweep over a single
35 * "active" bar (selected by `activeIndex`) — useful for highlighting a live
36 * or in-progress value. Render it AFTER `<BarDepthFront>`.
37 *
38 * Behavior notes:
39 *   - Negative values are supported: a bar whose value is below zero grows
40 *     downward from the baseline, with the lid sitting on the baseline.
41 *     (This requires the host `<BarChart>` to use a value scale whose
42 *     domain includes negatives.)
43 *   - Zero-value bars are skipped by default; set `minBarHeight` on
44 *     `<BarDepthProvider>` (and `<Bar>`) to floor them to a short visible bar.
45 *
46 * Performance:
47 *   - Three shared SVG gradients per layer instance (ID-collision-safe via
48 *     `useId()`).
49 *   - A per-bar `<clipPath>` for the side face animates from the baseline so
50 *     the static side path is revealed bottom-up in lockstep with the bar.
51 *     Only used where depth ≥ 0.5px.
52// … truncated