@tangle-network/charts 0.8.0 → 0.9.1

package/README.md

@@ -177,7 +177,7 @@ type ChartMark = { at: number; label: string; kind: "pass" | "deadline" | "died"
 type ChartBand = { from: number; to: number; label: string; kind: "after-pass" | "idle" | "missing" | "blocked" };
 type TimelineLane = { id: string; label: string; spans: Array<{ start: number; end: number | null; state: string; note?: string }>;
   parent?: string; depth?: number; ticks?: TimelineTick[]; detail?: string[] };
-type TimelineTick = { at: number; outcome: "ok" | "quota" | "rate-limit" | "oom" | "refused" | "aborted" | "other"; note?: string };
+type TimelineTick = { at: number; outcome: "ok" | "quota" | "lost" | "rate-limit" | "oom" | "refused" | "aborted" | "other"; note?: string };
 type MultiplePanel = { id: string; label: string; unit?: string; domain?: [number, number]; points?: TimePoint[];
   missing?: { why: string; detail?: string }; end?: { at: number; kind: ChartMark["kind"]; label?: string }; marks?: ChartMark[] };
 type MeterSegment = { label: string; value: number | null; color?: string; kind?: "measured" | "untraced" };
@@ -197,7 +197,7 @@ The window defaults to the extent of the data (spans, ticks and `now`), so a run
 Pass `start` (the run's start) to show time before the first span.
 
 Lanes form a tree through `parent`: each lane is drawn under its parent with a connector, siblings and roots keep their input order, and `depth` defaults to the parent's depth plus one. A stated depth that disagrees with the parent, a parent that is not a lane and a parent chain that loops are refused.
-`ticks` are recorded attempts, such as driver turns, at the time each ended: ok ticks rise above the bar and failed ticks drop below it in their outcome's colour (quota and rate-limit a light breach tone, oom, refused and other the breach tone, aborted ink), and the lane ends with its counts, `21✓ 250✗`. A lane without `ticks` shows no counts; an empty `ticks` shows `0✓ 0✗`. Ticks of one outcome within 2 px are drawn as one, with the count and the commonest `note` in its hover. An unknown outcome is refused.
+`ticks` are recorded attempts, such as driver turns, at the time each ended: ok ticks rise above the bar and failed ticks drop below it in their outcome's colour from the shared outcome palette (below), and the lane ends with its counts, `21✓ 250✗`. A lane without `ticks` shows no counts; an empty `ticks` shows `0✓ 0✗`. Ticks of one outcome within 2 px are drawn as one, with the count and the commonest `note` in its hover. An unknown outcome is refused.
 A mark with a `lane` is drawn on that lane only (a steer to one agent, a wake of the root) instead of across every lane; a lane that is not in the figure is refused.
 `detail` is the caller's facts about a lane (profile, model, status, attempts, cost, top error), one hover line each on the lane's label and every span, and a column of the lanes table.
 `collapsed` folds the named lanes' subtrees: descendants are hidden, the label gains `+N`, and the folded lane's ticks and counts total its subtree. Passing `collapsed`, even empty, makes each parent lane's label a fold toggle (`data-toggle`, a button with `aria-expanded`); `TimelineView` keeps the fold state and wires the toggles to a click, Enter or Space, returning focus to the toggle.
@@ -213,6 +213,44 @@ A mark with a `lane` is drawn on that lane only (a steer to one agent, a wake of
 
 `node scripts/capture-run-page.mjs [dir]` (after `npm run build`) captures each addition at 1440 px light and 390 px dark; the reviewed images are `docs/screenshots/run-page-*.png`.
 
+### Release checks: the climb and the bar
+
+A play's page asks how close its releases are to the check and to the goal's bar. `timeSeries` and `smallMultiples` draw it from the producer's recorded rows; Charts decides no verdict, comparability or checker.
+
+```ts
+const climb = timeSeries(rows, {
+  x: { label: "release", domain: [-0.5, 16.5], categories: tags.map((tag, at) => ({ at, label: tag })) },
+  y: { label: "check progress", unit: "", domain: [-0.05, 1.06], strip: "no score",
+    ticks: [...stages.map((label, i) => ({ at: i / stages.length, label })), { at: 1, label: "SOLVED" }] },
+  bands: [{ from: 0, to: 16, label: "18b · 5 published, 7 withheld", kind: "group" }],
+  marks: [{ at: 9.5, label: "10.5 h", kind: "event", source: "gap" }, { at: 13.47, label: "v4 · operator amendment 20:52Z", kind: "ruling" }],
+  markers: { circle: "check", diamond: "gate" },
+});
+// rows: one per checker (and run), `colorIndex` 0 for the current checker; points such as
+// { x: 13, y: 1, verdict: "pass", glyph: "check", marker: "circle", count: 3, firstAt, lastAt, annotation: line }
+// { x: 15, y: null, verdict: "unknown", marker: "diamond", label: "6/15", count: 12 }   → the strip, never a height
+```
+
+| Field | Drawn as |
+|---|---|
+| `verdict` | `pass` filled, `fail` outlined, `unknown` dashed; with `y: null`, a square in the strip under the plot (hatched when unknown) |
+| `count`, `firstAt`, `lastAt` | `×n` beside the mark; first and last times in the hover and the table |
+| `comparable` | `false` outlined with `*`, `null` outlined with `?` |
+| `glyph` | `✓` (`check`) or `✕` (`cross`), the only marks in the status tones |
+| `marker`, `label` | the mark's shape, named by the figure's `markers`; a short direct label such as `9/15` |
+| `y.scale`, `y.targets`, `y.ticks` | log10 y; target bands (dashed when `stretch`); caller-named gridlines |
+| `x.categories` | an ordinal axis of weighted columns; points sharing a column are spread across it |
+| `colorIndex` (row) | the checker palette, 0 current; dashes follow the index |
+
+The bar panels share the climb's columns: `smallMultiples(panels, { shared: "x", x: { label, domain, categories }, columns: 2, connect: false, markers })`, each panel with its own `unit`, `format`, `scale: "log"`, `domain` and `targets`. `docs/fixtures/magnetar-play.json` holds the Magnetar play's real 17c, 18b and 19b rows in these shapes (`docs/fixtures/export-magnetar-play.mjs` exports them on the Lab host), and `src/run-page-figures.test.ts` draws them.
+
+Attempt outcomes and checkers have one palette in every view. `OUTCOME_ORDER` is the stack order (ok, quota, lost, rate-limit, oom, refused, aborted, other; an open attempt is hatched, never an outcome); `OUTCOME_COLORS[outcome]` and `checkerColor(index)` return the `var(--chart-outcome-*)` and `var(--chart-checker-*)` tokens `figure.css` defines as `light-dark()` pairs, so they follow the page's `color-scheme`. Aborted and other share the neutral tone and always carry a label. `node scripts/palette-check.mjs <dataviz validate_palette.js>` checks both palettes, adjacent pairs in order, on the light surface and on #161616.
+
+| Play page figure | 1440 light | 390 dark |
+|---|---|---|
+| Climb | ![climb](docs/screenshots/run-page-play-climb-1440-light.png) | ![climb phone](docs/screenshots/run-page-play-climb-390-dark.png) |
+| Against the bar | ![bar](docs/screenshots/run-page-play-bar-1440-light.png) | ![bar phone](docs/screenshots/run-page-play-bar-390-dark.png) |
+
 ### Plots without visible report controls
 
 Use `renderFigure(figure, noteNumber, { presentation: "plot" })` to show the responsive plot alone.

package/dist/figure.css

@@ -310,8 +310,8 @@
 .tgc-tip-bg { fill: var(--chart-ink); }
 .tgc-tip-ink { fill: var(--chart-canvas); }
 
-.tgc-series-line { fill: none; stroke: var(--chart-accent); stroke-width: 2; stroke-linejoin: round; }
-.tgc-series-point, .tgc-series-key { fill: var(--chart-accent); stroke: var(--chart-canvas); stroke-width: 2; }
+.tgc-series-line { fill: none; stroke: var(--tgc-series, var(--chart-accent)); stroke-width: 2; stroke-linejoin: round; }
+.tgc-series-point, .tgc-series-key { fill: var(--tgc-series, var(--chart-accent)); stroke: var(--chart-canvas); stroke-width: 2; }
 
 /* Semantic states stay tied to Brand status tokens. No-data has its own neutral mark. */
 .tgc-heat-pass { fill: color-mix(in srgb, var(--chart-pass, var(--status-running)) 19%, var(--chart-canvas)); stroke: var(--chart-pass, var(--status-running)); stroke-width: .8; }
@@ -389,10 +389,13 @@
 .tgc-lane-toggle:hover .tgc-lane-hit { fill: var(--chart-shade); }
 .tgc-lane-toggle:focus-visible .tgc-lane-hit { stroke: var(--chart-accent); }
 .tgc-tick { stroke-width: 1.5; }
-.tgc-tick-ok { stroke: var(--chart-pass, var(--status-running)); }
-.tgc-tick-quota, .tgc-tick-rate-limit { stroke: color-mix(in srgb, var(--chart-breach, var(--status-error)) 55%, var(--chart-canvas)); }
-.tgc-tick-oom, .tgc-tick-refused, .tgc-tick-other { stroke: var(--chart-breach, var(--status-error)); }
-.tgc-tick-aborted { stroke: var(--chart-ink); }
+.tgc-tick-ok { stroke: var(--chart-outcome-ok); }
+.tgc-tick-quota { stroke: var(--chart-outcome-quota); }
+.tgc-tick-lost { stroke: var(--chart-outcome-lost); }
+.tgc-tick-rate-limit { stroke: var(--chart-outcome-rate-limit); }
+.tgc-tick-oom { stroke: var(--chart-outcome-oom); }
+.tgc-tick-refused { stroke: var(--chart-outcome-refused); }
+.tgc-tick-aborted, .tgc-tick-other { stroke: var(--chart-outcome-neutral); }
 /* Lane labels and counts keep a canvas halo, so rules and ticks under them never strike through the text. */
 .tgc-lane-label, .tgc-count { paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; }
 .tgc-count { fill: var(--chart-ink); }
@@ -404,3 +407,58 @@
 .tgc-view-plot svg { display: block; overflow: visible; }
 .tgc-view-wide svg { width: 100%; height: auto; }
 .tgc-view-narrow svg { max-width: 100%; height: auto; }
+
+/*
+ * One fixed palette for attempt outcomes and check versions in every view (src/outcomes.ts names them). Each is a
+ * light-dark() pair picked by the page's color-scheme. Outcomes pass the dataviz colour-vision checks as adjacent
+ * pairs in stack order (ok, quota, lost, rate-limit, oom, refused) on the light surface and on #161616; checkers pass
+ * as adjacent series (current, then older). `scripts/palette-check.mjs` re-runs the validator. A page may override
+ * any of these properties; :where() keeps them at zero specificity.
+ */
+:where(:root) {
+  --chart-outcome-ok: light-dark(#2a78d6, #3987e5);
+  --chart-outcome-quota: light-dark(#eb6834, #d95926);
+  --chart-outcome-lost: light-dark(#1baf7a, #199e70);
+  --chart-outcome-rate-limit: light-dark(#eda100, #c98500);
+  --chart-outcome-oom: light-dark(#e87ba4, #d55181);
+  --chart-outcome-refused: light-dark(#6250d6, #9085e9);
+  --chart-outcome-neutral: #898781;
+  --chart-checker-0: light-dark(#2a78d6, #3987e5);
+  --chart-checker-1: light-dark(#1baf7a, #199e70);
+  --chart-checker-2: light-dark(#6250d6, #9085e9);
+  --chart-checker-3: light-dark(#eda100, #c98500);
+}
+/* A series drawn in a checker's hue; past the fourth hue it is muted and named by its label. */
+.tgc-checker-0 { --tgc-series: var(--chart-checker-0); }
+.tgc-checker-1 { --tgc-series: var(--chart-checker-1); }
+.tgc-checker-2 { --tgc-series: var(--chart-checker-2); }
+.tgc-checker-3 { --tgc-series: var(--chart-checker-3); }
+.tgc-checker-other { --tgc-series: var(--chart-muted); }
+/* Recorded verdicts: a pass is filled, a fail or an incomparable value is an outline, an undecided one dashed. */
+.tgc-series-point.tgc-point-outline { fill: var(--chart-canvas); stroke: var(--tgc-series, var(--chart-accent)); stroke-width: 1.75; }
+.tgc-series-point.tgc-point-undecided { fill: var(--chart-canvas); stroke: var(--tgc-series, var(--chart-accent)); stroke-width: 1.5; stroke-dasharray: 2 1.5; }
+.tgc-strip-hatch .tgc-hatch { stroke: var(--tgc-series, var(--chart-muted)); }
+.tgc-strip-edge { fill: none; stroke: var(--tgc-series, var(--chart-muted)); stroke-width: 1.25; }
+.tgc-strip-observation:focus-visible { outline: none; }
+.tgc-strip-observation:focus-visible .tgc-series-hit { stroke: var(--chart-ink); stroke-width: 2; }
+.tgc-point-badge { paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; font-family: var(--font-mono, "JetBrains Mono", ui-monospace, monospace); }
+.tgc-point-label { fill: var(--chart-ink-muted); }
+.tgc-glyph-note { fill: var(--chart-ink); font-weight: 600; }
+/* Status colours appear only on these glyphs. */
+.tgc-glyph-check { fill: var(--chart-pass, var(--status-running)); font-weight: 600; }
+.tgc-glyph-cross { fill: var(--chart-breach, var(--status-error)); font-weight: 600; }
+/* Recorded targets sit under the data: a target is a soft band between solid edges, a stretch a dashed outline. */
+.tgc-target-target { fill: color-mix(in srgb, var(--chart-ink) 7%, transparent); }
+.tgc-target-stretch { fill: none; }
+.tgc-target-target-edge, .tgc-target-target.tgc-target-line { stroke: var(--chart-ink-muted); stroke-width: 1; }
+.tgc-target-stretch-edge, .tgc-target-stretch.tgc-target-line { stroke: var(--chart-ink-muted); stroke-width: 1; stroke-dasharray: 4 3; }
+.tgc-target-label { fill: var(--chart-ink-muted); paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; }
+/* Group headers: a labelled bracket above the plot and a light rule at each inner edge. */
+.tgc-group-rule { stroke: var(--chart-ink-muted); stroke-width: 1.5; }
+.tgc-group-edge { stroke: var(--chart-rule); stroke-width: 1; }
+.tgc-group-label { fill: var(--chart-ink); paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; }
+/* The verdict key: glyphs in the neutral ink, so they describe a mark's form, not a series. */
+.tgc-key-mark { stroke-width: 1.5; }
+.tgc-key-filled { fill: var(--chart-ink-muted); stroke: none; }
+.tgc-key-outline { fill: none; stroke: var(--chart-ink-muted); }
+.tgc-key-dashed { fill: none; stroke: var(--chart-ink-muted); stroke-dasharray: 2 1.5; }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Setup, E as isRefusal, S as Refusal, T as TierCounts, _ as Figure, a as TimelineTick, b as MatrixCell, c as ChartBand, d as MarkVerdict, f as BreakdownInput, g as Exclusion, h as Estimate, i as TimelineSpan, l as ChartMark, m as CostBasis, n as TimelineLane, o as timeline, p as ComparisonRow, r as TimelineOptions, s as BandKind, t as TickOutcome, u as MarkKind, v as Interval, w as Tier, x as RateRow, y as IntervalMethod } from "./timeline-CCEJug7n.js";
+import { A as IntervalMethod, C as BreakdownInput, D as Exclusion, E as Estimate, F as Tier, I as TierCounts, L as isRefusal, M as RateRow, N as Refusal, O as Figure, P as Setup, S as YTick, T as CostBasis, _ as MarkVerdict, a as timeline, b as YScale, c as OUTCOME_ORDER, d as PointFields, f as PointGlyph, g as MarkKind, h as ChartMark, i as TimelineTick, j as MatrixCell, k as Interval, l as TickOutcome, m as ChartBand, n as TimelineOptions, o as CHECKER_HUES, p as BandKind, r as TimelineSpan, s as OUTCOME_COLORS, t as TimelineLane, u as checkerColor, v as MarkerShape, w as ComparisonRow, x as YTarget, y as XCategory } from "./timeline-CNHABOS1.js";
 //#region src/block.d.ts
 interface RenderFigureOptions {
   /** Chart uses a closed data disclosure; plot keeps only the SVG and accessible data. */
@@ -185,7 +185,7 @@ interface MetricBarsOptions {
 export declare function metricBars(rows: MetricRow[], o: MetricBarsOptions): Figure | Refusal;
 //#endregion
 //#region src/time-series.d.ts
-interface TimePoint {
+interface TimePoint extends PointFields {
   x: number;
   y: number | null;
   observations?: Observations;
@@ -197,16 +197,32 @@ interface TimeSeriesRow {
   id: string;
   label: string;
   points: TimePoint[];
+  /** Draw this series in checker `colorIndex`'s hue (0 is the current checker); past the fourth hue it is muted. */
+  colorIndex?: number;
 }
 interface TimeSeriesOptions {
   x: {
     label: string;
     domain: [number, number];
+    /**
+     * An ordinal axis: one column per category, its width proportional to `weight`. Every point sits at a category's
+     * `at`; several points may share a column and are spread across it. Marks and bands between categories are placed
+     * between their columns, and a band bound that names a category covers that column.
+     */
+    categories?: XCategory[];
   };
   y: {
     label: string;
     unit: string;
     domain: [number, number];
+    /** `log` places values on a log10 scale and needs a positive domain. Default: linear. */
+    scale?: YScale;
+    /** Caller-named gridlines, such as check stages, in place of evenly spaced values. */
+    ticks?: YTick[];
+    /** Recorded goals drawn under the data: a shaded band (target) or a dashed one (stretch), a line when from equals to. */
+    targets?: YTarget[];
+    /** The label of the strip under the plot that holds verdicts recorded without a value. Default: no value. */
+    strip?: string;
   };
   formatX?: (value: number) => string;
   formatY?: (value: number) => string;
@@ -214,6 +230,8 @@ interface TimeSeriesOptions {
   marks?: ChartMark[];
   /** Recorded shaded spans on the x axis, such as time after the first pass or idle time; `missing` is hatched. */
   bands?: ChartBand[];
+  /** What each point `marker` stands for, such as `{ circle: "check", diamond: "gate" }`, named in the figure's key. */
+  markers?: Partial<Record<MarkerShape, string>>;
   id?: string;
 }
 export declare function timeSeries(rows: TimeSeriesRow[], o: TimeSeriesOptions): Figure | Refusal;
@@ -222,10 +240,19 @@ export declare function timeSeries(rows: TimeSeriesRow[], o: TimeSeriesOptions):
 interface MultiplePanel {
   id: string;
   label: string;
-  /** The panel's recorded unit. Every panel must match the figure's y unit. */
+  /**
+   * The panel's recorded unit. With `shared: "both"` it must match the figure's y unit; with `shared: "x"` each panel
+   * may record its own (a rate, a size, a time), and the figure's y unit is the default for panels that set none.
+   */
   unit?: string;
+  /** `shared: "x"` only: formats this panel's y values in place of the figure's `formatY`. */
+  format?: (value: number) => string;
   /** The panel's own y domain; required when only the x axis is shared. */
   domain?: [number, number];
+  /** `log` places values on a log10 scale and needs a positive domain. Default: linear. */
+  scale?: YScale;
+  /** Recorded goals drawn under the panel's data, such as a paper's bar: a shaded band, dashed for a stretch. */
+  targets?: YTarget[];
   points?: TimePoint[];
   /** The arm produced no data. The panel is hatched and names the reason. */
   missing?: {
@@ -241,9 +268,11 @@ interface MultiplePanel {
   marks?: ChartMark[];
 }
 interface SmallMultiplesOptions {
+  /** `categories` makes x ordinal, as in `timeSeries`: every panel shares the same columns. */
   x: {
     label: string;
     domain: [number, number];
+    categories?: XCategory[];
   };
   y: {
     label: string;
@@ -254,10 +283,16 @@ interface SmallMultiplesOptions {
   shared: "both" | "x";
   /** What one panel is, for the lede: "3 of 4 arms have data". Default: panel. */
   noun?: string;
+  /** Panels per row in the wide render (default 3); the phone render is one column. */
+  columns?: number;
+  /** false draws points without joining them, for values that are not one trajectory. Default true. */
+  connect?: boolean;
+  /** What each point `marker` stands for, such as `{ circle: "check", diamond: "gate" }`, named in the figure's key. */
+  markers?: Partial<Record<MarkerShape, string>>;
   formatX?: (value: number) => string;
   formatY?: (value: number) => string;
   id?: string;
 }
 export declare function smallMultiples(panels: MultiplePanel[], o: SmallMultiplesOptions): Figure | Refusal;
 //#endregion
-export { type BandKind, type BreakdownInput, type BreakdownOptions, type ChartBand, type ChartMark, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type Estimate, type Exclusion, type Figure, type HeatmapCell, type HeatmapColumn, type HeatmapOptions, type HeatmapRow, type HeatmapStatus, type Interval, type IntervalMethod, type LatencyRangeOptions, type LatencyRangeRow, type MarkKind, type MarkVerdict, type MatrixCell, type MetricBarsOptions, type MetricRow, type MultiplePanel, type Observations, type PhaseWaterfallOptions, type RankedRatesOptions, type RateIdentity, type RateRow, type Refusal, type RenderFigureOptions, type Setup, type SmallMultiplesOptions, type TaskMatrixOptions, type TickOutcome, type Tier, type TierCounts, type TimePoint, type TimeSeriesOptions, type TimeSeriesRow, type TimelineLane, type TimelineOptions, type TimelineSpan, type TimelineTick, type WaterfallPhase, isRefusal, timeline };
+export { type BandKind, type BreakdownInput, type BreakdownOptions, CHECKER_HUES, type ChartBand, type ChartMark, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type Estimate, type Exclusion, type Figure, type HeatmapCell, type HeatmapColumn, type HeatmapOptions, type HeatmapRow, type HeatmapStatus, type Interval, type IntervalMethod, type LatencyRangeOptions, type LatencyRangeRow, type MarkKind, type MarkVerdict, type MatrixCell, type MetricBarsOptions, type MetricRow, type MultiplePanel, OUTCOME_COLORS, OUTCOME_ORDER, type Observations, type PhaseWaterfallOptions, type PointFields, type PointGlyph, type RankedRatesOptions, type RateIdentity, type RateRow, type Refusal, type RenderFigureOptions, type Setup, type SmallMultiplesOptions, type TaskMatrixOptions, type TickOutcome, type Tier, type TierCounts, type TimePoint, type TimeSeriesOptions, type TimeSeriesRow, type TimelineLane, type TimelineOptions, type TimelineSpan, type TimelineTick, type WaterfallPhase, type XCategory, type YScale, type YTarget, type YTick, checkerColor, isRefusal, timeline };