@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,452 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ChartTokens } from "../../lib/vega/tokens.js";
+//#region src/components/ChartCard/ChartCard.model.d.ts
+/** What the consumer's transport reports. */
+type ChartCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the rows and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type ChartCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "insufficient" | "error";
+type ChartCardSize = "sm" | "md" | "lg";
+/**
+ * The FT Visual Vocabulary category a form belongs to — what comparison it
+ * makes visible. Drives the generated description and groups the types in the
+ * docs.
+ */
+type ChartIntent = "magnitude" | "change-over-time" | "part-to-whole" | "correlation" | "distribution" | "deviation" | "ranking" | "flow" | "spatial";
+/**
+ * Every form this card can draw, one per distinct Vega-Lite encoding. Grouped
+ * by the mark family that renders it; the FT intent each one serves is in
+ * `CHART_TYPES`.
+ */
+type ChartType = "bar" | "bar-horizontal" | "bar-grouped" | "bar-stacked" | "bar-normalized" | "bar-diverging" | "bar-range" | "lollipop" | "waterfall" | "line" | "line-points" | "step" | "trail" | "area" | "area-stacked" | "area-normalized" | "streamgraph" | "slope" | "pie" | "donut" | "radial" | "scatter" | "bubble" | "connected-scatter" | "heatmap-binned" | "histogram" | "density" | "boxplot" | "violin" | "strip" | "dot" | "errorbar" | "errorband" | "heatmap" | "punchcard" | "radar";
+/** Vega-Lite's field types, as this card infers or accepts them. */
+type ChartFieldType = "quantitative" | "temporal" | "ordinal" | "nominal";
+/** Aggregation applied to the measure before it is drawn — declared, never silent. */
+type ChartAggregate = "sum" | "mean" | "median" | "min" | "max" | "count" | "distinct";
+/** How colour is used. `auto` picks by series count against the theme's identity budget. */
+type ChartSeriesColor = "auto" | "categorical" | "sequential" | "emphasis";
+/** The resolved colour job, stamped as `data-series-color`. */
+type ChartColorMode = "single" | "categorical" | "sequential" | "emphasis" | "magnitude";
+/** What the legend row shows: one chip per series, a ramp of magnitude buckets, or nothing. */
+type ChartLegendKind = "series" | "ramp" | "none";
+/** Row order for a ranked form. */
+type ChartSort = "none" | "asc" | "desc";
+/** Extent of a `boxplot` whisker (`1.5` or `"min-max"`) or an `errorbar`/`errorband` band. */
+type ChartExtent = number | "min-max" | "ci" | "stderr" | "stdev" | "iqr";
+/** Which fields a form reads, so the card can validate and infer only what matters. */
+interface ChartTypeFields {
+  /** `x` is the primary position. `none` for the polar forms, which have no cartesian axes. */
+  x: "required" | "optional" | "none";
+  /** `y` is the second position. Forms that count (histogram, strip) derive it. */
+  y: "required" | "optional" | "none";
+  /** `series` is the identity field — it drives colour and the legend. */
+  series: "required" | "optional" | "none";
+  /** `value` is the measure when it is NOT a position: an angle, a cell's colour, a bubble's area. Falls back to `y`. */
+  value: boolean;
+  /** `size` is a second measure drawn as area. */
+  size: boolean;
+  /** `x2` closes a range (a Gantt bar, a duration). */
+  x2: boolean;
+}
+interface ChartTypeInfo {
+  /** The comparison this form makes visible. */
+  intent: ChartIntent;
+  /** The Vega-Lite mark family, for the description and the legend swatch. */
+  mark: "bar" | "line" | "area" | "arc" | "point" | "rect" | "tick" | "rule" | "boxplot" | "band";
+  fields: ChartTypeFields;
+  /** Polar forms draw no cartesian axes, so the plot reserves no room for one. */
+  polar: boolean;
+  /** The plot must be square — a wedge chart in an oval misreads every angle. A radar instead spends extra width on its label gutter. */
+  square: boolean;
+  /** The measure sits on x, not y — the plot reads as rows. */
+  horizontal: boolean;
+  /** How several series sit together, when the form stacks at all. */
+  stack: false | "zero" | "normalize" | "center";
+  /** Colour's job when `seriesColor` is `auto`: identity per series, magnitude through the ramp, or one hue. */
+  color: "identity" | "magnitude" | "single";
+  /** What the legend row can show for this form. */
+  legend: ChartLegendKind;
+  /** Vega aggregates or bins the rows itself — the card hands it raw observations. */
+  aggregating: boolean;
+  /** Fewer rows than this and the form says nothing (a one-point line is not a trend). */
+  minRows: number;
+  /** A short phrase naming the form in the generated description. */
+  name: string;
+}
+/**
+ * The registry every other part of the card reads: field-type inference, the
+ * legend, the description, the table twin and the spec builder all branch on
+ * this rather than on `type` directly, so adding a form is one entry plus one
+ * encoding.
+ */
+declare const CHART_TYPES: Record<ChartType, ChartTypeInfo>;
+/** Every form, in the docs' own order — the docs table and the type control read this. */
+declare const CHART_TYPE_ORDER: ChartType[];
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface ChartCardLabels {
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  /** Shown in place of the plot when there are too few rows for the form to say anything. */
+  insufficient: string;
+  stale: string;
+  /** Accessible name of the legend group. */
+  legendGroup: (name: string) => string;
+  showSeries: (label: string) => string;
+  hideSeries: (label: string) => string;
+  /** Label of the row the long tail folds into. */
+  other: string;
+  /** Accessible name and caption of the table twin. */
+  showTable: (name: string) => string;
+  hideTable: (name: string) => string;
+  tableCaption: (name: string) => string;
+  /** Table column headers, used when the consumer names no field titles. */
+  tableSeries: string;
+  tableValue: string;
+  tableShare: string;
+  /** Caption under a table that shows only the head of a large dataset. */
+  tableTruncated: (shown: number, total: number) => string;
+  /** The generated `aria-label` of the plot: "<form> of <measure> by <dimension>". */
+  chartOf: (form: string, measure: string, dimension: string) => string;
+  /** Card description sentences. */
+  describeSeries: (count: number, names: string) => string;
+  describeRange: (from: string, to: string) => string;
+  describeExtremes: (maxLabel: string, maxValue: string, minLabel: string, minValue: string) => string;
+  describeTotal: (total: string) => string;
+  describeRamp: (low: string, high: string) => string;
+  describeAggregate: (op: string, measure: string) => string;
+  describeFolded: (count: number, label: string) => string;
+  describeHidden: (count: number) => string;
+  describeStale: string;
+  describeLoading: (name: string) => string;
+  describeEmpty: (name: string) => string;
+  describeError: (name: string) => string;
+}
+declare const DEFAULT_CHART_LABELS: ChartCardLabels;
+declare function resolveChartLabels(overrides?: Partial<ChartCardLabels>): ChartCardLabels;
+interface DeriveChartStateInput {
+  status: ChartCardStatus;
+  /** The form has enough rows to draw. */
+  hasChart: boolean;
+  /** Any rows arrived at all. */
+  hasData: boolean;
+  /** The consumer's filter is active, so "nothing" reads as no-match rather than empty. */
+  filtered: boolean;
+}
+/**
+ * The state machine every card in this package shares, plus `insufficient`:
+ * rows arrived but the form needs more of them than it got.
+ */
+declare function deriveChartState({ status, hasChart, hasData, filtered }: DeriveChartStateInput): ChartCardState;
+/**
+ * Whether the form has enough to say something. Beyond the row floor in the
+ * registry, the forms Vega aggregates need several observations INSIDE a
+ * group: a box plot of one reading per category has no interquartile range to
+ * draw, and Vega then logs an empty-extent warning rather than a chart.
+ */
+declare function hasEnoughData(type: ChartType, summary: ChartSummary | null): boolean;
+/**
+ * The field names a form needs but did not get. A card missing one of these
+ * cannot draw at all, so it shows the insufficient state and says which field
+ * is absent rather than rendering an empty frame.
+ */
+declare function missingChartFields(type: ChartType, provided: {
+  x?: string;
+  y?: string;
+  series?: string;
+  value?: string;
+  size?: string;
+  x2?: string;
+}): string[];
+/**
+ * Infers a field's Vega-Lite type from the first rows that actually carry it:
+ * `Date` objects and ISO-8601 strings are temporal, numbers quantitative,
+ * everything else nominal. Returns `undefined` for a field no row defines, so
+ * a caller can tell "not present" from "nominal".
+ */
+declare function inferFieldType(rows: readonly ChartRecord[] | undefined, field: string | undefined): ChartFieldType | undefined;
+/** One record from the consumer's transport. Field names, never a Vega-Lite spec. */
+type ChartRecord = Record<string, unknown>;
+/**
+ * A row as the plot reads it. Short keys because they travel into the Vega
+ * dataflow on every row: `x`/`y` are the positions, `v` the measure (equal to
+ * `y` wherever the measure IS the y position), `s`/`n`/`c`/`i` the series'
+ * key, label, paint and index, `z` a size measure, `x2` a range end, and
+ * `lo`/`hi` a waterfall step's foot and head.
+ */
+interface ChartRow {
+  x?: unknown;
+  x2?: unknown;
+  y?: number | string | null;
+  v?: number | null;
+  z?: number | null;
+  s?: string;
+  n?: string;
+  c?: string;
+  i?: number;
+  lo?: number;
+  hi?: number;
+  /** A waterfall step's sign, so the bar can be painted by polarity without a scale. */
+  d?: "up" | "down" | "total";
+  /**
+   * The row's place in the consumer's order. A connected scatter's path
+   * follows it — without an explicit `order` a Vega-Lite line sorts its path
+   * by x, which is exactly the sequence a connected scatter exists to break.
+   */
+  o?: number;
+  /**
+   * A radar vertex on the unit plane, x right and y down. Vega-Lite 6.4 accepts
+   * `theta`/`radius` on `arc` and `text` marks ONLY — every other mark drops
+   * them with a warning — so a radar's polygon is drawn on ordinary cartesian
+   * scales from coordinates computed here: `sin(angle) * v / max` and
+   * `-cos(angle) * v / max`, with the first axis at twelve o'clock.
+   */
+  px?: number;
+  py?: number;
+  /** The radar axis this vertex belongs to, as an index — the polygon's path order. */
+  ai?: number;
+}
+/** One series as the legend, the table and the description see it. */
+interface ChartSeriesInfo {
+  key: string;
+  label: string;
+  /** The paint every row of this series carries. */
+  color: string;
+  /** Position in the consumer's order — the colour slot follows this, never the rank. */
+  index: number;
+  /** Sum of this series' finite measures, for the part-to-whole forms and the fold. */
+  total: number;
+  /** Finite readings in this series. */
+  count: number;
+}
+interface ChartExtremes {
+  maxLabel: string;
+  maxValue: number;
+  minLabel: string;
+  minValue: number;
+}
+interface ChartSummary {
+  /** Long-form rows for the visible series, in the consumer's order. */
+  rows: ChartRow[];
+  /** Every series the data contains, hidden ones included — the legend renders them all. */
+  series: ChartSeriesInfo[];
+  /** Rows with a finite measure. */
+  count: number;
+  /**
+   * A measure field was resolved at all. A range bar given only its two bounds
+   * has none, and `count` is then 0 for a chart that is perfectly drawable.
+   */
+  hasMeasure: boolean;
+  /** Distinct x values, in first-seen order. */
+  xValues: unknown[];
+  xType: ChartFieldType;
+  yType: ChartFieldType;
+  /** Extent of the measure across the visible rows — the ramp legend's domain. */
+  domain: [number, number] | null;
+  /** Sum of every visible finite measure, for part-to-whole descriptions. */
+  total: number;
+  /** The strongest and weakest readings, named. */
+  extremes: ChartExtremes | null;
+  /** How many series the tail fold swallowed; 0 when nothing was folded. */
+  folded: number;
+  /** The resolved colour job. */
+  colorMode: ChartColorMode;
+  /** Inferred period of temporal x values, for the axis and the tooltip. */
+  granularity: ArcTimeGranularity;
+}
+/** The key the folded tail takes. Never collides with a consumer key, which is a field value. */
+declare const CHART_OTHER_KEY = "__other__";
+interface NormalizeChartDataOptions {
+  type: ChartType;
+  /** Field names. `value` falls back to `y`; every one of them may be absent when the form does not read it. */
+  x?: string;
+  y?: string;
+  series?: string;
+  value?: string;
+  size?: string;
+  x2?: string;
+  /** Explicit field types; inferred from the rows when omitted. */
+  xType?: ChartFieldType;
+  yType?: ChartFieldType;
+  /** Keys of the series currently shown. `undefined` shows all of them. */
+  visible?: readonly string[];
+  /** Fold every series past this count (in the consumer's order) into one summed `Other`. Additive measures only. */
+  maxSeries?: number;
+  otherLabel: string;
+  /** Rank the x categories by the measure. Only meaningful for a discrete x. */
+  sort?: ChartSort;
+  colorMode: ChartColorMode;
+  tokens: ChartTokens;
+}
+/**
+ * Picks the paint for series `index` under the resolved colour job. Identity
+ * slots are assigned by the series' place in the consumer's order — never by
+ * rank — so hiding or re-sorting can never repaint the survivors. Past the
+ * theme's identity budget the ramp takes over: repeating a slot would make two
+ * series look like one, and a ramp at least stays ordered and separable.
+ */
+declare function chartSeriesColorAt(mode: ChartColorMode, index: number, total: number, tokens: ChartTokens): string;
+/**
+ * Resolves the colour job from the prop, the series count and the theme's own
+ * identity budget (`chart-1…N`, three hues on the stock theme). A form whose
+ * colour encodes a MEASURE — a heatmap, a punch card — always resolves to
+ * `magnitude`, whatever the prop says: colour has one job per chart, and there
+ * it is already spoken for.
+ */
+declare function resolveChartColorMode(requested: ChartSeriesColor, type: ChartType, seriesCount: number, slots: number): ChartColorMode;
+/** Infers the period of a temporal axis from the closest spacing its values show. */
+declare function inferGranularity(values: readonly unknown[]): ArcTimeGranularity;
+/**
+ * Turns the consumer's records into the long-form rows the plot draws: series
+ * keys and labels resolved (a series is one distinct value of the `series`
+ * field, in first-seen order), the measure coerced to a finite number or
+ * `null`, a paint baked into every row, the tail folded, the x categories
+ * optionally ranked, and the waterfall's running total computed here rather
+ * than in Vega so the table twin and the tooltip can show the same feet and
+ * heads the bars stand on.
+ *
+ * Returns `null` when there is nothing to normalise.
+ */
+declare function normalizeChartData(data: readonly ChartRecord[] | undefined, options: NormalizeChartDataOptions): ChartSummary | null;
+/** One vertex of a radar's grid, on the same unit plane the polygons use. */
+interface ChartWebRow {
+  /** The axis this vertex belongs to. */
+  x: unknown;
+  /** That axis' index — the ring polygons' path order. */
+  ai: number;
+  /** Which ring, as a fraction of the outer one. `0` is the centre. */
+  k: number;
+  px: number;
+  py: number;
+  /** Where this axis' label sits — outside the outer ring. */
+  lx: number;
+  ly: number;
+  /** The value the ring stands for, so the outer ring can be named. */
+  r: number;
+}
+/** Fractions of the outer ring a radar's web is drawn at. */
+declare const RADAR_RING_FRACTIONS: readonly [0.25, 0.5, 0.75, 1];
+/**
+ * The radar's grid: one row per axis per ring, on the same unit plane the
+ * polygons are drawn on. Built here rather than in the spec because the spec
+ * must stay structural — and because a ring then stands for a real value the
+ * description can name, not just a fraction of the frame.
+ */
+declare function buildRadarWebRows(summary: ChartSummary | null): ChartWebRow[];
+/** One bucket of a magnitude legend — a swatch and the range it stands for. */
+interface ChartRampBucket {
+  color: string;
+  /** Inclusive lower bound of the bucket. */
+  from: number;
+  /** Exclusive upper bound, except for the last bucket. */
+  to: number;
+  label: string;
+}
+/**
+ * Buckets a magnitude ramp for the legend row. Vega owns the continuous scale
+ * on the plot; this is the reader's key to it, and — like the reference
+ * heatmap's HIGH / MODERATE / LOW row — it is the only way a colour-encoded
+ * measure is legible without hovering.
+ */
+declare function buildRampBuckets(domain: [number, number] | null, tokens: ChartTokens, format: (value: number) => string, steps?: number): ChartRampBucket[];
+interface ChartTextFormatters {
+  /** The measure, in the card's one grammar. */
+  formatValue: (value: number | null | undefined) => string;
+  /** An x value, at whatever type the axis resolved to. */
+  formatX: (value: unknown) => string;
+  /** A y value that is a position rather than the measure (a heatmap's row). */
+  formatY: (value: unknown) => string;
+  /** A share of the total, for the part-to-whole forms. */
+  formatShare: (value: number | null | undefined) => string;
+}
+interface CreateChartFormattersOptions {
+  /** `arcNumber` grammar for the measure. */
+  format?: string;
+  locale?: string;
+  timeZone?: string;
+  /** Takes precedence over `format` everywhere a measure is rendered. */
+  formatValue?: (value: number) => string;
+  xType: ChartFieldType;
+  yType: ChartFieldType;
+  granularity: ArcTimeGranularity;
+}
+/**
+ * One set of formatters for the axis, the tooltip, the legend, the table and
+ * the description, so the same value never rounds two ways (Few's precision
+ * pitfall).
+ */
+declare function createChartFormatters({ format, locale, timeZone, formatValue, xType, yType, granularity }: CreateChartFormattersOptions): ChartTextFormatters;
+interface BuildChartDescriptionInput {
+  name: string;
+  type: ChartType;
+  state: ChartCardState;
+  summary: ChartSummary | null;
+  /** Keys of the series currently shown. */
+  visibleKeys: readonly string[];
+  formatters: ChartTextFormatters;
+  labels: ChartCardLabels;
+  /** Plain-text name of the measure, for "revenue by channel". */
+  measureName: string;
+  /** Plain-text name of the primary dimension. */
+  dimensionName: string;
+  aggregate?: ChartAggregate;
+  stale?: boolean;
+}
+/**
+ * The card's own accessible description (the figure's `aria-describedby`
+ * text): what the chart is, what it covers, where its extremes are, and what
+ * has been folded, hidden or aggregated away. Amy Cesal's alt-text formula —
+ * chart type, what data, why it is here — generated from the props, because a
+ * card whose face carries no text has nothing else for a screen reader to read.
+ */
+declare function buildChartDescription({ name, type, state, summary, visibleKeys, formatters, labels, measureName, dimensionName, aggregate, stale }: BuildChartDescriptionInput): string;
+/**
+ * The plot's own `aria-label` — set live through `view.description`, so Vega
+ * stamps it on the `graphics-document` node. Deliberately shorter than the
+ * card description: the figure's description already carries the detail, and
+ * repeating it makes a screen reader say everything twice.
+ */
+declare function buildChartPlotDescription({ type, measureName, dimensionName, labels }: {
+  type: ChartType;
+  measureName: string;
+  dimensionName: string;
+  labels: ChartCardLabels;
+}): string;
+interface ChartTableColumn {
+  key: string;
+  label: string;
+  /** Numeric columns are right-aligned and set in tabular figures. */
+  numeric: boolean;
+}
+interface ChartTableModel {
+  columns: ChartTableColumn[];
+  rows: string[][];
+  /** Rows the table shows out of the rows the plot draws — a large dataset is capped. */
+  shown: number;
+  total: number;
+}
+/** How many rows the table twin renders before it says "first N of M". */
+declare const CHART_TABLE_ROW_CAP = 200;
+/**
+ * Every value the plot draws, as text — the keyboard path to the data, since
+ * Vega gives marks none. Columns follow the form: a part-to-whole chart gets a
+ * share column, a range bar gets both bounds, a bubble gets its size, a
+ * waterfall gets the running total the bars stand on.
+ */
+declare function buildChartTableModel({ type, summary, formatters, labels, measureName, dimensionName, seriesName, sizeName, cap }: {
+  type: ChartType;
+  summary: ChartSummary | null;
+  formatters: ChartTextFormatters;
+  labels: ChartCardLabels;
+  measureName: string;
+  dimensionName: string;
+  seriesName: string;
+  sizeName?: string;
+  cap?: number;
+}): ChartTableModel | null;
+//#endregion
+export { BuildChartDescriptionInput, CHART_OTHER_KEY, CHART_TABLE_ROW_CAP, CHART_TYPES, CHART_TYPE_ORDER, ChartAggregate, ChartCardLabels, ChartCardSize, ChartCardState, ChartCardStatus, ChartColorMode, ChartExtent, ChartExtremes, ChartFieldType, ChartIntent, ChartLegendKind, ChartRampBucket, ChartRecord, ChartRow, ChartSeriesColor, ChartSeriesInfo, ChartSort, ChartSummary, ChartTableColumn, ChartTableModel, ChartTextFormatters, ChartType, ChartTypeFields, ChartTypeInfo, ChartWebRow, CreateChartFormattersOptions, DEFAULT_CHART_LABELS, DeriveChartStateInput, NormalizeChartDataOptions, RADAR_RING_FRACTIONS, buildChartDescription, buildChartPlotDescription, buildChartTableModel, buildRadarWebRows, buildRampBuckets, chartSeriesColorAt, createChartFormatters, deriveChartState, hasEnoughData, inferFieldType, inferGranularity, missingChartFields, normalizeChartData, resolveChartColorMode, resolveChartLabels };