@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,64 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { ProfileMark } from "./ProfileCard.model.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/ProfileCard/ProfileCard.chart.d.ts
+/** Long-form readings: one row per series × metric with a finite value (`ProfileCell`). */
+declare const PROFILE_CELLS_DATASET = "cells";
+/** One row per metric — `{ i, a, m, ml }` — the axis ring, the spokes, the band domain and the labels. */
+declare const PROFILE_AXES_DATASET = "axes";
+/** The web: one row per metric × ring level — `{ i, a, r }`. Empty for the non-radar marks. */
+declare const PROFILE_RINGS_DATASET = "rings";
+/** The hovered series' point selection. */
+declare const PROFILE_HOVER_PARAM = "hover";
+/** Which geometry the mark draws in. `radar` is cartesian-from-polar; the rest are ordinary plots. */
+declare function profileNeedsRings(mark: ProfileMark): boolean;
+interface ProfilePlotSpecOptions {
+  /** Which form the plot draws. */
+  mark: ProfileMark;
+  /** Plot height in pixels. The width rides the View API. */
+  height: number;
+  /**
+   * Which field the value channel reads. `raw` when every metric already
+   * shares one scale (`normalize="shared"`), so the axis speaks real units;
+   * `n` when each metric was scaled to its own range and only the 0–1 form
+   * is comparable. A radar and a parallel plot always read `n`.
+   */
+  valueField: "raw" | "n";
+  /** Draw the web rings and the spokes (radar only). */
+  rings: boolean;
+  /** Fill each radar polygon faintly. Off by default — a filled area invites an area comparison the geometry cannot support. */
+  fill: boolean;
+  /** Draw a dot on each vertex, so a reading is a mark and not only a bend in a path. */
+  vertices: boolean;
+  /** Wire the hover selection and the tooltip channel. */
+  tooltip: boolean;
+  /** Dim every series but the focused one. Only meaningful while a focus exists. */
+  emphasize: boolean;
+  /** Name the metrics on the plot. `false` leaves the axis to the popover table (a tile too small for labels). */
+  axisLabels: boolean;
+  /** Tooltip titles. */
+  itemTitle: string;
+  metricTitle: string;
+  valueTitle: string;
+  /** `arcNumber` grammar for the value axis and the tooltip. */
+  valueFormat: string;
+  locale?: string;
+}
+/**
+ * Builds the plot.
+ *
+ * `radar` draws a web of rings and spokes, then one closed polygon per item
+ * over the metric axes — the shape IS the reading, so the card fixes the axis
+ * order, keeps the fill off by default and never lets a rescaled axis go
+ * unannounced. `grouped` draws one bar per item inside each metric's band,
+ * which is the accurate form whenever values rather than shapes are being
+ * compared. `parallel` draws one path per item across parallel axes, which
+ * carries more items than a radar can without turning into a knot.
+ *
+ * Colour is identity here — several items on one plot — so it comes baked
+ * into every pushed row (`c`) with `scale: null`: hiding a series through the
+ * legend can then never repaint the survivors.
+ */
+declare function buildProfilePlotSpec(options: ProfilePlotSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { PROFILE_AXES_DATASET, PROFILE_CELLS_DATASET, PROFILE_HOVER_PARAM, PROFILE_RINGS_DATASET, ProfilePlotSpecOptions, buildProfilePlotSpec, profileNeedsRings };

package/dist/components/ProfileCard/ProfileCard.chart.js

@@ -0,0 +1,427 @@
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/ProfileCard/ProfileCard.chart.ts
+/** Long-form readings: one row per series × metric with a finite value (`ProfileCell`). */
+const PROFILE_CELLS_DATASET = "cells";
+/** One row per metric — `{ i, a, m, ml }` — the axis ring, the spokes, the band domain and the labels. */
+const PROFILE_AXES_DATASET = "axes";
+/** The web: one row per metric × ring level — `{ i, a, r }`. Empty for the non-radar marks. */
+const PROFILE_RINGS_DATASET = "rings";
+/** The hovered series' point selection. */
+const PROFILE_HOVER_PARAM = "hover";
+const PATH_WIDTH = 2;
+const VERTEX_SIZE = 48;
+const RESTING_OPACITY = .55;
+const FILL_OPACITY = .12;
+const LABEL_RADIUS = 1.08;
+const RADAR_DOMAIN = 1.72;
+const LABEL_LIMIT_EXPR = `max(24, width / 2 * ${(.6399999999999999 / RADAR_DOMAIN).toFixed(4)} - 2)`;
+const MAX_GROUP_BAR = 18;
+const PARALLEL_PADDING = .14;
+/** Which geometry the mark draws in. `radar` is cartesian-from-polar; the rest are ordinary plots. */
+function profileNeedsRings(mark) {
+	return mark === "radar";
+}
+/** The band domain and the axis-label lookup both read the axes dataset, so a metric nobody reported keeps its place. */
+const AXIS_DOMAIN_EXPR = `pluck(data('${PROFILE_AXES_DATASET}'), 'm')`;
+const AXIS_INDEX_DOMAIN_EXPR = `pluck(data('${PROFILE_AXES_DATASET}'), 'i')`;
+const AXIS_LABEL_EXPR = `((data('${PROFILE_AXES_DATASET}')[indexof(pluck(data('${PROFILE_AXES_DATASET}'), 'm'), datum.value)] || {}).ml)`;
+const AXIS_LABEL_BY_INDEX_EXPR = `((data('${PROFILE_AXES_DATASET}')[indexof(pluck(data('${PROFILE_AXES_DATASET}'), 'i'), datum.value)] || {}).ml)`;
+const RADAR_X = (radius) => `sin(datum.a) * ${radius}`;
+const RADAR_Y = (radius) => `cos(datum.a) * ${radius}`;
+/**
+* Builds the plot.
+*
+* `radar` draws a web of rings and spokes, then one closed polygon per item
+* over the metric axes — the shape IS the reading, so the card fixes the axis
+* order, keeps the fill off by default and never lets a rescaled axis go
+* unannounced. `grouped` draws one bar per item inside each metric's band,
+* which is the accurate form whenever values rather than shapes are being
+* compared. `parallel` draws one path per item across parallel axes, which
+* carries more items than a radar can without turning into a knot.
+*
+* Colour is identity here — several items on one plot — so it comes baked
+* into every pushed row (`c`) with `scale: null`: hiding a series through the
+* legend can then never repaint the survivors.
+*/
+function buildProfilePlotSpec(options, tokens) {
+	const { mark, height, valueField, rings, fill, vertices, tooltip, emphasize, axisLabels, itemTitle, metricTitle, valueTitle, valueFormat, locale } = options;
+	const colorChannel = {
+		field: "c",
+		type: "nominal",
+		scale: null,
+		legend: null
+	};
+	const seriesDetail = {
+		field: "s",
+		type: "nominal"
+	};
+	const tooltipChannel = [
+		{
+			field: "sl",
+			type: "nominal",
+			title: itemTitle
+		},
+		{
+			field: "ml",
+			type: "nominal",
+			title: metricTitle
+		},
+		{
+			field: "raw",
+			type: "quantitative",
+			title: valueTitle,
+			format: valueFormat,
+			formatType: "arcNumber"
+		}
+	];
+	const solid = { value: 1 };
+	const hovered = {
+		param: PROFILE_HOVER_PARAM,
+		...emphasize ? { empty: false } : {},
+		...solid
+	};
+	const focused = {
+		test: "datum.f",
+		...solid
+	};
+	const opacityChannel = tooltip && emphasize ? { opacity: {
+		condition: [hovered, focused],
+		value: RESTING_OPACITY
+	} } : tooltip ? { opacity: {
+		condition: hovered,
+		value: RESTING_OPACITY
+	} } : emphasize ? { opacity: {
+		condition: focused,
+		value: RESTING_OPACITY
+	} } : {};
+	const hoverParam = tooltip ? { params: [{
+		name: PROFILE_HOVER_PARAM,
+		select: {
+			type: "point",
+			on: "pointerover",
+			clear: "pointerout",
+			fields: ["s"]
+		}
+	}] } : {};
+	const layers = [];
+	if (mark === "radar") {
+		const cartesian = (radius) => [{
+			calculate: RADAR_X(radius),
+			as: "px"
+		}, {
+			calculate: RADAR_Y(radius),
+			as: "py"
+		}];
+		const px = {
+			field: "px",
+			type: "quantitative",
+			axis: null,
+			scale: {
+				domain: [-1.72, RADAR_DOMAIN],
+				nice: false
+			},
+			title: null
+		};
+		const py = {
+			field: "py",
+			type: "quantitative",
+			axis: null,
+			scale: {
+				domain: [-1.72, RADAR_DOMAIN],
+				nice: false
+			},
+			title: null
+		};
+		if (rings) {
+			layers.push({
+				data: { name: PROFILE_RINGS_DATASET },
+				transform: cartesian("datum.r"),
+				mark: {
+					type: "line",
+					interpolate: "linear-closed",
+					stroke: tokens.grid,
+					strokeWidth: 1,
+					aria: false
+				},
+				encoding: {
+					x: px,
+					y: py,
+					detail: {
+						field: "r",
+						type: "nominal"
+					},
+					order: {
+						field: "i",
+						type: "quantitative"
+					}
+				}
+			});
+			layers.push({
+				data: { name: PROFILE_AXES_DATASET },
+				transform: cartesian("1"),
+				mark: {
+					type: "rule",
+					stroke: tokens.grid,
+					strokeWidth: 1,
+					aria: false
+				},
+				encoding: {
+					x: px,
+					y: py,
+					x2: { datum: 0 },
+					y2: { datum: 0 }
+				}
+			});
+		}
+		layers.push({
+			transform: cartesian("datum.n"),
+			mark: {
+				type: "line",
+				interpolate: "linear-closed",
+				strokeWidth: PATH_WIDTH,
+				strokeJoin: "round",
+				...fill ? {
+					filled: true,
+					fillOpacity: FILL_OPACITY
+				} : { fill: null },
+				aria: false
+			},
+			encoding: {
+				x: px,
+				y: py,
+				stroke: colorChannel,
+				...fill ? { fill: colorChannel } : {},
+				detail: seriesDetail,
+				order: {
+					field: "i",
+					type: "quantitative"
+				},
+				...opacityChannel
+			}
+		});
+		if (vertices) layers.push({
+			...hoverParam,
+			transform: cartesian("datum.n"),
+			mark: {
+				type: "point",
+				filled: true,
+				size: VERTEX_SIZE,
+				aria: false
+			},
+			encoding: {
+				x: px,
+				y: py,
+				fill: colorChannel,
+				...opacityChannel,
+				...tooltip ? { tooltip: tooltipChannel } : {}
+			}
+		});
+		if (axisLabels) layers.push({
+			data: { name: PROFILE_AXES_DATASET },
+			transform: cartesian(String(LABEL_RADIUS)),
+			mark: {
+				type: "text",
+				fontSize: 10,
+				baseline: "middle",
+				fill: tokens.axisLabel,
+				limit: { expr: LABEL_LIMIT_EXPR },
+				align: { expr: "abs(datum.px) < 0.08 ? 'center' : (datum.px > 0 ? 'left' : 'right')" },
+				aria: false
+			},
+			encoding: {
+				x: px,
+				y: py,
+				text: {
+					field: "ml",
+					type: "nominal"
+				}
+			}
+		});
+	}
+	if (mark === "grouped") {
+		const catAxis = (owner) => !axisLabels ? { axis: null } : owner ? { axis: {
+			title: null,
+			labelExpr: AXIS_LABEL_EXPR,
+			labelLimit: 96,
+			domain: false,
+			ticks: false,
+			grid: false,
+			aria: false
+		} } : {};
+		const band = (owner) => ({
+			field: "m",
+			type: "nominal",
+			sort: null,
+			scale: {
+				type: "band",
+				domain: { expr: AXIS_DOMAIN_EXPR },
+				paddingInner: .3,
+				paddingOuter: .15
+			},
+			...catAxis(owner)
+		});
+		layers.push({
+			data: { name: PROFILE_AXES_DATASET },
+			mark: {
+				type: "rule",
+				stroke: tokens.grid,
+				strokeWidth: 1,
+				aria: false
+			},
+			encoding: { y: band(false) }
+		});
+		layers.push({
+			...hoverParam,
+			mark: {
+				type: "bar",
+				cornerRadiusEnd: 2,
+				aria: false
+			},
+			encoding: {
+				y: band(true),
+				yOffset: {
+					field: "s",
+					type: "nominal",
+					sort: null,
+					scale: { paddingInner: .1 }
+				},
+				x: {
+					field: valueField,
+					type: "quantitative",
+					scale: {
+						zero: true,
+						nice: true
+					},
+					axis: axisLabels ? {
+						title: null,
+						tickCount: 3,
+						format: valueFormat,
+						formatType: "arcNumber",
+						domain: false,
+						ticks: false,
+						grid: true,
+						aria: false
+					} : null
+				},
+				fill: colorChannel,
+				...opacityChannel,
+				...tooltip ? { tooltip: tooltipChannel } : {}
+			}
+		});
+	}
+	if (mark === "parallel") {
+		const axisChannel = (owner) => ({
+			field: "i",
+			type: "ordinal",
+			sort: null,
+			scale: {
+				type: "point",
+				domain: { expr: AXIS_INDEX_DOMAIN_EXPR },
+				padding: PARALLEL_PADDING
+			},
+			...!axisLabels ? { axis: null } : owner ? { axis: {
+				title: null,
+				labelAngle: 0,
+				labelExpr: AXIS_LABEL_BY_INDEX_EXPR,
+				labelLimit: 72,
+				domain: false,
+				ticks: false,
+				grid: false,
+				aria: false
+			} } : {}
+		});
+		const valueChannel = {
+			field: "n",
+			type: "quantitative",
+			axis: null,
+			scale: {
+				domain: [0, 1],
+				nice: false
+			},
+			title: null
+		};
+		layers.push({
+			data: { name: PROFILE_AXES_DATASET },
+			mark: {
+				type: "rule",
+				stroke: tokens.grid,
+				strokeWidth: 1,
+				aria: false
+			},
+			encoding: {
+				x: axisChannel(true),
+				y: {
+					datum: 0,
+					type: "quantitative",
+					scale: {
+						domain: [0, 1],
+						nice: false
+					},
+					axis: null,
+					title: null
+				},
+				y2: { datum: 1 }
+			}
+		});
+		layers.push({
+			mark: {
+				type: "line",
+				strokeWidth: PATH_WIDTH,
+				strokeJoin: "round",
+				aria: false
+			},
+			encoding: {
+				x: axisChannel(false),
+				y: valueChannel,
+				stroke: colorChannel,
+				detail: seriesDetail,
+				order: {
+					field: "i",
+					type: "quantitative"
+				},
+				...opacityChannel
+			}
+		});
+		if (vertices) layers.push({
+			...hoverParam,
+			mark: {
+				type: "point",
+				filled: true,
+				size: VERTEX_SIZE,
+				aria: false
+			},
+			encoding: {
+				x: axisChannel(false),
+				y: valueChannel,
+				fill: colorChannel,
+				...opacityChannel,
+				...tooltip ? { tooltip: tooltipChannel } : {}
+			}
+		});
+	}
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 280,
+		height,
+		autosize: mark === "radar" ? { type: "none" } : {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: 0,
+		background: "transparent",
+		data: { name: PROFILE_CELLS_DATASET },
+		layer: layers,
+		config: (() => {
+			const base = arcVegaConfig(tokens, { locale });
+			return {
+				...base,
+				bar: {
+					...base.bar,
+					maxBandSize: MAX_GROUP_BAR
+				}
+			};
+		})()
+	};
+}
+//#endregion
+export { PROFILE_AXES_DATASET, PROFILE_CELLS_DATASET, PROFILE_HOVER_PARAM, PROFILE_RINGS_DATASET, buildProfilePlotSpec, profileNeedsRings };

package/dist/components/ProfileCard/ProfileCard.d.ts

@@ -0,0 +1,140 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ProfileCardLabels, ProfileCardSize, ProfileCardStatus, ProfileItem, ProfileMark, ProfileMetric, ProfileMetricInfo, ProfileNormalize, RADAR_MAX_AXES, RADAR_MAX_SERIES } from "./ProfileCard.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/ProfileCard/ProfileCard.d.ts
+interface ProfileCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The comparison'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 profile means, shown in a tooltip behind an info control beside the label and exposed to assistive technology as its description. */
+  hint?: string;
+  /**
+   * The measures — one axis each, **in the order they should be read**. The
+   * card never sorts them, because a radar's shape depends on the axis order:
+   * pick an order the reader recognises and keep it stable across renders.
+   * `max` gives a measure its own ceiling for `normalize="max"`, `format` its
+   * own number grammar. Pass `[]` while loading.
+   */
+  metrics: readonly ProfileMetric[];
+  /**
+   * The things being profiled. `values` is keyed by metric key; a metric an
+   * item has no reading for is a gap, not a zero — omit it or pass `null`.
+   * Pass `[]` while loading.
+   */
+  items: readonly ProfileItem[];
+  /**
+   * The form the plot draws. `radar` (default) for the shape of a profile;
+   * `grouped` when values rather than shapes are being compared — the
+   * accurate form; `parallel` when there are more items than a radar can
+   * overlay. Stamped as `data-mark`.
+   */
+  mark?: ProfileMark;
+  /**
+   * How readings on different measures are brought onto one axis. `shared`
+   * (default) keeps one scale across every metric — honest only when they
+   * are commensurable; `max` scales each metric to its own ceiling; `minmax`
+   * scales each to its own observed range, which is readable and the most
+   * misleading. Whichever is chosen is announced in the description and
+   * printed under the plot. Stamped as `data-normalize`.
+   */
+  normalize?: ProfileNormalize;
+  /**
+   * Fill each radar polygon faintly. **Off by default**: a polygon's area is
+   * a sum of products of adjacent readings, so it changes when the axes are
+   * reordered and must never be read as a score. Turn it on only for a
+   * single-item profile, where there is no area to compare against.
+   */
+  fill?: boolean;
+  /** Draw a dot at every reading, so a value is a mark and not only a bend in a path. Default `true`. */
+  vertices?: boolean;
+  /** Name the metrics on the plot. `false` on a panel too small for them — the popover table still carries every name. Default `true`. */
+  axisLabels?: boolean;
+  /**
+   * Key of the subject, controlled — pair with `onFocusChange`. Its path
+   * stays solid while the others recede, and the description says where it
+   * leads and trails. `null` designates none: every item reads equally.
+   */
+  focus?: string | null;
+  /** The subject on first render when `focus` is uncontrolled. Default: the first item. */
+  defaultFocus?: string | null;
+  /** Called with the chosen item's key when the reader picks another subject from the legend. */
+  onFocusChange?: (key: string) => void;
+  /** Keys of the items on the plot, controlled — pair with `onVisibleSeriesChange`. Omit for the uncontrolled legend. */
+  visibleSeries?: readonly string[];
+  /** The items on the plot at first render when `visibleSeries` is uncontrolled. Default: all of them. */
+  defaultVisibleSeries?: readonly string[];
+  /** Called with the new visible set when the reader toggles an item in the legend. */
+  onVisibleSeriesChange?: (keys: string[]) => void;
+  /** Show the legend. `false` only when another surface names every item. Default `true`. */
+  showLegend?: boolean;
+  /** One grammar for every reading that has no `ProfileMetric.format` of its own: `number[:digits]`, `integer`, `compact[:digits]`, `percent[:digits]`, `currency:CODE[:digits|compact]`. */
+  format?: string;
+  /** Custom formatter for readings. Takes precedence over `format` and over a metric's own `format`. */
+  formatValue?: (value: number, metric?: ProfileMetricInfo) => string;
+  /** Metrics the skeleton reserves before `metrics` arrive, so the panel is already its final height. Default 5. */
+  expectedMetrics?: number;
+  /** Items the skeleton reserves in the legend before they arrive. Default 2. */
+  expectedItems?: number;
+  /** The takeaway in a sentence, rendered beside the AI mark under the plot. Wrap values in `<strong>`. */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with data already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: ProfileCardStatus;
+  /** The consumer's filter is active — no readings 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?: ProfileCardSize;
+  /** 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<ProfileCardLabels>;
+  /** Replaces the generated accessible description of the whole card. */
+  description?: string;
+  /** Trailing header slot — a ghost `Button` or `Menu`. */
+  action?: ReactNode;
+  /** Open the data 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;
+  /** 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 profile panel — the ninth member of the analytics card family, and the
+ * only one that compares **several items across several measures at once**.
+ * MetricCard compares one metric with its own past; ComparisonCard compares
+ * one metric across items; TrendCard asks what shape a metric is in over
+ * time. ProfileCard answers the question none of them can: *what shape is
+ * each of these things across the same set of measures, and where does one
+ * lead or lag?*
+ *
+ * `mark="radar"` (default) draws the profile as a polygon per item — with the
+ * axis order fixed, the fill off and the scaling announced, which is what
+ * makes a radar honest. `mark="grouped"` is the accurate alternative for
+ * comparing values, and `mark="parallel"` carries more items than a radar
+ * can. Every reading is also in the popover table, the legend is real
+ * toggles, and every loading, empty, error and stale state is layout-stable
+ * inside one `Box` frame.
+ */
+declare const ProfileCard: import("react").ForwardRefExoticComponent<ProfileCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { ProfileCard, ProfileCardProps };