@arcfusionz/arc-analytic-ui 0.0.0

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/components/AnomalyCard/AnomalyCard.chart.d.ts

@@ -0,0 +1,64 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { AnomalyMark, AnomalyScale, AnomalyXType } from "./AnomalyCard.model.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/AnomalyCard/AnomalyCard.chart.d.ts
+/** Every period `{ x, y, lo, hi, ex, d, a, dir, c, sh, e, sc }` per `AnomalyRow`. */
+declare const ANOMALY_TABLE_DATASET = "table";
+/** One row per period, `{ x }` — the crosshair, revealed by the hover selection. */
+declare const ANOMALY_PERIODS_DATASET = "periods";
+/** Zero or one row `{ start, end }` — the selected excursion's wash. */
+declare const ANOMALY_SPAN_DATASET = "span";
+/** The shared-x hover selection: projected onto `x`, so pointing anywhere in a column reads that period. */
+declare const ANOMALY_HOVER_PARAM = "hover";
+/** Responsive x tick values, recomputed by Vega when the domain or the width changes. */
+declare const ANOMALY_X_TICKS_PARAM = "anomaly_x_ticks";
+interface AnomalyPlotSpecOptions {
+  /** `line` reads shape; `area` fills from zero. */
+  mark: AnomalyMark;
+  /** `auto` lets a line crop to its data range; `zero` includes zero. An area always includes zero. */
+  scale: AnomalyScale;
+  xType: AnomalyXType;
+  /** Plot height in pixels, axes included. */
+  height: number;
+  /** Draw both axes. `false` shrinks the plot toward a sparkline; the table still carries every value. */
+  axes: boolean;
+  /** Number of y ticks — the caller scales it to the plot's height. */
+  yTicks: number;
+  /** Draw the expected range as a band. */
+  band: boolean;
+  /** Draw the model's expected value as a dashed hairline inside the band. */
+  expected: boolean;
+  /** Wash the selected excursion's span (the `span` dataset carries it). */
+  span: boolean;
+  /** Wire the shared-x hover selection, the crosshair and the tooltip channel. */
+  tooltip: boolean;
+  /** Tooltip titles. */
+  xTitle: string;
+  yTitle: string;
+  /** `arcNumber` grammar for the y axis and the tooltip. */
+  plotFormat: string;
+  /** `arcTime` grammar for temporal x in tooltips (`day@en-US@Asia/Bangkok`). */
+  timeFormat: string;
+  /** `arcTime` grammar for x-axis tick labels — the axis-length form (`day-short@en-US@Asia/Bangkok`). */
+  axisTimeFormat: string;
+  locale?: string;
+  timeZone?: string;
+}
+/**
+ * Builds the plot: the readings as a line or an area, the expected range as a
+ * quiet band behind them, the model's expectation as a dashed hairline, and
+ * every reading that broke out marked with a direction-shaped, polarity-hued
+ * flag — so the deviation is DIRECTLY visible as a mark outside a region
+ * rather than as two numbers to subtract.
+ *
+ * Gaps stay gaps — a `null` reading breaks the path rather than dropping it to
+ * zero, and a period with no bounds leaves a hole in the band rather than
+ * pretending the range continued. A line may crop (`scale: "auto"`); an area
+ * keeps a zero baseline whatever `scale` says, because proportional ink is not
+ * negotiable. Either way the extent the caller passes spans the band as well
+ * as the readings, so a cropped scale can never hide the range being judged
+ * against.
+ */
+declare function buildAnomalyPlotSpec(options: AnomalyPlotSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { ANOMALY_HOVER_PARAM, ANOMALY_PERIODS_DATASET, ANOMALY_SPAN_DATASET, ANOMALY_TABLE_DATASET, ANOMALY_X_TICKS_PARAM, AnomalyPlotSpecOptions, buildAnomalyPlotSpec };

package/dist/components/AnomalyCard/AnomalyCard.chart.js

@@ -0,0 +1,341 @@
+import { AXIS_LABEL_LIMIT_EXPR } from "../../lib/vega/axisTicks.js";
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/AnomalyCard/AnomalyCard.chart.ts
+/** Every period `{ x, y, lo, hi, ex, d, a, dir, c, sh, e, sc }` per `AnomalyRow`. */
+const ANOMALY_TABLE_DATASET = "table";
+/** One row per period, `{ x }` — the crosshair, revealed by the hover selection. */
+const ANOMALY_PERIODS_DATASET = "periods";
+/** Zero or one row `{ start, end }` — the selected excursion's wash. */
+const ANOMALY_SPAN_DATASET = "span";
+/** The shared-x hover selection: projected onto `x`, so pointing anywhere in a column reads that period. */
+const ANOMALY_HOVER_PARAM = "hover";
+/** Responsive x tick values, recomputed by Vega when the domain or the width changes. */
+const ANOMALY_X_TICKS_PARAM = "anomaly_x_ticks";
+const POINT_SIZE = 64;
+const FLAG_SIZE = 120;
+const PLOT_PADDING = 8;
+const BAND_OPACITY = .22;
+const EXPECTED_DASH = [4, 3];
+const EXPECTED_OPACITY = .9;
+const SPAN_OPACITY = .5;
+const DISCRETE_DOMAIN_EXPR = `pluck(data('${ANOMALY_PERIODS_DATASET}'), 'x')`;
+/**
+* Builds the plot: the readings as a line or an area, the expected range as a
+* quiet band behind them, the model's expectation as a dashed hairline, and
+* every reading that broke out marked with a direction-shaped, polarity-hued
+* flag — so the deviation is DIRECTLY visible as a mark outside a region
+* rather than as two numbers to subtract.
+*
+* Gaps stay gaps — a `null` reading breaks the path rather than dropping it to
+* zero, and a period with no bounds leaves a hole in the band rather than
+* pretending the range continued. A line may crop (`scale: "auto"`); an area
+* keeps a zero baseline whatever `scale` says, because proportional ink is not
+* negotiable. Either way the extent the caller passes spans the band as well
+* as the readings, so a cropped scale can never hide the range being judged
+* against.
+*/
+function buildAnomalyPlotSpec(options, tokens) {
+	const { mark, scale, xType, height, axes, yTicks, band, expected, span, tooltip, xTitle, yTitle, plotFormat, timeFormat, axisTimeFormat } = options;
+	const zero = mark !== "line" || scale === "zero";
+	const discreteX = xType === "ordinal";
+	const xTickFormat = xType === "temporal" ? axisTimeFormat : "compact";
+	const xTickKind = xType === "temporal" ? "time" : xType === "quantitative" ? "number" : "text";
+	const axisArgs = `domain('x'), width, ${discreteX}, ${JSON.stringify(xTickFormat)}, ${JSON.stringify(xTickKind)}`;
+	const xAxisLabels = xType === "temporal" ? {
+		format: axisTimeFormat,
+		formatType: "arcTime"
+	} : xType === "quantitative" ? {
+		format: "compact",
+		formatType: "arcNumber"
+	} : {};
+	const xAxis = axes ? {
+		title: null,
+		orient: "bottom",
+		domain: true,
+		ticks: false,
+		grid: false,
+		values: { expr: ANOMALY_X_TICKS_PARAM },
+		labelAngle: 0,
+		labelAlign: { expr: `arcAxisLabelAlign(datum.value, ${axisArgs})` },
+		labelFlush: false,
+		labelOverlap: false,
+		labelLimit: { expr: AXIS_LABEL_LIMIT_EXPR },
+		labelPadding: 4,
+		...xAxisLabels
+	} : null;
+	const yAxis = axes ? {
+		title: null,
+		orient: "left",
+		domain: false,
+		ticks: false,
+		grid: true,
+		tickCount: yTicks,
+		labelOverlap: true,
+		labelPadding: 6,
+		format: plotFormat,
+		formatType: "arcNumber"
+	} : null;
+	const xField = discreteX ? {
+		field: "x",
+		type: "ordinal",
+		sort: null,
+		axis: xAxis,
+		...discreteX ? { scale: {
+			domain: { expr: DISCRETE_DOMAIN_EXPR },
+			paddingOuter: .05
+		} } : {}
+	} : {
+		field: "x",
+		type: xType,
+		axis: xAxis,
+		scale: {
+			nice: false,
+			...xType === "quantitative" ? { zero: false } : {}
+		}
+	};
+	const yField = {
+		field: "y",
+		type: "quantitative",
+		axis: yAxis,
+		scale: {
+			zero,
+			nice: axes
+		},
+		stack: null
+	};
+	const tooltipChannel = [xType === "temporal" ? {
+		field: "x",
+		type: "temporal",
+		title: xTitle,
+		format: timeFormat,
+		formatType: "arcTime"
+	} : xType === "quantitative" ? {
+		field: "x",
+		type: "quantitative",
+		title: xTitle,
+		format: "number",
+		formatType: "arcNumber"
+	} : {
+		field: "x",
+		type: "nominal",
+		title: xTitle
+	}, {
+		field: "y",
+		type: "quantitative",
+		title: yTitle,
+		format: plotFormat,
+		formatType: "arcNumber"
+	}];
+	const layers = [];
+	if (span) layers.push({
+		data: { name: ANOMALY_SPAN_DATASET },
+		mark: {
+			type: "rect",
+			fill: tokens.brush,
+			aria: false
+		},
+		encoding: {
+			x: {
+				...xField,
+				field: "start",
+				axis: xAxis,
+				...discreteX ? { bandPosition: 0 } : {}
+			},
+			x2: {
+				field: "end",
+				...discreteX ? { bandPosition: 1 } : {}
+			},
+			opacity: {
+				condition: {
+					test: "datum.on",
+					value: SPAN_OPACITY
+				},
+				value: 0
+			}
+		}
+	});
+	if (band) layers.push({
+		mark: {
+			type: "area",
+			line: false,
+			interpolate: "linear",
+			fill: tokens.context,
+			fillOpacity: BAND_OPACITY,
+			invalid: "break-paths-show-domains",
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: {
+				...yField,
+				field: "lo"
+			},
+			y2: { field: "hi" }
+		}
+	});
+	if (expected) layers.push({
+		mark: {
+			type: "line",
+			interpolate: "linear",
+			stroke: tokens.context,
+			strokeWidth: 1,
+			strokeDash: EXPECTED_DASH,
+			opacity: EXPECTED_OPACITY,
+			invalid: "break-paths-show-domains",
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: {
+				...yField,
+				field: "ex"
+			}
+		}
+	});
+	if (mark === "area") layers.push({
+		mark: {
+			type: "area",
+			line: false,
+			interpolate: "linear",
+			fill: tokens.emphasis,
+			fillOpacity: .12,
+			invalid: "break-paths-show-domains",
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField
+		}
+	});
+	layers.push({
+		mark: {
+			type: "line",
+			stroke: tokens.emphasis,
+			strokeWidth: 2,
+			strokeCap: "round",
+			strokeJoin: "round",
+			interpolate: "linear",
+			invalid: "break-paths-show-domains"
+		},
+		encoding: {
+			x: xField,
+			y: yField
+		}
+	});
+	layers.push({
+		mark: {
+			type: "point",
+			filled: true,
+			size: FLAG_SIZE,
+			stroke: tokens.background,
+			strokeWidth: 1.5,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			fill: {
+				field: "c",
+				type: "nominal",
+				scale: null,
+				legend: null
+			},
+			shape: {
+				field: "sh",
+				type: "nominal",
+				scale: null,
+				legend: null
+			},
+			opacity: {
+				condition: {
+					test: "datum.a",
+					value: 1
+				},
+				value: 0
+			}
+		}
+	});
+	if (tooltip) {
+		layers.push({
+			data: { name: ANOMALY_PERIODS_DATASET },
+			mark: {
+				type: "rule",
+				stroke: tokens.axis,
+				strokeWidth: 1,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				opacity: {
+					condition: {
+						param: ANOMALY_HOVER_PARAM,
+						empty: false,
+						value: .6
+					},
+					value: 0
+				}
+			}
+		});
+		layers.push({
+			params: [{
+				name: ANOMALY_HOVER_PARAM,
+				select: {
+					type: "point",
+					on: "pointermove",
+					nearest: true,
+					clear: "pointerout",
+					encodings: ["x"]
+				}
+			}],
+			mark: {
+				type: "point",
+				filled: true,
+				size: POINT_SIZE,
+				fill: tokens.emphasis,
+				stroke: tokens.background,
+				strokeWidth: 1.5,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				opacity: {
+					condition: {
+						test: { and: [{
+							param: ANOMALY_HOVER_PARAM,
+							empty: false
+						}, "!datum.a"] },
+						value: 1
+					},
+					value: 0
+				},
+				tooltip: tooltipChannel
+			}
+		});
+	}
+	const params = [];
+	if (axes) params.push({
+		name: ANOMALY_X_TICKS_PARAM,
+		expr: `arcAxisTicks(${axisArgs})`
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 320,
+		height,
+		autosize: {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: PLOT_PADDING,
+		background: "transparent",
+		data: { name: ANOMALY_TABLE_DATASET },
+		...params.length > 0 ? { params } : {},
+		layer: layers,
+		config: arcVegaConfig(tokens, {
+			locale: options.locale,
+			timeZone: options.timeZone
+		})
+	};
+}
+//#endregion
+export { ANOMALY_HOVER_PARAM, ANOMALY_PERIODS_DATASET, ANOMALY_SPAN_DATASET, ANOMALY_TABLE_DATASET, ANOMALY_X_TICKS_PARAM, buildAnomalyPlotSpec };

package/dist/components/AnomalyCard/AnomalyCard.d.ts

@@ -0,0 +1,169 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { AnomalyBounds, AnomalyCardLabels, AnomalyCardSize, AnomalyCardStatus, AnomalyDeltaMode, AnomalyGoodDirection, AnomalyHeadline, AnomalyMark, AnomalyPoint, AnomalyScale } from "./AnomalyCard.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/AnomalyCard/AnomalyCard.d.ts
+interface AnomalyCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The measure'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;
+  /** Definition of the metric, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /**
+   * The readings, oldest first: `{ x, y, lower?, upper?, expected?, anomaly?, score? }`.
+   * `x` is a `Date`, an ISO string, a number or a period label; `y` the
+   * reading, or `null` for a period with no measurement — drawn as a gap,
+   * never as zero, and never flagged. `lower`/`upper` are that period's own
+   * expected range and fall back to `bounds`; `expected` is the model's
+   * predicted value; `anomaly` is the detector's own verdict and overrides
+   * the range in BOTH directions; `score` is its own score, printed through
+   * `scoreFormat`. Pass `[]` while loading to reserve the plot's height.
+   */
+  points: readonly AnomalyPoint[];
+  /**
+   * A flat expected range — a control limit or an SLO — applied to every
+   * period that carries no bounds of its own. Pass one side for a ceiling or
+   * a floor (`{ upper: 500 }` reads as `≤ 500`). A period with no bounds from
+   * either source is plotted but never judged, and the card says so.
+   */
+  bounds?: AnomalyBounds;
+  /**
+   * Key of the excursion the reader has selected, controlled — pair with
+   * `onSelectedEpisodeChange`. Its span is washed in the plot and its row is
+   * pressed. Omit for the uncontrolled card (`defaultSelectedEpisode`, else
+   * none).
+   */
+  selectedEpisode?: string | null;
+  /** The excursion selected on first render when `selectedEpisode` is uncontrolled. */
+  defaultSelectedEpisode?: string | null;
+  /**
+   * Called with an excursion's key when the reader selects it, and with `null`
+   * when they clear it — the drill-through hook: open a `HighlightCard` (or
+   * your own detail view) for that window from here.
+   */
+  onSelectedEpisodeChange?: (key: string | null) => void;
+  /** `line` (default, may crop) or `area` (fills from zero). */
+  mark?: AnomalyMark;
+  /** Y-scale baseline for a `line` plot: `auto` (default) fits the readings and their range; `zero` includes zero. An `area` always includes zero. */
+  scale?: AnomalyScale;
+  /**
+   * The big number: `latest` (default) is the last reading with the expected
+   * range beneath it; `count` makes the number of excursions the headline;
+   * `worst` makes the largest deviation the headline; `none` leaves the plot
+   * to carry the panel. Stamped as `data-headline`.
+   */
+  headline?: AnomalyHeadline;
+  /** `absolute` (default) states a deviation in the measure's own units — percentage points for a `percent` format; `percent` states it relative to the bound it broke. The other form rides along in the tooltip. */
+  deltaMode?: AnomalyDeltaMode;
+  /**
+   * Which direction is good, and therefore what colour means. `none`
+   * (default) is the honest answer for a detector — an excursion is
+   * UNEXPECTED, not bad — and both directions take the attention hue. `up`
+   * (revenue) and `down` (latency, cost, errors) split the excursions into
+   * the diverging ends. Direction itself is always carried by the mark's
+   * shape and by words, never by hue.
+   */
+  goodDirection?: AnomalyGoodDirection;
+  /**
+   * Number format for the headline, the axis, the rows, the table and the
+   * tooltip — one grammar so nothing rounds two ways: `number[:digits]`,
+   * `integer`, `compact[:digits]`, `percent[:digits]`,
+   * `currency:CODE[:digits|compact]`. Default `compact`.
+   */
+  format?: string;
+  /** Custom formatter for values. Takes precedence over `format` everywhere a reading is rendered. */
+  formatValue?: (value: number) => string;
+  /** Number format for the detector's `score`. Default `number:1`. */
+  scoreFormat?: string;
+  /** Unit shown after a `latest` headline in the muted role (`ms`, `req/s`). Prefer `format="currency:…"` for money. */
+  unit?: ReactNode;
+  /** Plot height in pixels, axes included. Defaults per `size` (120 / 160 / 200), plus 24 when `axes` draws the x labels. */
+  plotHeight?: number;
+  /** Draw both axes with grid lines and labels. Default `true`; `false` shrinks the plot toward a sparkline — the table still carries every value. */
+  axes?: boolean;
+  /** Draw the expected range as a band. Default `true`; ignored when no period carries bounds. */
+  band?: boolean;
+  /** Draw the model's `expected` value as a dashed hairline inside the band. Default `true`; ignored when no period carries one. */
+  expected?: boolean;
+  /** The key row under the plot — the readings, the expected range, the expected value and the anomaly mark. Default `true`. */
+  keys?: boolean;
+  /**
+   * The excursion rows — the ranked list of episodes, each a real button that
+   * selects it. Default `true`. The description and the table twin name every
+   * excursion regardless.
+   */
+  episodes?: boolean;
+  /**
+   * How many excursion slots the rows reserve. The box is exactly this tall in
+   * every state, so a card in a grid never resizes when a window gains an
+   * excursion; when there are more, the last slot names the overflow. Default 3.
+   */
+  maxEpisodes?: number;
+  /** Period granularity of temporal `x` values for the axis, tooltips and the table. Inferred from the spacing when omitted. */
+  granularity?: ArcTimeGranularity;
+  /**
+   * The takeaway in a sentence, rendered beside the AI mark under the rows —
+   * the insight slot. Wrap values in `<strong>` to set them in bold. Omitted,
+   * the card generates one from the window's excursions; pass `null` or
+   * `false` to render none.
+   */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with readings already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: AnomalyCardStatus;
+  /** The consumer's filter is active — no readings then reads as no-match rather than empty, with a clear-filters action when `onClearFilters` is set. */
+  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, as a time-grammar granularity — `day`
+   * (default, `Sep 8, 2026`), `datetime`, `time`, `month`, `year` — or a
+   * formatter for a custom form. Applies to the as-of line and the
+   * description alike, in the card's `locale` and `timeZone`.
+   */
+  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 dense grids, `md` (default), `lg` for a hero panel. Scales type, padding and the default plot height. */
+  size?: AnomalyCardSize;
+  /** Heading level of the label for the document outline. Default 3 — panels usually sit under a page's h2. */
+  titleLevel?: 2 | 3 | 4 | 5 | 6;
+  /** BCP 47 locale for every number and date. Defaults to the runtime's. Thai products on the Gregorian calendar pass `th-TH-u-ca-gregory`. */
+  locale?: string;
+  /** IANA time zone for dates. Defaults to the runtime's — pass it for deterministic output and single-business-zone reporting. */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<AnomalyCardLabels>;
+  /** Replaces the generated accessible description of the whole card (the figure's `aria-describedby` text). */
+  description?: string;
+  /** Trailing header slot — a ghost `Button` or `Menu` for drill-through, export, or settings. */
+  action?: ReactNode;
+  /** Open the data popover on first render, anchored to the card. */
+  defaultTableOpen?: boolean;
+  /** Hide the header info button for the data popover. Only when another surface exposes the same values to keyboard and screen-reader users. */
+  hideTableToggle?: 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 plot spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * An anomaly panel for dashboards: one measure plotted against the range it
+ * was expected to stay inside, every reading that broke out marked with a
+ * direction-shaped flag, the excursions grouped into episodes and ranked as
+ * rows the reader can select, a verdict that says whether it is happening
+ * now, and every loading, empty, error and stale state — layout-stable, with
+ * a generated text equivalent and a data table in an info popover.
+ *
+ * Where `HighlightCard` explains ONE window it was handed, AnomalyCard is the
+ * surface that finds them: select an excursion here and hand its window on.
+ */
+declare const AnomalyCard: import("react").ForwardRefExoticComponent<AnomalyCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { AnomalyCard, AnomalyCardProps };