@databricks/appkit-ui 0.57.0 → 0.59.0

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

@@ -16,6 +16,8 @@ type Orientation = "vertical" | "horizontal";
 type ChartType = "bar" | "line" | "area" | "pie" | "donut" | "scatter" | "radar" | "heatmap";
 /** Data that can be passed to unified charts */
 type ChartData = Table | Record<string, unknown>[];
+/** Formats a measure value for chart axes, tooltips, and value labels. */
+type ChartValueFormatter = (value: string | number, field: string) => string;
 /** Color palette types for different visualization needs */
 type ChartColorPalette = "categorical" | "sequential" | "diverging";
 /** Resolved colors for the chart UI — axis text, titles, grid lines, and tooltip. */
@@ -58,6 +60,57 @@ interface ChartBaseProps {
   testId?: string;
   /** Additional ECharts options to merge */
   options?: Record<string, unknown>;
+  /**
+   * Formats measure values in the chart's built-in value axes, tooltips, and
+   * value labels. `field` is the corresponding `yKey`, so one formatter can
+   * select a different format for each series.
+   *
+   * For charts with multiple series on one value axis, axis ticks use the
+   * first `yKey`; each tooltip uses its own series field.
+   */
+  valueFormatter?: ChartValueFormatter;
+  /**
+   * 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. Matching data element(s) render at full
+   * prominence while the rest are dimmed. Drive it from your own state to reflect a
+   * cross-filter or selection. Categorical charts (bar, pie/donut) show emphasis;
+   * other chart types ignore it.
+   */
+  selected?: string | string[];
+}
+/**
+ * A normalized description of a clicked chart element.
+ *
+ * In the common cross-filter case, {@link ChartClickDatum.name} carries the
+ * dimension value of the clicked element.
+ */
+interface ChartClickDatum {
+  /** Category label of the clicked element — the dimension value in the common cross-filter case. */
+  name: string;
+  /**
+   * The datum's scalar value:
+   * - bar / pie — the datum itself.
+   * - time-series / scatter — the y-component of the `[x, y]` point (see
+   *   {@link ChartClickDatum.x} / {@link ChartClickDatum.y}).
+   * - heatmap — the cell value (the third entry of ECharts'
+   *   `[xIndex, yIndex, value]` triple), *not* an axis index.
+   * - radar — `null`; the item holds one value per indicator, so there is no
+   *   single scalar to report. Read the vector from {@link ChartClickDatum.raw}.
+   *
+   * `null` whenever there is no scalar value to surface.
+   */
+  value: number | string | null;
+  x?: number | string;
+  y?: number | string;
+  seriesName?: string;
+  dataIndex: number;
+  seriesIndex: number;
+  raw: unknown;
 }
 /** Props for query-based data fetching */
 interface QueryProps extends ChartBaseProps {
@@ -174,5 +227,5 @@ declare function isQueryProps(props: UnifiedChartProps): props is QueryProps;
 /** Type guard to check if props are data-based */
 declare function isDataProps(props: UnifiedChartProps): props is DataProps;
 //#endregion
-export { 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 };
+export { 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 };
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/charts/types.ts"],"mappings":";;;;;AAcA;;;;;AAUA;KAVY,UAAA;;KAUA,WAAA;;KAGA,SAAA;AAWZ;AAAA,KAAY,SAAA,GAAY,KAAA,GAAQ,MAAA;;KAOpB,iBAAA;;UAGK,aAAA;EAHY;EAK3B,SAAA;EAL2B;EAO3B,SAAA;EAJe;EAMf,IAAA;;EAEA,SAAA;AAAA;;UAIe,cAAA;EAJf;EAMA,KAAA;EANS;EAQT,UAAA;EAJ6B;;;;;;EAW7B,YAAA,GAAe,iBAAA;EAEf;EAAA,MAAA;EAIA;EAFA,MAAA;EAOA;EALA,SAAA;EAUA;EAPA,IAAA;EAUU;EARV,IAAA;EAQgB;EALhB,SAAA;EAa0B;EAX1B,MAAA;EAea;EAZb,OAAA,GAAU,MAAA;AAAA;;UAQK,UAAA,SAAmB,cAAA;EAAc;EAEhD,QAAA;EAFkC;EAIlC,UAAA,GAAa,MAAA;EAAb;;;;;;;EAQA,MAAA,GAAS,UAAA;EAEqB;EAA9B,WAAA,OAAkB,IAAA,EAAM,CAAA,KAAM,CAAA;EAE9B,IAAA;AAAA;AAQF;AAAA,UAAiB,SAAA,SAAkB,cAAA;;EAEjC,IAAA,EAAM,SAAA;EAGN,QAAA;EACA,UAAA;EACA,MAAA;EACA,WAAA;AAAA;;KAQU,iBAAA,GAAoB,UAAA,GAAa,SAAA;;UAO5B,qBAAA;EAPL;EASV,WAAA,GAAc,WAAA;;EAEd,OAAA;AAAA;AAJF;AAAA,UAQiB,sBAAA;;EAEf,WAAA,GAAc,WAAA;EARd;EAUA,UAAA;EARA;EAUA,MAAA;AAAA;AANF;AAAA,UAUiB,sBAAA;;EAEf,WAAA,GAAc,WAAA;EAVd;EAYA,UAAA;EAVA;EAYA,MAAA;EAVM;EAYN,OAAA;AAAA;;UAIe,yBAAA;EAVU;EAYzB,UAAA;AAAA;;UAIe,qBAAA;EAVf;EAYA,WAAA;EAZO;EAcP,UAAA;EAVwC;EAYxC,aAAA;AAAA;;UAIe,uBAAA;EAVqB;EAYpC,QAAA;AAAA;;UAIe,yBAAA;EAVf;;;AAIF;EAWE,QAAA;;EAEA,GAAA;EAXQ;EAaR,GAAA;EATwC;EAWxC,UAAA;AAAA;AAAA,KAOU,aAAA,IAAiB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC3C,cAAA,IAAkB,UAAA,GAAa,SAAA,IAAa,sBAAA;AAAA,KAC5C,cAAA,IAAkB,UAAA,GAAa,SAAA,IAAa,sBAAA;AAAA,KAC5C,iBAAA,IAAqB,UAAA,GAAa,SAAA,IAC5C,yBAAA;AAAA,KACU,aAAA,IAAiB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC3C,eAAA,IAAmB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC7C,eAAA,IAAmB,UAAA,GAAa,SAAA,IAC1C,uBAAA;AAAA,KACU,iBAAA,IAAqB,UAAA,GAAa,SAAA,IAC5C,yBAAA;;UAOe,uBAAA;EACf,KAAA;EACA,MAAA;EACA,OAAA;EACA,SAAA;AAAA;;UAIe,mBAAA,SAA4B,uBAAA;EAC3C,QAAA,EAAU,MAAA;AAAA;AAzBZ;AAAA,iBA6BgB,YAAA,CAAa,IAAA,EAAM,SAAA,GAAY,IAAA,IAAQ,KAAA;;iBAWvC,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,UAAA;;iBASjD,WAAA,CAAY,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,SAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/charts/types.ts"],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../src/react/charts/types.ts"],"sourcesContent":["import type { Table } from \"apache-arrow\";\n\n// ============================================================================\n// Data Format Types\n// ============================================================================\n\n/**\n * Supported data formats for analytics queries.\n *\n * \"json\" and \"arrow\" are legacy aliases kept for backwards compatibility\n * with appkit-ui < 0.33.0 — safe to remove once no consumer is on a\n * pre-0.33.0 version. resolveFormat() normalizes them to their canonical\n * equivalents before any downstream code reads the value.\n */\nexport type DataFormat =\n  | \"json_array\"\n  | \"arrow_stream\"\n  | \"auto\"\n  /** @deprecated Use \"json_array\". Safe to remove once no consumer is on appkit-ui < 0.33.0. */\n  | \"json\"\n  /** @deprecated Use \"arrow_stream\". Safe to remove once no consumer is on appkit-ui < 0.33.0. */\n  | \"arrow\";\n\n/** Chart orientation */\nexport type Orientation = \"vertical\" | \"horizontal\";\n\n/** Supported chart types */\nexport type ChartType =\n  | \"bar\"\n  | \"line\"\n  | \"area\"\n  | \"pie\"\n  | \"donut\"\n  | \"scatter\"\n  | \"radar\"\n  | \"heatmap\";\n\n/** Data that can be passed to unified charts */\nexport type ChartData = Table | Record<string, unknown>[];\n\n// ============================================================================\n// Base Props (shared by all charts)\n// ============================================================================\n\n/** Color palette types for different visualization needs */\nexport type ChartColorPalette = \"categorical\" | \"sequential\" | \"diverging\";\n\n/** Resolved colors for the chart UI — axis text, titles, grid lines, and tooltip. */\nexport interface ChartUITokens {\n  /** Axis tick labels (≈ `--muted-foreground`) */\n  axisLabel: string;\n  /** Axis names, legend, title, and visualMap text (≈ `--foreground`) */\n  axisTitle: string;\n  /** Axis, tick, and split (grid) lines (≈ `--border`) */\n  grid: string;\n  /** Tooltip popover background (≈ `--popover`) */\n  tooltipBg: string;\n}\n\n/** Common visual and behavior props for all charts */\nexport interface ChartBaseProps {\n  /** Chart title */\n  title?: string;\n  /** Show legend */\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/intensity (heatmap)\n   * - \"diverging\": Two-tone for positive/negative values\n   */\n  colorPalette?: ChartColorPalette;\n  /** Custom colors for series (overrides colorPalette) */\n  colors?: string[];\n  /** Chart height in pixels @default 300 */\n  height?: number;\n  /** Additional CSS classes */\n  className?: string;\n\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\n  /** Accessibility label for screen readers */\n  ariaLabel?: string;\n  /** Test ID for automated testing */\n  testId?: string;\n\n  /** Additional ECharts options to merge */\n  options?: Record<string, unknown>;\n}\n\n// ============================================================================\n// Query-based Props (chart fetches data)\n// ============================================================================\n\n/** Props for query-based data fetching */\nexport interface QueryProps extends ChartBaseProps {\n  /** Analytics query key registered with analytics plugin */\n  queryKey: string;\n  /** Query parameters passed to the analytics endpoint */\n  parameters?: Record<string, unknown>;\n  /**\n   * Data format to use\n   * - \"json_array\": Use JSON format (smaller payloads, simpler)\n   * - \"arrow_stream\": Use Arrow format (faster for large datasets)\n   * - \"auto\": Automatically select based on expected data size\n   * @default \"auto\"\n   */\n  format?: DataFormat;\n  /** Transform raw data before rendering */\n  transformer?: <T>(data: T) => T;\n  // Discriminator: cannot use direct data with query\n  data?: never;\n}\n\n// ============================================================================\n// Data-based Props (chart receives data externally)\n// ============================================================================\n\n/** Props for direct data injection */\nexport interface DataProps extends ChartBaseProps {\n  /** Arrow Table or JSON array */\n  data: ChartData;\n\n  // Discriminator: cannot use query props with direct data\n  queryKey?: never;\n  parameters?: never;\n  format?: never;\n  transformer?: never;\n}\n\n// ============================================================================\n// Union Types for Each Chart\n// ============================================================================\n\n/** Base union type - either query-based or data-based */\nexport type UnifiedChartProps = QueryProps | DataProps;\n\n// ============================================================================\n// Chart-Specific Props\n// ============================================================================\n\n/** Props specific to bar charts */\nexport interface BarChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Stack bars */\n  stacked?: boolean;\n}\n\n/** Props specific to line charts */\nexport interface LineChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n}\n\n/** Props specific to area charts */\nexport interface AreaChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n  /** Stack areas @default false */\n  stacked?: boolean;\n}\n\n/** Props specific to scatter charts */\nexport interface ScatterChartSpecificProps {\n  /** Symbol size @default 8 */\n  symbolSize?: number;\n}\n\n/** Props specific to pie/donut charts */\nexport interface PieChartSpecificProps {\n  /** Inner radius for donut charts (0-100%) @default 0 */\n  innerRadius?: number;\n  /** Show labels on slices @default true */\n  showLabels?: boolean;\n  /** Label position @default \"outside\" */\n  labelPosition?: \"outside\" | \"inside\" | \"center\";\n}\n\n/** Props specific to radar charts */\nexport interface RadarChartSpecificProps {\n  /** Show area fill @default true */\n  showArea?: boolean;\n}\n\n/** Props specific to heatmap charts */\nexport interface HeatmapChartSpecificProps {\n  /**\n   * Field key for the Y-axis categories.\n   * For heatmaps, data should have: xKey (column), yAxisKey (row), and yKey (value).\n   */\n  yAxisKey?: string;\n  /** Min value for color scale (auto-detected if not provided) */\n  min?: number;\n  /** Max value for color scale (auto-detected if not provided) */\n  max?: number;\n  /** Show value labels on cells @default false */\n  showLabels?: boolean;\n}\n\n// ============================================================================\n// Complete Chart Props (union + specific)\n// ============================================================================\n\nexport type BarChartProps = (QueryProps | DataProps) & BarChartSpecificProps;\nexport type LineChartProps = (QueryProps | DataProps) & LineChartSpecificProps;\nexport type AreaChartProps = (QueryProps | DataProps) & AreaChartSpecificProps;\nexport type ScatterChartProps = (QueryProps | DataProps) &\n  ScatterChartSpecificProps;\nexport type PieChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type DonutChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type RadarChartProps = (QueryProps | DataProps) &\n  RadarChartSpecificProps;\nexport type HeatmapChartProps = (QueryProps | DataProps) &\n  HeatmapChartSpecificProps;\n\n// ============================================================================\n// Internal Types\n// ============================================================================\n\n/** Base normalized data shared by all chart types */\nexport interface NormalizedChartDataBase {\n  xData: (string | number)[];\n  xField: string;\n  yFields: string[];\n  chartType: \"timeseries\" | \"categorical\";\n}\n\n/** Normalized chart data for rendering (standard charts) */\nexport interface NormalizedChartData extends NormalizedChartDataBase {\n  yDataMap: Record<string, (string | number)[]>;\n}\n\n/** Type guard to check if data is an Arrow Table */\nexport function isArrowTable(data: ChartData): data is Table {\n  return (\n    data !== null &&\n    typeof data === \"object\" &&\n    \"schema\" in data &&\n    \"numRows\" in data &&\n    typeof (data as Table).getChild === \"function\"\n  );\n}\n\n/** Type guard to check if props are query-based */\nexport function isQueryProps(props: UnifiedChartProps): props is QueryProps {\n  return (\n    \"queryKey\" in props &&\n    typeof props.queryKey === \"string\" &&\n    props.queryKey.length > 0\n  );\n}\n\n/** Type guard to check if props are data-based */\nexport function isDataProps(props: UnifiedChartProps): props is DataProps {\n  return \"data\" in props && props.data != null;\n}\n"],"mappings":";;AAqPA,SAAgB,aAAa,MAAgC;AAC3D,QACE,SAAS,QACT,OAAO,SAAS,YAChB,YAAY,QACZ,aAAa,QACb,OAAQ,KAAe,aAAa;;;AAKxC,SAAgB,aAAa,OAA+C;AAC1E,QACE,cAAc,SACd,OAAO,MAAM,aAAa,YAC1B,MAAM,SAAS,SAAS;;;AAK5B,SAAgB,YAAY,OAA8C;AACxE,QAAO,UAAU,SAAS,MAAM,QAAQ"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/react/charts/types.ts"],"sourcesContent":["import type { Table } from \"apache-arrow\";\n\n// ============================================================================\n// Data Format Types\n// ============================================================================\n\n/**\n * Supported data formats for analytics queries.\n *\n * \"json\" and \"arrow\" are legacy aliases kept for backwards compatibility\n * with appkit-ui < 0.33.0 — safe to remove once no consumer is on a\n * pre-0.33.0 version. resolveFormat() normalizes them to their canonical\n * equivalents before any downstream code reads the value.\n */\nexport type DataFormat =\n  | \"json_array\"\n  | \"arrow_stream\"\n  | \"auto\"\n  /** @deprecated Use \"json_array\". Safe to remove once no consumer is on appkit-ui < 0.33.0. */\n  | \"json\"\n  /** @deprecated Use \"arrow_stream\". Safe to remove once no consumer is on appkit-ui < 0.33.0. */\n  | \"arrow\";\n\n/** Chart orientation */\nexport type Orientation = \"vertical\" | \"horizontal\";\n\n/** Supported chart types */\nexport type ChartType =\n  | \"bar\"\n  | \"line\"\n  | \"area\"\n  | \"pie\"\n  | \"donut\"\n  | \"scatter\"\n  | \"radar\"\n  | \"heatmap\";\n\n/** Data that can be passed to unified charts */\nexport type ChartData = Table | Record<string, unknown>[];\n\n/** Formats a measure value for chart axes, tooltips, and value labels. */\nexport type ChartValueFormatter = (\n  value: string | number,\n  field: string,\n) => string;\n\n// ============================================================================\n// Base Props (shared by all charts)\n// ============================================================================\n\n/** Color palette types for different visualization needs */\nexport type ChartColorPalette = \"categorical\" | \"sequential\" | \"diverging\";\n\n/** Resolved colors for the chart UI — axis text, titles, grid lines, and tooltip. */\nexport interface ChartUITokens {\n  /** Axis tick labels (≈ `--muted-foreground`) */\n  axisLabel: string;\n  /** Axis names, legend, title, and visualMap text (≈ `--foreground`) */\n  axisTitle: string;\n  /** Axis, tick, and split (grid) lines (≈ `--border`) */\n  grid: string;\n  /** Tooltip popover background (≈ `--popover`) */\n  tooltipBg: string;\n}\n\n/** Common visual and behavior props for all charts */\nexport interface ChartBaseProps {\n  /** Chart title */\n  title?: string;\n  /** Show legend */\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/intensity (heatmap)\n   * - \"diverging\": Two-tone for positive/negative values\n   */\n  colorPalette?: ChartColorPalette;\n  /** Custom colors for series (overrides colorPalette) */\n  colors?: string[];\n  /** Chart height in pixels @default 300 */\n  height?: number;\n  /** Additional CSS classes */\n  className?: string;\n\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\n  /** Accessibility label for screen readers */\n  ariaLabel?: string;\n  /** Test ID for automated testing */\n  testId?: string;\n\n  /** Additional ECharts options to merge */\n  options?: Record<string, unknown>;\n\n  /**\n   * Formats measure values in the chart's built-in value axes, tooltips, and\n   * value labels. `field` is the corresponding `yKey`, so one formatter can\n   * select a different format for each series.\n   *\n   * For charts with multiple series on one value axis, axis ticks use the\n   * first `yKey`; each tooltip uses its own series field.\n   */\n  valueFormatter?: ChartValueFormatter;\n\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\n  /**\n   * Controlled selection by category name. Matching data element(s) render at full\n   * prominence while the rest are dimmed. Drive it from your own state to reflect a\n   * cross-filter or selection. Categorical charts (bar, pie/donut) show emphasis;\n   * other chart types ignore it.\n   */\n  selected?: string | string[];\n}\n\n// ============================================================================\n// Interaction / Click Events\n// ============================================================================\n\n/**\n * A normalized description of a clicked chart element.\n *\n * In the common cross-filter case, {@link ChartClickDatum.name} carries the\n * dimension value of the clicked element.\n */\nexport interface ChartClickDatum {\n  /** Category label of the clicked element — the dimension value in the common cross-filter case. */\n  name: string;\n  /**\n   * The datum's scalar value:\n   * - bar / pie — the datum itself.\n   * - time-series / scatter — the y-component of the `[x, y]` point (see\n   *   {@link ChartClickDatum.x} / {@link ChartClickDatum.y}).\n   * - heatmap — the cell value (the third entry of ECharts'\n   *   `[xIndex, yIndex, value]` triple), *not* an axis index.\n   * - radar — `null`; the item holds one value per indicator, so there is no\n   *   single scalar to report. Read the vector from {@link ChartClickDatum.raw}.\n   *\n   * `null` whenever there is no scalar value to surface.\n   */\n  value: number | string | null;\n  x?: number | string;\n  y?: number | string;\n  seriesName?: string;\n  dataIndex: number;\n  seriesIndex: number;\n  // Untouched ECharts event params.\n  raw: unknown;\n}\n\n// ============================================================================\n// Query-based Props (chart fetches data)\n// ============================================================================\n\n/** Props for query-based data fetching */\nexport interface QueryProps extends ChartBaseProps {\n  /** Analytics query key registered with analytics plugin */\n  queryKey: string;\n  /** Query parameters passed to the analytics endpoint */\n  parameters?: Record<string, unknown>;\n  /**\n   * Data format to use\n   * - \"json_array\": Use JSON format (smaller payloads, simpler)\n   * - \"arrow_stream\": Use Arrow format (faster for large datasets)\n   * - \"auto\": Automatically select based on expected data size\n   * @default \"auto\"\n   */\n  format?: DataFormat;\n  /** Transform raw data before rendering */\n  transformer?: <T>(data: T) => T;\n  // Discriminator: cannot use direct data with query\n  data?: never;\n}\n\n// ============================================================================\n// Data-based Props (chart receives data externally)\n// ============================================================================\n\n/** Props for direct data injection */\nexport interface DataProps extends ChartBaseProps {\n  /** Arrow Table or JSON array */\n  data: ChartData;\n\n  // Discriminator: cannot use query props with direct data\n  queryKey?: never;\n  parameters?: never;\n  format?: never;\n  transformer?: never;\n}\n\n// ============================================================================\n// Union Types for Each Chart\n// ============================================================================\n\n/** Base union type - either query-based or data-based */\nexport type UnifiedChartProps = QueryProps | DataProps;\n\n// ============================================================================\n// Chart-Specific Props\n// ============================================================================\n\n/** Props specific to bar charts */\nexport interface BarChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Stack bars */\n  stacked?: boolean;\n}\n\n/** Props specific to line charts */\nexport interface LineChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n}\n\n/** Props specific to area charts */\nexport interface AreaChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n  /** Stack areas @default false */\n  stacked?: boolean;\n}\n\n/** Props specific to scatter charts */\nexport interface ScatterChartSpecificProps {\n  /** Symbol size @default 8 */\n  symbolSize?: number;\n}\n\n/** Props specific to pie/donut charts */\nexport interface PieChartSpecificProps {\n  /** Inner radius for donut charts (0-100%) @default 0 */\n  innerRadius?: number;\n  /** Show labels on slices @default true */\n  showLabels?: boolean;\n  /** Label position @default \"outside\" */\n  labelPosition?: \"outside\" | \"inside\" | \"center\";\n}\n\n/** Props specific to radar charts */\nexport interface RadarChartSpecificProps {\n  /** Show area fill @default true */\n  showArea?: boolean;\n}\n\n/** Props specific to heatmap charts */\nexport interface HeatmapChartSpecificProps {\n  /**\n   * Field key for the Y-axis categories.\n   * For heatmaps, data should have: xKey (column), yAxisKey (row), and yKey (value).\n   */\n  yAxisKey?: string;\n  /** Min value for color scale (auto-detected if not provided) */\n  min?: number;\n  /** Max value for color scale (auto-detected if not provided) */\n  max?: number;\n  /** Show value labels on cells @default false */\n  showLabels?: boolean;\n}\n\n// ============================================================================\n// Complete Chart Props (union + specific)\n// ============================================================================\n\nexport type BarChartProps = (QueryProps | DataProps) & BarChartSpecificProps;\nexport type LineChartProps = (QueryProps | DataProps) & LineChartSpecificProps;\nexport type AreaChartProps = (QueryProps | DataProps) & AreaChartSpecificProps;\nexport type ScatterChartProps = (QueryProps | DataProps) &\n  ScatterChartSpecificProps;\nexport type PieChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type DonutChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type RadarChartProps = (QueryProps | DataProps) &\n  RadarChartSpecificProps;\nexport type HeatmapChartProps = (QueryProps | DataProps) &\n  HeatmapChartSpecificProps;\n\n// ============================================================================\n// Internal Types\n// ============================================================================\n\n/** Base normalized data shared by all chart types */\nexport interface NormalizedChartDataBase {\n  xData: (string | number)[];\n  xField: string;\n  yFields: string[];\n  chartType: \"timeseries\" | \"categorical\";\n}\n\n/** Normalized chart data for rendering (standard charts) */\nexport interface NormalizedChartData extends NormalizedChartDataBase {\n  yDataMap: Record<string, (string | number)[]>;\n}\n\n/** Type guard to check if data is an Arrow Table */\nexport function isArrowTable(data: ChartData): data is Table {\n  return (\n    data !== null &&\n    typeof data === \"object\" &&\n    \"schema\" in data &&\n    \"numRows\" in data &&\n    typeof (data as Table).getChild === \"function\"\n  );\n}\n\n/** Type guard to check if props are query-based */\nexport function isQueryProps(props: UnifiedChartProps): props is QueryProps {\n  return (\n    \"queryKey\" in props &&\n    typeof props.queryKey === \"string\" &&\n    props.queryKey.length > 0\n  );\n}\n\n/** Type guard to check if props are data-based */\nexport function isDataProps(props: UnifiedChartProps): props is DataProps {\n  return \"data\" in props && props.data != null;\n}\n"],"mappings":";;AAuTA,SAAgB,aAAa,MAAgC;AAC3D,QACE,SAAS,QACT,OAAO,SAAS,YAChB,YAAY,QACZ,aAAa,QACb,OAAQ,KAAe,aAAa;;;AAKxC,SAAgB,aAAa,OAA+C;AAC1E,QACE,cAAc,SACd,OAAO,MAAM,aAAa,YAC1B,MAAM,SAAS,SAAS;;;AAK5B,SAAgB,YAAY,OAA8C;AACxE,QAAO,UAAU,SAAS,MAAM,QAAQ"}

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

@@ -1,3 +1,7 @@
+import { formatLabel } from "../../js/format/index.js";
+import "../../js/index.js";
+import "./types.js";
+
 //#region src/react/charts/utils.d.ts
 /**
  * Converts a value to a chart-compatible type.
@@ -9,13 +13,6 @@ declare function toChartValue(value: unknown): string | number;
  * Converts an array of values to chart-compatible types.
  */
 declare function toChartArray(data: unknown[]): (string | number)[];
-/**
- * Formats a field name into a human-readable label.
- * Handles camelCase, snake_case, acronyms, and ALL_CAPS.
- * E.g., "totalSpend" -> "Total Spend", "user_name" -> "User Name",
- *       "userID" -> "User Id", "TOTAL_SPEND" -> "Total Spend"
- */
-declare function formatLabel(field: string): string;
 /**
  * Truncates a label to a maximum length with ellipsis.
  */
@@ -25,12 +22,14 @@ declare function truncateLabel(value: string, maxLength?: number): string;
  */
 declare function createTimeSeriesData(xData: (string | number)[], yData: (string | number)[]): [string | number, string | number][];
 /**
- * Sorts time-series data in ascending chronological order.
+ * Sorts time-series data in ascending chronological order while preserving
+ * the correlation between each x value and its y values. Non-date category
+ * strings are intentionally left in their source order.
  */
 declare function sortTimeSeriesAscending(xData: (string | number)[], yDataMap: Record<string, (string | number)[]>, yFields: string[]): {
   xData: (string | number)[];
   yDataMap: Record<string, (string | number)[]>;
 };
 //#endregion
-export { createTimeSeriesData, formatLabel, sortTimeSeriesAscending, toChartArray, toChartValue, truncateLabel };
+export { createTimeSeriesData, sortTimeSeriesAscending, toChartArray, toChartValue, truncateLabel };
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","names":[],"sources":["../../../src/react/charts/utils.ts"],"mappings":";;AASA;;;;iBAAgB,YAAA,CAAa,KAAA;AAmB7B;;;AAAA,iBAAgB,YAAA,CAAa,IAAA;;AAW7B;;;;;iBAAgB,WAAA,CAAY,KAAA;;;;iBAwCZ,aAAA,CAAc,KAAA,UAAe,SAAA;;;;iBAO7B,oBAAA,CACd,KAAA,uBACA,KAAA;;;;iBA0Cc,uBAAA,CACd,KAAA,uBACA,QAAA,EAAU,MAAA,+BACV,OAAA;EAEA,KAAA;EACA,QAAA,EAAU,MAAA;AAAA"}
+{"version":3,"file":"utils.d.ts","names":[],"sources":["../../../src/react/charts/utils.ts"],"mappings":";;;;;;;;;AAWA;iBAAgB,YAAA,CAAa,KAAA;;;;iBAmBb,YAAA,CAAa,IAAA;;;AAkT7B;iBArRgB,aAAA,CAAc,KAAA,UAAe,SAAA;;;;iBAO7B,oBAAA,CACd,KAAA,uBACA,KAAA;;;;;;iBA4Qc,uBAAA,CACd,KAAA,uBACA,QAAA,EAAU,MAAA,+BACV,OAAA;EAEA,KAAA;EACA,QAAA,EAAU,MAAA;AAAA"}

package/dist/react/charts/utils.js

@@ -1,3 +1,5 @@
+import { formatLabel } from "../../js/format/index.js";
+
 //#region src/react/charts/utils.ts
 /**
 * Converts a value to a chart-compatible type.
@@ -19,15 +21,6 @@ function toChartArray(data) {
 	return data.map(toChartValue);
 }
 /**
-* Formats a field name into a human-readable label.
-* Handles camelCase, snake_case, acronyms, and ALL_CAPS.
-* E.g., "totalSpend" -> "Total Spend", "user_name" -> "User Name",
-*       "userID" -> "User Id", "TOTAL_SPEND" -> "Total Spend"
-*/
-function formatLabel(field) {
-	return field.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();
-}
-/**
 * Escapes HTML special characters to prevent XSS.
 * Required for ECharts function formatters: unlike string-template
 * formatters, their return values are injected as raw HTML into the
@@ -77,36 +70,150 @@ function sortNumericAscending(xData, yDataMap, yFields) {
 		yDataMap: sortedYDataMap
 	};
 }
+function resolveLineStrokePoint(params, axes, instance) {
+	if (params.seriesType !== "line" || params.value !== void 0 || !instance || typeof params.seriesIndex !== "number") return null;
+	const clickX = (params.event !== null && typeof params.event === "object" ? params.event : null)?.offsetX;
+	if (typeof clickX !== "number") return null;
+	try {
+		const option = instance.getOption();
+		if (option === null || typeof option !== "object") return null;
+		const series = option.series;
+		if (!Array.isArray(series)) return null;
+		const seriesOption = series[params.seriesIndex];
+		if (seriesOption === null || typeof seriesOption !== "object" || Array.isArray(seriesOption)) return null;
+		const data = seriesOption.data;
+		if (!Array.isArray(data)) return null;
+		let nearest = null;
+		let nearestDistance = Number.POSITIVE_INFINITY;
+		for (let dataIndex = 0; dataIndex < data.length; dataIndex++) {
+			const item = data[dataIndex];
+			const itemRecord = item !== null && typeof item === "object" && !Array.isArray(item) ? item : null;
+			const rawValue = itemRecord ? itemRecord.value : item;
+			let x;
+			let y;
+			if (Array.isArray(rawValue)) {
+				if ((typeof rawValue[0] === "string" || typeof rawValue[0] === "number") && (typeof rawValue[1] === "string" || typeof rawValue[1] === "number")) {
+					x = rawValue[0];
+					y = rawValue[1];
+				}
+			} else if ((typeof rawValue === "string" || typeof rawValue === "number") && axes.xLabels?.[dataIndex] !== void 0) {
+				x = axes.xLabels[dataIndex];
+				y = rawValue;
+			}
+			if (x === void 0 || y === void 0) continue;
+			const pixel = instance.convertToPixel({ seriesIndex: params.seriesIndex }, [x, y]);
+			if (!Array.isArray(pixel) || typeof pixel[0] !== "number") continue;
+			const distance = Math.abs(pixel[0] - clickX);
+			if (distance < nearestDistance) {
+				nearestDistance = distance;
+				nearest = {
+					name: typeof itemRecord?.name === "string" ? itemRecord.name : String(x),
+					value: [x, y],
+					dataIndex
+				};
+			}
+		}
+		return nearest;
+	} catch {
+		return null;
+	}
+}
+/**
+* Maps a raw ECharts click-event `params` object into a public
+* {@link ChartClickDatum}.
+*
+* @param params - The raw ECharts click-event payload (untyped at our boundary).
+* @param axes - Category labels used to resolve index-addressed heatmap data.
+* @param instance - The chart instance used to resolve series-level line clicks.
+* @returns A normalized, ECharts-free {@link ChartClickDatum}.
+*/
+function mapToDatum(params, axes = {}, instance) {
+	const p = params !== null && typeof params === "object" ? params : {};
+	const isScalar = (v) => typeof v === "number" || typeof v === "string";
+	const linePoint = resolveLineStrokePoint(p, axes, instance);
+	const rawValue = linePoint?.value ?? p.value;
+	const seriesType = typeof p.seriesType === "string" ? p.seriesType : void 0;
+	let x;
+	let y;
+	let value;
+	if (seriesType === "heatmap" && Array.isArray(rawValue)) {
+		const labelAt = (labels, index) => {
+			if (!isScalar(index)) return void 0;
+			if (typeof index === "number" && labels?.[index] !== void 0) return labels[index];
+			return index;
+		};
+		x = labelAt(axes.xLabels, rawValue[0]);
+		y = labelAt(axes.yLabels, rawValue[1]);
+		value = isScalar(rawValue[2]) ? rawValue[2] : null;
+	} else if (seriesType === "radar") value = null;
+	else if (Array.isArray(rawValue)) {
+		if (isScalar(rawValue[0])) x = rawValue[0];
+		if (isScalar(rawValue[1])) y = rawValue[1];
+		value = y ?? null;
+	} else value = isScalar(rawValue) ? rawValue : null;
+	const name = typeof p.name === "string" ? p.name : linePoint?.name ?? (x !== void 0 ? String(x) : "");
+	const seriesName = typeof p.seriesName === "string" ? p.seriesName : void 0;
+	const dataIndex = typeof p.dataIndex === "number" ? p.dataIndex : linePoint?.dataIndex ?? -1;
+	const seriesIndex = typeof p.seriesIndex === "number" ? p.seriesIndex : -1;
+	return {
+		name,
+		value,
+		x,
+		y,
+		seriesName,
+		dataIndex,
+		seriesIndex,
+		raw: params
+	};
+}
+const DATE_STRING_PATTERN = /^\d{4}-\d{2}-\d{2}(?:$|[T\s])/;
+/**
+* Converts a value to a number that can be compared chronologically, or null
+* when it is not a date. This is the single definition of "chartable date"
+* shared by field detection, value conversion and sorting: a shape-only check
+* would classify "2025-01-01 nonsense" as a date field and then fail to place
+* it on a time axis.
+*/
+function toChronologicalValue(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value !== "string") return null;
+	if (!DATE_STRING_PATTERN.test(value)) return null;
+	const timestamp = Date.parse(value.replace(" ", "T"));
+	return Number.isFinite(timestamp) ? timestamp : null;
+}
 /**
-* Sorts time-series data in ascending chronological order.
+* Sorts time-series data in ascending chronological order while preserving
+* the correlation between each x value and its y values. Non-date category
+* strings are intentionally left in their source order.
 */
 function sortTimeSeriesAscending(xData, yDataMap, yFields) {
 	if (xData.length <= 1) return {
 		xData,
 		yDataMap
 	};
-	const first = xData[0];
-	const last = xData[xData.length - 1];
-	if (typeof first === "number" && typeof last === "number" && first > last) {
-		const indices = xData.map((_, i) => i);
-		indices.sort((a, b) => xData[a] - xData[b]);
-		const sortedXData = indices.map((i) => xData[i]);
-		const sortedYDataMap = {};
-		for (const key of yFields) {
-			const original = yDataMap[key];
-			sortedYDataMap[key] = indices.map((i) => original[i]);
-		}
-		return {
-			xData: sortedXData,
-			yDataMap: sortedYDataMap
-		};
-	}
-	return {
+	const chronologicalValues = xData.map(toChronologicalValue);
+	if (chronologicalValues.some((value) => value === null)) return {
+		xData,
+		yDataMap
+	};
+	const indices = xData.map((_, i) => i);
+	indices.sort((a, b) => chronologicalValues[a] - chronologicalValues[b]);
+	if (indices.every((originalIndex, index) => originalIndex === index)) return {
 		xData,
 		yDataMap
 	};
+	const sortedXData = indices.map((i) => xData[i]);
+	const sortedYDataMap = { ...yDataMap };
+	for (const key of yFields) {
+		const original = yDataMap[key];
+		sortedYDataMap[key] = indices.map((i) => original[i]);
+	}
+	return {
+		xData: sortedXData,
+		yDataMap: sortedYDataMap
+	};
 }
 
 //#endregion
-export { createTimeSeriesData, escapeHtml, formatLabel, sortNumericAscending, sortTimeSeriesAscending, toChartArray, toChartValue, truncateLabel };
+export { createTimeSeriesData, escapeHtml, mapToDatum, sortNumericAscending, sortTimeSeriesAscending, toChartArray, toChartValue, toChronologicalValue, truncateLabel };
 //# sourceMappingURL=utils.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.js","names":[],"sources":["../../../src/react/charts/utils.ts"],"sourcesContent":["// ============================================================================\n// Chart Utility Functions\n// ============================================================================\n\n/**\n * Converts a value to a chart-compatible type.\n * Handles BigInt conversion (Arrow can return BigInt64Array values).\n * Handles Date objects by converting to timestamps.\n */\nexport function toChartValue(value: unknown): string | number {\n  if (value === null || value === undefined) {\n    return 0;\n  }\n  if (typeof value === \"bigint\") {\n    return Number(value);\n  }\n  if (value instanceof Date) {\n    return value.getTime();\n  }\n  if (typeof value === \"string\" || typeof value === \"number\") {\n    return value;\n  }\n  return String(value);\n}\n\n/**\n * Converts an array of values to chart-compatible types.\n */\nexport function toChartArray(data: unknown[]): (string | number)[] {\n  if (data.length === 0) return [];\n  return data.map(toChartValue);\n}\n\n/**\n * Formats a field name into a human-readable label.\n * Handles camelCase, snake_case, acronyms, and ALL_CAPS.\n * E.g., \"totalSpend\" -> \"Total Spend\", \"user_name\" -> \"User Name\",\n *       \"userID\" -> \"User Id\", \"TOTAL_SPEND\" -> \"Total Spend\"\n */\nexport function formatLabel(field: string): string {\n  return (\n    field\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\n/**\n * Escapes HTML special characters to prevent XSS.\n * Required for ECharts function formatters: unlike string-template\n * formatters, their return values are injected as raw HTML into the\n * tooltip DOM.\n *\n * Only for HTML tooltip contexts; do NOT use on canvas-rendered\n * axis/series label formatters — canvas text is not HTML and would\n * display literal entities (e.g. \"&amp;\").\n */\nexport function escapeHtml(value: string): string {\n  return value\n    .replace(/&/g, \"&amp;\")\n    .replace(/</g, \"&lt;\")\n    .replace(/>/g, \"&gt;\")\n    .replace(/\"/g, \"&quot;\")\n    .replace(/'/g, \"&#39;\");\n}\n\n/**\n * Truncates a label to a maximum length with ellipsis.\n */\nexport function truncateLabel(value: string, maxLength = 15): string {\n  return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;\n}\n\n/**\n * Creates time-series data pairs for ECharts.\n */\nexport function createTimeSeriesData(\n  xData: (string | number)[],\n  yData: (string | number)[],\n): [string | number, string | number][] {\n  const len = xData.length;\n  const result: [string | number, string | number][] = new Array(len);\n  for (let i = 0; i < len; i++) {\n    result[i] = [xData[i], yData[i]];\n  }\n  return result;\n}\n\n/**\n * Sorts numeric x-data in ascending order, reordering y-data to match.\n * Also coerces numeric string x-values to numbers.\n */\nexport function sortNumericAscending(\n  xData: (string | number)[],\n  yDataMap: Record<string, (string | number)[]>,\n  yFields: string[],\n): {\n  xData: (string | number)[];\n  yDataMap: Record<string, (string | number)[]>;\n} {\n  if (xData.length <= 1) {\n    return { xData, yDataMap };\n  }\n\n  const indices = xData.map((_, i) => i);\n  indices.sort((a, b) => Number(xData[a]) - Number(xData[b]));\n\n  const sortedXData = indices.map((i) => Number(xData[i]));\n  const sortedYDataMap: Record<string, (string | number)[]> = {};\n  for (const key of yFields) {\n    const original = yDataMap[key];\n    sortedYDataMap[key] = indices.map((i) => original[i]);\n  }\n\n  return { xData: sortedXData, yDataMap: sortedYDataMap };\n}\n\n/**\n * Sorts time-series data in ascending chronological order.\n */\nexport function sortTimeSeriesAscending(\n  xData: (string | number)[],\n  yDataMap: Record<string, (string | number)[]>,\n  yFields: string[],\n): {\n  xData: (string | number)[];\n  yDataMap: Record<string, (string | number)[]>;\n} {\n  if (xData.length <= 1) {\n    return { xData, yDataMap };\n  }\n\n  const first = xData[0];\n  const last = xData[xData.length - 1];\n\n  if (typeof first === \"number\" && typeof last === \"number\" && first > last) {\n    const indices = xData.map((_, i) => i);\n    indices.sort((a, b) => (xData[a] as number) - (xData[b] as number));\n\n    const sortedXData = indices.map((i) => xData[i]);\n    const sortedYDataMap: Record<string, (string | number)[]> = {};\n    for (const key of yFields) {\n      const original = yDataMap[key];\n      sortedYDataMap[key] = indices.map((i) => original[i]);\n    }\n\n    return { xData: sortedXData, yDataMap: sortedYDataMap };\n  }\n\n  return { xData, yDataMap };\n}\n"],"mappings":";;;;;;AASA,SAAgB,aAAa,OAAiC;AAC5D,KAAI,UAAU,QAAQ,UAAU,OAC9B,QAAO;AAET,KAAI,OAAO,UAAU,SACnB,QAAO,OAAO,MAAM;AAEtB,KAAI,iBAAiB,KACnB,QAAO,MAAM,SAAS;AAExB,KAAI,OAAO,UAAU,YAAY,OAAO,UAAU,SAChD,QAAO;AAET,QAAO,OAAO,MAAM;;;;;AAMtB,SAAgB,aAAa,MAAsC;AACjE,KAAI,KAAK,WAAW,EAAG,QAAO,EAAE;AAChC,QAAO,KAAK,IAAI,aAAa;;;;;;;;AAS/B,SAAgB,YAAY,OAAuB;AACjD,QACE,MAEG,QAAQ,yBAAyB,QAAQ,CAEzC,QAAQ,mBAAmB,QAAQ,CAEnC,QAAQ,MAAM,IAAI,CAElB,QAAQ,QAAQ,IAAI,CAEpB,aAAa,CACb,QAAQ,UAAU,MAAM,EAAE,aAAa,CAAC,CACxC,MAAM;;;;;;;;;;;;AAcb,SAAgB,WAAW,OAAuB;AAChD,QAAO,MACJ,QAAQ,MAAM,QAAQ,CACtB,QAAQ,MAAM,OAAO,CACrB,QAAQ,MAAM,OAAO,CACrB,QAAQ,MAAM,SAAS,CACvB,QAAQ,MAAM,QAAQ;;;;;AAM3B,SAAgB,cAAc,OAAe,YAAY,IAAY;AACnE,QAAO,MAAM,SAAS,YAAY,GAAG,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO;;;;;AAMxE,SAAgB,qBACd,OACA,OACsC;CACtC,MAAM,MAAM,MAAM;CAClB,MAAM,SAA+C,IAAI,MAAM,IAAI;AACnE,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,IACvB,QAAO,KAAK,CAAC,MAAM,IAAI,MAAM,GAAG;AAElC,QAAO;;;;;;AAOT,SAAgB,qBACd,OACA,UACA,SAIA;AACA,KAAI,MAAM,UAAU,EAClB,QAAO;EAAE;EAAO;EAAU;CAG5B,MAAM,UAAU,MAAM,KAAK,GAAG,MAAM,EAAE;AACtC,SAAQ,MAAM,GAAG,MAAM,OAAO,MAAM,GAAG,GAAG,OAAO,MAAM,GAAG,CAAC;CAE3D,MAAM,cAAc,QAAQ,KAAK,MAAM,OAAO,MAAM,GAAG,CAAC;CACxD,MAAM,iBAAsD,EAAE;AAC9D,MAAK,MAAM,OAAO,SAAS;EACzB,MAAM,WAAW,SAAS;AAC1B,iBAAe,OAAO,QAAQ,KAAK,MAAM,SAAS,GAAG;;AAGvD,QAAO;EAAE,OAAO;EAAa,UAAU;EAAgB;;;;;AAMzD,SAAgB,wBACd,OACA,UACA,SAIA;AACA,KAAI,MAAM,UAAU,EAClB,QAAO;EAAE;EAAO;EAAU;CAG5B,MAAM,QAAQ,MAAM;CACpB,MAAM,OAAO,MAAM,MAAM,SAAS;AAElC,KAAI,OAAO,UAAU,YAAY,OAAO,SAAS,YAAY,QAAQ,MAAM;EACzE,MAAM,UAAU,MAAM,KAAK,GAAG,MAAM,EAAE;AACtC,UAAQ,MAAM,GAAG,MAAO,MAAM,KAAiB,MAAM,GAAc;EAEnE,MAAM,cAAc,QAAQ,KAAK,MAAM,MAAM,GAAG;EAChD,MAAM,iBAAsD,EAAE;AAC9D,OAAK,MAAM,OAAO,SAAS;GACzB,MAAM,WAAW,SAAS;AAC1B,kBAAe,OAAO,QAAQ,KAAK,MAAM,SAAS,GAAG;;AAGvD,SAAO;GAAE,OAAO;GAAa,UAAU;GAAgB;;AAGzD,QAAO;EAAE;EAAO;EAAU"}
+{"version":3,"file":"utils.js","names":[],"sources":["../../../src/react/charts/utils.ts"],"sourcesContent":["import type { ChartClickDatum } from \"./types\";\n\n// ============================================================================\n// Chart Utility Functions\n// ============================================================================\n\n/**\n * Converts a value to a chart-compatible type.\n * Handles BigInt conversion (Arrow can return BigInt64Array values).\n * Handles Date objects by converting to timestamps.\n */\nexport function toChartValue(value: unknown): string | number {\n  if (value === null || value === undefined) {\n    return 0;\n  }\n  if (typeof value === \"bigint\") {\n    return Number(value);\n  }\n  if (value instanceof Date) {\n    return value.getTime();\n  }\n  if (typeof value === \"string\" || typeof value === \"number\") {\n    return value;\n  }\n  return String(value);\n}\n\n/**\n * Converts an array of values to chart-compatible types.\n */\nexport function toChartArray(data: unknown[]): (string | number)[] {\n  if (data.length === 0) return [];\n  return data.map(toChartValue);\n}\n\nexport { formatLabel } from \"@/js\";\n\n/**\n * Escapes HTML special characters to prevent XSS.\n * Required for ECharts function formatters: unlike string-template\n * formatters, their return values are injected as raw HTML into the\n * tooltip DOM.\n *\n * Only for HTML tooltip contexts; do NOT use on canvas-rendered\n * axis/series label formatters — canvas text is not HTML and would\n * display literal entities (e.g. \"&amp;\").\n */\nexport function escapeHtml(value: string): string {\n  return value\n    .replace(/&/g, \"&amp;\")\n    .replace(/</g, \"&lt;\")\n    .replace(/>/g, \"&gt;\")\n    .replace(/\"/g, \"&quot;\")\n    .replace(/'/g, \"&#39;\");\n}\n\n/**\n * Truncates a label to a maximum length with ellipsis.\n */\nexport function truncateLabel(value: string, maxLength = 15): string {\n  return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;\n}\n\n/**\n * Creates time-series data pairs for ECharts.\n */\nexport function createTimeSeriesData(\n  xData: (string | number)[],\n  yData: (string | number)[],\n): [string | number, string | number][] {\n  const len = xData.length;\n  const result: [string | number, string | number][] = new Array(len);\n  for (let i = 0; i < len; i++) {\n    result[i] = [xData[i], yData[i]];\n  }\n  return result;\n}\n\n/**\n * Sorts numeric x-data in ascending order, reordering y-data to match.\n * Also coerces numeric string x-values to numbers.\n */\nexport function sortNumericAscending(\n  xData: (string | number)[],\n  yDataMap: Record<string, (string | number)[]>,\n  yFields: string[],\n): {\n  xData: (string | number)[];\n  yDataMap: Record<string, (string | number)[]>;\n} {\n  if (xData.length <= 1) {\n    return { xData, yDataMap };\n  }\n\n  const indices = xData.map((_, i) => i);\n  indices.sort((a, b) => Number(xData[a]) - Number(xData[b]));\n\n  const sortedXData = indices.map((i) => Number(xData[i]));\n  const sortedYDataMap: Record<string, (string | number)[]> = {};\n  for (const key of yFields) {\n    const original = yDataMap[key];\n    sortedYDataMap[key] = indices.map((i) => original[i]);\n  }\n\n  return { xData: sortedXData, yDataMap: sortedYDataMap };\n}\n\n/**\n * Axis category labels for the chart being clicked, so index-addressed data\n * (heatmap) can be resolved back to the labels the user actually sees.\n */\ninterface DatumAxisContext {\n  xLabels?: (string | number)[];\n  yLabels?: (string | number)[];\n}\n\ninterface ChartEventInstance {\n  getOption(): unknown;\n  convertToPixel(\n    finder: { seriesIndex: number },\n    value: (string | number)[],\n  ): unknown;\n}\n\ninterface ResolvedLinePoint {\n  name: string;\n  value: [string | number, string | number];\n  dataIndex: number;\n}\n\nfunction resolveLineStrokePoint(\n  params: Record<string, unknown>,\n  axes: DatumAxisContext,\n  instance?: ChartEventInstance,\n): ResolvedLinePoint | null {\n  if (\n    params.seriesType !== \"line\" ||\n    params.value !== undefined ||\n    !instance ||\n    typeof params.seriesIndex !== \"number\"\n  ) {\n    return null;\n  }\n\n  const event =\n    params.event !== null && typeof params.event === \"object\"\n      ? (params.event as Record<string, unknown>)\n      : null;\n  const clickX = event?.offsetX;\n  if (typeof clickX !== \"number\") return null;\n\n  try {\n    const option = instance.getOption();\n    if (option === null || typeof option !== \"object\") return null;\n\n    const series = (option as Record<string, unknown>).series;\n    if (!Array.isArray(series)) return null;\n\n    const seriesOption = series[params.seriesIndex];\n    if (\n      seriesOption === null ||\n      typeof seriesOption !== \"object\" ||\n      Array.isArray(seriesOption)\n    ) {\n      return null;\n    }\n\n    const data = (seriesOption as Record<string, unknown>).data;\n    if (!Array.isArray(data)) return null;\n\n    let nearest: ResolvedLinePoint | null = null;\n    let nearestDistance = Number.POSITIVE_INFINITY;\n\n    for (let dataIndex = 0; dataIndex < data.length; dataIndex++) {\n      const item = data[dataIndex];\n      const itemRecord =\n        item !== null && typeof item === \"object\" && !Array.isArray(item)\n          ? (item as Record<string, unknown>)\n          : null;\n      const rawValue = itemRecord ? itemRecord.value : item;\n\n      let x: string | number | undefined;\n      let y: string | number | undefined;\n      if (Array.isArray(rawValue)) {\n        if (\n          (typeof rawValue[0] === \"string\" ||\n            typeof rawValue[0] === \"number\") &&\n          (typeof rawValue[1] === \"string\" || typeof rawValue[1] === \"number\")\n        ) {\n          x = rawValue[0];\n          y = rawValue[1];\n        }\n      } else if (\n        (typeof rawValue === \"string\" || typeof rawValue === \"number\") &&\n        axes.xLabels?.[dataIndex] !== undefined\n      ) {\n        x = axes.xLabels[dataIndex];\n        y = rawValue;\n      }\n      if (x === undefined || y === undefined) continue;\n\n      const pixel = instance.convertToPixel(\n        { seriesIndex: params.seriesIndex },\n        [x, y],\n      );\n      if (!Array.isArray(pixel) || typeof pixel[0] !== \"number\") continue;\n\n      const distance = Math.abs(pixel[0] - clickX);\n      if (distance < nearestDistance) {\n        nearestDistance = distance;\n        nearest = {\n          name:\n            typeof itemRecord?.name === \"string\" ? itemRecord.name : String(x),\n          value: [x, y],\n          dataIndex,\n        };\n      }\n    }\n\n    return nearest;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Maps a raw ECharts click-event `params` object into a public\n * {@link ChartClickDatum}.\n *\n * @param params - The raw ECharts click-event payload (untyped at our boundary).\n * @param axes - Category labels used to resolve index-addressed heatmap data.\n * @param instance - The chart instance used to resolve series-level line clicks.\n * @returns A normalized, ECharts-free {@link ChartClickDatum}.\n */\nexport function mapToDatum(\n  params: unknown,\n  axes: DatumAxisContext = {},\n  instance?: ChartEventInstance,\n): ChartClickDatum {\n  const p = (\n    params !== null && typeof params === \"object\" ? params : {}\n  ) as Record<string, unknown>;\n\n  const isScalar = (v: unknown): v is number | string =>\n    typeof v === \"number\" || typeof v === \"string\";\n\n  const linePoint = resolveLineStrokePoint(p, axes, instance);\n  const rawValue = linePoint?.value ?? p.value;\n  const seriesType =\n    typeof p.seriesType === \"string\" ? p.seriesType : undefined;\n\n  let x: number | string | undefined;\n  let y: number | string | undefined;\n  let value: number | string | null;\n\n  if (seriesType === \"heatmap\" && Array.isArray(rawValue)) {\n    // `[xIndex, yIndex, value]`: report the cell value\n    const labelAt = (\n      labels: (string | number)[] | undefined,\n      index: unknown,\n    ): number | string | undefined => {\n      if (!isScalar(index)) return undefined;\n      if (typeof index === \"number\" && labels?.[index] !== undefined) {\n        return labels[index];\n      }\n      return index;\n    };\n    x = labelAt(axes.xLabels, rawValue[0]);\n    y = labelAt(axes.yLabels, rawValue[1]);\n    value = isScalar(rawValue[2]) ? rawValue[2] : null;\n  } else if (seriesType === \"radar\") {\n    // A radar item holds one value per indicator;\n    value = null;\n  } else if (Array.isArray(rawValue)) {\n    // `[x, y]` (time-series / scatter): split values so callers don't have to re-parse `raw`.\n    if (isScalar(rawValue[0])) x = rawValue[0];\n    if (isScalar(rawValue[1])) y = rawValue[1];\n    value = y ?? null;\n  } else {\n    value = isScalar(rawValue) ? rawValue : null;\n  }\n\n  const name =\n    typeof p.name === \"string\"\n      ? p.name\n      : (linePoint?.name ?? (x !== undefined ? String(x) : \"\"));\n\n  const seriesName =\n    typeof p.seriesName === \"string\" ? p.seriesName : undefined;\n\n  const dataIndex =\n    typeof p.dataIndex === \"number\"\n      ? p.dataIndex\n      : (linePoint?.dataIndex ?? -1);\n  const seriesIndex = typeof p.seriesIndex === \"number\" ? p.seriesIndex : -1;\n\n  return {\n    name,\n    value,\n    x,\n    y,\n    seriesName,\n    dataIndex,\n    seriesIndex,\n    raw: params,\n  };\n}\n\nconst DATE_STRING_PATTERN = /^\\d{4}-\\d{2}-\\d{2}(?:$|[T\\s])/;\n\n/**\n * Converts a value to a number that can be compared chronologically, or null\n * when it is not a date. This is the single definition of \"chartable date\"\n * shared by field detection, value conversion and sorting: a shape-only check\n * would classify \"2025-01-01 nonsense\" as a date field and then fail to place\n * it on a time axis.\n */\nexport function toChronologicalValue(value: unknown): number | null {\n  if (typeof value === \"number\") {\n    return Number.isFinite(value) ? value : null;\n  }\n\n  if (typeof value !== \"string\") return null;\n  if (!DATE_STRING_PATTERN.test(value)) return null;\n\n  // Spark JSON_ARRAY timestamps commonly use a space between the date and\n  // time. Normalize that separator to the ISO form before parsing.\n  const timestamp = Date.parse(value.replace(\" \", \"T\"));\n  return Number.isFinite(timestamp) ? timestamp : null;\n}\n\n/**\n * Sorts time-series data in ascending chronological order while preserving\n * the correlation between each x value and its y values. Non-date category\n * strings are intentionally left in their source order.\n */\nexport function sortTimeSeriesAscending(\n  xData: (string | number)[],\n  yDataMap: Record<string, (string | number)[]>,\n  yFields: string[],\n): {\n  xData: (string | number)[];\n  yDataMap: Record<string, (string | number)[]>;\n} {\n  if (xData.length <= 1) {\n    return { xData, yDataMap };\n  }\n\n  const chronologicalValues = xData.map(toChronologicalValue);\n  if (chronologicalValues.some((value) => value === null)) {\n    return { xData, yDataMap };\n  }\n\n  const indices = xData.map((_, i) => i);\n  indices.sort(\n    (a, b) =>\n      (chronologicalValues[a] as number) - (chronologicalValues[b] as number),\n  );\n\n  if (indices.every((originalIndex, index) => originalIndex === index)) {\n    return { xData, yDataMap };\n  }\n\n  const sortedXData = indices.map((i) => xData[i]);\n  const sortedYDataMap: Record<string, (string | number)[]> = {\n    ...yDataMap,\n  };\n  for (const key of yFields) {\n    const original = yDataMap[key];\n    sortedYDataMap[key] = indices.map((i) => original[i]);\n  }\n\n  return { xData: sortedXData, yDataMap: sortedYDataMap };\n}\n"],"mappings":"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"}

package/dist/react/hooks/analytics-sse.js

@@ -0,0 +1,117 @@
+//#region src/react/hooks/analytics-sse.ts
+const GENERIC_LOAD_ERROR = "Unable to load data, please try again";
+function getDevMode() {
+	const dev = new URL(window.location.href).searchParams.get("dev");
+	return dev ? `?dev=${dev}` : "";
+}
+/** Map a fetch/SSE transport error to a user-facing message. */
+function userFacingFetchError(error) {
+	if (error instanceof Error) {
+		if (error.name === "AbortError") return "Request timed out, please try again";
+		if (error.message.includes("Failed to fetch")) return "Network error. Please check your connection.";
+	}
+	return GENERIC_LOAD_ERROR;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isWarehouseStatusPayload(value) {
+	return typeof value === "object" && value !== null && typeof value.state === "string";
+}
+/**
+* Parse and classify the deliberately loose analytics SSE wire format.
+* Result rows normalize to an empty array so hook state remains `T | null`.
+*/
+function parseAnalyticsSseMessage(data, defaultExecutionError) {
+	const parsed = JSON.parse(data);
+	if (!isRecord(parsed)) return {
+		kind: "invalid",
+		reason: "unrecognized",
+		payload: parsed
+	};
+	if (parsed.type === "warehouse_status") {
+		if (!isWarehouseStatusPayload(parsed.status)) return {
+			kind: "invalid",
+			reason: "malformed-warehouse-status",
+			payload: parsed
+		};
+		return {
+			kind: "warehouse-status",
+			status: parsed.status
+		};
+	}
+	if (parsed.type === "result") return {
+		kind: "result",
+		data: Array.isArray(parsed.data) ? parsed.data : [],
+		payload: parsed
+	};
+	if (parsed.type === "error" || parsed.error || parsed.code) return {
+		kind: "error",
+		message: typeof parsed.error === "string" && parsed.error || typeof parsed.message === "string" && parsed.message || defaultExecutionError,
+		errorCode: typeof parsed.errorCode === "string" ? parsed.errorCode : null,
+		code: parsed.code
+	};
+	return {
+		kind: "invalid",
+		reason: "unrecognized",
+		payload: parsed
+	};
+}
+function failWithGenericError(ctx) {
+	ctx.setLoading(false);
+	ctx.setError(GENERIC_LOAD_ERROR);
+	ctx.unpublishWarehouseStatus();
+}
+/**
+* Apply the state transitions shared by analytics-query and metric-view SSE
+* messages while delegating their distinct result/status state to callbacks.
+*/
+async function handleAnalyticsSseMessage(data, ctx) {
+	if (ctx.signal.aborted) return;
+	try {
+		const message = parseAnalyticsSseMessage(data, ctx.defaultExecutionError);
+		if (message.kind === "warehouse-status") {
+			ctx.onWarehouseStatus(message.status);
+			return;
+		}
+		if (message.kind === "result") {
+			ctx.setLoading(false);
+			ctx.onResult(message);
+			ctx.unpublishWarehouseStatus();
+			return;
+		}
+		if (message.kind === "error") {
+			ctx.setLoading(false);
+			ctx.setError(message.message);
+			ctx.unpublishWarehouseStatus();
+			if (message.errorCode !== null) ctx.setErrorCode(message.errorCode);
+			if (message.code) console.error(`[${ctx.source}] Code: ${String(message.code)}, Message: ${message.message}`);
+			return;
+		}
+		if (message.reason === "malformed-warehouse-status") console.error(`[${ctx.source}] Malformed warehouse_status event`, message.payload);
+		else console.error(`[${ctx.source}] Unrecognized SSE payload`, message.payload);
+		failWithGenericError(ctx);
+	} catch (error) {
+		console.warn(`[${ctx.source}] Malformed message received`, error);
+		ctx.setLoading(false);
+		ctx.setError(GENERIC_LOAD_ERROR);
+		if (ctx.unpublishOnMalformedMessage) ctx.unpublishWarehouseStatus();
+		ctx.abort();
+	}
+}
+/** Apply the shared terminal state for an SSE connection failure. */
+function handleAnalyticsSseError(error, ctx) {
+	if (ctx.signal.aborted) return;
+	ctx.setLoading(false);
+	ctx.unpublishWarehouseStatus();
+	if (error instanceof Error) console.error(`[${ctx.source}] Error`, {
+		...ctx.resource,
+		error: error.message,
+		stack: error.stack
+	});
+	ctx.setError(userFacingFetchError(error));
+}
+
+//#endregion
+export { GENERIC_LOAD_ERROR, getDevMode, handleAnalyticsSseError, handleAnalyticsSseMessage, userFacingFetchError };
+//# sourceMappingURL=analytics-sse.js.map

package/dist/react/hooks/analytics-sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-sse.js","names":[],"sources":["../../../src/react/hooks/analytics-sse.ts"],"sourcesContent":["import type { WarehouseStatus } from \"./types\";\n\nexport const GENERIC_LOAD_ERROR = \"Unable to load data, please try again\";\n\nexport function getDevMode(): string {\n  const dev = new URL(window.location.href).searchParams.get(\"dev\");\n  return dev ? `?dev=${dev}` : \"\";\n}\n\n/** Map a fetch/SSE transport error to a user-facing message. */\nexport function userFacingFetchError(error: unknown): string {\n  if (error instanceof Error) {\n    if (error.name === \"AbortError\") {\n      return \"Request timed out, please try again\";\n    }\n    if (error.message.includes(\"Failed to fetch\")) {\n      return \"Network error. Please check your connection.\";\n    }\n  }\n  return GENERIC_LOAD_ERROR;\n}\n\ninterface WarehouseStatusMessage {\n  kind: \"warehouse-status\";\n  status: WarehouseStatus;\n}\n\nexport interface AnalyticsSseResultMessage {\n  kind: \"result\";\n  data: unknown[];\n  payload: Record<string, unknown>;\n}\n\ninterface AnalyticsSseErrorMessage {\n  kind: \"error\";\n  message: string;\n  errorCode: string | null;\n  code: unknown;\n}\n\ninterface InvalidAnalyticsSseMessage {\n  kind: \"invalid\";\n  reason: \"malformed-warehouse-status\" | \"unrecognized\";\n  payload: unknown;\n}\n\ntype AnalyticsSseMessage =\n  | WarehouseStatusMessage\n  | AnalyticsSseResultMessage\n  | AnalyticsSseErrorMessage\n  | InvalidAnalyticsSseMessage;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isWarehouseStatusPayload(value: unknown): value is WarehouseStatus {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as WarehouseStatus).state === \"string\"\n  );\n}\n\n/**\n * Parse and classify the deliberately loose analytics SSE wire format.\n * Result rows normalize to an empty array so hook state remains `T | null`.\n */\nexport function parseAnalyticsSseMessage(\n  data: string,\n  defaultExecutionError: string,\n): AnalyticsSseMessage {\n  const parsed: unknown = JSON.parse(data);\n\n  if (!isRecord(parsed)) {\n    return { kind: \"invalid\", reason: \"unrecognized\", payload: parsed };\n  }\n\n  if (parsed.type === \"warehouse_status\") {\n    if (!isWarehouseStatusPayload(parsed.status)) {\n      return {\n        kind: \"invalid\",\n        reason: \"malformed-warehouse-status\",\n        payload: parsed,\n      };\n    }\n    return { kind: \"warehouse-status\", status: parsed.status };\n  }\n\n  if (parsed.type === \"result\") {\n    return {\n      kind: \"result\",\n      data: Array.isArray(parsed.data) ? parsed.data : [],\n      payload: parsed,\n    };\n  }\n\n  if (parsed.type === \"error\" || parsed.error || parsed.code) {\n    const message =\n      (typeof parsed.error === \"string\" && parsed.error) ||\n      (typeof parsed.message === \"string\" && parsed.message) ||\n      defaultExecutionError;\n    return {\n      kind: \"error\",\n      message,\n      errorCode: typeof parsed.errorCode === \"string\" ? parsed.errorCode : null,\n      code: parsed.code,\n    };\n  }\n\n  return { kind: \"invalid\", reason: \"unrecognized\", payload: parsed };\n}\n\nexport interface AnalyticsSseHandlerContext {\n  source: \"useAnalyticsQuery\" | \"useMetricView\";\n  resource: Record<string, unknown>;\n  defaultExecutionError: string;\n  unpublishOnMalformedMessage: boolean;\n  signal: AbortSignal;\n  abort: () => void;\n  setLoading: (loading: boolean) => void;\n  setError: (error: string | null) => void;\n  setErrorCode: (code: string | null) => void;\n  onWarehouseStatus: (status: WarehouseStatus) => void;\n  onResult: (message: AnalyticsSseResultMessage) => void;\n  unpublishWarehouseStatus: () => void;\n}\n\nfunction failWithGenericError(ctx: AnalyticsSseHandlerContext): void {\n  ctx.setLoading(false);\n  ctx.setError(GENERIC_LOAD_ERROR);\n  ctx.unpublishWarehouseStatus();\n}\n\n/**\n * Apply the state transitions shared by analytics-query and metric-view SSE\n * messages while delegating their distinct result/status state to callbacks.\n */\nexport async function handleAnalyticsSseMessage(\n  data: string,\n  ctx: AnalyticsSseHandlerContext,\n): Promise<void> {\n  if (ctx.signal.aborted) return;\n\n  try {\n    const message = parseAnalyticsSseMessage(data, ctx.defaultExecutionError);\n\n    if (message.kind === \"warehouse-status\") {\n      ctx.onWarehouseStatus(message.status);\n      return;\n    }\n\n    if (message.kind === \"result\") {\n      ctx.setLoading(false);\n      ctx.onResult(message);\n      ctx.unpublishWarehouseStatus();\n      return;\n    }\n\n    if (message.kind === \"error\") {\n      ctx.setLoading(false);\n      ctx.setError(message.message);\n      ctx.unpublishWarehouseStatus();\n      if (message.errorCode !== null) {\n        ctx.setErrorCode(message.errorCode);\n      }\n      if (message.code) {\n        console.error(\n          `[${ctx.source}] Code: ${String(message.code)}, Message: ${message.message}`,\n        );\n      }\n      return;\n    }\n\n    if (message.reason === \"malformed-warehouse-status\") {\n      console.error(\n        `[${ctx.source}] Malformed warehouse_status event`,\n        message.payload,\n      );\n    } else {\n      console.error(\n        `[${ctx.source}] Unrecognized SSE payload`,\n        message.payload,\n      );\n    }\n    failWithGenericError(ctx);\n  } catch (error) {\n    console.warn(`[${ctx.source}] Malformed message received`, error);\n    ctx.setLoading(false);\n    ctx.setError(GENERIC_LOAD_ERROR);\n    if (ctx.unpublishOnMalformedMessage) {\n      ctx.unpublishWarehouseStatus();\n    }\n    ctx.abort();\n  }\n}\n\n/** Apply the shared terminal state for an SSE connection failure. */\nexport function handleAnalyticsSseError(\n  error: unknown,\n  ctx: AnalyticsSseHandlerContext,\n): void {\n  if (ctx.signal.aborted) return;\n\n  ctx.setLoading(false);\n  ctx.unpublishWarehouseStatus();\n\n  if (error instanceof Error) {\n    console.error(`[${ctx.source}] Error`, {\n      ...ctx.resource,\n      error: error.message,\n      stack: error.stack,\n    });\n  }\n  ctx.setError(userFacingFetchError(error));\n}\n"],"mappings":"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"}

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

@@ -1,9 +1,12 @@
-import { AnalyticsFormat, InferResultByFormat, InferRowType, InferServingChunk, InferServingRequest, InferServingResponse, MetricRegistry, PluginRegistry, QueryRegistry, ServingAlias, ServingEndpointRegistry, TypedArrowTable, UseAnalyticsQueryOptions, UseAnalyticsQueryResult, WarehouseState, WarehouseStatus } from "./types.js";
+import { MetricFilter, MetricFilterOperatorName, MetricOrderBy, MetricOrderDirection, MetricPredicate } from "../../shared/src/metric-filter.js";
+import { MetricViewColumnDisplay } from "../../shared/src/metric-metadata.js";
+import { AnalyticsFormat, GrainsForSelectedTimeDims, InferDimensionKeys, InferMeasureKeys, InferMetricRow, InferResultByFormat, InferRowType, InferServingChunk, InferServingRequest, InferServingResponse, InferTimeDimensionKeys, InferTimeGrains, MetricKey, MetricRegistry, PickMetricRow, PluginRegistry, QueryRegistry, ServingAlias, ServingEndpointRegistry, TypedArrowTable, UseAnalyticsQueryOptions, UseAnalyticsQueryResult, UseMetricViewOptions, UseMetricViewResult, WarehouseState, WarehouseStatus } from "./types.js";
 import { UseChartDataOptions, UseChartDataResult, useChartData } from "./use-chart-data.js";
 import { AggregatedResourceStatus, ResourceSeverity, ResourceStatus, ResourceStatusFilter, ResourceStatusProvider, ResourceStatusProviderProps, useResourceStatus, useResourceStatusPublisher } from "./use-resource-status.js";
 import { ResourceKindRenderer, ResourceStatusIndicator, ResourceStatusIndicatorProps, ResourceStatusToasterOptions, useResourceStatusToaster } from "../resource-status-indicator.js";
 import { AgentChatEvent, UseAgentChatOptions, UseAgentChatResult, useAgentChat } from "./use-agent-chat.js";
 import { useAnalyticsQuery } from "./use-analytics-query.js";
+import { useMetricView } from "./use-metric-view.js";
 import { useIsMobile } from "./use-mobile.js";
 import { usePluginClientConfig } from "./use-plugin-config.js";
 import { UseServingInvokeOptions, UseServingInvokeResult, useServingInvoke } from "./use-serving-invoke.js";