@tangle-network/charts 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tangle Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,6 +15,14 @@ The library draws and never decides.
 Ranks, intervals, frontier membership, estimate labels and pass counts come from the producer: a board record, a VerticalBench report or an agent-eval lens.
 A figure function returns a `Refusal` in place of a figure it cannot draw honestly, for example a bar over too few units, an interval that names no method, or a frontier the producer did not compute.
 
+The producer's `estimate` controls rate marks: `descriptive` draws a rate bar and may show a named Wilson score interval when that estimate meets the producer's unit threshold.
+Task-clustered bootstrap intervals require a `bootstrap` estimate.
+Intervals without support are marked as not drawn in the data table and note.
+A missing, zero, or unproven cost prints `unknown`; zero passes print `no pass`.
+Rank numbers require every row to carry both a rank and a `bootstrap` estimate.
+Malformed rates, intervals, matrix counts, and breakdown counts return a refusal instead of a misleading mark.
+An interval whisker is omitted when its bounds exclude the row's rate.
+
 It has no runtime dependencies and uses no DOM, so it runs in a Worker, a build step or a browser.
 
 ## Use
@@ -55,5 +63,4 @@ pnpm --filter @tangle-network/charts build     # fails when src/css.generated.ts
 
 ## Release
 
-The package is private until its first npm publish.
-npm trusted publishing needs the package to exist before a trusted publisher can be added, so the first version is published once by an owner, then `npm trust github @tangle-network/charts --file release.yml --repo tangle-network/brand --allow-publish` hands later versions to the release workflow.
+Versions publish from the brand release workflow through npm trusted publishing, like `@tangle-network/brand` and `@tangle-network/ui`.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+//#region src/types.d.ts
 /**
  * Inputs and outputs of the figure functions.
  *
@@ -15,10 +16,10 @@ type IntervalMethod = "task-cluster-bootstrap" | "mcnemar-exact" | "wilson";
  * interval that does not name both.
  */
 interface Interval {
-    lower: number;
-    upper: number;
-    level: number | null;
-    method: IntervalMethod | null;
+  lower: number;
+  upper: number;
+  level: number | null;
+  method: IntervalMethod | null;
 }
 /** The App Grade ladder, lowest first. U (unable to measure) is not on it. */
 type Tier = "F" | "C" | "B" | "A" | "S";
@@ -27,255 +28,187 @@ type TierCounts = Record<Tier, number>;
 type CostBasis = "receipts" | "estimated" | "unknown";
 /** A column or row identity: an AgentProfile, a model, a judge, a search node. */
 interface Setup {
-    id: string;
-    label: string;
-    /** Null when the order is a sort, not a ranking backed by comparisons. */
-    rank: number | null;
+  id: string;
+  label: string;
+  /** Null when the order is a sort, not a ranking backed by comparisons. */
+  rank: number | null;
 }
 /** One setup's rate. Field names follow the board record's `BoardProfile`. */
 interface RateRow extends Setup {
-    solved: number;
-    attempts: number;
-    rate: number;
-    /** The producer's label for what `attempts` supports; the library holds no threshold. */
-    estimate: Estimate;
-    interval: Interval | null;
-    tiers: TierCounts | null;
-    cost: {
-        perSolvedUsd: number | null;
-        basis: CostBasis;
-        receipts: number | null;
-    };
-    medianWallMs: number | null;
-    /** Null when the producer computed no frontier. */
-    onFront: boolean | null;
+  solved: number;
+  attempts: number;
+  rate: number;
+  /** The producer's label for what `attempts` supports; the library holds no threshold. */
+  estimate: Estimate;
+  interval: Interval | null;
+  tiers: TierCounts | null;
+  cost: {
+    perSolvedUsd: number | null;
+    basis: CostBasis;
+    receipts: number | null;
+  };
+  medianWallMs: number | null;
+  /** Null when the producer computed no frontier. */
+  onFront: boolean | null;
 }
 /** One task × setup cell. */
 interface MatrixCell {
-    task: string;
-    setup: string;
-    /** Attempts that count; null when the cell never ran. */
-    attempts: number | null;
-    /** Attempts that passed; null when no pass rule applies. */
-    solved: number | null;
-    /** Attempts graded on the App Grade ladder. */
-    tiers: TierCounts | null;
-    /** Attempts graded U: no floor check failed, but one could not be observed. */
-    unmeasured?: number;
-    /** Attempts whose grade failed an integrity check and awaits human review. */
-    flagged?: number;
-    /** A lens cell's mean score; null when the setup never scored the task. */
-    mean: number | null;
-    costUsd: number | null;
+  task: string;
+  setup: string;
+  /** Attempts that count; null when the cell never ran. */
+  attempts: number | null;
+  /** Attempts that passed; null when no pass rule applies. */
+  solved: number | null;
+  /** Attempts graded on the App Grade ladder. */
+  tiers: TierCounts | null;
+  /** Attempts graded U: no floor check failed, but one could not be observed. */
+  unmeasured?: number;
+  /** Attempts whose grade failed an integrity check and awaits human review. */
+  flagged?: number;
+  /** A lens cell's mean score; null when the setup never scored the task. */
+  mean: number | null;
+  costUsd: number | null;
 }
 interface ComparisonRow {
-    /** Setup ids. */
-    favored: string;
-    other: string;
-    pairs: number | null;
-    minimumEffect: number | null;
-    /** The clustered interval on the difference, in the measure's units. */
-    interval: Interval | null;
-    /** The exact interval, drawn under the clustered one when present. */
-    exactInterval: Interval | null;
+  /** Setup ids. */
+  favored: string;
+  other: string;
+  pairs: number | null;
+  minimumEffect: number | null;
+  /** The clustered interval on the difference, in the measure's units. */
+  interval: Interval | null;
+  /** The exact interval, drawn under the clustered one when present. */
+  exactInterval: Interval | null;
 }
 interface BreakdownInput {
-    reasons: string[];
-    setups: Array<{
-        id: string;
-        label: string;
-        n: number | null;
-    }>;
-    counts: Array<{
-        reason: string;
-        setup: string;
-        count: number | null;
-    }>;
-    excluded: {
-        count: number;
-        why: string;
-    } | null;
-    /** True when one attempt can count under several reasons. */
-    overlapping?: boolean;
+  reasons: string[];
+  setups: Array<{
+    id: string;
+    label: string;
+    n: number | null;
+  }>;
+  counts: Array<{
+    reason: string;
+    setup: string;
+    count: number | null;
+  }>;
+  excluded: {
+    count: number;
+    why: string;
+  } | null;
+  /** True when one attempt can count under several reasons. */
+  overlapping?: boolean;
 }
 /** Attempts left out of a figure, stated in its note. */
 interface Exclusion {
-    count: number;
-    why: string;
+  count: number;
+  why: string;
 }
 interface Figure {
-    id: string;
-    /** Generated from the input; no function accepts heading text. */
-    finding: string;
-    /** One quantified sentence. */
-    lede: string;
-    /** How to read the marks. */
-    read: string;
-    /** 720 px and 358 px renders; a null narrow render means the table is the phone view. */
-    svg: {
-        wide: string;
-        narrow: string | null;
-    };
-    /** An HTML table with every number the plot shows. */
-    table: string;
-    note: {
-        method: string;
-        n: string;
-        exclusions: string[];
-    };
+  id: string;
+  /** Generated from the input; no function accepts heading text. */
+  finding: string;
+  /** One quantified sentence. */
+  lede: string;
+  /** How to read the marks. */
+  read: string;
+  /** 720 px and 358 px renders; a null narrow render means the table is the phone view. */
+  svg: {
+    wide: string;
+    narrow: string | null;
+  };
+  /** An HTML table with every number the plot shows. */
+  table: string;
+  note: {
+    method: string;
+    n: string;
+    exclusions: string[];
+  };
 }
 interface Refusal {
-    id: string;
-    refused: string;
+  id: string;
+  refused: string;
 }
-declare function isRefusal(value: Figure | Refusal): value is Refusal;
-
-/**
- * The figure block: one markup for every figure on every surface.
- *
- * In order: the finding as a heading with a note reference, a one-sentence
- * lede, the plot (both widths, swapped by `figure.css` on the figure's own
- * width), a reading line, and the data table in a disclosure. Notes render
- * once per page, numbered, each with a way back to its figure.
- */
-
-declare function renderFigure(f: Figure, noteNumber: number): string;
+export declare function isRefusal(value: Figure | Refusal): value is Refusal;
+//#endregion
+//#region src/block.d.ts
+export declare function renderFigure(f: Figure, noteNumber: number): string;
 /** Numbered notes for `figures`, in the order their blocks were numbered (1-based). */
-declare function renderNotes(figures: Figure[]): string;
+export declare function renderNotes(figures: Figure[]): string;
 /** What a page leaves out, and why. */
-declare function renderRefusals(refusals: Refusal[]): string;
-
-/**
- * `breakdown`: why attempts fail.
- *
- * Rows are reasons (a failure layer, cause or check); columns are setups with
- * `n=` under each name. Each cell prints its count over a neutral tint of
- * count / n, capped at 50% so ink keeps its contrast. The accent never marks a
- * failure. On a phone the table is the view.
- *
- * Refuses: a share without its column n (the count prints with no tint);
- * counting excluded attempts (they are stated in the note); hiding a zero.
- */
-
+export declare function renderRefusals(refusals: Refusal[]): string;
+//#endregion
+//#region src/breakdown.d.ts
 interface BreakdownOptions {
-    /** What a row counts, lower case: "failed checks". */
-    measure: string;
-    id?: string;
+  /** What a row counts, lower case: "failed checks". */
+  measure: string;
+  id?: string;
 }
-declare function breakdown(input: BreakdownInput, o: BreakdownOptions): Figure | Refusal;
-
-/**
- * `comparisonIntervals`: is each step in an order real.
- *
- * One row per comparison, "{favored} over {other}", with the pair count. x is
- * the difference in points with a muted zero line. The clustered interval is a
- * 6 px accent bar, the exact interval a 2 px muted bar under it, and a dashed
- * ink tick marks the row's registered minimum effect. There is no point
- * estimate, because the record carries none.
- *
- * Refuses: a row whose interval names no level or method, or that has no pair
- * count or no registered minimum effect (each is listed in the note); the
- * whole figure when no row can be drawn.
- */
-
+export declare function breakdown(input: BreakdownInput, o: BreakdownOptions): Figure | Refusal;
+//#endregion
+//#region src/comparison-intervals.d.ts
 interface ComparisonIntervalsOptions {
-    /** The measure the difference is in, lower case: "solve rate". */
-    measure: string;
-    id?: string;
+  /** The measure the difference is in, lower case: "solve rate". */
+  measure: string;
+  id?: string;
 }
-declare function comparisonIntervals(rows: ComparisonRow[], setups: Setup[], o: ComparisonIntervalsOptions): Figure | Refusal;
-
-/**
- * `costFrontier`: which setup gives the most passes per dollar.
- *
- * y is the measure on a fixed 0–1 axis. x is cost per pass on a log
- * scale, reversed so cheaper sits right and better is always up and right. A
- * point on the producer's frontier is an accent disc; any other point is a
- * hollow muted circle, and an estimated cost is never a filled disc. An ink
- * line joins frontier points. Every point is labelled directly; a label that
- * collides everywhere becomes a number listed in the table. A setup with no
- * pass or an unknown cost is listed under the axis, never placed at an
- * origin a log axis does not have. On a phone the plot becomes a list sorted
- * by the measure, with the same point marks, a rate bar and the cost as text.
- *
- * Refuses: the whole figure when fewer than two setups have a cost per pass; the frontier line unless two or more rows carry `onFront: true` (it
- * never computes dominance itself).
- */
-
+export declare function comparisonIntervals(rows: ComparisonRow[], setups: Setup[], o: ComparisonIntervalsOptions): Figure | Refusal;
+//#endregion
+//#region src/cost-frontier.d.ts
 interface CostFrontierOptions {
-    /** The y measure, lower case: "solve rate". */
-    measure: string;
-    id?: string;
+  /** The y measure, lower case: "solve rate". */
+  measure: string;
+  id?: string;
 }
-declare function costFrontier(rows: RateRow[], o: CostFrontierOptions): Figure | Refusal;
-
+export declare function costFrontier(rows: RateRow[], o: CostFrontierOptions): Figure | Refusal;
+//#endregion
+//#region src/css.generated.d.ts
 /** The figure block and mark styles (src/figure.css), for documents that inline their CSS. */
-declare const figureCss: string;
+export declare const figureCss: string;
 /** --chart-* resolved per theme, for documents without brand tokens: light, dark by preference or [data-theme="dark"], light in print. */
-declare const chartTokensCss: string;
-
+export declare const chartTokensCss: string;
+//#endregion
+//#region src/format.d.ts
 /**
- * `rankedRates`: which setup passes most, and how uncertain is each rate.
- *
- * One row per setup: rank (only when every row is ranked), label, an accent
- * bar on a shared 0–1 axis with the interval as an ink whisker, `passed/n`,
- * cost per pass and median run. An App Grade grader adds a tier strip under
- * the bar with a tick at the pass tier. Ranked rows keep their rank order;
- * unranked rows sort by rate, and the finding says no comparison backs it.
- *
- * Refuses: a bar when the producer labels the estimate `none` or
- * `insufficient` (the row prints its count only); a whisker whose interval
- * names no level or method; a rank number unless every row carries one; any
- * cost it was not given. It never prints "winner", "best" or "#1".
+ * The order rows are drawn in. Ranked rows keep their rank. Otherwise rows
+ * with enough units to draw a rate come first, highest rate first; rows with
+ * too few units follow, most units first, so a 1/1 row never heads the list.
  */
-
+export declare function rateOrder<T extends Pick<RateRow, "rank" | "rate" | "estimate" | "attempts">>(rows: readonly T[]): T[];
+//#endregion
+//#region src/ranked-rates.d.ts
 interface RankedRatesOptions {
-    /** What the rate measures, lower case: "solve rate". */
-    measure: string;
-    /** The App Grade tier a pass needs; marks the tier strip. */
-    passTier?: Tier;
-    /** Singular, lower-case nouns: what one unit of `attempts` is, and what a row is. */
-    nouns?: {
-        attempt: string;
-        setup: string;
-    };
-    id?: string;
-    excluded?: Exclusion[];
+  /** What the rate measures, lower case: "solve rate". */
+  measure: string;
+  /** The App Grade tier a pass needs; marks the tier strip. */
+  passTier?: Tier;
+  /** Singular, lower-case nouns: what one unit of `attempts` is, and what a row is. */
+  nouns?: {
+    attempt: string;
+    setup: string;
+  };
+  id?: string;
+  excluded?: Exclusion[];
 }
-declare function rankedRates(input: RateRow[], o: RankedRatesOptions): Figure | Refusal;
-
-/**
- * `taskMatrix`: where each setup succeeds and fails.
- *
- * Rows are tasks in the given (registered) order; columns are setups in rank
- * order when every setup is ranked, otherwise in the given order. Each cell
- * draws one 12 px tile per attempt, best first, then `solved/attempts`.
- * App Grade tiles fill by tier and F is an outline; U (unable to measure) is a
- * dashed outline and an integrity-flagged grade is a struck outline. Runner
- * verification fills solved tiles with the accent. A lens matrix (`show:
- * "means"`) prints each mean with a bar on one shared scale.
- *
- * Refuses: a fill for an attempt without a grade (outline with a dot); a zero
- * for a cell that never ran ("·"); counts that do not add up; any column order
- * but the given rank.
- */
-
+export declare function rankedRates(input: RateRow[], o: RankedRatesOptions): Figure | Refusal;
+//#endregion
+//#region src/task-matrix.d.ts
 interface TaskMatrixOptions {
-    /** The App Grade tier a pass needs; named in the legend. */
-    passTier?: Tier;
-    /** "attempts" draws a tile per attempt; "means" draws one tinted cell per mean. */
-    show?: "attempts" | "means";
-    /** Singular, lower-case nouns for rows, columns and one attempt. */
-    nouns?: {
-        task: string;
-        setup: string;
-        attempt?: string;
-    };
-    /** The columns grade the same attempts (judges on one set of plants): the finding reports agreement. */
-    agreement?: boolean;
-    id?: string;
-    excluded?: Exclusion[];
+  /** The App Grade tier a pass needs; named in the legend. */
+  passTier?: Tier;
+  /** "attempts" draws a tile per attempt; "means" draws one tinted cell per mean. */
+  show?: "attempts" | "means";
+  /** Singular, lower-case nouns for rows, columns and one attempt. */
+  nouns?: {
+    task: string;
+    setup: string;
+    attempt?: string;
+  };
+  /** The columns grade the same attempts (judges on one set of plants): the finding reports agreement. */
+  agreement?: boolean;
+  id?: string;
+  excluded?: Exclusion[];
 }
-declare function taskMatrix(tasks: string[], setupsIn: Setup[], cells: MatrixCell[], o?: TaskMatrixOptions): Figure | Refusal;
-
-export { type BreakdownInput, type BreakdownOptions, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type Estimate, type Exclusion, type Figure, type Interval, type IntervalMethod, type MatrixCell, type RankedRatesOptions, type RateRow, type Refusal, type Setup, type TaskMatrixOptions, type Tier, type TierCounts, breakdown, chartTokensCss, comparisonIntervals, costFrontier, figureCss, isRefusal, rankedRates, renderFigure, renderNotes, renderRefusals, taskMatrix };
+export declare function taskMatrix(tasks: string[], setupsIn: Setup[], cells: MatrixCell[], o?: TaskMatrixOptions): Figure | Refusal;
+//#endregion
+export type { BreakdownInput, BreakdownOptions, ComparisonIntervalsOptions, ComparisonRow, CostBasis, CostFrontierOptions, Estimate, Exclusion, Figure, Interval, IntervalMethod, MatrixCell, RankedRatesOptions, RateRow, Refusal, Setup, TaskMatrixOptions, Tier, TierCounts };