@databricks/appkit-ui 0.0.2

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

@@ -0,0 +1,160 @@
+import { Table } from "apache-arrow";
+
+//#region src/react/charts/types.d.ts
+/** Supported data formats for analytics queries */
+type DataFormat = "json" | "arrow" | "auto";
+/** Chart orientation */
+type Orientation = "vertical" | "horizontal";
+/** Supported chart types */
+type ChartType = "bar" | "line" | "area" | "pie" | "donut" | "scatter" | "radar" | "heatmap";
+/** Data that can be passed to unified charts */
+type ChartData = Table | Record<string, unknown>[];
+/** Color palette types for different visualization needs */
+type ChartColorPalette = "categorical" | "sequential" | "diverging";
+/** Common visual and behavior props for all charts */
+interface ChartBaseProps {
+  /** Chart title */
+  title?: string;
+  /** Show legend */
+  showLegend?: boolean;
+  /**
+   * Color palette to use. Auto-selected based on chart type if not specified.
+   * - "categorical": Distinct colors for different categories (bar, pie, line)
+   * - "sequential": Gradient for magnitude/intensity (heatmap)
+   * - "diverging": Two-tone for positive/negative values
+   */
+  colorPalette?: ChartColorPalette;
+  /** Custom colors for series (overrides colorPalette) */
+  colors?: string[];
+  /** Chart height in pixels @default 300 */
+  height?: number;
+  /** Additional CSS classes */
+  className?: string;
+  /** X-axis field key. Auto-detected from schema if not provided. */
+  xKey?: string;
+  /** Y-axis field key(s). Auto-detected from schema if not provided. */
+  yKey?: string | string[];
+  /** Accessibility label for screen readers */
+  ariaLabel?: string;
+  /** Test ID for automated testing */
+  testId?: string;
+  /** Additional ECharts options to merge */
+  options?: Record<string, unknown>;
+}
+/** Props for query-based data fetching */
+interface QueryProps extends ChartBaseProps {
+  /** Analytics query key registered with analytics plugin */
+  queryKey: string;
+  /** Query parameters passed to the analytics endpoint */
+  parameters?: Record<string, unknown>;
+  /**
+   * Data format to use
+   * - "json": Use JSON format (smaller payloads, simpler)
+   * - "arrow": Use Arrow format (faster for large datasets)
+   * - "auto": Automatically select based on expected data size
+   * @default "auto"
+   */
+  format?: DataFormat;
+  /** Transform raw data before rendering */
+  transformer?: <T>(data: T) => T;
+  data?: never;
+}
+/** Props for direct data injection */
+interface DataProps extends ChartBaseProps {
+  /** Arrow Table or JSON array */
+  data: ChartData;
+  queryKey?: never;
+  parameters?: never;
+  format?: never;
+  transformer?: never;
+}
+/** Base union type - either query-based or data-based */
+type UnifiedChartProps = QueryProps | DataProps;
+/** Props specific to bar charts */
+interface BarChartSpecificProps {
+  /** Chart orientation @default "vertical" */
+  orientation?: Orientation;
+  /** Stack bars */
+  stacked?: boolean;
+}
+/** Props specific to line charts */
+interface LineChartSpecificProps {
+  /** Chart orientation @default "vertical" */
+  orientation?: Orientation;
+  /** Show data point symbols @default false */
+  showSymbol?: boolean;
+  /** Smooth line curves @default true */
+  smooth?: boolean;
+}
+/** Props specific to area charts */
+interface AreaChartSpecificProps {
+  /** Chart orientation @default "vertical" */
+  orientation?: Orientation;
+  /** Show data point symbols @default false */
+  showSymbol?: boolean;
+  /** Smooth line curves @default true */
+  smooth?: boolean;
+  /** Stack areas @default false */
+  stacked?: boolean;
+}
+/** Props specific to scatter charts */
+interface ScatterChartSpecificProps {
+  /** Symbol size @default 8 */
+  symbolSize?: number;
+}
+/** Props specific to pie/donut charts */
+interface PieChartSpecificProps {
+  /** Inner radius for donut charts (0-100%) @default 0 */
+  innerRadius?: number;
+  /** Show labels on slices @default true */
+  showLabels?: boolean;
+  /** Label position @default "outside" */
+  labelPosition?: "outside" | "inside" | "center";
+}
+/** Props specific to radar charts */
+interface RadarChartSpecificProps {
+  /** Show area fill @default true */
+  showArea?: boolean;
+}
+/** Props specific to heatmap charts */
+interface HeatmapChartSpecificProps {
+  /**
+   * Field key for the Y-axis categories.
+   * For heatmaps, data should have: xKey (column), yAxisKey (row), and yKey (value).
+   */
+  yAxisKey?: string;
+  /** Min value for color scale (auto-detected if not provided) */
+  min?: number;
+  /** Max value for color scale (auto-detected if not provided) */
+  max?: number;
+  /** Show value labels on cells @default false */
+  showLabels?: boolean;
+}
+type BarChartProps = (QueryProps | DataProps) & BarChartSpecificProps;
+type LineChartProps = (QueryProps | DataProps) & LineChartSpecificProps;
+type AreaChartProps = (QueryProps | DataProps) & AreaChartSpecificProps;
+type ScatterChartProps = (QueryProps | DataProps) & ScatterChartSpecificProps;
+type PieChartProps = (QueryProps | DataProps) & PieChartSpecificProps;
+type DonutChartProps = (QueryProps | DataProps) & PieChartSpecificProps;
+type RadarChartProps = (QueryProps | DataProps) & RadarChartSpecificProps;
+type HeatmapChartProps = (QueryProps | DataProps) & HeatmapChartSpecificProps;
+/** Base normalized data shared by all chart types */
+interface NormalizedChartDataBase {
+  xData: (string | number)[];
+  xField: string;
+  yFields: string[];
+  chartType: "timeseries" | "categorical";
+}
+/** Normalized chart data for rendering (standard charts) */
+interface NormalizedChartData extends NormalizedChartDataBase {
+  yDataMap: Record<string, (string | number)[]>;
+}
+/** Type guard to check if data is an Arrow Table */
+declare function isArrowTable(data: ChartData): data is Table;
+/** Type guard to check if props are query-based */
+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, 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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/charts/types.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/react/charts/types.js

@@ -0,0 +1,17 @@
+//#region src/react/charts/types.ts
+/** Type guard to check if data is an Arrow Table */
+function isArrowTable(data) {
+	return data !== null && typeof data === "object" && "schema" in data && "numRows" in data && typeof data.getChild === "function";
+}
+/** Type guard to check if props are query-based */
+function isQueryProps(props) {
+	return "queryKey" in props && typeof props.queryKey === "string" && props.queryKey.length > 0;
+}
+/** Type guard to check if props are data-based */
+function isDataProps(props) {
+	return "data" in props && props.data != null;
+}
+
+//#endregion
+export { isArrowTable, isDataProps, isQueryProps };
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +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/** Supported data formats for analytics queries */\nexport type DataFormat = \"json\" | \"arrow\" | \"auto\";\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/** 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\": Use JSON format (smaller payloads, simpler)\n   * - \"arrow\": 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\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":";;AA4NA,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

@@ -0,0 +1,36 @@
+//#region src/react/charts/utils.d.ts
+/**
+ * Converts a value to a chart-compatible type.
+ * Handles BigInt conversion (Arrow can return BigInt64Array values).
+ * Handles Date objects by converting to timestamps.
+ */
+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.
+ */
+declare function truncateLabel(value: string, maxLength?: number): string;
+/**
+ * Creates time-series data pairs for ECharts.
+ */
+declare function createTimeSeriesData(xData: (string | number)[], yData: (string | number)[]): [string | number, string | number][];
+/**
+ * Sorts time-series data in ascending chronological 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 };
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","names":[],"sources":["../../../src/react/charts/utils.ts"],"sourcesContent":[],"mappings":";;AASA;AAmBA;AAWA;AAqBA;AAOgB,iBA1DA,YAAA,CA0DoB,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA,GAAA,MAAA;AAepC;;;AAMY,iBA5DI,YAAA,CA4DJ,IAAA,EAAA,OAAA,EAAA,CAAA,EAAA,CAAA,MAAA,GAAA,MAAA,CAAA,EAAA;;;;;;;iBAjDI,WAAA;;;;iBAqBA,aAAA;;;;iBAOA,oBAAA;;;;iBAeA,uBAAA,uCAEJ;;YAIA"}

package/dist/react/charts/utils.js

@@ -0,0 +1,77 @@
+//#region src/react/charts/utils.ts
+/**
+* Converts a value to a chart-compatible type.
+* Handles BigInt conversion (Arrow can return BigInt64Array values).
+* Handles Date objects by converting to timestamps.
+*/
+function toChartValue(value) {
+	if (value === null || value === void 0) return 0;
+	if (typeof value === "bigint") return Number(value);
+	if (value instanceof Date) return value.getTime();
+	if (typeof value === "string" || typeof value === "number") return value;
+	return String(value);
+}
+/**
+* Converts an array of values to chart-compatible types.
+*/
+function toChartArray(data) {
+	if (data.length === 0) return [];
+	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();
+}
+/**
+* Truncates a label to a maximum length with ellipsis.
+*/
+function truncateLabel(value, maxLength = 15) {
+	return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;
+}
+/**
+* Creates time-series data pairs for ECharts.
+*/
+function createTimeSeriesData(xData, yData) {
+	const len = xData.length;
+	const result = new Array(len);
+	for (let i = 0; i < len; i++) result[i] = [xData[i], yData[i]];
+	return result;
+}
+/**
+* Sorts time-series data in ascending chronological 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 {
+		xData,
+		yDataMap
+	};
+}
+
+//#endregion
+export { createTimeSeriesData, formatLabel, sortTimeSeriesAscending, toChartArray, toChartValue, truncateLabel };
+//# sourceMappingURL=utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":["result: [string | number, string | number][]","sortedYDataMap: Record<string, (string | number)[]>"],"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 * 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 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;;;;;AAOb,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,MAAMA,SAA+C,IAAI,MAAM,IAAI;AACnE,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,IACvB,QAAO,KAAK,CAAC,MAAM,IAAI,MAAM,GAAG;AAElC,QAAO;;;;;AAMT,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,MAAMC,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"}

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

@@ -0,0 +1,65 @@
+import { ChartData, DataFormat } from "./types.js";
+import { ReactNode } from "react";
+import * as react_jsx_runtime284 from "react/jsx-runtime";
+
+//#region src/react/charts/wrapper.d.ts
+interface ChartWrapperQueryProps {
+  /** Analytics query key */
+  queryKey: string;
+  /** Query parameters */
+  parameters?: Record<string, unknown>;
+  /** Data format preference */
+  format?: DataFormat;
+  /** Transform data after fetching */
+  transformer?: <T>(data: T) => T;
+  /** Direct data - not used in query mode */
+  data?: never;
+}
+interface ChartWrapperDataProps {
+  /** Direct data (Arrow Table or JSON array) */
+  data: ChartData;
+  /** Not used in data mode */
+  queryKey?: never;
+  parameters?: never;
+  format?: never;
+  transformer?: never;
+}
+interface CommonProps {
+  /** Chart height in pixels */
+  height?: number;
+  /** Additional CSS classes */
+  className?: string;
+  /** Accessibility label */
+  ariaLabel?: string;
+  /** Test ID for automated testing */
+  testId?: string;
+  /** Render function receiving the chart data */
+  children: (data: ChartData) => ReactNode;
+}
+type ChartWrapperProps = CommonProps & (ChartWrapperQueryProps | ChartWrapperDataProps);
+/**
+ * Wrapper component for charts.
+ * Handles data fetching (query mode) or direct data injection (data mode).
+ *
+ * @example Query mode - fetches data from analytics endpoint
+ * ```tsx
+ * <ChartWrapper
+ *   queryKey="spend_data"
+ *   parameters={{ limit: 100 }}
+ *   format="auto"
+ * >
+ *   {(data) => <MyChart data={data} />}
+ * </ChartWrapper>
+ * ```
+ *
+ * @example Data mode - uses provided data directly
+ * ```tsx
+ * <ChartWrapper data={myArrowTable}>
+ *   {(data) => <MyChart data={data} />}
+ * </ChartWrapper>
+ * ```
+ */
+declare function ChartWrapper(props: ChartWrapperProps): react_jsx_runtime284.JSX.Element;
+//#endregion
+export { ChartWrapper, ChartWrapperProps };
+//# sourceMappingURL=wrapper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","names":[],"sources":["../../../src/react/charts/wrapper.tsx"],"sourcesContent":[],"mappings":";;;;;UAaU,sBAAA;;;EAAA;EAAsB,UAAA,CAAA,EAIjB,MAJiB,CAAA,MAAA,EAAA,OAAA,CAAA;;QAMrB,CAAA,EAAA,UAAA;;aAEqB,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,IAAA,EAAN,CAAM,EAAA,GAAA,CAAA;EAAC;EAKvB,IAAA,CAAA,EAAA,KAAA;AAEO;UAFP,qBAAA,CAUW;;MAUY,EAlBzB,SAkByB;EAAS;EAG9B,QAAA,CAAA,EAAA,KAAA;EAAiB,UAAA,CAAA,EAAA,KAAA;QAAG,CAAA,EAAA,KAAA;aAC7B,CAAA,EAAA,KAAA;;UAdO,WAAA,CAcuC;EA0GjC;EAAY,MAAA,CAAA,EAAA,MAAA;;WAAyB,CAAA,EAAA,MAAA;EAAA;;;;;mBA9GlC,cAAc;;KAGrB,iBAAA,GAAoB,eAC7B,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;iBA0GZ,YAAA,QAAoB,oBAAiB,oBAAA,CAAA,GAAA,CAAA"}

package/dist/react/charts/wrapper.js

@@ -0,0 +1,94 @@
+import { isArrowTable } from "./types.js";
+import { useChartData } from "../hooks/use-chart-data.js";
+import { ChartErrorBoundary } from "./chart-error-boundary.js";
+import { EmptyState } from "./empty.js";
+import { ErrorState } from "./error.js";
+import { LoadingSkeleton } from "./loading.js";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react/charts/wrapper.tsx
+function QueryModeContent({ queryKey, parameters, format, transformer, height, className, ariaLabel, testId, children }) {
+	const { data, loading, error, isEmpty } = useChartData({
+		queryKey,
+		parameters,
+		format,
+		transformer
+	});
+	if (loading) return /* @__PURE__ */ jsx(LoadingSkeleton, { height: height ?? 300 });
+	if (error) return /* @__PURE__ */ jsx(ErrorState, { error });
+	if (isEmpty || !data) return /* @__PURE__ */ jsx(EmptyState, {});
+	return /* @__PURE__ */ jsx(ChartErrorBoundary, {
+		fallback: /* @__PURE__ */ jsx(ErrorState, { error: "Failed to render chart" }),
+		children: /* @__PURE__ */ jsx("div", {
+			className,
+			style: { height },
+			"aria-label": ariaLabel,
+			"data-testid": testId,
+			role: "img",
+			children: children(data)
+		})
+	});
+}
+function DataModeContent({ data, height, className, ariaLabel, testId, children }) {
+	if (isArrowTable(data) ? data.numRows === 0 : !Array.isArray(data) || data.length === 0) return /* @__PURE__ */ jsx(EmptyState, {});
+	return /* @__PURE__ */ jsx(ChartErrorBoundary, {
+		fallback: /* @__PURE__ */ jsx(ErrorState, { error: "Failed to render chart" }),
+		children: /* @__PURE__ */ jsx("div", {
+			className,
+			style: { height },
+			"aria-label": ariaLabel,
+			"data-testid": testId,
+			role: "img",
+			children: children(data)
+		})
+	});
+}
+/**
+* Wrapper component for charts.
+* Handles data fetching (query mode) or direct data injection (data mode).
+*
+* @example Query mode - fetches data from analytics endpoint
+* ```tsx
+* <ChartWrapper
+*   queryKey="spend_data"
+*   parameters={{ limit: 100 }}
+*   format="auto"
+* >
+*   {(data) => <MyChart data={data} />}
+* </ChartWrapper>
+* ```
+*
+* @example Data mode - uses provided data directly
+* ```tsx
+* <ChartWrapper data={myArrowTable}>
+*   {(data) => <MyChart data={data} />}
+* </ChartWrapper>
+* ```
+*/
+function ChartWrapper(props) {
+	const { height = 300, className, ariaLabel, testId, children } = props;
+	if ("data" in props && props.data !== void 0) return /* @__PURE__ */ jsx(DataModeContent, {
+		data: props.data,
+		height,
+		className,
+		ariaLabel,
+		testId,
+		children
+	});
+	if ("queryKey" in props && props.queryKey !== void 0) return /* @__PURE__ */ jsx(QueryModeContent, {
+		queryKey: props.queryKey,
+		parameters: props.parameters,
+		format: props.format,
+		transformer: props.transformer,
+		height,
+		className,
+		ariaLabel,
+		testId,
+		children
+	});
+	return /* @__PURE__ */ jsx(ErrorState, { error: "Chart requires either 'queryKey' or 'data' prop" });
+}
+
+//#endregion
+export { ChartWrapper };
+//# sourceMappingURL=wrapper.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.js","names":[],"sources":["../../../src/react/charts/wrapper.tsx"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { useChartData } from \"../hooks/use-chart-data\";\nimport { ChartErrorBoundary } from \"./chart-error-boundary\";\nimport { EmptyState } from \"./empty\";\nimport { ErrorState } from \"./error\";\nimport { LoadingSkeleton } from \"./loading\";\nimport type { ChartData, DataFormat } from \"./types\";\nimport { isArrowTable } from \"./types\";\n\n// ============================================================================\n// Props Types\n// ============================================================================\n\ninterface ChartWrapperQueryProps {\n  /** Analytics query key */\n  queryKey: string;\n  /** Query parameters */\n  parameters?: Record<string, unknown>;\n  /** Data format preference */\n  format?: DataFormat;\n  /** Transform data after fetching */\n  transformer?: <T>(data: T) => T;\n  /** Direct data - not used in query mode */\n  data?: never;\n}\n\ninterface ChartWrapperDataProps {\n  /** Direct data (Arrow Table or JSON array) */\n  data: ChartData;\n  /** Not used in data mode */\n  queryKey?: never;\n  parameters?: never;\n  format?: never;\n  transformer?: never;\n}\n\ninterface CommonProps {\n  /** Chart height in pixels */\n  height?: number;\n  /** Additional CSS classes */\n  className?: string;\n  /** Accessibility label */\n  ariaLabel?: string;\n  /** Test ID for automated testing */\n  testId?: string;\n  /** Render function receiving the chart data */\n  children: (data: ChartData) => ReactNode;\n}\n\nexport type ChartWrapperProps = CommonProps &\n  (ChartWrapperQueryProps | ChartWrapperDataProps);\n\n// ============================================================================\n// Query Mode Content\n// ============================================================================\n\nfunction QueryModeContent({\n  queryKey,\n  parameters,\n  format,\n  transformer,\n  height,\n  className,\n  ariaLabel,\n  testId,\n  children,\n}: CommonProps & ChartWrapperQueryProps) {\n  const { data, loading, error, isEmpty } = useChartData({\n    queryKey,\n    parameters,\n    format,\n    transformer,\n  });\n\n  if (loading) return <LoadingSkeleton height={height ?? 300} />;\n  if (error) return <ErrorState error={error} />;\n  if (isEmpty || !data) return <EmptyState />;\n\n  return (\n    <ChartErrorBoundary\n      fallback={<ErrorState error=\"Failed to render chart\" />}\n    >\n      <div\n        className={className}\n        style={{ height }}\n        aria-label={ariaLabel}\n        data-testid={testId}\n        role=\"img\"\n      >\n        {children(data)}\n      </div>\n    </ChartErrorBoundary>\n  );\n}\n\n// ============================================================================\n// Data Mode Content\n// ============================================================================\n\nfunction DataModeContent({\n  data,\n  height,\n  className,\n  ariaLabel,\n  testId,\n  children,\n}: CommonProps & ChartWrapperDataProps) {\n  const isEmpty = isArrowTable(data)\n    ? data.numRows === 0\n    : !Array.isArray(data) || data.length === 0;\n\n  if (isEmpty) return <EmptyState />;\n\n  return (\n    <ChartErrorBoundary\n      fallback={<ErrorState error=\"Failed to render chart\" />}\n    >\n      <div\n        className={className}\n        style={{ height }}\n        aria-label={ariaLabel}\n        data-testid={testId}\n        role=\"img\"\n      >\n        {children(data)}\n      </div>\n    </ChartErrorBoundary>\n  );\n}\n\n// ============================================================================\n// Main Wrapper Component\n// ============================================================================\n\n/**\n * Wrapper component for charts.\n * Handles data fetching (query mode) or direct data injection (data mode).\n *\n * @example Query mode - fetches data from analytics endpoint\n * ```tsx\n * <ChartWrapper\n *   queryKey=\"spend_data\"\n *   parameters={{ limit: 100 }}\n *   format=\"auto\"\n * >\n *   {(data) => <MyChart data={data} />}\n * </ChartWrapper>\n * ```\n *\n * @example Data mode - uses provided data directly\n * ```tsx\n * <ChartWrapper data={myArrowTable}>\n *   {(data) => <MyChart data={data} />}\n * </ChartWrapper>\n * ```\n */\nexport function ChartWrapper(props: ChartWrapperProps) {\n  const { height = 300, className, ariaLabel, testId, children } = props;\n\n  // Data mode: use provided data directly\n  if (\"data\" in props && props.data !== undefined) {\n    return (\n      <DataModeContent\n        data={props.data}\n        height={height}\n        className={className}\n        ariaLabel={ariaLabel}\n        testId={testId}\n      >\n        {children}\n      </DataModeContent>\n    );\n  }\n\n  // Query mode: fetch data from analytics endpoint\n  if (\"queryKey\" in props && props.queryKey !== undefined) {\n    return (\n      <QueryModeContent\n        queryKey={props.queryKey}\n        parameters={props.parameters}\n        format={props.format}\n        transformer={props.transformer}\n        height={height}\n        className={className}\n        ariaLabel={ariaLabel}\n        testId={testId}\n      >\n        {children}\n      </QueryModeContent>\n    );\n  }\n\n  // Should never reach here due to TypeScript, but safety fallback\n  return <ErrorState error=\"Chart requires either 'queryKey' or 'data' prop\" />;\n}\n"],"mappings":";;;;;;;;;AAwDA,SAAS,iBAAiB,EACxB,UACA,YACA,QACA,aACA,QACA,WACA,WACA,QACA,YACuC;CACvC,MAAM,EAAE,MAAM,SAAS,OAAO,YAAY,aAAa;EACrD;EACA;EACA;EACA;EACD,CAAC;AAEF,KAAI,QAAS,QAAO,oBAAC,mBAAgB,QAAQ,UAAU,MAAO;AAC9D,KAAI,MAAO,QAAO,oBAAC,cAAkB,QAAS;AAC9C,KAAI,WAAW,CAAC,KAAM,QAAO,oBAAC,eAAa;AAE3C,QACE,oBAAC;EACC,UAAU,oBAAC,cAAW,OAAM,2BAA2B;YAEvD,oBAAC;GACY;GACX,OAAO,EAAE,QAAQ;GACjB,cAAY;GACZ,eAAa;GACb,MAAK;aAEJ,SAAS,KAAK;IACX;GACa;;AAQzB,SAAS,gBAAgB,EACvB,MACA,QACA,WACA,WACA,QACA,YACsC;AAKtC,KAJgB,aAAa,KAAK,GAC9B,KAAK,YAAY,IACjB,CAAC,MAAM,QAAQ,KAAK,IAAI,KAAK,WAAW,EAE/B,QAAO,oBAAC,eAAa;AAElC,QACE,oBAAC;EACC,UAAU,oBAAC,cAAW,OAAM,2BAA2B;YAEvD,oBAAC;GACY;GACX,OAAO,EAAE,QAAQ;GACjB,cAAY;GACZ,eAAa;GACb,MAAK;aAEJ,SAAS,KAAK;IACX;GACa;;;;;;;;;;;;;;;;;;;;;;;;AA8BzB,SAAgB,aAAa,OAA0B;CACrD,MAAM,EAAE,SAAS,KAAK,WAAW,WAAW,QAAQ,aAAa;AAGjE,KAAI,UAAU,SAAS,MAAM,SAAS,OACpC,QACE,oBAAC;EACC,MAAM,MAAM;EACJ;EACG;EACA;EACH;EAEP;GACe;AAKtB,KAAI,cAAc,SAAS,MAAM,aAAa,OAC5C,QACE,oBAAC;EACC,UAAU,MAAM;EAChB,YAAY,MAAM;EAClB,QAAQ,MAAM;EACd,aAAa,MAAM;EACX;EACG;EACA;EACH;EAEP;GACgB;AAKvB,QAAO,oBAAC,cAAW,OAAM,oDAAoD"}

package/dist/react/hooks/index.js

@@ -0,0 +1,2 @@
+import { useAnalyticsQuery } from "./use-analytics-query.js";
+import { useChartData } from "./use-chart-data.js";

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

@@ -0,0 +1,101 @@
+import { Table } from "apache-arrow";
+
+//#region src/react/hooks/types.d.ts
+/** Supported response formats for analytics queries */
+type AnalyticsFormat = "JSON" | "ARROW";
+/**
+ * Typed Arrow Table - preserves row type information for type inference.
+ * At runtime this is just a regular Arrow Table, but TypeScript knows the row schema.
+ *
+ * @example
+ * ```typescript
+ * type MyTable = TypedArrowTable<{ id: string; value: number }>;
+ * // Can access table.getChild("id") knowing it exists
+ * ```
+ */
+interface TypedArrowTable<TRow extends Record<string, unknown> = Record<string, unknown>> extends Table {
+  /**
+   * Phantom type marker for row schema.
+   * Not used at runtime - only for TypeScript type inference.
+   */
+  readonly __rowType?: TRow;
+}
+/** Options for configuring an analytics SSE query */
+interface UseAnalyticsQueryOptions<F extends AnalyticsFormat = "JSON"> {
+  /** Response format - "JSON" returns typed arrays, "ARROW" returns TypedArrowTable */
+  format?: F;
+  /** Maximum size of serialized parameters in bytes */
+  maxParametersSize?: number;
+  /** Whether to automatically start the query when the hook is mounted. Default is true. */
+  autoStart?: boolean;
+}
+/** Result state returned by useAnalyticsQuery */
+interface UseAnalyticsQueryResult<T> {
+  /** Latest query result data */
+  data: T | null;
+  /** Loading state of the query */
+  loading: boolean;
+  /** Error state of the query */
+  error: string | null;
+}
+/**
+ * Query Registry for type-safe analytics queries.
+ * Extend this interface via module augmentation to get full type inference:
+ *
+ * @example
+ * ```typescript
+ * // config/appKitTypes.d.ts
+ * declare module "@databricks/appkit-ui/react" {
+ *   interface QueryRegistry {
+ *     apps_list: {
+ *       name: "apps_list";
+ *       parameters: { startDate: string; endDate: string; aggregationLevel: string };
+ *       result: Array<{ id: string; name: string }>;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface QueryRegistry {
+  [key: string]: {
+    name: string;
+    parameters: Record<string, unknown>;
+    result: unknown[];
+  };
+}
+/** Gets only literal keys from a registry (excludes index signature) */
+type AugmentedRegistry<T> = keyof { [K in keyof T as string extends K ? never : K]: T[K] };
+/** Resolves to registry keys if defined, otherwise string */
+type QueryKey = AugmentedRegistry<QueryRegistry> extends never ? string : AugmentedRegistry<QueryRegistry>;
+/**
+ * Infers result type from QueryRegistry[K]["result"]
+ * Returns the JSON array type for the query.
+ */
+type InferResult<T, K> = K extends AugmentedRegistry<QueryRegistry> ? QueryRegistry[K] extends {
+  result: infer R;
+} ? R : T : T;
+/**
+ * Infers the row type from a query result array.
+ * Used for TypedArrowTable row typing.
+ */
+type InferRowType<K> = K extends AugmentedRegistry<QueryRegistry> ? QueryRegistry[K] extends {
+  result: Array<infer R>;
+} ? R extends Record<string, unknown> ? R : Record<string, unknown> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Conditionally infers result type based on format.
+ * - JSON format: Returns the typed array from QueryRegistry
+ * - ARROW format: Returns TypedArrowTable with row type preserved
+ */
+type InferResultByFormat<T, K, F extends AnalyticsFormat> = F extends "ARROW" ? TypedArrowTable<InferRowType<K>> : InferResult<T, K>;
+/**
+ * Infers parameters type from QueryRegistry[K]["parameters"]
+ */
+type InferParams<K> = K extends AugmentedRegistry<QueryRegistry> ? QueryRegistry[K] extends {
+  parameters: infer P;
+} ? P : Record<string, unknown> : Record<string, unknown>;
+interface PluginRegistry {
+  [key: string]: Record<string, any>;
+}
+//#endregion
+export { AnalyticsFormat, InferParams, InferResultByFormat, InferRowType, PluginRegistry, QueryKey, QueryRegistry, TypedArrowTable, UseAnalyticsQueryOptions, UseAnalyticsQueryResult };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/hooks/types.ts"],"sourcesContent":[],"mappings":";;;;KAOY,eAAA;AAAZ;AAYA;;;;;;;AAeA;;AAAoD,UAfnC,eAemC,CAAA,aAdrC,MAcqC,CAAA,MAAA,EAAA,OAAA,CAAA,GAdX,MAcW,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,SAb1C,KAa0C,CAAA;;;AAYpD;AA2BA;EASY,SAAA,SAAA,CAAA,EAxDW,IAwDM;;;AACK,UAjDjB,wBAiDiB,CAAA,UAjDkB,eAiDlB,GAAA,MAAA,CAAA,CAAA;;QAAgB,CAAA,EA/CvC,CA+CuC;;EAAG,iBAAA,CAAA,EAAA,MAAA;EAIzC;EAAQ,SAAA,CAAA,EAAA,OAAA;;;AAEE,UA3CL,uBA2CK,CAAA,CAAA,CAAA,CAAA;;EAAD,IAAA,EAzCb,CAyCa,GAAA,IAAA;EAMT;EAAW,OAAA,EAAA,OAAA;;OAAqC,EAAA,MAAA,GAAA,IAAA;;;;;;;;AAU5D;;;;;;;;;;;;AAKM,UArCW,aAAA,CAqCX;MACF,EAAA,MAAA,CAAA,EAAA;IAAM,IAAA,EAAA,MAAA;IAOE,UAAA,EA1CI,MA0Ce,CAAA,MAAA,EAAA,OAAA,CAAA;IAAA,MAAA,EAAA,OAAA,EAAA;;;;AAIS,KAxC5B,iBAwC4B,CAAA,CAAA,CAAA,GAAA,MAAA,QAAhB,MAvCV,CAuCU,IAAA,MAAA,SAvCU,CAuCV,GAAA,KAAA,GAvCsB,CAuCtB,GAvC0B,CAuC1B,CAvC4B,CAuC5B,CAAA;;AAAmC,KAnC/C,QAAA,GAAW,iBAmCoC,CAnClB,aAmCkB,CAAA,SAAA,KAAA,GAAA,MAAA,GAjCvD,iBAiCuD,CAjCrC,aAiCqC,CAAA;;AAK3D;;;AAAyD,KAhC7C,WAgC6C,CAAA,CAAA,EAAA,CAAA,CAAA,GAhCzB,CAgCyB,SAhCf,iBAgCe,CAhCG,aAgCH,CAAA,GA/BrD,aA+BqD,CA/BvC,CA+BuC,CAAA,SAAA;QAAlB,EAAA,KAAA,EAAA;IA9BjC,IACA,CA8BF,GA7BA,CA6BA;;;;;AAGM,KA1BE,YA0BF,CAAA,CAAA,CAAA,GA1BoB,CA0BpB,SA1B8B,iBA0B9B,CA1BgD,aA0BhD,CAAA,GAzBN,aAyBM,CAzBQ,CAyBR,CAAA,SAAA;EAEO,MAAA,EA3BsB,KA2BtB,CAAA,KAAc,EAAA,CAAA;IA1BzB,UAAU,0BACR,IACA,0BACF,0BACF;;;;;;KAOQ,oCAGA,mBACR,oBAAoB,gBAAgB,aAAa,MAAM,YAAY,GAAG;;;;KAK9D,iBAAiB,UAAU,kBAAkB,iBACrD,cAAc;;IACZ,IACA,0BACF;UAEa,cAAA;iBACA"}