@inflexa-ai/harness 0.42.2 → 0.43.1

package/dist/report-render/chart.d.ts

@@ -5,27 +5,33 @@
  * `deriveChartOption` turns that grammar and the resolved rows into one ECharts option object. The chart
  * container markup lives beside this file, and it wraps the option that this derivation gives.
  *
- * The derivation reads one shape. A preset expands into a composition before the derivation
- * (`chart-presets.ts`), and each base chart type keeps its own fixed rule. Thus the two paths cannot
- * drift.
+ * A preset draws through its figure module (`figures/`), and each base chart type keeps its own fixed rule.
+ * A dense figure builds its points through the composition machinery of this file, thus a figure and a
+ * composition read one series path.
  *
- * The renderer computes no aggregate. Each plotted number stays traceable to one cell of the evidence
- * artifact, or to a per-row transform of one cell. A pie or a heatmap arrives one row per category or per
- * cell, thus a repeated category or a repeated pair is a refusal and not a silent sum.
+ * The renderer computes no aggregate outside the named summaries: the histogram bins, the box quantiles, the
+ * violin density, and the shares of a normalized bar. Every other plotted number stays traceable to one
+ * cell of the evidence artifact, or to a per-row transform of one cell. A pie, a heatmap, a stacked bar, and
+ * a radar arrive one row per category or per pair, thus a repeated category or a repeated pair is a refusal
+ * and not a silent sum.
  *
  * The derivation is deterministic. Every object builds in one fixed key order, and the code reads no
  * clock, no random value, and no locale. A string comparison uses the code-unit order (`<`) and never
  * `localeCompare`, thus the same rows give the same bytes on every host.
  *
  * The option rides to the page as inline JSON. Thus no axis label and no tooltip can carry a function
- * formatter, and every formatter here is a static template of the chart runtime. As a result the
- * derivation bounds the tick precision of the one axis whose unit it declares itself, and every other
- * value axis keeps the tick values that ECharts computes.
+ * formatter, and every formatter here is a static template of the chart runtime or a static text. As a
+ * result the derivation bounds the tick precision of the one axis whose unit it declares itself, and every
+ * other value axis keeps the tick values that ECharts computes. A custom series names its renderer as a
+ * string, and each consumer of the option binds the name (`chart-renderers.ts`).
  */
 import { type Result } from "neverthrow";
 import { type ChartBlock, type ChartTransform } from "../contracts/report-blocks.js";
 import { type PresetRule } from "./chart-presets.js";
-import type { RenderProblem } from "./types.js";
+import { transformColumn } from "./figures/common.js";
+import { type FigureRegistry } from "./figures/index.js";
+import type { RenderProblem, RenderStatistic, RenderTrack, RenderTrees } from "./types.js";
+export { transformColumn };
 /** One cell of a resolved row. A cell is one string or one number. */
 export type Cell = string | number;
 /** One resolved row of the bound table, keyed by column name. */
@@ -35,14 +41,30 @@ export type EchartOption = Record<string, unknown>;
 /**
  * Derive the ECharts option for a chart block, then pass it through `normalizeEchartSpec`.
  *
- * The normalizer owns the bottom legend, the save action, and the axis-label discipline. Thus the
- * derivation sets no `title`, no `legend`, and no `toolbox`. The theme palette assigns the series colors by
- * their order, and the null category of a preset is the one series that names a color of its own.
+ * The normalizer owns the bottom legend and the axis-label discipline. Thus the derivation sets no `title`,
+ * and it sets a `legend` only where an auxiliary series would show an orphan entry. The theme palette assigns
+ * the series colors by their order, and a null category or a focus is the one case that names a color.
  *
  * The axis of a channel names the label that the binding declares for its column. The semantic title of a
  * preset answers next, and the raw column name answers last.
  */
-export declare function deriveChartOption(block: ChartBlock, rows: readonly ChartRow[], columns?: readonly string[]): Result<EchartOption, RenderProblem>;
+export declare function deriveChartOption(block: ChartBlock, rows: readonly ChartRow[], columns?: readonly string[], inputs?: ChartInputs, opts?: ChartOpts): Result<EchartOption, RenderProblem>;
+/**
+ * The resolved parts of a chart beside the rows of its binding: the value of each statistic, in block order,
+ * the rows of the track, and the rows of the tree of each axis. A block that declares none of them takes no
+ * input.
+ */
+export interface ChartInputs {
+    readonly statistics?: readonly RenderStatistic[];
+    readonly track?: RenderTrack;
+    readonly trees?: RenderTrees;
+}
+/** The options of the chart derivation: the figure modules that the dispatch asks first. */
+export interface ChartOpts {
+    readonly figures: FigureRegistry;
+}
+/** The options of every render: the registered figure modules. */
+export declare const DEFAULT_CHART_OPTS: ChartOpts;
 /**
  * Derive the option of one chart, and read the shared payload of its artifact where the inline form grows
  * too large.
@@ -60,7 +82,7 @@ export declare function deriveChartOption(block: ChartBlock, rows: readonly Char
  * five-number summary, an addressed pair, and the upper half of a band are each such a value, thus no
  * descriptor can state one.
  */
-export declare function deriveChartRender(block: ChartBlock, rows: readonly ChartRow[], columns: readonly string[] | undefined, target: ChartPayloadTarget): Result<ChartRender, RenderProblem>;
+export declare function deriveChartRender(block: ChartBlock, rows: readonly ChartRow[], columns: readonly string[] | undefined, target: ChartPayloadTarget, inputs?: ChartInputs, opts?: ChartOpts): Result<ChartRender, RenderProblem>;
 /**
  * The label of one named point. `{b}` is the name of the item, thus the label needs no function.
  *
@@ -69,12 +91,13 @@ export declare function deriveChartRender(block: ChartBlock, rows: readonly Char
  */
 export declare const POINT_LABEL: EchartOption;
 /**
- * One column that a page-side series build reads: the place of the column in the payload, and the per-row
- * transform of the channel.
+ * One column that a page-side series build reads: the place of the column in the payload, the per-row
+ * transform of the channel, and whether the page reads each cell as its number.
  */
 export interface ChartColumnSource {
     readonly column: number;
     readonly transform?: ChartTransform;
+    readonly numeric?: true;
 }
 /**
  * One runtime series, as the page builds it from the columnar payload.
@@ -86,17 +109,24 @@ export interface ChartColumnSource {
  * flags are row places of the payload, thus a split carries the flags of its own rows alone.
  *
  * `sort` states that the form draws along the x axis, and `swap` states that the pair leads with the value
- * of a horizontal bar.
+ * of a horizontal bar. `rise` states that the points draw in the ascending order of their color, thus the high
+ * values draw on top.
+ *
+ * `color` and `size` name the columns of a continuous color and of a symbol size. Each one adds one member
+ * to the item after the pair, in that order, and a row whose cell is not numeric draws no point.
  */
 export interface ChartSeriesSource {
     readonly x: ChartColumnSource;
     readonly y: ChartColumnSource;
+    readonly color?: ChartColumnSource;
+    readonly size?: ChartColumnSource;
     readonly group?: ChartColumnSource;
     readonly value?: Cell;
     readonly category?: number;
     readonly label?: number;
     readonly flags?: readonly number[];
     readonly sort?: boolean;
+    readonly rise?: boolean;
     readonly swap?: boolean;
 }
 /**
@@ -120,16 +150,19 @@ export interface ChartPayloadTarget {
     readonly key: string;
     readonly columns: readonly string[];
 }
-/** The option of one chart, and whether it reads the registered payload of its artifact. */
+/**
+ * The option of one chart, whether it reads the registered payload of its artifact, the same chart with
+ * every row inline, and the box of its page chart body.
+ *
+ * A dense page option holds no row, thus the export renders the inline option. `bodyPx` is the height of the
+ * chart body: a facet grows it one row of height for each row of panels, and a figure of many rows states its
+ * own. `widthPx` is the width of a figure that draws a block of a fixed size, for example the square of a PCA.
+ * The card narrows the body to that width and centers it, and a chart with no such width fills the card.
+ */
 export interface ChartRender {
     readonly option: EchartOption;
     readonly readsPayload: boolean;
+    readonly inline: EchartOption;
+    readonly bodyPx: number;
+    readonly widthPx?: number;
 }
-/**
- * The transformed value of one column, one entry for each row. A row with no usable cell gives `null`.
- *
- * The page-side series build holds the twin of this function, because a chart that reads the payload
- * transforms its columns in the browser. A shared test vector runs the two over one set of cells, thus the
- * two cannot give different numbers in silence.
- */
-export declare function transformColumn(rows: readonly ChartRow[], column: string, transform: ChartTransform): (number | null)[];