@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,468 @@
+import { ArcDeltaDirection, ArcDeltaMode } from "../../lib/vega/formatters.js";
+//#region src/components/TargetCard/TargetCard.model.d.ts
+/** What the consumer's transport reports. */
+type TargetCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the value, the target
+ * and `filtered`. Stamped on the root as `data-state`.
+ */
+type TargetCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+/**
+ * Which way the target is reached: `up` — reach at least the target (a quota,
+ * a goal); `down` — stay at or under it (a budget, an error cap). A plan value
+ * that is neither is MetricCard's `goodDirection="none"` with a `target`.
+ */
+type TargetGoodDirection = "up" | "down";
+/** How a change reads once `goodDirection` is applied. Stamped as `data-polarity`. */
+type TargetPolarity = "positive" | "negative" | "neutral";
+type TargetDeltaMode = ArcDeltaMode;
+type TargetCardSize = "sm" | "md" | "lg";
+/** What the big number is: the attainment percentage (default) or the reading itself. Stamped as `data-headline`. */
+type TargetHeadline = "attainment" | "value";
+/**
+ * The judgement the card reaches, stamped as `data-track`: `achieved` (the
+ * target is met — at once for an `up` target, once the period has ended within
+ * it for a `down` one), `missed` (the period ended short of an `up` target, or
+ * a `down` target was exceeded), and the pace verdicts while the period runs —
+ * `on-track` (at or better than the plan expects by now), `at-risk` (behind by
+ * no more than `tolerance` of the target) and `off-track`.
+ */
+type TargetTrack = "achieved" | "on-track" | "at-risk" | "off-track" | "missed";
+/** The reading against what the plan expects by now, after `goodDirection`: better, worse, or equal. */
+type TargetPaceStatus = "ahead" | "behind" | "on";
+/** The bar's hue: the emphasis hue while the target is open, the positive hue once achieved, the negative hue once missed. */
+type TargetTone = "primary" | "positive" | "negative";
+/**
+ * The goal period. `start` and `end` are inclusive calendar dates when given
+ * as date-only ISO strings (`"2026-09-01"` – `"2026-09-30"` is the whole of
+ * September, midnight to midnight in the card's `timeZone`), or exact
+ * instants when given as `Date`s, timestamps or date-times. `label` names the
+ * period (`September 2026`, `Q3 FY26`) for the period line.
+ */
+interface TargetPeriod {
+  start: Date | string | number;
+  end: Date | string | number;
+  label?: string;
+}
+/** The period as instants: `[start, end)` in epoch milliseconds. */
+interface TargetPeriodBounds {
+  start: number;
+  end: number;
+  label?: string;
+  /** Both bounds were calendar dates, so the period line shows them as a date range rather than instants. */
+  dateOnly: boolean;
+}
+/** How far the period has run at the card's `updatedAt`. */
+interface TargetElapsed {
+  /** Elapsed share of the period, clamped to `[0, 1]`. */
+  fraction: number;
+  /** The unclamped share — below 0 before the period, above 1 after it. */
+  rawFraction: number;
+  started: boolean;
+  ended: boolean;
+  /** `fraction` as text — `61%`. */
+  percentText: string;
+}
+/** A change between two readings in the card's `deltaMode`, with polarity resolved through `goodDirection`. */
+interface TargetDelta {
+  direction: ArcDeltaDirection;
+  polarity: TargetPolarity;
+  /** Signed, formatted change: `+6.4%`, `-฿152K`, `-0.3 pp`. */
+  text: string;
+  renderedMode: ArcDeltaMode;
+  /** The same change in the other form, or `null` when it does not exist (a zero reference has no percent). */
+  secondaryText: string | null;
+}
+/** The reading against what the plan expects by now. */
+interface TargetPace {
+  /** The value the plan expects by `updatedAt` — an explicit `expected`, else `target × elapsed`. */
+  expected: number;
+  expectedRatio: number;
+  expectedText: string;
+  /** `expectedRatio` as text — `61%`. */
+  expectedPercentText: string;
+  /** The reading against the expectation in the card's `deltaMode`. */
+  delta: TargetDelta;
+  /** The same gap in percentage points of the target — `+3.9 pp`. */
+  pointsText: string;
+  status: TargetPaceStatus;
+  /** Whether the pace came from the period (`linear`) or from an explicit `expected` (`explicit`). */
+  source: "linear" | "explicit";
+}
+/** Where the reading lands at the period's end. */
+interface TargetProjection {
+  value: number;
+  ratio: number;
+  text: string;
+  percentText: string;
+  /** Whether the projection came from the run rate (`linear`) or from an explicit `projected` (`explicit`). */
+  source: "linear" | "explicit";
+  /** The projection reaches beyond the reading (away from zero), so the plot extends the bar to it. */
+  extends: boolean;
+}
+/** The plot's x domain — always spanning zero, the target and every marker. */
+interface TargetBounds {
+  min: number;
+  max: number;
+}
+/** Everything the card derives from the reading and the target. */
+interface TargetProgress {
+  value: number;
+  target: number;
+  /** `value / target`, unclamped — 1.1 is 110% of target, -0.24 is a loss against a profit target. */
+  ratio: number;
+  valueText: string;
+  targetText: string;
+  /** `ratio` as text — `65%`. */
+  percentText: string;
+  /** The reading is at or beyond the target in the good direction — an `up` target reached, a `down` one still within. */
+  withinTarget: boolean;
+  /** The reading is past the target: `over` — else `remaining` (the distance still to go, or the headroom left under a cap). */
+  gapKind: "remaining" | "over";
+  /** `|target − value|`, formatted. */
+  gapText: string;
+  /** The reading against the target itself in the card's `deltaMode` — the badge when there is no pace. */
+  targetDelta: TargetDelta;
+  elapsed: TargetElapsed | null;
+  pace: TargetPace | null;
+  projection: TargetProjection | null;
+  track: TargetTrack | null;
+  tone: TargetTone;
+  bounds: TargetBounds;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface TargetCardLabels {
+  /** After the attainment percentage — `65% of target`. */
+  ofTarget: string;
+  /**
+   * Joins the reading and the target once they share a symbol and a magnitude
+   * — `฿2.6/4M`, `187/200 ms`, `2.7/3%`. Default `/`.
+   */
+  pairSeparator: string;
+  /** The line under an attainment headline when the pair cannot be collapsed — `฿850K of ฿4M`. */
+  readingLine: (value: string, target: string) => string;
+  /** The line under a value headline — `65% of ฿4M`. */
+  attainmentLine: (percent: string, target: string) => string;
+  target: string;
+  /** The reading's name in the legend, tooltip and table — `Reached`. */
+  reached: string;
+  /** The distance still to go, or the headroom under a cap. */
+  remaining: string;
+  /** The amount past the target. */
+  overBy: string;
+  expectedByNow: string;
+  /** Comparison line and table row when the reading beats the plan — `ahead of pace` for a goal, `under pace` for a budget. */
+  aheadOfPace: (direction: TargetGoodDirection) => string;
+  /** … and when it trails the plan — `behind pace`, `over pace`. */
+  behindPace: (direction: TargetGoodDirection) => string;
+  onPace: string;
+  /** Comparison line under the badge when there is no pace — the badge then compares the reading with the target. */
+  vsTarget: string;
+  aboveTarget: string;
+  belowTarget: string;
+  onTarget: string;
+  projected: string;
+  period: string;
+  /** Names a week-shaped period. `year` is that week's year, already formatted in the card's locale and calendar. */
+  week: (weekNumber: number, year: string) => string;
+  /** Names a quarter-shaped period — `Q3 2026`. */
+  quarter: (quarter: number, year: string) => string;
+  /** The elapsed share, on its own line under the period's name — `62% elapsed`. */
+  elapsed: (percent: string) => string;
+  /** The table row naming the elapsed share. */
+  elapsedRow: string;
+  /** The table row naming how much of the period has gone in whole days. */
+  daysRow: string;
+  /** Whole days elapsed against the period's own length — `18 of 30`. */
+  days: (elapsed: number, total: number) => string;
+  /** The status chip's words per verdict. */
+  trackNames: Record<TargetTrack, string>;
+  /** The table row naming the verdict. */
+  trackRow: string;
+  /** Spoken direction words for the badge glyph. */
+  increase: string;
+  decrease: string;
+  unchanged: string;
+  /** Suffix for a percentage-point delta. */
+  percentagePoints: string;
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  /** Caption in the plot's place when a reading exists but no target does. */
+  noTarget: string;
+  stale: string;
+  asOf: string;
+  tableItem: string;
+  tableValue: string;
+  /** Column headers of the change's two forms in the explanation rows. */
+  changePercent: string;
+  changeAmount: string;
+  markNames: {
+    actual: string;
+    pace: string;
+    target: string;
+    projection: 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 badge stack — `Revenue against its target`. */
+  progressGroup: (name: string) => string;
+  /** Accessible name of the status chip — `Revenue status`. */
+  trackGroup: (name: string) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+  /** Compact label/value rows explaining the badge — the reading, the reference it is measured against and the change in both forms. */
+  explanation: (input: TargetExplanationInput) => readonly (readonly [label: string, value: string])[];
+  /** The description's attainment sentence — `Revenue: 65% of target (฿2.61M of ฿4M).` */
+  attainmentSentence: (input: {
+    name: string;
+    percent: string;
+    value: string;
+    target: string;
+  }) => string;
+  /** The description's gap sentence — `Remaining ฿1.39M.` / `Over by ฿150K.` */
+  gapSentence: (input: {
+    kind: "remaining" | "over";
+    amount: string;
+  }) => string;
+  /** The description's pace sentence. `primary` is the unsigned change (empty when on pace), `secondary` its other form or `null`. */
+  paceSentence: (input: {
+    word: string;
+    primary: string;
+    secondary: string | null;
+    expectedPercent: string;
+    elapsedPercent: string | null;
+  }) => string;
+  /** The description's projection sentence — `Projected ฿4.24M (106% of target).` */
+  projectionSentence: (input: {
+    value: string;
+    percent: string;
+  }) => string;
+  /**
+   * The description's period sentence — `Period Sep 2026 (Sep 1 – 30, 2026).`
+   * `name` is what the footer shows; `range` spells the bounds out, and is
+   * dropped when the name already is the range.
+   */
+  periodSentence: (input: {
+    name: string;
+    range: string;
+  }) => string;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    name: string;
+    value: string;
+    percent: string;
+    target: string;
+    expected: string | null;
+    expectedPercent: string | null;
+    projected: string | null;
+    projectedPercent: string | null;
+  }) => string;
+}
+/** What the badge explanation and the popover rows are built from. */
+interface TargetExplanationInput {
+  /** `pace` when the badge compares the reading with the plan's expectation, `target` when with the target itself. */
+  kind: "pace" | "target";
+  direction: TargetGoodDirection;
+  valueText: string;
+  percentText: string;
+  targetText: string;
+  gapKind: "remaining" | "over";
+  gapText: string;
+  expectedText: string | null;
+  expectedPercentText: string | null;
+  delta: TargetDelta;
+  paceStatus: TargetPaceStatus | null;
+}
+declare const DEFAULT_TARGET_LABELS: TargetCardLabels;
+declare function resolveTargetLabels(overrides?: Partial<TargetCardLabels>): TargetCardLabels;
+interface DeriveTargetStateInput {
+  status: TargetCardStatus;
+  /** A finite reading exists. */
+  hasValue: boolean;
+  /** Anything is on screen already — a reading or a target — so a reload is a refresh, not a first load. */
+  hasData: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine. Error wins; loading over existing data is a refresh (the
+ * previous render stays under the veil); a missing reading is `no-match` when
+ * the consumer's filter caused it and `empty` otherwise. A reading without a
+ * target is `ready` — the card then shows the reading and says no target is
+ * set (`data-insufficient`).
+ */
+declare function deriveTargetState({ status, hasValue, hasData, filtered }: DeriveTargetStateInput): TargetCardState;
+/**
+ * The period as instants in the card's time zone. A date-only bound is a
+ * whole calendar day: `start` opens at its midnight and `end` closes at the
+ * midnight after it, so `"2026-09-01"` – `"2026-09-30"` is all of September
+ * (30 days, not 29). Any other form is the exact instant. `null` when a bound
+ * cannot be parsed or the period has no length.
+ */
+declare function resolvePeriod(period: TargetPeriod | undefined, timeZone?: string): TargetPeriodBounds | null;
+/**
+ * How far the period has run at `asOf`. The fraction is clamped for the
+ * plan's expectation (nothing is expected before the start, everything by the
+ * end); `rawFraction` keeps the overshoot so a reading after the end knows
+ * the period is over. `null` when `asOf` is missing or unparseable.
+ */
+declare function deriveElapsed(bounds: TargetPeriodBounds | null | undefined, asOf: Date | string | number | null | undefined, locale?: string): TargetElapsed | null;
+/** The whole days a date-only period spans. */
+declare function periodDays(bounds: TargetPeriodBounds): number;
+/** How much of the period has gone in whole days, against its own length. */
+interface TargetDays {
+  /** Whole days between the period's first day and the day `asOf` falls on, clamped to the period. */
+  elapsed: number;
+  total: number;
+}
+interface TargetTextFormatters {
+  formatValue: (value: number | null | undefined) => string;
+  /** A ratio of the target as a whole percentage — `65%`. */
+  formatPercent: (ratio: number | null | undefined) => string;
+}
+/** The formatters every text surface shares — headline, badge, plot tooltip, table, descriptions. */
+declare function createTargetFormatters({ format, locale, formatValue }: {
+  format: string;
+  locale?: string;
+  formatValue?: (value: number) => string;
+}): TargetTextFormatters;
+/**
+ * Joins a reading and its target into one compact pair — `฿2.6M` and `฿4M`
+ * become `฿2.6/4M`, `187 ms` and `200 ms` become `187/200 ms`, `2.7%` and `3%`
+ * become `2.7/3%` — by lifting out the symbol they both start with and the
+ * magnitude they both end with. A leading sign stays on the reading
+ * (`-฿120/500K`).
+ *
+ * Returns `null` whenever the two cannot share their parts — `฿850K` against
+ * `฿4M` is not `฿850/4M`, and a locale or formatter this heuristic does not
+ * recognise must not be guessed at — so the caller falls back to the full
+ * `X of Y` line rather than printing something untrue.
+ */
+declare function formatValuePair(valueText: string, targetText: string, separator?: string): string | null;
+interface DeriveTargetDeltaOptions {
+  deltaMode: TargetDeltaMode;
+  goodDirection: TargetGoodDirection;
+  format: string;
+  locale?: string;
+  percentagePoints: string;
+}
+/** The reading against a reference (the target, or the plan's expectation), with polarity resolved through `goodDirection`. */
+declare function deriveTargetDelta(value: number, reference: number, { deltaMode, goodDirection, format, locale, percentagePoints }: DeriveTargetDeltaOptions): TargetDelta;
+interface DeriveTargetProgressInput extends DeriveTargetDeltaOptions {
+  value: number | null | undefined;
+  target: number | null | undefined;
+  formatters: TargetTextFormatters;
+  /** How far behind the plan, as a share of the target, still counts as at risk rather than off track. */
+  tolerance: number;
+  elapsed: TargetElapsed | null;
+  /** The plan's own expectation by now; `undefined` derives it from `elapsed`, `null` disables pace. */
+  expected?: number | null;
+  /** The consumer's own forecast; `undefined` derives the run rate from `elapsed`, `null` disables the projection. */
+  projected?: number | null;
+}
+/**
+ * Attainment, pace, projection and verdict — `null` without a finite reading
+ * and a finite, non-zero target (a zero target has no ratio).
+ *
+ * Pace is `target × elapsed` unless the product supplies its own `expected`
+ * (a seasonal plan curve); the projection is the linear run rate
+ * `value / elapsed` unless the product supplies `projected` — both are
+ * declared as such in `source`, and a run rate is only projected while the
+ * period is still running with some of it elapsed. The verdict: an `up`
+ * target is achieved the moment the reading reaches it and missed once the
+ * period ends short of it; a `down` target is missed the moment the reading
+ * exceeds it and achieved once the period ends within it. While the period
+ * runs, the gap to the plan's expectation in points of the target decides
+ * between on track, at risk (behind by no more than `tolerance`) and off
+ * track. Without a period or an `expected` there is no pace and no verdict
+ * short of achieved or missed.
+ */
+declare function deriveTargetProgress({ value, target, formatters, tolerance, elapsed, expected, projected, ...deltaOptions }: DeriveTargetProgressInput): TargetProgress | null;
+/** The word the pace badge's comparison line and explanation use for the reading's standing against the plan. */
+declare function paceWord(pace: TargetPace, direction: TargetGoodDirection, labels: TargetCardLabels): string;
+/** The rows behind the badge: the reading against the plan's expectation when there is a pace, else against the target. */
+declare function buildTargetExplanation(progress: TargetProgress, direction: TargetGoodDirection, labels: TargetCardLabels): readonly (readonly [label: string, value: string])[];
+/** One row of the details table — the table twin of the bullet graph. `tone` colours a change; `mark` keys the row to a mark in the plot. */
+interface TargetDetailRow {
+  key: string;
+  label: string;
+  value: string;
+  tone?: TargetPolarity;
+  mark?: keyof TargetCardLabels["markNames"];
+}
+interface BuildTargetDetailRowsInput {
+  progress: TargetProgress;
+  direction: TargetGoodDirection;
+  periodText: string | null;
+  /** Whole days elapsed and the period's length, from `deriveDays`. */
+  days?: TargetDays | null;
+  labels: TargetCardLabels;
+}
+/**
+ * Every value the card shows, as label/value rows: target, reading, the gap,
+ * the plan's expectation and the pace against it, the elapsed share, the
+ * projection, the period and the verdict — the popover's table, so nothing
+ * lives only in the plot or on hover.
+ */
+declare function buildTargetDetailRows({ progress, direction, periodText, days, labels }: BuildTargetDetailRowsInput): TargetDetailRow[];
+/** The period as text — the label, the date range, or both — for the period line and the descriptions. */
+/**
+ * What calendar unit the period actually is, read off its own bounds — a goal
+ * set for a week, a month, a quarter or a year names itself the way the
+ * business does (`Week 32`, `Sep 2026`, `Q3 2026`, `2026`) instead of
+ * repeating a date range, and anything else is `custom`.
+ */
+type TargetPeriodShape = "week" | "month" | "quarter" | "year" | "custom";
+/** The period as the footer and the descriptions speak it. */
+interface TargetPeriodText {
+  /** The consumer's `label` when it named the period, else the name its shape earns. */
+  name: string;
+  shape: TargetPeriodShape;
+  /** Whether `name` came from the consumer's `label`. */
+  labelled: boolean;
+  /** The bounds spelled out — `Sep 1 – 30, 2026` — for the popover table and the description. */
+  range: string;
+}
+/**
+ * Names the period and spells out its bounds. The name is the consumer's
+ * `label` when it gave one; otherwise the period's own shape supplies it
+ * (`Week 32`, `Sep 2026`, `Q3 2026`, `2026`), and a shape the calendar has no
+ * word for falls back to the range itself. Every part goes through `Intl` in
+ * the card's locale and zone, so a Thai card on the Buddhist calendar reads
+ * `ก.ย. 2569` while the arithmetic stays Gregorian.
+ */
+declare function formatPeriod(bounds: TargetPeriodBounds | null, { locale, timeZone, labels }: {
+  locale?: string;
+  timeZone?: string;
+  labels?: TargetCardLabels;
+}): TargetPeriodText | null;
+interface BuildTargetDescriptionInput {
+  name: string;
+  state: TargetCardState;
+  /** The formatted reading, for a card that has one but no target. */
+  valueText: string;
+  progress: TargetProgress | null;
+  direction: TargetGoodDirection;
+  periodText: TargetPeriodText | null;
+  asOfText?: string;
+  labels: TargetCardLabels;
+}
+/**
+ * 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.
+ */
+declare function buildTargetDescription({ name, state, valueText, progress, direction, periodText, asOfText, labels }: BuildTargetDescriptionInput): string;
+/** The bullet graph's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+declare function buildTargetChartDescription({ name, progress, labels }: {
+  name: string;
+  progress: TargetProgress;
+  labels: TargetCardLabels;
+}): string;
+//#endregion
+export { BuildTargetDescriptionInput, BuildTargetDetailRowsInput, DEFAULT_TARGET_LABELS, DeriveTargetDeltaOptions, DeriveTargetProgressInput, DeriveTargetStateInput, TargetBounds, TargetCardLabels, TargetCardSize, TargetCardState, TargetCardStatus, TargetDays, TargetDelta, TargetDeltaMode, TargetDetailRow, TargetElapsed, TargetExplanationInput, TargetGoodDirection, TargetHeadline, TargetPace, TargetPaceStatus, TargetPeriod, TargetPeriodBounds, TargetPeriodShape, TargetPeriodText, TargetPolarity, TargetProgress, TargetProjection, TargetTextFormatters, TargetTone, TargetTrack, buildTargetChartDescription, buildTargetDescription, buildTargetDetailRows, buildTargetExplanation, createTargetFormatters, deriveElapsed, deriveTargetDelta, deriveTargetProgress, deriveTargetState, formatPeriod, formatValuePair, paceWord, periodDays, resolvePeriod, resolveTargetLabels };