@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,508 @@
+import { ArcDeltaMode, ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ChartTokens } from "../../lib/vega/tokens.js";
+//#region src/components/AnomalyCard/AnomalyCard.model.d.ts
+/** What the consumer's transport reports. */
+type AnomalyCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the readings and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type AnomalyCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+/** Which side of the expected range a reading broke out of. */
+type AnomalyDirection = "high" | "low";
+/**
+ * How an excursion reads once `goodDirection` is applied. `neutral` is the
+ * default and the honest one for a detector: leaving the expected range is
+ * unexpected, which is neither good nor bad until the product says which way
+ * is good.
+ */
+type AnomalyPolarity = "positive" | "negative" | "neutral";
+/** Which way is good for this measure: revenue up, latency down, a detector with no opinion `none`. */
+type AnomalyGoodDirection = "up" | "down" | "none";
+/**
+ * The window's answer. `breach` — the latest reading is outside its expected
+ * range, so this is happening now; `watch` — it is inside now but the window
+ * holds excursions; `clear` — nothing left the range. Stamped as
+ * `data-verdict`.
+ */
+type AnomalyVerdict = "clear" | "watch" | "breach";
+/** `line` may crop; `area` keeps a zero baseline whatever `scale` says. */
+type AnomalyMark = "line" | "area";
+type AnomalyScale = "auto" | "zero";
+type AnomalyDeltaMode = ArcDeltaMode;
+type AnomalyCardSize = "sm" | "md" | "lg";
+type AnomalyXType = "temporal" | "quantitative" | "ordinal";
+/**
+ * The big number: the latest reading with its standing against the range
+ * (default), how many periods broke out, the worst excursion's deviation, or
+ * nothing. Stamped as `data-headline`.
+ */
+type AnomalyHeadline = "latest" | "count" | "worst" | "none";
+/**
+ * One reading with the range it was expected to sit in.
+ *
+ * `lower` / `upper` are that period's own expected bounds — a learned band
+ * from a detector, or control limits. A period that carries neither falls
+ * back to the card's flat `bounds`, and a period with no bounds at all is
+ * simply unjudged: it is drawn, and it can never be flagged by comparison.
+ */
+interface AnomalyPoint {
+  x: Date | string | number;
+  /** The reading, or `null` for a period with no measurement — drawn as a gap, never as zero, and never flagged. */
+  y: number | null;
+  /** Lower bound of the expected range at this period. */
+  lower?: number | null;
+  /** Upper bound of the expected range at this period. */
+  upper?: number | null;
+  /** What the model expected — drawn as a quiet dashed path inside the band, and named in the tooltip and the table. */
+  expected?: number | null;
+  /**
+   * The detector's own verdict for this period. Takes precedence over the
+   * band comparison in BOTH directions: `true` flags a reading the bounds
+   * would have accepted, `false` clears one they would have rejected. Leave
+   * it out to let the bounds decide.
+   */
+  anomaly?: boolean;
+  /** The detector's own score for this period (sigmas, a probability — whatever `scoreFormat` prints), shown in the tooltip, the rows and the table. */
+  score?: number | null;
+}
+/** A reading in the long-form shape the plot reads. */
+interface AnomalyRow {
+  x: number | string;
+  /** The reading — `null` for a gap, which breaks the path rather than dropping it to zero. */
+  y: number | null;
+  /** Expected range at this period, after the flat `bounds` fallback. */
+  lo: number | null;
+  hi: number | null;
+  /** What the model expected. */
+  ex: number | null;
+  /** Signed distance past the nearest bound — positive above `hi`, negative below `lo`; `null` inside the range or unjudged. */
+  d: number | null;
+  /** This reading is an excursion. */
+  a: boolean;
+  /** Which side it broke out of; `null` when a flag arrived with no bounds to place it against. */
+  dir: AnomalyDirection | null;
+  /** The paintable colour of this row's flag mark, baked in so the spec stays structural. */
+  c: string;
+  /** The flag mark's shape — direction is carried by shape as well as hue, never by hue alone. */
+  sh: AnomalyFlagShape;
+  /** Index of the episode this reading belongs to, or `-1`. */
+  e: number;
+  /** The detector's score, or `null`. */
+  sc: number | null;
+}
+/** Vega point shapes the flag marks use: direction as shape, so colour is never the only cue. */
+type AnomalyFlagShape = "triangle-up" | "triangle-down" | "circle";
+/** One row per period — the crosshair's own dataset, so the hover lands on the period. */
+interface AnomalyPeriodRow {
+  x: number | string;
+}
+/**
+ * The washed span of the selected episode — always exactly one row while
+ * there are periods, carrying `on` rather than appearing and disappearing.
+ * An EMPTY dataset still feeds the shared `x` scale, and Vega logs
+ * `Infinite extent for field "start"` for the life of the chart; a row that
+ * is merely transparent keeps the domain honest and keeps the selection a
+ * data push rather than a re-embed.
+ */
+interface AnomalySpanRow {
+  start: number | string;
+  end: number | string;
+  /** An excursion is selected, so the wash is painted. */
+  on: boolean;
+}
+/**
+ * A run of consecutive flagged periods — the unit a reader actually acts on.
+ * One reading three sigma out and a four-hour excursion are different events,
+ * and counting periods would call them the same size.
+ */
+interface AnomalyEpisode {
+  /** Stable identity for selection — derived from the first flagged period. */
+  key: string;
+  index: number;
+  start: number | string;
+  end: number | string;
+  /** Flagged periods inside it. */
+  count: number;
+  /** The direction of its peak. */
+  direction: AnomalyDirection | null;
+  /** It broke out of both bounds — the direction word alone would be a half-truth. */
+  mixed: boolean;
+  polarity: AnomalyPolarity;
+  /** The paintable colour of its flags, baked in so a row and its marks can never disagree. */
+  color: string;
+  /** The reading furthest past its bound; `null` when nothing in the episode could be measured against a bound. */
+  peak: AnomalyPeak | null;
+  /** It runs to the last period in the window, so it has not ended. */
+  ongoing: boolean;
+}
+/** The worst reading inside an episode, with everything the rows and sentences quote. */
+interface AnomalyPeak {
+  x: number | string;
+  y: number;
+  /** Signed distance past the bound it broke. */
+  deviation: number;
+  /** The bound it broke. */
+  bound: number;
+  direction: AnomalyDirection;
+  score: number | null;
+}
+interface AnomalySummary {
+  xType: AnomalyXType;
+  granularity: ArcTimeGranularity;
+  /** The period domain, in axis order. */
+  periods: (number | string)[];
+  rows: AnomalyRow[];
+  /** Periods with a finite reading. */
+  count: number;
+  /** The plot's extent — the readings AND the band, so `scale: "auto"` can never crop the range it is judging against. */
+  min: number | null;
+  max: number | null;
+  /** At least one period carries an expected range. */
+  hasBand: boolean;
+  /** At least one period carries an expected value. */
+  hasExpected: boolean;
+  /** At least one period carries a detector score. */
+  hasScore: boolean;
+  /** Periods judged against a range — the denominator the flag rate is honest about. */
+  judged: number;
+  /** Flagged periods. */
+  flagged: number;
+  episodes: AnomalyEpisode[];
+  /** The last period with a reading. */
+  latest: AnomalyRow | null;
+  /** The episode the latest period belongs to, when it is flagged — the reason a verdict can be `breach`. */
+  current: AnomalyEpisode | null;
+  /** The episode with the largest peak deviation, relative to the bound it broke. */
+  worst: AnomalyEpisode | null;
+}
+/** A piece of a generated insight sentence: plain text, or a value the card sets in bold. */
+type AnomalyInsightSegment = string | {
+  value: string;
+};
+/** What the flag tooltip and the episode rows explain about one excursion. */
+interface AnomalyExplanation {
+  periodText: string;
+  valueText: string;
+  expectedText: string | null;
+  rangeText: string;
+  deviationText: string;
+  secondaryText: string | null;
+  scoreText: string | null;
+  direction: AnomalyDirection | null;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface AnomalyCardLabels {
+  /** Direction words — used in badges, rows, the table and every sentence, so hue is never the only cue. */
+  high: string;
+  low: string;
+  mixed: string;
+  inRange: string;
+  /** Suffix for a percentage-point deviation. */
+  percentagePoints: string;
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  /** Shown in place of the plot when fewer than two periods carry a reading. */
+  insufficient: string;
+  /** Caption under a plot whose periods carry no expected range at all. */
+  unjudged: string;
+  stale: string;
+  asOf: string;
+  /** Verdict chip words. */
+  verdicts: Record<AnomalyVerdict, string>;
+  /** Key-row and legend names. */
+  seriesKey: string;
+  bandKey: string;
+  expectedKey: string;
+  flagKey: string;
+  /** Table and tooltip column names. */
+  tablePeriod: string;
+  tableValue: string;
+  tableExpected: string;
+  tableRange: string;
+  tableDeviation: string;
+  tableFlag: string;
+  score: string;
+  /** Heading of the excursion list. */
+  episodes: string;
+  /** Accessible name of the excursion list. */
+  episodeGroup: (name: string) => string;
+  /**
+   * A row's accessible name. It REPLACES the row's visible content for
+   * assistive technology, so it has to carry everything the row shows — the
+   * span, the direction, how many periods, how far out and the score — not
+   * just the action (WCAG 2.5.3 also wants the visible label, the span,
+   * inside it).
+   */
+  openEpisode: (input: {
+    range: string;
+    direction: string;
+    periods: string;
+    deviation: string | null;
+    score: string | null;
+    ongoing: boolean;
+  }) => string;
+  /** Read out on the episode that is still running. */
+  ongoing: string;
+  /** `1 period` / `3 periods`. */
+  periodCount: (count: number) => string;
+  /** Appended when the list is capped. */
+  moreEpisodes: (count: number) => string;
+  /** Shown in the list when the window is clean. */
+  noEpisodes: string;
+  showTable: (name: string) => string;
+  hideTable: (name: string) => string;
+  about: (name: string) => string;
+  loading: (name: string) => string;
+  tableCaption: (name: string) => string;
+  /** Accessible name of the standing group beside the headline. */
+  standingGroup: (name: string) => string;
+  /** Compact label/value rows explaining one excursion — the flag tooltip and the headline tooltip share them. */
+  explanation: (input: AnomalyExplanation) => readonly (readonly [label: string, value: string])[];
+  /** The headline caption under a `latest` headline. */
+  expectedRange: (range: string) => string;
+  /** The headline caption under a `count` headline — `of 84 periods judged`. */
+  ofJudged: (count: number) => string;
+  /** The verdict sentence in the card description. */
+  verdictSentence: (input: {
+    verdict: AnomalyVerdict;
+    name: string;
+    count: number;
+    range: string;
+    latest: string;
+  }) => string;
+  /** Names the worst excursion. */
+  worstSentence: (input: {
+    period: string;
+    value: string;
+    deviation: string;
+    bound: string;
+    direction: string;
+  }) => string;
+  /** Appended when the detector supplied scores. */
+  scoreSentence: (score: string) => string;
+  markNames: Record<AnomalyMark, string>;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    mark: string;
+    name: string;
+    periodCount: number;
+    range: string;
+    min: string;
+    max: string;
+    flagged: number;
+    band: string | null;
+  }) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+  /** The generated insight, as segments so the readings render in bold while the words stay plain. */
+  insight: (input: {
+    name: string;
+    verdict: AnomalyVerdict;
+    count: number;
+    range: string;
+    worstAt: string | null;
+    worstValue: string | null;
+    worstDeviation: string | null;
+    worstBound: string | null;
+    direction: string | null;
+    ongoing: boolean;
+  }) => AnomalyInsightSegment[];
+}
+declare const DEFAULT_ANOMALY_LABELS: AnomalyCardLabels;
+declare function resolveAnomalyLabels(overrides?: Partial<AnomalyCardLabels>): AnomalyCardLabels;
+interface DeriveAnomalyStateInput {
+  status: AnomalyCardStatus;
+  /** At least one reading exists. */
+  hasValue: boolean;
+  /** Anything is on screen already, so a reload is a refresh, not a first load. */
+  hasData: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine. Error wins; loading over existing readings is a refresh
+ * (the previous render stays under the veil); no readings is `no-match` when
+ * the consumer's filter caused it and `empty` otherwise.
+ */
+declare function deriveAnomalyState({ status, hasValue, hasData, filtered }: DeriveAnomalyStateInput): AnomalyCardState;
+/**
+ * The granularity an x axis labels its ticks at: the tooltip and the table
+ * keep the full form (`Sep 8, 2026`); an axis has room for `Sep 8`. Duplicated
+ * per component rather than shared, so a card's text grammar is readable in
+ * one file.
+ */
+declare function anomalyAxisGranularity(granularity: ArcTimeGranularity): ArcTimeGranularity;
+/**
+ * How an excursion reads once the product says which way is good.
+ *
+ * `none` — the default — is the honest answer for a detector: leaving the
+ * expected range is UNEXPECTED, which is not the same as bad. A product that
+ * knows (revenue up, latency down) gets the polarity, and with it the
+ * diverging hues; a product that does not gets the attention hue for both
+ * directions, and the direction is read from the mark's shape and its word.
+ */
+declare function anomalyPolarityFor(direction: AnomalyDirection | null, goodDirection: AnomalyGoodDirection): AnomalyPolarity;
+/**
+ * The colour one excursion paints with — colour's ONE job here is polarity.
+ * A neutral excursion takes the attention hue rather than a diverging end,
+ * because saying "good" or "bad" about a move nobody has assigned a direction
+ * to is exactly the lie rule 6 exists to prevent. This is one of the two
+ * places the reserved status hues belong on a mark: the encoded value IS
+ * "this needs a look".
+ */
+declare function anomalyColorFor(polarity: AnomalyPolarity, tokens: ChartTokens): string;
+/** Direction as SHAPE, so a flag never depends on hue alone (WCAG 1.4.1). */
+declare function anomalyShapeFor(direction: AnomalyDirection | null): AnomalyFlagShape;
+interface AnomalyBounds {
+  lower?: number | null;
+  upper?: number | null;
+}
+interface NormalizeAnomalyOptions {
+  granularity?: ArcTimeGranularity;
+  /**
+   * A flat expected range for every period that carries no bounds of its own —
+   * a control limit or an SLO, rather than a learned band. A period's own
+   * `lower` / `upper` always win.
+   */
+  bounds?: AnomalyBounds;
+  goodDirection: AnomalyGoodDirection;
+  tokens: ChartTokens;
+}
+/**
+ * Normalises the readings onto one period domain, resolves each period's
+ * expected range (its own bounds, else the flat `bounds`), decides the flag
+ * (the detector's `anomaly` first, the bounds second), measures how far past
+ * the bound each excursion went, and groups consecutive excursions into
+ * episodes.
+ *
+ * The plot's extent spans the readings AND the band, so a cropped `auto`
+ * scale can never hide the range the readings are being judged against.
+ *
+ * Returns `null` when there are no readings to speak of.
+ */
+declare function normalizeAnomalies(points: readonly AnomalyPoint[] | undefined, { granularity, bounds, goodDirection, tokens }: NormalizeAnomalyOptions): AnomalySummary | null;
+/** The periods the crosshair reads — one row each, so the hover lands on the period. */
+declare function buildAnomalyPeriodRows(summary: AnomalySummary): AnomalyPeriodRow[];
+/**
+ * The washed span of the selected episode. A wash in the brush role means
+ * SELECTION here, which is exactly what this is: the reader picked an
+ * excursion and the plot says which one.
+ *
+ * Always one row while the window has periods — a selection turns `on`, it
+ * does not add a row. An empty dataset would contribute an empty extent to
+ * the shared `x` scale (`Infinite extent for field "start"`), and gating the
+ * layer on the selection instead would re-embed the view every time the
+ * reader picked a different excursion.
+ */
+declare function buildAnomalySpanRows(summary: AnomalySummary | null | undefined, selectedKey: string | null | undefined): AnomalySpanRow[];
+/** The window's answer, and the polarity the verdict chip wears. */
+interface AnomalyStanding {
+  verdict: AnomalyVerdict;
+  /** The current excursion's polarity when breaching, else neutral — a chip is never coloured by an event that has ended. */
+  polarity: AnomalyPolarity;
+}
+/**
+ * `breach` when the latest reading is outside its range, `watch` when the
+ * window holds excursions but the latest reading is inside, `clear` when
+ * nothing left the range. A window with nothing to judge against is `clear`
+ * only in the sense that nothing was flagged, and the card says so in its
+ * caption rather than in the verdict.
+ */
+declare function deriveAnomalyStanding(summary: AnomalySummary | null | undefined): AnomalyStanding;
+interface AnomalyTextFormatters {
+  /** A reading in the card's own grammar. */
+  formatValue: (value: number | null | undefined) => string;
+  /** A signed deviation — `+124 ms`, `-2.4 pp`. */
+  formatDeviation: (deviation: number | null | undefined, bound: number | null | undefined, mode?: AnomalyDeltaMode) => string | null;
+  /** The relative deviation when the absolute one was rendered, and the other way round; `null` when the second form does not exist. */
+  formatDeviationSecondary: (deviation: number | null | undefined, bound: number | null | undefined, mode?: AnomalyDeltaMode) => string | null;
+  /** An expected range as `lo – hi`, or a one-sided bound as `≤ hi` / `≥ lo`. */
+  formatRange: (lo: number | null | undefined, hi: number | null | undefined) => string;
+  formatScore: (score: number | null | undefined) => string | null;
+  formatX: (x: number | string) => string;
+  /** A span between two `x` values — a collapsed date range for a temporal axis, `start – end` otherwise, and one period for a span of one. */
+  formatXRange: (start: number | string, end: number | string) => string;
+}
+/** The formatters every text surface shares — headline, rows, table, tooltip, descriptions. */
+declare function createAnomalyFormatters({ format, locale, timeZone, formatValue, xType, granularity, deltaMode, percentagePoints, scoreFormat }: {
+  format: string;
+  locale?: string;
+  timeZone?: string;
+  formatValue?: (value: number) => string;
+  xType: AnomalyXType;
+  granularity: ArcTimeGranularity;
+  deltaMode?: AnomalyDeltaMode;
+  percentagePoints?: string;
+  scoreFormat?: string;
+}): AnomalyTextFormatters;
+/** The label/value rows one excursion explains itself with — shared by the flag tooltip, the headline tooltip and the episode rows. */
+declare function buildAnomalyExplanation({ row, formatters, labels }: {
+  row: Pick<AnomalyRow, "x" | "y" | "lo" | "hi" | "ex" | "d" | "dir" | "sc">;
+  formatters: AnomalyTextFormatters;
+  labels: AnomalyCardLabels;
+}): AnomalyExplanation;
+/**
+ * The generated insight — what the card shows beside the AI mark when the
+ * consumer passes no `insight`. Values come back as `{ value }` segments so
+ * the card can set them in bold; the words come from `labels.insight`.
+ */
+declare function buildAnomalyInsight({ name, summary, standing, formatters, labels }: {
+  name: string;
+  summary: AnomalySummary;
+  standing: AnomalyStanding;
+  formatters: AnomalyTextFormatters;
+  labels: AnomalyCardLabels;
+}): AnomalyInsightSegment[];
+/** Everything the hover chip shows for one period. */
+interface AnomalyTooltipModel {
+  explanation: AnomalyExplanation;
+  /** This period is an excursion — the chip leads with the direction word. */
+  flagged: boolean;
+  directionText: string | null;
+  /** The flag's own hue, taken from the row rather than recomputed, so the chip and the mark can never disagree. */
+  color: string;
+  /** The flag's own shape, for the same reason. */
+  shape: AnomalyFlagShape;
+}
+/**
+ * The hover chip's contents for one period — pure, so the reading is
+ * unit-tested rather than only reachable through a pointer event (Vega's own
+ * hit-testing needs a visible document, which a hidden frame does not give).
+ * Returns `null` for a period the card does not have.
+ */
+declare function buildAnomalyTooltip({ summary, x, formatters, labels }: {
+  summary: AnomalySummary | null | undefined;
+  /** The hovered period, as it arrives on the row. */
+  x: number | string | undefined;
+  formatters: AnomalyTextFormatters;
+  labels: AnomalyCardLabels;
+}): AnomalyTooltipModel | null;
+interface BuildAnomalyDescriptionInput {
+  name: string;
+  state: AnomalyCardState;
+  summary: AnomalySummary | null;
+  standing: AnomalyStanding;
+  formatters: AnomalyTextFormatters;
+  asOfText?: string;
+  labels: AnomalyCardLabels;
+}
+/**
+ * The card'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. Every
+ * excursion is named with its span, so nothing lives only in the marks.
+ */
+declare function buildAnomalyDescription({ name, state, summary, standing, formatters, asOfText, labels }: BuildAnomalyDescriptionInput): string;
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+declare function buildAnomalyChartDescription({ name, mark, summary, formatters, labels }: {
+  name: string;
+  mark: AnomalyMark;
+  summary: AnomalySummary;
+  formatters: AnomalyTextFormatters;
+  labels: AnomalyCardLabels;
+}): string;
+//#endregion
+export { AnomalyBounds, AnomalyCardLabels, AnomalyCardSize, AnomalyCardState, AnomalyCardStatus, AnomalyDeltaMode, AnomalyDirection, AnomalyEpisode, AnomalyExplanation, AnomalyFlagShape, AnomalyGoodDirection, AnomalyHeadline, AnomalyInsightSegment, AnomalyMark, AnomalyPeak, AnomalyPeriodRow, AnomalyPoint, AnomalyPolarity, AnomalyRow, AnomalyScale, AnomalySpanRow, AnomalyStanding, AnomalySummary, AnomalyTextFormatters, AnomalyTooltipModel, AnomalyVerdict, AnomalyXType, BuildAnomalyDescriptionInput, DEFAULT_ANOMALY_LABELS, DeriveAnomalyStateInput, NormalizeAnomalyOptions, anomalyAxisGranularity, anomalyColorFor, anomalyPolarityFor, anomalyShapeFor, buildAnomalyChartDescription, buildAnomalyDescription, buildAnomalyExplanation, buildAnomalyInsight, buildAnomalyPeriodRows, buildAnomalySpanRows, buildAnomalyTooltip, createAnomalyFormatters, deriveAnomalyStanding, deriveAnomalyState, normalizeAnomalies, resolveAnomalyLabels };