@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,385 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+//#region src/components/ProgressCard/ProgressCard.model.d.ts
+/** What the consumer's transport reports. */
+type ProgressCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the snapshots and
+ * `filtered`. Stamped on the root as `data-state`. `insufficient` is a run
+ * with fewer than two readings: there is a completion to show but no
+ * trajectory to draw and no rate to project from, so the plot degrades to the
+ * bar and says so rather than inventing a trend from one point.
+ */
+type ProgressCardState = "loading" | "refreshing" | "ready" | "insufficient" | "empty" | "no-match" | "error";
+type ProgressCardSize = "sm" | "md" | "lg";
+/**
+ * What the big number is: the finished share (default), the date the work is
+ * projected to finish, or how much is left. Stamped as `data-headline`.
+ */
+type ProgressHeadline = "percent" | "date" | "remaining";
+/**
+ * The judgement the card reaches, stamped as `data-verdict`. `done` — every
+ * unit is finished. `on-time` — the current rate lands on or before the due
+ * date. `at-risk` — it lands after it but within `tolerance` days.
+ * `late` — beyond that. `stalled` — nothing has been finished across the
+ * rate window, so there is no rate to project with and the work is not
+ * moving. Without a `due` date there is no verdict short of `done` and
+ * `stalled`: a projection with nothing to measure it against is not a
+ * judgement.
+ */
+type ProgressVerdict = "done" | "on-time" | "at-risk" | "late" | "stalled";
+/** How a reading reads once the deadline is applied. Stamped as `data-polarity`. */
+type ProgressPolarity = "positive" | "negative" | "neutral";
+/**
+ * What a stage means for completion, for the optional breakdown bar.
+ * `complete` is finished work, `active` is in flight (the default), `blocked`
+ * has stopped and needs someone, `remaining` is not started.
+ */
+type ProgressStageTone = "complete" | "active" | "blocked" | "remaining";
+/**
+ * One reading of the run: how much was finished by `date`, and what the whole
+ * was at that moment.
+ */
+interface ProgressSnapshot {
+  /** When the reading was taken. Date-only ISO strings are midnight in the card's `timeZone`. */
+  date: Date | string | number;
+  /**
+   * Cumulative units finished by then — the running total, not the delta.
+   * `null` is a reading the transport missed: the line breaks at it rather
+   * than drawing through it.
+   */
+  completed: number | null;
+  /**
+   * The whole as it stood at that moment. Defaults to the card's `total`, so
+   * a run whose scope never moved needs only `completed`. Passing it per
+   * snapshot is what makes a scope change visible instead of hidden — the
+   * reason this card is a burn-up.
+   */
+  total?: number | null;
+}
+/** A snapshot placed on the run. */
+interface ProgressPoint {
+  /** The reading's instant, in epoch milliseconds. */
+  t: number;
+  /** Units finished, or `null` for a missed reading. */
+  completed: number | null;
+  /** The whole at that instant. */
+  total: number;
+}
+/** Where the current rate lands. */
+interface ProgressProjection {
+  /** The instant the run reaches its scope at the observed rate. */
+  date: number;
+  /** Whole days between the due date and that instant — negative is early, positive is late. */
+  daysLate: number;
+  /** The projection lands after the due date. */
+  late: boolean;
+  /** Formatted finish date, in the card's locale, zone and `updatedAtFormat`. */
+  dateText: string;
+  /** `2 days late` / `3 days early` / `on the due date`, or the bare date when there is no deadline. */
+  text: string;
+  /** Whether the rate came from the readings (`observed`) or from the consumer's own forecast (`explicit`). */
+  source: "observed" | "explicit";
+}
+/** The rate the work is being finished at. */
+interface ProgressRate {
+  /** Units per day across the rate window. */
+  perDay: number;
+  /** Days the rate was measured over. */
+  days: number;
+  /** Units per day the deadline needs from now on — `remaining / days left`; `null` without a due date or once it has passed. */
+  requiredPerDay: number | null;
+  /** `12 tables/day`, in the card's grammar. */
+  text: string;
+  /** The required rate in the same grammar, or `null`. */
+  requiredText: string | null;
+}
+/** One stage of the optional breakdown bar. */
+interface ProgressStageInput {
+  /** Identifies the stage; defaults to `label`. */
+  key?: string;
+  /** The stage's name — the legend row and the bar's accessible name. */
+  label: string;
+  /** Units in this stage. `null` keeps the row with no segment; a count cannot be negative, so a negative reads `—`. */
+  value: number | null;
+  /** What the stage means for completion. Default `active`. */
+  tone?: ProgressStageTone;
+}
+/** A stage placed on the breakdown bar. */
+interface ProgressStage {
+  key: string;
+  label: string;
+  value: number;
+  missing: boolean;
+  tone: ProgressStageTone;
+  /** `value / total`, in `[0, 1]`. */
+  share: number;
+  /** The segment's width as a CSS percentage string. */
+  width: string;
+  valueText: string;
+  shareText: string;
+  /** The card synthesised this stage from the units the parts left unaccounted. */
+  implicit: boolean;
+}
+/** Everything the card derives from the snapshots and the deadline. */
+interface ProgressRun {
+  /** Readings in chronological order. */
+  points: ProgressPoint[];
+  /** Readings that carry a count — what the line can actually draw. */
+  observed: ProgressPoint[];
+  /** First and last reading instants. */
+  start: number;
+  /** The as-of instant: the last reading that carries a count. */
+  asOf: number;
+  /** The deadline, or `null`. */
+  due: number | null;
+  /** The whole as it stands now. */
+  scope: number;
+  /** The whole when the run started — different from `scope` when the goalposts moved. */
+  openingScope: number;
+  openingScopeText: string;
+  /** The scope moved during the run, which a burn-down would have hidden. */
+  scopeChanged: boolean;
+  /** Units finished now. */
+  completed: number;
+  /** `scope − completed`. */
+  remaining: number;
+  /** `completed / scope`, in `[0, 1]`. */
+  completeRatio: number;
+  rate: ProgressRate | null;
+  projection: ProgressProjection | null;
+  verdict: ProgressVerdict | null;
+  polarity: ProgressPolarity;
+  /** The ideal line's two ends — `[start, 0]` to `[due, scope]`; `null` without a deadline. */
+  ideal: {
+    from: {
+      t: number;
+      y: number;
+    };
+    to: {
+      t: number;
+      y: number;
+    };
+  } | null;
+  /** The plot's x domain, spanning the readings, the deadline and the projection. */
+  bounds: {
+    min: number;
+    max: number;
+  };
+  scopeText: string;
+  completedText: string;
+  remainingText: string;
+  percentText: string;
+  dueText: string | null;
+  asOfText: string;
+  done: boolean;
+  /** Fewer than two readings carry a count, so there is no trajectory and no rate. */
+  insufficient: boolean;
+  /** Nothing was finished between the last two readings, so the run is not moving and no projection is honest. */
+  stalled: boolean;
+  /** The stage breakdown, when the consumer passed one. */
+  stages: ProgressStage[];
+}
+/** A row of the details table. */
+interface ProgressDetailRow {
+  key: string;
+  label: string;
+  value: string;
+  /** Share of the whole, where the row has one. */
+  share?: string;
+  /** The stage this row draws, so the table can wear its swatch. */
+  stage?: ProgressStage;
+  /** A summary row, set in the medium weight. */
+  summary?: boolean;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface ProgressCardLabels {
+  /** After the finished share — `68% complete`. */
+  complete: string;
+  /** The line under a percent headline — `164 of 240`. */
+  countLine: (value: string, total: string) => string;
+  /** The line under a count or date headline — `68% complete`. Takes the resolved labels so overriding `complete` reaches it. */
+  percentLine: (percent: string, labels: ProgressCardLabels) => string;
+  /** The headline's own words when it counts what is left — `76 left`. */
+  remainingHeadline: (value: string) => string;
+  /** Names the projected finish — `Finishes Sep 18`. */
+  finishes: (date: string) => string;
+  /**
+   * The projection against the deadline — `2 days late`. Takes the count, not
+   * a pre-built phrase, so the noun and its plural belong to the label: a
+   * language with different plural rules (or none) writes the whole thing.
+   */
+  daysLate: (days: number) => string;
+  /** … and the other way — `3 days early`. */
+  daysEarly: (days: number) => string;
+  /** The projection landing exactly on the due date. */
+  onDueDate: string;
+  /** The verdict chip's words. */
+  verdicts: Record<ProgressVerdict, string>;
+  /** The rate, in the card's own units — `12 tables/day` becomes `12/day` without a unit. */
+  perDay: (value: string) => string;
+  /** The rate the deadline still needs — `needs 19/day`. */
+  needsPerDay: (value: string) => string;
+  /** Mark names for the plot's legend, tooltip and table. */
+  markNames: {
+    completed: string;
+    scope: string;
+    ideal: string;
+    projection: string;
+    due: string;
+  };
+  /** The work in flight, on the breakdown bar. */
+  active: string;
+  blocked: string;
+  remaining: string;
+  total: string;
+  scope: string;
+  /** The note under the plot when the scope moved during the run. */
+  scopeMoved: (from: string, to: string) => string;
+  /** Table columns and rows. */
+  tableItem: string;
+  tableValue: string;
+  tableShare: string;
+  tableDate: string;
+  tableCompleted: string;
+  /** The caption in the plot's place when there is only one reading. */
+  needsHistory: string;
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  stale: string;
+  asOf: 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 headline group whose tooltip explains the projection. */
+  progressGroup: (name: string) => string;
+  /** Accessible name of the composed breakdown bar — it is one image, so the whole thing is named. */
+  stageBar: (name: string, parts: string) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+  /** Compact label/value rows explaining the headline. */
+  explanation: (run: ProgressRun, labels: ProgressCardLabels) => readonly (readonly [label: string, value: string])[];
+  /** The plot's own accessible label. */
+  chartDescription: (name: string, run: ProgressRun, labels: ProgressCardLabels) => string;
+  /** The whole card's accessible description — Cesal's alt-text formula. */
+  description: (input: ProgressDescriptionInput) => string;
+}
+interface ProgressDescriptionInput {
+  name: string;
+  state: ProgressCardState;
+  run: ProgressRun | null;
+  labels: ProgressCardLabels;
+}
+declare const DEFAULT_PROGRESS_LABELS: ProgressCardLabels;
+/** Merges consumer overrides over the English defaults. */
+declare function resolveProgressLabels(overrides?: Partial<ProgressCardLabels>): ProgressCardLabels;
+interface ProgressTextFormatters {
+  formatValue: (value: number | null | undefined) => string;
+  formatShare: (ratio: number) => string;
+  formatDay: (ms: number) => string;
+  /**
+   * A per-day rate. Keeps the card's own grammar, except that `integer`
+   * becomes `number:1` — a rate is a derived quantity, and a run finishing
+   * 7.8 units a day would otherwise round to "8", while anything under one a
+   * day would round to "0" and read as stalled when it is not.
+   */
+  formatRate: (value: number) => string;
+}
+interface CreateProgressFormattersInput {
+  /** `arcNumber` grammar for counts — `integer` by default, since a run counts things. */
+  format?: string;
+  locale?: string;
+  timeZone?: string;
+  /** Takes precedence over `format` everywhere a count is rendered. */
+  formatValue?: (value: number) => string;
+  /** Fraction digits for every share. Default 0. */
+  percentDigits?: number;
+  /** How dates are written. Default `day`. */
+  dateGranularity?: ArcTimeGranularity;
+  /** Takes precedence over `dateGranularity` everywhere a date is rendered. */
+  formatDateValue?: (date: Date) => string;
+}
+declare function createProgressFormatters({ format, locale, timeZone, formatValue, percentDigits, dateGranularity, formatDateValue }?: CreateProgressFormattersInput): ProgressTextFormatters;
+/**
+ * Whole calendar days from `from` to `to` in `timeZone` — counted between
+ * calendar dates, so a daylight-saving change never shifts the count and
+ * "2 days late" means two dates on the wall calendar.
+ */
+declare function dayDiff(from: number, to: number, timeZone?: string): number;
+interface DeriveProgressStateInput {
+  status: ProgressCardStatus;
+  /** At least one reading carries a count. */
+  hasValues: boolean;
+  /** There is a whole to divide. */
+  hasData: boolean;
+  /** At least two readings carry a count, so a trajectory exists. */
+  hasTrend: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine: the transport's `status` first, then what the data says.
+ * A refresh over existing readings keeps the previous render under the veil
+ * rather than swapping to a skeleton, so a dashboard never jumps. One reading
+ * is `insufficient`, not `ready`: a completion with no history.
+ */
+declare function deriveProgressState({ status, hasValues, hasData, hasTrend, filtered }: DeriveProgressStateInput): ProgressCardState;
+/** Places the optional breakdown stages over the run's scope. */
+declare function deriveProgressStages(input: readonly ProgressStageInput[], scope: number, formatters: ProgressTextFormatters, labels: ProgressCardLabels): ProgressStage[];
+interface DeriveProgressRunInput {
+  snapshots: readonly ProgressSnapshot[];
+  /** The whole, for snapshots that do not carry their own. */
+  total?: number | null;
+  /** The deadline. */
+  due?: Date | string | number | null;
+  /**
+   * Days of recent history the rate is measured over. Omit to use the whole
+   * run (`completed / elapsed`), which is steadier and matches TargetCard's
+   * linear run rate; pass a window when a recent change of pace is the point.
+   */
+  rateWindow?: number;
+  /** The consumer's own forecast finish, replacing the observed rate's. */
+  projected?: Date | string | number | null;
+  /** Days past the due date that still count as `at-risk` rather than `late`. Default 2. */
+  tolerance?: number;
+  /** The optional breakdown stages. */
+  stages?: readonly ProgressStageInput[];
+  formatters: ProgressTextFormatters;
+  labels: ProgressCardLabels;
+  timeZone?: string;
+}
+/**
+ * Normalises the snapshots into a burn-up run: readings in order, the scope as
+ * it stood at each of them, the rate the work is actually being finished at,
+ * where that rate crosses the scope, and the verdict against the deadline.
+ * Returns `null` when there is nothing to divide — no reading carries a count
+ * and no `total` was declared.
+ */
+declare function deriveProgressRun({ snapshots, total: declaredTotal, due: dueInput, rateWindow, projected, tolerance, stages: stageInput, formatters, labels, timeZone }: DeriveProgressRunInput): ProgressRun | null;
+/** The headline's big text and the line beneath it, per `headline`. */
+declare function buildProgressHeadline(run: ProgressRun, headline: ProgressHeadline, labels: ProgressCardLabels): {
+  big: string;
+  sub: string;
+};
+/**
+ * The table twin: every reading in order, labelled by its own date, with the
+ * count finished by then and the share it made of the scope as it stood — so
+ * a reader who cannot use the plot reads the same trajectory — then the run's
+ * own figures beneath.
+ */
+declare function buildProgressReadingRows(run: ProgressRun, formatters: ProgressTextFormatters, labels: ProgressCardLabels): ProgressDetailRow[];
+/** The stage rows for the details table, when the consumer passed a breakdown. */
+declare function buildProgressStageRows(run: ProgressRun, labels: ProgressCardLabels): ProgressDetailRow[];
+/** The headline group's explanation rows. */
+declare function buildProgressExplanation(run: ProgressRun, labels: ProgressCardLabels): readonly (readonly [label: string, value: string])[];
+/** The plot's own accessible label. */
+declare function buildProgressChartDescription(name: string, run: ProgressRun, labels: ProgressCardLabels): string;
+/** The whole card's accessible description. */
+declare function buildProgressDescription(input: ProgressDescriptionInput): string;
+/** The composed breakdown bar is one image, so its parts are named in one string. */
+declare function buildStageBarLabel(name: string, run: ProgressRun, labels: ProgressCardLabels): string;
+//#endregion
+export { CreateProgressFormattersInput, DEFAULT_PROGRESS_LABELS, DeriveProgressRunInput, DeriveProgressStateInput, ProgressCardLabels, ProgressCardSize, ProgressCardState, ProgressCardStatus, ProgressDescriptionInput, ProgressDetailRow, ProgressHeadline, ProgressPoint, ProgressPolarity, ProgressProjection, ProgressRate, ProgressRun, ProgressSnapshot, ProgressStage, ProgressStageInput, ProgressStageTone, ProgressTextFormatters, ProgressVerdict, buildProgressChartDescription, buildProgressDescription, buildProgressExplanation, buildProgressHeadline, buildProgressReadingRows, buildProgressStageRows, buildStageBarLabel, createProgressFormatters, dayDiff, deriveProgressRun, deriveProgressStages, deriveProgressState, resolveProgressLabels };