minerva-design 1.3.0 → 1.4.0

package/dist/charts/react/shapes.d.ts

@@ -1,16 +1,20 @@
 import { CSSProperties, ReactNode, Ref } from 'react';
 import { ChartPadding } from '../engine/types.js';
-import { GaugeBand, RadarIndicator, RadarSeries, ShapeChartInstance, ShapeDatum, ShapeHoverEvent, ShapeLegendOptions, ShapeToggleEvent, ShapeTooltipOptions, TreemapNode } from '../engine/shapes/types.js';
+import { BulletDatum, CalendarDate, CalendarDatum, GaugeBand, RadarIndicator, RadarSeries, RadialBarDatum, SankeyLink, SankeyNode, ShapeChartInstance, ShapeChartLabels, ShapeDatum, ShapeDrillEvent, ShapeHoverEvent, ShapeLegendOptions, ShapeToggleEvent, ShapeTooltipOptions, TreemapNode } from '../engine/shapes/types.js';
 /** Imperative handle of the shape chart components (`ref`) */
 export interface ShapeChartHandle {
     /** The underlying engine instance (minerva-design/charts/core) */
     getInstance(): ShapeChartInstance | null;
 }
-/** Props shared by PieChart, DonutChart, RadarChart, GaugeChart, FunnelChart and TreemapChart */
+/**
+ * Props shared by PieChart, DonutChart, RadarChart, GaugeChart, FunnelChart,
+ * TreemapChart, SankeyChart, SunburstChart, RadialBarChart, CalendarHeatmap
+ * and BulletChart
+ */
 export interface ShapeChartCommonProps {
     /**
      * Height of the chart (the legend included); numbers are pixels
-     * @default 320 (GaugeChart: 240)
+     * @default 320 (GaugeChart: 240, RadialBarChart: 300, CalendarHeatmap and BulletChart: from the data)
      */
     height?: number | string;
     /**
@@ -21,8 +25,8 @@ export interface ShapeChartCommonProps {
     /** Colors of the marks without `color` (defaults to the `--chart-series-1..8` CSS variables, then the theme colors) */
     palette?: readonly string[];
     /**
-     * Legend; clicking an item hides / shows its slice, stage or series
-     * @default shown for pie, donut, funnel and multi-series radar charts
+     * Legend; clicking an item hides / shows its slice, stage, series, node, bar, row or level
+     * @default shown for pie, donut, funnel, multi-series radar charts, calendar heatmaps and radial bar charts without labels
      */
     legend?: boolean | ShapeLegendOptions;
     /**
@@ -32,16 +36,26 @@ export interface ShapeChartCommonProps {
     tooltip?: boolean | ShapeTooltipOptions;
     /**
      * Formats the values of the labels and the tooltip
-     * @default compact numbers (1.2k, 3.4M)
+     * @default compact numbers of the `locale` (1.2k, 3.4M; 1.2万 in Chinese and Japanese)
      */
     format?: (value: number) => string;
     /**
      * Formats the shares (labels, conversion rates, tooltip); `share` is 0-1
-     * @default one decimal, e.g. "40.0%"
+     * @default a percent of the `locale` with one decimal, e.g. "40.0%", "40,0 %"
      */
     percentFormat?: (share: number) => string;
     /**
-     * Hidden slices / stages / radar series / top-level treemap nodes, by
+     * BCP 47 locale of the texts and numbers the chart writes (tooltip rows,
+     * accessible names, number and percent formats, calendar dates); built-in
+     * texts in English, Chinese, Japanese and French (English otherwise)
+     * @default the page language (`<html lang>`, followed when it changes), else the browser language
+     */
+    locale?: string;
+    /** Replaces built-in texts of the `locale` (tooltip rows, accessible names, "No data") */
+    texts?: Partial<ShapeChartLabels>;
+    /**
+     * Hidden slices / stages / radar series / top-level treemap or sunburst
+     * nodes / sankey nodes / radial bars / bullet rows / calendar levels, by
      * index. Makes the visibility controlled: legend clicks then only call
      * `onToggle`, whose `hiddenIndexes` should be stored and passed back.
      * Leave undefined to let the legend hide / show entries by itself.
@@ -64,7 +78,7 @@ export interface ShapeChartCommonProps {
     padding?: ChartPadding;
     /**
      * Accessible name of the chart
-     * @default the chart type, e.g. "Donut chart"
+     * @default the chart type in the `locale`, e.g. "Donut chart"
      */
     ariaLabel?: string;
     /** Called when the hovered (or keyboard-focused) mark changes */
@@ -238,6 +252,258 @@ export interface TreemapChartProps extends ShapeChartCommonProps {
      */
     headers?: boolean;
 }
+/** Props of SankeyChart */
+export interface SankeyChartProps extends ShapeChartCommonProps {
+    /** Nodes, in their initial order; nodes only named by a link are appended */
+    nodes?: readonly SankeyNode[];
+    /** Flows between the nodes (by name or index); links closing a cycle are ignored */
+    links: readonly SankeyLink[];
+    /**
+     * Width of the node bars, in pixels
+     * @default 12
+     */
+    nodeWidth?: number;
+    /**
+     * Vertical gap between the nodes of a column, in pixels (reduced when space is short)
+     * @default 12
+     */
+    nodePadding?: number;
+    /**
+     * Column of the nodes without a `column`: `justify` puts the sinks in the
+     * last column, `left` / `right` align on the sources / sinks, `center`
+     * puts the sources next to their first target
+     * @default "justify"
+     */
+    align?: "justify" | "left" | "right" | "center";
+    /**
+     * Relaxation passes that straighten the flows and reduce crossings
+     * @default 32
+     */
+    iterations?: number;
+    /**
+     * Color of the links without `color`: a gradient from the source to the
+     * target color, one of the two, or a neutral gray
+     * @default "gradient"
+     */
+    linkColor?: "gradient" | "source" | "target" | "neutral";
+    /**
+     * Opacity of the links, 0-1 (hovered flows are more opaque)
+     * @default 0.4
+     */
+    linkOpacity?: number;
+    /**
+     * Node labels (name and value); overlapping labels are skipped
+     * @default true
+     */
+    labels?: boolean;
+    /**
+     * Shows the value after the name in the labels
+     * @default true
+     */
+    labelValues?: boolean;
+}
+/** Props of SunburstChart */
+export interface SunburstChartProps extends ShapeChartCommonProps {
+    /** Nodes: leaves carry a value, parents sum their children */
+    data: readonly TreemapNode[];
+    /**
+     * Radius of the center circle as a fraction of the outer radius
+     * @default 0.26
+     */
+    innerRadius?: number;
+    /**
+     * Rings shown at once below the focused node (fewer when they would be thinner than 18 px)
+     * @default every level
+     */
+    levels?: number;
+    /**
+     * Angle of the first node, degrees clockwise from 12 o'clock
+     * @default 0
+     */
+    startAngle?: number;
+    /**
+     * Gap between the sectors, in pixels
+     * @default 1
+     */
+    padAngle?: number;
+    /**
+     * Corner radius of the sectors, in pixels
+     * @default 2
+     */
+    cornerRadius?: number;
+    /**
+     * Sector labels: `auto` writes each name along the arc or along the
+     * radius, whichever fits best; labels that do not fit are shortened or skipped
+     * @default "auto"
+     */
+    labels?: "auto" | "tangential" | "radial" | "none";
+    /**
+     * Clicking (or Enter on) a parent zooms into it; clicking the center (or Backspace) goes back up
+     * @default true
+     */
+    drill?: boolean;
+    /**
+     * Names from the root to the focused node (`[]` = the root). Makes the
+     * drill-down controlled: clicks then only call `onDrill`, whose `path`
+     * should be stored and passed back.
+     */
+    drillPath?: readonly string[];
+    /** Called when a parent or the center is clicked (or the instance's `drill()` is called) */
+    onDrill?: (event: ShapeDrillEvent) => void;
+}
+/** Props of RadialBarChart */
+export interface RadialBarChartProps extends ShapeChartCommonProps {
+    /** Bars, from the outermost ring inward: a name, a value, an optional `max` and color */
+    data: readonly RadialBarDatum[];
+    /**
+     * Value of a full bar for the data without `max`
+     * @default the largest value
+     */
+    max?: number;
+    /**
+     * Radius of the innermost ring's inner edge, as a fraction of the outer radius
+     * @default 0.3
+     */
+    innerRadius?: number;
+    /**
+     * Angle where the bars start, degrees clockwise from 12 o'clock
+     * @default 0
+     */
+    startAngle?: number;
+    /**
+     * Angle of a full bar, degrees (360 = full rings)
+     * @default 270
+     */
+    sweep?: number;
+    /**
+     * Gap between the rings, as a fraction of a ring's slot (0-0.9)
+     * @default 0.28
+     */
+    gap?: number;
+    /**
+     * Background tracks behind the bars
+     * @default true
+     */
+    track?: boolean;
+    /**
+     * Rounded bar ends
+     * @default true
+     */
+    rounded?: boolean;
+    /**
+     * Labels before the start of the bars (in the empty part of the circle)
+     * @default true when `sweep` leaves room for them (up to 300°)
+     */
+    labels?: boolean;
+    /**
+     * What a label shows: name, value, percent of the bar's max (combinable)
+     * @default ["name", "value"]
+     */
+    labelContent?: readonly ("name" | "value" | "percent")[];
+    /** Big text in the center (e.g. the overall completion) */
+    centerValue?: string;
+    /** Small text under `centerValue` */
+    centerLabel?: string;
+}
+/** Props of CalendarHeatmap */
+export interface CalendarHeatmapProps extends ShapeChartCommonProps {
+    /** Daily values (several entries of the same day add up) */
+    data: readonly CalendarDatum[];
+    /**
+     * Days shown: a year (`2026`) or an inclusive `[start, end]` range
+     * @default the 53 weeks ending on the last day of the data
+     */
+    range?: number | readonly [CalendarDate, CalendarDate];
+    /**
+     * `weeks`: a column per week and a row per weekday (one strip per year
+     * when the range spans several years); `months`: a small calendar per month
+     * @default "weeks"
+     */
+    layout?: "weeks" | "months";
+    /**
+     * First day of the week, 0 = Sunday … 6 = Saturday
+     * @default from `locale`
+     */
+    weekStart?: number;
+    /**
+     * BCP 47 locale of the month and weekday names, of the tooltip dates, of the default `weekStart` and of the built-in texts
+     * @default the page language (`<html lang>`), else the browser language
+     */
+    locale?: string;
+    /**
+     * Color of the highest level (lower levels are lighter)
+     * @default the first palette color
+     */
+    color?: string;
+    /** Colors of the levels, lowest first (replaces `color` and sets the number of levels) */
+    colors?: readonly string[];
+    /**
+     * Number of color levels above the empty days
+     * @default 4
+     */
+    levels?: number;
+    /**
+     * Upper bounds of the levels but the last, ascending (`[2, 5, 10]`: 1-2,
+     * 3-5, 6-10, more); an even split of the largest value by default
+     */
+    thresholds?: readonly number[];
+    /**
+     * Gap between the cells, in pixels
+     * @default 3
+     */
+    gap?: number;
+    /**
+     * Corner radius of the cells, in pixels
+     * @default 2
+     */
+    radius?: number;
+    /**
+     * Largest cell size, in pixels (cells shrink to fit the width)
+     * @default 16 (weeks), 28 (months)
+     */
+    maxCellSize?: number;
+    /**
+     * Month names (and years) around the cells
+     * @default true
+     */
+    monthLabels?: boolean;
+    /**
+     * Weekday names beside (weeks) or above (months) the cells
+     * @default true
+     */
+    weekdayLabels?: boolean;
+}
+/** Props of BulletChart */
+export interface BulletChartProps extends ShapeChartCommonProps {
+    /** Rows (columns when vertical): name, value, target, ranges and scale */
+    data: readonly BulletDatum[];
+    /**
+     * Horizontal rows or vertical columns
+     * @default "horizontal"
+     */
+    orientation?: "horizontal" | "vertical";
+    /** Qualitative ranges of the rows without `ranges`: upper bounds, ascending */
+    ranges?: readonly number[];
+    /** Names of the qualitative ranges, lowest first (tooltip) */
+    rangeLabels?: readonly string[];
+    /** Colors of the qualitative ranges, lowest first; shades of gray by default */
+    rangeColors?: readonly string[];
+    /**
+     * Thickness of the value bar as a fraction of the ranges' thickness
+     * @default 0.4
+     */
+    barSize?: number;
+    /**
+     * Color of the target markers
+     * @default the text color
+     */
+    targetColor?: string;
+    /**
+     * Tick labels of the scales (when there is room)
+     * @default true
+     */
+    ticks?: boolean;
+}
 /**
  * Pie chart (or a donut with `innerRadius`, or a Nightingale rose with
  * `rose`): slices with gaps, outside labels with leader lines, legend toggles.
@@ -253,3 +519,19 @@ export declare function GaugeChart(props: GaugeChartProps): import('react').JSX.
 export declare function FunnelChart(props: FunnelChartProps): import('react').JSX.Element;
 /** Treemap: nested rectangles of areas proportional to the values */
 export declare function TreemapChart(props: TreemapChartProps): import('react').JSX.Element;
+/**
+ * Sankey diagram: flows between nodes in columns, link thickness
+ * proportional to the flow; hovering a node or a link highlights its flows
+ */
+export declare function SankeyChart(props: SankeyChartProps): import('react').JSX.Element;
+/**
+ * Sunburst chart: a hierarchy as concentric rings; clicking a parent zooms
+ * into it, clicking the center goes back up
+ */
+export declare function SunburstChart(props: SunburstChartProps): import('react').JSX.Element;
+/** Radial bar chart: concentric progress rings (activity rings, KPI completion) */
+export declare function RadialBarChart(props: RadialBarChartProps): import('react').JSX.Element;
+/** Calendar heatmap: daily values on a calendar, contributions-style */
+export declare function CalendarHeatmap(props: CalendarHeatmapProps): import('react').JSX.Element;
+/** Bullet chart: KPI bars against qualitative ranges and a target marker */
+export declare function BulletChart(props: BulletChartProps): import('react').JSX.Element;