@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,497 @@
+import { ArcDeltaDirection, ArcDeltaMode, ArcTimeGranularity } from "../../lib/vega/formatters.js";
+//#region src/components/ForecastCard/ForecastCard.model.d.ts
+/** What the consumer's transport reports. */
+type ForecastCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the readings and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type ForecastCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+/** Which way is good for this measure: revenue up, cost down, headcount neutral. */
+type ForecastGoodDirection = "up" | "down" | "none";
+/** How the projected change reads once `goodDirection` is applied. Stamped as `data-polarity`. */
+type ForecastPolarity = "positive" | "negative" | "neutral";
+type ForecastDeltaMode = ArcDeltaMode;
+/**
+ * How the measured half is drawn. `line` may crop; `area` fills it from zero.
+ * The projected half is never filled from zero either way — the ink you can
+ * trust there is the interval, not the magnitude.
+ */
+type ForecastMark = "line" | "area";
+type ForecastScale = "auto" | "zero";
+type ForecastCardSize = "sm" | "md" | "lg";
+/**
+ * The big number. `landing` (default) is where the forecast ends, with its
+ * interval underneath; `latest` is the last measured reading; `change` makes
+ * the projected move itself the number; `none` leaves the plot to carry the
+ * panel. Stamped as `data-headline`.
+ */
+type ForecastHeadline = "landing" | "latest" | "change" | "none";
+type ForecastXType = "temporal" | "quantitative" | "ordinal";
+/** Which half of the axis a period belongs to — measured, or projected. */
+type ForecastKind = "actual" | "forecast";
+/**
+ * Where the target sits relative to the forecast's interval at the horizon —
+ * the verdict only a forecast WITH uncertainty can honestly give. `likely`: the
+ * whole interval reaches the target. `unlikely`: none of it does. `uncertain`:
+ * the target falls inside the interval, so the data does not decide. `none`: no
+ * target, no landing, or `goodDirection: "none"` — reaching is undefined
+ * without a direction, and the card does not guess. Stamped as `data-outlook`.
+ */
+type ForecastOutlook = "likely" | "uncertain" | "unlikely" | "none";
+/**
+ * One reading. `{ x, y }` is Cloudscape's point contract; a forecast point may
+ * also carry the bounds of its prediction interval. `y` is `null` for a period
+ * with no reading — drawn as a gap, never as zero — and `lower`/`upper` are
+ * optional per point, so a path may be certain at its start and uncertain later.
+ */
+interface ForecastPoint {
+  x: Date | string | number;
+  y: number | null;
+  /** Lower bound of the interval at this period. Ignored unless `upper` is finite too. */
+  lower?: number | null;
+  /** Upper bound of the interval at this period. */
+  upper?: number | null;
+}
+/** A period in the shape the plot reads: the value, its bounds, and which half of the axis it is on. */
+interface ForecastRow {
+  x: number | string;
+  y: number | null;
+  /** Interval bounds, `null` where the period has none. */
+  lo: number | null;
+  hi: number | null;
+  k: ForecastKind;
+  /** The paintable colour, baked into the row so the spec stays structural. */
+  c: string;
+  /** The measure's name, for Vega's own aria text. */
+  n: string;
+}
+/** One row per period — the crosshair's own dataset, so the nearest-point selection is unambiguous. */
+interface ForecastPeriodRow {
+  x: number | string;
+}
+/** The projected stretch of the axis, as a single washed rect. */
+interface ForecastRegionRow {
+  start: number | string;
+  end: number | string;
+}
+/** A period with everything the table, the tooltip and the text equivalents need. */
+interface ForecastReading {
+  x: number | string;
+  y: number | null;
+  lower: number | null;
+  upper: number | null;
+  kind: ForecastKind;
+}
+/** A reading that is certain to have a value — the latest, the landing, a crossing. */
+interface ForecastMoment {
+  x: number | string;
+  y: number;
+  lower: number | null;
+  upper: number | null;
+}
+interface ForecastSummary {
+  xType: ForecastXType;
+  granularity: ArcTimeGranularity;
+  /** Every period, measured then projected, in axis order. */
+  periods: (number | string)[];
+  /** One entry per period, in the same order — the table twin's rows. */
+  readings: ForecastReading[];
+  /**
+   * Plot rows. The last measured reading appears TWICE — once as `actual` and
+   * once as the projected path's anchor — so the solid and dashed paths meet
+   * instead of leaving a gap at the boundary. `readings` carries it once.
+   */
+  rows: ForecastRow[];
+  /** Interval rows: the anchor (a zero-width band at the last reading) and every projected period with finite bounds. */
+  interval: {
+    x: number | string;
+    lo: number;
+    hi: number;
+  }[];
+  /** The last measured period — where the axis stops being data. `null` when nothing is measured. */
+  boundary: number | string | null;
+  /** The last measured reading. */
+  latest: ForecastMoment | null;
+  /** The last projected reading — where the forecast lands. */
+  landing: ForecastMoment | null;
+  /** Measured periods carrying a finite reading. */
+  actualCount: number;
+  /** Projected periods carrying a finite reading. */
+  forecastCount: number;
+  /** Projected periods carrying a finite interval. */
+  intervalCount: number;
+  /** The extent the y scale must span — bounds included, since the band is drawn. */
+  min: number | null;
+  max: number | null;
+  hasNegative: boolean;
+}
+interface ForecastDelta {
+  direction: ArcDeltaDirection;
+  polarity: ForecastPolarity;
+  /** 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 move the forecast projects, from the last measured reading to the landing. */
+interface ForecastProjection {
+  from: ForecastMoment;
+  to: ForecastMoment;
+  /** The span as text — `Sep 7 – Nov 2, 2026`. */
+  rangeText: string;
+  delta: ForecastDelta;
+}
+/** A piece of a generated insight sentence: plain text, or a value the card sets in bold. */
+type ForecastInsightSegment = string | {
+  value: string;
+};
+/** What the change tooltip explains: the two readings behind the badge and the change in both forms. */
+interface ForecastDeltaExplanation {
+  fromLabel: string;
+  fromText: string;
+  toLabel: string;
+  toText: string;
+  changeText: string;
+  secondaryText: string | null;
+  renderedMode: ArcDeltaMode;
+  direction: ArcDeltaDirection;
+  /** The landing's interval, when it has one. */
+  rangeText: string | null;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface ForecastCardLabels {
+  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 there are fewer than two periods to draw. */
+  insufficient: string;
+  /** Caption under a plot that has history but nothing projected — a forecast card must say when it has no forecast. */
+  noForecast: string;
+  stale: string;
+  asOf: string;
+  /** Mark keys, the table's kind column and the legend row. */
+  actual: string;
+  forecast: string;
+  interval: string;
+  target: string;
+  /** The rule at the last measured period. */
+  boundary: string;
+  tablePeriod: string;
+  tableValue: string;
+  tableKind: string;
+  tableInterval: string;
+  /**
+   * The description's opening sentence: the name, the big number, and what
+   * that number IS. A caption is a fragment written for the card face, so it is
+   * placed rather than case-folded into a sentence — folding it would rewrite
+   * the date inside it.
+   */
+  headlineSentence: (input: {
+    name: string;
+    value: string;
+    caption: string;
+  }) => string;
+  /** Headline captions: what the big number IS, since a projection is not a reading. */
+  landingCaption: (period: string) => string;
+  latestCaption: (period: string) => string;
+  /** The interval under the headline — `฿2.3M – ฿2.9M`, named by its level when there is one. */
+  intervalCaption: (range: string, level: string | null) => string;
+  /**
+   * The interval's name in the key row and the tooltip — `90% interval`. A
+   * function rather than `level + interval`, so a localisation is not at the
+   * mercy of case folding or word order.
+   */
+  intervalKey: (level: string | null) => string;
+  /** A confidence level as text — `90%`. */
+  levelText: (level: number) => string;
+  /** The verdict chip. */
+  outlook: Record<Exclude<ForecastOutlook, "none">, string>;
+  /** The verdict chip's accessible explanation. */
+  outlookExplanation: (input: {
+    outlook: Exclude<ForecastOutlook, "none">;
+    target: string;
+    landing: string;
+    range: string | null;
+    horizon: string;
+  }) => string;
+  /** The crossing sentence — when the path reaches the target. */
+  crossesAt: (period: string) => string;
+  /** Shown when the path never reaches the target inside the horizon. */
+  noCrossing: 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: ForecastDeltaExplanation) => readonly (readonly [label: string, value: string])[];
+  /** The projection sentence in the card description. */
+  projectionSentence: (input: {
+    word: string;
+    primary: string;
+    secondary: string | null;
+    from: string;
+    to: string;
+    horizon: string;
+  }) => string;
+  /** The interval sentence in the card description. */
+  intervalSentence: (input: {
+    low: string;
+    high: string;
+    level: string | null;
+    horizon: string;
+  }) => string;
+  /** Names the measured span behind the projection. */
+  historySentence: (input: {
+    count: number;
+    range: string;
+    latest: string;
+  }) => string;
+  /** Appended when some projected periods carry no interval. */
+  partialIntervalSentence: (input: {
+    with: number;
+    total: number;
+  }) => string;
+  markNames: Record<ForecastMark, string>;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    mark: string;
+    name: string;
+    actualCount: number;
+    forecastCount: number;
+    range: string;
+    min: string;
+    max: string;
+    boundary: string | null;
+    interval: string | null;
+    target: 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: {
+    name: string;
+    direction: ArcDeltaDirection;
+    from: string;
+    to: string;
+    change: string;
+    horizon: string;
+    low: string | null;
+    high: string | null;
+    level: string | null;
+    outlook: ForecastOutlook;
+    target: string | null;
+    crossesAt: string | null;
+  }) => ForecastInsightSegment[];
+}
+declare const DEFAULT_FORECAST_LABELS: ForecastCardLabels;
+declare function resolveForecastLabels(overrides?: Partial<ForecastCardLabels>): ForecastCardLabels;
+interface DeriveForecastStateInput {
+  status: ForecastCardStatus;
+  /** At least one reading exists, measured or projected. */
+  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 deriveForecastState({ status, hasValue, hasData, filtered }: DeriveForecastStateInput): ForecastCardState;
+/**
+ * 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 — the same reason each card owns its own state machine.
+ */
+declare function forecastAxisGranularity(granularity: ArcTimeGranularity): ArcTimeGranularity;
+interface NormalizeForecastOptions {
+  granularity?: ArcTimeGranularity;
+  /** The measure's name, baked into every row for Vega's aria text. */
+  name: string;
+  /** The one hue the whole card paints with — actual, forecast and interval are the same measure. */
+  color: string;
+}
+/**
+ * Lays the measured and the projected readings onto one period domain.
+ *
+ * The two halves stay distinguishable at every level: each period carries its
+ * `kind`, the projected half is the only one with interval bounds, and the plot
+ * rows repeat the last measured reading as the projected path's ANCHOR so the
+ * solid and dashed paths meet — the interval opens from that anchor at zero
+ * width, which is what makes a fan read as growing uncertainty rather than as a
+ * band that appears from nowhere. `readings` carries the anchor once, so the
+ * table and the description never double-count it.
+ *
+ * A projected period that repeats a measured one is dropped: a forecast cannot
+ * overwrite a reading. Returns `null` when there is nothing at all to show.
+ */
+declare function normalizeForecast(actual: readonly ForecastPoint[] | undefined, forecast: readonly ForecastPoint[] | undefined, { granularity, name, color }: NormalizeForecastOptions): ForecastSummary | null;
+/** The periods the crosshair reads — one row each, so it lands on the period rather than on a mark. */
+declare function buildForecastPeriodRows(summary: ForecastSummary): ForecastPeriodRow[];
+/**
+ * The projected stretch as one washed rect, from the last measured period to
+ * the horizon — the ground under everything the card did not measure. Empty
+ * when nothing is projected, so a card with history alone draws no wash.
+ */
+declare function buildForecastRegionRows(summary: ForecastSummary): ForecastRegionRow[];
+/** Zero or one row — the rule at the last measured period. */
+declare function buildForecastBoundaryRows(summary: ForecastSummary): ForecastPeriodRow[];
+/** Zero or one row — where the landing label sits. */
+declare function buildForecastLandingRows(summary: ForecastSummary, text: string): {
+  x: number | string;
+  y: number;
+  n: string;
+  c: string;
+}[];
+/** Whether a value reaches the target, given which direction is good. `null` when reaching is undefined. */
+declare function reachesTarget(value: number, target: number, goodDirection: ForecastGoodDirection): boolean | null;
+interface DeriveForecastOutlookInput {
+  landing: ForecastMoment | null;
+  target?: number | null;
+  goodDirection: ForecastGoodDirection;
+}
+/**
+ * The verdict the interval supports, and nothing more: `likely` when the WHOLE
+ * interval reaches the target, `unlikely` when none of it does, `uncertain`
+ * when the target falls inside it — the honest answer a point estimate cannot
+ * give. Without an interval the point estimate decides between `likely` and
+ * `unlikely` (the card says so in its explanation); without a target, a landing
+ * or a direction, there is no verdict at all.
+ */
+declare function deriveForecastOutlook({ landing, target, goodDirection }: DeriveForecastOutlookInput): ForecastOutlook;
+/**
+ * The first projected period whose reading reaches the target — the "when" a
+ * forecast is really asked for. `null` when the last measured reading already
+ * reaches it (there is nothing to wait for), when the path never gets there, or
+ * when reaching is undefined.
+ */
+declare function deriveForecastCrossing(summary: ForecastSummary | null | undefined, target: number | null | undefined, goodDirection: ForecastGoodDirection): ForecastMoment | null;
+interface DeriveForecastDeltaOptions {
+  deltaMode: ForecastDeltaMode;
+  goodDirection: ForecastGoodDirection;
+  format: string;
+  locale?: string;
+  percentagePoints: string;
+}
+/** A change between two readings, with polarity resolved through `goodDirection`. */
+declare function deriveForecastDelta(value: number | null | undefined, previous: number | null | undefined, { deltaMode, goodDirection, format, locale, percentagePoints }: DeriveForecastDeltaOptions): ForecastDelta | null;
+interface DeriveForecastProjectionOptions extends DeriveForecastDeltaOptions {
+  formatters: ForecastTextFormatters;
+}
+/**
+ * The move from the last measured reading to the landing. `null` unless the
+ * card has both — a forecast with no history to leave from, or a history with
+ * nothing projected, has no projected change to state.
+ */
+declare function deriveForecastProjection(summary: ForecastSummary | null | undefined, { formatters, ...deltaOptions }: DeriveForecastProjectionOptions): ForecastProjection | null;
+interface ForecastTextFormatters {
+  /** A reading in the card's own grammar. */
+  formatValue: (value: number | null | undefined) => string;
+  formatX: (x: number | string) => string;
+  /** A span between two `x` values — a collapsed date range for a temporal axis, `start – end` otherwise. */
+  formatXRange: (start: number | string, end: number | string) => string;
+  /** An interval as text — `฿2.3M – ฿2.9M`. `null` when either bound is missing. */
+  formatInterval: (lower: number | null | undefined, upper: number | null | undefined) => string | null;
+}
+/** The formatters every text surface shares — headline, badge, table, tooltip, descriptions. */
+declare function createForecastFormatters({ format, locale, timeZone, formatValue, xType, granularity }: {
+  format: string;
+  locale?: string;
+  timeZone?: string;
+  formatValue?: (value: number) => string;
+  xType: ForecastXType;
+  granularity: ArcTimeGranularity;
+}): ForecastTextFormatters;
+/** Everything the hover chip shows for one period. */
+interface ForecastTooltipModel {
+  periodText: string;
+  kind: ForecastKind;
+  kindText: string;
+  valueText: string;
+  /** The interval at this period, or `null` where there is none. */
+  intervalText: string | null;
+  targetText: string | null;
+}
+/**
+ * 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 buildForecastTooltip({ summary, x, target, formatters, labels }: {
+  summary: ForecastSummary | null | undefined;
+  /** The hovered period, as it arrives on the row. */
+  x: number | string | undefined;
+  target?: number | null;
+  formatters: ForecastTextFormatters;
+  labels: ForecastCardLabels;
+}): ForecastTooltipModel | null;
+interface BuildForecastInsightInput {
+  name: string;
+  summary: ForecastSummary;
+  projection: ForecastProjection | null;
+  outlook: ForecastOutlook;
+  crossing: ForecastMoment | null;
+  target?: number | null;
+  level?: number | null;
+  formatters: ForecastTextFormatters;
+  labels: ForecastCardLabels;
+}
+/**
+ * The generated insight — what the card shows beside the AI mark when the
+ * consumer passes no `insight`: where the measure lands, the move that takes it
+ * there, the interval around it, and what that means for the target. Values
+ * come back as `{ value }` segments so the card can set them in bold.
+ */
+declare function buildForecastInsight({ name, summary, projection, outlook, crossing, target, level, formatters, labels }: BuildForecastInsightInput): ForecastInsightSegment[] | null;
+interface BuildForecastDescriptionInput {
+  name: string;
+  state: ForecastCardState;
+  headline: ForecastHeadline;
+  summary: ForecastSummary | null;
+  projection: ForecastProjection | null;
+  outlook: ForecastOutlook;
+  crossing: ForecastMoment | null;
+  target?: number | null;
+  level?: number | null;
+  formatters: ForecastTextFormatters;
+  asOfText?: string;
+  labels: ForecastCardLabels;
+}
+/**
+ * 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. The
+ * landing, its interval, the measured span behind it and the verdict are all
+ * here, so nothing the plot says lives only in the marks.
+ */
+declare function buildForecastDescription({ name, state, headline, summary, projection, outlook, crossing, target, level, formatters, asOfText, labels }: BuildForecastDescriptionInput): string;
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+declare function buildForecastChartDescription({ name, mark, summary, level, formatters, targetText, labels }: {
+  name: string;
+  mark: ForecastMark;
+  summary: ForecastSummary;
+  level?: number | null;
+  formatters: ForecastTextFormatters;
+  targetText?: string | null;
+  labels: ForecastCardLabels;
+}): string;
+//#endregion
+export { BuildForecastDescriptionInput, BuildForecastInsightInput, DEFAULT_FORECAST_LABELS, DeriveForecastDeltaOptions, DeriveForecastOutlookInput, DeriveForecastProjectionOptions, DeriveForecastStateInput, ForecastCardLabels, ForecastCardSize, ForecastCardState, ForecastCardStatus, ForecastDelta, ForecastDeltaExplanation, ForecastDeltaMode, ForecastGoodDirection, ForecastHeadline, ForecastInsightSegment, ForecastKind, ForecastMark, ForecastMoment, ForecastOutlook, ForecastPeriodRow, ForecastPoint, ForecastPolarity, ForecastProjection, ForecastReading, ForecastRegionRow, ForecastRow, ForecastScale, ForecastSummary, ForecastTextFormatters, ForecastTooltipModel, ForecastXType, NormalizeForecastOptions, buildForecastBoundaryRows, buildForecastChartDescription, buildForecastDescription, buildForecastInsight, buildForecastLandingRows, buildForecastPeriodRows, buildForecastRegionRows, buildForecastTooltip, createForecastFormatters, deriveForecastCrossing, deriveForecastDelta, deriveForecastOutlook, deriveForecastProjection, deriveForecastState, forecastAxisGranularity, normalizeForecast, reachesTarget, resolveForecastLabels };