@inflexa-ai/harness 0.42.2 → 0.43.1

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

@@ -0,0 +1,124 @@
+/**
+ * The toolbox of a page chart: the download menu, the data view, and the zoom of a dense cartesian chart.
+ *
+ * The derivation gives a figure with no toolbox. The chart card adds the toolbox to the option of the page, and
+ * each export removes it again, thus a file never shows it. The option rides to the page as inline JSON, thus
+ * it holds no function. Each handler of the toolbox is the name of a page function, and the bootstrap binds the
+ * function under that name after the parse, as it registers a named renderer.
+ *
+ * The toolbox holds no `magicType`, because a reader must not change the form that the author chose.
+ */
+import type { ChartType } from "../contracts/report-blocks.js";
+import type { EchartOption } from "./chart.js";
+/**
+ * The chart types that get the zoom and the restore controls: the dense cartesian forms. A reader zooms into a
+ * cloud of many thousands of points to read one region.
+ */
+export declare const DENSE_CARTESIAN_CHARTS: readonly ChartType[];
+/** The page function that opens the download menu of a chart, and the page function that gives the data view. */
+export declare const EXPORT_MENU_FUNCTION = "reportOpenExportMenu";
+export declare const DATA_VIEW_FUNCTION = "reportDataViewContent";
+/**
+ * The members of a toolbox feature that name a page function. The bootstrap replaces each name with its
+ * function, and it removes a name that the page does not hold, because the runtime calls the member.
+ */
+export declare const TOOLBOX_FUNCTION_MEMBERS: readonly ["onclick", "optionToContent"];
+/** The names of the page functions that a toolbox can name. Each one is a function of `CHART_TOOLBOX_SOURCE`. */
+export declare const TOOLBOX_PAGE_FUNCTIONS: readonly ["reportOpenExportMenu", "reportDataViewContent"];
+/** The download icon: an arrow into a tray, as the path of a 24-pixel box. The runtime strokes it in the icon color. */
+export declare const DOWNLOAD_ICON = "path://M12 3L12 15M7 10L12 15L17 10M4 17L4 21L20 21L20 17";
+/**
+ * The canvas layer of the toolbox. The print hides this layer, because a new option draws each series again and
+ * a dense series then draws in chunks over some frames. The runtime gives a dense series a layer of its own and
+ * lifts each later component one layer, thus the toolbox stands far above each layer that the runtime gives.
+ */
+export declare const TOOLBOX_ZLEVEL = 1000;
+/**
+ * The height of the band that the toolbox takes at the top of the chart body, in pixels: the top gap, the
+ * padding over and under the icons, and the box of one outline icon. The derivation gives no toolbox, and no
+ * layer reserves this band, thus a figure that places its own grid keeps its plot and its text under the band.
+ */
+export declare const TOOLBOX_BAND_PX: number;
+/** The attribute of the download control of a card. It holds the id of the container whose menu the control opens. */
+export declare const MENU_CONTROL_ATTRIBUTE = "data-chart-menu";
+/** The class of an open download menu. The design sheet shows a menu with this class, and it hides each other menu. */
+export declare const MENU_OPEN_CLASS = "report-chart-menu-open";
+/** The class of the hidden note that a menu shows when the page cannot build the file of an entry. */
+export declare const MENU_FAULT_CLASS = "report-chart-menu-fault";
+/** The class of a fault note that the page shows. The design sheet hides each other fault note. */
+export declare const MENU_FAULT_SHOWN_CLASS = "report-chart-menu-fault-shown";
+/**
+ * The most rows that the data view shows. A dense chart plots many thousands of points, and a table of each one
+ * costs the page a DOM node for each cell. The note of the view then states the count that it holds back.
+ */
+export declare const DATA_VIEW_ROW_LIMIT = 1000;
+/** The id of the download menu of the chart in one container. */
+export declare function chartMenuId(containerId: string): string;
+/** The id of the download control in the card of the chart in one container. */
+export declare function chartMenuControlId(containerId: string): string;
+/**
+ * The toolbox of one page chart.
+ *
+ * Each chart gets the data view and the download control. A dense cartesian chart also gets the zoom and the
+ * restore controls. A composition names no chart type, thus it gets no zoom. The download control is the last
+ * feature, thus it sits at the right edge and its menu opens under it.
+ */
+export declare function chartToolbox(chartType: ChartType | undefined): EchartOption;
+/** The option of the page: the derived option with the toolbox of its chart type. The derived option stays as it is. */
+export declare function pageChartOption(option: EchartOption, chartType: ChartType | undefined): EchartOption;
+/**
+ * The page function that makes the label formatter of a genome axis, and the member of the axis that it reads.
+ *
+ * A genome axis plots the cumulative position over the chromosomes. At the full range a series names the
+ * chromosomes, and the axis hides its labels. While a zoom of the toolbox narrows the axis, the axis shows each
+ * position as the chromosome and the position on it, and that series hides.
+ */
+export declare const GENOME_POSITION_FUNCTION = "reportGenomePosition";
+export declare const GENOME_MEMBER = "genome";
+/** The genome member of an axis: the series that names the chromosomes, and the start and the label of each chromosome in position order. */
+export interface GenomeAxis {
+    readonly names: string;
+    readonly starts: ReadonlyArray<readonly [number, string]>;
+}
+/**
+ * The page functions of the toolbox, as browser source text.
+ *
+ * `reportOpenExportMenu` is the click handler of the download icon of the toolbox. The runtime calls it with the
+ * model, the API of the chart, the name of the icon, and the event. The runtime draws the icon on the canvas and
+ * binds a mouse click alone, thus the card also carries a download control in its title line. `reportMenuClick`
+ * takes a click on that control, and a button fires a click for the Enter key and the Space key. The two paths
+ * open the menu of the chart under the icon, at the right edge of the chart body, and a second click closes it.
+ * The control states the open menu in `aria-expanded`.
+ *
+ * The menu takes the keyboard: the first entry takes the focus, the arrow keys, `Home`, and `End` move the focus,
+ * and `Escape` closes the menu and gives the focus back to the control of the card. `Tab` closes the menu and puts
+ * the focus on the control, thus the next Tab stop comes after the control. A click outside the menu closes it,
+ * and so does a click on an entry. After an entry fires, the focus goes back to the control.
+ *
+ * The runtime sends the click of the icon on to the document, and that click is outside the menu. Thus the menu
+ * keeps the event that opened it, and the outside test skips that one event. On a touch screen the runtime fires
+ * the click of the icon from the touch end, and the browser then sends its own click to the chart. Thus a menu that
+ * a tap opened also skips the next click inside its chart.
+ *
+ * `reportMenuFault` shows the fault note of the open menu and gives it the focus, when the page cannot build the
+ * file of an entry. The menu then stays open, and the close hides the note again.
+ *
+ * `reportDataViewContent` gives the data view: the plotted rows of each series as one plain table, up to the row
+ * limit. A series that the reader cannot hover, for example the anchors of the point names, holds no data of the
+ * figure, thus the table skips it. A number of a category axis reads as its category. The view builds each cell
+ * as text, thus a hostile name reaches the view as text and never as markup.
+ *
+ * `reportBindToolbox` replaces each function name of the toolbox with its page function. It also replaces the name
+ * of the formatter of each genome axis with the formatter that `reportGenomePosition` makes from the genome member
+ * of the axis. The formatter gives the label of the chromosome that holds the position, and the distance from the
+ * start of that chromosome in megabases.
+ *
+ * `reportWatchZoom` attaches the zoom handler to a chart after its init. The handler reads the window of each
+ * axis after each zoom. The toolbox zoom fixes the ends of a zoomed axis to the ends of the selected box, and the
+ * runtime prints each end of a value axis as a label beside the round labels. Thus a zoomed value axis hides
+ * its two end labels, and a genome axis shows its labels and hides the series that names the chromosomes. That
+ * series draws one point under the middle of each chromosome, and a zoom clips each point outside the window.
+ * At the full range each value goes back to the value of the option. The restore of the toolbox sets the option
+ * of the chart again, thus the handler then starts from the option.
+ */
+export declare const CHART_TOOLBOX_SOURCE: string;