@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,405 @@
+import { ArcDeltaDirection, ArcDeltaMode, ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ChartTokens } from "../../lib/vega/tokens.js";
+//#region src/components/InsightCard/InsightCard.model.d.ts
+/** What the consumer's transport reports. */
+type InsightCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the finding and
+ * `filtered`. Stamped on the root as `data-state`. `insufficient` is a
+ * finding with too little history to plot: the claim, the evidence row and
+ * the range strip all still read, so the card renders — the time plot is
+ * what degrades, and it says so rather than drawing a trend from one point.
+ */
+type InsightCardState = "loading" | "refreshing" | "ready" | "insufficient" | "empty" | "no-match" | "error";
+/** Which way is good for this measure: revenue up, churn down, headcount neither. */
+type InsightGoodDirection = "up" | "down" | "none";
+/** How the deviation reads once `goodDirection` is applied. Stamped as `data-polarity`. */
+type InsightPolarity = "positive" | "negative" | "neutral";
+/**
+ * How much the finding matters — a different axis from `polarity`, which says
+ * whether it is good news. Stamped as `data-severity`.
+ */
+type InsightSeverity = "info" | "notable" | "critical";
+/**
+ * What kind of finding this is. It drives the badge's word and glyph and
+ * nothing else: a rail of mixed kinds still reads as one medium, because the
+ * encoding underneath never changes with the kind (Few's pitfall #6).
+ */
+type InsightKind = "anomaly" | "trend" | "threshold" | "outlier" | "correlation" | "forecast" | "milestone" | "note";
+/**
+ * The form the evidence plot draws. Every one shows the same thing — where
+ * the observed reading sits against what was expected — at a different
+ * density:
+ *
+ * - `spark`: the measure over its history, with the expected corridor, the
+ *   flagged period's expected interval and the flagged reading marked. The
+ *   fullest evidence, and the default whenever there is history.
+ * - `range`: a one-dimensional strip — the expected band laid on the value
+ *   domain with the observed reading marked against it. The honest degrade
+ *   when there is no history, and the compact form for a dense rail.
+ * - `none`: no plot. For a finding whose evidence is not a number on a scale
+ *   (a correlation, a data-quality note) — the statement and the table carry it.
+ *
+ * `auto` (default) picks `spark` when the history supports one, then `range`
+ * when an expectation does, then `none`. Stamped as `data-evidence`.
+ */
+type InsightEvidence = "auto" | "spark" | "range" | "none";
+type InsightXType = "temporal" | "quantitative" | "ordinal";
+type InsightCardSize = "sm" | "md" | "lg";
+type InsightDeltaMode = ArcDeltaMode;
+/**
+ * Which scale the deviation is measured on, and therefore what
+ * `severityThresholds` are counted in. Stamped as `data-strength`.
+ *
+ * - `sigma`: the detector reported a standard deviation — the deviation in
+ *   standard deviations. Defaults 2 and 3, the conventional bounds.
+ * - `band`: an expected range without a σ — the deviation in half-widths of
+ *   that range, so 1 is exactly at the edge. Defaults 1 and 2.
+ * - `relative`: a point expectation only — the deviation as a share of it.
+ *   Defaults 0.1 and 0.25.
+ */
+type InsightStrengthKind = "sigma" | "band" | "relative";
+/** What the reader told us about the finding. */
+type InsightFeedback = "helpful" | "not-helpful";
+/** How much the detector trusts the finding, bucketed for the provenance line. */
+type InsightConfidenceLevel = "high" | "moderate" | "low";
+/** One reading on the measure's history — what the evidence spark draws. */
+interface InsightPoint {
+  /** Period or position. A `Date`, an ISO string, a number, or a category name. */
+  x: Date | string | number;
+  /** The reading. `null` or omitted is a gap, never a zero. */
+  y?: number | null;
+  /** What was expected at this period, when the detector reports one per period. Drawn as a dashed line. */
+  expected?: number | null;
+  /** The expected corridor at this period. Both bounds or neither; drawn as a band. */
+  lower?: number | null;
+  upper?: number | null;
+  /** This is the reading the finding is about. Without one the card flags the period named by `observation.at`, then the last finite reading. */
+  flagged?: boolean;
+}
+/**
+ * The finding as numbers: the reading it is about and what was expected of
+ * it. This is what makes the claim checkable — a statement with no
+ * observation is an assertion, and the card renders it as one.
+ */
+interface InsightObservation {
+  /** The reading the finding is about. */
+  value: number;
+  /** The point expectation. Defaults to the midpoint of `lower`/`upper` when only a band is reported. */
+  expected?: number | null;
+  /** The expected range. Both bounds or neither. */
+  lower?: number | null;
+  upper?: number | null;
+  /** Standard deviation of the expectation, when the detector reports one — it turns the deviation into a z-score. */
+  sd?: number | null;
+  /** The period the reading belongs to. Matches a point's `x` to place the marker; also read out in the description. */
+  at?: Date | string | number;
+}
+/** Overrides for the severity ladder, in the units of the active `InsightStrengthKind`. */
+interface InsightSeverityThresholds {
+  /** At or above this strength the finding is `notable`. */
+  notable?: number;
+  /** At or above this strength it is `critical`. */
+  critical?: number;
+}
+/** One row the spark reads. */
+interface InsightRow {
+  /** Epoch ms for a temporal axis, the number for a quantitative one, the category otherwise. */
+  x: number | string;
+  /** The reading; `null` for a gap, so the path breaks rather than inventing a segment. */
+  y: number | null;
+  /** The per-period expectation, or `null`. */
+  e: number | null;
+  /** The per-period corridor, or `null`. */
+  lo: number | null;
+  hi: number | null;
+  /** This row is the flagged reading. */
+  f: boolean;
+  /** The paintable colour of the flagged marker, baked in so the spec stays structural. */
+  c: string;
+}
+/** The flagged period's expected interval, drawn as a rule when the corridor is a single scalar band. */
+interface InsightIntervalRow {
+  x: number | string;
+  lo: number;
+  hi: number;
+}
+/** The one row the range strip reads: the band, the expectation, the reading, and the domain to draw them in. */
+interface InsightStripRow {
+  lo: number | null;
+  hi: number | null;
+  e: number | null;
+  v: number;
+  /** Scale bounds, computed here so the strip's domain is a data push and never a re-embed. */
+  d0: number;
+  d1: number;
+  c: string;
+}
+/** The finding, resolved. */
+interface InsightSummary {
+  /** The reading the finding is about, or `null` when the finding carries no number. */
+  value: number | null;
+  /** The expectation — as reported, or the midpoint of the band. */
+  expected: number | null;
+  lower: number | null;
+  upper: number | null;
+  sd: number | null;
+  /** `value - expected`, in the measure's own units. */
+  deviation: number | null;
+  /** The deviation as a share of the expectation, or `null` when the expectation is zero. */
+  relative: number | null;
+  /** The reading falls outside the expected range. `false` when no range was reported. */
+  outside: boolean;
+  /** How far from expectation, on `strengthKind`'s scale. */
+  strength: number | null;
+  strengthKind: InsightStrengthKind | null;
+  direction: ArcDeltaDirection;
+  polarity: InsightPolarity;
+  severity: InsightSeverity;
+  /** The colour the flagged marker paints with — polarity, because there the encoded value IS good or bad. */
+  color: string;
+  /** The evidence form the data can actually carry, after `evidence` was asked for. */
+  evidence: "spark" | "range" | "none";
+  xType: InsightXType;
+  /** History rows, in axis order. */
+  points: InsightRow[];
+  /** The flagged period's interval — one row, or none when the corridor is per-period (the band already shows it). */
+  interval: InsightIntervalRow[];
+  /** The range strip's one row, or none. */
+  strip: InsightStripRow[];
+  /** The flagged row's x, for the axis anchor and the description. */
+  flaggedX: number | string | null;
+  /** The period the reading belongs to, as given — for the "as of this period" sentence. */
+  at: Date | string | number | null;
+  /** Readings with a finite value. */
+  count: number;
+  /** At least two rows carry a corridor, so the spark draws a band rather than one interval. */
+  hasBand: boolean;
+  /** At least one row carries a per-period expectation, so the spark draws the dashed expected line. */
+  hasExpectedLine: boolean;
+  /** Fewer than two finite readings — there is a claim to state but no history to plot. */
+  insufficient: boolean;
+}
+/** Default severity ladders, per scale. Sigma takes the conventional 2σ / 3σ; a band counts half-widths, so 1 is the edge. */
+declare const DEFAULT_SEVERITY_THRESHOLDS: Record<InsightStrengthKind, {
+  notable: number;
+  critical: number;
+}>;
+/** Confidence at or above these reads as high, then moderate; below, low. */
+declare const CONFIDENCE_BOUNDS: {
+  readonly high: 0.9;
+  readonly moderate: 0.7;
+};
+/** Buckets a 0–1 confidence for the provenance line. `null` for anything outside the range. */
+declare function insightConfidenceLevel(confidence: number | null | undefined): InsightConfidenceLevel | null;
+/** Guesses the axis kind from the first reading that has an `x`. */
+declare function inferInsightXType(points: readonly InsightPoint[] | undefined): InsightXType;
+/** The severity the strength supports. Never guesses from a scale the data does not establish. */
+declare function deriveInsightSeverity(strength: number | null, kind: InsightStrengthKind | null, overrides?: InsightSeverityThresholds): InsightSeverity;
+/** How a deviation reads once the measure's good direction is applied. */
+declare function deriveInsightPolarity(direction: ArcDeltaDirection, goodDirection: InsightGoodDirection): InsightPolarity;
+interface NormalizeInsightOptions {
+  /** The finding's numbers. Without one the card has a statement and no checkable claim. */
+  observation?: InsightObservation | null;
+  /** The measure's history. Two or more finite readings make a spark possible. */
+  points?: readonly InsightPoint[];
+  /** Axis kind. Inferred from the first reading when omitted. */
+  xType?: InsightXType;
+  goodDirection?: InsightGoodDirection;
+  /** The evidence form asked for; `auto` takes the fullest the data supports. */
+  evidence?: InsightEvidence;
+  /** Overrides the derived severity — a detector that already scored the finding passes its own. */
+  severity?: InsightSeverity;
+  severityThresholds?: InsightSeverityThresholds;
+  /** Resolved theme tokens; `null` before the first read, which leaves the marker colour empty until it lands. */
+  tokens: ChartTokens | null;
+}
+/**
+ * Resolves the finding: which reading is flagged, what was expected of it,
+ * how far off it is and on which scale, how that reads as severity and
+ * polarity, which evidence form the data can carry, and the rows each form
+ * draws. Returns `null` when there is neither a reading nor a history to
+ * speak of.
+ */
+declare function normalizeInsight({ observation, points, xType: xTypeProp, goodDirection, evidence, severity: severityOverride, severityThresholds, tokens }: NormalizeInsightOptions): InsightSummary | null;
+interface InsightTextFormatters {
+  /** A reading in the measure's grammar. */
+  formatValue: (value: number | null | undefined) => string;
+  /** The expected range as one string, or `null` when there is no range. */
+  formatRange: (lower: number | null, upper: number | null) => string | null;
+  /** The deviation, signed, in the mode asked for. */
+  formatDeviation: (value: number, expected: number) => string;
+  /** The strength, in the units of its own scale — `2.8σ`, `1.4× the range`, `+51%`. */
+  formatStrength: (strength: number | null, kind: InsightStrengthKind | null) => string | null;
+}
+declare function createInsightFormatters({ format, locale, deltaMode, formatValue, labels }: {
+  format: string;
+  locale?: string;
+  deltaMode: InsightDeltaMode;
+  formatValue?: (value: number) => string;
+  labels: InsightCardLabels;
+}): InsightTextFormatters;
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface InsightCardLabels {
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  stale: string;
+  asOf: string;
+  /** Key-row headers. */
+  observed: string;
+  expected: string;
+  deviation: string;
+  /** The expected range, written as one value. */
+  rangeText: (lower: string, upper: string) => string;
+  /** Says whether the reading cleared the range — the claim in words, so it never rests on the plot. */
+  outsideRange: (range: string) => string;
+  insideRange: (range: string) => string;
+  /** The strength, in its own units. */
+  sigmaText: (value: string) => string;
+  bandText: (value: string) => string;
+  relativeText: (value: string) => string;
+  /** Provenance parts. */
+  detected: (when: string) => string;
+  sample: (count: string) => string;
+  confidence: (level: string, percent: string) => string;
+  confidenceNames: Record<InsightConfidenceLevel, string>;
+  /** Badge words. */
+  kindNames: Record<InsightKind, string>;
+  severityNames: Record<InsightSeverity, string>;
+  /**
+   * The badge's text, from the already-localised severity and kind. Severity
+   * rides the badge's hue AND its words — an `info` finding drops the word,
+   * because "Info anomaly" is noise, not information.
+   */
+  badge: (severity: string, kind: string, key: InsightSeverity) => string;
+  /** Spoken beside the delta glyph, so direction never rests on an arrow or a hue. */
+  directionWords: Record<ArcDeltaDirection, string>;
+  /** Controls. */
+  dismiss: (name: string) => string;
+  helpful: string;
+  notHelpful: string;
+  feedbackGroup: (name: string) => string;
+  showTable: (name: string) => string;
+  hideTable: (name: string) => string;
+  about: (name: string) => string;
+  loading: (name: string) => string;
+  tableCaption: (name: string) => string;
+  /** Table headers. */
+  tablePeriod: string;
+  tableValue: string;
+  tableExpected: string;
+  tableRange: string;
+  tableFlagged: string;
+  /** Marks the flagged row in the table, so the marker is never colour alone. */
+  flagged: string;
+  /** Caption under a plot that could not be drawn from one reading. */
+  needsHistory: string;
+  /** How each evidence form names itself at the start of the plot's `aria-label`. */
+  evidenceNames: Record<"spark" | "range", string>;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    evidence: string;
+    name: string;
+    readings: number;
+    observed: string;
+    expected: string | null;
+    range: string | null;
+    at: string | null;
+  }) => string;
+  /** The finding restated for the description, when the statement is not plain text. */
+  claim: (input: {
+    kind: string;
+    name: string;
+    observed: string;
+    expected: string | null;
+    deviation: string | null;
+  }) => string;
+  /** Accessible name of the AI mark beside the statement. */
+  insightMark: string;
+}
+declare const DEFAULT_INSIGHT_LABELS: InsightCardLabels;
+declare function resolveInsightLabels(overrides?: Partial<InsightCardLabels>): InsightCardLabels;
+interface DeriveInsightStateInput {
+  status: InsightCardStatus;
+  /** There is something to say — a statement, or a reading to report. */
+  hasFinding: boolean;
+  /** Anything is on screen already, so a reload is a refresh rather than a first load. */
+  hasData: boolean;
+  /** A finding with fewer than two readings behind it. */
+  insufficient: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine. Error wins; loading over an existing finding is a
+ * refresh (the previous render stays under the veil); a finding with too
+ * little history to plot is `insufficient`, not `ready` — the claim still
+ * reads, only the time plot degrades; nothing to say is `no-match` when the
+ * consumer's filter caused it and `empty` otherwise.
+ */
+declare function deriveInsightState({ status, hasFinding, hasData, insufficient, filtered }: DeriveInsightStateInput): InsightCardState;
+interface BuildInsightDescriptionInput {
+  name: string;
+  state: InsightCardState;
+  /** The finding in plain text, when the statement is a string or `statementText` was given. */
+  statement?: string | null;
+  kind: InsightKind;
+  severity: InsightSeverity;
+  summary: InsightSummary | null;
+  formatters: InsightTextFormatters;
+  /** The provenance sentence parts, already formatted. */
+  provenance?: readonly string[];
+  asOfText?: string | null;
+  labels: InsightCardLabels;
+}
+/**
+ * The figure's generated description: what kind of finding this is, how much
+ * it matters, the claim, the evidence that supports it, where the reading sits
+ * against the expected range, and the provenance — because a machine claim
+ * without provenance is not honest data.
+ */
+declare function buildInsightDescription({ name, state, statement, kind, severity, summary, formatters, provenance, asOfText, labels }: BuildInsightDescriptionInput): string;
+/** The plot's own `aria-label` — the form, what is on it, and where the flagged reading sits. */
+declare function buildInsightChartDescription({ name, summary, formatters, atText, labels }: {
+  name: string;
+  summary: InsightSummary;
+  formatters: InsightTextFormatters;
+  atText?: string | null;
+  labels: InsightCardLabels;
+}): string;
+/**
+ * The provenance parts, in reading order — method, confidence, sample size,
+ * detection time. Empty when the consumer reported none, which is itself
+ * worth seeing: an unattributed claim looks unattributed.
+ */
+declare function buildInsightProvenance({ method, confidence, sampleSize, detectedAtText, locale, labels }: {
+  method?: string | null;
+  confidence?: number | null;
+  sampleSize?: number | null;
+  detectedAtText?: string | null;
+  locale?: string;
+  labels: InsightCardLabels;
+}): string[];
+/** Writes a row's period the way the axis and the tooltip write it, so the table never disagrees with the plot. */
+declare function formatInsightX(x: number | string | null, { xType, granularity, locale, timeZone }: {
+  xType: InsightXType;
+  granularity?: ArcTimeGranularity;
+  locale?: string;
+  timeZone?: string;
+}): string;
+/** Whether a measure's own format is a percentage, so an absolute delta is written in points rather than percent. */
+declare function insightFormatIsPercent(format: string): boolean;
+/**
+ * The granularity an axis tick may use, given the one the card reads dates at
+ * and how long the plotted window is. An axis label has a pixel budget and
+ * ellipsizes past it, so the tooltip's full form is never the axis's form: a
+ * date drops its year, a month drops its year, and a datetime drops its clock
+ * — except across a window shorter than two days, where a bare date would
+ * print the same label at both ends and the hour is the part that separates
+ * them. The hour is in the tooltip and the table either way.
+ */
+declare function insightAxisGranularity(granularity: ArcTimeGranularity, spanMs?: number | null): ArcTimeGranularity;
+//#endregion
+export { BuildInsightDescriptionInput, CONFIDENCE_BOUNDS, DEFAULT_INSIGHT_LABELS, DEFAULT_SEVERITY_THRESHOLDS, DeriveInsightStateInput, InsightCardLabels, InsightCardSize, InsightCardState, InsightCardStatus, InsightConfidenceLevel, InsightDeltaMode, InsightEvidence, InsightFeedback, InsightGoodDirection, InsightIntervalRow, InsightKind, InsightObservation, InsightPoint, InsightPolarity, InsightRow, InsightSeverity, InsightSeverityThresholds, InsightStrengthKind, InsightStripRow, InsightSummary, InsightTextFormatters, InsightXType, NormalizeInsightOptions, buildInsightChartDescription, buildInsightDescription, buildInsightProvenance, createInsightFormatters, deriveInsightPolarity, deriveInsightSeverity, deriveInsightState, formatInsightX, inferInsightXType, insightAxisGranularity, insightConfidenceLevel, insightFormatIsPercent, normalizeInsight, resolveInsightLabels };