katucharts.js 0.2.21 → 0.2.22

package/dist/layout/LayoutEngine.d.ts

@@ -22,6 +22,12 @@ export interface LayoutResult {
         width: number;
         height: number;
     };
+    captionArea: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
 }
 export declare class LayoutEngine {
     compute(config: InternalConfig, chartWidth: number, chartHeight: number): LayoutResult;

package/dist/series/BaseSeries.d.ts

@@ -20,7 +20,12 @@ export interface SeriesContext {
     totalSeriesOfType?: number;
     indexInType?: number;
     animate?: boolean;
+    /** Positive-side running stack offset, also aliased as the plain offset for all-positive consumers (area/radar). */
     stackOffsets?: Map<number | string, number>;
+    /** Running same-sign stack offset for this series, split so diverging stacks (e.g. pyramids) fill opposite sides of zero. */
+    stackOffsetsPos?: Map<number | string, number>;
+    stackOffsetsNeg?: Map<number | string, number>;
+    /** Absolute stack height per category (positive sum + |negative sum|), used as the percent-stacking denominator. */
     stackTotals?: Map<number | string, number>;
     allSeries?: BaseSeries[];
     inverted?: boolean;
@@ -179,7 +184,10 @@ export declare abstract class BaseSeries {
     /**
      * Render data labels for all visible points based on dataLabels config.
      */
-    protected renderDataLabels(data: PointOptions[], getX: (d: PointOptions, i: number) => number, getY: (d: PointOptions, i: number) => number): void;
+    protected renderDataLabels(data: PointOptions[], getX: (d: PointOptions, i: number) => number, getY: (d: PointOptions, i: number) => number, getPlacement?: (d: PointOptions, i: number, textWidth: number) => {
+        x: number;
+        anchor: 'start' | 'middle' | 'end';
+    } | null, defaultDy?: number): void;
     /**
      * Handle point selection toggle when allowPointSelect is enabled.
      */

package/dist/series/cartesian/ColumnChart.d.ts

@@ -5,11 +5,11 @@
  */
 import 'd3-transition';
 import { BaseSeries } from '../BaseSeries';
-import type { InternalSeriesConfig } from '../../types/options';
+import type { InternalSeriesConfig, PointOptions } from '../../types/options';
 export declare class ColumnChart extends BaseSeries {
     protected isHorizontal: boolean;
     constructor(config: InternalSeriesConfig);
-    private getEntryDuration;
+    protected getEntryDuration(): number;
     render(): void;
     private renderVerticalBars;
     private renderHorizontalBars;
@@ -28,9 +28,9 @@ export declare class ColumnChart extends BaseSeries {
         baseline: number;
         groupWidth: number;
     };
-    private getPointColor;
-    private renderColumnDataLabels;
-    private attachHoverEffects;
+    protected getPointColor(d: PointOptions, i: number, seriesColor: string, negativeColor?: string, threshold?: number): string;
+    protected renderColumnDataLabels(data: PointOptions[], barWidth: number, barOffset: number, baseline: number, getStackedY?: (d: PointOptions) => number, getStackedBase?: (d: PointOptions) => number): void;
+    protected attachHoverEffects(bars: any, data: PointOptions[]): void;
 }
 export declare class BarChart extends ColumnChart {
     protected isHorizontal: boolean;

package/dist/series/financial/AreaRangeChart.d.ts

@@ -6,6 +6,20 @@ export declare class AreaRangeChart extends BaseSeries {
     /** Curve used for the band edges. Overridden by areasplinerange for smoothing. */
     protected getCurve(): CurveFactory;
     render(): void;
+    /**
+     * Picks a solid representative color from a gradient `color` (the first fully
+     * opaque stop, else the middle stop) so line/markers match the band instead
+     * of falling back to an unrelated palette color. Returns null for non-gradients.
+     */
+    private gradientBaseColor;
+    private hoverHandlers?;
+    /**
+     * Shows diamond markers at the band's high and low for the hovered category,
+     * so a shared-tooltip hover highlights the range extremes (the line series
+     * draws its own marker). Driven by the `point:mouseover` event the hovered
+     * series emits, matched by x so it works in shared mode.
+     */
+    private setupHoverMarkers;
     /**
      * Computes extents using low/high values for the y-axis range.
      */

package/dist/series/hierarchical/TreegraphChart.d.ts

@@ -19,6 +19,13 @@ export declare function normalizeTreegraphRows(data: TreegraphNodeDatum[]): Tree
 export declare class TreegraphChart extends BaseSeries {
     constructor(config: InternalSeriesConfig);
     render(): void;
+    /**
+     * Assigns a color to each node top-down following the level options: explicit
+     * per-point or per-level color, `colorByPoint` cycling the palette across a
+     * level, or `colorVariation` brightening the inherited parent color across
+     * siblings. Result is stored as `__color` on each node.
+     */
+    private assignColors;
     private buildRoot;
     getDataExtents(): {
         xMin: number;

package/dist/series/pictorial/PictorialChart.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pictorial series — a stacked column whose fill is masked to a custom SVG
+ * silhouette. Each category supplies one or more path definitions; the stacked
+ * segments fill the silhouette from the baseline upward, so the shape reads as a
+ * proportional gauge. Works with `stacking: 'percent'` (fill by share of total)
+ * or `stacking: 'normal'` (fill by value against the axis range).
+ */
+import 'd3-transition';
+import { ColumnChart } from '../cartesian/ColumnChart';
+export declare class PictorialChart extends ColumnChart {
+    render(): void;
+    /**
+     * Draws the value labels centered within each stacked segment so they read on
+     * top of the filled silhouette instead of piling up at the segment edges.
+     */
+    private renderPictorialLabels;
+    animateUpdate(): void;
+    private getPaths;
+    /** The value the silhouette's top edge maps to (100 for percent stacks, else the axis max). */
+    private getAxisTopValue;
+    /**
+     * Places a silhouette inside the column slot preserving its aspect ratio. The
+     * path is scaled to fill the full value-axis band height — so a vertical gauge
+     * uses all the available height with no top/bottom gap — and centered
+     * horizontally within the slot. The natural width that results is not clipped
+     * (pictorial opts out of the plot clip), so the shape keeps its proportions.
+     * The returned value→pixel mapper is anchored to the band, so a stacked share
+     * of X% fills X% of the shape's height.
+     */
+    private computeSilhouette;
+    private shadowFill;
+}

package/dist/series/pie/PieChart.d.ts

@@ -35,7 +35,36 @@ export declare class PieChart extends BaseSeries {
     private dataLabelConfigs;
     init(context: SeriesContext): void;
     render(): void;
+    /**
+     * The colour of slice `index`: an explicit per-point colour wins, then the
+     * series palette, then the chart palette — matching the slice fill so labels,
+     * connectors and measurement all agree.
+     */
+    private resolveSliceColor;
+    /**
+     * Resolves a point's label to its rendered text (formatter/format/fallback,
+     * HTML stripped) plus any inline `color:` declared in the markup. Shared by the
+     * sizing pre-pass and the renderer so the measured width can't drift from what
+     * is actually drawn.
+     */
+    private resolveLabelText;
+    /**
+     * Plot space to reserve for external labels, measured from real text widths.
+     * Horizontal: the widest `distance + textWidth + connectorPadding` over each
+     * side, capped at a third of the plot width per side so a single long label
+     * can't shrink the pie to nothing. Vertical: the radial `distance + 10`, since
+     * side labels stack vertically and don't consume horizontal text room.
+     */
+    private measureLabelMargins;
     private renderPieLabels;
+    /**
+     * Renders a pie label on one line, or word-wraps it onto multiple lines when
+     * it exceeds the horizontal space before the plot edge — so long category
+     * names break instead of being ellipsis-truncated. Lines are vertically
+     * centered on the anchor; an over-long run is capped at three lines and the
+     * last is ellipsized.
+     */
+    private wrapLabelLines;
     /**
      * Rank-based label distribution. Packs the side's labels into the available
      * vertical span using rank-based priority (higher percentage = higher rank)
@@ -45,6 +74,8 @@ export declare class PieChart extends BaseSeries {
      * regions instead of fanning every label out on a long leader line.
      */
     private distribute;
+    /** Estimated wrapped line count for a label (1-3), from its width vs available space. */
+    private estimateLabelLines;
     private distributeBoxes;
     /**
      * Renders pseudo-3D side effect below pie slices using the depth config.

package/dist/types/options.d.ts

@@ -1,7 +1,7 @@
 /**
  * Option types for KatuCharts.
  */
-export type SeriesType = 'line' | 'spline' | 'area' | 'areaspline' | 'arearange' | 'column' | 'bar' | 'barchartrace' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'heatmap' | 'treemap' | 'sunburst' | 'treegraph' | 'wordcloud' | 'sankey' | 'dependencywheel' | 'networkgraph' | 'gauge' | 'solidgauge' | 'polar' | 'radar' | 'candlestick' | 'ohlc' | 'heikinashi' | 'hollowcandlestick' | 'volume' | 'arearange' | 'baseline' | 'flags' | 'renko' | 'kagi' | 'pointandfigure' | 'linebreak' | 'waterfall' | 'boxplot' | 'funnel' | 'pyramid' | 'timeline' | 'gantt' | 'map' | 'mappoint' | 'flowmap' | 'venn' | 'volcano' | 'manhattan' | 'violin' | 'kaplanmeier' | 'forestplot' | 'sequencelogo' | 'clusteredheatmap' | 'phylotree' | 'circos' | 'circosHeatmap' | 'circosComparative' | 'circosSpiral' | 'item' | 'classroom' | 'pcoa';
+export type SeriesType = 'line' | 'spline' | 'area' | 'areaspline' | 'arearange' | 'column' | 'bar' | 'barchartrace' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'heatmap' | 'treemap' | 'sunburst' | 'treegraph' | 'wordcloud' | 'sankey' | 'dependencywheel' | 'networkgraph' | 'gauge' | 'solidgauge' | 'polar' | 'radar' | 'candlestick' | 'ohlc' | 'heikinashi' | 'hollowcandlestick' | 'volume' | 'arearange' | 'baseline' | 'flags' | 'renko' | 'kagi' | 'pointandfigure' | 'linebreak' | 'waterfall' | 'boxplot' | 'pictorial' | 'funnel' | 'pyramid' | 'timeline' | 'gantt' | 'map' | 'mappoint' | 'flowmap' | 'venn' | 'volcano' | 'manhattan' | 'violin' | 'kaplanmeier' | 'forestplot' | 'sequencelogo' | 'clusteredheatmap' | 'phylotree' | 'circos' | 'circosHeatmap' | 'circosComparative' | 'circosSpiral' | 'item' | 'classroom' | 'pcoa';
 export type CursorType = 'pointer' | 'default' | 'crosshair' | 'move' | 'help' | 'text' | 'not-allowed';
 export type DashStyleType = 'Solid' | 'ShortDash' | 'ShortDot' | 'ShortDashDot' | 'ShortDashDotDot' | 'Dot' | 'Dash' | 'LongDash' | 'DashDot' | 'LongDashDot' | 'LongDashDotDot';
 export type AlignType = 'left' | 'center' | 'right';
@@ -113,6 +113,9 @@ export interface TitleOptions {
 }
 export interface SubtitleOptions extends TitleOptions {
 }
+/** Source/footnote text rendered in a band at the bottom of the chart. */
+export interface CaptionOptions extends TitleOptions {
+}
 export interface AxisLabelOptions {
     enabled?: boolean;
     format?: string;
@@ -644,6 +647,10 @@ export interface SeriesOptions {
     borderWidth?: number;
     borderColor?: string;
     borderRadius?: number | BorderRadiusOptions;
+    /** Silhouette path definitions for the pictorial series, indexed (and cycled) by point. */
+    paths?: {
+        definition: string;
+    }[];
     colorByPoint?: boolean;
     colors?: string[];
     innerSize?: string | number;
@@ -1272,6 +1279,7 @@ export interface KatuChartsOptions {
     chart?: ChartOptions;
     title?: TitleOptions;
     subtitle?: SubtitleOptions;
+    caption?: CaptionOptions;
     xAxis?: AxisOptions | AxisOptions[];
     yAxis?: AxisOptions | AxisOptions[];
     colorAxis?: ColorAxisOptions | ColorAxisOptions[];
@@ -1331,6 +1339,7 @@ export interface InternalConfig {
     chart: Required<Pick<ChartOptions, 'width' | 'height' | 'backgroundColor' | 'animation' | 'reflow'>> & ChartOptions;
     title: TitleOptions;
     subtitle: SubtitleOptions;
+    caption?: CaptionOptions;
     xAxis: InternalAxisConfig[];
     yAxis: InternalAxisConfig[];
     colorAxis: ColorAxisOptions[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "katucharts.js",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "description": "D3.js charting library with a simple declarative interface",
   "type": "module",
   "main": "./dist/katucharts.umd.js",