@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/ForecastCard/ForecastCard.chart.js

@@ -0,0 +1,416 @@
+import { AXIS_LABEL_LIMIT_EXPR } from "../../lib/vega/axisTicks.js";
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/ForecastCard/ForecastCard.chart.ts
+/** Every plotted period `{ x, y, lo, hi, k, c, n }`, measured then projected, with the anchor repeated. */
+const FORECAST_TABLE_DATASET = "table";
+/** The interval band `{ x, lo, hi }` — the anchor at zero width, then every projected period with bounds. */
+const FORECAST_INTERVAL_DATASET = "interval";
+/** One row per period, `{ x }` — the crosshair, filtered by the hover selection. */
+const FORECAST_PERIODS_DATASET = "periods";
+/** Zero or one row `{ start, end }` — the projected stretch: the wash, and the x axis's anchors. */
+const FORECAST_REGION_DATASET = "region";
+/** Zero or one row `{ x }` — the rule at the last measured period. */
+const FORECAST_BOUNDARY_DATASET = "boundary";
+/** Zero or one row `{ value }` — the target reference rule. */
+const FORECAST_REFERENCE_DATASET = "reference";
+/** Zero or one row `{ x, y, n, c }` — the landing dot and its direct label. */
+const FORECAST_LANDING_DATASET = "landing";
+/** The shared-x hover selection: projected onto `x`, so pointing anywhere in a column reads that period. */
+const FORECAST_HOVER_PARAM = "hover";
+/** Responsive x tick values, recomputed by Vega when the domain or the width changes. */
+const FORECAST_X_TICKS_PARAM = "forecast_x_ticks";
+/** The projected window's bounds, read from the `region` dataset — the x axis labels them. */
+const FORECAST_REGION_START_PARAM = "forecast_region_start";
+const FORECAST_REGION_END_PARAM = "forecast_region_end";
+const POINT_SIZE = 64;
+const PLOT_PADDING = 6;
+const LABEL_LIMIT_PX = 72;
+const LABEL_DODGE_PX = 14;
+const LABEL_DODGE_ROOM_PX = 20;
+const LABEL_INSET_PX = 4;
+const INTERVAL_OPACITY = .16;
+const REGION_OPACITY = .55;
+const ACTUAL_DASH = [1, 0];
+const FORECAST_DASH = [6, 4];
+const AREA_FILL_OPACITY = .12;
+const DISCRETE_DOMAIN_EXPR = `pluck(data('${FORECAST_PERIODS_DATASET}'), 'x')`;
+/**
+* Builds the plot: the measured readings as a solid path, the projection as the
+* same path dashed, the prediction interval as a band that opens from the last
+* reading, a wash and a rule marking where measurement stops, an optional
+* target rule, a dotted landing, and the documented shared-x hover (a
+* transparent `point` layer carrying a `nearest` selection projected onto `x`,
+* with a crosshair rule read from the period dataset).
+*
+* Gaps stay gaps — a `null` reading breaks the path rather than dropping it to
+* zero. An `area` keeps its zero baseline whatever `scale` says, because
+* proportional ink is not negotiable; a line may crop, and since both axes are
+* drawn the crop is always visible in the axis.
+*/
+function buildForecastPlotSpec(options, tokens) {
+	const { mark, scale, xType, height, axes, yTicks, interval, region, boundary, reference, landing, landingLabel, tooltip, xTitle, yTitle, kindTitle, plotFormat, timeFormat, axisTimeFormat } = options;
+	const zero = mark === "area" || 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 anchorsArg = region ? `, [${FORECAST_REGION_START_PARAM}, ${FORECAST_REGION_END_PARAM}]` : "";
+	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: FORECAST_X_TICKS_PARAM },
+		labelAngle: 0,
+		labelAlign: { expr: `arcAxisLabelAlign(datum.value, ${axisArgs}${anchorsArg})` },
+		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 colorField = {
+		field: "c",
+		type: "nominal",
+		scale: null,
+		legend: null
+	};
+	const dashField = {
+		field: "k",
+		type: "nominal",
+		scale: {
+			domain: ["actual", "forecast"],
+			range: [ACTUAL_DASH, FORECAST_DASH]
+		},
+		legend: 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: "k",
+			type: "nominal",
+			title: kindTitle
+		},
+		{
+			field: "y",
+			type: "quantitative",
+			title: yTitle,
+			format: plotFormat,
+			formatType: "arcNumber"
+		}
+	];
+	const layers = [];
+	if (region) layers.push({
+		data: { name: FORECAST_REGION_DATASET },
+		mark: {
+			type: "rect",
+			fill: tokens.muted,
+			opacity: REGION_OPACITY,
+			aria: false
+		},
+		encoding: {
+			x: {
+				...xField,
+				field: "start",
+				axis: xAxis,
+				...discreteX ? { bandPosition: 0 } : {}
+			},
+			x2: {
+				field: "end",
+				...discreteX ? { bandPosition: 1 } : {}
+			}
+		}
+	});
+	if (interval) layers.push({
+		data: { name: FORECAST_INTERVAL_DATASET },
+		mark: {
+			type: "area",
+			line: false,
+			interpolate: "linear",
+			fillOpacity: INTERVAL_OPACITY,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: {
+				...yField,
+				field: "lo"
+			},
+			y2: { field: "hi" },
+			fill: { value: tokens.emphasis }
+		}
+	});
+	if (mark === "area") layers.push({
+		mark: {
+			type: "area",
+			line: false,
+			interpolate: "linear",
+			invalid: "break-paths-show-domains",
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			fill: colorField,
+			fillOpacity: {
+				field: "k",
+				type: "nominal",
+				sort: ["actual", "forecast"],
+				scale: {
+					domain: ["actual", "forecast"],
+					range: [AREA_FILL_OPACITY, 0]
+				},
+				legend: null
+			}
+		}
+	});
+	layers.push({
+		mark: {
+			type: "line",
+			strokeWidth: 2,
+			strokeCap: "round",
+			strokeJoin: "round",
+			interpolate: "linear",
+			invalid: "break-paths-show-domains"
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			stroke: colorField,
+			strokeDash: dashField
+		}
+	});
+	if (boundary) layers.push({
+		data: { name: FORECAST_BOUNDARY_DATASET },
+		mark: {
+			type: "rule",
+			stroke: tokens.axis,
+			strokeWidth: 1,
+			strokeDash: [4, 3],
+			opacity: .9,
+			aria: false
+		},
+		encoding: { x: {
+			...xField,
+			axis: xAxis
+		} }
+	});
+	if (reference) layers.push({
+		data: { name: FORECAST_REFERENCE_DATASET },
+		mark: {
+			type: "rule",
+			stroke: tokens.reference,
+			strokeWidth: 1.5,
+			strokeDash: [0, 4],
+			strokeCap: "round",
+			opacity: .9,
+			aria: false
+		},
+		encoding: {
+			y: {
+				...yField,
+				field: "value"
+			},
+			...tooltip ? { tooltip: [{
+				field: "value",
+				type: "quantitative",
+				title: options.targetTitle ?? "Target",
+				format: plotFormat,
+				formatType: "arcNumber"
+			}] } : {}
+		}
+	});
+	if (landing) {
+		layers.push({
+			data: { name: FORECAST_LANDING_DATASET },
+			mark: {
+				type: "point",
+				filled: false,
+				size: POINT_SIZE,
+				strokeWidth: 2,
+				fill: tokens.background,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				stroke: colorField
+			}
+		});
+		if (landingLabel) layers.push({
+			data: { name: FORECAST_LANDING_DATASET },
+			mark: {
+				type: "text",
+				align: "right",
+				baseline: "middle",
+				dx: LABEL_INSET_PX,
+				dy: { expr: `scale('y', datum.y) < height / 2 ? (scale('y', datum.y) >= ${LABEL_DODGE_ROOM_PX} ? -${LABEL_DODGE_PX} : ${LABEL_DODGE_PX}) : (height - scale('y', datum.y) >= ${LABEL_DODGE_ROOM_PX} ? ${LABEL_DODGE_PX} : -${LABEL_DODGE_PX})` },
+				fontSize: 11,
+				fontWeight: 500,
+				limit: { expr: `max(${LABEL_LIMIT_PX}, width / 3)` },
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				text: {
+					field: "n",
+					type: "nominal"
+				},
+				color: colorField
+			}
+		});
+	}
+	if (tooltip) {
+		layers.push({
+			params: [{
+				name: FORECAST_HOVER_PARAM,
+				select: {
+					type: "point",
+					on: "pointermove",
+					nearest: true,
+					clear: "pointerout",
+					encodings: ["x"]
+				}
+			}],
+			mark: {
+				type: "point",
+				filled: true,
+				size: POINT_SIZE,
+				stroke: tokens.background,
+				strokeWidth: 1.5,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				fill: colorField,
+				opacity: {
+					condition: {
+						param: FORECAST_HOVER_PARAM,
+						empty: false,
+						value: 1
+					},
+					value: 0
+				},
+				tooltip: tooltipChannel
+			}
+		});
+		layers.push({
+			data: { name: FORECAST_PERIODS_DATASET },
+			mark: {
+				type: "rule",
+				stroke: tokens.axis,
+				strokeWidth: 1,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				opacity: {
+					condition: {
+						param: FORECAST_HOVER_PARAM,
+						empty: false,
+						value: .6
+					},
+					value: 0
+				}
+			}
+		});
+	}
+	const params = [];
+	if (region) params.push({
+		name: FORECAST_REGION_START_PARAM,
+		expr: `length(data('${FORECAST_REGION_DATASET}')) ? data('${FORECAST_REGION_DATASET}')[0].start : null`
+	}, {
+		name: FORECAST_REGION_END_PARAM,
+		expr: `length(data('${FORECAST_REGION_DATASET}')) ? data('${FORECAST_REGION_DATASET}')[0].end : null`
+	});
+	if (axes) params.push({
+		name: FORECAST_X_TICKS_PARAM,
+		expr: `arcAxisTicks(${axisArgs}${anchorsArg})`
+	});
+	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: FORECAST_TABLE_DATASET },
+		...params.length > 0 ? { params } : {},
+		layer: layers,
+		config: arcVegaConfig(tokens, {
+			locale: options.locale,
+			timeZone: options.timeZone
+		})
+	};
+}
+//#endregion
+export { FORECAST_BOUNDARY_DATASET, FORECAST_HOVER_PARAM, FORECAST_INTERVAL_DATASET, FORECAST_LANDING_DATASET, FORECAST_PERIODS_DATASET, FORECAST_REFERENCE_DATASET, FORECAST_REGION_DATASET, FORECAST_REGION_END_PARAM, FORECAST_REGION_START_PARAM, FORECAST_TABLE_DATASET, FORECAST_X_TICKS_PARAM, buildForecastPlotSpec };

package/dist/components/ForecastCard/ForecastCard.d.ts

@@ -0,0 +1,148 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ForecastCardLabels, ForecastCardSize, ForecastCardStatus, ForecastDeltaMode, ForecastGoodDirection, ForecastHeadline, ForecastMark, ForecastPoint, ForecastScale } from "./ForecastCard.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/ForecastCard/ForecastCard.d.ts
+interface ForecastCardProps 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 measure, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /**
+   * The measured readings, oldest first: `{ x, y }` — `x` a `Date`, ISO string,
+   * number or period label; `y` the value or `null` for a gap (drawn as a gap,
+   * never as zero). Pass `[]` while loading to reserve the plot's height.
+   */
+  actual: readonly ForecastPoint[];
+  /**
+   * The projection, in the same `x` type and continuing past the last measured
+   * period: `{ x, y, lower?, upper? }`. `lower`/`upper` are the prediction
+   * interval at that period — pass both or neither; the band opens from the
+   * last reading, so the fan starts where the data stops. A projected period
+   * that repeats a measured one is dropped: a forecast cannot overwrite a
+   * reading. Omit for a card that has history but nothing projected yet — it
+   * plots the history and says so.
+   */
+  forecast?: readonly ForecastPoint[];
+  /**
+   * The interval's confidence level as a ratio (`0.9` → `90% interval`), named
+   * in the headline caption, the key row, the insight and the description. A
+   * band with no level is not a claim a reader can act on, so pass it whenever
+   * the transport knows it.
+   */
+  level?: number | null;
+  /** A goal for the measure. Draws a dotted reference rule and turns on the verdict chip. */
+  target?: number | null;
+  /**
+   * The big number: `landing` (default) is where the forecast ends, with its
+   * interval beneath and the projected change in a polarity badge; `latest` is
+   * the last measured reading; `change` makes the projected move itself the
+   * headline; `none` leaves the plot to carry the panel. Stamped as
+   * `data-headline`.
+   */
+  headline?: ForecastHeadline;
+  /** `percent` (default) is relative change; `absolute` is the difference in the value's units — percentage points for a `percent` format. */
+  deltaMode?: ForecastDeltaMode;
+  /**
+   * Which direction is good. Drives the change badge's polarity AND what
+   * "reaching the target" means: `up` (revenue), `down` (churn, cost, latency)
+   * or `none` (headcount — the change stays neutral and the card gives no
+   * verdict, because reaching is undefined without a direction). Default `up`.
+   */
+  goodDirection?: ForecastGoodDirection;
+  /** `line` (default, may crop) or `area`, which fills the MEASURED half from zero — the projected half is never filled, because its magnitude is not measured. */
+  mark?: ForecastMark;
+  /** Y-scale baseline for a `line` plot: `auto` (default) fits the data range and reads for shape; `zero` includes zero. An `area` always includes zero. */
+  scale?: ForecastScale;
+  /**
+   * Number format for the headline, the interval, the axis, the key row, 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;
+  /** Unit shown after the 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 key row under the plot — actual, forecast, interval, target. Default `true`; the tooltip, table and description name every mark regardless. */
+  keys?: boolean;
+  /** Wash the projected stretch of the axis and anchor the x labels on its bounds. Default `true`. */
+  region?: boolean;
+  /** Hang the landing's value beside its dot, in a right-hand gutter, so the answer needs no round trip to the axis. Default `false`. */
+  labelLanding?: boolean;
+  /** 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 plot —
+   * the insight slot. Wrap values in `<strong>` to set them in bold. Omitted,
+   * the card generates one from the projection, its interval and the target;
+   * 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?: ForecastCardStatus;
+  /** 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?: ForecastCardSize;
+  /** 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<ForecastCardLabels>;
+  /** 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;
+}
+/**
+ * A forecast panel for dashboards: the measured readings as a solid path, the
+ * projection as the same path dashed, its prediction interval as a band opening
+ * from the last reading, the boundary between measurement and projection marked
+ * three ways, an optional target with the verdict only uncertainty can give
+ * (likely / too close to call / unlikely), the landing as the headline, and
+ * every loading, empty, error and stale state — layout-stable, with a generated
+ * text equivalent and a period-by-period table in an info popover.
+ *
+ * Where `TrendCard` answers "what shape is this metric in", ForecastCard
+ * answers "where is it heading, how sure are we, and does that clear the
+ * target".
+ */
+declare const ForecastCard: import("react").ForwardRefExoticComponent<ForecastCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { ForecastCard, ForecastCardProps };