@fasl-work/caos-app-shell 0.17.0 → 0.19.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,29 @@
 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 './tokens-BvU9bFPw.js';
+export { r as referenceLineName, a as repeatedLabels } from './tokens-BvU9bFPw.js';
+import { B as BiText, L as Lang } from './text-BlY47nIt.js';
 import 'zustand';
 
+/**
+ * The pure rules of the interactions every shell chart carries (Tier A of the interactive-visualization rubric, shell 0.19.0):
+ * zoom and pan of a range, the keys of the keyboard model, the window of categories a bar chart shows, the text a screen
+ * reader gets, and the thinning of a long table. Nothing here touches the DOM, so each rule is tested in node.
+ */
+
+/** A placed mark label, in device pixels: the box its text occupies (`y1` is the baseline). */
+interface LabelBox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+
 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)[];
@@ -20,6 +39,14 @@ interface ChartSeries {
      * 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). */
@@ -46,6 +73,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;
@@ -58,10 +96,10 @@ 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;
     }[];
@@ -88,7 +126,49 @@ 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 chart's accessible name and the name of its data table (0.19.0); by default the y axis by the x axis. */
+    title?: BiText;
+    /** Zoom and pan the y axis too (0.19.0): the wheel, the pinch, the brush and the keys then work on both axes (a parity plot
+     * always does, its two axes share one range). Off by default: x zooms and y follows the visible data. */
+    zoomY?: boolean;
+    /** Turn zoom, pan and the brush off (0.19.0), with the reason, in both languages when the page is bilingual (a chart whose
+     * range is the finding). It names a reason of at least 12 characters, or the gate fails it; the gate lists every chart that
+     * sets it. The keyboard crosshair, the readout, the data table and the summary cannot be turned off. */
+    zoomOff?: BiText;
 }
+/** 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). */
@@ -149,14 +229,22 @@ declare function overlayExtent(series: readonly ChartSeries[], positiveX?: boole
     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;
+/** A placed mark label, in device pixels: its box (`y1` is the baseline), the kind of mark, the text drawn and the whole text it stands for. */
+interface MarkBox extends LabelBox {
+    kind: 'x' | 'y';
+    text: string;
+    full: string;
+}
 /**
  * The vertical marks of a chart and their labels. Every label is drawn with an explicit alignment (uPlot leaves the
  * context right-aligned after its last axis, so a label meant to start at its line ended there and ran off the plot
  * near the left edge, CAOS_Fragmenta 2026-10-06), on the side of its line where it fits inside the plot, on the next
- * row down when it would overlap the label before it, with a halo in the surface colour so a curve under it does not
+ * row down when it would overlap a label before it, with a halo in the surface colour so a curve under it does not
  * cross its letters. A mark outside the x range is not drawn.
+ *
+ * Since 0.19.0 the labels of x marks and of y marks share one set of boxes (`boxes`, to which `drawYMarks` adds its own first): no x
+ * label lies over a y label or another x label. A label for which no row inside the plot has room is cut with an ellipsis, and one
+ * that fits nowhere is not written; the whole texts of those are returned, and every label placed is added to `boxes`.
  */
 declare function drawMarks(u: uPlot, marks: {
     x: number;
@@ -165,22 +253,24 @@ declare function drawMarks(u: uPlot, marks: {
     color: string;
     halo: string;
     family: string;
-}): void;
+}, boxes?: MarkBox[]): string[];
 /**
  * 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, then to the other side of its line or a row further, and is cut with an ellipsis when no place
+ * clears (`placeYLabel`; `boxes`, when given, collects what is placed, for `drawMarks` to avoid). Returns the whole texts of the labels it cut
+ * or could not write. 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;
     halo: string;
     family: string;
-}): void;
+}, boxes?: MarkBox[]): string[];
 /**
  * The index of the point nearest (left, top) in the plane, over every series, or null when no point has a value.
  * `xs` and every column of `ys` are positions in the same pixels as (left, top); a null position is no point.
@@ -195,8 +285,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, onYMarkChange, 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, title, zoomY, zoomOff }: UPlotChartProps): react.JSX.Element;
 
-export { type ChartAxis, type ChartSeries, LOG_TABLE_FLOOR, UPlotChart, type UPlotChartProps, YMARK_TONE_TOKENS, type YMarkDrag, type YMarkTone, clampMark, decadeOnly, drawMarks, drawYMarks, logDecades, nearestPoint, nudgeMark, overlayExtent, parityBox, 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, seriesStyle, smallestPositive, soloKey, soloStyle, sortOrder, tickLabelAt, tickSplits, tickSteps, xScaleRange };