@cascivo/charts 0.4.1 → 0.5.1

package/README.md

@@ -3,7 +3,7 @@
 <div align="center">
   <a href="https://cascivo.com"><img src="https://cascivo.com/favicon.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</strong></p>
+  <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>
 
 [![npm](https://img.shields.io/npm/v/%40cascivo%2Fcharts?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/charts)
 [![downloads](https://img.shields.io/npm/dm/%40cascivo%2Fcharts?style=flat-square&color=0079bf)](https://www.npmjs.com/package/@cascivo/charts)
@@ -18,6 +18,8 @@
 
 Accessible, signal-driven chart library for cascivo — AreaChart, BarChart, LineChart, Sparkline, Heatmap, and more. All charts are keyboard-navigable with `aria-live` tooltips. CVD-safe palettes (Okabe-Ito, oklch) verified in CI across all 12 themes.
 
+> **Docs offline?** The full cascivo reference ships as an npm package — `npx -y @cascivo/docs`, no website needed.
+
 ## Install
 
 ```sh
@@ -49,6 +51,24 @@ export function Traffic() {
 Charts are CSS-token-themed: drop them inside any element carrying a `data-theme` (or import a
 theme stylesheet) and they pick up the same palette, radii, and typography as the rest of cascivo.
 
+### Sizing — responsive by default
+
+**Omit `width`** and the chart fills and tracks its container (a `ResizeObserver`
+watches the slot), so a chart drops cleanly into a responsive `Card` or grid cell with
+no measuring on your part. `height` defaults to `300` (px); set it to change the aspect.
+
+Pass an explicit `width` only for a fixed-size export — and even then it is **clamped to
+the container** (`max-inline-size: 100%`), so an over-wide `width` scales down instead of
+overflowing and clipping data. To size another element to match a chart, or to build a
+custom chart, use the exported `useChartSize()` hook.
+
+```tsx
+<Card>
+  <LineChart data={data} />           {/* fills the card, resizes with it */}
+</Card>
+<LineChart data={data} height={160} /> {/* shorter, still full-width */}
+```
+
 > **Vite SSR (TanStack Start, Remix, vite-ssr, workerd)?** Like the rest of cascivo, the
 > chart CSS ships as side-effect imports a bare server loader can't resolve — mark
 > `ssr: { noExternal: [/^@cascivo\//] }` (the pattern already covers `@cascivo/charts`) and

package/dist/charts.css

@@ -1,2 +1,2 @@
-@layer cascivo.component{._frame_1doa7_2{inline-size:100%;position:relative}@media (prefers-reduced-motion:no-preference){._frame_1doa7_2>svg{animation:_cascivo-chart-in_1doa7_1 var(--cascivo-chart-anim-dur,.32s) var(--cascivo-chart-anim-ease,ease-out) both}@keyframes _cascivo-chart-in_1doa7_1{0%{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}._frame_1doa7_2 svg :is(path,rect,circle,line)[data-series],._frame_1doa7_2 svg path[data-link],._frame_1doa7_2 svg path[data-depth],._frame_1doa7_2 svg rect[data-day]{transition-property:var(--cascivo-chart-anim-props,opacity, fill, fill-opacity);transition-duration:var(--cascivo-chart-anim-dur,.24s);transition-timing-function:var(--cascivo-chart-anim-ease,ease)}._frame_1doa7_2[data-no-anim]>svg{animation:none}._frame_1doa7_2[data-no-anim] svg :is(path,rect,circle,line)[data-series],._frame_1doa7_2[data-no-anim] svg path[data-link],._frame_1doa7_2[data-no-anim] svg path[data-depth],._frame_1doa7_2[data-no-anim] svg rect[data-day]{transition:none}}._fallback_1doa7_53{clip-path:inset(50%);white-space:nowrap;block-size:1px;inline-size:1px;position:absolute;inset-inline-start:-9999px;overflow:hidden}._legend_zczeh_2{gap:var(--cascivo-space-2);padding-block:var(--cascivo-space-2);flex-wrap:wrap;display:flex}._item_zczeh_9{align-items:center;gap:var(--cascivo-space-1);padding:var(--cascivo-space-1) var(--cascivo-space-2);border:1px solid var(--cascivo-color-border);border-radius:var(--cascivo-radius-sm);cursor:pointer;font-size:var(--cascivo-font-size-sm);color:var(--cascivo-color-text);transition:opacity var(--cascivo-duration-150,.15s) ease;background:0 0;display:flex}._item_zczeh_9[data-state=off]{opacity:.4}._swatch_zczeh_27{border-radius:2px;flex-shrink:0;block-size:12px;inline-size:12px;display:inline-block}}
+@layer cascivo.component{._frame_1xxqo_2{inline-size:100%;position:relative}._frame_1xxqo_2>svg{block-size:auto;max-inline-size:100%}@media (prefers-reduced-motion:no-preference){._frame_1xxqo_2>svg{animation:_cascivo-chart-in_1xxqo_1 var(--cascivo-chart-anim-dur,.32s) var(--cascivo-chart-anim-ease,ease-out) both}@keyframes _cascivo-chart-in_1xxqo_1{0%{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}._frame_1xxqo_2 svg :is(path,rect,circle,line)[data-series],._frame_1xxqo_2 svg path[data-link],._frame_1xxqo_2 svg path[data-depth],._frame_1xxqo_2 svg rect[data-day]{transition-property:var(--cascivo-chart-anim-props,opacity, fill, fill-opacity);transition-duration:var(--cascivo-chart-anim-dur,.24s);transition-timing-function:var(--cascivo-chart-anim-ease,ease)}._frame_1xxqo_2[data-no-anim]>svg{animation:none}._frame_1xxqo_2[data-no-anim] svg :is(path,rect,circle,line)[data-series],._frame_1xxqo_2[data-no-anim] svg path[data-link],._frame_1xxqo_2[data-no-anim] svg path[data-depth],._frame_1xxqo_2[data-no-anim] svg rect[data-day]{transition:none}}._fallback_1xxqo_62{clip-path:inset(50%);white-space:nowrap;block-size:1px;inline-size:1px;position:absolute;inset-inline-start:-9999px;overflow:hidden}._legend_zczeh_2{gap:var(--cascivo-space-2);padding-block:var(--cascivo-space-2);flex-wrap:wrap;display:flex}._item_zczeh_9{align-items:center;gap:var(--cascivo-space-1);padding:var(--cascivo-space-1) var(--cascivo-space-2);border:1px solid var(--cascivo-color-border);border-radius:var(--cascivo-radius-sm);cursor:pointer;font-size:var(--cascivo-font-size-sm);color:var(--cascivo-color-text);transition:opacity var(--cascivo-duration-150,.15s) ease;background:0 0;display:flex}._item_zczeh_9[data-state=off]{opacity:.4}._swatch_zczeh_27{border-radius:2px;flex-shrink:0;block-size:12px;inline-size:12px;display:inline-block}}
 /*$vite$:1*/

package/dist/index.d.ts

@@ -765,7 +765,15 @@ interface ZoomConfig {
 interface ChartFrameProps {
   title: string;
   description?: string | undefined;
+  /**
+   * Fixed SVG width in px. **Omit it (the default) for a responsive chart** — the
+   * frame fills and tracks its container's width via `ResizeObserver`. Set a fixed
+   * width only for a fixed-size export or thumbnail; even then it is clamped to the
+   * container (`max-inline-size: 100%`) so it can never overflow its card.
+   */
   width?: number | undefined;
+  /** SVG height in px. Defaults to 300 (48 in `plain` mode). Unlike `width`, height
+   * does not track the container — set it to change the chart's aspect. */
   height?: number | undefined;
   fallback?: ReactNode;
   children: (size: {
@@ -847,6 +855,20 @@ interface ChartSize {
   width: number;
   height: number;
 }
+/**
+ * Measure a container and track its size in signals. **Every cascivo chart already
+ * uses this internally** — charts are responsive by default and fill their
+ * container, so you do NOT need this to make a chart responsive (just omit the
+ * chart's `width`). Reach for it only to size *another* element to match a chart,
+ * or to build a custom chart on the same measurement primitive.
+ *
+ * Returns `{ ref, width, height }`: spread `ref` onto the element to measure; read
+ * `width.value` / `height.value` (they update on resize via a `ResizeObserver`,
+ * deferred one frame to avoid the "ResizeObserver loop" warning). Under SSR (no
+ * `ResizeObserver`) it falls back to a single `getBoundingClientRect()` read, so
+ * the first paint has a sensible size. `defaultWidth` seeds the signal only until
+ * the first real measurement lands.
+ */
 declare function useChartSize(defaultWidth?: number, defaultHeight?: number): {
   ref: React.RefObject<HTMLDivElement | null>;
   width: import('@preact/signals-react').Signal<number>;
@@ -865,6 +887,19 @@ declare const PLAIN_MARGINS: {
   readonly bottom: 2;
   readonly left: 2;
 };
+/**
+ * Left margin sized to the widest left-axis label so wide ticks (e.g. `40,000`)
+ * aren't clipped past the SVG's `0` origin. The default 36px only fits ~4 glyphs;
+ * a 6-glyph thousands label needs ~45px. `plain` charts keep their tiny margin.
+ */
+declare function leftMarginForLabels(leftAxisLabels: readonly string[], plain: boolean | undefined): number;
+/**
+ * Stride for a crowded categorical (band) axis: render every Nth label so they stop
+ * colliding (e.g. 14 `Jul 1`…`Jul 14` dates in a narrow chart). Returns `undefined`
+ * when every label fits — callers pass that straight to `Axis.labelEvery` (all shown).
+ * An explicit `xLabelEvery` from the caller always overrides this.
+ */
+declare function autoLabelStride(labels: readonly string[], axisLength: number): number | undefined;
 /**
  * Pure index-window math shared by the DataZoom slider and the in-plot wheel/drag
  * zoom-pan. A "window" is an inclusive `[startIndex, endIndex]` over a series of
@@ -1272,7 +1307,12 @@ interface AreaChartProps<Datum = {
   y: number;
 }> {
   series: readonly AreaChartSeries<Datum>[];
-  x: (d: Datum) => number;
+  /**
+   * 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.
+   */
+  x: (d: Datum) => number | Date;
   /**
    * 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
@@ -2089,4 +2129,4 @@ declare function Gauge({
   className,
   plain
 }: GaugeProps): import("react").JSX.Element;
-export { AggOp, AggregateSpec, AngleBand, Annotation, AnnotationContext, AnnotationScale, AreaChart, AreaChartProps, AreaChartSeries, AreaDecimateOptions, Axis, AxisProps, BandScale, BarChart, BarChartProps, BarChartSeries, Bin, BoundStream, BoxStats, Boxplot, BoxplotProps, BoxplotSeries, Brush, BrushProps, BubbleChart, BubbleChartProps, BubbleDatum, BubbleSeries, Bullet, BulletProps, Calendar, CalendarDatum, CalendarProps, Candlestick, CandlestickDatum, CandlestickProps, CanvasLayer, CanvasLayerProps, CanvasPaint, CanvasSize, CategoryDatum, CategoryMapping, ChartDefs, ChartDefsProps, ChartFrame, ChartFrameProps, ChartSize, ComboChart, ComboChartBar, ComboChartPoint, ComboChartProps, Curve, DEFAULT_MARGINS, DataLabel, DataLabelProps, DataZoom, DataZoomProps, DecimateMethod, DecimateOptions, DefSeries, EncodeMapping, EncodedResult, EncodedSeries, FillKind, Funnel, FunnelProps, FunnelStage, Gauge, GaugeProps, GaugeThreshold, Glyph, GlyphProps, GlyphShape, GridLines, GridLinesProps, Heatmap, HeatmapDatum, HeatmapProps, HierNode, Histogram, HistogramBin, HistogramProps, Kpi, KpiProps, LabelOptions, LaidLink, LaidNode, Legend, LegendProps, LegendSeries, LineChart, LineChartProps, LineChartSeries, LinearScale, LogScale, Meter, MeterProps, MeterThresholds, PLAIN_MARGINS, PartitionedNode, PatternKind, PieChart, PieChartDatum, PieChartProps, Point, Polar, PolarDatum, PolarProps, Pt, Radar, RadarProps, RadarSeries, RadialBar, RadialBarDatum, RadialBarProps, RampKind, Rect, RegressionResult, RegressionType, ResolvedLabelOptions, Row, Sankey, SankeyLayout, SankeyLink, SankeyNode, SankeyOptions, SankeyProps, ScatterChart, ScatterChartProps, ScatterChartSeries, ScatterDatum, Sparkline, SparklineProps, StackedRow, StackedSegment, Stream, StreamDecimate, StreamOffset, StreamProps, StreamSeries, StreamSeriesOptions, StreamSource, Sunburst, SunburstProps, SyncGroup, Text, TextProps, TimeScale, Toolbox, ToolboxOptions, ToolboxProps, Treemap, TreemapDatum, TreemapNode, TreemapProps, TreemapRect, Vec, VisualChannel, VisualMap, VisualMapOptions, VisualMapProps, VisualMode, VisualResult, ZoomConfig, _syncGroupCount, aggregate, angleBand, annotationSummary, arcPath, areaPath, bandScale, bin, binValues, bindStream, boxStats, cellPath, decimate$1 as decimate, divergingRamp, download, encode, encodeCategory, extent, fillFor, filter, getSyncGroup, glyphPath, gradientId, isZoomed, linePath, linearScale, linkPath, logScale, lttb, mapVisual, maxDepth, minmax, nearestIndex, niceTicks, panWindow, partition, patternId, pieceIndex, polarPoint, quantize, radiusScale, rampLightness, rampOf, rampStops, regression, releaseSyncGroup, renderAnnotation, renderAnnotations, resolveColor, resolveLabels, sankeyLayout, sequentialRamp, serializeSvg, sort, splitDefined, sqrtScale, squarify, stackSeries, streamExtent, streamLayout, sumValue, svgToPngBlob, timeScale, toStackedSeries, useChartSize, useStreamSeries, visualVisible, voronoiCells, voronoiFind, wrapText, zoomWindow };
+export { AggOp, AggregateSpec, AngleBand, Annotation, AnnotationContext, AnnotationScale, AreaChart, AreaChartProps, AreaChartSeries, AreaDecimateOptions, Axis, AxisProps, BandScale, BarChart, BarChartProps, BarChartSeries, Bin, BoundStream, BoxStats, Boxplot, BoxplotProps, BoxplotSeries, Brush, BrushProps, BubbleChart, BubbleChartProps, BubbleDatum, BubbleSeries, Bullet, BulletProps, Calendar, CalendarDatum, CalendarProps, Candlestick, CandlestickDatum, CandlestickProps, CanvasLayer, CanvasLayerProps, CanvasPaint, CanvasSize, CategoryDatum, CategoryMapping, ChartDefs, ChartDefsProps, ChartFrame, ChartFrameProps, ChartSize, ComboChart, ComboChartBar, ComboChartPoint, ComboChartProps, Curve, DEFAULT_MARGINS, DataLabel, DataLabelProps, DataZoom, DataZoomProps, DecimateMethod, DecimateOptions, DefSeries, EncodeMapping, EncodedResult, EncodedSeries, FillKind, Funnel, FunnelProps, FunnelStage, Gauge, GaugeProps, GaugeThreshold, Glyph, GlyphProps, GlyphShape, GridLines, GridLinesProps, Heatmap, HeatmapDatum, HeatmapProps, HierNode, Histogram, HistogramBin, HistogramProps, Kpi, KpiProps, LabelOptions, LaidLink, LaidNode, Legend, LegendProps, LegendSeries, LineChart, LineChartProps, LineChartSeries, LinearScale, LogScale, Meter, MeterProps, MeterThresholds, PLAIN_MARGINS, PartitionedNode, PatternKind, PieChart, PieChartDatum, PieChartProps, Point, Polar, PolarDatum, PolarProps, Pt, Radar, RadarProps, RadarSeries, RadialBar, RadialBarDatum, RadialBarProps, RampKind, Rect, RegressionResult, RegressionType, ResolvedLabelOptions, Row, Sankey, SankeyLayout, SankeyLink, SankeyNode, SankeyOptions, SankeyProps, ScatterChart, ScatterChartProps, ScatterChartSeries, ScatterDatum, Sparkline, SparklineProps, StackedRow, StackedSegment, Stream, StreamDecimate, StreamOffset, StreamProps, StreamSeries, StreamSeriesOptions, StreamSource, Sunburst, SunburstProps, SyncGroup, Text, TextProps, TimeScale, Toolbox, ToolboxOptions, ToolboxProps, Treemap, TreemapDatum, TreemapNode, TreemapProps, TreemapRect, Vec, VisualChannel, VisualMap, VisualMapOptions, VisualMapProps, VisualMode, VisualResult, ZoomConfig, _syncGroupCount, aggregate, angleBand, annotationSummary, arcPath, areaPath, autoLabelStride, bandScale, bin, binValues, bindStream, boxStats, cellPath, decimate$1 as decimate, divergingRamp, download, encode, encodeCategory, extent, fillFor, filter, getSyncGroup, glyphPath, gradientId, isZoomed, leftMarginForLabels, linePath, linearScale, linkPath, logScale, lttb, mapVisual, maxDepth, minmax, nearestIndex, niceTicks, panWindow, partition, patternId, pieceIndex, polarPoint, quantize, radiusScale, rampLightness, rampOf, rampStops, regression, releaseSyncGroup, renderAnnotation, renderAnnotations, resolveColor, resolveLabels, sankeyLayout, sequentialRamp, serializeSvg, sort, splitDefined, sqrtScale, squarify, stackSeries, streamExtent, streamLayout, sumValue, svgToPngBlob, timeScale, toStackedSeries, useChartSize, useStreamSeries, visualVisible, voronoiCells, voronoiFind, wrapText, zoomWindow };