@inflexa-ai/harness 0.42.2 → 0.43.1

package/dist/report-render/figures/common.d.ts

@@ -0,0 +1,321 @@
+/**
+ * The shared parts of each chart: the axis builders, the guide lines, the statistics text, the color scale,
+ * the size legend, the categorical palette, and the legend icons.
+ *
+ * The shared chart path of `chart.ts` and each figure module read these helpers, and no figure writes an axis
+ * style of its own. Thus each rule of a publication figure holds in one place, and each chart of a page obeys
+ * it:
+ *
+ * - The y title turns 90 degrees and sits in the middle beside its axis. The x title sits in the middle under
+ *   its axis.
+ * - A category axis shows a title only where the block declares one. A value axis always shows a title.
+ * - A guide line is thin, gray, and dashed. Its label sits inside the plot at the far end of the line, thus it
+ *   never covers a tick label.
+ * - A continuous color scale prints its title and its two ends as static text, and it shows no drag control.
+ * - Eight categories or fewer take the Okabe-Ito palette, and more take the wide palette.
+ * - A legend icon matches the form of its series.
+ *
+ * Each helper gives plain data, because the option rides to the page as inline JSON.
+ */
+import { type Result } from "neverthrow";
+import { type ChannelOrder, type ChartEncoding, type ChartTransform } from "../../contracts/report-blocks.js";
+import { type ArtifactTableReference, type ColumnMeaning } from "../../contracts/report-reference.js";
+import type { Cell, ChartRow, EchartOption } from "../chart.js";
+import type { RenderProblem } from "../types.js";
+/** The display labels that a bound table declares, keyed by the raw column name. */
+export type ColumnLabels = ArtifactTableReference["columnLabels"];
+/** The column meanings that a bound table declares, keyed by the raw column name. */
+export type ColumnMeanings = ArtifactTableReference["columnMeanings"];
+/** A typed `invalid-chart-input` problem that names the block and the cause. */
+export declare function chartProblem(blockId: string, detail: string): RenderProblem;
+/** Convert one cell to a finite number, or `null` when it is absent or not numeric. */
+export declare function toNumber(cell: Cell | null | undefined): number | null;
+/**
+ * The legend text of one category value: the value with each underscore as a space.
+ *
+ * An analysis column carries a machine category such as `up_in_nonresponders`, and a legend reads for a
+ * person. The replacement reads no locale, thus the same value gives the same text on every host. The raw
+ * value stays in the data rows, thus the provenance loses nothing.
+ */
+export declare function categoryName(value: Cell): string;
+/**
+ * The lane of each span in turn, for at most `count` spans: the lowest lane whose last span ends under the start
+ * of the next span, else a new lane under the others.
+ *
+ * A tree over the lanes holds the least end of each range of lanes, thus the lowest free lane takes one walk down
+ * the tree, and a track of many overlapping spans takes linear-logarithmic time. A lane that holds no span yet
+ * ends at minus infinity, thus the lowest such lane is the next new lane.
+ */
+export declare function firstFreeLanes(count: number): (start: number, end: number) => number;
+/** The distinct values in first-appearance order. */
+export declare function firstAppearance<T>(values: readonly T[]): T[];
+/** True when the column exists in the declared header, or in one row at least. */
+export declare function columnPresent(column: string, rows: readonly Record<string, Cell>[], columns: readonly string[] | undefined): boolean;
+/**
+ * Compare two cells for a sort by x, and for a rank rule.
+ *
+ * A pair that both hold a finite number compares by that number. A text-backed table gives each cell as a
+ * string, thus a code-unit order would put `"10"` between `"1"` and `"2"` and a time axis would run out of
+ * order. Any other pair compares by the code-unit order of the string form.
+ *
+ * The comparison never calls `localeCompare`, thus the order stays the same on every host.
+ */
+export declare function compareCell(a: Cell, b: Cell): number;
+/**
+ * Sort the categories of one channel by the value of its order column.
+ *
+ * The key of a category is the cell of the order column in each row of that category, and it must be one
+ * value across those rows. A category whose rows disagree has no one place, thus it refuses and names the
+ * category. The compare of the sort reads two numbers as numbers and anything else as text. The sort is
+ * stable and a descending order negates the compare, thus a tie keeps the first appearance in both
+ * directions.
+ *
+ * `categoryAt` gives the category of one row, or no value for a row that draws none, and `keyAt` gives the
+ * cell of the order column of one row. The categories and the rows match by their text, thus a category list
+ * of strings and a column of numbers still meet. A row that lacks the order cell gives its category no place,
+ * thus it refuses.
+ */
+export declare function orderCategories<T extends Cell>(blockId: string, rowCount: number, categoryAt: (index: number) => Cell | null | undefined, categories: readonly T[], order: ChannelOrder | undefined, keyAt: (index: number) => Cell | undefined): Result<T[], RenderProblem>;
+/**
+ * Sort the categories of one quick-path channel that reads a plain column, by the order of that channel.
+ * The row of each category reads the category column and the order column of the same row.
+ */
+export declare function orderQuickCategories(blockId: string, rows: readonly ChartRow[], column: string, order: ChannelOrder | undefined): Result<Cell[], RenderProblem>;
+/** One channel of the quick-path encoding that names one column. */
+export type ColumnChannel = Exclude<keyof ChartEncoding, "label" | "tracks">;
+/** The table that a figure reads a channel from: the block, the rows, and the declared column order. */
+export interface ChannelSource {
+    readonly blockId: string;
+    readonly rows: readonly ChartRow[];
+    readonly columns?: readonly string[];
+}
+/**
+ * The column of one channel that a figure reads as a plain column, or `undefined` where the block names no
+ * such channel.
+ *
+ * A figure reads the cells of such a channel as they are. Thus a transform or an order on the channel would
+ * do nothing, and it refuses. A column that no row holds refuses, as it does on every other chart.
+ */
+export declare function plainColumn(figure: string, encoding: ChartEncoding, channel: ColumnChannel, source: ChannelSource): Result<string | undefined, RenderProblem>;
+/** The column of one channel that a figure demands, read as a plain column. An absent channel refuses. */
+export declare function demandedColumn(figure: string, encoding: ChartEncoding, channel: ColumnChannel, source: ChannelSource): Result<string, RenderProblem>;
+/**
+ * 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)[];
+/**
+ * The distance in pixels between the x axis line and its name.
+ *
+ * The name sits under the middle of the axis, thus the gap must clear the axis labels below the line. The
+ * value is a fixed constant, thus the derivation stays deterministic.
+ */
+export declare const X_AXIS_NAME_GAP = 34;
+/**
+ * The distance in pixels between the tick labels of the y axis and its name.
+ *
+ * The chart runtime moves a name that overlaps the tick labels past them, and the gap then counts from the
+ * labels. Thus a long tick label never runs under the title.
+ */
+export declare const Y_AXIS_NAME_GAP = 10;
+/**
+ * The name fields of one axis, or no field where the axis carries no title.
+ *
+ * The x title sits under the middle of the axis. The y title turns 90 degrees and sits in the middle beside
+ * the axis, thus it reads along the axis and it takes no width from the plot.
+ */
+export declare function axisNameFields(axis: "x" | "y", title: string | undefined): EchartOption;
+/**
+ * The title of a quantity under one per-row transform, for example `log10(Normalized count)` or
+ * `−log10(Adjusted p-value)`. The minus sign is the character, not a hyphen.
+ */
+export declare function transformedTitle(transform: ChartTransform, base: string): string;
+/**
+ * The labels of a bound table with one more entry for each transformed channel whose column declares a label.
+ * The derived name of the channel maps to the label inside the transform, thus an axis over the channel reads
+ * `log10(Normalized count)` and never `log10(normalized_count)`. A derived name that the table declares itself
+ * keeps its own label, and a column with no label keeps the derived name.
+ */
+export declare function withTransformedLabels(labels: ColumnLabels, channels: ReadonlyArray<{
+    readonly name: string;
+    readonly column: string;
+    readonly transform?: ChartTransform;
+}>): ColumnLabels;
+/**
+ * The title of a value axis that reads one column, most specific first: the declared label of the column, the
+ * semantic title of the preset, then the raw column name.
+ *
+ * A declared label answers for this one column of this one artifact, and a preset title answers for every
+ * chart of its kind. Thus the label outranks the preset. The caller resolves an agent axes title over this
+ * whole chain, because that title names this one axis of this one block.
+ */
+export declare function valueAxisTitle(labels: ColumnLabels, column: string, preset?: string): string;
+/**
+ * The title of a category axis, or `undefined` where the block declares none.
+ *
+ * The category names already state what the axis holds, and a raw column name such as `cluster` or `sample`
+ * repeats them in machine text. Thus a category axis carries a title only where the author declared one: an
+ * axes title of the block, or the label of the column.
+ */
+export declare function categoryAxisTitle(labels: ColumnLabels, column: string, declared?: string): string | undefined;
+/**
+ * One value axis: the axis type, a fitted range where the chart asks for one, and the name fields.
+ *
+ * `scale` fits the range to the data, and a bar leaves it out because a bar measures from zero. `log` gives
+ * the logarithmic axis type.
+ */
+export declare function valueAxis(axis: "x" | "y", title: string, fields?: {
+    scale?: boolean;
+    log?: boolean;
+    min?: number;
+    max?: number;
+}): EchartOption;
+/**
+ * One category axis: the categories in their order, the direction, and the declared title alone.
+ *
+ * `topDown` inverts a y axis. The chart runtime draws the first category of a y axis at the origin, thus a
+ * table that reads top-down needs the inverted axis to put its first row at the top.
+ */
+export declare function categoryAxis(axis: "x" | "y", categories: readonly Cell[], fields?: {
+    title?: string;
+    topDown?: boolean;
+}): EchartOption;
+/** The stroke of each guide line. */
+export declare const GUIDE_LINE_STYLE: EchartOption;
+/**
+ * The label place of each guide line: inside the plot, at the far end of the line.
+ *
+ * A vertical line ends at the top of the plot and a horizontal line ends at the right edge. Both ends lie away
+ * from the tick labels, thus a guide label never covers a tick.
+ */
+export declare const GUIDE_LABEL_POSITION = "insideEndTop";
+/**
+ * One guide line of a mark member: a constant on one axis, and its label.
+ *
+ * A guide with no text shows no label. The runtime would print the constant there, and a bare number beside a
+ * line reads as a plotted value.
+ */
+export declare function guideLine(axis: "x" | "y", value: number, label?: string): EchartOption;
+/** The mark member of some guide lines, in the one guide style. */
+export declare function guideMarkLine(lines: readonly EchartOption[]): EchartOption;
+/**
+ * One statistic that a figure prints: the label of the block, the resolved value, and the shown text of the
+ * value.
+ */
+export interface FigureStatistic {
+    readonly label: string;
+    readonly value: string | number;
+    readonly text: string;
+}
+/**
+ * The shown text of one statistic, in the number format of its column, with the power of ten of a figure, and
+ * the unit of its reference after it.
+ *
+ * The kind follows the column of the locator, as a table cell does. Thus a p-value prints in the scientific
+ * form, for example `1.3 × 10⁻³`, and a stored zero of a p-value prints the below-resolution form and never a
+ * bare zero. A percent sign joins its value, for example `27.5%`, and every other unit follows a space, for
+ * example `426 days`.
+ */
+export declare function statisticText(value: string | number, column: string, unit?: string): string;
+/** The four corners of a plot where a figure prints its statistics. */
+export type PlotCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/**
+ * The statistics of a figure as one text element inside the plot: one line for each statistic, in block
+ * order, in the form `label = value`.
+ *
+ * A `graphic` element sits at a place of the chart and reads no data coordinate, thus the figure names the
+ * corner that its field uses. A figure with no statistic gives no element.
+ */
+export declare function statisticsGraphic(statistics: readonly FigureStatistic[], corner: PlotCorner): EchartOption[];
+/** The inset of a statistics text from its data corner, in pixels. */
+export declare const STATISTICS_POINT_INSET_PX = 8;
+/**
+ * The statistics of a figure as the label of one point of no size at a corner of the data: one line for each
+ * statistic, in block order, in the form `label = value`.
+ *
+ * A `graphic` element sits at a place of the container, and a plot whose size follows the container moves
+ * away from it. A point sits in the data, thus its label stays at the corner of the plot in every container
+ * and in every export. The corner names the side of the point that the text takes. The label reads the text
+ * from the name of the point, thus no character of a statistic reads as a template of the chart runtime. A
+ * figure with no statistic gives no series.
+ */
+export declare function statisticsSeries(statistics: readonly FigureStatistic[], point: readonly [number, number], corner: PlotCorner): EchartOption[];
+/** The range and the ramp of one continuous color. */
+export interface ContinuousScale {
+    readonly min: number;
+    readonly max: number;
+    readonly ramp: readonly string[];
+}
+/**
+ * The scale of one continuous color over its values.
+ *
+ * A column whose values cross zero takes the diverging ramp, centered on zero, thus a negative value and a
+ * positive value of one size read as two colors of one strength. Every other column takes the sequential
+ * ramp over its own range. The extent reads the values in one pass, thus a large column never spreads onto
+ * the call stack.
+ */
+export declare function continuousScale(values: readonly number[]): ContinuousScale;
+/** The shown text of one end of a scale over one column, in the number format of that column, with the power of ten of a figure. */
+export declare function scaleEndText(end: number, column: string, meaning?: ColumnMeaning): string;
+/**
+ * The members of one continuous color map: the range, the place at the right edge of the plot, the title and
+ * the two ends as static text, and the ramp.
+ *
+ * The map shows no drag control, because a figure is a still image and a handle would print its own raw
+ * value. The number helper formats each end, thus the scale and a table cell of one column read alike. The
+ * title and the upper end share the top text, one line each, and the lower end sits under the bar.
+ */
+export declare function colorScale(scale: ContinuousScale, title: string, column: string, meaning?: ColumnMeaning): EchartOption;
+/**
+ * The size legend of a size channel: the title, and three reference circles with their values.
+ *
+ * The circles show the smallest value, the middle of the range, and the largest value, at the symbol size
+ * that the size map gives each one. The number helper formats each value. The legend is one `graphic` group,
+ * thus a figure places it where its field puts it. A range of one value gives one circle.
+ */
+export declare function sizeLegend(range: {
+    readonly min: number;
+    readonly max: number;
+}, title: string, column: string, place: EchartOption, meaning?: ColumnMeaning): EchartOption;
+/** The categorical palette of a chart that draws `count` categories. */
+export declare function categoricalPalette(count: number): readonly string[];
+/**
+ * The count of lines that the entries of a horizontal legend fill at one width, at one text size. An entry is
+ * the icon of the text size, the gap to its text, and the text. The entries fill each line in order, one item
+ * gap apart. The export estimates the lines of a legend with the same rule.
+ */
+export declare function legendLineCount(entries: readonly string[], widthPx: number, textPx: number): number;
+/** The height of one line of a legend at one text size, in pixels: the text and the item gap under it. */
+export declare function legendLinePx(textPx: number, itemGapPx?: number): number;
+/**
+ * The legend icon of a line and of a step: a flat bar of eight units by one. The legend keeps the aspect of
+ * the path, thus the icon draws as a short line at the width of one legend item.
+ */
+export declare const LINE_LEGEND_ICON = "path://M0,0H8V1H0Z";
+/** The legend icon of a bar, an area, a box, and a shape: a filled square. */
+export declare const AREA_LEGEND_ICON = "rect";
+/** The legend icon of a point. */
+export declare const POINT_LEGEND_ICON = "circle";
+/** The legend icon of one runtime series, by its form. */
+export declare function legendIconOf(series: EchartOption): string;
+/**
+ * The figure rules that read the whole option: the wide palette past eight categories, the icon of each
+ * legend entry, and the title of each axis off its labels.
+ *
+ * The derivation and each figure module give an option, and this pass runs on it after the layout discipline.
+ * An option that states its own palette keeps it.
+ */
+export declare function applyFigureRules(option: EchartOption): EchartOption;
+/**
+ * The option member in which a figure states the height of the page chart body that it needs, in pixels.
+ *
+ * A figure of many rows, for example a heatmap of many genes, needs a body taller than the default body to
+ * print each row name. The chart runtime reads no such field, and the render takes the member off the option
+ * before the option reaches the page or the export.
+ */
+export declare const FIGURE_BODY_MEMBER = "reportFigureBodyPx";
+/** One option with the height of the chart body that its figure needs, bounded by the largest body. */
+export declare function withFigureBody(option: EchartOption, bodyPx: number): EchartOption;