@cascivo/charts 1.0.0 → 1.2.0

package/README.md

@@ -1,7 +1,7 @@
 <!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
 
 <div align="center">
-  <a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="72" height="72" alt="cascivo logo"></a>
+  <a href="https://cascivo.com"><img src="https://cascivo.com/logo-mark-img-accent.svg" width="72" height="72" alt="cascivo logo"></a>
   <h1>@cascivo/charts</h1>
   <p><strong>Chart components built from scratch — scales, shapes, and signal-driven rendering, zero dependencies. Colors come from @cascivo/themes; components from @cascivo/react. Docs offline: npx @cascivo/docs</strong></p>
 
@@ -169,4 +169,4 @@ pnpm add @cascivo/charts
 
 [cascivo.com](https://cascivo.com) · [Docs](https://cascivo.com/docs) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/cascivo/cascivo) · AI agents: read [`llms.txt`](https://cascivo.com/llms.txt) (install steps + component index, plain text) or use [`@cascivo/mcp`](https://github.com/cascivo/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/cascivo/cascivo/blob/main/registry.json) · MIT
 
-<div align="center"><a href="https://cascivo.com"><img src="https://cascivo.com/favicon.svg" width="28" height="28" alt="cascivo"></a></div>
+<div align="center"><a href="https://cascivo.com"><img src="https://cascivo.com/logo-mark-img.svg" width="28" height="28" alt="cascivo"></a></div>

package/dist/chart-frame.module-B498IKO9.js

@@ -0,0 +1 @@
+"use client";function linearScale(e,t){let[n,r]=e,[i,a]=t,o=r-n;return{domain:e,range:t,map:e=>o===0?i:i+(e-n)/o*(a-i),invert:e=>a-i===0?n:n+(e-i)/(a-i)*o,ticks:(e=5,t)=>niceTicks(n,r,e,t)}}function niceTicks(e,t,n=5,r){if(!Number.isFinite(e)||!Number.isFinite(t)||e===t)return[e];e>t&&([e,t]=[t,e]);let i=r??!(Number.isInteger(e)&&Number.isInteger(t)),a=(t-e)/Math.max(1,n),o=10**Math.floor(Math.log10(a)),s=i?[1,2,2.5,5,10]:[1,2,5,10],c=a/o,l=(s.find(e=>e>=c)??10)*o;i||(l=Math.max(1,Math.round(l)));let u=Math.ceil(e/l),d=Math.floor(t/l+1e-9),f=[],m=Math.max(0,Math.ceil(-Math.log10(l))+2);for(let e=u;e<=d;e++)f.push(parseFloat((e*l).toFixed(m)));return f}function bandScale(e,t,n=.1){let[r,i]=t,a=e.length,o=(i-r)/Math.max(1,a+n*(a+1)),s=o,c=o*n,l=new Map(e.map((e,t)=>[e,t]));return{domain:e,range:t,bandwidth:s,map:e=>{let t=l.get(e);return t===void 0?void 0:r+c+t*(o+c)}}}function sqrtScale(e,t){let[n,r]=e,[i,a]=t,o=Math.sqrt(Math.max(0,n)),s=Math.sqrt(Math.max(0,r))-o;return e=>s===0?(i+a)/2:i+(Math.sqrt(Math.max(0,e))-o)/s*(a-i)}function quantize(e){return Math.round(e*100)/100}function splitDefined(e,t=!1){if(t){let t=e.filter(e=>e!==null);return t.length>0?[t]:[]}let n=[],r=[];for(let t of e)t===null?(r.length>0&&n.push(r),r=[]):r.push(t);return r.length>0&&n.push(r),n}function linePath(e,t=`linear`){if(e.length===0)return``;if(e.length===1||t===`linear`)return e.map(([e,t],n)=>`${n===0?`M`:`L`}${e},${t}`).join(``);switch(t){case`monotone`:return monotonePath(e);case`step`:case`stepBefore`:case`stepAfter`:return stepPath(e,t);case`natural`:return naturalPath(e);case`basis`:return basisPath(e);case`cardinal`:return cardinalPath(e,0);case`catmullRom`:return catmullRomPath(e,.5);default:return monotonePath(e)}}function stepPath(e,t){let n=`M${e[0][0]},${e[0][1]}`;for(let r=0;r<e.length-1;r++){let[i,a]=e[r],[o,s]=e[r+1];if(t===`stepBefore`)n+=`L${i},${s}L${o},${s}`;else if(t===`stepAfter`)n+=`L${o},${a}L${o},${s}`;else{let e=(i+o)/2;n+=`L${e},${a}L${e},${s}L${o},${s}`}}return n}function naturalControls(e){let t=e.length-1;if(t<1)return[[],[]];let n=Array(t),r=Array(t),i=Array(t);r[0]=2,i[0]=e[0]+2*e[1];for(let a=1;a<t-1;a++)n[a]=1,r[a]=4,i[a]=4*e[a]+2*e[a+1];n[t-1]=2,r[t-1]=7,i[t-1]=8*e[t-1]+e[t];for(let e=1;e<t;e++){let t=(n[e]??0)/r[e-1];r[e]=r[e]-t,i[e]=i[e]-t*i[e-1]}let a=Array(t),o=Array(t);a[t-1]=i[t-1]/r[t-1];for(let e=t-2;e>=0;e--)a[e]=(i[e]-a[e+1])/r[e];for(let n=0;n<t-1;n++)o[n]=2*e[n+1]-a[n+1];return o[t-1]=(e[t]+a[t-1])/2,[a,o]}function naturalPath(e){let t=e.length;if(t<3)return e.map(([e,t],n)=>`${n===0?`M`:`L`}${e},${t}`).join(``);let n=e.map(e=>e[0]),r=e.map(e=>e[1]),[i,a]=naturalControls(n),[o,s]=naturalControls(r),c=`M${n[0]},${r[0]}`;for(let e=0;e<t-1;e++)c+=`C${i[e]},${o[e]} ${a[e]},${s[e]} ${n[e+1]},${r[e+1]}`;return c}function basisPath(e){let t=e.length;if(t<3)return e.map(([e,t],n)=>`${n===0?`M`:`L`}${e},${t}`).join(``);let px=n=>e[Math.max(0,Math.min(t-1,n))][0],py=n=>e[Math.max(0,Math.min(t-1,n))][1],n=`M${px(0)},${py(0)}`;for(let e=0;e<t-1;e++){let t=px(e-1),r=py(e-1),i=px(e),a=py(e),o=px(e+1),s=py(e+1),c=(2*t+i)/3,l=(2*r+a)/3,u=(t+2*i)/3,d=(r+2*a)/3,f=(t+4*i+o)/6,m=(r+4*a+s)/6;n+=`C${c},${l} ${u},${d} ${f},${m}`}let r=e[t-1];return n+=`L${r[0]},${r[1]}`,n}function cardinalPath(e,t){let n=e.length;if(n<3)return e.map(([e,t],n)=>`${n===0?`M`:`L`}${e},${t}`).join(``);let r=(1-t)/6,p=t=>e[Math.max(0,Math.min(n-1,t))],i=`M${e[0][0]},${e[0][1]}`;for(let e=0;e<n-1;e++){let t=p(e-1),n=p(e),a=p(e+1),o=p(e+2),s=n[0]+r*(a[0]-t[0]),c=n[1]+r*(a[1]-t[1]),l=a[0]-r*(o[0]-n[0]),u=a[1]-r*(o[1]-n[1]);i+=`C${s},${c} ${l},${u} ${a[0]},${a[1]}`}return i}function catmullRomPath(e,t){let n=e.length;if(n<3)return e.map(([e,t],n)=>`${n===0?`M`:`L`}${e},${t}`).join(``);let p=t=>e[Math.max(0,Math.min(n-1,t))],dist=(e,t)=>Math.hypot(t[0]-e[0],t[1]-e[1]),r=`M${e[0][0]},${e[0][1]}`;for(let e=0;e<n-1;e++){let n=p(e-1),i=p(e),a=p(e+1),o=p(e+2),s=dist(n,i)**+t||1e-6,c=dist(i,a)**+t||1e-6,l=dist(a,o)**+t||1e-6,u=a[0]-i[0]+c*((i[0]-n[0])/s-(a[0]-n[0])/(s+c)),d=a[1]-i[1]+c*((i[1]-n[1])/s-(a[1]-n[1])/(s+c)),f=a[0]-i[0]+c*((o[0]-a[0])/l-(o[0]-i[0])/(c+l)),m=a[1]-i[1]+c*((o[1]-a[1])/l-(o[1]-i[1])/(c+l)),h=i[0]+u/3,g=i[1]+d/3,_=a[0]-f/3,v=a[1]-m/3;r+=`C${h},${g} ${_},${v} ${a[0]},${a[1]}`}return r}function monotonePath(e){let t=e.length,n=[],r=[],i=[];for(let a=0;a<t-1;a++)n[a]=e[a+1][0]-e[a][0],r[a]=e[a+1][1]-e[a][1],i[a]=n[a]===0?0:r[a]/n[a];let a=[i[0]??0];for(let e=1;e<t-1;e++){let t=i[e-1],n=i[e];a[e]=t*n<=0?0:2*t*n/(t+n)}a[t-1]=i[t-2]??0;let o=`M${e[0][0]},${e[0][1]}`;for(let n=0;n<t-1;n++){let[t,r]=e[n],[i,s]=e[n+1],c=(i-t)/3;o+=`C${t+c},${r+c*a[n]} ${i-c},${s-c*a[n+1]} ${i},${s}`}return o}function areaPath(e,t,n=`linear`){if(e.length===0)return``;let r=linePath(e,n),i=e[e.length-1],a=e[0];return`${r}L${i[0]},${t}L${a[0]},${t}Z`}function arcPath(e,t,n,r,i,a){let o=2*Math.PI;if(Math.abs(a-i)>=o-1e-9){let a=i+Math.PI;return arcPath(e,t,n,r,i,a)+arcPath(e,t,n,r,a,i+o-1e-9)}let point=(n,r)=>[quantize(e+n*Math.sin(r)),quantize(t-n*Math.cos(r))],s=+(a-i>Math.PI),c=quantize(n),l=quantize(r),[u,d]=point(n,i),[f,m]=point(n,a);if(r<=0)return`M${quantize(e)},${quantize(t)}L${u},${d}A${c},${c} 0 ${s} 1 ${f},${m}Z`;let[h,g]=point(r,a),[_,v]=point(r,i);return`M${u},${d}A${c},${c} 0 ${s} 1 ${f},${m}L${h},${g}A${l},${l} 0 ${s} 0 ${_},${v}Z`}function stackSeries(e){let t=e[0]?.length??0,n=Array.from({length:t},()=>0);return e.map(e=>e.map((e,t)=>{let r=n[t];return n[t]=r+e,[r,n[t]]}))}var e={frame:`_frame_1gm0a_2`,"cascivo-chart-in":`_cascivo-chart-in_1gm0a_1`,fallback:`_fallback_1gm0a_78`};export{quantize as a,bandScale as c,sqrtScale as d,linePath as i,linearScale as l,arcPath as n,splitDefined as o,areaPath as r,stackSeries as s,e as t,niceTicks as u};

package/dist/index.d.ts

@@ -330,6 +330,15 @@ interface BarChartProps<Datum = {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /**
    * Approximate number of ticks on the **value** axis, whichever way the chart is turned.
@@ -1405,9 +1414,13 @@ interface LineChartSeries<Datum> {
 interface LineChartProps<Datum = {
   x: number;
   y: number;
-}> {
+}, XValue extends number | Date = number | Date> {
   series: readonly LineChartSeries<Datum>[];
-  x: (d: Datum) => number | Date;
+  /**
+   * X-value accessor. Its return type is inferred and threaded into `format`, so an `x` that
+   * returns `Date` gives you `format: (value: Date) => string` with no `instanceof` guard.
+   */
+  x: (d: Datum) => XValue;
   /**
    * Y-value accessor, applied to **every** series' data unless a series provides
    * its own `y`. There is one x-domain per chart, so `x` is chart-level only; to
@@ -1477,7 +1490,7 @@ interface LineChartProps<Datum = {
    * />
    * ```
    */
-  format?: (value: number | string | Date) => string;
+  format?: (value: XValue) => string;
   legend?: boolean;
   tooltip?: boolean;
   formatTooltip?: (datum: Datum, series: LineChartSeries<Datum>) => string;
@@ -1563,9 +1576,9 @@ interface LineChartProps<Datum = {
 declare function LineChart<Datum = {
   x: number;
   y: number;
-}>({
+}, XValue extends number | Date = number | Date>({
   series: rawSeries,
-  x,
+  x: xProp,
   y,
   title,
   description,
@@ -1595,7 +1608,7 @@ declare function LineChart<Datum = {
   transition,
   onBeforeDraw,
   onAfterDraw
-}: LineChartProps<Datum>): import("react").JSX.Element;
+}: LineChartProps<Datum, XValue>): import("react").JSX.Element;
 interface AreaDecimateOptions {
   method?: DecimateMethod;
   threshold?: number;
@@ -1637,14 +1650,17 @@ interface AreaChartSeries<Datum> {
 interface AreaChartProps<Datum = {
   x: number;
   y: number;
-}> {
+}, XValue extends number | Date = number | Date> {
   series: readonly AreaChartSeries<Datum>[];
   /**
    * X-value accessor. Return a `number` for a numeric axis, or a `Date` for a
    * time axis — when the values are Dates the chart uses a time scale and formats
    * ticks as dates (parity with `LineChart`). One x-domain per chart.
+   *
+   * Its return type is inferred and threaded into `format`, so an `x` that returns `Date`
+   * gives you `format: (value: Date) => string` with no `instanceof` guard to write.
    */
-  x: (d: Datum) => number | Date;
+  x: (d: Datum) => XValue;
   /**
    * Y-value accessor, applied to **every** series' data unless a series provides
    * its own `y`. There is one x-domain per chart, so `x` is chart-level only; to
@@ -1695,6 +1711,15 @@ interface AreaChartProps<Datum = {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /**
    * Approximate number of ticks on the x-axis.
@@ -1768,22 +1793,27 @@ interface AreaChartProps<Datum = {
   /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
   toolbox?: boolean | ToolboxOptions;
   /**
-   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a string,
-   * or a `Date`, whichever the series carries.
+   * Format each X-axis tick label. Receives the datum's raw `x` value, typed as whatever
+   * your `x` accessor returns — a `Date` when the series is a time series, a `number`
+   * otherwise.
    *
    * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for a
    * time series) renders as `1,785,217,000,000`. Passing `Date` objects switches the axis to
    * a time scale, but that format is fixed, so every bucket narrower than a day collapses to
    * the same label. Threads through `Axis`'s own `format` (2026-07-28 report C16).
+   *
+   * The parameter used to be widened to `number | string | Date` regardless, so every
+   * consumer wrote the same `v instanceof Date ? v : new Date(v)` guard against a value the
+   * chart already knew the type of (2026-08-31 report §28).
    */
-  format?: (value: number | string | Date) => string;
+  format?: (value: XValue) => string;
 }
 declare function AreaChart<Datum = {
   x: number;
   y: number;
-}>({
+}, XValue extends number | Date = number | Date>({
   series: rawSeries,
-  x,
+  x: xProp,
   y,
   title,
   description,
@@ -1811,7 +1841,7 @@ declare function AreaChart<Datum = {
   decimate,
   toolbox,
   format: xFormat
-}: AreaChartProps<Datum>): import("react").JSX.Element;
+}: AreaChartProps<Datum, XValue>): import("react").JSX.Element;
 interface PieChartDatum {
   id: string;
   label: string;
@@ -1825,6 +1855,15 @@ interface PieChartProps {
   description?: string;
   donut?: boolean;
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /** Square shorthand: sets width === height. Explicit width/height win. */
   size?: number;
@@ -1896,6 +1935,12 @@ interface ScatterChartProps {
   series: readonly ScatterChartSeries[];
   title: string;
   description?: string;
+  /**
+   * Point radius or accessor
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   r?: number | ((d: ScatterDatum) => number);
   /**
    * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
@@ -1906,6 +1951,15 @@ interface ScatterChartProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /**
    * Approximate number of ticks on the x-axis.
@@ -2063,6 +2117,15 @@ interface MeterProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
 }
 declare function Meter({
@@ -2152,6 +2215,15 @@ interface HistogramProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   className?: string;
   /**
@@ -2202,6 +2274,15 @@ interface BoxplotProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   className?: string;
   /**
@@ -2252,6 +2333,15 @@ interface BubbleChartProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   tooltip?: boolean;
   className?: string;
@@ -2397,6 +2487,15 @@ interface HeatmapProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   className?: string;
   /**
@@ -2449,6 +2548,15 @@ interface TreemapProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   className?: string;
   /**
@@ -2488,6 +2596,15 @@ interface RadarProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   className?: string;
   /**
@@ -2568,6 +2685,15 @@ interface RadialBarProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /** Domain top — the value a full sweep represents. Defaults to the largest datum. */
   max?: number;
@@ -2636,6 +2762,15 @@ interface FunnelProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /**
    * Append each stage’s % of the first stage to its label.
@@ -2706,6 +2841,15 @@ interface StreamProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   legend?: boolean;
   tooltip?: boolean;
@@ -2757,6 +2901,15 @@ interface SunburstProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   tooltip?: boolean;
   className?: string;
@@ -2794,6 +2947,15 @@ interface SankeyProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   tooltip?: boolean;
   className?: string;
@@ -2908,6 +3070,15 @@ interface CandlestickProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /**
    * Approximate number of ticks on the y-axis.
@@ -2920,7 +3091,12 @@ interface CandlestickProps {
   upColor?: string;
   /** Colour for down candles (close < open). */
   downColor?: string;
-  /** Render volume bars beneath the candles. */
+  /**
+   * Render volume bars beneath the candles.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   volume?: boolean;
   tooltip?: boolean;
   className?: string;
@@ -3005,6 +3181,15 @@ interface PolarProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   /**
    * Radial ring count.
@@ -3088,6 +3273,15 @@ interface GaugeProps {
    * @see the component manifest
    */
   width?: number;
+  /**
+   * Fixed plot-area height in px — the SVG only; the title, description and legend render
+   * outside it. ⚠ **Omit for a responsive chart**, exactly like `width`: height tracks the
+   * container via the same `ResizeObserver`, so in a `Card` that stretches to a taller
+   * sibling the plot fills the space left over (and falls back to 300px in an auto-height
+   * parent). A pinned `height={280}` is what leaves dead space at the bottom of the taller
+   * card in a `Grid` (2026-08-31 report §29).
+   * @see the component manifest
+   */
   height?: number;
   className?: string;
   /**