@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,545 @@
+import { ArcDeltaDirection, ArcDeltaMode, ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ChartTokens } from "../../lib/vega/tokens.js";
+//#region src/components/TrendCard/TrendCard.model.d.ts
+/** What the consumer's transport reports. */
+type TrendCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the series and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type TrendCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+/** Which way is good for the focused series: revenue up, latency down, headcount neutral. */
+type TrendGoodDirection = "up" | "down" | "none";
+/** How the change across the span reads once `goodDirection` is applied. Stamped as `data-polarity`. */
+type TrendPolarity = "positive" | "negative" | "neutral";
+type TrendDeltaMode = ArcDeltaMode;
+/** `line` may crop; `area` and `bar` keep a zero baseline whatever `scale` says. */
+type TrendMark = "line" | "area" | "bar";
+type TrendScale = "auto" | "zero";
+/**
+ * How several `area` or `bar` series sit together: `false` overlays them (each
+ * read against the same axis), `"zero"` stacks them into a total, `"normalize"`
+ * stacks them to 100% — the composition-over-time reading. Lines never stack.
+ */
+type TrendStack = false | "zero" | "normalize";
+/**
+ * `none` plots the readings as they are. `index` divides every series by its
+ * own first finite reading × 100, which is the honest way to compare series in
+ * different units on ONE axis — the alternative to a second y scale, which this
+ * package does not allow. The raw reading rides along in the tooltip and the
+ * table, so the transformation is never silent.
+ */
+type TrendNormalize = "none" | "index";
+/**
+ * What colour is doing. `auto` picks by count against the theme's own slot
+ * budget: one series takes the emphasis hue, a handful take the categorical
+ * slots, and past the budget identity moves to `emphasis` — the focused series
+ * in the hue on a context-gray field. `categorical` forces identity slots (and
+ * degrades to `emphasis` when the theme has fewer slots than series, rather
+ * than repeating a hue and making two series look like one). `sequential` is
+ * for ORDERED series — cohorts, years, buckets — low → high through the ramp.
+ */
+type TrendSeriesColor = "auto" | "emphasis" | "categorical" | "sequential";
+/** The resolved colour job, after `auto` and the slot budget. Stamped as `data-series-color`. */
+type TrendSeriesColorMode = "emphasis" | "categorical" | "sequential";
+type TrendCardSize = "sm" | "md" | "lg";
+/** The big number: the focused series' latest reading, its change across the span, or nothing. Stamped as `data-headline`. */
+type TrendHeadline = "latest" | "change" | "none";
+type TrendXType = "temporal" | "quantitative" | "ordinal";
+/**
+ * One reading. 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 TrendPoint {
+  x: Date | string | number;
+  y: number | null;
+}
+/**
+ * One series over time. `key` identifies it for `focus` and `visibleSeries`
+ * (defaults to `label`); `points` need not cover every period — a period this
+ * series is missing is a gap, not a zero.
+ */
+interface TrendSeries {
+  key?: string;
+  label: string;
+  points: readonly TrendPoint[];
+}
+/**
+ * A named stretch of the x axis — a launch week, an outage, a promotion. Drawn
+ * as a quiet wash behind the marks (never in a series hue, so it cannot be read
+ * as data), named in the legend row, marked on the table's rows and added to
+ * the tooltip while the pointer is inside it.
+ */
+interface TrendBand {
+  start: Date | string | number;
+  end: Date | string | number;
+  label?: string;
+}
+/** A reading in the long-form shape the plot reads: series key, series index, and the colour the row paints with. */
+interface TrendRow {
+  x: number | string;
+  /** Series key. */
+  s: string;
+  /** The plotted value — indexed when `normalize` is `index`, else the reading. */
+  y: number | null;
+  /** The reading as it arrived, kept for the tooltip and the table when `normalize` transforms `y`. */
+  raw: number | null;
+  /** Series index in the consumer's order — the stack order, so stacking never follows a hex string. */
+  i: number;
+  /** The paintable colour for this series, baked into the row so the spec stays structural and filtering never repaints a survivor. */
+  c: string;
+  /** Series label, for Vega's own aria text. */
+  n: string;
+  /** This row belongs to the focused series — what the plot's emphasis opacity tests. */
+  f: boolean;
+}
+/** One row per period — the crosshair's own dataset, so the nearest-point selection is unambiguous. */
+interface TrendPeriodRow {
+  x: number | string;
+}
+/** A resolved band, snapped to the period domain. */
+interface TrendBandRow {
+  start: number | string;
+  end: number | string;
+  label?: string;
+}
+/** A series after normalisation, with everything the legend, headline and text equivalents need. */
+interface TrendSeriesInfo {
+  key: string;
+  label: string;
+  /** Index in the consumer's order — the identity slot, never the rank, so a filter cannot repaint the survivors. */
+  index: number;
+  color: string;
+  /** Readings by period, aligned to `TrendSummary.periods`; `null` for a gap or a period this series has no reading for. */
+  values: (number | null)[];
+  /** The plotted values, indexed when `normalize` is `index`. */
+  plotted: (number | null)[];
+  /**
+   * Whether this series mentioned each period at all, aligned to `periods`. A
+   * period it never mentioned emits no row (a short series stays short); a
+   * period it reported as `null` emits a gap row, which is what breaks a
+   * line's path instead of dropping it to zero.
+   */
+  reported: boolean[];
+  /** Periods with a finite reading. */
+  count: number;
+  first: {
+    x: number | string;
+    y: number;
+  } | null;
+  latest: {
+    x: number | string;
+    y: number;
+  } | null;
+  /** The last finite PLOTTED reading — where a direct endpoint label sits. */
+  latestPlotted: {
+    x: number | string;
+    y: number;
+  } | null;
+  min: number | null;
+  max: number | null;
+}
+interface TrendSummary {
+  xType: TrendXType;
+  granularity: ArcTimeGranularity;
+  /** The shared x domain — the union of every series' periods, in axis order. */
+  periods: (number | string)[];
+  series: TrendSeriesInfo[];
+  /** Long-form rows for the visible series, in period × series order. */
+  rows: TrendRow[];
+  /** Readings with a finite value across every visible series. */
+  count: number;
+  /** The plotted extent across the visible series — what the y scale spans. */
+  min: number | null;
+  max: number | null;
+  hasNegative: boolean;
+  /** Series folded into `Other`; 0 when nothing was folded. */
+  folded: number;
+  /** The key `focus` actually resolved to — the named series if it exists, else the first. */
+  focusKey: string;
+}
+interface TrendDelta {
+  direction: ArcDeltaDirection;
+  polarity: TrendPolarity;
+  /** Signed, formatted change: `+12.4%`, `-0.3 pp`, `+฿124K`. */
+  text: string;
+  renderedMode: ArcDeltaMode;
+  /** The same change in the other form, or `null` when it does not exist (a zero baseline has no percent). */
+  secondaryText: string | null;
+}
+/** The change one series made across the span, with the two readings behind it. */
+interface TrendSpan {
+  seriesKey: string;
+  seriesLabel: string;
+  from: {
+    x: number | string;
+    y: number;
+  };
+  to: {
+    x: number | string;
+    y: number;
+  };
+  /** The span as text — `Aug 7 – Sep 8, 2026`. */
+  rangeText: string;
+  delta: TrendDelta;
+  /** The extremes inside the span, so the description and the insight can name where it peaked and bottomed. */
+  peak: {
+    x: number | string;
+    y: number;
+  } | null;
+  trough: {
+    x: number | string;
+    y: number;
+  } | null;
+}
+/** A piece of a generated insight sentence: plain text, or a value the card sets in bold. */
+type TrendInsightSegment = string | {
+  value: string;
+};
+/** What the change tooltip explains: the two readings behind the badge and the change in both forms. */
+interface TrendDeltaExplanation {
+  seriesLabel: string;
+  fromLabel: string;
+  fromText: string;
+  toLabel: string;
+  toText: string;
+  changeText: string;
+  secondaryText: string | null;
+  renderedMode: ArcDeltaMode;
+  direction: ArcDeltaDirection;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface TrendCardLabels {
+  increase: string;
+  decrease: string;
+  unchanged: string;
+  /** Suffix for a percentage-point delta. */
+  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;
+  stale: string;
+  asOf: string;
+  tablePeriod: string;
+  tableValue: string;
+  /** Column suffix for the raw reading beside an indexed value. */
+  tableActual: string;
+  /** Label for the dotted target reference line. */
+  target: string;
+  /** Label of the series the long tail folds into. */
+  other: string;
+  /** Legend group's accessible name — `Series shown in Revenue by channel`. */
+  legendGroup: (name: string) => string;
+  /** A legend chip's accessible name — `Hide Retail` / `Show Retail`. */
+  hideSeries: (series: string) => string;
+  showSeries: (series: string) => string;
+  /** Read out after the focused series' legend chip. */
+  focused: string;
+  /** Read out on a band's legend key and its table rows. */
+  band: string;
+  /** The comparison line under the headline — `vs Aug 7`, or the span for a `change` headline. */
+  since: (period: string) => string;
+  /** Index-mode caption: `Indexed to 100 at Aug 7`. */
+  indexedAt: (period: string) => string;
+  /** Stacked-to-100% caption. */
+  normalized: 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 change group beside the value. */
+  changeGroup: (name: string) => string;
+  /** Compact label/value rows explaining the change badge. */
+  deltaExplanation: (delta: TrendDeltaExplanation) => readonly (readonly [label: string, value: string])[];
+  /** The change sentence in the card description. */
+  spanSentence: (input: {
+    word: string;
+    series: string;
+    primary: string;
+    secondary: string | null;
+    range: string;
+    from: string;
+    to: string;
+  }) => string;
+  /** Names the peak and the trough inside the span. */
+  extremesSentence: (input: {
+    peak: string;
+    peakAt: string;
+    trough: string;
+    troughAt: string;
+  }) => string;
+  /** Lists every series with its latest reading. */
+  seriesSummary: (count: number, list: string) => string;
+  /** Appended when series were folded into Other. */
+  foldedSummary: (count: number) => string;
+  /** Appended when bands are drawn. */
+  bandsSummary: (list: string) => string;
+  markNames: Record<TrendMark, string>;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    mark: string;
+    name: string;
+    seriesCount: number;
+    periodCount: number;
+    range: string;
+    min: string;
+    max: string;
+    focus: string | null;
+    target: string | null;
+    stacked: string | null;
+  }) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+  /**
+   * The generated insight, as segments so the readings and the change render in
+   * bold while the words stay plain.
+   */
+  insight: (input: {
+    series: string;
+    direction: ArcDeltaDirection;
+    from: string;
+    to: string;
+    change: string;
+    secondary: string | null;
+    range: string;
+    peak: string | null;
+    peakAt: string | null;
+  }) => TrendInsightSegment[];
+}
+declare const DEFAULT_TREND_LABELS: TrendCardLabels;
+declare function resolveTrendLabels(overrides?: Partial<TrendCardLabels>): TrendCardLabels;
+interface DeriveTrendStateInput {
+  status: TrendCardStatus;
+  /** At least one reading exists across the visible series. */
+  hasValue: boolean;
+  /** Anything is on screen already — any series at all — so a reload is a refresh, not a first load. */
+  hasData: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine. Error wins; loading over existing series 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 deriveTrendState({ status, hasValue, hasData, filtered }: DeriveTrendStateInput): TrendCardState;
+/** The key of the series the long tail folds into. Never collides with a consumer key that is a label. */
+declare const TREND_OTHER_KEY = "__other__";
+/**
+ * The granularity an x axis labels its ticks at: the tooltip and 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 — the same reason each card owns its own state machine.
+ */
+declare function trendAxisGranularity(granularity: ArcTimeGranularity): ArcTimeGranularity;
+/**
+ * The colour job, resolved against the theme's own categorical budget.
+ *
+ * The brand ships six hues and reserves three for status, so `colors.css`
+ * defines only a handful of `chart-N` identity slots. Repeating a slot would
+ * make two series look like one, so `categorical` past the budget degrades to
+ * `emphasis` — the focused series in the hue on a context-gray field, which is
+ * the FT/Few reading of a many-line chart anyway. `auto` applies the same
+ * budget without being asked.
+ */
+declare function resolveSeriesColorMode(requested: TrendSeriesColor, seriesCount: number, slots: number): TrendSeriesColorMode;
+/**
+ * The colour one series paints with. Identity slots are assigned by the
+ * series' index in the consumer's order — never by rank or by value — so
+ * hiding a series cannot repaint the survivors (rule 6). A sequential ramp
+ * spreads the ordered series across the whole ramp so the ends are always the
+ * ends, however many series there are.
+ */
+declare function seriesColorAt(index: number, seriesCount: number, mode: TrendSeriesColorMode, focusIndex: number, tokens: ChartTokens): string;
+interface NormalizeSeriesOptions {
+  granularity?: ArcTimeGranularity;
+  normalize?: TrendNormalize;
+  /** Which series is the subject — its key. Resolves to the first series when absent. */
+  focus?: string;
+  /** The keys the reader has left switched on. `undefined` shows every series. */
+  visible?: readonly string[];
+  /** Fold every series past this count (in the consumer's order) into one `Other` series whose readings are the sum of the folded finite readings. The focus is never folded. */
+  maxSeries?: number;
+  otherLabel: string;
+  colorMode: TrendSeriesColorMode;
+  tokens: ChartTokens;
+  /** Stack mode — a stacked plot's extent is the stack's total, not the tallest series. */
+  stack?: TrendStack;
+}
+/**
+ * Normalises `series` onto one shared period domain for the plot, the legend
+ * and the table: temporal `x` becomes epoch milliseconds, invalid dates are
+ * dropped, a period a series has no reading for stays a gap (never a zero),
+ * the long tail folds into `Other` when asked, and the visible series are laid
+ * out long-form with their colour and stack order baked into each row — so the
+ * spec stays structural and a visibility change is a data push, not a re-embed.
+ *
+ * Returns `null` when there are no series to speak of.
+ */
+declare function normalizeSeries(series: readonly TrendSeries[] | undefined, { granularity, normalize, focus, visible, maxSeries, otherLabel, colorMode, tokens, stack }: NormalizeSeriesOptions): TrendSummary | null;
+/** The periods the crosshair reads — one row each, so it lands on the period rather than on a series. */
+declare function buildPeriodRows(summary: TrendSummary): TrendPeriodRow[];
+/** One row per visible series at its last plotted reading — where a direct endpoint label sits. */
+declare function buildLatestRows(summary: TrendSummary, visibleKeys: readonly string[]): {
+  x: number | string;
+  y: number;
+  n: string;
+  c: string;
+}[];
+/**
+ * Snaps every band onto the period domain. Each bound moves inward to the
+ * nearest period the data actually has, so a band can never extend the axis;
+ * a band that covers no period is dropped rather than drawn as a hairline.
+ */
+declare function resolveBands(bands: readonly TrendBand[] | undefined, summary: TrendSummary | null): TrendBandRow[];
+/**
+ * The band a period falls inside — the tooltip's and the table's band marker.
+ * A continuous axis compares the values; an ordinal one compares positions in
+ * `periods`, since a category label has no order of its own. The first
+ * matching band wins, so overlapping bands are read in the consumer's order.
+ */
+declare function bandAt(bands: readonly TrendBandRow[], periods: readonly (number | string)[], x: number | string): TrendBandRow | null;
+interface DeriveTrendSpanOptions {
+  deltaMode: TrendDeltaMode;
+  goodDirection: TrendGoodDirection;
+  format: string;
+  locale?: string;
+  percentagePoints: string;
+  formatters: TrendTextFormatters;
+}
+/**
+ * The change the focused series made across the span it actually covers —
+ * first finite reading to last finite reading — with the extremes in between.
+ * `null` unless the series holds two distinct readings, so the card never
+ * invents a trend from one point.
+ */
+declare function deriveTrendSpan(summary: TrendSummary | null | undefined, focusKey: string | undefined, { deltaMode, goodDirection, format, locale, percentagePoints, formatters }: DeriveTrendSpanOptions): TrendSpan | null;
+interface DeriveTrendDeltaOptions {
+  deltaMode: TrendDeltaMode;
+  goodDirection: TrendGoodDirection;
+  format: string;
+  locale?: string;
+  percentagePoints: string;
+}
+/** A change between two readings, with polarity resolved through `goodDirection`. */
+declare function deriveTrendDelta(value: number | null | undefined, previous: number | null | undefined, { deltaMode, goodDirection, format, locale, percentagePoints }: DeriveTrendDeltaOptions): TrendDelta | null;
+interface TrendTextFormatters {
+  /** A reading in the card's own grammar. */
+  formatValue: (value: number | null | undefined) => string;
+  /** A plotted value — index points under `normalize="index"`, a share under `stack="normalize"`, else the reading. */
+  formatPlotted: (value: number | null | undefined) => string;
+  formatX: (x: number | string) => string;
+  /** A span between two `x` values — a collapsed date range for a temporal axis (`Aug 7 – Sep 8, 2026`), `start – end` otherwise. */
+  formatXRange: (start: number | string, end: number | string) => string;
+}
+/** The formatters every text surface shares — headline, badge, legend, table, tooltip, descriptions. */
+declare function createTrendFormatters({ format, locale, timeZone, formatValue, xType, granularity, normalize, stack, indexFormat }: {
+  format: string;
+  locale?: string;
+  timeZone?: string;
+  formatValue?: (value: number) => string;
+  xType: TrendXType;
+  granularity: ArcTimeGranularity;
+  normalize?: TrendNormalize;
+  stack?: TrendStack;
+  indexFormat?: string;
+}): TrendTextFormatters;
+/**
+ * The generated insight — what the card shows beside the AI mark when the
+ * consumer passes no `insight`. The focused series' two ends, its change (in
+ * the badge's form, with the other form in brackets) and its peak come back as
+ * `{ value }` segments so the card can set them in bold; the words come from
+ * `labels.insight`.
+ */
+declare function buildTrendInsight({ span, formatters, labels }: {
+  span: TrendSpan;
+  formatters: TrendTextFormatters;
+  labels: TrendCardLabels;
+}): TrendInsightSegment[];
+/** One series' reading at the hovered period, as the tooltip prints it. */
+interface TrendTooltipEntry {
+  key: string;
+  label: string;
+  color: string;
+  /** The subject — marked so a field of gray lines still says which one is the point. */
+  isFocus: boolean;
+  /** The reading in the card's own grammar. */
+  valueText: string;
+  /**
+   * What the plot actually drew, when the axis is transformed (index points or
+   * a share) — `null` when the plot draws the reading itself, so the chip shows
+   * one number rather than the same number twice.
+   */
+  plottedText: string | null;
+}
+/** Everything the hover chip shows for one period. */
+interface TrendTooltipModel {
+  periodText: string;
+  /** The annotated period the hover falls inside, named — never left to the wash. */
+  bandText: string | null;
+  /** The visible series that reported this period, ranked by what the plot drew. */
+  entries: TrendTooltipEntry[];
+  targetText: string | null;
+}
+/**
+ * The hover chip's contents for one period — pure, so the shared-x 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).
+ *
+ * Ranked descending by the PLOTTED value, so the reader compares by reading
+ * down the chip in the order the marks sit on screen. Returns `null` for a
+ * period the card does not have.
+ */
+declare function buildTrendTooltip({ summary, visibleKeys, bands, x, target, formatters, transformed }: {
+  summary: TrendSummary | null | undefined;
+  visibleKeys: readonly string[];
+  bands: readonly TrendBandRow[];
+  /** The hovered period, as it arrives on the row. */
+  x: number | string | undefined;
+  target?: number | null;
+  formatters: TrendTextFormatters;
+  /** The plot draws something other than the reading (`normalize="index"` or a 100% stack). */
+  transformed: boolean;
+}): TrendTooltipModel | null;
+interface BuildTrendDescriptionInput {
+  name: string;
+  state: TrendCardState;
+  headline: TrendHeadline;
+  summary: TrendSummary | null;
+  /** Only the series the reader has left switched on are described — the card describes what it shows. */
+  visibleKeys: readonly string[];
+  span: TrendSpan | null;
+  bands: readonly TrendBandRow[];
+  formatters: TrendTextFormatters;
+  targetText?: string | null;
+  asOfText?: string;
+  labels: TrendCardLabels;
+}
+/**
+ * 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
+ * visible series' latest reading is listed, so nothing lives only in the lines.
+ */
+declare function buildTrendDescription({ name, state, headline, summary, visibleKeys, span, bands, formatters, targetText, asOfText, labels }: BuildTrendDescriptionInput): string;
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+declare function buildTrendChartDescription({ name, mark, summary, visibleKeys, focusLabel, stack, normalize, formatters, targetText, labels }: {
+  name: string;
+  mark: TrendMark;
+  summary: TrendSummary;
+  visibleKeys: readonly string[];
+  /** Named only while colour marks one series out — otherwise nothing is emphasised. */
+  focusLabel: string | null;
+  stack: TrendStack;
+  normalize: TrendNormalize;
+  formatters: TrendTextFormatters;
+  targetText?: string | null;
+  labels: TrendCardLabels;
+}): string;
+//#endregion
+export { BuildTrendDescriptionInput, DEFAULT_TREND_LABELS, DeriveTrendDeltaOptions, DeriveTrendSpanOptions, DeriveTrendStateInput, NormalizeSeriesOptions, TREND_OTHER_KEY, TrendBand, TrendBandRow, TrendCardLabels, TrendCardSize, TrendCardState, TrendCardStatus, TrendDelta, TrendDeltaExplanation, TrendDeltaMode, TrendGoodDirection, TrendHeadline, TrendInsightSegment, TrendMark, TrendNormalize, TrendPeriodRow, TrendPoint, TrendPolarity, TrendRow, TrendScale, TrendSeries, TrendSeriesColor, TrendSeriesColorMode, TrendSeriesInfo, TrendSpan, TrendStack, TrendSummary, TrendTextFormatters, TrendTooltipEntry, TrendTooltipModel, TrendXType, bandAt, buildLatestRows, buildPeriodRows, buildTrendChartDescription, buildTrendDescription, buildTrendInsight, buildTrendTooltip, createTrendFormatters, deriveTrendDelta, deriveTrendSpan, deriveTrendState, normalizeSeries, resolveBands, resolveSeriesColorMode, resolveTrendLabels, seriesColorAt, trendAxisGranularity };