@fasl-work/caos-app-shell 0.16.0 → 0.18.0

package/chart.css

@@ -22,3 +22,8 @@
 .caos-chart.fill[data-parity] > .caos-chart-plot { display: flex; align-items: center; justify-content: center; }
 .caos-chart[data-pick] .u-over { cursor: pointer; }
 .caos-chart .u-cursor-x, .caos-chart .u-cursor-y { border-color: var(--color-fg-faint) !important; }
+/* The key that solos a series (`solo`, 0.18.0): each entry is a button. At rest it reads as the plain key; the soloed one is
+   set off by a border and bold text, in the text colour, never by colour alone. */
+.caos-chart-key-button { display: inline-flex; align-items: center; gap: 0.3rem; min-width: 0; margin: 0; padding: 0.15rem 0.45rem; border: 1px solid transparent; border-radius: 0.4rem; background: none; color: inherit; font: inherit; line-height: inherit; text-align: start; cursor: pointer; }
+.caos-chart-key-button:hover { border-color: var(--color-border); }
+.caos-chart-key-button[aria-pressed="true"] { border-color: var(--color-fg-subtle); color: var(--color-fg); font-weight: 600; }

package/dist/chart.d.ts

@@ -1,10 +1,15 @@
 import * as react from 'react';
 import uPlot from 'uplot';
-import { F as FormatOptions, S as ShellColorToken } from './tokens-BTOzar-U.js';
-import { B as BiText } from './text-BlY47nIt.js';
+import { F as FormatOptions, S as ShellColorToken } from './text-DyQ1A8oo.js';
+export { r as referenceLineName } from './text-DyQ1A8oo.js';
+import { B as BiText, L as Lang } from './text-BlY47nIt.js';
 import 'zustand';
 
 interface ChartSeries {
+    /** What identifies the series to the solo key (0.18.0): the solo follows the series with this id when the list of series
+     * changes (one dropped, one added, a label changed), not its position. Without an id the English label is the key. Unique
+     * within the chart; with two series of one key the first is taken. */
+    id?: string;
     label: BiText;
     /** One value per x; `null` leaves a gap. */
     values: (number | null)[];
@@ -16,6 +21,25 @@ interface ChartSeries {
     mode?: 'line' | 'points';
     /** The marker diameter of a `points` series, in CSS pixels (9 by default): a larger one rings the selected case. */
     size?: number;
+    /** A `points` series on x values of its own (measured cases over a modelled curve that has other sizes): one x per
+     * value. It is drawn over the plot on its own x, outside the curve's data, so it takes no part in the cursor, the
+     * pick or the readout, and the axes take its extent in. */
+    x?: number[];
+    /** A dot at each value of a `line` series (CAOS_Fragmenta drew them under 40 values: `dots={x.length < 40}`). Off by
+     * default; no dot is drawn at a `null`. */
+    dots?: boolean;
+}
+/** A named x tick: the x value it sits at and the text the axis reads there (and the readout, for an x on it). */
+interface ChartTick {
+    value: number;
+    label: BiText;
+}
+/** What a reference line may be dragged over: the range it stays inside, and the step it snaps to (a hundredth of the
+ * range when not given; on a log axis the step is a factor). */
+interface YMarkDrag {
+    min: number;
+    max: number;
+    step?: number;
 }
 interface ChartAxis {
     label: BiText;
@@ -35,6 +59,17 @@ interface UPlotChartProps {
         values: number[];
         time?: boolean;
         log?: boolean;
+        /** Named ticks (0.18.0): the axis ticks exactly at these values, no other, each labelled with its text in the page
+         * language (a categorical axis: protocols, blast ids). The readout names an x that sits on one by its label. A tick
+         * outside the range is not drawn; an empty list leaves uPlot its own ticks. A value listed twice keeps its first label.
+         * Labels must be different from each other, adjacent or not (the gate fails any repeated label, G6). An x is on a tick
+         * when it is within 1e-9 of the x span of it. Ignored on a time axis. */
+        ticks?: ChartTick[];
+        /** The x scale spans at least this range (0.18.0), as `y.range` fixes the y scale: widen it past the data so an end tick's
+         * label is not cut by the plot edge. The data and the overlays still widen it further. On a log axis a range that reaches 0
+         * or below is ignored (the overlays still widen the scale); on a parity chart it is ignored, the chart's own shared range
+         * rules. */
+        range?: [number, number];
     };
     y: ChartAxis & {
         log?: boolean;
@@ -47,12 +82,17 @@ interface UPlotChartProps {
         label: BiText;
     }[];
     /** Horizontal reference lines at y values, labelled at their right end (a null model's constant prediction, a
-     * target, a limit). */
+     * target, a limit). A line without a `label` is drawn with no label box and nothing reserved for one (a zero line). */
     yMarks?: {
         y: number;
-        label: BiText;
+        label?: BiText;
         tone?: YMarkTone;
+        drag?: YMarkDrag;
     }[];
+    /** Called with the index in `yMarks` and the new y of a draggable reference line (`drag`) every time the reader moves
+     * it, by the pointer or the keyboard (a slider on the line: arrows, Page keys, Home and End); the caller sets the new
+     * y in `yMarks`. */
+    onYMarkChange?: (index: number, y: number) => void;
     /** Height in pixels, or `fill` to take the container's height (inside `PlotCard fill`); the width is always the
      * container's. */
     height?: number | 'fill';
@@ -72,7 +112,40 @@ interface UPlotChartProps {
     readout?: (index: number) => string;
     /** The readout at rest; by default "Hover the chart to read the values". */
     hint?: BiText;
+    /** The key solos a series (0.18.0): each entry is a button (`aria-pressed`, Tab, click, Enter or Space) that dims every
+     * other series (alpha 0.12, 1 px) and leaves the chosen one as drawn; pressing it again releases it, pressing another
+     * moves the solo. The chart is redrawn, not rebuilt. A chart of one series shows the key too. Off by default. */
+    solo?: boolean;
 }
+/** The alpha a series takes when another one is soloed (0.18.0; what CAOS_Fragmenta's key did). */
+declare const SOLO_DIM_ALPHA = 0.12;
+/** How a series is drawn while `solo` (the index in `series` of the soloed one, or null) is held: as given, or dimmed to
+ * `SOLO_DIM_ALPHA` and 1 px when another is soloed. Dimmed, never hidden, so the reader keeps the context. */
+declare function soloStyle(solo: number | null, i: number, width: number): {
+    alpha: number;
+    width: number;
+};
+/** The values a named x axis ticks at inside [min, max]: ascending, each once; on a log axis only the ones above 0. A value
+ * that is not a number is dropped. */
+declare function tickSplits(ticks: readonly ChartTick[], min: number, max: number, log?: boolean): number[];
+/** The label of the named tick at an x, in the page language; null when no tick sits there. An x is on a tick when it is
+ * within 1e-9 of `span` (the x span, as `tickSplits` takes the range) of its value, so 0.1 + 0.2 is on a tick at 0.3; without
+ * a span only an equal x is. A value listed twice keeps its first label. */
+declare function tickLabelAt(ticks: readonly ChartTick[] | undefined, x: number, lang: Lang, span?: number): string | null;
+/** How many of the labels of named ticks repeat another's, adjacent or not (the gate's check of numeric ticks counts only
+ * neighbours, and on a categorical axis order means nothing), and which ones; an empty label is no label. */
+declare function namedRepeats(labels: readonly string[]): {
+    n: number;
+    names: string[];
+};
+/** What a series is known by to the solo key: its id, else its English label. */
+declare function soloKey(s: ChartSeries): string;
+/** The x scale of a chart whose x range is fixed, or whose overlays reach past the curve: the data's extent widened by the
+ * given range and by the overlays' x; null when none is given (uPlot's own range), and on a log axis when the data would reach 0.
+ * One x alone gets a unit either side, a decade on a log axis. `xs` is sorted ascending. */
+declare function xScaleRange(xs: readonly number[], ext: {
+    x: [number, number];
+} | null, range: readonly [number, number] | undefined, log: boolean): [number, number] | null;
 /** The colour and dash of a series: its own, or the rotation's; when the rotation comes round (a seventh series
  * repeats the first colour) the repeat is dashed, so two series never look the same (CAOS_Fragmenta drew this for
  * itself until 0.9.0). */
@@ -110,6 +183,29 @@ declare const LOG_TABLE_FLOOR = 1e-22;
 declare function logDecades(min: number, max: number, most?: number): number[];
 /** The smallest positive value among columns of values and the lower end of a fixed range; Infinity if none. */
 declare function smallestPositive(columns: readonly (readonly (number | null)[])[], range?: readonly [number, number] | null): number;
+/**
+ * The ticks of a log x axis that get a label: the powers of ten only (null for every other tick, which formatTicks leaves
+ * blank). A range with no power of ten in it keeps its ticks, so the axis is never left without a label.
+ */
+declare function decadeOnly(ticks: readonly (number | null)[]): (number | null)[];
+/** The side of the square box of a parity plot: the smaller of the box's width and the height asked for (the box's
+ * height when the chart fills it). */
+declare function parityBox(boxWidth: number, boxHeight: number, height: number, fill: boolean): number;
+/** A dragged value kept inside the range of its line and snapped to its step; a value that is not a number falls to the
+ * lower end. */
+declare function clampMark(y: number, drag: YMarkDrag): number;
+/**
+ * The value a key sets on a draggable line, or null for a key it does not handle: the arrows one step, Page Up and Down
+ * ten, Home and End the ends of the range. A step is a hundredth of the range, or `drag.step`; on a log axis it is a factor
+ * (a hundredth of the range in decades) and `drag.step` is not used.
+ */
+declare function nudgeMark(y: number, key: string, drag: YMarkDrag, log?: boolean): number | null;
+/** The x and y extent of the series that bring an x of their own, finite points only (on a log x axis, `positiveX`,
+ * only the points with x above 0); null when there are none. */
+declare function overlayExtent(series: readonly ChartSeries[], positiveX?: boolean): {
+    x: [number, number];
+    y: [number, number];
+} | null;
 /** How many tick labels repeat the label before them (empty labels apart); the gate fails a chart with any (G6). */
 declare function repeatedLabels(labels: readonly (string | null | undefined)[]): number;
 /**
@@ -130,12 +226,12 @@ declare function drawMarks(u: uPlot, marks: {
 /**
  * The horizontal reference lines of a chart and their labels: a dashed line across the plot, its label at the right
  * end above the line (below it when the line runs along the top), inside the plot, haloed; a label that would overlap
- * the one placed before it moves left of it. A line outside the y range is not drawn. A mark's `color` (the tone's) draws
+ * the one placed before it moves left of it. A line outside the y range is not drawn; a line without a label is drawn alone. A mark's `color` (the tone's) draws
  * its line and its label; without one `style.color` does.
  */
 declare function drawYMarks(u: uPlot, marks: {
     y: number;
-    label: string;
+    label?: string;
     color?: string;
 }[], style: {
     color: string;
@@ -156,8 +252,10 @@ declare function nearestPoint(xs: readonly number[], ys: readonly (readonly (num
  * uPlot's legend, which a sized host clips (known shell defect 3). A chart of two or more series keys every series
  * under the plot, always (its colour, a dashed or a dotted swatch, its label): at rest the readout names none of them
  * (known shell defect 17). An axis with fixed decimals ticks only where its labels differ (`tickSteps`). The host
- * declares `data-series`, `data-axis-titles`, `data-ticks-cut`, `data-ticks-repeat` and `data-drawn` for the gate.
+ * declares `data-series`, `data-axis-titles`, `data-ticks-cut`, `data-ticks-repeat` and `data-drawn` for the gate. Since
+ * 0.18.0: named x ticks (`x.ticks`, declared in `data-x-tick-labels`), an x range (`x.range`), a key that solos a series
+ * (`solo`, declared in `data-solo`), dots on a line (`ChartSeries.dots`) and reference lines without a label.
  */
-declare function UPlotChart({ x, y, series, marks, yMarks, height, onCursor, onPick, parity, readout, hint }: UPlotChartProps): react.JSX.Element;
+declare function UPlotChart({ x, y, series, marks, yMarks, onYMarkChange, height, onCursor, onPick, parity, readout, hint, solo }: UPlotChartProps): react.JSX.Element;
 
-export { type ChartAxis, type ChartSeries, LOG_TABLE_FLOOR, UPlotChart, type UPlotChartProps, YMARK_TONE_TOKENS, type YMarkTone, drawMarks, drawYMarks, logDecades, nearestPoint, parityRange, rangeWithLevels, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };
+export { type ChartAxis, type ChartSeries, type ChartTick, LOG_TABLE_FLOOR, SOLO_DIM_ALPHA, UPlotChart, type UPlotChartProps, YMARK_TONE_TOKENS, type YMarkDrag, type YMarkTone, clampMark, decadeOnly, drawMarks, drawYMarks, logDecades, namedRepeats, nearestPoint, nudgeMark, overlayExtent, parityBox, parityRange, rangeWithLevels, repeatedLabels, seriesStyle, smallestPositive, soloKey, soloStyle, sortOrder, tickLabelAt, tickSplits, tickSteps, xScaleRange };