@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/TargetCard/TargetCard.chart.js

@@ -0,0 +1,273 @@
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/TargetCard/TargetCard.chart.ts
+/** One row `{ value, zero, ratio, tone }` — the reading, drawn as the bar from zero. */
+const TARGET_ACTUAL_DATASET = "table";
+/** One row `{ min, max, target }` — the x domain (always spanning zero, the target and every marker) and the target's position for the label layout. */
+const TARGET_BOUNDS_DATASET = "bounds";
+/** One or two rows `{ value, ratio, role }` with `role` `target` or `pace` — the ticks and their words. */
+const TARGET_MARKERS_DATASET = "markers";
+/** Zero or one row `{ from, to, ratio, tone }` — the projected extension beyond the reading. */
+const TARGET_PROJECTION_DATASET = "projection";
+/** The x domain's ends, read from the `bounds` dataset. */
+const TARGET_MIN_PARAM = "target_x_min";
+const TARGET_MAX_PARAM = "target_x_max";
+/** The target's value, read from the `bounds` dataset — the pace word yields to the target word when the two would collide. */
+const TARGET_MARKER_PARAM = "target_marker";
+const TARGET_LABEL_ROW_PX = 16;
+const PACE_OVERSHOOT_PX = 2;
+const TARGET_OVERSHOOT_PX = 4;
+const LABEL_EDGE_PX = 30;
+const LABEL_GAP_PX = 48;
+const PROJECTION_OPACITY = .25;
+/**
+* A fill that follows the reading's standing through the row's `tone`: the
+* positive hue once the target is met, the negative hue once it is missed,
+* the emphasis hue while it is open — three token values in the spec, so the
+* spec stays structural while the data decides.
+*/
+function toneColor(tokens) {
+	return {
+		condition: [{
+			test: "datum.tone === 'positive'",
+			value: tokens.divergingPositive
+		}, {
+			test: "datum.tone === 'negative'",
+			value: tokens.divergingNegative
+		}],
+		value: tokens.emphasis
+	};
+}
+/**
+* Builds the bullet graph: a muted track across the whole domain, the reading
+* as a bar from zero (length on a shared zero-based scale — Cleveland &
+* McGill's channel for magnitude, Wilke's proportional ink), a lighter
+* extension to the projection, a thin gray tick where the plan expects the
+* reading to be by now and a heavier tick at the target, each with its word
+* underneath — the pace word yielding when the two would collide — and a
+* tooltip on every mark. The domain is explicit (`bounds`), so a reading past
+* its target extends the scale rather than clipping, and a negative reading
+* grows the track to the left of zero.
+*/
+function buildTargetBulletSpec(options, tokens) {
+	const { barHeight, height, labels, tooltip, targetLabel, paceLabel, valueFormat, valueTitle, targetTitle, paceTitle, projectionTitle, locale } = options;
+	const thickness = Math.min(24, barHeight);
+	const rowHeight = labels ? height - 16 : height;
+	const barTop = Math.round((rowHeight - thickness) / 2);
+	const barBottom = barTop + thickness;
+	const labelY = rowHeight + 2;
+	const xScale = {
+		domain: { expr: `[${TARGET_MIN_PARAM}, ${TARGET_MAX_PARAM}]` },
+		nice: false
+	};
+	const xField = {
+		field: "value",
+		type: "quantitative",
+		axis: null,
+		scale: xScale
+	};
+	const band = {
+		y: { value: barTop },
+		y2: { value: barBottom }
+	};
+	const valueTooltip = (title) => tooltip ? { tooltip: [{
+		field: "value",
+		type: "quantitative",
+		title,
+		format: valueFormat,
+		formatType: "arcNumber"
+	}] } : {};
+	const layers = [
+		{
+			data: { name: TARGET_BOUNDS_DATASET },
+			mark: {
+				type: "rect",
+				fill: tokens.muted,
+				cornerRadius: 2,
+				aria: false
+			},
+			encoding: {
+				x: {
+					field: "min",
+					type: "quantitative",
+					axis: null,
+					scale: xScale
+				},
+				x2: { field: "max" },
+				...band
+			}
+		},
+		{
+			data: { name: TARGET_PROJECTION_DATASET },
+			mark: {
+				type: "bar",
+				orient: "horizontal",
+				cornerRadiusEnd: 2,
+				fillOpacity: PROJECTION_OPACITY,
+				aria: false
+			},
+			encoding: {
+				x: {
+					field: "from",
+					type: "quantitative",
+					axis: null,
+					scale: xScale
+				},
+				x2: { field: "to" },
+				...band,
+				fill: toneColor(tokens),
+				...tooltip ? { tooltip: [{
+					field: "to",
+					type: "quantitative",
+					title: projectionTitle,
+					format: valueFormat,
+					formatType: "arcNumber"
+				}] } : {}
+			}
+		},
+		{
+			data: { name: TARGET_ACTUAL_DATASET },
+			mark: {
+				type: "bar",
+				orient: "horizontal",
+				cornerRadiusEnd: 2,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				x2: { field: "zero" },
+				...band,
+				fill: toneColor(tokens),
+				...valueTooltip(valueTitle)
+			}
+		},
+		{
+			data: { name: TARGET_MARKERS_DATASET },
+			transform: [{ filter: "datum.role === 'pace'" }],
+			mark: {
+				type: "rule",
+				stroke: tokens.reference,
+				strokeWidth: 1.5,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: { value: barTop - PACE_OVERSHOOT_PX },
+				y2: { value: barBottom + PACE_OVERSHOOT_PX },
+				...valueTooltip(paceTitle)
+			}
+		},
+		{
+			data: { name: TARGET_MARKERS_DATASET },
+			transform: [{ filter: "datum.role === 'target'" }],
+			mark: {
+				type: "rule",
+				stroke: tokens.foreground,
+				strokeWidth: 2,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: { value: barTop - TARGET_OVERSHOOT_PX },
+				y2: { value: barBottom + TARGET_OVERSHOOT_PX },
+				...valueTooltip(targetTitle)
+			}
+		}
+	];
+	if (tooltip) layers.push({
+		data: { name: TARGET_MARKERS_DATASET },
+		mark: {
+			type: "rule",
+			strokeWidth: 12,
+			opacity: 0,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: { value: 0 },
+			y2: { value: rowHeight },
+			tooltip: [{
+				field: "label",
+				type: "nominal",
+				title: " "
+			}, {
+				field: "value",
+				type: "quantitative",
+				title: valueTitle,
+				format: valueFormat,
+				formatType: "arcNumber"
+			}]
+		},
+		transform: [{
+			calculate: `datum.role === 'target' ? ${JSON.stringify(targetTitle)} : ${JSON.stringify(paceTitle)}`,
+			as: "label"
+		}]
+	});
+	if (labels) layers.push({
+		data: { name: TARGET_MARKERS_DATASET },
+		transform: [{
+			calculate: `datum.role === 'target' ? ${JSON.stringify(targetLabel)} : ${JSON.stringify(paceLabel)}`,
+			as: "label"
+		}],
+		mark: {
+			type: "text",
+			baseline: "top",
+			fontSize: 11,
+			font: tokens.fontSans,
+			fill: tokens.axisLabel,
+			align: { expr: `scale('x', datum.value) > width - ${LABEL_EDGE_PX} ? 'right' : scale('x', datum.value) < ${LABEL_EDGE_PX} ? 'left' : 'center'` },
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: { value: labelY },
+			text: {
+				field: "label",
+				type: "nominal"
+			},
+			opacity: {
+				condition: {
+					test: `datum.role === 'target' || abs(scale('x', datum.value) - scale('x', ${TARGET_MARKER_PARAM})) >= ${LABEL_GAP_PX}`,
+					value: 1
+				},
+				value: 0
+			}
+		}
+	});
+	const bounds = (field, fallback) => `length(data('${TARGET_BOUNDS_DATASET}')) ? data('${TARGET_BOUNDS_DATASET}')[0].${field} : ${fallback}`;
+	const params = [
+		{
+			name: TARGET_MIN_PARAM,
+			expr: bounds("min", 0)
+		},
+		{
+			name: TARGET_MAX_PARAM,
+			expr: bounds("max", 1)
+		},
+		{
+			name: TARGET_MARKER_PARAM,
+			expr: bounds("target", 1)
+		}
+	];
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 240,
+		height,
+		autosize: {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: {
+			left: 1,
+			right: 1,
+			top: 0,
+			bottom: 0
+		},
+		background: "transparent",
+		data: { name: TARGET_ACTUAL_DATASET },
+		params,
+		layer: layers,
+		config: arcVegaConfig(tokens, { locale })
+	};
+}
+//#endregion
+export { TARGET_ACTUAL_DATASET, TARGET_BOUNDS_DATASET, TARGET_LABEL_ROW_PX, TARGET_MARKERS_DATASET, TARGET_MARKER_PARAM, TARGET_MAX_PARAM, TARGET_MIN_PARAM, TARGET_PROJECTION_DATASET, buildTargetBulletSpec };

package/dist/components/TargetCard/TargetCard.d.ts

@@ -0,0 +1,143 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { TargetCardLabels, TargetCardSize, TargetCardStatus, TargetDeltaMode, TargetGoodDirection, TargetHeadline, TargetPeriod } from "./TargetCard.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/TargetCard/TargetCard.d.ts
+interface TargetCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The goal's name — the tile'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 goal, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /** The reading so far — what has been reached, spent or counted. `null`/`undefined` renders the empty (or no-match) state. */
+  value?: number | null;
+  /**
+   * The goal. Draws the target tick and gives the reading its attainment;
+   * pass `null` while unknown to keep the frame, and the card says no target
+   * is set (`data-insufficient`) when a reading arrives without one. Zero is
+   * no target — attainment has no ratio against it.
+   */
+  target?: number | null;
+  /**
+   * Number format for the reading, the target, the badge, the plot, 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` (`3.8M`).
+   */
+  format?: string;
+  /** Custom formatter for values. Takes precedence over `format` everywhere a value is rendered. */
+  formatValue?: (value: number) => string;
+  /** Unit shown after the reading in the muted role (`signups`, `ms`). Prefer `format="currency:…"` for money. */
+  unit?: ReactNode;
+  /**
+   * How the target is reached: `up` (default) — reach at least the target: a
+   * quota, a goal; `down` — stay at or under it: a budget, an error cap. It
+   * decides the badge's polarity, the pace words (`ahead of pace` / `under
+   * pace`) and when the target counts as met or missed.
+   */
+  goodDirection?: TargetGoodDirection;
+  /**
+   * What the big number is: `attainment` (default) — the percentage of the
+   * target reached, with the reading and the target on the line below; or
+   * `value` — the reading itself, with the attainment below. Stamped as
+   * `data-headline`.
+   */
+  headline?: TargetHeadline;
+  /**
+   * The goal period as `{ start, end, label? }`. Date-only ISO strings are
+   * inclusive calendar dates in the card's `timeZone` (`"2026-09-01"` –
+   * `"2026-09-30"` is the whole of September); `Date`s and date-times are
+   * exact instants. With `updatedAt` as "now" it gives the elapsed share, the
+   * pace marker (`target × elapsed`), the run-rate projection and the
+   * verdict; `label` names it on the period line. Pass stable values (ISO
+   * strings or memoized Dates): the period is re-resolved when they change.
+   */
+  period?: TargetPeriod;
+  /**
+   * What the plan expects to be reached by `updatedAt`, when the plan is not a
+   * straight line — a seasonal curve, working days, a phased rollout. Replaces
+   * the linear `target × elapsed` as the pace marker and the badge's
+   * reference; `null` disables pace even with a `period`.
+   */
+  expected?: number | null;
+  /**
+   * The product's own forecast of where the reading lands at the period's end.
+   * Replaces the linear run rate (`value / elapsed`) as the projected extension
+   * and the projection line; `null` hides the projection even with a `period`.
+   */
+  projected?: number | null;
+  /**
+   * How far behind the plan's expectation, as a share of the target, still
+   * counts as `at-risk` rather than `off-track`. Default `0.05` — five points
+   * of the target.
+   */
+  tolerance?: number;
+  /** `percent` (default) is the change relative to the reference — the plan's expectation, or the target; `absolute` is the difference in the value's units (percentage points for a `percent` format). */
+  deltaMode?: TargetDeltaMode;
+  /** Write the marker words (`Target`, `Pace`) under their ticks. Default `true`; `false` for a very narrow tile — the tooltip, table and description still name them. */
+  markerLabels?: boolean;
+  /** The takeaway in a sentence, rendered beside the AI mark under the plot. Wrap values in `<strong>` to set them in bold. */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with data already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: TargetCardStatus;
+  /** The consumer's filter is active — a missing reading 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 (the date by
+   * default — see `updatedAtFormat`), included in the description, and the
+   * "now" pacing is measured at — without it a `period` yields no pace, so
+   * baselines never depend on the wall clock.
+   */
+  updatedAt?: Date | string | number;
+  /**
+   * How `updatedAt` is written, as a time-grammar granularity — `day`
+   * (default, `Sep 19, 2026`), `datetime` (`Sep 19, 2026, 04:30 PM`), `time`
+   * (`04:30 PM`), `month` (`Sep 2026`), `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 goal. Scales type, padding, the bar thickness and the plot height. */
+  size?: TargetCardSize;
+  /** Heading level of the label for the document outline. Default 3 — tiles 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 the period's calendar dates and the as-of date. 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<TargetCardLabels>;
+  /** 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 details popover on first render, anchored to the card. */
+  defaultTableOpen?: boolean;
+  /** Hide the header info button for the details popover. Only when another surface exposes the same figures to keyboard and screen-reader users. */
+  hideTableToggle?: boolean;
+  /** Called with vega-embed's result once the bullet graph mounts — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the bullet graph spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A goal-tracking tile for dashboard grids: how much of a target is reached,
+ * whether the reading is ahead of or behind the plan at this point in the
+ * period, where the run rate lands, and the verdict — on a Few-style bullet
+ * graph (the reading as a bar from zero, a pace tick and a target tick, the
+ * projection as a lighter extension) with every loading, empty, error and
+ * stale state — layout-stable, with a generated text equivalent and a details
+ * table in an info popover.
+ */
+declare const TargetCard: import("react").ForwardRefExoticComponent<TargetCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { TargetCard, TargetCardProps };