@cascivo/charts 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 urbanisierung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -43,6 +43,126 @@ declare function linePath(points: readonly Point[], curve?: 'linear' | 'monotone
 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][][];
+/** 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;
+  /** Share of the whole, 0–100 (pie/donut). Available to a custom formatter. */
+  percent?: number;
+  /** Mark color for this point — used to tint the tooltip text. */
+  color?: string;
+  /** Per-segment breakdown for a stacked category, in layer order. */
+  segments?: readonly {
+    label: string;
+    value: number;
+    color?: string;
+  }[];
+}
+interface TooltipModel {
+  /** All focusable points in traversal order */
+  points: ChartPoint[];
+  /** Custom formatter — defaults to "label: value" */
+  format?: (p: ChartPoint) => string;
+}
+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;
+  /** Show every Nth category label (and always the last) to thin a crowded x-axis. */
+  xLabelEvery?: number;
+  legend?: boolean;
+  tooltip?: boolean;
+  /** Custom tooltip formatter. Stacked default lists "label · total" + per-layer values. */
+  tooltipFormat?: (p: ChartPoint) => string;
+  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,
+  xLabelEvery,
+  legend,
+  tooltip,
+  tooltipFormat,
+  className,
+  plain
+}: BarChartProps<Datum>): import("react").JSX.Element;
+/** One layer of a stacked bar at a category. */
+interface StackedSegment {
+  /** Layer key — becomes the series id/label (e.g. "Done", "In progress"). */
+  key: string;
+  value: number;
+  /** Optional CSS color for this layer; the first non-undefined per key wins. */
+  color?: string;
+}
+/** A single category (bar) with its per-layer segments. */
+interface StackedRow {
+  label: string;
+  segments: readonly StackedSegment[];
+}
+type StackedDatum = {
+  x: string;
+  y: number;
+};
+/**
+ * Pivot row-oriented `{ label, segments[] }` data into the column-oriented
+ * `BarChartSeries[]` + `x`/`y` accessors that `BarChart` consumes. Spread the
+ * result straight into the component:
+ *
+ * ```tsx
+ * <BarChart mode="stacked" {...toStackedSeries(rows)} title="…" />
+ * ```
+ *
+ * - Layer keys are collected in first-seen order across all rows (stable column order).
+ * - A key missing from a row contributes 0 so stacks stay aligned.
+ * - Each layer's color is the first non-undefined color seen for that key.
+ *
+ * Pure and dependency-free.
+ */
+declare function toStackedSeries(rows: readonly StackedRow[]): {
+  series: BarChartSeries<StackedDatum>[];
+  x: (d: StackedDatum) => string;
+  y: (d: StackedDatum) => 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. */
@@ -85,26 +205,6 @@ interface TreemapRect {
  * 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;
@@ -117,6 +217,8 @@ interface ChartFrameProps {
   }) => ReactNode;
   className?: string | undefined;
   'data-state'?: string | undefined;
+  /** Visible placeholder text shown when data-state is "empty". Defaults to the i18n built-in. */
+  emptyLabel?: string | undefined;
   plain?: boolean | undefined;
   /**
    * Tooltip model. Pass a TooltipModel directly, or a factory function that
@@ -136,6 +238,7 @@ declare function ChartFrame({
   children,
   className,
   'data-state': dataState,
+  emptyLabel,
   plain,
   tooltip
 }: ChartFrameProps): import("react").JSX.Element;
@@ -168,6 +271,8 @@ interface AxisProps {
   length: number;
   format?: (value: number | string | Date) => string;
   tickCount?: number;
+  /** For band scales: render every Nth category label (and always the last) to avoid crowding. */
+  labelEvery?: number | undefined;
   transform?: string;
 }
 declare function Axis({
@@ -176,6 +281,7 @@ declare function Axis({
   length,
   format,
   tickCount,
+  labelEvery,
   transform
 }: AxisProps): import("react").JSX.Element;
 interface GridLinesProps {
@@ -299,57 +405,11 @@ declare function AreaChart<Datum = {
   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;
+  /** CSS color overriding the positional palette for this slice. */
   color?: string;
 }
 interface PieChartProps {
@@ -359,6 +419,22 @@ interface PieChartProps {
   donut?: boolean;
   width?: number;
   height?: number;
+  /** Square shorthand: sets width === height. Explicit width/height win. */
+  size?: number;
+  /** Donut ring width in px. Defaults to 0.4 × radius (innerRadius = 0.6 × radius). */
+  thickness?: number;
+  /** Donut inner radius in px. Takes precedence over `thickness`. Clamped to [0, outerRadius). */
+  innerRadius?: number;
+  /** Center value text rendered in the donut hole (donut only). */
+  centerValue?: string;
+  /** Center label text rendered below the value in the donut hole (donut only). */
+  centerLabel?: string;
+  /** Arbitrary content rendered in the donut hole; takes precedence over centerValue/centerLabel. */
+  centerSlot?: ReactNode;
+  /** Visible placeholder text when data is empty. Defaults to the i18n built-in ("No data"). */
+  emptyLabel?: string;
+  /** Custom tooltip formatter. Defaults to "value (pct%)". Receives ChartPoint.percent. */
+  tooltipFormat?: (p: ChartPoint) => string;
   legend?: boolean;
   className?: string;
   /** Render only the marks — no legend. For micro/inline charts. */
@@ -371,6 +447,14 @@ declare function PieChart({
   donut,
   width: fixedWidth,
   height,
+  size,
+  thickness,
+  innerRadius,
+  centerValue,
+  centerLabel,
+  centerSlot,
+  emptyLabel,
+  tooltipFormat,
   legend,
   className,
   plain
@@ -681,4 +765,4 @@ declare function Bullet({
   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 };
+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, StackedRow, StackedSegment, TimeScale, Treemap, TreemapDatum, TreemapNode, TreemapProps, TreemapRect, arcPath, areaPath, bandScale, binValues, boxStats, extent, linePath, linearScale, logScale, nearestIndex, niceTicks, sqrtScale, squarify, stackSeries, timeScale, toStackedSeries, useChartSize };