@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,501 @@
+//#region src/components/SankeyCard/SankeyCard.model.d.ts
+/** What the consumer's transport reports. */
+type SankeyCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the links and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type SankeyCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "insufficient" | "error";
+type SankeyCardSize = "sm" | "md" | "lg";
+/**
+ * Which column a node lands in.
+ *
+ * - `justify` (default): depth is the longest path from a source, but every
+ *   node with no outgoing flow is pushed to the LAST column. The funnel
+ *   reading — terminal buckets line up on the right however early they were
+ *   reached, so "where did the volume end up" is one vertical scan.
+ * - `left`: depth is the longest path from a source, and a terminal bucket
+ *   stays in the column it was reached in. The process reading — the x axis
+ *   is elapsed stages, so an early exit is visibly early.
+ * - `right`: depth is counted back from the sinks, so sources spread out
+ *   instead of terminals. Reach for it when the question is what FEEDS an
+ *   outcome rather than what becomes of an input.
+ *
+ * Stamped as `data-align`.
+ */
+type SankeyAlign = "left" | "right" | "justify";
+/**
+ * What colour means on the ribbons — one job per chart.
+ *
+ * - `none` (default): every ribbon takes the one emphasis hue. Thickness and
+ *   position already carry the whole comparison, so this is the honest
+ *   default: a hue per stage would only restate the x position, which is
+ *   decoration, and decoration still costs attention.
+ * - `polarity`: the `tone` each link declares — retained, lost, neutral — on
+ *   the diverging ends. The one licensed use of a good/bad hue on a mark,
+ *   because here the value genuinely MEANS good or bad. The funnel answer.
+ * - `terminal`: identity by the outcome each flow ends in, from the fixed
+ *   categorical slots. The allocation answer — where did the volume land.
+ * - `node`: identity by the flow's source node. The attribution answer —
+ *   which input produced this.
+ *
+ * `terminal` and `node` are capped by the theme's identity budget
+ * (`SANKEY_MAX_IDENTITY`): past it the tail folds to the context gray and the
+ * card stamps `data-over-identity` rather than repeating a slot, because two
+ * entities in one hue is a lie a legend cannot fix. Stamped as `data-color`.
+ */
+type SankeyColor = "none" | "polarity" | "terminal" | "node";
+/**
+ * How nodes are stacked inside their column.
+ *
+ * - `declared` (default when `nodes` is given): the consumer's own order. A
+ *   node keeps its place — and its identity colour slot — when the data
+ *   changes, so a filter cannot reshuffle the diagram under the reader.
+ * - `value`: largest first. The ranking read, and the default when `nodes` is
+ *   omitted and there is no declared order to honour.
+ */
+type SankeyNodeOrder = "declared" | "value";
+/** What a flow means, when it means anything: volume kept, volume lost, or neither. */
+type SankeyTone = "positive" | "negative" | "neutral";
+/**
+ * Which node names the plot draws.
+ *
+ * - `all` (default): every node. Interior names sit to the right of their
+ *   node, over the ribbons, in the foreground text role.
+ * - `ends`: the first and last columns only — the two that carry the question
+ *   — each in its own gutter, so no name ever sits over a ribbon. The right
+ *   choice on a narrow panel.
+ * - `none`: no names on the plot; the table and the tooltip carry every one.
+ *
+ * Stamped as `data-labels`.
+ */
+type SankeyNodeLabels = "all" | "ends" | "none";
+/**
+ * The theme ships three categorical identity slots (`chart-1…3`), because
+ * three of the brand's six hues are reserved for status. An identity encoding
+ * past that folds its tail to the context gray instead of repeating a slot.
+ */
+declare const SANKEY_MAX_IDENTITY = 3;
+/** Below two columns there is no flow to draw — one column is a bar chart, and the card says so instead of drawing a sankey of nothing. */
+declare const SANKEY_MIN_STAGES = 2;
+/**
+ * Below two flows there is nothing to compare. A diagram of ONE ribbon is a
+ * picture of a single number: it has no sibling to weigh it against, no split
+ * to read a share at, and no chain — every reason this card exists is
+ * missing. The reader is better served by a number, so the card declines and
+ * says so rather than drawing a decoration.
+ */
+declare const SANKEY_MIN_FLOWS = 2;
+/** Points sampled along each ribbon edge. Fixed, so a Chromatic baseline never drifts on it. */
+declare const RIBBON_SAMPLES = 20;
+/**
+ * One node, declared. `nodes` is optional — the card derives the set from the
+ * links — but declaring it fixes the ORDER, which fixes each node's place in
+ * its column and its identity colour slot, so the diagram does not reshuffle
+ * when the data moves.
+ */
+interface SankeyNode {
+  /** Stable id the links refer to. Defaults to `label`. */
+  key?: string;
+  label: string;
+}
+/** One flow, from one node to another. `source` and `target` are node keys. */
+interface SankeyLink {
+  source: string;
+  target: string;
+  /** The quantity flowing. Must be finite and ≥ 0 — a negative flow has no thickness and is dropped, counted and reported. */
+  value: number;
+  /** Names this specific flow in the tooltip and the table, in place of `source → target`. */
+  label?: string;
+  /** What the flow means, for `color="polarity"`. Omitted reads as `neutral`. */
+  tone?: SankeyTone;
+}
+/** A node after normalisation: its column, its totals, and whether the two agree. */
+interface SankeyNodeInfo {
+  key: string;
+  label: string;
+  /** Column index, 0-based, after `align`. */
+  depth: number;
+  /** Position in the consumer's declared order — the identity slot, never the rank, so a filter cannot repaint the survivors. */
+  index: number;
+  /** Position inside its own column, top to bottom. */
+  order: number;
+  /** `max(inValue, outValue)` — the d3-sankey convention, so an imbalance shows as unfilled node instead of being hidden. */
+  value: number;
+  inValue: number;
+  outValue: number;
+  /**
+   * `inValue - outValue`: volume that arrived and did not leave through any
+   * declared link. Never balanced away — an unmodelled leak is a finding, and
+   * the card reports it in the table, the caption and `data-imbalanced`.
+   */
+  imbalance: number;
+  isSource: boolean;
+  isSink: boolean;
+  /** This node is the `Other` fold of its column. */
+  folded: boolean;
+  /** Labels folded into this node, so the table can still name every one. */
+  members: string[];
+  /** The paintable colour, baked in so the spec stays structural. */
+  color: string;
+}
+/** A flow after normalisation, with its share of the volume leaving its source. */
+interface SankeyLinkInfo {
+  /** `source→target`, unique after aggregation. */
+  id: string;
+  source: string;
+  target: string;
+  sourceLabel: string;
+  targetLabel: string;
+  /** The consumer's own name for this flow, when it gave one. */
+  label?: string;
+  value: number;
+  /** `value / source.outValue` — the part-to-whole at this split. `null` when nothing leaves the source. */
+  share: number | null;
+  tone: SankeyTone;
+  color: string;
+  /** The source's column, so a flow can be read as "between stage n and n+1". */
+  depth: number;
+  /** The target's column. Greater than `depth` for every drawn flow. */
+  targetDepth: number;
+}
+/** A flow the graph could not keep, and why — reported, never silently dropped. */
+interface SankeyRejectedLink {
+  source: string;
+  target: string;
+  value: number;
+  reason: "negative" | "self-loop" | "cycle" | "unknown-node";
+}
+interface SankeySummary {
+  nodes: SankeyNodeInfo[];
+  links: SankeyLinkInfo[];
+  /** Nodes grouped by column, each already in stacking order. */
+  columns: SankeyNodeInfo[][];
+  /** Number of columns. Below `SANKEY_MIN_STAGES` the card refuses to draw a sankey. */
+  stages: number;
+  /** Volume entering the diagram — the total leaving the first column's nodes. */
+  total: number;
+  /** Flows with a value greater than zero — what the plot can actually draw. */
+  count: number;
+  /** Flows the graph rejected, with the reason. */
+  rejected: SankeyRejectedLink[];
+  /** A cycle was broken to make the graph drawable. */
+  cycles: number;
+  /** Nodes whose inflow and outflow disagree. */
+  imbalanced: SankeyNodeInfo[];
+  /** A column exceeded `maxNodesPerStage` and its tail was folded into `Other`. */
+  folded: boolean;
+  /** An identity encoding ran past the theme's slot budget and its tail took the context gray. */
+  overIdentity: boolean;
+}
+/** Node geometry in normalised [0,1] coordinates — `y` measured DOWNWARD from the top, which the plot's reversed y scale undoes. */
+interface SankeyNodeRow {
+  k: string;
+  /** The column's centre line. The node rect straddles it with a pixel `mark.width`, so the geometry carries no pixel width of its own. */
+  x: number;
+  y: number;
+  y2: number;
+  /** Vertical middle, where the name sits. */
+  mid: number;
+  /** Node height in PIXELS, so a name only prints its value line when the node is tall enough to hold one. */
+  h: number;
+  label: string;
+  /** Formatted total, for the value line. */
+  vt: string;
+  c: string;
+  /** Column position flags — the first and last columns label into their own gutters, the rest label over the ribbons. */
+  first: boolean;
+  last: boolean;
+  /** Draw this node's name. */
+  lab: boolean;
+}
+/** One sampled point along a ribbon. `y`/`y2` are its two edges at that x. */
+interface SankeyRibbonRow {
+  id: string;
+  x: number;
+  y: number;
+  y2: number;
+  c: string;
+  /** Tooltip and highlight fields, carried on every sample so no lookup is needed at hover time. */
+  sl: string;
+  tl: string;
+  v: number;
+  /** Formatted share of the source's outflow, or the missing marker. */
+  sh: string;
+  s: string;
+  t: string;
+}
+interface SankeyLayout {
+  nodes: SankeyNodeRow[];
+  ribbons: SankeyRibbonRow[];
+  /** Normalised x centre per column, for the DOM stage headings above the plot. */
+  columnCenters: number[];
+  /**
+   * Drawable flows whose thickness lands under `HAIRLINE_PX` — real volume
+   * the plot cannot show at this scale.
+   *
+   * The card REPORTS these rather than widening them. A minimum ribbon width
+   * would make thickness stop meaning quantity, and it cannot be done
+   * honestly anyway: widening a ribbon past its share would overflow the node
+   * it leaves, so the sum of the ribbons at a node would no longer be the
+   * node. The proportions stay exact, the note says the smallest flows are
+   * below a pixel, and the table carries their values — which is how
+   * StatusCard handles the same problem with a 17-second outage.
+   */
+  hairlines: number;
+}
+/** Below this many pixels a ribbon is not a shape a reader can see, whatever it means. */
+declare const HAIRLINE_PX = 1.5;
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface SankeyCardLabels {
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  stale: string;
+  asOf: string;
+  /** The card cannot draw a flow from a single column. */
+  insufficient: string;
+  /** Column headers of the flow table. */
+  tableFrom: string;
+  tableTo: string;
+  tableValue: string;
+  tableShare: string;
+  /** Column headers of the node table. */
+  tableNode: string;
+  tableStage: string;
+  tableIn: string;
+  tableOut: string;
+  tableUnaccounted: string;
+  /** The `Other` fold's name, and how the table lists what went into it. */
+  other: string;
+  otherMembers: (list: string) => string;
+  /** Tooltip row titles. */
+  flowTitle: string;
+  shareTitle: string;
+  /** Said once, politely, when the reader picks another node. */
+  selectedNode: (label: string) => string;
+  /** Clears the node selection. */
+  clearSelection: string;
+  /** Accessible name of a node's own button in the table — the keyboard path Vega does not provide. */
+  selectNode: (label: string) => string;
+  showTable: (name: string) => string;
+  hideTable: (name: string) => string;
+  about: (name: string) => string;
+  loading: (name: string) => string;
+  tableCaption: (name: string) => string;
+  flowsCaption: (name: string) => string;
+  nodesCaption: (name: string) => string;
+  /** Warns that a cycle was broken so the graph could be drawn at all. */
+  cyclesNote: (count: number) => string;
+  /** Warns that some volume arrived at a node and did not leave through any declared flow. */
+  imbalanceNote: (count: number, amount: string) => string;
+  /** Says a column's tail was folded, so a reader never mistakes `Other` for a real bucket. */
+  foldedNote: (label: string) => string;
+  /** Says the smallest flows are below a pixel at this scale, so the table is the only place to read them. */
+  hairlineNote: (count: number) => string;
+  /** Says an identity encoding ran out of slots and the tail went gray. */
+  overIdentityNote: (max: number) => string;
+  /** Names the flows the graph could not keep. */
+  rejectedNote: (count: number) => string;
+  /** The takeaway: the biggest flow out of the first stage, and the biggest loss. */
+  flowSentence: (input: {
+    value: string;
+    total: string;
+    share: string;
+    from: string;
+    to: string;
+  }) => string;
+  lossSentence: (input: {
+    value: string;
+    share: string;
+    to: string;
+  }) => string;
+  /** Lists the stages on the plot. */
+  stageSummary: (count: number, list: string) => string;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    name: string;
+    stages: number;
+    nodes: number;
+    flows: number;
+    total: string;
+    stageList: string;
+  }) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+  /** The generated insight, as segments so the values render bold while the words stay plain. */
+  insight: (input: {
+    name: string;
+    total: string;
+    from: string;
+    to: string;
+    value: string;
+    share: string;
+    lossTo: string | null;
+    lossValue: string | null;
+    lossShare: string | null;
+  }) => SankeyInsightSegment[];
+}
+/** A piece of a generated insight: plain text, or a value the card sets in bold. */
+type SankeyInsightSegment = string | {
+  value: string;
+};
+declare const DEFAULT_SANKEY_LABELS: SankeyCardLabels;
+declare function resolveSankeyLabels(overrides?: Partial<SankeyCardLabels>): SankeyCardLabels;
+interface DeriveSankeyStateInput {
+  status: SankeyCardStatus;
+  /** At least one flow with a value greater than zero survived normalisation. */
+  hasFlow: boolean;
+  /** Anything is on screen already, so a reload is a refresh rather than a first load. */
+  hasData: boolean;
+  filtered: boolean;
+  /** Columns the graph resolved to. */
+  stages: number;
+  /** Flows with a value greater than zero — what the plot can actually draw. */
+  count: number;
+}
+/**
+ * The state machine. Error wins; loading over existing data is a refresh (the
+ * previous render stays under the veil); no flow at all is `no-match` when the
+ * consumer's filter caused it and `empty` otherwise.
+ *
+ * `insufficient` is the honest refusal: a single flow is a picture of one
+ * number, with no sibling to compare it against and no chain to follow, so
+ * the card declines to draw a sankey of it. The column floor is checked
+ * alongside it — a valid flow always spans two columns, so that half is a
+ * guard rather than a case, and it keeps the rule true if the depth
+ * assignment ever changes.
+ */
+declare function deriveSankeyState({ status, hasFlow, hasData, filtered, stages, count }: DeriveSankeyStateInput): SankeyCardState;
+interface NormalizeSankeyOptions {
+  align?: SankeyAlign;
+  nodeOrder?: SankeyNodeOrder;
+  color?: SankeyColor;
+  /** Nodes a column may hold before its smallest fold into `Other`. */
+  maxNodesPerStage?: number;
+  /** Identity slots in fixed order (`chart-1…N`). */
+  palette: readonly string[];
+  /** The one hue a `color="none"` diagram draws with. */
+  emphasis: string;
+  /** The gray a folded identity tail, and every node rect, takes. */
+  context: string;
+  /** The diverging ends, for `color="polarity"`. */
+  positive: string;
+  negative: string;
+  /** Localised name of the `Other` fold. */
+  otherLabel: string;
+}
+/**
+ * Normalises `nodes` and `links` into a drawable DAG plus everything the text
+ * surfaces read.
+ *
+ * The order of operations matters and each step is a decision:
+ * 1. Keys resolve (a repeat is suffixed), and a link naming a node that does
+ *    not exist is rejected rather than inventing one.
+ * 2. Flows aggregate — two `A→B` rows are one ribbon — and a negative or
+ *    self-looping flow is rejected. Each rejection is COUNTED and reported.
+ * 3. Cycles break, deterministically, and are reported.
+ * 4. Depths resolve through `align`.
+ * 5. A column past `maxNodesPerStage` folds its smallest into `Other`, links
+ *    re-route onto the fold and aggregate again. The table still names every
+ *    member, so the fold is honest rather than a disappearance.
+ * 6. Node values are `max(in, out)`, so an imbalance shows as unfilled node
+ *    rather than being balanced away.
+ * 7. Colours are assigned by the node's declared POSITION, never its rank, so
+ *    filtering cannot repaint the survivors.
+ *
+ * Returns `null` when there is nothing to speak of.
+ */
+declare function normalizeSankey(nodes: readonly SankeyNode[] | undefined, links: readonly SankeyLink[] | undefined, { align, nodeOrder, color, maxNodesPerStage, palette, emphasis, context, positive, negative, otherLabel }: NormalizeSankeyOptions): SankeySummary | null;
+interface LayoutSankeyOptions {
+  /**
+   * Plot height in pixels. The only pixel the layout needs: the horizontal
+   * axis is normalised to [0,1] and the node rect takes a pixel `mark.width`,
+   * so a WIDTH change is `view.width()` and never a relayout.
+   */
+  plotHeight: number;
+  /** Vertical pixels between stacked nodes. */
+  nodeGap: number;
+  /** Crossing-reduction passes. Fixed and small, so the result is deterministic. */
+  iterations?: number;
+  /** 0 draws straight ribbons, 1 the fully eased S. */
+  curvature?: number;
+  /** Which names the plot draws. */
+  labels?: SankeyNodeLabels;
+  /** A node shorter than this many pixels gets no name, because the name would collide with its neighbour's. */
+  minLabelHeight?: number;
+  formatValue: (value: number) => string;
+  formatShare: (share: number) => string;
+  missing: string;
+}
+/**
+ * Turns a summary into normalised geometry.
+ *
+ * Vertical: one value→pixel scale shared by every column (d3-sankey's `ky`),
+ * so a thickness means the same quantity wherever it appears — the whole
+ * point of the diagram. Nodes stack from the top with `nodeGap` between them,
+ * then a few relaxation passes slide each node toward the weighted centre of
+ * what it connects to and push overlaps apart again; that is what stops the
+ * ribbons knotting, and it is capped and deterministic so a baseline never
+ * drifts. Each node's flows are then stacked in the order of the partner's
+ * position, so ribbons run roughly parallel instead of crossing inside a node.
+ *
+ * Horizontal: a column is a normalised centre LINE. The node rect straddles
+ * it with a pixel width and the ribbons run line to line, passing under the
+ * opaque rects — so the geometry carries no pixel width at all and the same
+ * rows are correct at every panel width.
+ */
+declare function layoutSankey(summary: SankeySummary | null, { plotHeight, nodeGap, iterations, curvature, labels, minLabelHeight, formatValue, formatShare, missing }: LayoutSankeyOptions): SankeyLayout;
+interface SankeyTextFormatters {
+  formatValue: (value: number | null | undefined) => string;
+  formatShare: (share: number | null | undefined) => string;
+}
+declare function createSankeyFormatters({ format, shareFormat, locale, formatValue }: {
+  format: string;
+  shareFormat: string;
+  locale?: string;
+  formatValue?: (value: number) => string;
+}): SankeyTextFormatters;
+interface SankeyHighlights {
+  /** The biggest flow out of the first stage — what most of the volume did. */
+  main: SankeyLinkInfo;
+  /** The biggest flow the data called a loss, when any link declared a tone. */
+  loss: SankeyLinkInfo | null;
+}
+/**
+ * What the diagram is about: the largest flow leaving the first stage, and
+ * the largest declared loss anywhere. Only a link the consumer TONED as
+ * negative counts as a loss — the card never decides on its own that an
+ * outcome is bad.
+ */
+declare function deriveSankeyHighlights(summary: SankeySummary | null): SankeyHighlights | null;
+interface BuildSankeyDescriptionInput {
+  name: string;
+  state: SankeyCardState;
+  summary: SankeySummary | null;
+  formatters: SankeyTextFormatters;
+  asOfText?: string | null;
+  labels: SankeyCardLabels;
+}
+/** The figure's generated description: the volume, the stages, the main flow, the largest loss, the caveats and the as-of. */
+declare function buildSankeyDescription({ name, state, summary, formatters, asOfText, labels }: BuildSankeyDescriptionInput): string;
+/** The plot's own `aria-label` — the form, the volume, the stages. */
+declare function buildSankeyChartDescription({ name, summary, formatters, labels }: {
+  name: string;
+  summary: SankeySummary;
+  formatters: SankeyTextFormatters;
+  labels: SankeyCardLabels;
+}): string;
+/** The generated insight, as segments so the values render bold and the words stay plain. */
+declare function buildSankeyInsight({ name, summary, formatters, labels }: {
+  name: string;
+  summary: SankeySummary | null;
+  formatters: SankeyTextFormatters;
+  labels: SankeyCardLabels;
+}): SankeyInsightSegment[] | null;
+/** The plain-text reading of insight segments — for descriptions and tests. */
+declare function sankeyInsightToText(segments: readonly SankeyInsightSegment[]): string;
+//#endregion
+export { BuildSankeyDescriptionInput, DEFAULT_SANKEY_LABELS, DeriveSankeyStateInput, HAIRLINE_PX, LayoutSankeyOptions, NormalizeSankeyOptions, RIBBON_SAMPLES, SANKEY_MAX_IDENTITY, SANKEY_MIN_FLOWS, SANKEY_MIN_STAGES, SankeyAlign, SankeyCardLabels, SankeyCardSize, SankeyCardState, SankeyCardStatus, SankeyColor, SankeyHighlights, SankeyInsightSegment, SankeyLayout, SankeyLink, SankeyLinkInfo, SankeyNode, SankeyNodeInfo, SankeyNodeLabels, SankeyNodeOrder, SankeyNodeRow, SankeyRejectedLink, SankeyRibbonRow, SankeySummary, SankeyTextFormatters, SankeyTone, buildSankeyChartDescription, buildSankeyDescription, buildSankeyInsight, createSankeyFormatters, deriveSankeyHighlights, deriveSankeyState, layoutSankey, normalizeSankey, resolveSankeyLabels, sankeyInsightToText };