@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,381 @@
+import { ArcDeltaDirection, ArcDeltaMode, ArcTimeGranularity } from "../../lib/vega/formatters.js";
+//#region src/components/TableCard/TableCard.model.d.ts
+/** What the consumer's transport reports. */
+type TableCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the rows and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type TableCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+type TableCardSortDirection = "asc" | "desc";
+/** The active column order. `field` is the column's `id` (which defaults to its `field`); `direction` is which end leads. */
+interface TableCardSort {
+  field: string;
+  direction: TableCardSortDirection;
+}
+/** Which way is good for a change: revenue up, cost per acquisition down, headcount neutral. */
+type TableCardGoodDirection = "up" | "down" | "none";
+/** How a delta reads once `goodDirection` is applied. */
+type TableCardPolarity = "positive" | "negative" | "neutral";
+/** Cell alignment. Numbers align to their end so digits line up; names read from the start. */
+type TableCardAlign = "start" | "end";
+/**
+ * What a column encodes. `text` is identity, `number` is the exact reading,
+ * `bar` adds magnitude on the column's own shared scale, `delta` is the
+ * change against a baseline, `trend` is the shape over time, `badge` is a
+ * category.
+ */
+type TableCardColumnKind = "text" | "number" | "bar" | "delta" | "trend" | "badge";
+/** A footer total. `sum` only for additive measures — a rate, a ratio or an average must never be summed. */
+type TableCardTotal = "sum" | "mean" | "max" | "min";
+/** A badge cell's meaning. `neutral` is the default because a category is not good or bad. */
+type TableCardTone = "neutral" | "positive" | "negative" | "warning" | "info";
+/** How a trend cell draws. A line may crop; an area and bars keep a zero baseline. */
+type TableCardTrendMark = "line" | "area" | "bar";
+type TableCardSize = "sm" | "md" | "lg";
+/** One reading of a trend cell's series. `x` labels it in the tooltip; omit it and the index is used. */
+interface TableCardTrendPoint {
+  x: string | number;
+  y: number | null;
+}
+/** A row: field values by column `field`, plus whatever else the consumer carries. */
+type TableCardRow = Readonly<Record<string, unknown>>;
+interface TableCardColumnShared {
+  /** The field each row is read at. */
+  field: string;
+  /**
+   * The column's identity — what `sort` names, what `data-column` stamps, and
+   * the key its cell is filed under. Defaults to `field`, and only needs
+   * setting when two columns read the same field: a value beside its own bar,
+   * or a reading beside the change in it.
+   */
+  id?: string;
+  /** Column heading — plain text, so it can name the sort control, the footer cell and the generated description. */
+  header: string;
+  /** Unit or qualifier shown muted beside the heading (`THB`, `per day`, `7d`). */
+  unit?: string;
+  /** Cell alignment. Default: `start` for `text` and `badge`, `end` for `number`, `bar` and `delta`, `start` for `trend`. */
+  align?: TableCardAlign;
+  /** Offer this column's order. Default `true`; a `trend` column sorts by the change across its series. */
+  sortable?: boolean;
+  /** Column width as a CSS length — obeyed because the table lays out `fixed`. */
+  width?: string;
+  /** Drop this column when the card is narrower than this many pixels — the responsive degradation ladder. */
+  hideBelow?: number;
+  /**
+   * Footer aggregate for this column. Omitted means no footer cell, which is
+   * the default: only the consumer knows whether a measure is additive, and a
+   * summed rate is a lie (rule 14 — totals reconcile with parts).
+   */
+  total?: TableCardTotal;
+  /** What the column means, shown in a tooltip behind an info control in the heading and read as that control's description. */
+  hint?: string;
+}
+interface TableCardTextColumn extends TableCardColumnShared {
+  kind: "text";
+  /** Secondary field rendered muted under the label — an id, a channel, a parent. */
+  captionField?: string;
+}
+interface TableCardNumberColumn extends TableCardColumnShared {
+  kind: "number";
+  /** `arcNumber` grammar (`compact`, `percent:1`, `currency:THB:compact`). Default `number`. */
+  format?: string;
+}
+interface TableCardBarColumn extends TableCardColumnShared {
+  kind: "bar";
+  /** `arcNumber` grammar for the number beside the bar. Default `compact`. */
+  format?: string;
+  /**
+   * Upper bound of the column's shared length scale: `max` (default) makes the
+   * largest row a full bar so rows are comparable down the column, `total`
+   * makes each bar that row's share of the column sum, and a number pins the
+   * scale so the same column is comparable across cards. Bars always start at
+   * zero (Wilke's proportional ink).
+   */
+  domain?: number | "max" | "total";
+  /** Show the formatted number beside the bar. Default `true` — a bar alone is not a value. */
+  showValue?: boolean;
+}
+interface TableCardDeltaColumn extends TableCardColumnShared {
+  kind: "delta";
+  /** `arcNumber` grammar of the underlying measure — it decides whether an absolute delta reads in units or percentage points. Default `number`. */
+  format?: string;
+  /**
+   * Field holding the earlier reading. With it, `field` is the current reading
+   * and the change is computed; without it, `field` is read as an
+   * already-computed relative change (`0.124` → `+12.4%`).
+   */
+  previousField?: string;
+  /** Relative (`percent`, default) or in the measure's own units (`absolute`). */
+  mode?: ArcDeltaMode;
+  /** Which direction is good, so the cell can colour the change. Default `up`. */
+  goodDirection?: TableCardGoodDirection;
+}
+interface TableCardTrendColumn extends TableCardColumnShared {
+  kind: "trend";
+  /** `arcNumber` grammar for the readings in the tooltip and the cell's sentence. Default `compact`. */
+  format?: string;
+  /** Default `line`. An `area` or `bar` keeps a zero baseline whatever the readings do. */
+  mark?: TableCardTrendMark;
+  /** `arcTime` granularity for a temporal `x` in the tooltip. Omit for index or category x. */
+  granularity?: ArcTimeGranularity;
+}
+interface TableCardBadgeColumn extends TableCardColumnShared {
+  kind: "badge";
+  /**
+   * Tone per value — the one place a status hue may touch this table, because
+   * there the value itself means good or bad. Anything unlisted stays
+   * `neutral`; the word is always in the badge, so the hue is never the only
+   * carrier.
+   */
+  tones?: Readonly<Record<string, TableCardTone>>;
+}
+type TableCardColumn = TableCardTextColumn | TableCardNumberColumn | TableCardBarColumn | TableCardDeltaColumn | TableCardTrendColumn | TableCardBadgeColumn;
+/** A column after resolution: defaults applied, and the scale and total this data gives it. */
+interface TableCardColumnModel {
+  column: TableCardColumn;
+  /** The column's identity — `column.id ?? column.field`. */
+  id: string;
+  /** The field it reads on each row. */
+  field: string;
+  kind: TableCardColumnKind;
+  header: string;
+  align: TableCardAlign;
+  sortable: boolean;
+  /** `bar` columns: the resolved upper bound of the length scale. `null` when no row has a value. */
+  domainMax: number | null;
+  /** The aggregate the footer shows, already formatted. `null` when the column declares none. */
+  totalText: string | null;
+  /** The raw aggregate, for tests and for the generated sentences. */
+  totalValue: number | null;
+  /** `true` once any row in this column has no reading — the description says so. */
+  hasMissing: boolean;
+}
+interface TableCardCellDelta {
+  direction: ArcDeltaDirection;
+  polarity: TableCardPolarity;
+  /** Signed change: `+12.4%`, `-0.8 pp`, `+฿24K`. */
+  text: string;
+  renderedMode: ArcDeltaMode;
+  /** The change as a number, for sorting. */
+  value: number;
+}
+/** What a trend cell's series says, in numbers — the basis of its sort order and its sentence. */
+interface TableCardTrendSummary {
+  first: number | null;
+  last: number | null;
+  min: number | null;
+  max: number | null;
+  /** Readings with a value. */
+  count: number;
+  /** Readings that are null — drawn as gaps, never as zero. */
+  gaps: number;
+  /** `last - first`, or `null` when either end is missing. */
+  change: number | null;
+  direction: ArcDeltaDirection | null;
+}
+interface TableCardCell {
+  /** The column's identity — what `byField` files this cell under. */
+  id: string;
+  /** The row field it was read from. Two cells in a row may share it. */
+  field: string;
+  kind: TableCardColumnKind;
+  /** The formatted text the cell shows. `MISSING_VALUE` when there is no reading. */
+  text: string;
+  /** What this cell sorts by: a number for every numeric kind, the string for `text` and `badge`, `null` when missing. */
+  sortValue: number | string | null;
+  /** The raw numeric reading, for the footer aggregates. */
+  value: number | null;
+  /** `bar` cells: 0–1 of the column's domain, clamped. `null` when there is no reading. */
+  share: number | null;
+  /** `delta` cells. */
+  delta: TableCardCellDelta | null;
+  /** `trend` cells: the normalised series. */
+  points: readonly TableCardTrendPoint[] | null;
+  /** `trend` cells: what the series says. */
+  trend: TableCardTrendSummary | null;
+  /** `badge` cells. */
+  tone: TableCardTone | null;
+  /** `text` cells: the muted second line. */
+  caption: string | null;
+  /**
+   * The sentence assistive technology hears when the visual form is not text —
+   * a trend cell's shape, a bar's share. `null` when `text` already says
+   * everything.
+   */
+  detail: string | null;
+}
+interface TableCardRowModel {
+  key: string;
+  /** The row's identifying text — its first `text` column, else its key. */
+  label: string;
+  /** 1-based place in the current order, ties shared. `null` when the table is unsorted. */
+  rank: number | null;
+  cells: TableCardCell[];
+  byField: Readonly<Record<string, TableCardCell>>;
+}
+interface TableCardSummary {
+  rows: TableCardRowModel[];
+  columns: TableCardColumnModel[];
+  /** Rows shown. */
+  count: number;
+  /** Rows behind the table — `totalRows` when the consumer paged or filtered upstream, else the input length. */
+  total: number;
+  /** Rows `maxRows` cut off. */
+  truncated: number;
+  /** The resolved sorted column, `null` when unsorted. */
+  sortColumn: TableCardColumnModel | null;
+  /** First and last row of the current order — what the insight names. */
+  leader: TableCardRowModel | null;
+  trailer: TableCardRowModel | null;
+  /** Any `trend` column is present, so the engine chunk is needed. */
+  hasTrend: boolean;
+  /** One row where the order is the point — a ranking of one is not a ranking. */
+  insufficient: boolean;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface TableCardLabels {
+  /** Accessible name of a column's sort control. */
+  sortBy: (header: string) => string;
+  /** Accessible name that reverses the active order. */
+  sortDescending: (header: string) => string;
+  sortAscending: (header: string) => string;
+  /** Announced once after the reader re-sorts. */
+  sortedBy: (header: string, direction: TableCardSortDirection) => string;
+  ascending: string;
+  descending: string;
+  /** Accessible prefix for a row's ordinal, so "1." is unambiguous. */
+  rank: (place: number) => string;
+  /** Footer row heading. */
+  total: string;
+  /** Caption under the table when `maxRows` cut the tail off. */
+  showingTopOf: (shown: number, total: number) => string;
+  showAll: string;
+  /** The generated takeaway when the leader stands above the median of the sorted column. */
+  insightAboveMedian: (leader: string, header: string, value: string, share: string, rows: number) => string;
+  /** …and below it — possible when the order is ascending. */
+  insightBelowMedian: (leader: string, header: string, value: string, share: string, rows: number) => string;
+  /** …and exactly at it. */
+  insightAtMedian: (leader: string, header: string, value: string, rows: number) => string;
+  /** A trend cell's sentence: `4.2K to 5.1K, up 21%`. */
+  trendSentence: (first: string, last: string, change: string) => string;
+  /** A trend cell with one or no readings. */
+  trendInsufficient: string;
+  /** A bar cell's share, appended to its value. */
+  shareOf: (share: string) => string;
+  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 note when a ranked table has a single row. */
+  insufficient: string;
+  stale: string;
+  asOf: string;
+  about: (name: string) => string;
+  /** Accessible name of a row's drill control. */
+  openRow: (label: string) => string;
+  /** The table's own caption, when the consumer passes none. */
+  caption: (name: string) => string;
+}
+declare const DEFAULT_TABLE_LABELS: TableCardLabels;
+/** Merges a partial override over the defaults. */
+declare function resolveTableLabels(labels?: Partial<TableCardLabels>): TableCardLabels;
+/**
+ * Normalises a trend field: a bare array of readings becomes indexed points,
+ * `{ x, y }` records pass through, and anything else becomes an empty series.
+ * Nulls survive as nulls — a gap is not a zero.
+ */
+declare function normalizeTrendPoints(value: unknown): TableCardTrendPoint[];
+/** What a trend cell's series says: its ends, its extremes, its gaps, and the change across it. */
+declare function summarizeTrend(points: readonly TableCardTrendPoint[]): TableCardTrendSummary;
+/** How a change reads once `goodDirection` is applied: up is not always good. */
+declare function deltaPolarity(direction: ArcDeltaDirection, goodDirection: TableCardGoodDirection): TableCardPolarity;
+/** A column's identity: its own `id`, else the field it reads. */
+declare function columnId(column: TableCardColumn): string;
+interface NormalizeTableInput {
+  columns: readonly TableCardColumn[];
+  rows: readonly TableCardRow[];
+  /** Field naming each row. Default: the first `text` column's field, then the row index. */
+  rowKey?: string;
+  sort?: TableCardSort | null;
+  /** Cap the rows shown. The tail is cut off and counted, never folded — a summed rate is a lie. */
+  maxRows?: number;
+  /** The true row count behind the table when the consumer already paged or capped upstream. */
+  totalRows?: number;
+  /** Number the rows in the current order. */
+  showRank?: boolean;
+  locale?: string;
+  timeZone?: string;
+  labels?: TableCardLabels;
+}
+/**
+ * Turns the consumer's columns and records into the model the card renders:
+ * every column resolved (alignment, sortability, its own length scale and its
+ * footer aggregate), every cell formatted once and given the single number it
+ * sorts by, the rows ordered, capped and ranked.
+ *
+ * Missing readings sort last in both directions — "no reading" is not the
+ * smallest reading — and a capped tail is reported in `truncated` rather than
+ * folded into an "Other" row: a table's columns are not all additive, so
+ * summing them would invent numbers.
+ */
+declare function normalizeTable(input: NormalizeTableInput): TableCardSummary;
+interface DeriveTableStateInput {
+  status: TableCardStatus;
+  /** Rows the card was handed. */
+  rowCount: number;
+  /** A filter is active, so no rows means "excluded", not "none". */
+  filtered?: boolean;
+}
+/**
+ * The state machine: `loading` with nothing to show, `refreshing` when a
+ * reload arrives over a rendered table (the previous render stays under the
+ * veil rather than collapsing to a skeleton), `error`, then `empty` or
+ * `no-match` — different messages, because "there is no data" and "your
+ * filters exclude all of it" call for different actions (Cloudscape's
+ * `empty` / `noMatch` split).
+ */
+declare function deriveTableState({ status, rowCount, filtered }: DeriveTableStateInput): TableCardState;
+interface BuildTableDescriptionInput {
+  name: string;
+  summary: TableCardSummary;
+  labels: TableCardLabels;
+  sort?: TableCardSort | null;
+  updatedAt?: string | number | Date;
+  updatedAtFormat?: ArcTimeGranularity;
+  locale?: string;
+  timeZone?: string;
+}
+/**
+ * The card's accessible description (Amy Cesal's alt-text formula: what form,
+ * what data, why it is here, as of when) — what the table holds, how it is
+ * ordered, which measures it carries, and whether it is capped.
+ */
+declare function buildTableDescription({ name, summary, labels, sort, updatedAt, updatedAtFormat, locale, timeZone }: BuildTableDescriptionInput): string;
+interface BuildTableInsightInput {
+  summary: TableCardSummary;
+  labels: TableCardLabels;
+  locale?: string;
+}
+/**
+ * The takeaway, as one visible sentence (Chartability's "title, summary,
+ * context"): how far the leader stands above the middle of the sorted column,
+ * because "who is on top" is already visible and "by how much" is the part a
+ * reader has to compute. `null` when the table is unsorted or too short for
+ * the comparison to mean anything.
+ */
+declare function buildTableInsight({ summary, labels, locale }: BuildTableInsightInput): string | null;
+/** The `arcTime` grammar string for a trend cell's tooltip x, built from the card's locale and zone. */
+declare function trendTimeFormat(granularity: ArcTimeGranularity | undefined, locale?: string, timeZone?: string): string;
+/** The `arcNumber` grammar string for a column, with the card's locale appended. */
+declare function columnValueFormat(column: TableCardColumn, locale?: string): string;
+/** Flips a column's order: a fresh click on a numeric column leads with the largest, on a name with A. */
+declare function nextSort(current: TableCardSort | null, column: TableCardColumnModel): TableCardSort;
+//#endregion
+export { BuildTableDescriptionInput, BuildTableInsightInput, DEFAULT_TABLE_LABELS, DeriveTableStateInput, NormalizeTableInput, TableCardAlign, TableCardBadgeColumn, TableCardBarColumn, TableCardCell, TableCardCellDelta, TableCardColumn, TableCardColumnKind, TableCardColumnModel, TableCardDeltaColumn, TableCardGoodDirection, TableCardLabels, TableCardNumberColumn, TableCardPolarity, TableCardRow, TableCardRowModel, TableCardSize, TableCardSort, TableCardSortDirection, TableCardState, TableCardStatus, TableCardSummary, TableCardTextColumn, TableCardTone, TableCardTotal, TableCardTrendColumn, TableCardTrendMark, TableCardTrendPoint, TableCardTrendSummary, buildTableDescription, buildTableInsight, columnId, columnValueFormat, deltaPolarity, deriveTableState, nextSort, normalizeTable, normalizeTrendPoints, resolveTableLabels, summarizeTrend, trendTimeFormat };