@databricks/appkit-ui 0.57.0 → 0.59.0

package/dist/js/format/index.d.ts

@@ -0,0 +1,38 @@
+import { MetricViewColumnDisplay } from "../../shared/src/metric-metadata.js";
+import "../../shared/src/index.js";
+
+//#region src/js/format/index.d.ts
+/**
+ * Format a raw value using a UC/YAML printf-style format spec.
+ *
+ *
+ * No format spec -> sensible default: numbers via `toLocaleString`, everything
+ * else via `String()`. `null`/`undefined` -> `""`. Unrecognized specs fall back
+ * to a best-effort result (the number grouped, or `String(value)`).
+ */
+declare function formatValue(value: unknown, format?: string): string;
+declare function formatLabel(name: string, columnMeta?: MetricViewColumnDisplay): string;
+interface D3FormatParts {
+  /** Numeric d3-format specifier, without a currency symbol. */
+  specifier: string;
+  /** Literal currency prefix from the UC format, when present. */
+  prefix?: string;
+}
+/**
+ * Maps a UC/spreadsheet-style format spec to the pieces consumed by
+ * [d3-format](https://d3js.org/d3-format)-based charts.
+ *
+ * Best-effort mapping for the common specs:
+ * - `"$#,##0.00"` -> `{ specifier: ",.2f", prefix: "$" }`
+ * - `"€#,##0.00"` -> `{ specifier: ",.2f", prefix: "€" }`
+ * - `"#,##0"` -> `{ specifier: ",.0f" }`, `"0.0%"` -> `{ specifier: ".1%" }`
+ *
+ * A d3 specifier cannot encode an arbitrary currency symbol: its `$` marker is
+ * resolved through global locale configuration. Returning the literal prefix
+ * separately lets consumers such as Plotly pass it as `tickprefix` instead of
+ * silently rendering every currency as `$`.
+ */
+declare function toD3Format(format?: string): D3FormatParts | undefined;
+//#endregion
+export { D3FormatParts, formatLabel, formatValue, toD3Format };
+//# sourceMappingURL=index.d.ts.map

package/dist/js/format/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/js/format/index.ts"],"mappings":";;;;;;AA8JA;;;;;AAuEA;iBAvEgB,WAAA,CAAY,KAAA,WAAgB,MAAA;AAAA,iBAuE5B,WAAA,CACd,IAAA,UACA,UAAA,GAAa,uBAAA;AAAA,UAME,aAAA;EAPf;EASA,SAAA;EARA;EAUA,MAAA;AAAA;AAJF;;;;;AAqBA;;;;;;;;;AArBA,iBAqBgB,UAAA,CAAW,MAAA,YAAkB,aAAA"}

package/dist/js/format/index.js

@@ -0,0 +1,160 @@
+//#region src/js/format/index.ts
+const SPEC_CACHE_MAX = 256;
+const specCache = /* @__PURE__ */ new Map();
+function countDecimals(format) {
+	const dotIndex = format.indexOf(".");
+	if (dotIndex === -1) return 0;
+	const match = format.slice(dotIndex + 1).match(/^[0#]+/);
+	return match ? match[0].length : 0;
+}
+/**
+* Best-effort coercion of an arbitrary value to a finite number.
+* Returns null when the value cannot be meaningfully treated as a number.
+*/
+function coerceNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "string") {
+		if (value.trim() === "") return null;
+		const n = Number(value);
+		return Number.isFinite(n) ? n : null;
+	}
+	return null;
+}
+/** Parse a plain decimal string without passing through a JS number. */
+function parseExactDecimal(value) {
+	const match = /^([+-]?)(\d+)(?:\.(\d+))?$/.exec(value.trim());
+	if (!match) return null;
+	const fraction = match[3] ?? "";
+	const coefficient = BigInt(`${match[2]}${fraction}`);
+	return {
+		coefficient,
+		negative: match[1] === "-" && coefficient !== 0n,
+		scale: fraction.length
+	};
+}
+function powerOfTen(exponent) {
+	return 10n ** BigInt(exponent);
+}
+/** Round an unsigned fixed-point coefficient to the requested display scale. */
+function quantizeDecimal(coefficient, sourceScale, targetScale) {
+	if (sourceScale <= targetScale) return coefficient * powerOfTen(targetScale - sourceScale);
+	const divisor = powerOfTen(sourceScale - targetScale);
+	const quotient = coefficient / divisor;
+	return coefficient % divisor * 2n >= divisor ? quotient + 1n : quotient;
+}
+function groupInteger(value) {
+	return value.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+/**
+* Format an exact fixed-point value without ever coercing it to `Number`.
+* Rounding is half-away-from-zero, matching Intl.NumberFormat's default.
+*/
+function formatExactDecimal(value, decimals, grouping, prefix, percent) {
+	const digits = quantizeDecimal(percent ? value.coefficient * 100n : value.coefficient, value.scale, decimals).toString().padStart(decimals + 1, "0");
+	const split = digits.length - decimals;
+	const integer = grouping ? groupInteger(digits.slice(0, split)) : digits.slice(0, split);
+	const fraction = decimals > 0 ? `.${digits.slice(split)}` : "";
+	return `${value.negative ? "-" : ""}${prefix}${integer}${fraction}${percent ? "%" : ""}`;
+}
+/** Format a number with fixed decimals + optional thousands grouping. */
+function formatNumber(value, decimals, grouping) {
+	return value.toLocaleString("en-US", {
+		minimumFractionDigits: decimals,
+		maximumFractionDigits: decimals,
+		useGrouping: grouping
+	});
+}
+/**
+* The currency symbol a spec carries — everything before the first digit
+* placeholder (`#`/`0`). The metric-view generator emits `$`, `€`, `£`, `¥`,
+* `₹`, `R$`, or an unknown ISO code + space (e.g. `"XYZ "`); this recovers any
+* of them verbatim. Returns `""` for a bare numeric spec (`"#,##0"`) or a
+* percent spec (`"0.0%"`), neither of which has a leading symbol.
+*/
+function currencyPrefix(format) {
+	const match = format.match(/^[^#0]+/);
+	return match ? match[0] : "";
+}
+/** The spec's `{ isPercent, grouping, decimals, prefix }`, parsed at most once. */
+function getOrParseSpec(format) {
+	const cached = specCache.get(format);
+	if (cached !== void 0) return cached;
+	const parsed = {
+		isPercent: format.includes("%"),
+		grouping: format.includes(","),
+		decimals: countDecimals(format),
+		prefix: currencyPrefix(format)
+	};
+	if (specCache.size < SPEC_CACHE_MAX) specCache.set(format, parsed);
+	return parsed;
+}
+/**
+* Format a raw value using a UC/YAML printf-style format spec.
+*
+*
+* No format spec -> sensible default: numbers via `toLocaleString`, everything
+* else via `String()`. `null`/`undefined` -> `""`. Unrecognized specs fall back
+* to a best-effort result (the number grouped, or `String(value)`).
+*/
+function formatValue(value, format) {
+	if (value === null || value === void 0) return "";
+	if (!format) {
+		if (typeof value === "number") return Number.isFinite(value) ? value.toLocaleString() : String(value);
+		if (typeof value === "bigint") return value.toLocaleString();
+		return String(value);
+	}
+	const { isPercent, grouping, decimals, prefix } = getOrParseSpec(format);
+	const exact = typeof value === "bigint" ? {
+		coefficient: value < 0n ? -value : value,
+		negative: value < 0n,
+		scale: 0
+	} : typeof value === "string" ? parseExactDecimal(value) : null;
+	if (exact !== null) return formatExactDecimal(exact, decimals, grouping, isPercent ? "" : prefix, isPercent);
+	const num = coerceNumber(value);
+	if (num === null) return String(value);
+	if (isPercent) return `${formatNumber(num * 100, decimals, grouping)}%`;
+	if (prefix) return `${num < 0 ? "-" : ""}${prefix}${formatNumber(Math.abs(num), decimals, grouping)}`;
+	return formatNumber(num, decimals, grouping);
+}
+function humanize(name) {
+	return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/_/g, " ").replace(/\s+/g, " ").toLowerCase().replace(/\b\w/g, (l) => l.toUpperCase()).trim();
+}
+function formatLabel(name, columnMeta) {
+	if (columnMeta?.display_name) return columnMeta.display_name;
+	return humanize(name);
+}
+/**
+* Maps a UC/spreadsheet-style format spec to the pieces consumed by
+* [d3-format](https://d3js.org/d3-format)-based charts.
+*
+* Best-effort mapping for the common specs:
+* - `"$#,##0.00"` -> `{ specifier: ",.2f", prefix: "$" }`
+* - `"€#,##0.00"` -> `{ specifier: ",.2f", prefix: "€" }`
+* - `"#,##0"` -> `{ specifier: ",.0f" }`, `"0.0%"` -> `{ specifier: ".1%" }`
+*
+* A d3 specifier cannot encode an arbitrary currency symbol: its `$` marker is
+* resolved through global locale configuration. Returning the literal prefix
+* separately lets consumers such as Plotly pass it as `tickprefix` instead of
+* silently rendering every currency as `$`.
+*/
+function toD3Format(format) {
+	if (!format) return void 0;
+	const { prefix, grouping, decimals, isPercent } = getOrParseSpec(format);
+	const numeric = format.slice(prefix.length);
+	if (numeric.replace(/[#0,.%\s]/g, "") !== "") return void 0;
+	if (!/[0#]/.test(numeric)) return void 0;
+	const group = grouping ? "," : "";
+	if (isPercent) return {
+		specifier: `${group}.${decimals}%`,
+		...prefix ? { prefix } : {}
+	};
+	return {
+		specifier: `${group}.${decimals}f`,
+		...prefix ? { prefix } : {}
+	};
+}
+
+//#endregion
+export { formatLabel, formatValue, toD3Format };
+//# sourceMappingURL=index.js.map

package/dist/js/format/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/js/format/index.ts"],"sourcesContent":["import type { MetricViewColumnDisplay } from \"shared\";\n\nexport type { MetricViewColumnDisplay };\n\nconst SPEC_CACHE_MAX = 256;\nconst specCache = new Map<\n  string,\n  {\n    isPercent: boolean;\n    grouping: boolean;\n    decimals: number;\n    prefix: string;\n  }\n>();\n\nfunction countDecimals(format: string): number {\n  const dotIndex = format.indexOf(\".\");\n  if (dotIndex === -1) return 0;\n  const frac = format.slice(dotIndex + 1);\n  const match = frac.match(/^[0#]+/);\n  return match ? match[0].length : 0;\n}\n\n/**\n * Best-effort coercion of an arbitrary value to a finite number.\n * Returns null when the value cannot be meaningfully treated as a number.\n */\nfunction coerceNumber(value: unknown): number | null {\n  if (typeof value === \"number\") return Number.isFinite(value) ? value : null;\n  if (typeof value === \"bigint\") return Number(value);\n  if (typeof value === \"string\") {\n    if (value.trim() === \"\") return null;\n    const n = Number(value);\n    return Number.isFinite(n) ? n : null;\n  }\n  return null;\n}\n\ninterface ExactDecimal {\n  coefficient: bigint;\n  negative: boolean;\n  scale: number;\n}\n\n/** Parse a plain decimal string without passing through a JS number. */\nfunction parseExactDecimal(value: string): ExactDecimal | null {\n  const match = /^([+-]?)(\\d+)(?:\\.(\\d+))?$/.exec(value.trim());\n  if (!match) return null;\n\n  const fraction = match[3] ?? \"\";\n  const coefficient = BigInt(`${match[2]}${fraction}`);\n  return {\n    coefficient,\n    negative: match[1] === \"-\" && coefficient !== 0n,\n    scale: fraction.length,\n  };\n}\n\nfunction powerOfTen(exponent: number): bigint {\n  return 10n ** BigInt(exponent);\n}\n\n/** Round an unsigned fixed-point coefficient to the requested display scale. */\nfunction quantizeDecimal(\n  coefficient: bigint,\n  sourceScale: number,\n  targetScale: number,\n): bigint {\n  if (sourceScale <= targetScale) {\n    return coefficient * powerOfTen(targetScale - sourceScale);\n  }\n\n  const divisor = powerOfTen(sourceScale - targetScale);\n  const quotient = coefficient / divisor;\n  const remainder = coefficient % divisor;\n  return remainder * 2n >= divisor ? quotient + 1n : quotient;\n}\n\nfunction groupInteger(value: string): string {\n  return value.replace(/\\B(?=(\\d{3})+(?!\\d))/g, \",\");\n}\n\n/**\n * Format an exact fixed-point value without ever coercing it to `Number`.\n * Rounding is half-away-from-zero, matching Intl.NumberFormat's default.\n */\nfunction formatExactDecimal(\n  value: ExactDecimal,\n  decimals: number,\n  grouping: boolean,\n  prefix: string,\n  percent: boolean,\n): string {\n  const coefficient = percent ? value.coefficient * 100n : value.coefficient;\n  const quantized = quantizeDecimal(coefficient, value.scale, decimals);\n  const digits = quantized.toString().padStart(decimals + 1, \"0\");\n  const split = digits.length - decimals;\n  const integer = grouping\n    ? groupInteger(digits.slice(0, split))\n    : digits.slice(0, split);\n  const fraction = decimals > 0 ? `.${digits.slice(split)}` : \"\";\n  const sign = value.negative ? \"-\" : \"\";\n  return `${sign}${prefix}${integer}${fraction}${percent ? \"%\" : \"\"}`;\n}\n\n/** Format a number with fixed decimals + optional thousands grouping. */\nfunction formatNumber(\n  value: number,\n  decimals: number,\n  grouping: boolean,\n): string {\n  return value.toLocaleString(\"en-US\", {\n    minimumFractionDigits: decimals,\n    maximumFractionDigits: decimals,\n    useGrouping: grouping,\n  });\n}\n\n/**\n * The currency symbol a spec carries — everything before the first digit\n * placeholder (`#`/`0`). The metric-view generator emits `$`, `€`, `£`, `¥`,\n * `₹`, `R$`, or an unknown ISO code + space (e.g. `\"XYZ \"`); this recovers any\n * of them verbatim. Returns `\"\"` for a bare numeric spec (`\"#,##0\"`) or a\n * percent spec (`\"0.0%\"`), neither of which has a leading symbol.\n */\nfunction currencyPrefix(format: string): string {\n  const match = format.match(/^[^#0]+/);\n  return match ? match[0] : \"\";\n}\n\n/** The spec's `{ isPercent, grouping, decimals, prefix }`, parsed at most once. */\nfunction getOrParseSpec(format: string) {\n  const cached = specCache.get(format);\n  if (cached !== undefined) return cached;\n\n  // Cache miss: parse now and store if under the limit.\n  const parsed = {\n    isPercent: format.includes(\"%\"),\n    grouping: format.includes(\",\"),\n    decimals: countDecimals(format),\n    prefix: currencyPrefix(format),\n  };\n\n  if (specCache.size < SPEC_CACHE_MAX) {\n    specCache.set(format, parsed);\n  }\n\n  return parsed;\n}\n\n/**\n * Format a raw value using a UC/YAML printf-style format spec.\n *\n *\n * No format spec -> sensible default: numbers via `toLocaleString`, everything\n * else via `String()`. `null`/`undefined` -> `\"\"`. Unrecognized specs fall back\n * to a best-effort result (the number grouped, or `String(value)`).\n */\nexport function formatValue(value: unknown, format?: string): string {\n  if (value === null || value === undefined) return \"\";\n\n  if (!format) {\n    if (typeof value === \"number\") {\n      return Number.isFinite(value) ? value.toLocaleString() : String(value);\n    }\n    if (typeof value === \"bigint\") return value.toLocaleString();\n    return String(value);\n  }\n\n  const { isPercent, grouping, decimals, prefix } = getOrParseSpec(format);\n\n  // JSON_ARRAY delivers SQL scalar cells as strings. Parse plain integer and\n  // fractional forms as fixed-point values so DECIMAL precision is never lost\n  // through Number(), even when the magnitude exceeds ±2^53.\n  const exact =\n    typeof value === \"bigint\"\n      ? {\n          coefficient: value < 0n ? -value : value,\n          negative: value < 0n,\n          scale: 0,\n        }\n      : typeof value === \"string\"\n        ? parseExactDecimal(value)\n        : null;\n  if (exact !== null) {\n    return formatExactDecimal(\n      exact,\n      decimals,\n      grouping,\n      isPercent ? \"\" : prefix,\n      isPercent,\n    );\n  }\n\n  const num = coerceNumber(value);\n  // Non-numeric value with a numeric-ish spec: nothing sensible to format.\n  if (num === null) return String(value);\n\n  if (isPercent) {\n    return `${formatNumber(num * 100, decimals, grouping)}%`;\n  }\n\n  if (prefix) {\n    const sign = num < 0 ? \"-\" : \"\";\n    return `${sign}${prefix}${formatNumber(Math.abs(num), decimals, grouping)}`;\n  }\n\n  return formatNumber(num, decimals, grouping);\n}\n\n// Turns a raw column name into a human-readable label.\nfunction humanize(name: string): string {\n  return (\n    name\n      // Handle consecutive uppercase followed by lowercase (e.g., HTTPUrl -> HTTP Url)\n      .replace(/([A-Z]+)([A-Z][a-z])/g, \"$1 $2\")\n      // Handle lowercase followed by uppercase (e.g., totalSpend -> total Spend)\n      .replace(/([a-z])([A-Z])/g, \"$1 $2\")\n      // Replace underscores with spaces\n      .replace(/_/g, \" \")\n      // Collapse multiple spaces into one\n      .replace(/\\s+/g, \" \")\n      // Normalize to title case\n      .toLowerCase()\n      .replace(/\\b\\w/g, (l) => l.toUpperCase())\n      .trim()\n  );\n}\n\nexport function formatLabel(\n  name: string,\n  columnMeta?: MetricViewColumnDisplay,\n): string {\n  if (columnMeta?.display_name) return columnMeta.display_name;\n  return humanize(name);\n}\n\nexport interface D3FormatParts {\n  /** Numeric d3-format specifier, without a currency symbol. */\n  specifier: string;\n  /** Literal currency prefix from the UC format, when present. */\n  prefix?: string;\n}\n\n/**\n * Maps a UC/spreadsheet-style format spec to the pieces consumed by\n * [d3-format](https://d3js.org/d3-format)-based charts.\n *\n * Best-effort mapping for the common specs:\n * - `\"$#,##0.00\"` -> `{ specifier: \",.2f\", prefix: \"$\" }`\n * - `\"€#,##0.00\"` -> `{ specifier: \",.2f\", prefix: \"€\" }`\n * - `\"#,##0\"` -> `{ specifier: \",.0f\" }`, `\"0.0%\"` -> `{ specifier: \".1%\" }`\n *\n * A d3 specifier cannot encode an arbitrary currency symbol: its `$` marker is\n * resolved through global locale configuration. Returning the literal prefix\n * separately lets consumers such as Plotly pass it as `tickprefix` instead of\n * silently rendering every currency as `$`.\n */\nexport function toD3Format(format?: string): D3FormatParts | undefined {\n  if (!format) return undefined;\n\n  // Strip any leading currency prefix first, then require the remainder to be\n  // built purely from numeric-format characters; anything else (date patterns,\n  // free text, ...) is left unrecognized.\n  const { prefix, grouping, decimals, isPercent } = getOrParseSpec(format);\n  const numeric = format.slice(prefix.length);\n  if (numeric.replace(/[#0,.%\\s]/g, \"\") !== \"\") return undefined;\n  if (!/[0#]/.test(numeric)) return undefined;\n\n  const group = grouping ? \",\" : \"\";\n\n  if (isPercent) {\n    return {\n      specifier: `${group}.${decimals}%`,\n      ...(prefix ? { prefix } : {}),\n    };\n  }\n\n  return {\n    specifier: `${group}.${decimals}f`,\n    ...(prefix ? { prefix } : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/js/index.d.ts

@@ -1,3 +1,5 @@
+import { MetricFilter, MetricFilterOperatorName, MetricOrderBy, MetricOrderDirection, MetricPredicate } from "../shared/src/metric-filter.js";
+import { MetricViewColumnDisplay } from "../shared/src/metric-metadata.js";
 import { SQLBinaryMarker, SQLBooleanMarker, SQLDateMarker, SQLNumberMarker, SQLStringMarker, SQLTimestampMarker, SQLTypeMarker } from "../shared/src/sql/types.js";
 import { isSQLTypeMarker, sql } from "../shared/src/sql/helpers.js";
 import "../shared/src/index.js";
@@ -6,6 +8,8 @@ import { ArrowClient, DetectedFields, Field, Table } from "./arrow/arrow-client.
 import { getArrowModule, initializeTypeIdSets } from "./arrow/lazy-arrow.js";
 import "./arrow/index.js";
 import { AppKitClientConfig, _resetConfigCache, getClientConfig, getPluginClientConfig } from "./config.js";
+import { D3FormatParts, formatLabel, formatValue, toD3Format } from "./format/index.js";
+import { MetricFilterShorthand, toMetricFilter } from "./metric-filter/index.js";
 import { ConnectSSEOptions, SSEMessage } from "./sse/types.js";
 import { connectSSE } from "./sse/connect-sse.js";
-export { AppKitClientConfig, ArrowClient, ConnectSSEOptions, DATE_FIELD_PATTERNS, DetectedFields, Field, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS, type SQLBinaryMarker, type SQLBooleanMarker, type SQLDateMarker, type SQLNumberMarker, type SQLStringMarker, type SQLTimestampMarker, type SQLTypeMarker, SSEMessage, Table, _resetConfigCache, connectSSE, getArrowModule, getClientConfig, getPluginClientConfig, initializeTypeIdSets, isSQLTypeMarker, sql };
+export { AppKitClientConfig, ArrowClient, ConnectSSEOptions, D3FormatParts, DATE_FIELD_PATTERNS, DetectedFields, Field, METADATA_DATE_PATTERNS, MetricFilter, MetricFilterOperatorName, MetricFilterShorthand, MetricOrderBy, MetricOrderDirection, MetricPredicate, MetricViewColumnDisplay, NAME_FIELD_PATTERNS, type SQLBinaryMarker, type SQLBooleanMarker, type SQLDateMarker, type SQLNumberMarker, type SQLStringMarker, type SQLTimestampMarker, type SQLTypeMarker, SSEMessage, Table, _resetConfigCache, connectSSE, formatLabel, formatValue, getArrowModule, getClientConfig, getPluginClientConfig, initializeTypeIdSets, isSQLTypeMarker, sql, toD3Format, toMetricFilter };

package/dist/js/index.js

@@ -3,6 +3,8 @@ import { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS } from
 import { getArrowModule, initializeTypeIdSets } from "./arrow/lazy-arrow.js";
 import { ArrowClient } from "./arrow/arrow-client.js";
 import { _resetConfigCache, getClientConfig, getPluginClientConfig } from "./config.js";
+import { formatLabel, formatValue, toD3Format } from "./format/index.js";
+import { toMetricFilter } from "./metric-filter/index.js";
 import { connectSSE } from "./sse/connect-sse.js";
 
-export { ArrowClient, DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS, _resetConfigCache, connectSSE, getArrowModule, getClientConfig, getPluginClientConfig, initializeTypeIdSets, isSQLTypeMarker, sql };
+export { ArrowClient, DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS, _resetConfigCache, connectSSE, formatLabel, formatValue, getArrowModule, getClientConfig, getPluginClientConfig, initializeTypeIdSets, isSQLTypeMarker, sql, toD3Format, toMetricFilter };

package/dist/js/metric-filter/index.d.ts

@@ -0,0 +1,40 @@
+import { MetricFilter, MetricFilterOperatorName, MetricOrderBy, MetricOrderDirection, MetricPredicate } from "../../shared/src/metric-filter.js";
+import "../../shared/src/index.js";
+
+//#region src/js/metric-filter/index.d.ts
+/**
+ * Shorthand map of `dimension -> selected value(s)`.
+ * A member is dropped when its value is `undefined` or empty array,
+ * so a partially-filled filter-bar selection maps straight to "no predicate for that dimension".
+ *
+ */
+type MetricFilterShorthand = Record<string, string | number | null | ReadonlyArray<string | number> | undefined>;
+/**
+ * Compile a `{ dimension -> value(s) }` shorthand into a {@link MetricFilter}
+ * Returns a bare {@link MetricPredicate} for a single member, an `and` group for
+ * several, and `undefined` when nothing is selected (so the caller can pass it
+ * straight to `useMetricView`'s optional `filter`, which omits the field when
+ * `undefined`). For operators beyond equality/membership (ranges, `contains`,
+ * `set`), build the {@link MetricFilter} tree directly.
+ *
+ * @example
+ * ```typescript
+ * toMetricFilter({ region: "EMEA" });
+ * // → { member: "region", operator: "equals", values: ["EMEA"] }
+ *
+ * toMetricFilter({ region: ["EMEA", "APAC"], segment: "SMB" });
+ * // → { and: [
+ * //     { member: "region", operator: "in", values: ["EMEA", "APAC"] },
+ * //     { member: "segment", operator: "equals", values: ["SMB"] },
+ * //   ] }
+ *
+ * toMetricFilter({ region: undefined }); // → undefined
+ *
+ * toMetricFilter({ region: null });
+ * // → { member: "region", operator: "notSet" }
+ * ```
+ */
+declare function toMetricFilter(selection: MetricFilterShorthand): MetricFilter | undefined;
+//#endregion
+export { MetricFilterShorthand, toMetricFilter };
+//# sourceMappingURL=index.d.ts.map

package/dist/js/metric-filter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/js/metric-filter/index.ts"],"mappings":";;;;;;AAgBA;;;;KAAY,qBAAA,GAAwB,MAAA,kCAET,aAAA;AA4B3B;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iBAAgB,cAAA,CACd,SAAA,EAAW,qBAAA,GACV,YAAA"}

package/dist/js/metric-filter/index.js

@@ -0,0 +1,56 @@
+//#region src/js/metric-filter/index.ts
+/**
+* Compile a `{ dimension -> value(s) }` shorthand into a {@link MetricFilter}
+* Returns a bare {@link MetricPredicate} for a single member, an `and` group for
+* several, and `undefined` when nothing is selected (so the caller can pass it
+* straight to `useMetricView`'s optional `filter`, which omits the field when
+* `undefined`). For operators beyond equality/membership (ranges, `contains`,
+* `set`), build the {@link MetricFilter} tree directly.
+*
+* @example
+* ```typescript
+* toMetricFilter({ region: "EMEA" });
+* // → { member: "region", operator: "equals", values: ["EMEA"] }
+*
+* toMetricFilter({ region: ["EMEA", "APAC"], segment: "SMB" });
+* // → { and: [
+* //     { member: "region", operator: "in", values: ["EMEA", "APAC"] },
+* //     { member: "segment", operator: "equals", values: ["SMB"] },
+* //   ] }
+*
+* toMetricFilter({ region: undefined }); // → undefined
+*
+* toMetricFilter({ region: null });
+* // → { member: "region", operator: "notSet" }
+* ```
+*/
+function toMetricFilter(selection) {
+	const predicates = [];
+	for (const member of Object.keys(selection)) {
+		const value = selection[member];
+		if (value === void 0) continue;
+		if (value === null) predicates.push({
+			member,
+			operator: "notSet"
+		});
+		else if (Array.isArray(value)) {
+			if (value.length === 0) continue;
+			predicates.push({
+				member,
+				operator: "in",
+				values: [...value]
+			});
+		} else predicates.push({
+			member,
+			operator: "equals",
+			values: [value]
+		});
+	}
+	if (predicates.length === 0) return void 0;
+	if (predicates.length === 1) return predicates[0];
+	return { and: predicates };
+}
+
+//#endregion
+export { toMetricFilter };
+//# sourceMappingURL=index.js.map

package/dist/js/metric-filter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/js/metric-filter/index.ts"],"sourcesContent":["import type { MetricFilter, MetricPredicate } from \"shared\";\n\nexport type {\n  MetricFilter,\n  MetricFilterOperatorName,\n  MetricOrderBy,\n  MetricOrderDirection,\n  MetricPredicate,\n} from \"shared\";\n\n/**\n * Shorthand map of `dimension -> selected value(s)`.\n * A member is dropped when its value is `undefined` or empty array,\n * so a partially-filled filter-bar selection maps straight to \"no predicate for that dimension\".\n *\n */\nexport type MetricFilterShorthand = Record<\n  string,\n  string | number | null | ReadonlyArray<string | number> | undefined\n>;\n\n/**\n * Compile a `{ dimension -> value(s) }` shorthand into a {@link MetricFilter}\n * Returns a bare {@link MetricPredicate} for a single member, an `and` group for\n * several, and `undefined` when nothing is selected (so the caller can pass it\n * straight to `useMetricView`'s optional `filter`, which omits the field when\n * `undefined`). For operators beyond equality/membership (ranges, `contains`,\n * `set`), build the {@link MetricFilter} tree directly.\n *\n * @example\n * ```typescript\n * toMetricFilter({ region: \"EMEA\" });\n * // → { member: \"region\", operator: \"equals\", values: [\"EMEA\"] }\n *\n * toMetricFilter({ region: [\"EMEA\", \"APAC\"], segment: \"SMB\" });\n * // → { and: [\n * //     { member: \"region\", operator: \"in\", values: [\"EMEA\", \"APAC\"] },\n * //     { member: \"segment\", operator: \"equals\", values: [\"SMB\"] },\n * //   ] }\n *\n * toMetricFilter({ region: undefined }); // → undefined\n *\n * toMetricFilter({ region: null });\n * // → { member: \"region\", operator: \"notSet\" }\n * ```\n */\nexport function toMetricFilter(\n  selection: MetricFilterShorthand,\n): MetricFilter | undefined {\n  const predicates: MetricPredicate[] = [];\n  for (const member of Object.keys(selection)) {\n    const value = selection[member];\n    if (value === undefined) continue;\n    if (value === null) {\n      predicates.push({ member, operator: \"notSet\" });\n    } else if (Array.isArray(value)) {\n      if (value.length === 0) continue;\n      predicates.push({ member, operator: \"in\", values: [...value] });\n    } else {\n      predicates.push({\n        member,\n        operator: \"equals\",\n        values: [value as string | number],\n      });\n    }\n  }\n  if (predicates.length === 0) return undefined;\n  if (predicates.length === 1) return predicates[0];\n  return { and: predicates };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,SAAgB,eACd,WAC0B;CAC1B,MAAM,aAAgC,EAAE;AACxC,MAAK,MAAM,UAAU,OAAO,KAAK,UAAU,EAAE;EAC3C,MAAM,QAAQ,UAAU;AACxB,MAAI,UAAU,OAAW;AACzB,MAAI,UAAU,KACZ,YAAW,KAAK;GAAE;GAAQ,UAAU;GAAU,CAAC;WACtC,MAAM,QAAQ,MAAM,EAAE;AAC/B,OAAI,MAAM,WAAW,EAAG;AACxB,cAAW,KAAK;IAAE;IAAQ,UAAU;IAAM,QAAQ,CAAC,GAAG,MAAM;IAAE,CAAC;QAE/D,YAAW,KAAK;GACd;GACA,UAAU;GACV,QAAQ,CAAC,MAAyB;GACnC,CAAC;;AAGN,KAAI,WAAW,WAAW,EAAG,QAAO;AACpC,KAAI,WAAW,WAAW,EAAG,QAAO,WAAW;AAC/C,QAAO,EAAE,KAAK,YAAY"}

package/dist/react/charts/base.d.ts

@@ -1,4 +1,4 @@
-import { ChartColorPalette, ChartData, ChartType, Orientation } from "./types.js";
+import { ChartClickDatum, ChartColorPalette, ChartData, ChartType, ChartValueFormatter, Orientation } from "./types.js";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/react/charts/base.d.ts
@@ -62,8 +62,22 @@ interface BaseChartProps {
    * duplicate echarts copies won't share registrations).
    */
   options?: Record<string, unknown>;
+  /** Formats measure values. See {@link ChartBaseProps.valueFormatter}. */
+  valueFormatter?: ChartValueFormatter;
   /** Additional CSS classes */
   className?: string;
+  /**
+   * Fired when a data element (bar, slice, point) is clicked. Fire-and-forget:
+   * the return value is ignored (async handlers are fine — the chart never awaits).
+   * The handler receives a normalized {@link ChartClickDatum}.
+   *
+   * Pointer-only: charts render to <canvas>, so this does not fire for keyboard
+   * users. Provide a keyboard-accessible equivalent (e.g. a table row action) for
+   * the same action.
+   */
+  onDataClick?: (datum: ChartClickDatum) => void;
+  /** Controlled selection by category name. See {@link ChartBaseProps.selected}. */
+  selected?: string | string[];
 }
 /**
  * Base chart component that handles both Arrow and JSON data.
@@ -92,7 +106,10 @@ declare function BaseChart({
   min,
   max,
   options: customOptions,
-  className
+  valueFormatter,
+  className,
+  onDataClick,
+  selected
 }: BaseChartProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { BaseChart, BaseChartProps };

package/dist/react/charts/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","names":[],"sources":["../../../src/react/charts/base.tsx"],"mappings":";;;;UA4GiB,cAAA;;EAEf,IAAA,EAAM,SAAA;EAFS;EAIf,SAAA,EAAW,SAAA;;EAEX,IAAA;EAFW;EAIX,IAAA;EAee;EAbf,WAAA,GAAc,WAAA;EAiDE;EA/ChB,MAAA;EAVA;EAYA,KAAA;EAVA;EAYA,UAAA;EAVA;;;;;;EAiBA,YAAA,GAAe,iBAAA;EAAf;EAEA,MAAA;EAAA;EAEA,UAAA;EAEA;EAAA,MAAA;EAIA;EAFA,OAAA;EAMA;EAJA,UAAA;EAQA;EANA,QAAA;EAUA;EARA,WAAA;EAsBA;EApBA,UAAA;EAsBA;EApBA,aAAA;EAoBS;EAlBT,QAAA;EA6BuB;EA3BvB,GAAA;EA4BA;EA1BA,GAAA;EA4BA;;;;;;;;;;;EAhBA,OAAA,GAAU,MAAA;EA4BV;EA1BA,SAAA;AAAA;;;;;iBAWc,SAAA,CAAA;EACd,IAAA;EACA,SAAA;EACA,IAAA;EACA,IAAA;EACA,WAAA;EACA,MAAA;EACA,KAAA;EACA,UAAA;EACA,YAAA;EACA,MAAA,EAAQ,YAAA;EACR,UAAA;EACA,MAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA;EACA,WAAA;EACA,UAAA;EACA,aAAA;EACA,QAAA;EACA,GAAA;EACA,GAAA;EACA,OAAA,EAAS,aAAA;EACT;AAAA,GACC,cAAA,GAAc,kBAAA,CAAA,GAAA,CAAA,OAAA"}
+{"version":3,"file":"base.d.ts","names":[],"sources":["../../../src/react/charts/base.tsx"],"mappings":";;;;UAiHiB,cAAA;;EAEf,IAAA,EAAM,SAAA;EAFS;EAIf,SAAA,EAAW,SAAA;;EAEX,IAAA;EAFW;EAIX,IAAA;EAee;EAbf,WAAA,GAAc,WAAA;EAmDG;EAjDjB,MAAA;EA6DqC;EA3DrC,KAAA;EAZA;EAcA,UAAA;EAZA;;;;;;EAmBA,YAAA,GAAe,iBAAA;EATf;EAWA,MAAA;EAFA;EAIA,UAAA;EAFA;EAIA,MAAA;EAAA;EAEA,OAAA;EAEA;EAAA,UAAA;EAIA;EAFA,QAAA;EAMA;EAJA,WAAA;EAQA;EANA,UAAA;EAoBA;EAlBA,aAAA;EAoBA;EAlBA,QAAA;EAoBA;EAlBA,GAAA;EA4BsB;EA1BtB,GAAA;EA4BA;;;AAWF;;;;;;;;EA3BE,OAAA,GAAU,MAAA;EAkCV;EAhCA,cAAA,GAAiB,mBAAA;EAkCjB;EAhCA,SAAA;EAkCA;;;;;;;;;EAxBA,WAAA,IAAe,KAAA,EAAO,eAAA;EAkCtB;EAhCA,QAAA;AAAA;;;;;iBAWc,SAAA,CAAA;EACd,IAAA;EACA,SAAA;EACA,IAAA;EACA,IAAA;EACA,WAAA;EACA,MAAA;EACA,KAAA;EACA,UAAA;EACA,YAAA;EACA,MAAA,EAAQ,YAAA;EACR,UAAA;EACA,MAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA;EACA,WAAA;EACA,UAAA;EACA,aAAA;EACA,QAAA;EACA,GAAA;EACA,GAAA;EACA,OAAA,EAAS,aAAA;EACT,cAAA;EACA,SAAA;EACA,WAAA;EACA;AAAA,GACC,cAAA,GAAc,kBAAA,CAAA,GAAA,CAAA,OAAA"}

package/dist/react/charts/base.js

@@ -1,5 +1,6 @@
+import { mapToDatum } from "./utils.js";
 import { normalizeChartData, normalizeHeatmapData } from "./normalize.js";
-import { buildCartesianOption, buildHeatmapOption, buildHorizontalBarOption, buildPieOption, buildRadarOption } from "./options.js";
+import { applySelectionEmphasis, buildCartesianOption, buildHeatmapOption, buildHorizontalBarOption, buildPieOption, buildRadarOption } from "./options.js";
 import { useChartUITokens, useThemeColors } from "./theme.js";
 import { BarChart, HeatmapChart, LineChart, PieChart, RadarChart, ScatterChart } from "echarts/charts";
 import { GridComponent, LegendComponent, TitleComponent, TooltipComponent, VisualMapComponent } from "echarts/components";
@@ -41,10 +42,13 @@ function getDefaultPalette(chartType) {
 * Base chart component that handles both Arrow and JSON data.
 * Renders using ECharts for consistent output across both formats.
 */
-function BaseChart({ data, chartType, xKey, yKey, orientation, height = 300, title, showLegend = true, colorPalette, colors: customColors, showSymbol = false, smooth = true, stacked = false, symbolSize = 8, showArea = true, innerRadius = 0, showLabels = true, labelPosition = "outside", yAxisKey, min, max, options: customOptions, className }) {
+function BaseChart({ data, chartType, xKey, yKey, orientation, height = 300, title, showLegend = true, colorPalette, colors: customColors, showSymbol = false, smooth = true, stacked = false, symbolSize = 8, showArea = true, innerRadius = 0, showLabels = true, labelPosition = "outside", yAxisKey, min, max, options: customOptions, valueFormatter, className, onDataClick, selected }) {
 	const themeColors = useThemeColors(colorPalette ?? getDefaultPalette(chartType));
 	const colors = customColors ?? themeColors;
 	const ui = useChartUITokens();
+	const interactive = !!onDataClick;
+	const onDataClickRef = useRef(onDataClick);
+	onDataClickRef.current = onDataClick;
 	const echartsInstanceRef = useRef(null);
 	const chartRefCallback = useCallback((node) => {
 		if (echartsInstanceRef.current && !echartsInstanceRef.current.isDisposed()) echartsInstanceRef.current.dispose();
@@ -74,7 +78,8 @@ function BaseChart({ data, chartType, xKey, yKey, orientation, height = 300, tit
 			title,
 			showLegend,
 			xField,
-			ui
+			ui,
+			valueFormatter
 		};
 		const isPie = chartType === "pie" || chartType === "donut";
 		const isRadar = chartType === "radar";
@@ -101,12 +106,13 @@ function BaseChart({ data, chartType, xKey, yKey, orientation, height = 300, tit
 			stacked,
 			smooth,
 			showSymbol,
-			symbolSize
+			symbolSize,
+			interactive
 		});
-		return customOptions ? {
+		return applySelectionEmphasis(customOptions ? {
 			...opt,
 			...customOptions
-		} : opt;
+		} : opt, selected);
 	}, [
 		normalized,
 		colors,
@@ -125,8 +131,21 @@ function BaseChart({ data, chartType, xKey, yKey, orientation, height = 300, tit
 		showArea,
 		min,
 		max,
-		customOptions
+		customOptions,
+		valueFormatter,
+		selected,
+		interactive
 	]);
+	const axisLabels = useMemo(() => ({
+		xLabels: normalized.xData,
+		yLabels: "yAxisData" in normalized ? normalized.yAxisData : void 0
+	}), [normalized]);
+	const axisLabelsRef = useRef(axisLabels);
+	axisLabelsRef.current = axisLabels;
+	const onEvents = useMemo(() => interactive ? { click: (params, instance) => {
+		const result = onDataClickRef.current?.(mapToDatum(params, axisLabelsRef.current, instance));
+		if (result && typeof result.then === "function") result.catch(() => {});
+	} } : void 0, [interactive]);
 	if (!option) return /* @__PURE__ */ jsx("div", {
 		className: "flex items-center justify-center h-full text-muted-foreground",
 		children: "No data"
@@ -139,7 +158,8 @@ function BaseChart({ data, chartType, xKey, yKey, orientation, height = 300, tit
 		className,
 		opts: { renderer: "canvas" },
 		notMerge: false,
-		lazyUpdate: true
+		lazyUpdate: true,
+		onEvents
 	});
 }
 

package/dist/react/charts/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","names":[],"sources":["../../../src/react/charts/base.tsx"],"sourcesContent":["// Type-only import: erased at compile time, does not pull the full echarts\n// bundle in. The `ECharts` type is used for the stored ECharts instance ref.\nimport type { ECharts } from \"echarts\";\nimport {\n  BarChart,\n  HeatmapChart,\n  LineChart,\n  PieChart,\n  RadarChart,\n  ScatterChart,\n} from \"echarts/charts\";\nimport {\n  GridComponent,\n  LegendComponent,\n  TitleComponent,\n  TooltipComponent,\n  VisualMapComponent,\n} from \"echarts/components\";\nimport * as echarts from \"echarts/core\";\nimport { LegacyGridContainLabel } from \"echarts/features\";\nimport { CanvasRenderer } from \"echarts/renderers\";\n// Import the ESM core build, not `echarts-for-react/lib/core` (CJS). The package\n// has no `exports` map, so `/lib/core` resolves to the literal CommonJS file\n// whose default export is `module.exports`; under ESM default-import interop a\n// consumer's bundler hands back the whole `{ default, __esModule }` object rather\n// than the component, so `<ReactEChartsCore/>` renders an object and React throws\n// \"Element type is invalid\". `esm/core` is real ESM with a true `export default`.\nimport ReactEChartsCore from \"echarts-for-react/esm/core\";\nimport { useCallback, useMemo, useRef } from \"react\";\nimport { normalizeChartData, normalizeHeatmapData } from \"./normalize\";\nimport {\n  buildCartesianOption,\n  buildHeatmapOption,\n  buildHorizontalBarOption,\n  buildPieOption,\n  buildRadarOption,\n  type OptionBuilderContext,\n} from \"./options\";\nimport { useChartUITokens, useThemeColors } from \"./theme\";\nimport type {\n  ChartColorPalette,\n  ChartData,\n  ChartType,\n  Orientation,\n} from \"./types\";\n\n// ============================================================================\n// ECharts Registration (modular imports for tree-shaking)\n// ============================================================================\n// Only the chart types and components used by the option builders in\n// `options.ts` are registered. Importing from `echarts/core` instead of the\n// full `echarts` entry keeps unused chart types (graph, sankey, gauge, ...)\n// out of consumer bundles.\n//\n// If you add a new chart type or use a new ECharts feature (e.g. dataZoom,\n// toolbox, markLine), register it here. Consumers passing custom `options`\n// that need extra features can register them in their own app via\n// `import { use } from \"echarts/core\"`.\n//\n// Note: tooltip-driven axisPointer is bundled with `TooltipComponent`, so no\n// explicit AxisPointerComponent registration is needed.\n//\n// This `use()` call must stay co-located in the same module as `BaseChart`:\n// `package.json#sideEffects` declares JS modules side-effect free, so moving\n// registration to a separate import-for-side-effect module would let bundlers\n// drop it during tree-shaking.\necharts.use([\n  // Series types used by the option builders\n  LineChart, // line + area charts (area = line with areaStyle)\n  BarChart, // bar + horizontal bar charts\n  PieChart, // pie + donut charts\n  ScatterChart,\n  HeatmapChart,\n  RadarChart,\n  // Components referenced by built options\n  TitleComponent, // `title`\n  TooltipComponent, // `tooltip`\n  LegendComponent, // `legend`\n  GridComponent, // `grid` / `xAxis` / `yAxis`\n  VisualMapComponent, // `visualMap` (heatmap color scale)\n  // Features\n  LegacyGridContainLabel, // `grid.containLabel` (cartesian option builder)\n  // Renderer (BaseChart always renders with `renderer: \"canvas\"`)\n  CanvasRenderer,\n]);\n\n// ============================================================================\n// Palette Selection\n// ============================================================================\n\n/**\n * Determines the appropriate color palette for a chart type.\n * - Heatmaps use sequential (low → high intensity)\n * - All other charts use categorical (distinct categories)\n */\nfunction getDefaultPalette(chartType: ChartType): ChartColorPalette {\n  switch (chartType) {\n    case \"heatmap\":\n      return \"sequential\";\n    default:\n      return \"categorical\";\n  }\n}\n\n// ============================================================================\n// Component Props\n// ============================================================================\n\nexport interface BaseChartProps {\n  /** Chart data (Arrow Table or JSON array) - format is auto-detected */\n  data: ChartData;\n  /** Chart type */\n  chartType: ChartType;\n  /** X-axis field key (auto-detected from schema if not provided) */\n  xKey?: string;\n  /** Y-axis field key(s) (auto-detected from schema if not provided) */\n  yKey?: string | string[];\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Chart height in pixels @default 300 */\n  height?: number;\n  /** Chart title */\n  title?: string;\n  /** Show legend @default true */\n  showLegend?: boolean;\n  /**\n   * Color palette to use. Auto-selected based on chart type if not specified.\n   * - \"categorical\": Distinct colors for different categories (bar, pie, line)\n   * - \"sequential\": Gradient for magnitude (heatmap)\n   * - \"diverging\": Two-tone for positive/negative (correlation)\n   */\n  colorPalette?: ChartColorPalette;\n  /** Custom colors (overrides colorPalette) */\n  colors?: string[];\n  /** Show data point symbols (line/area charts) @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves (line/area charts) @default true */\n  smooth?: boolean;\n  /** Stack series @default false */\n  stacked?: boolean;\n  /** Symbol size for scatter charts @default 8 */\n  symbolSize?: number;\n  /** Show area fill for radar charts @default true */\n  showArea?: boolean;\n  /** Inner radius for pie/donut (0-100) @default 0 */\n  innerRadius?: number;\n  /** Show labels on pie/donut slices @default true */\n  showLabels?: boolean;\n  /** Label position for pie/donut @default \"outside\" */\n  labelPosition?: \"outside\" | \"inside\" | \"center\";\n  /** Y-axis field key for heatmap (the row dimension) */\n  yAxisKey?: string;\n  /** Min value for heatmap color scale */\n  min?: number;\n  /** Max value for heatmap color scale */\n  max?: number;\n  /**\n   * Additional ECharts options to merge.\n   *\n   * Only the built-in feature set is registered by this package, so options\n   * referencing extra ECharts features (`dataZoom`, `toolbox`, `markLine`,\n   * `markArea`, `graphic`, `dataset`, top-level `axisPointer`, ...) require\n   * registering them in your app via `import { use } from \"echarts/core\"`.\n   * This only works when your `echarts` resolves to the same module\n   * instance/version as this package's (the registry is a singleton;\n   * duplicate echarts copies won't share registrations).\n   */\n  options?: Record<string, unknown>;\n  /** Additional CSS classes */\n  className?: string;\n}\n\n// ============================================================================\n// Base Chart Component\n// ============================================================================\n\n/**\n * Base chart component that handles both Arrow and JSON data.\n * Renders using ECharts for consistent output across both formats.\n */\nexport function BaseChart({\n  data,\n  chartType,\n  xKey,\n  yKey,\n  orientation,\n  height = 300,\n  title,\n  showLegend = true,\n  colorPalette,\n  colors: customColors,\n  showSymbol = false,\n  smooth = true,\n  stacked = false,\n  symbolSize = 8,\n  showArea = true,\n  innerRadius = 0,\n  showLabels = true,\n  labelPosition = \"outside\",\n  yAxisKey,\n  min,\n  max,\n  options: customOptions,\n  className,\n}: BaseChartProps) {\n  // Determine the appropriate color palette based on chart type\n  const resolvedPalette = colorPalette ?? getDefaultPalette(chartType);\n  const themeColors = useThemeColors(resolvedPalette);\n  const colors = customColors ?? themeColors;\n\n  const ui = useChartUITokens();\n\n  // Store ECharts instance directly to avoid stale ref issues on unmount\n  const echartsInstanceRef = useRef<ECharts | null>(null);\n\n  // Callback ref pattern: captures the ECharts instance when ReactECharts mounts\n  // This ensures we always have a stable reference to the actual instance\n  const chartRefCallback = useCallback((node: ReactEChartsCore | null) => {\n    // Dispose previous instance if component is being replaced\n    if (\n      echartsInstanceRef.current &&\n      !echartsInstanceRef.current.isDisposed()\n    ) {\n      echartsInstanceRef.current.dispose();\n    }\n\n    // Store the new instance\n    if (node) {\n      echartsInstanceRef.current = node.getEchartsInstance();\n    } else {\n      // Component unmounting - dispose the stored instance\n      if (\n        echartsInstanceRef.current &&\n        !echartsInstanceRef.current.isDisposed()\n      ) {\n        echartsInstanceRef.current.dispose();\n      }\n      echartsInstanceRef.current = null;\n    }\n  }, []);\n\n  // Memoize data normalization\n  const normalized = useMemo(\n    () =>\n      chartType === \"heatmap\"\n        ? normalizeHeatmapData(data, xKey, yAxisKey, yKey)\n        : normalizeChartData(data, xKey, yKey, orientation),\n    [data, xKey, yKey, yAxisKey, orientation, chartType],\n  );\n\n  // Memoize option building\n  const option = useMemo(() => {\n    const { xData, yFields, xField, chartType: detectedChartType } = normalized;\n\n    if (xData.length === 0) return null;\n\n    // Determine chart mode first (needed to handle yDataMap)\n    const isHeatmap = chartType === \"heatmap\";\n\n    // Heatmaps use heatmapData instead of yDataMap\n    // For other charts, yDataMap is required\n    const yDataMap = \"yDataMap\" in normalized ? normalized.yDataMap : {};\n\n    const baseCtx: OptionBuilderContext = {\n      xData,\n      yDataMap,\n      yFields,\n      colors,\n      title,\n      showLegend,\n      xField,\n      ui,\n    };\n    const isPie = chartType === \"pie\" || chartType === \"donut\";\n    const isRadar = chartType === \"radar\";\n    const isHorizontal =\n      !isPie &&\n      !isRadar &&\n      !isHeatmap &&\n      (orientation === \"horizontal\" ||\n        (detectedChartType === \"categorical\" &&\n          !orientation &&\n          chartType === \"bar\"));\n    const isTimeSeries =\n      detectedChartType === \"timeseries\" &&\n      !isHorizontal &&\n      !isRadar &&\n      !isHeatmap;\n\n    // Build option based on chart type\n    let opt: Record<string, unknown>;\n\n    if (isHeatmap && \"yAxisData\" in normalized && \"heatmapData\" in normalized) {\n      const heatmapNorm = normalized as {\n        yAxisData: (string | number)[];\n        heatmapData: [number, number, number][];\n        min: number;\n        max: number;\n      } & typeof normalized;\n      opt = buildHeatmapOption({\n        ...baseCtx,\n        yAxisData: heatmapNorm.yAxisData,\n        heatmapData: heatmapNorm.heatmapData,\n        min: min ?? heatmapNorm.min,\n        max: max ?? heatmapNorm.max,\n        showLabels,\n      });\n    } else if (isRadar) {\n      opt = buildRadarOption(baseCtx, showArea);\n    } else if (isPie) {\n      opt = buildPieOption(\n        baseCtx,\n        chartType as \"pie\" | \"donut\",\n        innerRadius,\n        showLabels,\n        labelPosition,\n      );\n    } else if (isHorizontal) {\n      opt = buildHorizontalBarOption(baseCtx, stacked);\n    } else {\n      opt = buildCartesianOption({\n        ...baseCtx,\n        chartType,\n        isTimeSeries,\n        stacked,\n        smooth,\n        showSymbol,\n        symbolSize,\n      });\n    }\n\n    // Merge custom options\n    return customOptions ? { ...opt, ...customOptions } : opt;\n  }, [\n    normalized,\n    colors,\n    ui,\n    title,\n    showLegend,\n    chartType,\n    orientation,\n    innerRadius,\n    showLabels,\n    labelPosition,\n    stacked,\n    smooth,\n    showSymbol,\n    symbolSize,\n    showArea,\n    min,\n    max,\n    customOptions,\n  ]);\n\n  if (!option) {\n    return (\n      <div className=\"flex items-center justify-center h-full text-muted-foreground\">\n        No data\n      </div>\n    );\n  }\n\n  return (\n    <ReactEChartsCore\n      ref={chartRefCallback}\n      echarts={echarts}\n      option={option}\n      style={{ height }}\n      className={className}\n      opts={{ renderer: \"canvas\" }}\n      notMerge={false}\n      lazyUpdate={true}\n    />\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAkEA,QAAQ,IAAI;CAEV;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CAEA;CAEA;CACD,CAAC;;;;;;AAWF,SAAS,kBAAkB,WAAyC;AAClE,SAAQ,WAAR;EACE,KAAK,UACH,QAAO;EACT,QACE,QAAO;;;;;;;AAgFb,SAAgB,UAAU,EACxB,MACA,WACA,MACA,MACA,aACA,SAAS,KACT,OACA,aAAa,MACb,cACA,QAAQ,cACR,aAAa,OACb,SAAS,MACT,UAAU,OACV,aAAa,GACb,WAAW,MACX,cAAc,GACd,aAAa,MACb,gBAAgB,WAChB,UACA,KACA,KACA,SAAS,eACT,aACiB;CAGjB,MAAM,cAAc,eADI,gBAAgB,kBAAkB,UAAU,CACjB;CACnD,MAAM,SAAS,gBAAgB;CAE/B,MAAM,KAAK,kBAAkB;CAG7B,MAAM,qBAAqB,OAAuB,KAAK;CAIvD,MAAM,mBAAmB,aAAa,SAAkC;AAEtE,MACE,mBAAmB,WACnB,CAAC,mBAAmB,QAAQ,YAAY,CAExC,oBAAmB,QAAQ,SAAS;AAItC,MAAI,KACF,oBAAmB,UAAU,KAAK,oBAAoB;OACjD;AAEL,OACE,mBAAmB,WACnB,CAAC,mBAAmB,QAAQ,YAAY,CAExC,oBAAmB,QAAQ,SAAS;AAEtC,sBAAmB,UAAU;;IAE9B,EAAE,CAAC;CAGN,MAAM,aAAa,cAEf,cAAc,YACV,qBAAqB,MAAM,MAAM,UAAU,KAAK,GAChD,mBAAmB,MAAM,MAAM,MAAM,YAAY,EACvD;EAAC;EAAM;EAAM;EAAM;EAAU;EAAa;EAAU,CACrD;CAGD,MAAM,SAAS,cAAc;EAC3B,MAAM,EAAE,OAAO,SAAS,QAAQ,WAAW,sBAAsB;AAEjE,MAAI,MAAM,WAAW,EAAG,QAAO;EAG/B,MAAM,YAAY,cAAc;EAMhC,MAAM,UAAgC;GACpC;GACA,UAJe,cAAc,aAAa,WAAW,WAAW,EAAE;GAKlE;GACA;GACA;GACA;GACA;GACA;GACD;EACD,MAAM,QAAQ,cAAc,SAAS,cAAc;EACnD,MAAM,UAAU,cAAc;EAC9B,MAAM,eACJ,CAAC,SACD,CAAC,WACD,CAAC,cACA,gBAAgB,gBACd,sBAAsB,iBACrB,CAAC,eACD,cAAc;EACpB,MAAM,eACJ,sBAAsB,gBACtB,CAAC,gBACD,CAAC,WACD,CAAC;EAGH,IAAI;AAEJ,MAAI,aAAa,eAAe,cAAc,iBAAiB,YAAY;GACzE,MAAM,cAAc;AAMpB,SAAM,mBAAmB;IACvB,GAAG;IACH,WAAW,YAAY;IACvB,aAAa,YAAY;IACzB,KAAK,OAAO,YAAY;IACxB,KAAK,OAAO,YAAY;IACxB;IACD,CAAC;aACO,QACT,OAAM,iBAAiB,SAAS,SAAS;WAChC,MACT,OAAM,eACJ,SACA,WACA,aACA,YACA,cACD;WACQ,aACT,OAAM,yBAAyB,SAAS,QAAQ;MAEhD,OAAM,qBAAqB;GACzB,GAAG;GACH;GACA;GACA;GACA;GACA;GACA;GACD,CAAC;AAIJ,SAAO,gBAAgB;GAAE,GAAG;GAAK,GAAG;GAAe,GAAG;IACrD;EACD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CAAC;AAEF,KAAI,CAAC,OACH,QACE,oBAAC;EAAI,WAAU;YAAgE;GAEzE;AAIV,QACE,oBAAC;EACC,KAAK;EACI;EACD;EACR,OAAO,EAAE,QAAQ;EACN;EACX,MAAM,EAAE,UAAU,UAAU;EAC5B,UAAU;EACV,YAAY;GACZ"}
+{"version":3,"file":"base.js","names":[],"sources":["../../../src/react/charts/base.tsx"],"sourcesContent":["// Type-only import: erased at compile time, does not pull the full echarts\n// bundle in. The `ECharts` type is used for the stored ECharts instance ref.\nimport type { ECharts } from \"echarts\";\nimport {\n  BarChart,\n  HeatmapChart,\n  LineChart,\n  PieChart,\n  RadarChart,\n  ScatterChart,\n} from \"echarts/charts\";\nimport {\n  GridComponent,\n  LegendComponent,\n  TitleComponent,\n  TooltipComponent,\n  VisualMapComponent,\n} from \"echarts/components\";\nimport * as echarts from \"echarts/core\";\nimport { LegacyGridContainLabel } from \"echarts/features\";\nimport { CanvasRenderer } from \"echarts/renderers\";\n// Import the ESM core build, not `echarts-for-react/lib/core` (CJS). The package\n// has no `exports` map, so `/lib/core` resolves to the literal CommonJS file\n// whose default export is `module.exports`; under ESM default-import interop a\n// consumer's bundler hands back the whole `{ default, __esModule }` object rather\n// than the component, so `<ReactEChartsCore/>` renders an object and React throws\n// \"Element type is invalid\". `esm/core` is real ESM with a true `export default`.\nimport ReactEChartsCore from \"echarts-for-react/esm/core\";\nimport { useCallback, useMemo, useRef } from \"react\";\nimport { normalizeChartData, normalizeHeatmapData } from \"./normalize\";\nimport {\n  applySelectionEmphasis,\n  buildCartesianOption,\n  buildHeatmapOption,\n  buildHorizontalBarOption,\n  buildPieOption,\n  buildRadarOption,\n  type OptionBuilderContext,\n} from \"./options\";\nimport { useChartUITokens, useThemeColors } from \"./theme\";\nimport type {\n  ChartBaseProps,\n  ChartClickDatum,\n  ChartColorPalette,\n  ChartData,\n  ChartType,\n  ChartValueFormatter,\n  Orientation,\n} from \"./types\";\nimport { mapToDatum } from \"./utils\";\n\n// ============================================================================\n// ECharts Registration (modular imports for tree-shaking)\n// ============================================================================\n// Only the chart types and components used by the option builders in\n// `options.ts` are registered. Importing from `echarts/core` instead of the\n// full `echarts` entry keeps unused chart types (graph, sankey, gauge, ...)\n// out of consumer bundles.\n//\n// If you add a new chart type or use a new ECharts feature (e.g. dataZoom,\n// toolbox, markLine), register it here. Consumers passing custom `options`\n// that need extra features can register them in their own app via\n// `import { use } from \"echarts/core\"`.\n//\n// Note: tooltip-driven axisPointer is bundled with `TooltipComponent`, so no\n// explicit AxisPointerComponent registration is needed.\n//\n// This `use()` call must stay co-located in the same module as `BaseChart`:\n// `package.json#sideEffects` declares JS modules side-effect free, so moving\n// registration to a separate import-for-side-effect module would let bundlers\n// drop it during tree-shaking.\necharts.use([\n  // Series types used by the option builders\n  LineChart, // line + area charts (area = line with areaStyle)\n  BarChart, // bar + horizontal bar charts\n  PieChart, // pie + donut charts\n  ScatterChart,\n  HeatmapChart,\n  RadarChart,\n  // Components referenced by built options\n  TitleComponent, // `title`\n  TooltipComponent, // `tooltip`\n  LegendComponent, // `legend`\n  GridComponent, // `grid` / `xAxis` / `yAxis`\n  VisualMapComponent, // `visualMap` (heatmap color scale)\n  // Features\n  LegacyGridContainLabel, // `grid.containLabel` (cartesian option builder)\n  // Renderer (BaseChart always renders with `renderer: \"canvas\"`)\n  CanvasRenderer,\n]);\n\n// ============================================================================\n// Palette Selection\n// ============================================================================\n\n/**\n * Determines the appropriate color palette for a chart type.\n * - Heatmaps use sequential (low → high intensity)\n * - All other charts use categorical (distinct categories)\n */\nfunction getDefaultPalette(chartType: ChartType): ChartColorPalette {\n  switch (chartType) {\n    case \"heatmap\":\n      return \"sequential\";\n    default:\n      return \"categorical\";\n  }\n}\n\n// ============================================================================\n// Component Props\n// ============================================================================\n\nexport interface BaseChartProps {\n  /** Chart data (Arrow Table or JSON array) - format is auto-detected */\n  data: ChartData;\n  /** Chart type */\n  chartType: ChartType;\n  /** X-axis field key (auto-detected from schema if not provided) */\n  xKey?: string;\n  /** Y-axis field key(s) (auto-detected from schema if not provided) */\n  yKey?: string | string[];\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Chart height in pixels @default 300 */\n  height?: number;\n  /** Chart title */\n  title?: string;\n  /** Show legend @default true */\n  showLegend?: boolean;\n  /**\n   * Color palette to use. Auto-selected based on chart type if not specified.\n   * - \"categorical\": Distinct colors for different categories (bar, pie, line)\n   * - \"sequential\": Gradient for magnitude (heatmap)\n   * - \"diverging\": Two-tone for positive/negative (correlation)\n   */\n  colorPalette?: ChartColorPalette;\n  /** Custom colors (overrides colorPalette) */\n  colors?: string[];\n  /** Show data point symbols (line/area charts) @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves (line/area charts) @default true */\n  smooth?: boolean;\n  /** Stack series @default false */\n  stacked?: boolean;\n  /** Symbol size for scatter charts @default 8 */\n  symbolSize?: number;\n  /** Show area fill for radar charts @default true */\n  showArea?: boolean;\n  /** Inner radius for pie/donut (0-100) @default 0 */\n  innerRadius?: number;\n  /** Show labels on pie/donut slices @default true */\n  showLabels?: boolean;\n  /** Label position for pie/donut @default \"outside\" */\n  labelPosition?: \"outside\" | \"inside\" | \"center\";\n  /** Y-axis field key for heatmap (the row dimension) */\n  yAxisKey?: string;\n  /** Min value for heatmap color scale */\n  min?: number;\n  /** Max value for heatmap color scale */\n  max?: number;\n  /**\n   * Additional ECharts options to merge.\n   *\n   * Only the built-in feature set is registered by this package, so options\n   * referencing extra ECharts features (`dataZoom`, `toolbox`, `markLine`,\n   * `markArea`, `graphic`, `dataset`, top-level `axisPointer`, ...) require\n   * registering them in your app via `import { use } from \"echarts/core\"`.\n   * This only works when your `echarts` resolves to the same module\n   * instance/version as this package's (the registry is a singleton;\n   * duplicate echarts copies won't share registrations).\n   */\n  options?: Record<string, unknown>;\n  /** Formats measure values. See {@link ChartBaseProps.valueFormatter}. */\n  valueFormatter?: ChartValueFormatter;\n  /** Additional CSS classes */\n  className?: string;\n  /**\n   * Fired when a data element (bar, slice, point) is clicked. Fire-and-forget:\n   * the return value is ignored (async handlers are fine — the chart never awaits).\n   * The handler receives a normalized {@link ChartClickDatum}.\n   *\n   * Pointer-only: charts render to <canvas>, so this does not fire for keyboard\n   * users. Provide a keyboard-accessible equivalent (e.g. a table row action) for\n   * the same action.\n   */\n  onDataClick?: (datum: ChartClickDatum) => void;\n  /** Controlled selection by category name. See {@link ChartBaseProps.selected}. */\n  selected?: string | string[];\n}\n\n// ============================================================================\n// Base Chart Component\n// ============================================================================\n\n/**\n * Base chart component that handles both Arrow and JSON data.\n * Renders using ECharts for consistent output across both formats.\n */\nexport function BaseChart({\n  data,\n  chartType,\n  xKey,\n  yKey,\n  orientation,\n  height = 300,\n  title,\n  showLegend = true,\n  colorPalette,\n  colors: customColors,\n  showSymbol = false,\n  smooth = true,\n  stacked = false,\n  symbolSize = 8,\n  showArea = true,\n  innerRadius = 0,\n  showLabels = true,\n  labelPosition = \"outside\",\n  yAxisKey,\n  min,\n  max,\n  options: customOptions,\n  valueFormatter,\n  className,\n  onDataClick,\n  selected,\n}: BaseChartProps) {\n  // Determine the appropriate color palette based on chart type\n  const resolvedPalette = colorPalette ?? getDefaultPalette(chartType);\n  const themeColors = useThemeColors(resolvedPalette);\n  const colors = customColors ?? themeColors;\n\n  const ui = useChartUITokens();\n\n  // Handler presence enables line interaction and gates events. Tracking the\n  // boolean keeps inline handler identities from rebuilding chart options.\n  const interactive = !!onDataClick;\n\n  // Keep the latest handler in a ref so `onEvents` can call the current\n  // `onDataClick` without listing it as a dependency (see `onEvents` below).\n  const onDataClickRef = useRef(onDataClick);\n  onDataClickRef.current = onDataClick;\n\n  // Store ECharts instance directly to avoid stale ref issues on unmount\n  const echartsInstanceRef = useRef<ECharts | null>(null);\n\n  // Callback ref pattern: captures the ECharts instance when ReactECharts mounts\n  // This ensures we always have a stable reference to the actual instance\n  const chartRefCallback = useCallback((node: ReactEChartsCore | null) => {\n    // Dispose previous instance if component is being replaced\n    if (\n      echartsInstanceRef.current &&\n      !echartsInstanceRef.current.isDisposed()\n    ) {\n      echartsInstanceRef.current.dispose();\n    }\n\n    // Store the new instance\n    if (node) {\n      echartsInstanceRef.current = node.getEchartsInstance();\n    } else {\n      // Component unmounting - dispose the stored instance\n      if (\n        echartsInstanceRef.current &&\n        !echartsInstanceRef.current.isDisposed()\n      ) {\n        echartsInstanceRef.current.dispose();\n      }\n      echartsInstanceRef.current = null;\n    }\n  }, []);\n\n  // Memoize data normalization\n  const normalized = useMemo(\n    () =>\n      chartType === \"heatmap\"\n        ? normalizeHeatmapData(data, xKey, yAxisKey, yKey)\n        : normalizeChartData(data, xKey, yKey, orientation),\n    [data, xKey, yKey, yAxisKey, orientation, chartType],\n  );\n\n  // Memoize option building\n  const option = useMemo(() => {\n    const { xData, yFields, xField, chartType: detectedChartType } = normalized;\n\n    if (xData.length === 0) return null;\n\n    // Determine chart mode first (needed to handle yDataMap)\n    const isHeatmap = chartType === \"heatmap\";\n\n    // Heatmaps use heatmapData instead of yDataMap\n    // For other charts, yDataMap is required\n    const yDataMap = \"yDataMap\" in normalized ? normalized.yDataMap : {};\n\n    const baseCtx: OptionBuilderContext = {\n      xData,\n      yDataMap,\n      yFields,\n      colors,\n      title,\n      showLegend,\n      xField,\n      ui,\n      valueFormatter,\n    };\n    const isPie = chartType === \"pie\" || chartType === \"donut\";\n    const isRadar = chartType === \"radar\";\n    const isHorizontal =\n      !isPie &&\n      !isRadar &&\n      !isHeatmap &&\n      (orientation === \"horizontal\" ||\n        (detectedChartType === \"categorical\" &&\n          !orientation &&\n          chartType === \"bar\"));\n    const isTimeSeries =\n      detectedChartType === \"timeseries\" &&\n      !isHorizontal &&\n      !isRadar &&\n      !isHeatmap;\n\n    // Build option based on chart type\n    let opt: Record<string, unknown>;\n\n    if (isHeatmap && \"yAxisData\" in normalized && \"heatmapData\" in normalized) {\n      const heatmapNorm = normalized as {\n        yAxisData: (string | number)[];\n        heatmapData: [number, number, number][];\n        min: number;\n        max: number;\n      } & typeof normalized;\n      opt = buildHeatmapOption({\n        ...baseCtx,\n        yAxisData: heatmapNorm.yAxisData,\n        heatmapData: heatmapNorm.heatmapData,\n        min: min ?? heatmapNorm.min,\n        max: max ?? heatmapNorm.max,\n        showLabels,\n      });\n    } else if (isRadar) {\n      opt = buildRadarOption(baseCtx, showArea);\n    } else if (isPie) {\n      opt = buildPieOption(\n        baseCtx,\n        chartType as \"pie\" | \"donut\",\n        innerRadius,\n        showLabels,\n        labelPosition,\n      );\n    } else if (isHorizontal) {\n      opt = buildHorizontalBarOption(baseCtx, stacked);\n    } else {\n      opt = buildCartesianOption({\n        ...baseCtx,\n        chartType,\n        isTimeSeries,\n        stacked,\n        smooth,\n        showSymbol,\n        symbolSize,\n        interactive,\n      });\n    }\n\n    // Apply selection after custom options; empty selection is a no-op.\n    const merged = customOptions ? { ...opt, ...customOptions } : opt;\n    return applySelectionEmphasis(merged, selected);\n  }, [\n    normalized,\n    colors,\n    ui,\n    title,\n    showLegend,\n    chartType,\n    orientation,\n    innerRadius,\n    showLabels,\n    labelPosition,\n    stacked,\n    smooth,\n    showSymbol,\n    symbolSize,\n    showArea,\n    min,\n    max,\n    customOptions,\n    valueFormatter,\n    selected,\n    interactive,\n  ]);\n\n  // Heatmap data uses axis indexes; preserve labels for click results instead\n  // of exposing those raw positions.\n  const axisLabels = useMemo(\n    () => ({\n      xLabels: normalized.xData,\n      yLabels:\n        \"yAxisData\" in normalized\n          ? (normalized.yAxisData as (string | number)[])\n          : undefined,\n    }),\n    [normalized],\n  );\n\n  // `onEvents` must not re-subscribe when the data changes (e.g. each SSE tick).\n  const axisLabelsRef = useRef(axisLabels);\n  axisLabelsRef.current = axisLabels;\n\n  // Memoize by handler presence because echarts-for-react re-subscribes whenever\n  // `onEvents` changes, while callers commonly pass a new inline callback on\n  // every render. This also avoids churn during frequently changing data such\n  // as SSE ticks.\n  const onEvents = useMemo(\n    () =>\n      interactive\n        ? {\n            click: (params: unknown, instance: ECharts) => {\n              const result = onDataClickRef.current?.(\n                mapToDatum(params, axisLabelsRef.current, instance),\n              ) as void | Promise<void>;\n              if (\n                result &&\n                typeof (result as Promise<void>).then === \"function\"\n              ) {\n                (result as Promise<void>).catch(() => {});\n              }\n            },\n          }\n        : undefined,\n    [interactive],\n  );\n\n  if (!option) {\n    return (\n      <div className=\"flex items-center justify-center h-full text-muted-foreground\">\n        No data\n      </div>\n    );\n  }\n\n  return (\n    <ReactEChartsCore\n      ref={chartRefCallback}\n      echarts={echarts}\n      option={option}\n      style={{ height }}\n      className={className}\n      opts={{ renderer: \"canvas\" }}\n      notMerge={false}\n      lazyUpdate={true}\n      onEvents={onEvents}\n    />\n  );\n}\n"],"mappings":"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"}

package/dist/react/charts/index.d.ts

@@ -1,5 +1,6 @@
 import { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS } from "../../js/constants.js";
-import { AreaChartProps, AreaChartSpecificProps, BarChartProps, BarChartSpecificProps, ChartBaseProps, ChartColorPalette, ChartData, ChartType, ChartUITokens, DataFormat, DataProps, DonutChartProps, HeatmapChartProps, HeatmapChartSpecificProps, LineChartProps, LineChartSpecificProps, NormalizedChartData, NormalizedChartDataBase, Orientation, PieChartProps, PieChartSpecificProps, QueryProps, RadarChartProps, RadarChartSpecificProps, ScatterChartProps, ScatterChartSpecificProps, UnifiedChartProps, isArrowTable, isDataProps, isQueryProps } from "./types.js";
+import { formatLabel } from "../../js/format/index.js";
+import { AreaChartProps, AreaChartSpecificProps, BarChartProps, BarChartSpecificProps, ChartBaseProps, ChartClickDatum, ChartColorPalette, ChartData, ChartType, ChartUITokens, ChartValueFormatter, DataFormat, DataProps, DonutChartProps, HeatmapChartProps, HeatmapChartSpecificProps, LineChartProps, LineChartSpecificProps, NormalizedChartData, NormalizedChartDataBase, Orientation, PieChartProps, PieChartSpecificProps, QueryProps, RadarChartProps, RadarChartSpecificProps, ScatterChartProps, ScatterChartSpecificProps, UnifiedChartProps, isArrowTable, isDataProps, isQueryProps } from "./types.js";
 import { AreaChart } from "./area/index.js";
 import { BarChart } from "./bar/index.js";
 import { HeatmapChart } from "./heatmap/index.js";
@@ -15,5 +16,5 @@ import { ChartWrapper, ChartWrapperProps } from "./wrapper.js";
 import { NormalizedHeatmapData, normalizeChartData, normalizeHeatmapData } from "./normalize.js";
 import { CHART_COLOR_VARS, CHART_COLOR_VARS_CATEGORICAL, CHART_COLOR_VARS_DIVERGING, CHART_COLOR_VARS_SEQUENTIAL, FALLBACK_COLORS_CATEGORICAL, FALLBACK_COLORS_DIVERGING, FALLBACK_COLORS_SEQUENTIAL } from "./constants.js";
 import { useAllThemeColors, useChartUITokens, useThemeColors } from "./theme.js";
-import { createTimeSeriesData, formatLabel, sortTimeSeriesAscending, toChartArray, toChartValue, truncateLabel } from "./utils.js";
-import { CartesianContext, HeatmapContext, OptionBuilderContext, buildCartesianOption, buildHeatmapOption, buildHorizontalBarOption, buildPieOption, buildRadarOption } from "./options.js";
+import { createTimeSeriesData, sortTimeSeriesAscending, toChartArray, toChartValue, truncateLabel } from "./utils.js";
+import { CartesianContext, HeatmapContext, OptionBuilderContext, applySelectionEmphasis, buildCartesianOption, buildHeatmapOption, buildHorizontalBarOption, buildPieOption, buildRadarOption } from "./options.js";

package/dist/react/charts/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","names":[],"sources":["../../../src/react/charts/normalize.ts"],"mappings":";;;;;AA2NA;;iBAAgB,kBAAA,CACd,IAAA,EAAM,SAAA,EACN,IAAA,WACA,IAAA,sBACA,WAAA,GAAc,WAAA,GACb,mBAAA;;;;;;UAiGc,qBAAA,SAA8B,uBAAA;EArG7C;EAuGA,SAAA;EArGA;EAuGA,WAAA;EAtGA;EAwGA,GAAA;EAvGoB;EAyGpB,GAAA;AAAA;;;;;;;;;;iBAYc,oBAAA,CACd,IAAA,EAAM,SAAA,EACN,IAAA,WACA,QAAA,WACA,QAAA,uBACC,qBAAA"}
+{"version":3,"file":"normalize.d.ts","names":[],"sources":["../../../src/react/charts/normalize.ts"],"mappings":";;;;;AA4NA;;iBAAgB,kBAAA,CACd,IAAA,EAAM,SAAA,EACN,IAAA,WACA,IAAA,sBACA,WAAA,GAAc,WAAA,GACb,mBAAA;;;;;;UAiGc,qBAAA,SAA8B,uBAAA;EArG7C;EAuGA,SAAA;EArGA;EAuGA,WAAA;EAtGA;EAwGA,GAAA;EAvGoB;EAyGpB,GAAA;AAAA;;;;;;;;;;iBAYc,oBAAA,CACd,IAAA,EAAM,SAAA,EACN,IAAA,WACA,QAAA,WACA,QAAA,uBACC,qBAAA"}