@inflexa-ai/harness 0.42.2 → 0.43.0

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

@@ -15,6 +15,8 @@
  * The token block is the exception to the first invariant. The token set is the contract of the identity,
  * thus it stays complete even where no current rule reads a token.
  */
+/** The height of the chart body on the page, in pixels, for a chart that states no height of its own. */
+export declare const CHART_BODY_PX = 400;
 /** The style rules of the page. The renderer inlines them in one `<style>` block. */
 export declare const DESIGN_CSS: string;
 /**
@@ -88,6 +90,164 @@ export declare const GRID_THEME_PARAMS: {
  * reads it. One source prevents a silent mismatch between the two sites.
  */
 export declare const ECHARTS_THEME_NAME = "inflexa";
+/**
+ * The font stack of the chart text: the journal sans stack. A figure keeps its own typography on the page
+ * and in the paper, thus the chart text never reads the page fonts.
+ *
+ * No family name takes quotes. The server render of the chart runtime writes the stack into a double-quoted
+ * `style` attribute with no escape, and a double quote there breaks the SVG file.
+ */
+export declare const CHART_FONT_STACK = "Helvetica, Arial, sans-serif";
+/**
+ * The text sizes of a chart, in pixels: on the page, in the SVG and the column PNG, and in the slide PNG.
+ *
+ * The print size is 7 points at the column width, which is the upper bound of the Nature guide (5 to 7
+ * points), at 96 pixels for each inch. The slide size reads from the back of a room at the full width of a
+ * slide.
+ */
+export declare const CHART_PAGE_TEXT_PX = 12;
+export declare const CHART_PRINT_TEXT_PX = 9.33;
+export declare const CHART_SLIDE_TEXT_PX = 24;
+/** The names of the two export themes. The registration script and the export read the same names. */
+export declare const CHART_PRINT_THEME_NAME = "inflexa-print";
+export declare const CHART_SLIDE_THEME_NAME = "inflexa-slide";
+/** The size of one chart export: the name of its theme, the CSS pixel box, and the millimeter box of a column. */
+export interface ChartExportSize {
+    readonly theme: string;
+    readonly textPx: number;
+    readonly widthPx: number;
+    readonly heightPx: number;
+    readonly widthMm?: number;
+    readonly heightMm?: number;
+    readonly pixelRatio: number;
+    readonly label: string;
+}
+/**
+ * The export sizes of a chart: the single journal column, the double journal column, and a 16:9 slide.
+ *
+ * A column states its box in millimeters and in CSS pixels at 96 pixels for each inch: 89 × 67 mm is 336 ×
+ * 253 px, and 183 × 92 mm is 692 × 348 px. The column PNG draws at a pixel ratio of 3.125, which is 300 DPI,
+ * thus the single column is 1050 px wide. The slide draws at 1920 × 1080 px at a ratio of one. The columns
+ * read the print text size, and the slide reads the slide text size.
+ */
+export declare const CHART_EXPORT_SIZES: {
+    readonly single: {
+        readonly theme: "inflexa-print";
+        readonly textPx: 9.33;
+        readonly widthPx: 336;
+        readonly heightPx: 253;
+        readonly widthMm: 89;
+        readonly heightMm: 67;
+        readonly pixelRatio: number;
+        readonly label: "89 mm";
+    };
+    readonly double: {
+        readonly theme: "inflexa-print";
+        readonly textPx: 9.33;
+        readonly widthPx: 692;
+        readonly heightPx: 348;
+        readonly widthMm: 183;
+        readonly heightMm: 92;
+        readonly pixelRatio: number;
+        readonly label: "183 mm";
+    };
+    readonly slide: {
+        readonly theme: "inflexa-slide";
+        readonly textPx: 24;
+        readonly widthPx: 1920;
+        readonly heightPx: 1080;
+        readonly pixelRatio: 1;
+        readonly label: "16:9";
+    };
+};
+/** The height that each further row of facet panels adds to the chart body, in pixels. */
+export declare const FACET_ROW_PX = 360;
+/** The largest chart body, in pixels. A figure of more rows than this height holds hides a name that overlaps its neighbor. */
+export declare const CHART_BODY_MAX_PX = 1480;
+/**
+ * The width of the chart body on a page at a window 1280 pixels wide, in pixels. A derivation that fits its
+ * category labels to the page measures them against this width.
+ */
+export declare const CHART_PAGE_WIDTH_PX = 900;
+/** The largest height of a journal figure: 170 mm, the full page depth of the Nature guide. */
+export declare const CHART_EXPORT_MAX_HEIGHT_MM = 170;
+/**
+ * The export size of a chart whose body is taller than the default body.
+ *
+ * A column export keeps its width, and its height grows in the ratio of the body to the default body, thus a
+ * row of the figure keeps its share of the height in the export. The height stops at the journal maximum. A
+ * slide keeps its 16:9 box, and a chart of the default body keeps each size.
+ */
+export declare function exportSizeFor(size: ChartExportSize, bodyPx: number): ChartExportSize;
+/**
+ * The near-black ink of a chart: the text, the two axis lines, and the stroke of an interval.
+ *
+ * A journal figure draws its frame and its text in one dark ink, thus the page and the export read alike.
+ */
+export declare const CHART_INK = "#222222";
+/**
+ * The categorical palette of a chart: the Okabe-Ito set, in the order blue, vermilion, bluish green,
+ * orange, reddish purple, sky blue, yellow, and black.
+ *
+ * The set is public and colorblind-safe: no two hues differ by a red-green difference alone. A series that
+ * names no color takes the next hue of this order.
+ */
+export declare const CHART_PALETTE: readonly ["#0072b2", "#d55e00", "#009e73", "#e69f00", "#cc79a7", "#56b4e9", "#f0e442", "#000000"];
+/**
+ * The categorical palette of a chart that draws more than eight categories: the eight hues of the Okabe-Ito
+ * set in their order, then sixteen more hues. Each hue differs from its neighbors in hue or in lightness, and
+ * no hue is near white. The order is fixed, thus one category count gives one set of colors on every chart.
+ *
+ * Past eight categories no palette stays safe for each color-vision deficiency, thus the colors carry the
+ * categories and the legend names them.
+ */
+export declare const CHART_WIDE_PALETTE: readonly ["#0072b2", "#d55e00", "#009e73", "#e69f00", "#cc79a7", "#56b4e9", "#f0e442", "#000000", "#875692", "#8db600", "#be0032", "#a1caf1", "#882d17", "#17becf", "#f99379", "#604e97", "#dcd300", "#b3446c", "#2b3d26", "#e68fac", "#654522", "#c2b280", "#e7298a", "#7fc97f"];
+/**
+ * The stroke of a guide line: a thin gray dash. A guide is a reference and never a plotted value, thus it
+ * reads behind the data.
+ */
+export declare const GUIDE_LINE_COLOR = "#8c8c8c";
+export declare const GUIDE_LINE_WIDTH_PX = 1;
+/** The one focus color of a chart. It is the first hue of the palette, thus a focus reads as the lead series. */
+export declare const FOCUS_CHART_COLOR: "#0072b2";
+/**
+ * The sequential ramp of a continuous color: the ten stops of viridis, dark to light. A continuous scale maps
+ * the low value to `#440154` and the high value to `#fde725`.
+ */
+export declare const SEQUENTIAL_RAMP: readonly ["#440154", "#482777", "#3e4989", "#31688e", "#26828e", "#1f9e89", "#35b779", "#6ece58", "#b5de2b", "#fde725"];
+/**
+ * The diverging ramp of a continuous color: the palette blue through a near-white to the palette vermilion.
+ * The derivation centers the ramp on zero, thus the near-white stop marks no change.
+ */
+export declare const DIVERGING_RAMP: readonly ["#0072b2", "#f7f7f7", "#d55e00"];
+/** The smallest and the largest symbol of a `size` channel, in pixels. */
+export declare const SIZE_CHANNEL_RANGE_PX: readonly [6, 24];
+/**
+ * The band at the right edge of a chart that a continuous color scale takes, in percent of the width. The plot
+ * leaves the band free, and the title of the scale in an export wraps into it.
+ */
+export declare const COLOR_SCALE_BAND_PCT = 18;
+/**
+ * The largest count of slots of one chart, where a slot is one pair of a category and a group. A stacked form,
+ * a radar, a violin, and a heatmap lay out one slot for each pair, thus the bound holds their grids to a size
+ * that a reader reads and that the render holds in memory.
+ */
+export declare const CHART_SLOT_LIMIT = 100000;
+/**
+ * The largest count of bars that carry a value label, counted across the series of one chart.
+ *
+ * A label on each of a few bars reads as the exact value beside the bar. Past this count the labels crowd
+ * each other, and the axis reads better alone.
+ */
+export declare const BAR_VALUE_LABEL_LIMIT = 12;
+/**
+ * The largest count of facet panels of one chart, and the count of panels in one row.
+ *
+ * A small multiple compares its panels at a glance. Past twelve panels each panel is too small to read, and
+ * a derived table of fewer groups serves the reader better.
+ */
+export declare const FACET_PANEL_LIMIT = 12;
+export declare const FACET_COLUMNS = 3;
 /**
  * The muted chart color, beside the palette of the theme.
  *
@@ -122,12 +282,19 @@ export declare const SCATTER_CROWD_OPACITY = 0.5;
  */
 export declare const CHART_INLINE_OPTION_BOUND = 100000;
 /**
- * The ECharts theme as a plain object. The renderer serializes this object and registers it, thus the theme
- * never rides a JSON file and no run-time read is necessary. The palette and the axis styles mirror the
- * light design tokens above.
+ * The publication theme of a chart, at one text size.
+ *
+ * The page and the export read one theme, thus a chart on the page is the chart that the paper gets. The
+ * left and the bottom axis lines are strong and dark, with ticks outside the plot. There is no grid line, no
+ * frame around the legend, and no toolbox, because the chart card adds the toolbox of the page and a file carries
+ * none. The text reads in the journal sans stack and in the near-black ink.
+ *
+ * The chart runtime reads the style of an axis by its type, thus each of the four axis types carries the same
+ * style. The text size scales the text alone: the page, the print export, and the slide export each register
+ * one theme.
  */
-export declare const ECHARTS_THEME: {
-    color: string[];
+export declare function chartTheme(textPx: number): {
+    color: ("#0072b2" | "#d55e00" | "#009e73" | "#e69f00" | "#cc79a7" | "#56b4e9" | "#f0e442" | "#000000")[];
     backgroundColor: string;
     textStyle: {
         fontFamily: string;
@@ -139,7 +306,9 @@ export declare const ECHARTS_THEME: {
     };
     legend: {
         bottom: number;
+        borderWidth: number;
         textStyle: {
+            fontFamily: string;
             fontSize: number;
             color: string;
         };
@@ -163,28 +332,209 @@ export declare const ECHARTS_THEME: {
         };
         extraCssText: string;
     };
-    toolbox: {
-        feature: {
-            saveAsImage: {
-                title: string;
-                pixelRatio: number;
+    categoryAxis: {
+        axisLine: {
+            show: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisTick: {
+            show: boolean;
+            inside: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+        };
+        splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
+    };
+    valueAxis: {
+        axisLine: {
+            onZero: boolean;
+            show: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisTick: {
+            show: boolean;
+            inside: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+        };
+        splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
+    };
+    logAxis: {
+        axisLine: {
+            onZero: boolean;
+            show: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisTick: {
+            show: boolean;
+            inside: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+        };
+        splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
+    };
+    timeAxis: {
+        axisLine: {
+            onZero: boolean;
+            show: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
             };
         };
-        iconStyle: {
-            borderColor: string;
+        axisTick: {
+            show: boolean;
+            inside: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
         };
+        splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
+    };
+    visualMap: {
+        textStyle: {
+            fontFamily: string;
+            fontSize: number;
+            color: string;
+        };
+    };
+    radar: {
+        axisName: {
+            color: string;
+            fontSize: number;
+        };
+        axisLine: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        splitLine: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        splitArea: {
+            show: boolean;
+        };
+    };
+};
+/**
+ * The colors and the font of the toolbox of a page chart: a quiet icon, the primary accent on hover, and the mono
+ * face of the card title for the title of an icon.
+ */
+export declare const CHART_TOOLBOX_ICON_COLOR: "#64748b";
+export declare const CHART_TOOLBOX_ACTIVE_COLOR: "#576dea";
+export declare const CHART_TOOLBOX_FONT: "\"IBM Plex Mono\", ui-monospace, monospace";
+/** The theme that the page registers under `ECHARTS_THEME_NAME`, at the page text size. */
+export declare const ECHARTS_THEME: {
+    color: ("#0072b2" | "#d55e00" | "#009e73" | "#e69f00" | "#cc79a7" | "#56b4e9" | "#f0e442" | "#000000")[];
+    backgroundColor: string;
+    textStyle: {
+        fontFamily: string;
+        fontSize: number;
+        color: string;
+    };
+    title: {
+        show: boolean;
+    };
+    legend: {
+        bottom: number;
+        borderWidth: number;
+        textStyle: {
+            fontFamily: string;
+            fontSize: number;
+            color: string;
+        };
+        itemGap: number;
+        itemWidth: number;
+        itemHeight: number;
+    };
+    grid: {
+        left: number;
         right: number;
         top: number;
+        bottom: number;
+        containLabel: boolean;
+    };
+    tooltip: {
+        backgroundColor: string;
+        borderColor: string;
+        textStyle: {
+            color: string;
+            fontSize: number;
+        };
+        extraCssText: string;
     };
-    xAxis: {
+    categoryAxis: {
         axisLine: {
+            show: boolean;
             lineStyle: {
                 color: string;
+                width: number;
             };
         };
         axisTick: {
+            show: boolean;
+            inside: boolean;
             lineStyle: {
                 color: string;
+                width: number;
             };
         };
         axisLabel: {
@@ -192,28 +542,138 @@ export declare const ECHARTS_THEME: {
             fontSize: number;
         };
         splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
+    };
+    valueAxis: {
+        axisLine: {
+            onZero: boolean;
+            show: boolean;
             lineStyle: {
                 color: string;
-                type: string;
+                width: number;
             };
         };
+        axisTick: {
+            show: boolean;
+            inside: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+        };
+        splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
     };
-    yAxis: {
+    logAxis: {
         axisLine: {
+            onZero: boolean;
             show: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
         };
         axisTick: {
             show: boolean;
+            inside: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
         };
         axisLabel: {
             color: string;
             fontSize: number;
         };
         splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
+    };
+    timeAxis: {
+        axisLine: {
+            onZero: boolean;
+            show: boolean;
+            lineStyle: {
+                color: string;
+                width: number;
+            };
+        };
+        axisTick: {
+            show: boolean;
+            inside: boolean;
             lineStyle: {
                 color: string;
-                type: string;
+                width: number;
             };
         };
+        axisLabel: {
+            color: string;
+            fontSize: number;
+        };
+        splitLine: {
+            show: boolean;
+        };
+        nameTextStyle: {
+            color: string;
+            fontSize: number;
+        };
+    };
+    visualMap: {
+        textStyle: {
+            fontFamily: string;
+            fontSize: number;
+            color: string;
+        };
+    };
+    radar: {
+        axisName: {
+            color: string;
+            fontSize: number;
+        };
+        axisLine: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        splitLine: {
+            lineStyle: {
+                color: string;
+            };
+        };
+        splitArea: {
+            show: boolean;
+        };
     };
 };
+/**
+ * The registered themes: the page theme, the print theme of the SVG and the column PNG, and the slide theme.
+ * The registration script writes each one, and the export reads one by its name.
+ */
+export declare const CHART_THEMES: readonly [{
+    readonly name: "inflexa";
+    readonly textPx: 12;
+}, {
+    readonly name: "inflexa-print";
+    readonly textPx: 9.33;
+}, {
+    readonly name: "inflexa-slide";
+    readonly textPx: 24;
+}];