@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/HighlightCard/HighlightCard.model.d.ts

@@ -0,0 +1,692 @@
+import { ArcDeltaDirection, ArcDeltaMode, ArcTimeGranularity } from "../../lib/vega/formatters.js";
+//#region src/components/HighlightCard/HighlightCard.model.d.ts
+/** What the consumer's transport reports. */
+type HighlightCardStatus = "loading" | "ready" | "error";
+/**
+ * What the panel actually shows, derived from `status`, the series and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type HighlightCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+/** Which way is good: revenue up, churn down, headcount neither. */
+type HighlightGoodDirection = "up" | "down" | "none";
+/** How a change reads once `goodDirection` is applied. Stamped as `data-polarity`. */
+type HighlightPolarity = "positive" | "negative" | "neutral";
+type HighlightDeltaMode = ArcDeltaMode;
+type HighlightMark = "line" | "area" | "bar";
+type HighlightScale = "auto" | "zero";
+type HighlightXType = "temporal" | "quantitative" | "ordinal";
+type HighlightCardSize = "sm" | "md" | "lg";
+/**
+ * How the window's change is placed among its peers. `sigma` reports the mean
+ * and standard deviation of the comparable changes and the window's distance
+ * from the mean in them; `percentile` reports where the change falls in the
+ * sorted peers. Stamped as `data-baseline`.
+ *
+ * Neither is a significance test — see `HighlightPeerMode`.
+ */
+type HighlightBaseline = "sigma" | "percentile";
+/**
+ * Which comparable windows the change is placed among. `rolling` takes a
+ * window at every offset — the most peers, but overlapping windows share
+ * readings, so the spread is narrower than independent sampling would give.
+ * `adjacent` tiles non-overlapping windows aligned to the highlight's own
+ * start, which is the statistically honest set and a much smaller one.
+ *
+ * Either way the card reports a COMPARISON, never a significance test: it says
+ * "the 2nd largest of 48 windows this length", not "p < 0.05". Stamped as
+ * `data-peers`.
+ */
+type HighlightPeerMode = "rolling" | "adjacent";
+/**
+ * The verdict, from where the change falls among its peers. Drives the badge
+ * beside the headline and is stamped as `data-severity`. A heuristic on the
+ * spread of comparable windows — thresholds are documented on
+ * `severityThresholds` and overridable.
+ */
+type HighlightSeverity = "typical" | "notable" | "unusual" | "extreme";
+/** Which analysis sections the panel draws, in order. Stamped as `data-sections`. */
+type HighlightSection = "context" | "peers" | "drivers";
+/**
+ * One reading of the metric. Cloudscape's `{ x, y }` point contract: `x` is a
+ * `Date`, an ISO string, a number or a period label; `y` is the value, or
+ * `null` for a period with no reading (drawn as a gap, never as zero).
+ */
+interface HighlightPoint {
+  x: Date | string | number;
+  y: number | null;
+}
+/** A reading after normalisation: temporal `x` is epoch milliseconds, ordinal `x` a string. */
+interface HighlightRow {
+  x: number | string;
+  y: number | null;
+}
+interface HighlightSummary {
+  rows: HighlightRow[];
+  xType: HighlightXType;
+  /** Readings with a finite `y`. */
+  count: number;
+  first: HighlightRow | null;
+  last: HighlightRow | null;
+  /** The last reading with a finite `y`. */
+  latest: HighlightRow | null;
+  min: number | null;
+  max: number | null;
+  granularity: ArcTimeGranularity;
+}
+/** A finite reading the window snapped to, with its index in the normalised rows. */
+interface HighlightReading {
+  x: number | string;
+  y: number;
+  index: number;
+}
+/** A change in every form the panel speaks it. */
+interface HighlightDelta {
+  direction: ArcDeltaDirection;
+  polarity: HighlightPolarity;
+  /** Signed, formatted change: `+12.4%`, `-0.3 pp`, `+฿124K`. */
+  text: string;
+  renderedMode: ArcDeltaMode;
+  /** The same change in the other form, or `null` when it has none (a zero baseline has no percent). */
+  secondaryText: string | null;
+}
+/**
+ * The window the panel is about, in the series' own `x` type: `Date`s or ISO
+ * strings for a temporal series, numbers for a quantitative one, the category
+ * labels for an ordinal one. Each bound snaps inward to the nearest finite
+ * reading, so a window may begin or end on a gap.
+ */
+interface HighlightWindow {
+  start: Date | string | number;
+  end: Date | string | number;
+  /**
+   * Names the window — `Steepest 2-week drop`, `Outage`. Shown beside the
+   * period on the headline and used as the window's name in every generated
+   * sentence; the period itself always travels with it.
+   */
+  label?: string;
+}
+/** One step between consecutive readings inside the window. */
+interface HighlightLeg {
+  from: HighlightReading;
+  to: HighlightReading;
+  /** `to.y - from.y`, in the value's units. */
+  change: number;
+  /** The step in the panel's `deltaMode`. */
+  changeText: string;
+  rangeText: string;
+  direction: ArcDeltaDirection;
+  polarity: HighlightPolarity;
+}
+/** The resolved window: its bounds, its change, and its anatomy. */
+interface HighlightWindowInfo {
+  start: HighlightReading;
+  end: HighlightReading;
+  label?: string;
+  /** The period, formatted with the panel's locale — `Aug 17 – 24, 2026`, `Q2 – Q4`. */
+  rangeText: string;
+  /** The change from start to end in the panel's `deltaMode` — the headline. */
+  delta: HighlightDelta;
+  /** `end.y - start.y`, in the value's units — the total the drivers must reconcile with. */
+  absolute: number;
+  absoluteText: string;
+  /** The relative change, or `MISSING_VALUE` when the start reading is zero. */
+  percentText: string;
+  /** Every finite reading inside the window, in axis order. */
+  readings: HighlightReading[];
+  /** Steps between consecutive readings — the window's path. */
+  legs: HighlightLeg[];
+  /** How many rows the window spans, gaps included — the peer windows' length. */
+  length: number;
+  /** The highest and lowest readings inside the window. `null` when the window holds one reading. */
+  peak: HighlightReading | null;
+  trough: HighlightReading | null;
+  /** The single largest step inside the window, by absolute size. */
+  steepest: HighlightLeg | null;
+}
+/** One comparable window's change, as the strip plot draws it and the table lists it. */
+interface HighlightPeer {
+  start: number | string;
+  end: number | string;
+  /** The change in the compared mode — a ratio for `percent`, the value's units for `absolute`. */
+  change: number;
+  changeText: string;
+  rangeText: string;
+  /** The highlight's own window, which the strip marks and the table flags. */
+  isHighlight: boolean;
+  /** `positive`/`negative` once `goodDirection` resolves it, for the mark colour. */
+  polarity: HighlightPolarity;
+}
+/**
+ * Where the window's change falls among the changes of every comparable
+ * window in the same series — the reading that establishes the highlight.
+ */
+interface HighlightPeerStats {
+  mode: HighlightPeerMode;
+  baseline: HighlightBaseline;
+  /** Every compared window including the highlight's own, in axis order. */
+  peers: HighlightPeer[];
+  /** Comparable windows, the highlight's own excluded. */
+  count: number;
+  /** `count + 1` — what `rank` is out of. */
+  total: number;
+  /** Windows dropped because a relative change needs a non-zero start reading, or a bound fell on a gap. */
+  skipped: number;
+  /** The window's length in rows, so the text can say "windows this length". */
+  length: number;
+  /** The highlight's own change, in the compared mode. */
+  change: number;
+  changeText: string;
+  /** Mean and standard deviation of the comparable changes (population, the highlight excluded). */
+  mean: number;
+  sd: number;
+  meanText: string;
+  sdText: string;
+  /** Distance from the mean in standard deviations. `null` when every peer changed by the same amount. */
+  z: number | null;
+  zText: string;
+  /** Where the change sits in the sorted peers, 0–100. */
+  percentile: number;
+  percentileText: string;
+  /** 1 is the largest absolute change of `total` windows. */
+  rank: number;
+  rankText: string;
+  /** The typical range: mean ± 1 sd, or the 10th–90th percentile. */
+  typicalLow: number;
+  typicalHigh: number;
+  typicalText: string;
+  /** Whether the change sits inside the typical range. */
+  typical: boolean;
+  severity: HighlightSeverity;
+}
+/** Thresholds turning a placement into a verdict. Compared against `|z|` for the `sigma` baseline, and against the distance from the median percentile (0–50) for `percentile`. */
+interface HighlightSeverityThresholds {
+  /** Above this the verdict is `notable`. Defaults: 1 (sigma), 40 (percentile — outside p10–p90). */
+  notable: number;
+  /** Above this the verdict is `unusual`. Defaults: 2 (sigma), 45 (outside p5–p95). */
+  unusual: number;
+  /** Above this the verdict is `extreme`. Defaults: 3 (sigma), 49 (outside p1–p99). */
+  extreme: number;
+}
+declare const DEFAULT_SIGMA_THRESHOLDS: HighlightSeverityThresholds;
+declare const DEFAULT_PERCENTILE_THRESHOLDS: HighlightSeverityThresholds;
+/**
+ * One contributor to the window's change. Pass `contribution` (the signed
+ * amount this driver added to the total, in the value's units) or `from` and
+ * `to` (its readings at the window's bounds, from which the contribution is
+ * the difference). Contributions are amounts, never percentages — the panel
+ * derives each share against the total itself.
+ */
+interface HighlightDriver {
+  /** Stable identity for selection and for the colour, if the panel ever assigns one. Defaults to `label`. */
+  key?: string;
+  label: string;
+  /** The signed amount this driver added to the window's change. Takes precedence over `from`/`to`. */
+  contribution?: number;
+  /** This driver's reading at the window's start and end — the contribution is `to - from`. */
+  from?: number | null;
+  to?: number | null;
+}
+/** A driver after normalisation, in every form the bars, the table and the sentences need. */
+interface HighlightDriverInfo {
+  key: string;
+  label: string;
+  contribution: number;
+  contributionText: string;
+  /** `contribution / total`, or `null` when the total is zero (no share is definable). */
+  share: number | null;
+  shareText: string;
+  from: number | null;
+  to: number | null;
+  fromText: string;
+  toText: string;
+  direction: ArcDeltaDirection;
+  polarity: HighlightPolarity;
+  /** `driver` is a passed contributor, `other` the fold of the tail, `residual` the part no driver explains. */
+  role: "driver" | "other" | "residual";
+}
+/** The decomposition of the window's change, reconciled against it. */
+interface HighlightDriversInfo {
+  /** The bars, largest absolute contribution first, with `other` and `residual` last. */
+  rows: HighlightDriverInfo[];
+  /** The window's own change in the value's units — what the parts must sum to. */
+  total: number;
+  totalText: string;
+  /** The sum of the passed contributions. */
+  explained: number;
+  explainedText: string;
+  /** `total - explained` — rendered as its own row once it clears `tolerance`. */
+  residual: number;
+  residualText: string;
+  /** Whether the parts reconcile with the total inside `tolerance`. Stamped as `data-reconciles`. */
+  reconciles: boolean;
+  /** How many drivers were folded into `Other`. */
+  folded: number;
+  /** The largest contributor in the total's own direction, and the largest one against it — the insight's subjects. */
+  top: HighlightDriverInfo | null;
+  counter: HighlightDriverInfo | null;
+}
+/** A piece of a generated insight sentence: plain text, or a value the panel sets in bold. */
+type HighlightInsightSegment = string | {
+  value: string;
+};
+/** Every string the panel renders or announces, so a product can localise it. Sentences are functions. */
+interface HighlightCardLabels {
+  severityNames: Record<HighlightSeverity, string>;
+  increase: string;
+  decrease: string;
+  unchanged: string;
+  percentagePoints: string;
+  contextTitle: string;
+  peersTitle: string;
+  driversTitle: string;
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  unresolved: string;
+  insufficientPeers: string;
+  stale: string;
+  asOf: string;
+  tablePeriod: string;
+  tableValue: string;
+  tableStep: string;
+  tableChange: string;
+  tableShare: string;
+  tableDriver: string;
+  tableWindow: string;
+  windowStart: string;
+  windowEnd: string;
+  windowChange: string;
+  windowChangePercent: string;
+  windowPeriod: string;
+  windowPeak: string;
+  windowTrough: string;
+  windowSteepest: string;
+  highlighted: string;
+  peerMean: string;
+  peerSd: string;
+  peerTypical: string;
+  peerRank: string;
+  peerPercentile: string;
+  peerZ: string;
+  peerThis: string;
+  peerCount: string;
+  driverTotal: string;
+  driverExplained: string;
+  driverResidual: string;
+  driverOther: string;
+  driverContribution: string;
+  insightMark: string;
+  about: (name: string) => string;
+  loading: (name: string) => string;
+  showTable: (name: string) => string;
+  hideTable: (name: string) => string;
+  /** Accessible name of the headline stack, which opens the window's details. */
+  windowDetails: (name: string) => string;
+  /** Accessible name of the drivers list, and of one driver's drill button. */
+  driversGroup: (name: string) => string;
+  selectDriver: (label: string) => string;
+  /**
+   * Spoken once through the polite status line when the reader drills into a
+   * driver. The button's own `aria-pressed` already carries its state, so this
+   * adds the figures beside it — what a sighted reader takes from the row at a
+   * glance. `share` is `null` when the window did not move, which leaves no
+   * total to be a share of.
+   */
+  driverSelected: (input: {
+    label: string;
+    contribution: string;
+    share: string | null;
+  }) => string;
+  tableCaption: (name: string) => string;
+  peersCaption: (input: {
+    count: number;
+    readings: number;
+    mode: HighlightPeerMode;
+  }) => string;
+  driversCaption: (input: {
+    total: string;
+    explained: string;
+    residual: string;
+    reconciles: boolean;
+  }) => string;
+  foldedCaption: (folded: number, label: string) => string;
+  /** The period line under the headline: the window's name and its period, or the period alone. */
+  windowLine: (input: {
+    range: string;
+    label?: string;
+  }) => string;
+  /** Compact label/value rows explaining the headline — the window's readings, its change in both forms, and its anatomy. */
+  windowExplanation: (input: {
+    periodText: string;
+    startText: string;
+    endText: string;
+    changeText: string;
+    secondaryText: string | null;
+    renderedMode: ArcDeltaMode;
+    direction: ArcDeltaDirection;
+    peakText: string | null;
+    troughText: string | null;
+    steepestText: string | null;
+  }) => readonly (readonly [label: string, value: string])[];
+  /** Compact label/value rows explaining the peer placement. */
+  peerExplanation: (stats: HighlightPeerStats) => readonly (readonly [label: string, value: string])[];
+  /** The sentence stating the verdict, rendered as visible text under the strip. */
+  peerVerdict: (input: {
+    severity: HighlightSeverity;
+    rank: string;
+    /** Windows the rank is out of — the peers plus this one. */
+    total: number;
+    readings: number;
+    typical: string;
+    change: string;
+    inside: boolean;
+  }) => string;
+  /** Accessible description of the context plot. */
+  contextDescription: (input: {
+    mark: string;
+    name: string;
+    count: number;
+    first: string;
+    last: string;
+    min: string;
+    max: string;
+    range: string;
+    label?: string;
+    direction: ArcDeltaDirection;
+    change: string;
+  }) => string;
+  /** Accessible description of the peer strip. */
+  peersDescription: (input: {
+    name: string;
+    count: number;
+    readings: number;
+    mode: HighlightPeerMode;
+    change: string;
+    rank: string;
+    typical: string;
+    /** The verdict as its localised word, already lowercased for mid-sentence use. */
+    severity: string;
+  }) => string;
+  /** Accessible description of the drivers bars. */
+  driversDescription: (input: {
+    name: string;
+    count: number;
+    total: string;
+    top: string | null;
+    topContribution: string | null;
+    counter: string | null;
+    counterContribution: string | null;
+    residual: string | null;
+  }) => string;
+  /** The whole panel's text equivalent. */
+  cardDescription: (input: {
+    name: string;
+    state: HighlightCardState;
+    range: string;
+    label?: string;
+    direction: ArcDeltaDirection;
+    change: string;
+    secondary: string | null;
+    startText: string;
+    endText: string;
+    severity: string | null;
+    rank: string | null;
+    count: number | null;
+    driverCount: number;
+    topDriver: string | null;
+    topContribution: string | null;
+    asOf: string | null;
+  }) => string;
+  /**
+   * The generated insight, as segments so the values render in bold while the
+   * words stay plain: what moved, how it places among its peers, and which
+   * driver carried it.
+   */
+  insight: (input: {
+    name: string;
+    direction: ArcDeltaDirection;
+    change: string;
+    secondary: string | null;
+    range: string;
+    label?: string;
+    severity: HighlightSeverity;
+    rank: string | null;
+    count: number | null;
+    topDriver: string | null;
+    topContribution: string | null;
+    topShare: string | null;
+  }) => HighlightInsightSegment[];
+  markNames: Record<HighlightMark, string>;
+  peerModeNames: Record<HighlightPeerMode, string>;
+}
+declare const DEFAULT_HIGHLIGHT_LABELS: HighlightCardLabels;
+declare function resolveHighlightLabels(overrides?: Partial<HighlightCardLabels>): HighlightCardLabels;
+interface DeriveHighlightStateInput {
+  status: HighlightCardStatus;
+  /** The series holds at least one finite reading. */
+  hasData: boolean;
+  /** The consumer's filter is active, so nothing to show is a no-match rather than an empty. */
+  filtered: boolean;
+}
+/**
+ * The state the panel renders, from the transport's status and the data.
+ * `loading` with data already present is a refresh: the previous render stays
+ * under the veil rather than collapsing to a skeleton.
+ */
+declare function deriveHighlightState({ status, hasData, filtered }: DeriveHighlightStateInput): HighlightCardState;
+/**
+ * Normalises `series` for Vega and the tables: temporal `x` becomes epoch
+ * milliseconds (a bare number is quantitative — pass a `Date` or an ISO string
+ * for time), invalid dates are dropped, `null` readings stay as gaps, and the
+ * range is summarised for the text equivalents. Rows are sorted along the axis
+ * for a temporal or quantitative series, so a window can be snapped and peer
+ * windows can be walked; an ordinal series keeps the consumer's order, which
+ * IS its axis. Returns `null` without a series at all.
+ */
+declare function normalizeHighlightSeries(points: readonly HighlightPoint[] | undefined, granularity?: ArcTimeGranularity): HighlightSummary | null;
+interface HighlightTextFormatters {
+  /** A reading in the panel's value format. */
+  formatY: (value: number | null | undefined) => string;
+  formatX: (x: number | string) => string;
+  /** A period between two `x` values — a collapsed date range for a temporal axis. */
+  formatXRange: (start: number | string, end: number | string) => string;
+  /** A signed change in the value's own units — percentage points for a percent format. */
+  formatAmountChange: (delta: number) => string;
+  /** A signed change in the compared mode: a ratio as a percent, or the amount. */
+  formatPeerChange: (change: number) => string;
+  /** A share of the total, as a whole percentage. */
+  formatShare: (share: number | null) => string;
+}
+/** The formatters every text surface shares — headline, badges, strip, bars, tables, tooltips, descriptions. */
+declare function createHighlightFormatters({ format, locale, timeZone, formatValue, xType, granularity, deltaMode, percentagePoints }: {
+  format: string;
+  locale?: string;
+  timeZone?: string;
+  formatValue?: (value: number) => string;
+  xType: HighlightXType;
+  granularity: ArcTimeGranularity;
+  deltaMode: HighlightDeltaMode;
+  percentagePoints: string;
+}): HighlightTextFormatters;
+interface DeriveHighlightDeltaOptions {
+  deltaMode: HighlightDeltaMode;
+  goodDirection: HighlightGoodDirection;
+  format: string;
+  locale?: string;
+  percentagePoints: string;
+}
+/** The change between two readings, with polarity resolved through `goodDirection`. */
+declare function deriveHighlightDelta(value: number | null | undefined, previousValue: number | null | undefined, { deltaMode, goodDirection, format, locale, percentagePoints }: DeriveHighlightDeltaOptions): HighlightDelta | null;
+interface ResolveHighlightWindowOptions extends DeriveHighlightDeltaOptions {
+  formatters: HighlightTextFormatters;
+}
+/**
+ * Snaps the window onto the series and measures it. Each bound moves inward to
+ * the nearest finite reading (a temporal or quantitative bound need not hit a
+ * reading exactly; an ordinal bound is a category label), the bounds may come
+ * in either order, and the result is `null` when the window does not hold two
+ * distinct finite readings — the panel then says so and stamps
+ * `data-window="unresolved"` rather than inventing a change.
+ *
+ * Beyond the change it records the window's ANATOMY, which is what makes this
+ * a highlight-analysis panel rather than a tile: every reading inside it, the
+ * step between each consecutive pair, the peak, the trough and the steepest
+ * single step.
+ */
+declare function resolveHighlightWindow(summary: HighlightSummary | null | undefined, window: HighlightWindow | undefined, { deltaMode, goodDirection, format, locale, percentagePoints, formatters }: ResolveHighlightWindowOptions): HighlightWindowInfo | null;
+interface DerivePeersOptions extends DeriveHighlightDeltaOptions {
+  mode: HighlightPeerMode;
+  baseline: HighlightBaseline;
+  formatters: HighlightTextFormatters;
+  /** Fewer comparable windows than this and the section is not drawn — a spread of two is not a spread. Default 4. */
+  minPeers?: number;
+  thresholds?: HighlightSeverityThresholds;
+}
+/**
+ * Places the window's change among the changes of every comparable window in
+ * the same series — the reading that ESTABLISHES the highlight, and the half
+ * MetricCard's tile cannot show. Windows are the same length as the
+ * highlight's (in rows), taken at every offset (`rolling`) or tiled
+ * non-overlapping from the highlight's own start (`adjacent`), and both bounds
+ * must carry a finite reading; a window that cannot produce a change in the
+ * compared mode is skipped and counted in `skipped`.
+ *
+ * Returns `null` when fewer than `minPeers` comparable windows exist — the
+ * panel then omits the section and says why, rather than calling one window
+ * out of three "extreme".
+ *
+ * The spread is a COMPARISON, not a significance test: `rolling` windows
+ * overlap, so their changes are autocorrelated and the standard deviation is
+ * narrower than independent sampling would give. `adjacent` is the honest set.
+ * The generated text says "the 2nd largest of 48 comparable periods"; nothing
+ * here claims a p-value.
+ */
+declare function derivePeers(summary: HighlightSummary | null | undefined, info: HighlightWindowInfo | null | undefined, { mode, baseline, deltaMode, goodDirection, format, locale, percentagePoints, formatters, minPeers, thresholds }: DerivePeersOptions): HighlightPeerStats | null;
+interface NormalizeDriversOptions {
+  goodDirection: HighlightGoodDirection;
+  formatters: HighlightTextFormatters;
+  /** Fold every driver past this count (by absolute contribution) into one `Other` row. */
+  limit?: number;
+  otherLabel: string;
+  residualLabel: string;
+  /**
+   * How far the contributions may miss the window's own change and still
+   * reconcile, as a fraction of that change. Default 0.005 (half a percent).
+   */
+  tolerance?: number;
+}
+/**
+ * Decomposes the window's change into its contributors — the half that
+ * EXPLAINS the highlight. Each driver's contribution is the amount it added to
+ * the total, either passed directly or derived from its own `from`/`to`
+ * readings; rows sort by absolute contribution so the biggest mover reads
+ * first, the tail folds into `Other`, and whatever the parts do not account
+ * for becomes an explicit `Unexplained` row.
+ *
+ * Totals reconcile with parts or the panel says they do not: a decomposition
+ * that silently misses a third of the move is worse than none.
+ */
+declare function normalizeDrivers(drivers: readonly HighlightDriver[] | undefined, info: HighlightWindowInfo | null | undefined, { goodDirection, formatters, limit, otherLabel, residualLabel, tolerance }: NormalizeDriversOptions): HighlightDriversInfo | null;
+/** A context-plot row: `hl` marks the window, `tone` carries its polarity for the mark colour. */
+interface HighlightContextRow extends HighlightRow {
+  hl: boolean;
+  tone: HighlightPolarity | null;
+}
+/** The readings outside the window, split so the context line stops at the window's edges. */
+interface HighlightOutsideRow extends HighlightRow {
+  seg: "before" | "after";
+}
+interface HighlightEndpointRow {
+  x: number | string;
+  y: number;
+  role: "start" | "end";
+  tone: HighlightPolarity;
+}
+/** One row spanning the window — the band behind the line and the source of the axis anchors. */
+interface HighlightBandRow {
+  start: number | string;
+  end: number | string;
+  tone: HighlightPolarity;
+}
+/** Every named dataset the three plots read. */
+interface HighlightContextDatasets {
+  table: HighlightContextRow[];
+  outside: HighlightOutsideRow[];
+  inside: HighlightContextRow[];
+  endpoints: HighlightEndpointRow[];
+  band: HighlightBandRow[];
+}
+/**
+ * Splits the series around the window for the context plot: every row carries
+ * `hl` and the window's `tone`, the readings outside it are split into a
+ * `before` and an `after` run so the gray path never runs under the coloured
+ * one, and the window's extent rides one band row.
+ */
+declare function buildHighlightContextDatasets(summary: HighlightSummary, info: HighlightWindowInfo): HighlightContextDatasets;
+/** One row `{ low, high }` — the typical-range band behind the strip. */
+declare function buildTypicalRows(stats: HighlightPeerStats): {
+  low: number;
+  high: number;
+}[];
+/** The driver bars, in row order, with the fields the spec encodes. */
+declare function buildDriverRows(info: HighlightDriversInfo): {
+  key: string;
+  label: string;
+  value: number;
+  share: number | null;
+  tone: HighlightPolarity;
+  role: string;
+}[];
+declare function highlightSegmentsToText(segments: readonly HighlightInsightSegment[]): string;
+interface BuildHighlightAnalysisInsightInput {
+  name: string;
+  info: HighlightWindowInfo;
+  peers: HighlightPeerStats | null;
+  drivers: HighlightDriversInfo | null;
+  labels: HighlightCardLabels;
+}
+/** The takeaway: what moved, how it places among its peers, which driver carried it. */
+declare function buildHighlightAnalysisInsight({ name, info, peers, drivers, labels }: BuildHighlightAnalysisInsightInput): HighlightInsightSegment[];
+interface BuildHighlightDescriptionInput {
+  name: string;
+  state: HighlightCardState;
+  info: HighlightWindowInfo | null;
+  peers: HighlightPeerStats | null;
+  drivers: HighlightDriversInfo | null;
+  formatters: HighlightTextFormatters;
+  asOfText?: string;
+  labels: HighlightCardLabels;
+}
+/**
+ * The panel's text equivalent (Amy Cesal's alt-text formula: what it is, what
+ * it shows, why it is here, when it was true) — the figure's accessible
+ * description, and the summary a screen reader gets before the parts.
+ */
+declare function buildHighlightDescription({ name, state, info, peers, drivers, formatters, asOfText, labels }: BuildHighlightDescriptionInput): string;
+/** Accessible description of the context plot — set live through `view.description`. */
+declare function buildContextDescription({ name, mark, summary, info, formatters, labels }: {
+  name: string;
+  mark: HighlightMark;
+  summary: HighlightSummary;
+  info: HighlightWindowInfo;
+  formatters: HighlightTextFormatters;
+  labels: HighlightCardLabels;
+}): string;
+/** Accessible description of the peer strip. */
+declare function buildPeersDescription({ name, stats, labels }: {
+  name: string;
+  stats: HighlightPeerStats;
+  labels: HighlightCardLabels;
+}): string;
+/** Accessible description of the drivers bars. */
+declare function buildDriversDescription({ name, info, labels }: {
+  name: string;
+  info: HighlightDriversInfo;
+  labels: HighlightCardLabels;
+}): string;
+/** The verdict sentence under the strip — visible text, never colour alone. */
+declare function buildPeerVerdict(stats: HighlightPeerStats, labels: HighlightCardLabels): string;
+//#endregion
+export { BuildHighlightAnalysisInsightInput, BuildHighlightDescriptionInput, DEFAULT_HIGHLIGHT_LABELS, DEFAULT_PERCENTILE_THRESHOLDS, DEFAULT_SIGMA_THRESHOLDS, DeriveHighlightDeltaOptions, DeriveHighlightStateInput, DerivePeersOptions, HighlightBandRow, HighlightBaseline, HighlightCardLabels, HighlightCardSize, HighlightCardState, HighlightCardStatus, HighlightContextDatasets, HighlightContextRow, HighlightDelta, HighlightDeltaMode, HighlightDriver, HighlightDriverInfo, HighlightDriversInfo, HighlightEndpointRow, HighlightGoodDirection, HighlightInsightSegment, HighlightLeg, HighlightMark, HighlightOutsideRow, HighlightPeer, HighlightPeerMode, HighlightPeerStats, HighlightPoint, HighlightPolarity, HighlightReading, HighlightRow, HighlightScale, HighlightSection, HighlightSeverity, HighlightSeverityThresholds, HighlightSummary, HighlightTextFormatters, HighlightWindow, HighlightWindowInfo, HighlightXType, NormalizeDriversOptions, ResolveHighlightWindowOptions, buildContextDescription, buildDriverRows, buildDriversDescription, buildHighlightAnalysisInsight, buildHighlightContextDatasets, buildHighlightDescription, buildPeerVerdict, buildPeersDescription, buildTypicalRows, createHighlightFormatters, deriveHighlightDelta, deriveHighlightState, derivePeers, highlightSegmentsToText, normalizeDrivers, normalizeHighlightSeries, resolveHighlightLabels, resolveHighlightWindow };