@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,392 @@
+//#region src/components/ReportCard/ReportCard.model.d.ts
+/** What the consumer's transport reports. */
+type ReportCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the criteria and
+ * `filtered`. Stamped on the root as `data-state`. `insufficient` is a list of
+ * criteria none of which is scored: there are rows to name but nothing to
+ * grade, so the rows carry a caption rather than a plot of empty tracks.
+ */
+type ReportCardState = "loading" | "refreshing" | "ready" | "insufficient" | "empty" | "no-match" | "error";
+/** Which way is good for a criterion's raw reading: revenue up, cost down. Only used when a score is derived from `value`. */
+type ReportGoodDirection = "up" | "down";
+/**
+ * What a band means. `positive` and `negative` take the diverging ends,
+ * `warning` the degraded status hue, `neutral` the emphasis hue — the one
+ * place status hues belong on a mark, because a grade IS good or bad.
+ */
+type ReportBandTone = "positive" | "neutral" | "warning" | "negative";
+/** How the score of a criterion was reached — stated in the table so a normalisation is never silent. */
+type ReportScoreSource = "score" | "target" | "range" | "none";
+/** How the overall score was reached. `given` is the consumer's own roll-up. */
+type ReportOverallMode = "weighted" | "min" | "none";
+type ReportOverallSource = ReportOverallMode | "given";
+/** Row order: the consumer's, worst score first (the action list), best first, or by the weighted points a criterion costs the grade. */
+type ReportSort = "none" | "worst" | "best" | "impact";
+/** What the big number is: the overall score, its grade, or nothing. Stamped as `data-headline`. */
+type ReportHeadline = "score" | "grade" | "none";
+/** How the change against `previousScore` reads. Stamped as `data-polarity`. A score is always up-is-good. */
+type ReportPolarity = "positive" | "negative" | "neutral";
+type ReportCardSize = "sm" | "md" | "lg";
+/** A row's part in the report — a criterion, or the fold of the long tail. */
+type ReportRole = "criterion" | "other";
+/** The score scale's two ends, `[floor, ceiling]` — the bars' baseline and a perfect score. */
+type ReportScoreDomain = readonly [number, number];
+/**
+ * One step of the grade ladder. `min` is the lowest score in the band; the
+ * band runs up to the next band's `min` (or the top of the scale), so the
+ * ladder needs no `max` and can never leave a gap.
+ */
+interface ReportBand {
+  /** Identifies the band for `data-grade` and the table. Defaults to `label`. */
+  key?: string;
+  /** What this grade is called — `Excellent`, `Meets standard`, `A`. */
+  label: string;
+  /** Lowest score in the band, inclusive. */
+  min: number;
+  /** What the grade means. Default `neutral`. */
+  tone?: ReportBandTone;
+  /** One or two characters for the row's grade column. Defaults to `label`. */
+  short?: string;
+}
+/** A band resolved against the scale: its span, its tone and its place in the ladder. */
+interface ReportBandSpan {
+  key: string;
+  label: string;
+  short: string;
+  tone: ReportBandTone;
+  /** Lowest score in the band, inclusive — clipped to the plotted domain. */
+  from: number;
+  /** Top of the band, exclusive (inclusive at the ceiling) — clipped to the plotted domain. */
+  to: number;
+  /** 0 for the lowest band, upward — the neutral wash's intensity follows it. */
+  index: number;
+}
+/**
+ * One thing the subject is graded on. A criterion resolves to exactly one
+ * score on the card's scale, by one of three routes, checked in order:
+ * `score` as given; `value` against `target` (attainment, ×100 — `down`
+ * criteria invert it, so staying under a budget scores above 100); `value`
+ * inside `range` (linear, `[worst, best]` — a reversed pair reads as
+ * lower-is-better). A criterion with none of those is unscored: its row stays,
+ * with no bar, and it is left out of the roll-up rather than counted as zero.
+ */
+interface ReportCriterion {
+  /** Identifies the criterion for `selected` and the table. Defaults to `label`. */
+  key?: string;
+  label: string;
+  /** The score itself, on the card's `scoreDomain`. Takes precedence over `value`. */
+  score?: number | null;
+  /** The raw reading in the criterion's own units — always shown as text, and the source of a derived score. */
+  value?: number | null;
+  /** The reading's goal, in the reading's units. With `value` it makes the score an attainment percentage. */
+  target?: number | null;
+  /** `[worst, best]` readings that map to the ends of the score scale. With `value` it makes the score a linear normalisation. */
+  range?: readonly [number, number];
+  /** Which way is good for this reading. Defaults to the card's `goodDirection`. */
+  goodDirection?: ReportGoodDirection;
+  /** How much this criterion counts in the roll-up. Default 1; non-finite and negative weights fall back to 1. */
+  weight?: number;
+  /** The score this criterion is expected to reach — the row's comparative tick. Defaults to the card's `passing`. */
+  targetScore?: number | null;
+  /** Number format for this criterion's raw reading, overriding the card's `format` — criteria rarely share units. */
+  format?: string;
+  /** One line of context, shown in the tooltip, the table and the selected row's detail line. */
+  note?: string;
+}
+/** A criterion after normalisation, in display order, with its score, grade and cost resolved. */
+interface ReportRow {
+  key: string;
+  label: string;
+  role: ReportRole;
+  /** The score as reported — may sit above the scale's ceiling (140% of target is not clipped away). `null` when unscored. */
+  score: number | null;
+  /** The score the plot draws, clamped into the plotted domain. `null` when unscored. */
+  plotted: number | null;
+  /** Where the score came from. */
+  source: ReportScoreSource;
+  /** The raw reading, when there is one. */
+  value: number | null;
+  /** The reading's goal, when there is one. */
+  target: number | null;
+  /** The row's comparative tick, in the score domain. */
+  targetScore: number | null;
+  weight: number;
+  /** The band the score falls in. `null` when unscored. */
+  band: ReportBandSpan | null;
+  /** The band's tone, or `neutral` when unscored — what the bar is painted with. */
+  tone: ReportBandTone;
+  /** This row's share of the weighted overall: `score × weight / total weight`. `null` when unscored. */
+  contribution: number | null;
+  /** Weighted points this row costs a perfect overall: `(ceiling − score) × weight / total weight`. The ranking behind `sort="impact"`. */
+  shortfall: number | null;
+  /** Number format for the raw reading. */
+  format?: string;
+  note?: string;
+}
+/** The roll-up: one score, one grade, and how honestly it was reached. */
+interface ReportOverall {
+  /** The composite score, or `null` when nothing is scored and none was given. */
+  score: number | null;
+  /** The band the composite falls in. */
+  band: ReportBandSpan | null;
+  /** How it was reached — `given` when the consumer supplied it. */
+  source: ReportOverallSource;
+  /** Criteria that carry a score. */
+  scored: number;
+  /** Criteria with no score — declared, never silently counted as zero. */
+  unscored: number;
+  /** Total weight behind the composite. */
+  weight: number;
+  /** The criteria do not all weigh the same, so the roll-up is a weighted mean and says so. */
+  weighted: boolean;
+}
+interface ReportSummary {
+  rows: ReportRow[];
+  bands: ReportBandSpan[];
+  overall: ReportOverall;
+  /** The domain the plot draws, `scoreDomain` widened to hold every score. */
+  domain: readonly [number, number];
+  /** The scale's declared floor — the bars' baseline, whatever the plotted domain grew to. */
+  floor: number;
+  /** The scale's declared ceiling — a perfect score, whatever the plotted domain grew to. */
+  ceiling: number;
+  /** The strongest and weakest scored rows — what the chart description names. */
+  best: ReportRow | null;
+  worst: ReportRow | null;
+  /** Criteria folded into the `Other` row; 0 when nothing was folded. */
+  folded: number;
+}
+/** The change of the overall score against `previousScore`, in points. */
+interface ReportDelta {
+  direction: "up" | "down" | "flat";
+  polarity: ReportPolarity;
+  /** The change in score points, signed: `+6`. */
+  text: string;
+  points: number;
+}
+/**
+ * The default ladder: a four-step grade on a 0–100 scale, lettered for the
+ * row column and worded for the headline. `Good` is neutral on purpose —
+ * meeting the standard is not a celebration; only `Excellent` earns the
+ * positive hue and only `Poor` the negative one.
+ */
+declare const DEFAULT_REPORT_BANDS: readonly ReportBand[];
+/** The key of the row the long tail folds into. Never collides with a consumer key that is a label. */
+declare const REPORT_OTHER_KEY = "__other__";
+/** What the delta explanation and the description say about the overall roll-up. */
+interface ReportOverallExplanation {
+  scoreText: string;
+  gradeLabel: string | null;
+  scored: number;
+  unscored: number;
+  weighted: boolean;
+  source: ReportOverallSource;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface ReportCardLabels {
+  /** Caption under the headline — `across 8 criteria`. */
+  criteriaCount: (count: number) => string;
+  /** Comparison line under the delta badge when `previousLabel` is omitted. */
+  versusPrevious: string;
+  increase: string;
+  decrease: string;
+  unchanged: string;
+  /** Suffix after a score delta — `+6 pts`. */
+  points: string;
+  /** Written after the overall score in the headline's unit slot — `/100`. */
+  outOf: (ceiling: string) => string;
+  /** Caption when some criteria carry no score. */
+  notMeasured: (unscored: number, total: number) => string;
+  /** The detail line for the selected row: its grade, its reading and what it is expected to reach. */
+  rowDetail: (input: {
+    label: string;
+    scoreText: string;
+    gradeLabel: string | null;
+    valueText: string | null;
+    targetText: string | null;
+    targetScoreText: string | null;
+    weightText: string | null;
+    note?: string;
+  }) => string;
+  /** Shown in place of a score a criterion does not have. */
+  unscored: string;
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  /** Shown in place of the plot when criteria exist but none is scored. */
+  insufficient: string;
+  stale: string;
+  asOf: string;
+  /** Column headers of the data table. */
+  tableCriterion: string;
+  tableValue: string;
+  tableTarget: string;
+  tableScore: string;
+  tableGrade: string;
+  tableWeight: string;
+  /** Header of the weighted points a criterion costs the overall. */
+  tableShortfall: string;
+  /** The overall row's name in the table. */
+  tableOverall: string;
+  /** Label of the row the long tail folds into. */
+  other: string;
+  /** Legend heading over the band ladder. */
+  bandsLegend: string;
+  /** A band's span in the legend — `75–90`. */
+  bandRange: (from: string, to: string) => string;
+  /** Tooltip title for a row's comparative tick. */
+  expected: string;
+  /** Read out after the selected row's label. */
+  selected: string;
+  weight: 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 selectable rows (a radio group). */
+  criteriaGroup: (name: string) => string;
+  /** The card's first sentence — the overall grade. */
+  overallSentence: (input: ReportOverallExplanation) => string;
+  /** Lists every row — `list` is `Delivery 92 Excellent, Quality 61 Fair, …`. */
+  criteriaSummary: (count: number, list: string) => string;
+  /** Appended when criteria were folded into Other. */
+  foldedSummary: (count: number) => string;
+  /** The change sentence in the description. */
+  changeSentence: (input: {
+    word: string;
+    points: string;
+    previous: string;
+    previousLabel: string;
+  }) => string;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    name: string;
+    count: number;
+    ceiling: string;
+    best: string;
+    bestScore: string;
+    worst: string;
+    worstScore: string;
+    bands: string;
+  }) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+}
+declare const DEFAULT_REPORT_LABELS: ReportCardLabels;
+declare function resolveReportLabels(overrides?: Partial<ReportCardLabels>): ReportCardLabels;
+interface DeriveReportStateInput {
+  status: ReportCardStatus;
+  /** At least one criterion carries a score. */
+  hasScore: boolean;
+  /** Anything is on screen already — any criterion at all — so a reload is a refresh, not a first load. */
+  hasData: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine. Error wins; loading over existing criteria is a refresh
+ * (the previous render stays under the veil); criteria with no scores at all
+ * is `insufficient` — the rows are real, the grade is not; nothing at all is
+ * `no-match` when the consumer's filter caused it and `empty` otherwise.
+ */
+declare function deriveReportState({ status, hasScore, hasData, filtered }: DeriveReportStateInput): ReportCardState;
+/**
+ * Resolves the ladder against the scale: bands sorted low to high, each
+ * running up to the next one's floor and the last to the ceiling, clipped to
+ * the plotted domain so a stripe never paints outside the axis. Bands wholly
+ * below the floor or above the ceiling of the plotted domain are dropped.
+ */
+declare function normalizeBands(bands: readonly ReportBand[] | undefined, domain: readonly [number, number]): ReportBandSpan[];
+/** The band a score falls in — the highest band whose floor it reaches; the lowest band catches anything under the ladder. */
+declare function findBand(bands: readonly ReportBandSpan[], score: number | null | undefined): ReportBandSpan | null;
+interface NormalizeCriteriaOptions {
+  bands?: readonly ReportBand[];
+  /** The declared score scale, `[floor, ceiling]`. Default `[0, 100]`. */
+  scoreDomain?: ReportScoreDomain;
+  /** Which way is good for a reading, when a criterion does not say. Default `up`. */
+  goodDirection?: ReportGoodDirection;
+  /** The score every criterion is expected to reach, when it does not name its own. */
+  passing?: number | null;
+  /** How the composite is reached. Default `weighted`. */
+  overallMode?: ReportOverallMode;
+  /** The consumer's own composite, which replaces the roll-up. */
+  overall?: number | null;
+  sort?: ReportSort;
+  /** Fold every criterion past this count (after sorting) into one `Other` row. */
+  maxCriteria?: number;
+  otherLabel: string;
+}
+/** The score a criterion resolves to, and the route it took. */
+declare function resolveScore(criterion: ReportCriterion, { goodDirection, ceiling }?: {
+  goodDirection?: ReportGoodDirection;
+  ceiling?: number;
+}): {
+  score: number | null;
+  source: ReportScoreSource;
+};
+/**
+ * Normalises `criteria` for the plot, the rows and the table: keys default to
+ * labels (a repeated key is suffixed so two rows never share a band), each
+ * criterion resolves to one score on the declared scale, the plotted domain
+ * widens to hold any score past the ends (a reading at 140% of target extends
+ * the axis rather than clipping to a full bar), the ladder is resolved and
+ * clipped to it, rows are sorted if asked, the tail past `maxCriteria` folds
+ * into one `Other` row whose score is the *weighted mean* of the folded rows
+ * (a mean folds honestly where a sum would not), and every row's contribution
+ * and weighted shortfall are computed against the total weight. Returns `null`
+ * when there are no criteria to speak of.
+ */
+declare function normalizeCriteria(criteria: readonly ReportCriterion[] | undefined, { bands, scoreDomain, goodDirection, passing, overallMode, overall, sort, maxCriteria, otherLabel }: NormalizeCriteriaOptions): ReportSummary | null;
+/** The overall score against `previousScore`, in points. A score is always up-is-good, so the polarity follows the direction. */
+declare function deriveReportDelta(score: number | null | undefined, previous: number | null | undefined, { scoreFormat, locale }?: {
+  scoreFormat?: string;
+  locale?: string;
+}): ReportDelta | null;
+interface ReportTextFormatters {
+  /** A score, in the card's score format. */
+  formatScore: (score: number | null | undefined) => string;
+  /** A raw reading, in the criterion's own format when it has one. */
+  formatValue: (value: number | null | undefined, format?: string) => string;
+  /** A weight — `×2`, and nothing at all for the default weight of 1. */
+  formatWeight: (weight: number) => string | null;
+}
+/** The formatters every text surface shares — headline, rows, detail line, table, tooltip, descriptions. */
+declare function createReportFormatters({ scoreFormat, format, locale, formatScore, formatValue }: {
+  scoreFormat?: string;
+  format?: string;
+  locale?: string;
+  formatScore?: (score: number) => string;
+  formatValue?: (value: number) => string;
+}): ReportTextFormatters;
+interface BuildReportDescriptionInput {
+  name: string;
+  state: ReportCardState;
+  summary: ReportSummary | null;
+  delta: ReportDelta | null;
+  previousScore?: number | null;
+  previousLabel?: string;
+  formatters: ReportTextFormatters;
+  asOfText?: string;
+  labels: ReportCardLabels;
+}
+/**
+ * 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
+ * criterion is listed with its score and grade, so nothing lives only in the
+ * bars, and an unmeasured criterion is named as unmeasured rather than
+ * silently missing.
+ */
+declare function buildReportDescription({ name, state, summary, delta, previousScore, previousLabel, formatters, asOfText, labels }: BuildReportDescriptionInput): string;
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+declare function buildReportChartDescription({ name, summary, formatters, labels }: {
+  name: string;
+  summary: ReportSummary;
+  formatters: ReportTextFormatters;
+  labels: ReportCardLabels;
+}): string;
+//#endregion
+export { BuildReportDescriptionInput, DEFAULT_REPORT_BANDS, DEFAULT_REPORT_LABELS, DeriveReportStateInput, NormalizeCriteriaOptions, REPORT_OTHER_KEY, ReportBand, ReportBandSpan, ReportBandTone, ReportCardLabels, ReportCardSize, ReportCardState, ReportCardStatus, ReportCriterion, ReportDelta, ReportGoodDirection, ReportHeadline, ReportOverall, ReportOverallExplanation, ReportOverallMode, ReportOverallSource, ReportPolarity, ReportRole, ReportRow, ReportScoreDomain, ReportScoreSource, ReportSort, ReportSummary, ReportTextFormatters, buildReportChartDescription, buildReportDescription, createReportFormatters, deriveReportDelta, deriveReportState, findBand, normalizeBands, normalizeCriteria, resolveReportLabels, resolveScore };