@pushwoosh/kit-charts 0.0.3 → 0.0.4

package/ai-documentation.md

@@ -62,7 +62,8 @@ Deliberate differences from Highcharts:
    `ChartOptions<TChartMeta, TSeriesMeta, TPointMeta>`.
 2. Formatters take a typed context **argument**; there is no `this`.
 3. Formatters return a `ReactNode`, never an HTML string. There is no `useHTML`.
-4. `TooltipPoint` exposes `prev` and `next` neighbours directly.
+4. `TooltipPoint` exposes `prev` and `next` neighbours directly, and carries the
+   point's own `meta` as `pointMeta` beside the series' `meta`.
 5. Formatters see `ctx.chart.title` and `ctx.chart.meta`, not the option tree.
 6. No `credits` option.
 7. No `reflow`; resize is observed automatically.
@@ -338,6 +339,14 @@ the value wrapped in `valuePrefix`/`valueSuffix`. `formatter` replaces the body
 returns a `ReactNode`; `ctx.points[].prev`/`.next` carry the neighbouring points, so
 a delta needs no extra lookup. `shared: true` collects every series at the hovered x.
 
+`ctx.points[].pointMeta` is the hovered point's own `meta` — the third type
+parameter of `ChartOptions<TChartMeta, TSeriesMeta, TPointMeta>`, the same object
+`onPointClick` reports. `meta` beside it stays the series'. A bar whose height is a
+rate and whose tooltip has to name the two counts behind it needs the per-point
+one; nothing else reaches it, because a formatter sees no option tree.
+
+Golden case: `tooltip/point-meta`.
+
 Golden cases: `tooltip/callout`, `tooltip/shared-formatter`.
 
 ## Styling
@@ -362,6 +371,18 @@ A data label whose text carries `\n` is drawn as stacked lines, styled by
 `style` for the first and `secondaryStyle` for the rest. It is one label: it
 moves, measures and hides as one.
 
+## Areas
+
+`fillColor` paints the body under the line, where the fill is a token of its own
+rather than a wash of the series colour — `color` still keys the legend, the
+markers and the tooltip swatch. Left unset the body is the series colour at
+`fillOpacity`. Golden case: `area/fill-color`.
+
+Both live on `SeriesOptionsBase`, as every series option does, but a renderer
+reads only what it draws with: `fillColor` is read by `area` alone, `fillOpacity`
+by `area` and `column`. On a pie or a heatmap they are typed and inert — the same
+deal as `innerSize` on a line.
+
 ## The device pixel grid
 
 `useSize` floors the measured box, so the canvas is always a whole number of

package/core/Chart/Chart.d.ts

@@ -12,8 +12,8 @@ export interface ClickedPoint<TPointMeta = unknown> {
     color: string;
     meta: TPointMeta;
 }
-export interface ChartProps<TChartMeta = unknown, TSeriesMeta = unknown> {
-    options: ChartOptions<TChartMeta, TSeriesMeta>;
+export interface ChartProps<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown> {
+    options: ChartOptions<TChartMeta, TSeriesMeta, TPointMeta>;
     renderers?: readonly AnySeriesRenderer[];
     isLoading?: boolean;
     empty?: ReactNode;
@@ -28,6 +28,6 @@ export interface ChartProps<TChartMeta = unknown, TSeriesMeta = unknown> {
      */
     onSeriesToggle?: (seriesIndex: number, visible: boolean, pointIndex?: number) => void;
     /** Called with the point nearest a click inside the plot; drill-down hangs off this. */
-    onPointClick?: (point: ClickedPoint, event: ReactMouseEvent<SVGSVGElement>) => void;
+    onPointClick?: (point: ClickedPoint<TPointMeta>, event: ReactMouseEvent<SVGSVGElement>) => void;
 }
-export declare function Chart<TChartMeta = unknown, TSeriesMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta>): ReactElement;
+export declare function Chart<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta, TPointMeta>): ReactElement;

package/core/Chart/Chart.js

@@ -409,6 +409,7 @@ function ChartBody({
         value: hit.value,
         index: hit.pointIndex,
         meta: series?.options.meta,
+        pointMeta: neighbours[hit.pointIndex]?.meta,
         prev: previous ? {
           x: previous.x,
           y: previous.y,

package/core/types/formatter.d.ts

@@ -35,7 +35,7 @@ export interface TooltipNeighbour {
     y: number | null;
     index: number;
 }
-export interface TooltipPoint<TSeriesMeta = unknown> {
+export interface TooltipPoint<TSeriesMeta = unknown, TPointMeta = unknown> {
     seriesIndex: number;
     seriesName: string;
     color: string;
@@ -44,16 +44,18 @@ export interface TooltipPoint<TSeriesMeta = unknown> {
     value: number | null;
     index: number;
     meta: TSeriesMeta | undefined;
+    /** The hovered point's own `meta` — what `onPointClick` reports, at hover time. */
+    pointMeta: TPointMeta | undefined;
     prev: TooltipNeighbour | undefined;
     next: TooltipNeighbour | undefined;
 }
-export interface TooltipContext<TChartMeta = unknown, TSeriesMeta = unknown> {
+export interface TooltipContext<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown> {
     x: number | string;
-    points: readonly TooltipPoint<TSeriesMeta>[];
+    points: readonly TooltipPoint<TSeriesMeta, TPointMeta>[];
     chart: {
         title: string | undefined;
         meta: TChartMeta | undefined;
     };
 }
-export type TooltipFormatter<TChartMeta = unknown, TSeriesMeta = unknown> = (ctx: TooltipContext<TChartMeta, TSeriesMeta>) => ReactNode;
-export type TooltipCellFormatter<TSeriesMeta = unknown> = (point: TooltipPoint<TSeriesMeta>) => ReactNode;
+export type TooltipFormatter<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown> = (ctx: TooltipContext<TChartMeta, TSeriesMeta, TPointMeta>) => ReactNode;
+export type TooltipCellFormatter<TSeriesMeta = unknown, TPointMeta = unknown> = (point: TooltipPoint<TSeriesMeta, TPointMeta>) => ReactNode;

package/core/types/options.d.ts

@@ -175,36 +175,36 @@ export interface LegendOptions<TSeriesMeta = unknown> {
     symbolPadding?: number;
     labelFormatter?: LegendLabelFormatter<TSeriesMeta>;
 }
-export interface TooltipTableColumn<TChartMeta = unknown, TSeriesMeta = unknown> {
+export interface TooltipTableColumn<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown> {
     /**
      * A function is resolved per hover, and one that returns `null` drops the whole
      * column: that is how a "vs the previous point" column names the date it
      * compares against and disappears on the first point, where there is none.
      */
-    title?: string | TooltipFormatter<TChartMeta, TSeriesMeta>;
+    title?: string | TooltipFormatter<TChartMeta, TSeriesMeta, TPointMeta>;
     align?: 'left' | 'right';
-    cell: TooltipCellFormatter<TSeriesMeta>;
+    cell: TooltipCellFormatter<TSeriesMeta, TPointMeta>;
 }
 /**
  * Lays the tooltip out as a table: a header line, a heading row, and one row per
  * series with its swatch. Use it when a point carries more than one figure —
  * a count and its share of the whole — and a single line would run them together.
  */
-export interface TooltipTableOptions<TChartMeta = unknown, TSeriesMeta = unknown> {
+export interface TooltipTableOptions<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown> {
     /** The line above the table. Defaults to the formatted x. */
-    header?: TooltipFormatter<TChartMeta, TSeriesMeta>;
+    header?: TooltipFormatter<TChartMeta, TSeriesMeta, TPointMeta>;
     /** Heading over the series-name column. */
     seriesTitle?: string;
-    columns: readonly TooltipTableColumn<TChartMeta, TSeriesMeta>[];
+    columns: readonly TooltipTableColumn<TChartMeta, TSeriesMeta, TPointMeta>[];
 }
-export interface TooltipOptions<TChartMeta = unknown, TSeriesMeta = unknown> {
+export interface TooltipOptions<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown> {
     enabled?: boolean;
     shared?: boolean;
-    table?: TooltipTableOptions<TChartMeta, TSeriesMeta>;
+    table?: TooltipTableOptions<TChartMeta, TSeriesMeta, TPointMeta>;
     /** `callout` anchors a beaked bubble to the point; `box` floats near the cursor. */
     shape?: 'callout' | 'box';
     followPointer?: boolean;
-    formatter?: TooltipFormatter<TChartMeta, TSeriesMeta>;
+    formatter?: TooltipFormatter<TChartMeta, TSeriesMeta, TPointMeta>;
     dateFormat?: string;
     valuePrefix?: string;
     valueSuffix?: string;
@@ -298,6 +298,8 @@ export interface SeriesOptionsBase<TSeriesMeta = unknown, TPointMeta = unknown>
      */
     borderPosition?: 'all' | 'top';
     fillOpacity?: number;
+    /** The body's own colour, where the fill is not a wash of the series colour. */
+    fillColor?: string;
     pointPadding?: number;
     groupPadding?: number;
     minPointLength?: number;
@@ -321,7 +323,7 @@ export interface ChartOptions<TChartMeta = unknown, TSeriesMeta = unknown, TPoin
     yAxis?: AxisOptions | readonly AxisOptions[];
     colorAxis?: ColorAxisOptions;
     legend?: LegendOptions<TSeriesMeta>;
-    tooltip?: TooltipOptions<TChartMeta, TSeriesMeta>;
+    tooltip?: TooltipOptions<TChartMeta, TSeriesMeta, TPointMeta>;
     plotOptions?: PlotOptions<TSeriesMeta, TPointMeta>;
     series?: readonly SeriesOptionsBase<TSeriesMeta, TPointMeta>[];
     colors?: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/kit-charts",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Small React chart library on SVG, with a Highcharts-shaped configuration model",
   "license": "MIT",
   "repository": {

package/presets/AreaChart.d.ts

@@ -1,3 +1,3 @@
 import { type ReactElement } from 'react';
 import { type ChartProps } from '../core/Chart/Chart';
-export declare function AreaChart<TChartMeta = unknown, TSeriesMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta>): ReactElement;
+export declare function AreaChart<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta, TPointMeta>): ReactElement;

package/presets/ColumnChart.d.ts

@@ -1,3 +1,3 @@
 import { type ReactElement } from 'react';
 import { type ChartProps } from '../core/Chart/Chart';
-export declare function ColumnChart<TChartMeta = unknown, TSeriesMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta>): ReactElement;
+export declare function ColumnChart<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta, TPointMeta>): ReactElement;

package/presets/LineChart.d.ts

@@ -1,3 +1,3 @@
 import { type ReactElement } from 'react';
 import { type ChartProps } from '../core/Chart/Chart';
-export declare function LineChart<TChartMeta = unknown, TSeriesMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta>): ReactElement;
+export declare function LineChart<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta, TPointMeta>): ReactElement;

package/presets/PieChart.d.ts

@@ -1,3 +1,3 @@
 import { type ReactElement } from 'react';
 import { type ChartProps } from '../core/Chart/Chart';
-export declare function PieChart<TChartMeta = unknown, TSeriesMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta>): ReactElement;
+export declare function PieChart<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta, TPointMeta>): ReactElement;

package/presets/StackedColumnChart.d.ts

@@ -1,7 +1,7 @@
 import { type ReactElement } from 'react';
 import { type ChartProps } from '../core/Chart/Chart';
 import { type Stacking } from '../core/types/options';
-export interface StackedColumnChartProps<TChartMeta = unknown, TSeriesMeta = unknown> extends ChartProps<TChartMeta, TSeriesMeta> {
+export interface StackedColumnChartProps<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown> extends ChartProps<TChartMeta, TSeriesMeta, TPointMeta> {
     stacking?: Stacking;
 }
-export declare function StackedColumnChart<TChartMeta = unknown, TSeriesMeta = unknown>(props: StackedColumnChartProps<TChartMeta, TSeriesMeta>): ReactElement;
+export declare function StackedColumnChart<TChartMeta = unknown, TSeriesMeta = unknown, TPointMeta = unknown>(props: StackedColumnChartProps<TChartMeta, TSeriesMeta, TPointMeta>): ReactElement;

package/series/area/area.js

@@ -27,7 +27,7 @@ export const area = {
     return _jsxs("g", {
       children: [_jsx("path", {
         d: toAreaPath(slots),
-        fill: color,
+        fill: ctx.series.fillColor ?? color,
         fillOpacity: ctx.series.fillOpacity ?? DEFAULT_FILL_OPACITY,
         stroke: "none"
       }), lineWidth ? _jsx("path", {