@cascivo/charts 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,684 @@
+import { ReactNode } from "react";
+import { Signal } from "@preact/signals-react";
+
+interface LinearScale {
+  domain: [number, number];
+  range: [number, number];
+  map(value: number): number;
+  invert(position: number): number;
+  ticks(count?: number): number[];
+}
+declare function linearScale(domain: [number, number], range: [number, number]): LinearScale;
+/** Extended nice-numbers: steps are 1, 2, 2.5 or 5 × 10^k covering [min, max]. */
+declare function niceTicks(min: number, max: number, count?: number): number[];
+interface BandScale<T extends string = string> {
+  domain: readonly T[];
+  range: [number, number];
+  bandwidth: number;
+  map(value: T): number | undefined;
+}
+declare function bandScale<T extends string>(domain: readonly T[], range: [number, number], padding?: number): BandScale<T>;
+/** Square-root scale for area-proportional bubble sizes. Maps values in sqrt space. */
+declare function sqrtScale(domain: [number, number], range: [number, number]): (value: number) => number;
+interface LogScale {
+  domain: [number, number];
+  range: [number, number];
+  map(value: number): number;
+  invert(position: number): number;
+  ticks(): number[];
+}
+declare function logScale(domain: [number, number], range: [number, number]): LogScale;
+interface TimeScale {
+  domain: [Date, Date];
+  range: [number, number];
+  map(value: Date): number;
+  invert(position: number): Date;
+  ticks(count?: number): Date[];
+  tickInterval(): 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+  tickFormat(): Intl.DateTimeFormatOptions;
+}
+declare function timeScale(domain: [Date, Date], range: [number, number]): TimeScale;
+type Point = readonly [x: number, y: number];
+declare function linePath(points: readonly Point[], curve?: 'linear' | 'monotone'): string;
+declare function areaPath(points: readonly Point[], baseline: number, curve?: 'linear' | 'monotone'): string;
+declare function arcPath(cx: number, cy: number, outerRadius: number, innerRadius: number, startAngle: number, endAngle: number): string;
+declare function stackSeries(series: readonly (readonly number[])[]): [number, number][][];
+/** Binary search for the index of the nearest value in a sorted array. */
+declare function nearestIndex(values: readonly number[], target: number): number;
+/** Statistical helpers for histogram and boxplot charts. */
+interface Bin {
+  x0: number;
+  x1: number;
+  count: number;
+}
+/**
+ * Freedman–Diaconis bin width with sane fallbacks.
+ * Returns inclusive-exclusive bins covering [min, max].
+ */
+declare function binValues(values: readonly number[], binCount?: number): Bin[];
+interface BoxStats {
+  min: number;
+  q1: number;
+  median: number;
+  q3: number;
+  max: number;
+  outliers: number[];
+}
+/** Five-number summary with outlier detection via 1.5×IQR fences. */
+declare function boxStats(values: readonly number[]): BoxStats;
+/** [min, max] extent of an array of numbers. */
+declare function extent(values: readonly number[]): [number, number];
+/** Squarified treemap layout algorithm. */
+interface TreemapNode {
+  id: string;
+  value: number;
+}
+interface TreemapRect {
+  id: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+/**
+ * Squarified treemap algorithm (~60 lines).
+ * Returns rectangles positioned within [0, width] × [0, height].
+ */
+declare function squarify(nodes: TreemapNode[], width: number, height: number): TreemapRect[];
+/** A single focusable data point for the chart tooltip system.
+ * cx/cy are absolute SVG coordinates (already include margin offsets). */
+interface ChartPoint {
+  id: string;
+  /** Absolute SVG x coordinate */
+  cx: number;
+  /** Absolute SVG y coordinate */
+  cy: number;
+  /** Category label or x-axis label */
+  label: string;
+  /** Datum value (y or measure) */
+  value: number | string;
+  seriesId?: string;
+}
+interface TooltipModel {
+  /** All focusable points in traversal order */
+  points: ChartPoint[];
+  /** Custom formatter — defaults to "label: value" */
+  format?: (p: ChartPoint) => string;
+}
+interface ChartFrameProps {
+  title: string;
+  description?: string | undefined;
+  width?: number | undefined;
+  height?: number | undefined;
+  fallback?: ReactNode;
+  children: (size: {
+    width: number;
+    height: number;
+  }) => ReactNode;
+  className?: string | undefined;
+  'data-state'?: string | undefined;
+  plain?: boolean | undefined;
+  /**
+   * Tooltip model. Pass a TooltipModel directly, or a factory function that
+   * receives the resolved chart size so cx/cy can be computed from scales.
+   */
+  tooltip?: TooltipModel | ((size: {
+    width: number;
+    height: number;
+  }) => TooltipModel | undefined) | undefined;
+}
+declare function ChartFrame({
+  title,
+  description,
+  width: fixedWidth,
+  height: fixedHeight,
+  fallback,
+  children,
+  className,
+  'data-state': dataState,
+  plain,
+  tooltip
+}: ChartFrameProps): import("react").JSX.Element;
+interface ChartSize {
+  width: number;
+  height: number;
+}
+declare function useChartSize(defaultWidth?: number, defaultHeight?: number): {
+  ref: React.RefObject<HTMLDivElement | null>;
+  width: import('@preact/signals-react').Signal<number>;
+  height: import('@preact/signals-react').Signal<number>;
+};
+declare const DEFAULT_MARGINS: {
+  readonly top: 8;
+  readonly right: 8;
+  readonly bottom: 24;
+  readonly left: 36;
+};
+/** Margins for plain (chrome-less) charts — just enough to keep strokes unclipped. */
+declare const PLAIN_MARGINS: {
+  readonly top: 2;
+  readonly right: 2;
+  readonly bottom: 2;
+  readonly left: 2;
+};
+type AnyScale = LinearScale | BandScale | LogScale | TimeScale;
+interface AxisProps {
+  scale: AnyScale;
+  orientation: 'x' | 'y';
+  length: number;
+  format?: (value: number | string | Date) => string;
+  tickCount?: number;
+  transform?: string;
+}
+declare function Axis({
+  scale,
+  orientation,
+  length,
+  format,
+  tickCount,
+  transform
+}: AxisProps): import("react").JSX.Element;
+interface GridLinesProps {
+  scale: LinearScale;
+  orientation: 'x' | 'y';
+  length: number;
+  tickCount?: number;
+  transform?: string;
+}
+declare function GridLines({
+  scale,
+  orientation,
+  length,
+  tickCount,
+  transform
+}: GridLinesProps): import("react").JSX.Element;
+interface LegendSeries {
+  id: string;
+  label: string;
+  color: string;
+}
+interface LegendProps {
+  series: readonly LegendSeries[];
+  hidden: Signal<Set<string>>;
+}
+declare function Legend({
+  series,
+  hidden
+}: LegendProps): import("react").JSX.Element;
+interface LineChartSeries<Datum> {
+  id: string;
+  label: string;
+  data: readonly Datum[];
+  color?: string;
+}
+interface LineChartProps<Datum = {
+  x: number;
+  y: number;
+}> {
+  series: readonly LineChartSeries<Datum>[];
+  x: (d: Datum) => number | Date;
+  y: (d: Datum) => number;
+  title: string;
+  description?: string;
+  curve?: 'linear' | 'monotone';
+  width?: number;
+  height?: number;
+  xTicks?: number;
+  yTicks?: number;
+  legend?: boolean;
+  tooltip?: boolean;
+  formatTooltip?: (datum: Datum, series: LineChartSeries<Datum>) => string;
+  className?: string;
+  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function LineChart<Datum = {
+  x: number;
+  y: number;
+}>({
+  series,
+  x,
+  y,
+  title,
+  description,
+  curve,
+  width: fixedWidth,
+  height,
+  xTicks,
+  yTicks,
+  legend,
+  tooltip,
+  formatTooltip,
+  className,
+  plain
+}: LineChartProps<Datum>): import("react").JSX.Element;
+interface AreaChartSeries<Datum> {
+  id: string;
+  label: string;
+  data: readonly Datum[];
+  color?: string;
+}
+interface AreaChartProps<Datum = {
+  x: number;
+  y: number;
+}> {
+  series: readonly AreaChartSeries<Datum>[];
+  x: (d: Datum) => number;
+  y: (d: Datum) => number;
+  title: string;
+  description?: string;
+  stacked?: boolean;
+  curve?: 'linear' | 'monotone';
+  width?: number;
+  height?: number;
+  xTicks?: number;
+  yTicks?: number;
+  legend?: boolean;
+  tooltip?: boolean;
+  className?: string;
+  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function AreaChart<Datum = {
+  x: number;
+  y: number;
+}>({
+  series,
+  x,
+  y,
+  title,
+  description,
+  stacked,
+  curve,
+  width: fixedWidth,
+  height,
+  xTicks,
+  yTicks,
+  legend,
+  tooltip,
+  className,
+  plain
+}: AreaChartProps<Datum>): import("react").JSX.Element;
+interface BarChartSeries<Datum> {
+  id: string;
+  label: string;
+  data: readonly Datum[];
+  color?: string;
+}
+interface BarChartProps<Datum = {
+  x: string;
+  y: number;
+}> {
+  series: readonly BarChartSeries<Datum>[];
+  x: (d: Datum) => string;
+  y: (d: Datum) => number;
+  title: string;
+  description?: string;
+  orientation?: 'vertical' | 'horizontal';
+  mode?: 'grouped' | 'stacked';
+  width?: number;
+  height?: number;
+  xTicks?: number;
+  yTicks?: number;
+  legend?: boolean;
+  tooltip?: boolean;
+  className?: string;
+  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function BarChart<Datum = {
+  x: string;
+  y: number;
+}>({
+  series,
+  x,
+  y,
+  title,
+  description,
+  orientation,
+  mode,
+  width: fixedWidth,
+  height,
+  xTicks,
+  yTicks,
+  legend,
+  tooltip,
+  className,
+  plain
+}: BarChartProps<Datum>): import("react").JSX.Element;
+interface PieChartDatum {
+  id: string;
+  label: string;
+  value: number;
+  color?: string;
+}
+interface PieChartProps {
+  data: readonly PieChartDatum[];
+  title: string;
+  description?: string;
+  donut?: boolean;
+  width?: number;
+  height?: number;
+  legend?: boolean;
+  className?: string;
+  /** Render only the marks — no legend. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function PieChart({
+  data,
+  title,
+  description,
+  donut,
+  width: fixedWidth,
+  height,
+  legend,
+  className,
+  plain
+}: PieChartProps): import("react").JSX.Element;
+interface ScatterDatum {
+  x: number;
+  y: number;
+  r?: number;
+}
+interface ScatterChartSeries {
+  id: string;
+  label: string;
+  data: readonly ScatterDatum[];
+  color?: string;
+}
+interface ScatterChartProps {
+  series: readonly ScatterChartSeries[];
+  title: string;
+  description?: string;
+  r?: number | ((d: ScatterDatum) => number);
+  width?: number;
+  height?: number;
+  xTicks?: number;
+  yTicks?: number;
+  legend?: boolean;
+  tooltip?: boolean;
+  className?: string;
+  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function ScatterChart({
+  series,
+  title,
+  description,
+  r: rProp,
+  width: fixedWidth,
+  height,
+  xTicks,
+  yTicks,
+  legend,
+  tooltip,
+  className,
+  plain
+}: ScatterChartProps): import("react").JSX.Element;
+interface SparklineProps {
+  data: readonly number[];
+  width?: number;
+  height?: number;
+  label: string;
+  color?: string;
+  endDot?: boolean;
+}
+declare function Sparkline({
+  data,
+  width,
+  height,
+  label,
+  color,
+  endDot
+}: SparklineProps): import("react").JSX.Element;
+interface MeterThresholds {
+  warning?: number;
+  critical?: number;
+}
+interface MeterProps {
+  value: number;
+  min?: number;
+  max?: number;
+  label: string;
+  variant?: 'bar' | 'gauge';
+  thresholds?: MeterThresholds;
+  width?: number;
+  height?: number;
+}
+declare function Meter({
+  value,
+  min,
+  max,
+  label,
+  variant,
+  thresholds,
+  width,
+  height
+}: MeterProps): import("react").JSX.Element;
+interface KpiProps {
+  value: string | number;
+  label: string;
+  delta?: number;
+  deltaLabel?: string;
+  icon?: ReactNode;
+  sparkline?: readonly number[];
+  className?: string;
+}
+declare function Kpi({
+  value,
+  label,
+  delta,
+  deltaLabel,
+  icon,
+  sparkline,
+  className
+}: KpiProps): import("react").JSX.Element;
+interface HistogramProps {
+  data: number[];
+  bins?: number;
+  title: string;
+  label: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  /** Render only the marks — no axes or grid lines. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function Histogram({
+  data,
+  bins,
+  title,
+  label: _label,
+  description,
+  width: fixedWidth,
+  height,
+  className,
+  plain
+}: HistogramProps): import("react").JSX.Element;
+interface BoxplotSeries {
+  id: string;
+  label: string;
+  values: number[];
+}
+interface BoxplotProps {
+  series: BoxplotSeries[];
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  /** Render only the marks — no axes. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function Boxplot({
+  series,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  className,
+  plain
+}: BoxplotProps): import("react").JSX.Element;
+interface BubbleDatum {
+  x: number;
+  y: number;
+  size: number;
+}
+interface BubbleSeries {
+  name: string;
+  data: BubbleDatum[];
+}
+interface BubbleChartProps {
+  series: BubbleSeries[];
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  tooltip?: boolean;
+  className?: string;
+  /** Render only the marks — no axes or grid lines. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function BubbleChart({
+  series,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  tooltip,
+  className,
+  plain
+}: BubbleChartProps): import("react").JSX.Element;
+interface ComboChartBar {
+  label: string;
+  value: number;
+}
+interface ComboChartPoint {
+  x: number;
+  y: number;
+}
+interface ComboChartProps {
+  bars: ComboChartBar[];
+  line: ComboChartPoint[];
+  title: string;
+  description?: string;
+  secondAxis?: boolean;
+  width?: number;
+  height?: number;
+  tooltip?: boolean;
+  className?: string;
+  /** Render only the marks — no axes or grid lines. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function ComboChart({
+  bars,
+  line,
+  title,
+  description,
+  secondAxis,
+  width: fixedWidth,
+  height,
+  tooltip,
+  className,
+  plain
+}: ComboChartProps): import("react").JSX.Element;
+interface HeatmapDatum {
+  x: string;
+  y: string;
+  value: number;
+}
+interface HeatmapProps {
+  data: HeatmapDatum[];
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  /** Render only the marks — no axes. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function Heatmap({
+  data,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  className,
+  plain
+}: HeatmapProps): import("react").JSX.Element;
+interface TreemapDatum {
+  id: string;
+  label: string;
+  value: number;
+}
+interface TreemapProps {
+  data: TreemapDatum[];
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  /** Render only the colored rects — no text labels. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function Treemap({
+  data,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  className,
+  plain
+}: TreemapProps): import("react").JSX.Element;
+interface RadarSeries {
+  id: string;
+  label: string;
+  values: number[];
+}
+interface RadarProps {
+  axes: string[];
+  series: RadarSeries[];
+  max?: number;
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  /** Render only the data polygons — no rings, spokes, or axis labels. For micro/inline charts. */
+  plain?: boolean;
+}
+declare function Radar({
+  axes,
+  series,
+  max,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  className,
+  plain
+}: RadarProps): import("react").JSX.Element;
+interface BulletProps {
+  value: number;
+  target: number;
+  ranges: number[];
+  label: string;
+  min?: number;
+  max?: number;
+  width?: number;
+  height?: number;
+  className?: string;
+}
+declare function Bullet({
+  value,
+  target,
+  ranges,
+  label,
+  min,
+  max,
+  width,
+  height,
+  className
+}: BulletProps): import("react").JSX.Element;
+export { AreaChart, AreaChartProps, AreaChartSeries, Axis, AxisProps, BandScale, BarChart, BarChartProps, BarChartSeries, Bin, BoxStats, Boxplot, BoxplotProps, BoxplotSeries, BubbleChart, BubbleChartProps, BubbleDatum, BubbleSeries, Bullet, BulletProps, ChartFrame, ChartFrameProps, ChartSize, ComboChart, ComboChartBar, ComboChartPoint, ComboChartProps, DEFAULT_MARGINS, GridLines, GridLinesProps, Heatmap, HeatmapDatum, HeatmapProps, Histogram, HistogramProps, Kpi, KpiProps, Legend, LegendProps, LegendSeries, LineChart, LineChartProps, LineChartSeries, LinearScale, LogScale, Meter, MeterProps, MeterThresholds, PLAIN_MARGINS, PieChart, PieChartDatum, PieChartProps, Point, Radar, RadarProps, RadarSeries, ScatterChart, ScatterChartProps, ScatterChartSeries, ScatterDatum, Sparkline, SparklineProps, TimeScale, Treemap, TreemapDatum, TreemapNode, TreemapProps, TreemapRect, arcPath, areaPath, bandScale, binValues, boxStats, extent, linePath, linearScale, logScale, nearestIndex, niceTicks, sqrtScale, squarify, stackSeries, timeScale, useChartSize };