@finos/legend-query-builder 4.17.99 → 4.18.0

package/src/components/result/QueryBuilderResultPanel.tsx

@@ -727,10 +727,14 @@ export const QueryBuilderResultPanel = observer(
 
             {allowSettingPreviewLimit && (
               <div className="query-builder__result__limit">
-                <div className="query-builder__result__limit__label">
+                <label
+                  className="query-builder__result__limit__label"
+                  htmlFor="query-builder__result__preview-limit-input"
+                >
                   preview row limit
-                </div>
+                </label>
                 <input
+                  id="query-builder__result__preview-limit-input"
                   ref={inputRef}
                   className="input--dark query-builder__result__limit__input"
                   spellCheck={false}

package/src/components/result/tds/QueryBuilderTDSAsyncCellSelectionStats.ts

@@ -0,0 +1,254 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { type RefObject, useEffect, useRef, useState } from 'react';
+import type { TDSResultCellData, TDSRowDataType } from '@finos/legend-graph';
+import type { DataGridApi } from '@finos/legend-lego/data-grid';
+import {
+  computeCellSelectionStats,
+  type CellSelectionStats,
+} from './QueryBuilderTDSCellSelectionStats.js';
+
+/**
+ * Return type for useAsyncCellSelectionStats.
+ *
+ * When the hook returns non-undefined, the stats bar should be shown.
+ *
+ * - `cellCount` is 0 until Phase 1 (50 ms) resolves, then the actual count.
+ * - `countReady` is false while the count is still being debounced.
+ * - `stats` is undefined until Phase 2 (200 ms + rAF) resolves.
+ */
+export interface AsyncCellSelectionStatsResult {
+  /** Total selected cell count — 0 while Phase 1 debounce is pending. */
+  cellCount: number;
+  /** True once the 50 ms debounce has resolved and cellCount is accurate. */
+  countReady: boolean;
+  /** Fully-computed stats, or undefined while Phase 2 is pending. */
+  stats: CellSelectionStats | undefined;
+}
+
+/**
+ * Three-tier debounced stats hook for AG Grid enterprise cell-range selections.
+ *
+ * The hook is deliberately decoupled from the MobX `selectedCells` array.
+ * Instead it takes a lightweight `selectionVersion` counter that is
+ * incremented by `onCellSelectionChanged` (O(1)) and reads cell data lazily
+ * from the grid API only when the debounce timers fire.
+ *
+ * Immediate — when quickCount ≥ 2:
+ *   The bar is shown immediately with spinner placeholders for everything
+ *   (including the count).
+ *
+ * Phase 1 — COUNT_DEBOUNCE_MS (50 ms):
+ *   Reads `getCellRanges()` to get the cell count in O(ranges) time.
+ *   The count spinner is replaced with the actual number.
+ *
+ * Phase 2 — STATS_DEBOUNCE_MS (200 ms) + rAF paint guarantee:
+ *   Reads all cell values from the grid and calls `computeCellSelectionStats`.
+ *   The remaining spinners are replaced with computed values.
+ *
+ * Hiding is immediate: when selectionVersion changes and the count drops
+ * below 2, the panel is hidden synchronously.
+ */
+const COUNT_DEBOUNCE_MS = 50;
+const STATS_DEBOUNCE_MS = 200;
+
+/**
+ * Fast O(ranges) cell count — just sums rows×cols per range.
+ * May overcount with overlapping ranges but that's acceptable for the
+ * show-debounce decision (exact count comes later in readSelectedCells).
+ */
+const fastCellCount = (api: DataGridApi<TDSRowDataType>): number => {
+  try {
+    const ranges = api.getCellRanges();
+    if (!ranges || ranges.length === 0) {
+      return 0;
+    }
+    let total = 0;
+    for (const range of ranges) {
+      const start = range.startRow?.rowIndex ?? 0;
+      const end = range.endRow?.rowIndex ?? 0;
+      const rows = Math.abs(end - start) + 1;
+      total += rows * range.columns.length;
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+};
+
+/**
+ * Reads all selected cell values from the grid API — called lazily at stats
+ * time (Tier 2).  Complexity: O(rows) for the node map + O(cells) for the
+ * range iteration.
+ */
+const readSelectedCells = (
+  api: DataGridApi<TDSRowDataType>,
+): TDSResultCellData[] => {
+  const ranges = api.getCellRanges();
+  if (!ranges || ranges.length === 0) {
+    return [];
+  }
+  // Build a rowIndex → node map once in O(rows), then look up in O(1) per cell.
+  const nodeByRowIndex = new Map<number, TDSRowDataType>();
+  api.forEachNode((node) => {
+    if (node.rowIndex !== null && node.data) {
+      nodeByRowIndex.set(node.rowIndex, node.data);
+    }
+  });
+  // Build a colId → column-index map once in O(columns) instead of calling
+  // findIndex inside the inner loop (which would be O(cols) per cell).
+  // Uses getColumns() (runtime column state) rather than getColumnDefs() (input config).
+  const allColumns = api.getColumns() ?? [];
+  const colIndexByColId = new Map<string, number>();
+  allColumns.forEach((col, i) => {
+    colIndexByColId.set(col.getColId(), i);
+  });
+  const seen = new Map<string, TDSResultCellData>();
+  for (const range of ranges) {
+    const start = range.startRow?.rowIndex ?? 0;
+    const end = range.endRow?.rowIndex ?? 0;
+    const lo = Math.min(start, end);
+    const hi = Math.max(start, end);
+    for (let r = lo; r <= hi; r++) {
+      const rowData = nodeByRowIndex.get(r);
+      if (!rowData) {
+        continue;
+      }
+      for (const col of range.columns) {
+        const colId = col.getColId();
+        const key = `${r}|${colId}`;
+        if (!seen.has(key)) {
+          seen.set(key, {
+            value: (rowData as Record<string, unknown>)[colId],
+            columnName: colId,
+            coordinates: {
+              rowIndex: r,
+              colIndex: colIndexByColId.get(colId) ?? -1,
+            },
+          } as TDSResultCellData);
+        }
+      }
+    }
+  }
+  return Array.from(seen.values());
+};
+
+export const useAsyncCellSelectionStats = (
+  /** Incremented O(1) on every onCellSelectionChanged — never the full cell array. */
+  selectionVersion: number,
+  columnTypes: Map<string, string | undefined>,
+  gridApiRef: RefObject<DataGridApi<TDSRowDataType> | null>,
+  /** Fallback cell array used when gridApiRef.current is null (simple grid). */
+  fallbackCells?: TDSResultCellData[],
+): AsyncCellSelectionStatsResult | undefined => {
+  const [visible, setVisible] = useState(false);
+  const [cellCount, setCellCount] = useState(0);
+  const [countReady, setCountReady] = useState(false);
+  const [stats, setStats] = useState<CellSelectionStats | undefined>(undefined);
+
+  const columnTypesRef = useRef(columnTypes);
+  useEffect(() => {
+    columnTypesRef.current = columnTypes;
+  });
+
+  const fallbackCellsRef = useRef(fallbackCells);
+  useEffect(() => {
+    fallbackCellsRef.current = fallbackCells;
+  });
+
+  useEffect(() => {
+    const api = gridApiRef.current;
+
+    // Immediate check — O(ranges) or O(1) for fallback
+    const quickCount = api
+      ? fastCellCount(api)
+      : (fallbackCellsRef.current?.length ?? 0);
+
+    if (quickCount < 2) {
+      setVisible(false);
+      setCellCount(0);
+      setCountReady(false);
+      setStats(undefined);
+      return undefined;
+    }
+
+    // Immediate: show bar with all spinners (count included)
+    setVisible(true);
+    setCellCount(0);
+    setCountReady(false);
+    setStats(undefined);
+
+    let cancelled = false;
+
+    // Phase 1: resolve count after 50 ms debounce
+    const countId = globalThis.setTimeout(() => {
+      if (cancelled) {
+        return;
+      }
+      const currentApi = gridApiRef.current;
+      const count = currentApi
+        ? fastCellCount(currentApi)
+        : (fallbackCellsRef.current?.length ?? 0);
+      if (count >= 2) {
+        setCellCount(count);
+        setCountReady(true);
+      } else {
+        // Selection shrunk below 2 during debounce — hide
+        setVisible(false);
+        setCellCount(0);
+        setCountReady(false);
+      }
+    }, COUNT_DEBOUNCE_MS);
+
+    // Phase 2: read cells + compute stats after 200 ms, deferred past a paint
+    let rafId = 0;
+    const statsId = globalThis.setTimeout(() => {
+      if (cancelled) {
+        return;
+      }
+      rafId = requestAnimationFrame(() => {
+        if (cancelled) {
+          return;
+        }
+        const currentApi = gridApiRef.current;
+        const cells = currentApi
+          ? readSelectedCells(currentApi)
+          : (fallbackCellsRef.current ?? []);
+        const result = computeCellSelectionStats(cells, columnTypesRef.current);
+        // Also ensure count is accurate from the actual cell read
+        setCellCount(cells.length);
+        setCountReady(true);
+        setStats(result);
+      });
+    }, STATS_DEBOUNCE_MS);
+
+    return () => {
+      cancelled = true;
+      globalThis.clearTimeout(countId);
+      globalThis.clearTimeout(statsId);
+      if (rafId !== 0) {
+        cancelAnimationFrame(rafId);
+      }
+    };
+  }, [selectionVersion, gridApiRef]);
+
+  if (!visible) {
+    return undefined;
+  }
+
+  return { cellCount, countReady, stats };
+};

package/src/components/result/tds/QueryBuilderTDSCellSelectionStats.ts

@@ -0,0 +1,397 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { type TDSResultCellData, PRIMITIVE_TYPE } from '@finos/legend-graph';
+
+export interface ValueFrequency {
+  /** String representation of the value, or '(other)' / '(empty)' for synthetic buckets */
+  label: string;
+  count: number;
+  /** True for the synthetic '(other)' bucket */
+  isOther?: boolean;
+  /** True for the synthetic '(empty)' bucket */
+  isEmpty?: boolean;
+}
+
+export interface DistributionBucket {
+  /** Lower bound of the bucket (inclusive) */
+  lower: number;
+  /** Upper bound of the bucket (exclusive, except the last which is inclusive) */
+  upper: number;
+  /** Number of values that fall in this bucket */
+  count: number;
+  /** For date columns: human-readable label for lower bound */
+  lowerDateLabel?: string;
+  /** For date columns: human-readable label for upper bound */
+  upperDateLabel?: string;
+}
+
+/** Discriminates how the chart tooltip should describe bucket bounds */
+export type DistributionChartType = 'numeric' | 'string-length' | 'date';
+
+export interface CellSelectionStats {
+  count: number;
+  uniqueCount: number;
+  nullCount: number;
+  min: number | undefined;
+  max: number | undefined;
+  sum: number | undefined;
+  avg: number | undefined;
+  dateMin: string | undefined;
+  dateMax: string | undefined;
+  strMinLength: number | undefined;
+  strMaxLength: number | undefined;
+  /** Frequency distribution histogram buckets.
+   *  Computed for numeric, string (length), and date columns.
+   *  undefined for other types. */
+  distributionBuckets: DistributionBucket[] | undefined;
+  /** Describes what the bucket bounds represent, for tooltip formatting */
+  distributionChartType: DistributionChartType | undefined;
+  /** Top-10 value frequencies for the Unique Count tooltip, plus optional (other) */
+  valueFrequencies: ValueFrequency[] | undefined;
+}
+
+const NUMERIC_TYPES = new Set<string>([
+  PRIMITIVE_TYPE.INTEGER,
+  PRIMITIVE_TYPE.FLOAT,
+  PRIMITIVE_TYPE.DECIMAL,
+  PRIMITIVE_TYPE.NUMBER,
+]);
+
+const DATE_TYPES = new Set<string>([
+  PRIMITIVE_TYPE.DATE,
+  PRIMITIVE_TYPE.STRICTDATE,
+  PRIMITIVE_TYPE.DATETIME,
+]);
+
+const STRING_TYPES = new Set<string>([PRIMITIVE_TYPE.STRING]);
+
+const MAX_BUCKETS = 20;
+
+/**
+ * Build a frequency-distribution histogram for an array of numeric values.
+ * ...existing code...
+ */
+const computeDistribution = (values: number[]): DistributionBucket[] => {
+  if (values.length === 0) {
+    return [];
+  }
+
+  const dataMin = Math.min(...values);
+  const dataMax = Math.max(...values);
+  const range = dataMax - dataMin;
+
+  if (range === 0) {
+    return [{ lower: dataMin, upper: dataMax, count: values.length }];
+  }
+
+  // Use exact integer buckets when range is small enough
+  const allIntegers = values.every((v) => Number.isInteger(v));
+  const intRange = dataMax - dataMin + 1;
+  let bucketCount: number;
+  if (allIntegers && intRange <= MAX_BUCKETS) {
+    bucketCount = intRange;
+  } else {
+    // Sturges' rule, capped at MAX_BUCKETS
+    bucketCount = Math.min(
+      MAX_BUCKETS,
+      Math.ceil(Math.log2(values.length) + 1),
+    );
+  }
+
+  const bucketSize = range / bucketCount;
+  const buckets: DistributionBucket[] = Array.from(
+    { length: bucketCount },
+    (_, i) => ({
+      lower: dataMin + i * bucketSize,
+      upper: dataMin + (i + 1) * bucketSize,
+      count: 0,
+    }),
+  );
+
+  for (const v of values) {
+    const idx = Math.min(
+      bucketCount - 1,
+      Math.floor((v - dataMin) / bucketSize),
+    );
+    const bucket = buckets[idx];
+    if (bucket) {
+      bucket.count += 1;
+    }
+  }
+
+  return buckets;
+};
+
+/**
+ * Format an epoch-ms timestamp back to an ISO date/datetime string.
+ * Uses date-only format (YYYY-MM-DD) when the time component is midnight UTC.
+ */
+const epochToDateLabel = (epochMs: number): string => {
+  const d = new Date(epochMs);
+  if (
+    d.getUTCHours() === 0 &&
+    d.getUTCMinutes() === 0 &&
+    d.getUTCSeconds() === 0 &&
+    d.getUTCMilliseconds() === 0
+  ) {
+    return d.toISOString().slice(0, 10);
+  }
+  return d.toISOString().replace('T', ' ').slice(0, 19);
+};
+
+/**
+ * Build a frequency-distribution histogram for an array of ISO date strings.
+ * Buckets are computed over epoch-ms timestamps; each bucket carries
+ * human-readable date labels for tooltip display.
+ */
+const computeDateDistribution = (
+  dateStrings: string[],
+): DistributionBucket[] => {
+  if (dateStrings.length === 0) {
+    return [];
+  }
+
+  const epochs = dateStrings
+    .map((s) => Date.parse(s))
+    .filter((e) => !Number.isNaN(e));
+  if (epochs.length === 0) {
+    return [];
+  }
+
+  const raw = computeDistribution(epochs);
+  return raw.map((b) => ({
+    ...b,
+    lowerDateLabel: epochToDateLabel(b.lower),
+    upperDateLabel: epochToDateLabel(b.upper),
+  }));
+};
+
+const MAX_FREQ_ENTRIES = 10;
+
+/**
+ * Safely convert an unknown value to a string key.
+ * Objects are serialised with JSON.stringify to avoid '[object Object]'.
+ */
+const valueToString = (v: unknown): string => {
+  if (typeof v === 'string') {
+    return v;
+  }
+  if (typeof v === 'number' || typeof v === 'boolean') {
+    return String(v);
+  }
+  if (v === null || v === undefined) {
+    return '';
+  }
+  return JSON.stringify(v);
+};
+
+/**
+ * Build top-N value frequency list from non-null values.
+ * Values beyond the top N are collapsed into a single '(other)' entry.
+ * If nullCount > 0, an '(empty)' entry is appended at the end.
+ */
+const computeValueFrequencies = (
+  nonNullValues: unknown[],
+  nullCount: number,
+): ValueFrequency[] => {
+  const freq = new Map<string, number>();
+  for (const v of nonNullValues) {
+    const key = valueToString(v);
+    freq.set(key, (freq.get(key) ?? 0) + 1);
+  }
+
+  const sorted = [...freq.entries()].sort((a, b) => b[1] - a[1]);
+  const top = sorted.slice(0, MAX_FREQ_ENTRIES);
+  const otherCount = sorted
+    .slice(MAX_FREQ_ENTRIES)
+    .reduce((s, [, c]) => s + c, 0);
+
+  const result: ValueFrequency[] = top.map(([label, count]) => ({
+    label,
+    count,
+  }));
+  if (otherCount > 0) {
+    result.push({ label: '(other)', count: otherCount, isOther: true });
+  }
+  if (nullCount > 0) {
+    result.push({ label: '(empty)', count: nullCount, isEmpty: true });
+  }
+  return result;
+};
+
+// ---------------------------------------------------------------------------
+// Private helpers for computeCellSelectionStats
+// ---------------------------------------------------------------------------
+
+type ColumnTypeCategory = 'numeric' | 'date' | 'string' | 'mixed';
+
+const classifyColumns = (
+  columnNames: Set<string>,
+  columnTypes: Map<string, string | undefined>,
+): ColumnTypeCategory => {
+  const isType = (typeSet: Set<string>): boolean =>
+    [...columnNames].every((col) => {
+      const t = columnTypes.get(col);
+      return t !== undefined && typeSet.has(t);
+    });
+  if (isType(NUMERIC_TYPES)) {
+    return 'numeric';
+  }
+  if (isType(DATE_TYPES)) {
+    return 'date';
+  }
+  if (isType(STRING_TYPES)) {
+    return 'string';
+  }
+  return 'mixed';
+};
+
+const buildBaseStats = (
+  count: number,
+  uniqueCount: number,
+  nullCount: number,
+  valueFrequencies: ValueFrequency[] | undefined,
+): CellSelectionStats => ({
+  count,
+  uniqueCount,
+  nullCount,
+  min: undefined,
+  max: undefined,
+  sum: undefined,
+  avg: undefined,
+  dateMin: undefined,
+  dateMax: undefined,
+  strMinLength: undefined,
+  strMaxLength: undefined,
+  distributionBuckets: undefined,
+  distributionChartType: undefined,
+  valueFrequencies,
+});
+
+const computeNumericStats = (
+  base: CellSelectionStats,
+  selectedCells: TDSResultCellData[],
+  valueFrequencies: ValueFrequency[] | undefined,
+): CellSelectionStats => {
+  const numericValues = selectedCells
+    .map((c) => {
+      if (c.value === null || c.value === undefined || c.value === '') {
+        return null;
+      }
+      const n = Number(c.value);
+      return Number.isNaN(n) ? null : n;
+    })
+    .filter((v): v is number => v !== null);
+
+  if (numericValues.length === 0) {
+    return { ...base, valueFrequencies };
+  }
+
+  const sum = numericValues.reduce((acc, n) => acc + n, 0);
+  return {
+    ...base,
+    min: Math.min(...numericValues),
+    max: Math.max(...numericValues),
+    sum,
+    avg: sum / numericValues.length,
+    distributionBuckets: computeDistribution(numericValues),
+    distributionChartType: 'numeric',
+    valueFrequencies,
+  };
+};
+
+const computeDateStats = (
+  base: CellSelectionStats,
+  nonNullValues: unknown[],
+  valueFrequencies: ValueFrequency[] | undefined,
+): CellSelectionStats => {
+  const dateValues = nonNullValues.map(String).filter((s) => s.length > 0);
+  const sorted = [...dateValues].sort((a, b) => a.localeCompare(b));
+  const dateBuckets = computeDateDistribution(dateValues);
+  return {
+    ...base,
+    dateMin: sorted[0],
+    dateMax: sorted[sorted.length - 1],
+    distributionBuckets: dateBuckets.length >= 2 ? dateBuckets : undefined,
+    distributionChartType: dateBuckets.length >= 2 ? 'date' : undefined,
+    valueFrequencies,
+  };
+};
+
+const computeStringStats = (
+  base: CellSelectionStats,
+  nonNullValues: unknown[],
+  valueFrequencies: ValueFrequency[] | undefined,
+): CellSelectionStats => {
+  const lengths = nonNullValues
+    .map((v) => valueToString(v).length)
+    .filter((l) => l > 0);
+  return {
+    ...base,
+    strMinLength: lengths.length > 0 ? Math.min(...lengths) : undefined,
+    strMaxLength: lengths.length > 0 ? Math.max(...lengths) : undefined,
+    distributionBuckets:
+      lengths.length > 0 ? computeDistribution(lengths) : undefined,
+    distributionChartType: lengths.length > 0 ? 'string-length' : undefined,
+    valueFrequencies,
+  };
+};
+
+/**
+ * Compute summary statistics for a cell selection.
+ * ...existing code...
+ */
+export const computeCellSelectionStats = (
+  selectedCells: TDSResultCellData[],
+  columnTypes: Map<string, string | undefined>,
+): CellSelectionStats | undefined => {
+  if (selectedCells.length < 2) {
+    return undefined;
+  }
+
+  const count = selectedCells.length;
+
+  const nullCount = selectedCells.filter(
+    (c) => c.value === null || c.value === undefined || c.value === '',
+  ).length;
+
+  const nonNullValues = selectedCells
+    .map((c) => c.value)
+    .filter((v) => v !== null && v !== undefined && v !== '');
+  const uniqueCount = new Set(nonNullValues).size;
+
+  const selectedColumnNames = new Set(selectedCells.map((c) => c.columnName));
+  const columnTypeCategory = classifyColumns(selectedColumnNames, columnTypes);
+
+  const valueFrequencies =
+    nonNullValues.length > 0 || nullCount > 0
+      ? computeValueFrequencies(nonNullValues, nullCount)
+      : undefined;
+
+  const base = buildBaseStats(count, uniqueCount, nullCount, valueFrequencies);
+
+  if (columnTypeCategory === 'numeric') {
+    return computeNumericStats(base, selectedCells, valueFrequencies);
+  }
+  if (columnTypeCategory === 'date') {
+    return computeDateStats(base, nonNullValues, valueFrequencies);
+  }
+  if (columnTypeCategory === 'string') {
+    return computeStringStats(base, nonNullValues, valueFrequencies);
+  }
+  return base;
+};