@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/SankeyCard/SankeyCard.chart.js

@@ -0,0 +1,249 @@
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/SankeyCard/SankeyCard.chart.ts
+/** Sampled ribbon edges: `RIBBON_SAMPLES` rows per flow (`SankeyRibbonRow`). */
+const SANKEY_RIBBONS_DATASET = "ribbons";
+/** One row per node — the rect, the name and the value line (`SankeyNodeRow`). */
+const SANKEY_NODES_DATASET = "nodes";
+/** The pointed flow. */
+const SANKEY_HOVER_PARAM = "hover";
+/** The pointed node. */
+const SANKEY_NODE_HOVER_PARAM = "nodeHover";
+/**
+* The reader's chosen node, driven from React with `view.signal`. A VARIABLE
+* param, not a selection: consumer-owned state pushed into a selection would
+* live in that selection's `_store` dataset and fight the reader's own
+* pointer, which is the bridge's rule.
+*/
+const SANKEY_SELECTED_PARAM = "selectedNode";
+const RIBBON_OPACITY = .7;
+const RIBBON_HOVER_OPACITY = .92;
+const RIBBON_MUTED_OPACITY = .16;
+const NODE_OPACITY = 1;
+const NODE_MUTED_OPACITY = .35;
+const LABEL_OFFSET = 6;
+/** True while a node is selected and this row does not touch it. */
+const RIBBON_IN_PLAY = `${SANKEY_SELECTED_PARAM} == null || datum.s === ${SANKEY_SELECTED_PARAM} || datum.t === ${SANKEY_SELECTED_PARAM}`;
+const NODE_IN_PLAY = `${SANKEY_SELECTED_PARAM} == null || datum.k === ${SANKEY_SELECTED_PARAM}`;
+/**
+* Builds the flow diagram: the ribbons, then the node rects over their ends,
+* then the names.
+*
+* Colour rides the data (`c`, with `scale: null`) rather than a scale, so
+* whichever job the card gave it — one emphasis hue, the declared polarity,
+* or an identity slot per outcome — the spec stays structural and re-colouring
+* is a data push that cannot repaint a survivor it did not mean to.
+*/
+function buildSankeyPlotSpec(options, tokens) {
+	const { height, nodeWidth, padLeft, padRight, padTop, padBottom, labelLimit, labels, labelEndsOutward, showValues, tooltip, selectable, valueFormat, fromTitle, toTitle, valueTitle, locale } = options;
+	const x = {
+		field: "x",
+		type: "quantitative",
+		scale: {
+			domain: [0, 1],
+			nice: false,
+			zero: false
+		},
+		axis: null,
+		title: null
+	};
+	const y = {
+		field: "y",
+		type: "quantitative",
+		scale: {
+			domain: [1, 0],
+			nice: false,
+			zero: false
+		},
+		axis: null,
+		title: null
+	};
+	const layers = [];
+	const ribbonOpacity = (() => {
+		const conditions = [];
+		if (tooltip) conditions.push({
+			param: SANKEY_HOVER_PARAM,
+			empty: false,
+			value: RIBBON_HOVER_OPACITY
+		});
+		if (selectable) conditions.push({
+			test: RIBBON_IN_PLAY,
+			value: RIBBON_OPACITY
+		});
+		if (conditions.length === 0) return { value: RIBBON_OPACITY };
+		return {
+			condition: conditions,
+			value: selectable ? RIBBON_MUTED_OPACITY : RIBBON_OPACITY
+		};
+	})();
+	layers.push({
+		data: { name: SANKEY_RIBBONS_DATASET },
+		...tooltip ? { params: [{
+			name: SANKEY_HOVER_PARAM,
+			select: {
+				type: "point",
+				on: "pointerover",
+				clear: "pointerout",
+				fields: ["id"]
+			}
+		}] } : {},
+		mark: {
+			type: "area",
+			line: false,
+			interpolate: "linear",
+			aria: false
+		},
+		encoding: {
+			x,
+			y,
+			y2: { field: "y2" },
+			detail: {
+				field: "id",
+				type: "nominal"
+			},
+			fill: {
+				field: "c",
+				type: "nominal",
+				scale: null,
+				legend: null
+			},
+			fillOpacity: ribbonOpacity,
+			...tooltip ? { tooltip: [
+				{
+					field: "sl",
+					type: "nominal",
+					title: fromTitle
+				},
+				{
+					field: "tl",
+					type: "nominal",
+					title: toTitle
+				},
+				{
+					field: "v",
+					type: "quantitative",
+					title: valueTitle,
+					format: valueFormat,
+					formatType: "arcNumber"
+				}
+			] } : {}
+		}
+	});
+	const nodeOpacity = selectable ? { opacity: {
+		condition: [{
+			test: NODE_IN_PLAY,
+			value: NODE_OPACITY
+		}],
+		value: NODE_MUTED_OPACITY
+	} } : {};
+	layers.push({
+		data: { name: SANKEY_NODES_DATASET },
+		...tooltip ? { params: [{
+			name: SANKEY_NODE_HOVER_PARAM,
+			select: {
+				type: "point",
+				on: "pointerover",
+				clear: "pointerout",
+				fields: ["k"]
+			}
+		}] } : {},
+		mark: {
+			type: "rect",
+			width: nodeWidth,
+			cornerRadius: 1,
+			aria: false
+		},
+		encoding: {
+			x,
+			y,
+			y2: { field: "y2" },
+			fill: {
+				field: "c",
+				type: "nominal",
+				scale: null,
+				legend: null
+			},
+			...nodeOpacity
+		}
+	});
+	if (labels) {
+		const visible = [{ filter: "datum.lab" }];
+		const align = labelEndsOutward ? { expr: "datum.first ? 'right' : 'left'" } : { expr: "'left'" };
+		const dx = labelEndsOutward ? { expr: `datum.first ? ${-(nodeWidth / 2 + LABEL_OFFSET)} : ${nodeWidth / 2 + LABEL_OFFSET}` } : { expr: String(nodeWidth / 2 + LABEL_OFFSET) };
+		layers.push({
+			data: { name: SANKEY_NODES_DATASET },
+			transform: visible,
+			mark: {
+				type: "text",
+				fontSize: 11,
+				fontWeight: 500,
+				baseline: showValues ? "bottom" : "middle",
+				dy: showValues ? -1 : 0,
+				fill: tokens.foreground,
+				align,
+				dx,
+				limit: { expr: labelLimit },
+				aria: false
+			},
+			encoding: {
+				x,
+				y: {
+					...y,
+					field: "mid"
+				},
+				text: {
+					field: "label",
+					type: "nominal"
+				}
+			}
+		});
+		if (showValues) layers.push({
+			data: { name: SANKEY_NODES_DATASET },
+			transform: [{ filter: "datum.lab && datum.h >= 24" }],
+			mark: {
+				type: "text",
+				fontSize: 10,
+				baseline: "top",
+				dy: 1,
+				fill: tokens.mutedForeground,
+				align,
+				dx,
+				limit: { expr: labelLimit },
+				aria: false
+			},
+			encoding: {
+				x,
+				y: {
+					...y,
+					field: "mid"
+				},
+				text: {
+					field: "vt",
+					type: "nominal"
+				}
+			}
+		});
+	}
+	const params = [];
+	if (selectable) params.push({
+		name: SANKEY_SELECTED_PARAM,
+		value: null
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 320,
+		height,
+		autosize: { type: "none" },
+		padding: {
+			left: padLeft,
+			right: padRight,
+			top: padTop,
+			bottom: padBottom
+		},
+		background: "transparent",
+		...params.length > 0 ? { params } : {},
+		layer: layers,
+		config: arcVegaConfig(tokens, { locale })
+	};
+}
+//#endregion
+export { SANKEY_HOVER_PARAM, SANKEY_NODES_DATASET, SANKEY_NODE_HOVER_PARAM, SANKEY_RIBBONS_DATASET, SANKEY_SELECTED_PARAM, buildSankeyPlotSpec };

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

@@ -0,0 +1,185 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { SANKEY_MAX_IDENTITY, SANKEY_MIN_FLOWS, SankeyAlign, SankeyCardLabels, SankeyCardSize, SankeyCardStatus, SankeyColor, SankeyLink, SankeyNode, SankeyNodeLabels, SankeyNodeOrder } from "./SankeyCard.model.js";
+import { ReactNode } from "react";
+import { BoxProps } from "@arcfusionz/arc-primitive-ui";
+import { TopLevelSpec } from "vega-lite";
+import { Result } from "vega-embed";
+//#region src/components/SankeyCard/SankeyCard.d.ts
+interface SankeyCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The flow's name — the panel's heading. Pass `name` too when this is not plain text. */
+  label: ReactNode;
+  /** Plain-text name used in the generated descriptions and control labels. Defaults to `label` when it is a string. */
+  name?: string;
+  /** What the flow means, shown in a tooltip behind an info control beside the label and exposed to assistive technology as its description. */
+  hint?: string;
+  /**
+   * The flows — `{ source, target, value }` by node key, plus an optional
+   * `label` naming one and a `tone` for `color="polarity"`. Two rows with the
+   * same source and target are ONE ribbon (their values add). A negative
+   * value, a self-loop, a flow to an undeclared node and a flow that closes a
+   * cycle are each rejected, counted, and reported in the details popover and
+   * the description — never silently dropped. Pass `[]` while loading.
+   */
+  links: readonly SankeyLink[];
+  /**
+   * The nodes. **Optional** — the card derives the set from `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. With `nodes` declared, a link naming an unknown key is a data
+   * error rather than a new node.
+   */
+  nodes?: readonly SankeyNode[];
+  /**
+   * Which column a node lands in. `justify` (default) pushes every terminal
+   * bucket to the last column, so "where did the volume end up" is one
+   * vertical scan; `left` leaves an early exit in the column it was reached
+   * in, so the x axis reads as elapsed stages; `right` counts back from the
+   * sinks, for when the question is what FEEDS an outcome. Stamped as
+   * `data-align`.
+   */
+  align?: SankeyAlign;
+  /**
+   * What colour means. `none` (default) draws every ribbon in the one
+   * emphasis hue — thickness and position already carry the comparison, and a
+   * hue per stage would only restate the x position. `polarity` uses each
+   * link's `tone` on the diverging ends (the funnel answer); `terminal` gives
+   * each outcome its own identity slot (where did it land); `node` gives each
+   * source one (what produced this). The identity modes cap at
+   * `SANKEY_MAX_IDENTITY` and fold the tail to gray rather than repeat a
+   * slot. Stamped as `data-color`.
+   */
+  color?: SankeyColor;
+  /**
+   * How nodes stack inside a column. `declared` — the consumer's own order,
+   * the default when `nodes` is given — keeps a node in its place through a
+   * data change; `value` puts the largest first, and is the default when
+   * `nodes` is omitted. `Other` always sits last either way.
+   */
+  nodeOrder?: SankeyNodeOrder;
+  /**
+   * Nodes a column may hold before its smallest fold into one `Other` node.
+   * The fold re-routes their flows and the details popover still names every
+   * member, so nothing disappears. Default 8. Stamped as `data-folded` when
+   * it bites.
+   */
+  maxNodesPerStage?: number;
+  /**
+   * Which node names the plot draws. `all` (default) names every node tall
+   * enough to hold one, interior names sitting to the right of their node;
+   * `ends` names the first and last columns only, each in its own gutter, so
+   * no name sits over a ribbon — the right choice on a narrow panel; `none`
+   * leaves every name to the details popover. Stamped as `data-labels`.
+   */
+  nodeLabels?: SankeyNodeLabels;
+  /** Print each node's total under its name, for nodes tall enough for both lines. Default `false`. */
+  showValues?: boolean;
+  /**
+   * Names for the columns, left to right — rendered as real text above the
+   * plot rather than as Vega marks, so they are selectable and reach
+   * assistive technology directly. A shorter array leaves the later columns
+   * unnamed.
+   */
+  stages?: readonly string[];
+  /** The node rect's pixel width. Defaults to the size's own. */
+  nodeWidth?: number;
+  /** Pixels between stacked nodes. Defaults to the size's own. */
+  nodeGap?: number;
+  /** 0 draws straight ribbons, 1 (default 0.5) the fully eased S. */
+  curvature?: number;
+  /**
+   * Crossing-reduction passes over the layout. Default 6 — enough for the
+   * graphs a panel can hold, and fixed so a Chromatic baseline never drifts.
+   * Raise it for a dense graph; 0 keeps the declared stacking exactly.
+   */
+  iterations?: number;
+  /** The plot's inner height in pixels. Defaults to the size's own, and grows with the busiest column. */
+  height?: number;
+  /**
+   * Key of the node whose paths are highlighted, controlled — pair with
+   * `onNodeSelect`. `null` highlights nothing. Every flow that misses the
+   * node recedes.
+   */
+  selectedNode?: string | null;
+  /** The highlighted node on first render when `selectedNode` is uncontrolled. */
+  defaultSelectedNode?: string | null;
+  /** Called with the node's key when the reader picks one, or `null` when the selection is cleared. */
+  onNodeSelect?: (key: string | null) => void;
+  /** `arcNumber` grammar for every volume: `number[:digits]`, `integer`, `compact[:digits]`, `percent[:digits]`, `currency:CODE[:digits|compact]`. */
+  format?: string;
+  /** `arcNumber` grammar for a flow's share of its source. Default `percent:0`. */
+  shareFormat?: string;
+  /** Custom formatter for volumes. Takes precedence over `format`. */
+  formatValue?: (value: number) => string;
+  /** Columns the skeleton reserves before `links` arrive, so the panel is already its final height. Default 3. */
+  expectedStages?: number;
+  /** Nodes per column the skeleton reserves before they arrive. Default 3. */
+  expectedNodes?: number;
+  /**
+   * The takeaway in a sentence, rendered beside the AI mark under the plot.
+   * Wrap values in `<strong>`. Omit for the card's own generated sentence —
+   * the main flow out of the first stage and the largest declared loss;
+   * `false` for none.
+   */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with data already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: SankeyCardStatus;
+  /** The consumer's filter is active — no flow then reads as no-match rather than empty. */
+  filtered?: boolean;
+  /** The data is older than the product's freshness rule (TanStack Query's `isStale`). Shows a badge and stamps `data-stale`. */
+  stale?: boolean;
+  /** When the data was last true. Rendered as an "as of" line and included in the description. */
+  updatedAt?: Date | string | number;
+  /** How `updatedAt` is written, in the card's `locale` and `timeZone`. Default `day`. */
+  updatedAtFormat?: ArcTimeGranularity | ((date: Date) => string);
+  /** Recovery action for the error state; renders a retry button when set. */
+  onRetry?: () => void;
+  /** Recovery action for the no-match state; renders a clear-filters button when set. */
+  onClearFilters?: () => void;
+  /** Density: `sm` for a dense grid, `md` (default), `lg` for a hero panel. */
+  size?: SankeyCardSize;
+  /** Heading level of the label for the document outline. Default 3. */
+  titleLevel?: 2 | 3 | 4 | 5 | 6;
+  /** BCP 47 locale for every number and date. Thai products on the Gregorian calendar pass `th-TH-u-ca-gregory`. */
+  locale?: string;
+  /** IANA time zone for the as-of date. Defaults to the runtime's — pass it for deterministic output. */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<SankeyCardLabels>;
+  /** Replaces the generated accessible description of the whole card. */
+  description?: string;
+  /** Trailing header slot — a ghost `Button` or `Menu`. */
+  action?: ReactNode;
+  /** Open the details popover on first render. */
+  defaultTableOpen?: boolean;
+  /** Hide the header info button. Only when another surface exposes the same values to keyboard and screen-reader users. */
+  hideTableToggle?: boolean;
+  /** Hide the `Alert` that reports broken cycles, unaccounted volume and rejected flows. The description still carries them. */
+  hideNotes?: boolean;
+  /** Called with vega-embed's result once the plot mounts — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A flow panel — the tenth member of the analytics card family, and the only
+ * one whose subject is the **edges of a graph** rather than a measure.
+ *
+ * `links` of `{ source, target, value }` become a sankey: stages as columns,
+ * nodes as rects, and each flow as a ribbon whose thickness is its quantity.
+ * It answers the one question no other card can — *what became of this
+ * volume, and where did it leak* — because only a flow diagram draws an edge
+ * as a quantity while keeping the chain intact.
+ *
+ * The card enforces what makes the form honest. A cycle is broken and
+ * reported rather than drawn. Volume that arrives and does not leave shows as
+ * unfilled node and is named, never balanced away. A graph with fewer than
+ * two columns is refused, because a part-to-whole belongs in a `Progress`
+ * bar. Colour defaults to a single emphasis hue, since thickness and position
+ * already carry the comparison. And every quantity a ribbon encodes is also
+ * text — in the tooltip, the flow table with its share of the source, and the
+ * node table with in, out and what did not reconcile — which is what makes
+ * the weakest channel in the family safe to use.
+ */
+declare const SankeyCard: import("react").ForwardRefExoticComponent<SankeyCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { SankeyCard, SankeyCardProps };