minerva-design 1.3.0 → 1.5.0

package/dist/charts/engine/presets.d.cts

@@ -1,4 +1,16 @@
-import { ChartCurve, ChartOptions, ChartSeries, ChartSeriesType } from './types.cjs';
+import { ChartColorScheme, ChartConnectorOptions, ChartCurve, ChartOptions, ChartPointDatum, ChartSeries, ChartSeriesType, ChartXValue } from './types.cjs';
+/** Default series names of the presets */
+interface PresetLabels {
+    value: string;
+    values: string;
+    count: string;
+    change: string;
+    tasks: string;
+    progress: string;
+    milestones: string;
+}
+/** Default series names of the presets in a locale (the page language by default) */
+export declare const presetLabels: (locale?: string) => PresetLabels;
 /** Gives the series without a `type` the type of the component */
 export declare const withSeriesType: (series: readonly ChartSeries[], type: ChartSeriesType, stack?: string, curve?: ChartCurve) => ChartSeries[];
 /** Options of the line-like components */
@@ -35,10 +47,19 @@ export interface HeatmapConfig {
     xCategories?: readonly string[];
     /** Row names from bottom to top (collected from the data when omitted) */
     yCategories?: readonly string[];
-    /** Colors from the lowest to the highest value; a ramp of the first palette color by default */
-    colorScale?: readonly string[];
+    /**
+     * Colors from the lowest to the highest value (interpolated in OKLab), or
+     * a built-in theme-aware ramp of the first palette color
+     * @default "sequential"
+     */
+    colorScale?: readonly string[] | ChartColorScheme;
     /** Values at the ends of the color scale; the data range by default */
     valueRange?: readonly [number, number];
+    /**
+     * Value at the middle of the color scale (diverging data)
+     * @default 0 for `diverging` ramps spanning it, else the middle of the range
+     */
+    colorMidpoint?: number;
     /** Name of the value in the tooltip */
     name?: string;
     /** Corner radius of the cells, in pixels */
@@ -167,3 +188,252 @@ export declare const quadrantCenter: (config: Pick<QuadrantConfig, "xDomain" | "
 };
 /** Engine options of a quadrant matrix */
 export declare const quadrantChartOptions: (config: QuadrantConfig, base?: Omit<ChartOptions, "series">) => ChartOptions;
+/**
+ * Quantiles of values (`[0.5, 0.95, 0.99]` gives the median, p95 and p99),
+ * linearly interpolated like NumPy and Excel; non-finite values are ignored
+ */
+export declare const quantiles: (values: ArrayLike<number>, ps: readonly number[]) => number[];
+/** How the bins of a histogram are chosen: a count, or a rule */
+export type HistogramBinning = number | "auto" | "sturges" | "freedman-diaconis";
+/** Options of `binValues` */
+export interface BinOptions {
+    /**
+     * Number of bins, or the rule choosing it: `sturges` (log2 n + 1, for
+     * small normal-ish samples), `freedman-diaconis` (bin width from the
+     * interquartile range, robust to outliers); `auto` uses Freedman-Diaconis
+     * and Sturges when the spread is zero
+     * @default "auto"
+     */
+    bins?: HistogramBinning;
+    /** Range covered by the bins (values outside are not counted); the data range by default */
+    domain?: readonly [number, number];
+    /**
+     * Rounds the bin width to 1, 2 or 5 × 10^k and aligns the edges on it
+     * @default true
+     */
+    nice?: boolean;
+}
+/** Bins of a histogram */
+export interface HistogramBins {
+    /** Edges of the bins: one more than the bins */
+    edges: number[];
+    /** Number of values in every bin */
+    counts: number[];
+    /** Width of a bin */
+    width: number;
+    /** Number of values counted (finite, inside the domain) */
+    total: number;
+}
+/**
+ * Counts values into bins of equal width: linear in the number of values
+ * (a million samples take a few milliseconds; the spread of large samples
+ * is estimated on an even subsample)
+ */
+export declare const binValues: (values: ArrayLike<number>, options?: BinOptions) => HistogramBins;
+/** Options of `histogramSeries` */
+export interface HistogramSeriesOptions extends BinOptions {
+    /** Name of the series (legend, tooltip) */
+    name?: string;
+    /** Bar color (any CSS color) */
+    color?: string;
+    /** Formats the edges of the bins in the tooltip */
+    format?: (value: number) => string;
+    /** Bins already computed (`binValues`): `values` are then ignored */
+    binned?: HistogramBins;
+    /**
+     * Locale of the default name and of the bin edges
+     * @default the page language
+     */
+    locale?: string;
+}
+/** Bar series of a histogram: one touching bar per bin, labelled with its range */
+export declare const histogramSeries: (values: ArrayLike<number>, options?: HistogramSeriesOptions) => ChartSeries;
+/** Options of `boxplotStats` */
+export interface BoxplotStatsOptions {
+    /**
+     * Reach of the whiskers in interquartile ranges beyond the box (Tukey:
+     * 1.5); `"minmax"` extends them to the extremes (no outliers)
+     * @default 1.5
+     */
+    whisker?: number | "minmax";
+}
+/** Five-number summary of a sample, with the outliers */
+export interface BoxplotStats {
+    /** Lower whisker: the smallest value within reach */
+    low: number;
+    /** First quartile */
+    q1: number;
+    median: number;
+    /** Third quartile */
+    q3: number;
+    /** Upper whisker: the largest value within reach */
+    high: number;
+    /** Values beyond the whiskers */
+    outliers: number[];
+    min: number;
+    max: number;
+    mean: number;
+    /** Number of finite values */
+    count: number;
+}
+/** Quartiles, whiskers (Tukey's 1.5 IQR by default) and outliers of raw values */
+export declare const boxplotStats: (values: ArrayLike<number>, options?: BoxplotStatsOptions) => BoxplotStats;
+/** A sample of a box plot */
+export interface BoxplotGroup {
+    /** Category (or position) of the box */
+    x: ChartXValue;
+    /** Raw values: their quartiles, whiskers and outliers are computed */
+    values: ArrayLike<number>;
+    /** Color of the box (any CSS color) */
+    color?: string;
+}
+/** Box plot data of raw samples (one datum per group) */
+export declare const boxplotData: (groups: readonly BoxplotGroup[], options?: BoxplotStatsOptions) => ChartPointDatum[];
+/** Series of a BoxPlotChart */
+export declare const boxplotSeries: (series: readonly ChartSeries[]) => ChartSeries[];
+/** A bar of a waterfall chart */
+export interface WaterfallStep {
+    /** Category name of the bar */
+    label: string;
+    /** Change (positive or negative); ignored by totals */
+    value?: number;
+    /**
+     * `subtotal` and `total` bars show the running total, from zero
+     * @default "change"
+     */
+    kind?: "change" | "subtotal" | "total";
+    /** Color of this bar (any CSS color) */
+    color?: string;
+}
+/** Options of `waterfallSeries` */
+export interface WaterfallOptions {
+    /** Name of the series (tooltip) */
+    name?: string;
+    /** Color of the increases @default the success color */
+    upColor?: string;
+    /** Color of the decreases @default the danger color */
+    downColor?: string;
+    /** Color of the totals and subtotals @default the primary color */
+    totalColor?: string;
+    /**
+     * Value the first change starts from
+     * @default 0
+     */
+    start?: number;
+    /**
+     * Writes the change (or the total) at the end of every bar
+     * @default false
+     */
+    labels?: boolean;
+    /** Formats the values (labels, tooltip) */
+    format?: (value: number) => string;
+    /**
+     * Thin lines from the end of every bar to the next one; an object styles
+     * them
+     * @default true (dashed, secondary text color)
+     */
+    connector?: boolean | ChartConnectorOptions;
+    /**
+     * Locale of the default name
+     * @default the page language
+     */
+    locale?: string;
+}
+/**
+ * Floating bar series of a waterfall (bridge) chart: every change starts
+ * where the previous one ended; totals and subtotals start from zero
+ */
+export declare const waterfallSeries: (steps: readonly WaterfallStep[], options?: WaterfallOptions) => ChartSeries;
+/** Options of `bubbleSeries` */
+export interface BubbleOptions {
+    /**
+     * Diameter in pixels of the smallest bubbles
+     * @default 6
+     */
+    minSize?: number;
+    /**
+     * Diameter in pixels of the largest value
+     * @default 48
+     */
+    maxSize?: number;
+    /** Value drawn with `maxSize` (share a scale between charts); the largest value by default */
+    maxValue?: number;
+}
+/**
+ * Scatter series whose dots are sized by the `value` of their points: the
+ * area of a bubble is proportional to its value (diameter ∝ √value), the
+ * scale is shared by every series. Points are drawn from the largest to
+ * the smallest, so small bubbles stay on top (hover indexes refer to that
+ * order).
+ */
+export declare const bubbleSeries: (series: readonly ChartSeries[], options?: BubbleOptions) => ChartSeries[];
+/** A task (or milestone) of a Gantt chart */
+export interface GanttTask {
+    /** Row name (unique) */
+    name: string;
+    /** Start (a timestamp or a date) */
+    start: number | Date;
+    /** End; omitted for milestones */
+    end?: number | Date;
+    /** Share done, 0-1: drawn as a solid bar over the task */
+    progress?: number;
+    /** Group (phase, team): a color and a legend entry per group */
+    group?: string;
+    /** Color of the task (any CSS color); the color of its group by default */
+    color?: string;
+    /** Draws a dot at `start` instead of a bar */
+    milestone?: boolean;
+    /** Names of the tasks this one waits for (shown in its tooltip) */
+    dependencies?: readonly string[];
+}
+/** Options of `ganttSeries` */
+export interface GanttOptions {
+    /** Colors of the groups in order of appearance (any CSS colors); the chart palette by default */
+    colors?: readonly string[];
+    /**
+     * Name of the tasks without a group
+     * @default "Tasks" (in the `locale`)
+     */
+    taskName?: string;
+    /**
+     * Name of the progress bars (legend, tooltip)
+     * @default "Progress" (in the `locale`)
+     */
+    progressName?: string;
+    /**
+     * Name of the milestones (legend, tooltip)
+     * @default "Milestones" (in the `locale`)
+     */
+    milestoneName?: string;
+    /** Formats the progress shares (tooltip) @default "60%" */
+    formatProgress?: (share: number) => string;
+    /**
+     * Name of the dependencies row of the tooltip
+     * @default "Depends on" (in the `locale`)
+     */
+    dependenciesName?: string;
+    /**
+     * Locale of the default names and of the progress shares
+     * @default the page language
+     */
+    locale?: string;
+}
+/** Series of a Gantt chart and the row names in order */
+export interface GanttSeries {
+    series: ChartSeries[];
+    /** Task names from top to bottom (the `categories` of the x axis) */
+    categories: string[];
+    /** Time range of the tasks with a small margin (the `min` / `max` of the value axis) */
+    domain: [number, number];
+}
+/** Color `k` of the chart palette as a CSS color (theme variables first) */
+export declare const paletteColor: (k: number) => string;
+/**
+ * Floating bar series of a Gantt chart (horizontal, on a time axis): a
+ * translucent bar per task with its progress drawn over it, one series per
+ * group, and the milestones as dots
+ */
+export declare const ganttSeries: (tasks: readonly GanttTask[], options?: GanttOptions) => GanttSeries;
+/** Series of a RangeAreaChart: bands between `y0` and `y` (thin edges) */
+export declare const rangeAreaSeries: (series: readonly ChartSeries[], curve?: ChartCurve) => ChartSeries[];
+export {};

package/dist/charts/engine/presets.d.ts

@@ -1,4 +1,16 @@
-import { ChartCurve, ChartOptions, ChartSeries, ChartSeriesType } from './types.js';
+import { ChartColorScheme, ChartConnectorOptions, ChartCurve, ChartOptions, ChartPointDatum, ChartSeries, ChartSeriesType, ChartXValue } from './types.js';
+/** Default series names of the presets */
+interface PresetLabels {
+    value: string;
+    values: string;
+    count: string;
+    change: string;
+    tasks: string;
+    progress: string;
+    milestones: string;
+}
+/** Default series names of the presets in a locale (the page language by default) */
+export declare const presetLabels: (locale?: string) => PresetLabels;
 /** Gives the series without a `type` the type of the component */
 export declare const withSeriesType: (series: readonly ChartSeries[], type: ChartSeriesType, stack?: string, curve?: ChartCurve) => ChartSeries[];
 /** Options of the line-like components */
@@ -35,10 +47,19 @@ export interface HeatmapConfig {
     xCategories?: readonly string[];
     /** Row names from bottom to top (collected from the data when omitted) */
     yCategories?: readonly string[];
-    /** Colors from the lowest to the highest value; a ramp of the first palette color by default */
-    colorScale?: readonly string[];
+    /**
+     * Colors from the lowest to the highest value (interpolated in OKLab), or
+     * a built-in theme-aware ramp of the first palette color
+     * @default "sequential"
+     */
+    colorScale?: readonly string[] | ChartColorScheme;
     /** Values at the ends of the color scale; the data range by default */
     valueRange?: readonly [number, number];
+    /**
+     * Value at the middle of the color scale (diverging data)
+     * @default 0 for `diverging` ramps spanning it, else the middle of the range
+     */
+    colorMidpoint?: number;
     /** Name of the value in the tooltip */
     name?: string;
     /** Corner radius of the cells, in pixels */
@@ -167,3 +188,252 @@ export declare const quadrantCenter: (config: Pick<QuadrantConfig, "xDomain" | "
 };
 /** Engine options of a quadrant matrix */
 export declare const quadrantChartOptions: (config: QuadrantConfig, base?: Omit<ChartOptions, "series">) => ChartOptions;
+/**
+ * Quantiles of values (`[0.5, 0.95, 0.99]` gives the median, p95 and p99),
+ * linearly interpolated like NumPy and Excel; non-finite values are ignored
+ */
+export declare const quantiles: (values: ArrayLike<number>, ps: readonly number[]) => number[];
+/** How the bins of a histogram are chosen: a count, or a rule */
+export type HistogramBinning = number | "auto" | "sturges" | "freedman-diaconis";
+/** Options of `binValues` */
+export interface BinOptions {
+    /**
+     * Number of bins, or the rule choosing it: `sturges` (log2 n + 1, for
+     * small normal-ish samples), `freedman-diaconis` (bin width from the
+     * interquartile range, robust to outliers); `auto` uses Freedman-Diaconis
+     * and Sturges when the spread is zero
+     * @default "auto"
+     */
+    bins?: HistogramBinning;
+    /** Range covered by the bins (values outside are not counted); the data range by default */
+    domain?: readonly [number, number];
+    /**
+     * Rounds the bin width to 1, 2 or 5 × 10^k and aligns the edges on it
+     * @default true
+     */
+    nice?: boolean;
+}
+/** Bins of a histogram */
+export interface HistogramBins {
+    /** Edges of the bins: one more than the bins */
+    edges: number[];
+    /** Number of values in every bin */
+    counts: number[];
+    /** Width of a bin */
+    width: number;
+    /** Number of values counted (finite, inside the domain) */
+    total: number;
+}
+/**
+ * Counts values into bins of equal width: linear in the number of values
+ * (a million samples take a few milliseconds; the spread of large samples
+ * is estimated on an even subsample)
+ */
+export declare const binValues: (values: ArrayLike<number>, options?: BinOptions) => HistogramBins;
+/** Options of `histogramSeries` */
+export interface HistogramSeriesOptions extends BinOptions {
+    /** Name of the series (legend, tooltip) */
+    name?: string;
+    /** Bar color (any CSS color) */
+    color?: string;
+    /** Formats the edges of the bins in the tooltip */
+    format?: (value: number) => string;
+    /** Bins already computed (`binValues`): `values` are then ignored */
+    binned?: HistogramBins;
+    /**
+     * Locale of the default name and of the bin edges
+     * @default the page language
+     */
+    locale?: string;
+}
+/** Bar series of a histogram: one touching bar per bin, labelled with its range */
+export declare const histogramSeries: (values: ArrayLike<number>, options?: HistogramSeriesOptions) => ChartSeries;
+/** Options of `boxplotStats` */
+export interface BoxplotStatsOptions {
+    /**
+     * Reach of the whiskers in interquartile ranges beyond the box (Tukey:
+     * 1.5); `"minmax"` extends them to the extremes (no outliers)
+     * @default 1.5
+     */
+    whisker?: number | "minmax";
+}
+/** Five-number summary of a sample, with the outliers */
+export interface BoxplotStats {
+    /** Lower whisker: the smallest value within reach */
+    low: number;
+    /** First quartile */
+    q1: number;
+    median: number;
+    /** Third quartile */
+    q3: number;
+    /** Upper whisker: the largest value within reach */
+    high: number;
+    /** Values beyond the whiskers */
+    outliers: number[];
+    min: number;
+    max: number;
+    mean: number;
+    /** Number of finite values */
+    count: number;
+}
+/** Quartiles, whiskers (Tukey's 1.5 IQR by default) and outliers of raw values */
+export declare const boxplotStats: (values: ArrayLike<number>, options?: BoxplotStatsOptions) => BoxplotStats;
+/** A sample of a box plot */
+export interface BoxplotGroup {
+    /** Category (or position) of the box */
+    x: ChartXValue;
+    /** Raw values: their quartiles, whiskers and outliers are computed */
+    values: ArrayLike<number>;
+    /** Color of the box (any CSS color) */
+    color?: string;
+}
+/** Box plot data of raw samples (one datum per group) */
+export declare const boxplotData: (groups: readonly BoxplotGroup[], options?: BoxplotStatsOptions) => ChartPointDatum[];
+/** Series of a BoxPlotChart */
+export declare const boxplotSeries: (series: readonly ChartSeries[]) => ChartSeries[];
+/** A bar of a waterfall chart */
+export interface WaterfallStep {
+    /** Category name of the bar */
+    label: string;
+    /** Change (positive or negative); ignored by totals */
+    value?: number;
+    /**
+     * `subtotal` and `total` bars show the running total, from zero
+     * @default "change"
+     */
+    kind?: "change" | "subtotal" | "total";
+    /** Color of this bar (any CSS color) */
+    color?: string;
+}
+/** Options of `waterfallSeries` */
+export interface WaterfallOptions {
+    /** Name of the series (tooltip) */
+    name?: string;
+    /** Color of the increases @default the success color */
+    upColor?: string;
+    /** Color of the decreases @default the danger color */
+    downColor?: string;
+    /** Color of the totals and subtotals @default the primary color */
+    totalColor?: string;
+    /**
+     * Value the first change starts from
+     * @default 0
+     */
+    start?: number;
+    /**
+     * Writes the change (or the total) at the end of every bar
+     * @default false
+     */
+    labels?: boolean;
+    /** Formats the values (labels, tooltip) */
+    format?: (value: number) => string;
+    /**
+     * Thin lines from the end of every bar to the next one; an object styles
+     * them
+     * @default true (dashed, secondary text color)
+     */
+    connector?: boolean | ChartConnectorOptions;
+    /**
+     * Locale of the default name
+     * @default the page language
+     */
+    locale?: string;
+}
+/**
+ * Floating bar series of a waterfall (bridge) chart: every change starts
+ * where the previous one ended; totals and subtotals start from zero
+ */
+export declare const waterfallSeries: (steps: readonly WaterfallStep[], options?: WaterfallOptions) => ChartSeries;
+/** Options of `bubbleSeries` */
+export interface BubbleOptions {
+    /**
+     * Diameter in pixels of the smallest bubbles
+     * @default 6
+     */
+    minSize?: number;
+    /**
+     * Diameter in pixels of the largest value
+     * @default 48
+     */
+    maxSize?: number;
+    /** Value drawn with `maxSize` (share a scale between charts); the largest value by default */
+    maxValue?: number;
+}
+/**
+ * Scatter series whose dots are sized by the `value` of their points: the
+ * area of a bubble is proportional to its value (diameter ∝ √value), the
+ * scale is shared by every series. Points are drawn from the largest to
+ * the smallest, so small bubbles stay on top (hover indexes refer to that
+ * order).
+ */
+export declare const bubbleSeries: (series: readonly ChartSeries[], options?: BubbleOptions) => ChartSeries[];
+/** A task (or milestone) of a Gantt chart */
+export interface GanttTask {
+    /** Row name (unique) */
+    name: string;
+    /** Start (a timestamp or a date) */
+    start: number | Date;
+    /** End; omitted for milestones */
+    end?: number | Date;
+    /** Share done, 0-1: drawn as a solid bar over the task */
+    progress?: number;
+    /** Group (phase, team): a color and a legend entry per group */
+    group?: string;
+    /** Color of the task (any CSS color); the color of its group by default */
+    color?: string;
+    /** Draws a dot at `start` instead of a bar */
+    milestone?: boolean;
+    /** Names of the tasks this one waits for (shown in its tooltip) */
+    dependencies?: readonly string[];
+}
+/** Options of `ganttSeries` */
+export interface GanttOptions {
+    /** Colors of the groups in order of appearance (any CSS colors); the chart palette by default */
+    colors?: readonly string[];
+    /**
+     * Name of the tasks without a group
+     * @default "Tasks" (in the `locale`)
+     */
+    taskName?: string;
+    /**
+     * Name of the progress bars (legend, tooltip)
+     * @default "Progress" (in the `locale`)
+     */
+    progressName?: string;
+    /**
+     * Name of the milestones (legend, tooltip)
+     * @default "Milestones" (in the `locale`)
+     */
+    milestoneName?: string;
+    /** Formats the progress shares (tooltip) @default "60%" */
+    formatProgress?: (share: number) => string;
+    /**
+     * Name of the dependencies row of the tooltip
+     * @default "Depends on" (in the `locale`)
+     */
+    dependenciesName?: string;
+    /**
+     * Locale of the default names and of the progress shares
+     * @default the page language
+     */
+    locale?: string;
+}
+/** Series of a Gantt chart and the row names in order */
+export interface GanttSeries {
+    series: ChartSeries[];
+    /** Task names from top to bottom (the `categories` of the x axis) */
+    categories: string[];
+    /** Time range of the tasks with a small margin (the `min` / `max` of the value axis) */
+    domain: [number, number];
+}
+/** Color `k` of the chart palette as a CSS color (theme variables first) */
+export declare const paletteColor: (k: number) => string;
+/**
+ * Floating bar series of a Gantt chart (horizontal, on a time axis): a
+ * translucent bar per task with its progress drawn over it, one series per
+ * group, and the milestones as dots
+ */
+export declare const ganttSeries: (tasks: readonly GanttTask[], options?: GanttOptions) => GanttSeries;
+/** Series of a RangeAreaChart: bands between `y0` and `y` (thin edges) */
+export declare const rangeAreaSeries: (series: readonly ChartSeries[], curve?: ChartCurve) => ChartSeries[];
+export {};