@finos/legend-cube-builder 0.0.0-stage → 0.0.3

package/src/components/grid/CubeGridRegion.tsx

@@ -0,0 +1,275 @@
+/**
+ * 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 { PanelLoadingIndicator } from '@finos/legend-art';
+import { flowResult } from 'mobx';
+import { observer } from 'mobx-react-lite';
+import { useState } from 'react';
+import { EXECUTE_SHORTCUT_LABEL } from '../../__lib__/LegendCubeCommand.js';
+import {
+  CUBE_PENDING_LABEL,
+  formatDisabledReasons,
+  getRowLimitError,
+  getTruncationMessage,
+  ROW_LIMIT_WARNING_THRESHOLD,
+} from '../../__lib__/LegendCubeLabels.js';
+import { LEGEND_CUBE_TEST_ID } from '../../__lib__/LegendCubeTesting.js';
+import type { CubeEditorState } from '../../stores/CubeEditorState.js';
+import { CubeButton } from '../CubeButton.js';
+import { CubeResultGrid } from './CubeResultGrid.js';
+import { formatDuration } from './CubeGridValues.js';
+
+/** The first line of an error is shown, at most this long; the rest is under Details */
+const MAX_ERROR_LINE_LENGTH = 500;
+
+const CubeRowLimitInput = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const [draft, setDraft] = useState(String(editorState.rowLimit));
+    const [error, setError] = useState<string | undefined>();
+    const commit = (): void => {
+      const problem = getRowLimitError(draft);
+      setError(problem);
+      if (!problem) {
+        editorState.setRowLimit(Number(draft.trim()));
+      }
+    };
+    return (
+      <div className="flex items-center gap-1">
+        <label className="flex items-center gap-1 text-base">
+          Rows
+          <input
+            className="h-6 w-20 rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] px-1 text-right text-base text-[var(--color-text-primary)]"
+            aria-label="Row limit"
+            aria-invalid={error !== undefined}
+            value={draft}
+            onChange={(event) => setDraft(event.target.value)}
+            onBlur={commit}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                commit();
+              }
+            }}
+          />
+        </label>
+        {error !== undefined && (
+          <span
+            className="text-sm text-[var(--color-status-error)]"
+            role="alert"
+          >
+            {error}
+          </span>
+        )}
+        {error === undefined &&
+          editorState.rowLimit > ROW_LIMIT_WARNING_THRESHOLD && (
+            <span className="text-sm text-[var(--color-status-warn)]">
+              A large row limit can slow the page down.
+            </span>
+          )}
+      </div>
+    );
+  },
+);
+
+const CubeGridToolbar = observer(
+  (props: {
+    editorState: CubeEditorState;
+    showSql: boolean;
+    onToggleSql: () => void;
+  }) => {
+    const { editorState, showSql, onToggleSql } = props;
+    const { execution, host } = editorState;
+    const { applicationStore } = host;
+    const { result } = execution;
+    const disabledReasons = execution.disabledReasons;
+    const execute = (): void => {
+      flowResult(execution.execute()).catch(
+        applicationStore.alertUnhandledError,
+      );
+    };
+    return (
+      <div
+        className="flex h-8 shrink-0 items-center gap-3 border-b border-[var(--color-border-default)] bg-[var(--color-bg-panel-header)] px-2"
+        data-testid={LEGEND_CUBE_TEST_ID.GRID_TOOLBAR}
+      >
+        {execution.isRunning ? (
+          <CubeButton title="Stop the run" onClick={() => execution.stop()}>
+            Stop
+          </CubeButton>
+        ) : (
+          <CubeButton
+            primary={true}
+            disabled={!execution.canExecute}
+            title={
+              disabledReasons.length
+                ? `${formatDisabledReasons(disabledReasons)}\n(${EXECUTE_SHORTCUT_LABEL})`
+                : `Run the query up to the selected node (${EXECUTE_SHORTCUT_LABEL})`
+            }
+            onClick={execute}
+          >
+            Execute
+          </CubeButton>
+        )}
+        <CubeRowLimitInput editorState={editorState} />
+        {execution.isRunning && (
+          <span className="text-base text-[var(--color-text-secondary)]">
+            {CUBE_PENDING_LABEL.EXECUTING_QUERY}
+          </span>
+        )}
+        {execution.isStale && (
+          <span
+            className="rounded-sm bg-[var(--color-status-warn-bg)] px-1 text-base text-[var(--color-status-warn)]"
+            title="The query or the row limit changed since this run"
+          >
+            Stale: execute again to refresh
+          </span>
+        )}
+        {result && !execution.isRunning && (
+          <>
+            <span className="text-base text-[var(--color-text-secondary)]">
+              {`${result.rows.length.toLocaleString('en-US')} row${result.rows.length === 1 ? '' : 's'} in ${formatDuration(result.durationMs)}`}
+            </span>
+            {result.limited && (
+              <span className="text-base text-[var(--color-status-warn)]">
+                {getTruncationMessage(result.rowLimit)}
+              </span>
+            )}
+            {result.sql.length > 0 && (
+              <CubeButton aria-expanded={showSql} onClick={onToggleSql}>
+                {showSql ? 'Hide SQL' : 'Show SQL'}
+              </CubeButton>
+            )}
+          </>
+        )}
+      </div>
+    );
+  },
+);
+
+/** The SQL the run's database ran, with Copy */
+const CubeSqlPanel = observer((props: { editorState: CubeEditorState }) => {
+  const { editorState } = props;
+  const { applicationStore } = editorState.host;
+  const sql = editorState.execution.result?.sql ?? [];
+  if (!sql.length) {
+    return null;
+  }
+  const copySql = (): void => {
+    applicationStore.clipboardService
+      .copyTextToClipboard(sql.join('\n\n'))
+      .catch(applicationStore.alertUnhandledError);
+  };
+  return (
+    <div
+      className="flex max-h-40 shrink-0 gap-2 overflow-auto border-b border-[var(--color-border-default)] p-2"
+      data-testid={LEGEND_CUBE_TEST_ID.SQL_PANEL}
+    >
+      <div className="min-w-0 flex-1">
+        {sql.map((statement, index) => (
+          <pre
+            // statements hold no state, and the same one may run twice
+            // eslint-disable-next-line react/no-array-index-key
+            key={index}
+            className="whitespace-pre-wrap font-mono text-sm"
+          >
+            {statement}
+          </pre>
+        ))}
+      </div>
+      <CubeButton onClick={copySql}>Copy SQL</CubeButton>
+    </div>
+  );
+});
+
+const CubeExecutionError = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const error = props.editorState.execution.error;
+    if (!error) {
+      return null;
+    }
+    const isCut = error.firstLine.length > MAX_ERROR_LINE_LENGTH;
+    const firstLine = isCut
+      ? `${error.firstLine.slice(0, MAX_ERROR_LINE_LENGTH)}…`
+      : error.firstLine;
+    return (
+      <div
+        className="m-2 rounded-sm border border-[var(--color-status-error)] bg-[var(--color-status-error-bg)] p-2 text-base"
+        data-testid={LEGEND_CUBE_TEST_ID.EXECUTION_ERROR}
+        role="alert"
+      >
+        <div
+          className="font-medium text-[var(--color-status-error)]"
+          title={isCut ? error.firstLine : undefined}
+        >
+          {firstLine}
+        </div>
+        {(isCut || error.detail !== error.firstLine) && (
+          <details className="mt-1">
+            <summary className="cursor-pointer text-[var(--color-text-secondary)]">
+              Details
+            </summary>
+            <pre className="mt-1 max-h-60 overflow-auto whitespace-pre-wrap text-sm">
+              {error.detail}
+            </pre>
+          </details>
+        )}
+      </div>
+    );
+  },
+);
+
+/** The results: Execute, the row limit and the run's stats above the grid (PLAN §9) */
+export const CubeGridRegion = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const { execution, host } = editorState;
+    const [showSql, setShowSql] = useState(false);
+    const darkMode =
+      !host.applicationStore.layoutService.TEMPORARY__isLightColorThemeEnabled;
+    return (
+      <div
+        className="flex h-full flex-col bg-[var(--color-bg-panel)]"
+        data-testid={LEGEND_CUBE_TEST_ID.GRID_REGION}
+      >
+        <PanelLoadingIndicator isLoading={execution.isRunning} />
+        <CubeGridToolbar
+          editorState={editorState}
+          showSql={showSql}
+          onToggleSql={() => setShowSql(!showSql)}
+        />
+        {showSql && !execution.isRunning && (
+          <CubeSqlPanel editorState={editorState} />
+        )}
+        <div className="min-h-0 flex-1">
+          {execution.error ? (
+            <CubeExecutionError editorState={editorState} />
+          ) : execution.result ? (
+            <CubeResultGrid
+              key={execution.result.id}
+              editorState={editorState}
+              result={execution.result}
+              darkMode={darkMode}
+            />
+          ) : (
+            <div className="flex h-full items-center justify-center text-base text-[var(--color-text-secondary)]">
+              Execute the query to see its rows.
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  },
+);

package/src/components/grid/CubeGridValues.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 { TypeFamily } from '@finos/legend-cube';
+import type { CubeResultValue } from '../../graph-manager/CubeEngine.js';
+
+// How the grid shows and sorts values (PLAN §9, Settled before M1.8).
+// Integer and Decimal values arrive as their exact text and are never turned
+// into JS numbers, which would lose digits.
+
+const NUMERIC_FAMILIES: ReadonlySet<TypeFamily> = new Set([
+  TypeFamily.INTEGER,
+  TypeFamily.FLOAT,
+  TypeFamily.DECIMAL,
+  TypeFamily.NUMBER,
+]);
+
+export const isNumericFamily = (family: TypeFamily): boolean =>
+  NUMERIC_FAMILIES.has(family);
+
+const NUMBER_TEXT =
+  /^(?<sign>[+-]?)(?<whole>\d*)(?:\.(?<fraction>\d*))?(?:[eE](?<exponent>[+-]?\d+))?$/u;
+
+/** A number's text as sign, digits without leading or trailing zeros, and the position of the decimal point */
+const parseNumberText = (
+  text: string,
+): { negative: boolean; digits: string; point: number } | undefined => {
+  const groups = NUMBER_TEXT.exec(text.trim())?.groups;
+  if (!groups || (!groups.whole && !groups.fraction)) {
+    return undefined;
+  }
+  const {
+    sign,
+    whole = '',
+    fraction = '',
+    exponent = '0',
+  } = groups as Partial<Record<string, string>>;
+  const allDigits = whole + fraction;
+  const leadingZeros = allDigits.length - allDigits.replace(/^0+/u, '').length;
+  const digits = allDigits.slice(leadingZeros).replace(/0+$/u, '');
+  return {
+    negative: sign === '-' && digits !== '',
+    digits,
+    point: whole.length - leadingZeros + Number(exponent),
+  };
+};
+
+const compareMagnitudes = (
+  left: { digits: string; point: number },
+  right: { digits: string; point: number },
+): number => {
+  if (!left.digits || !right.digits) {
+    return (left.digits ? 1 : 0) - (right.digits ? 1 : 0);
+  }
+  if (left.point !== right.point) {
+    return left.point < right.point ? -1 : 1;
+  }
+  const length = Math.max(left.digits.length, right.digits.length);
+  const a = left.digits.padEnd(length, '0');
+  const b = right.digits.padEnd(length, '0');
+  return a === b ? 0 : a < b ? -1 : 1;
+};
+
+/** Compares two numbers written as text, digit for digit: `'9' < '10'`, `'9007199254740993' > '9007199254740992'` */
+export const compareNumberText = (left: string, right: string): number => {
+  const a = parseNumberText(left);
+  const b = parseNumberText(right);
+  if (!a || !b) {
+    // not a number: keep a stable order by text
+    return left < right ? -1 : left > right ? 1 : 0;
+  }
+  if (a.negative !== b.negative) {
+    return a.negative ? -1 : 1;
+  }
+  const magnitude = compareMagnitudes(a, b);
+  return a.negative ? -magnitude : magnitude;
+};
+
+/** Orders a column's values: nulls first, then numbers by value whether they are JS numbers or exact text */
+export const compareCellValues = (
+  left: CubeResultValue | undefined,
+  right: CubeResultValue | undefined,
+): number => {
+  if (
+    left === null ||
+    left === undefined ||
+    right === null ||
+    right === undefined
+  ) {
+    return (left ?? null) === null ? ((right ?? null) === null ? 0 : -1) : 1;
+  }
+  if (typeof left === 'number' && typeof right === 'number') {
+    return left - right;
+  }
+  if (
+    (typeof left === 'string' || typeof left === 'number') &&
+    (typeof right === 'string' || typeof right === 'number')
+  ) {
+    return compareNumberText(String(left), String(right));
+  }
+  return String(left) < String(right)
+    ? -1
+    : String(left) > String(right)
+      ? 1
+      : 0;
+};
+
+/** A run's duration for the toolbar: milliseconds under a second, else seconds */
+export const formatDuration = (durationMs: number): string =>
+  durationMs < 1000
+    ? `${Math.round(durationMs)} ms`
+    : `${(durationMs / 1000).toFixed(1)} s`;

package/src/components/grid/CubeResultGrid.tsx

@@ -0,0 +1,138 @@
+/**
+ * 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 { clsx } from '@finos/legend-art';
+import {
+  DataGrid,
+  type DataGridCellRendererParams,
+  type DataGridColumnDefinition,
+  type DataGridDefaultMenuItem,
+  type DataGridGetContextMenuItemsParams,
+  type DataGridMenuItemDef,
+} from '@finos/legend-lego/data-grid';
+import { memo, useCallback, useMemo } from 'react';
+import { NULL_CELL_TEXT } from '../../__lib__/LegendCubeLabels.js';
+import { LEGEND_CUBE_TEST_ID } from '../../__lib__/LegendCubeTesting.js';
+import type { CubeResultValue } from '../../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from '../../stores/CubeEditorState.js';
+import type { CubeExecutionResult } from '../../stores/CubeExecutionState.js';
+import { getCubeGridQuickActions } from '../../stores/CubeGridQuickActions.js';
+import { compareCellValues, isNumericFamily } from './CubeGridValues.js';
+
+type CubeRow = readonly CubeResultValue[];
+
+/** A column's id in the grid: its position, as `c<position>` */
+const COLUMN_ID_PREFIX = 'c';
+
+/**
+ * The grid's context menu (spec §12.4): on a cell, its quick actions, then
+ * ag-grid's own items, which M7 curates; elsewhere ag-grid's only. Read when
+ * the menu opens, so it reflects the cube and the run as they are then.
+ */
+export const getCubeGridContextMenuItems = (
+  editorState: CubeEditorState,
+  params: DataGridGetContextMenuItemsParams<CubeRow>,
+): (DataGridDefaultMenuItem | DataGridMenuItemDef<CubeRow>)[] => {
+  const defaultItems = params.defaultItems ?? [];
+  const colId = params.column?.getColId();
+  if (!colId?.startsWith(COLUMN_ID_PREFIX)) {
+    return defaultItems;
+  }
+  const position = Number(colId.slice(COLUMN_ID_PREFIX.length));
+  const cell = params.node?.data?.[position] ?? null;
+  const actions = getCubeGridQuickActions(editorState, position, cell);
+  if (!actions.length) {
+    return defaultItems;
+  }
+  return [
+    ...actions.map((quickAction): DataGridMenuItemDef<CubeRow> => {
+      const tooltip = quickAction.disabledReason ?? quickAction.hint;
+      return {
+        name: quickAction.label,
+        disabled: quickAction.disabledReason !== undefined,
+        ...(tooltip === undefined ? {} : { tooltip }),
+        action: () => quickAction.apply(),
+      };
+    }),
+    'separator',
+    ...defaultItems,
+  ];
+};
+
+const CubeCell: React.FC<
+  DataGridCellRendererParams<CubeRow, CubeResultValue>
+> = (props) =>
+  props.value === null || props.value === undefined ? (
+    <span className="text-[var(--color-text-muted)]">{NULL_CELL_TEXT}</span>
+  ) : (
+    <>{String(props.value)}</>
+  );
+
+/**
+ * The rows of a run (PLAN §9): columns from Cube's own schema of the capture
+ * node, by position, so any column name works. Numbers are right-aligned and
+ * shown and sorted exactly as the engine wrote them. A cell's context menu
+ * offers the quick actions (`getCubeGridContextMenuItems`).
+ */
+export const CubeResultGrid = memo(
+  (props: {
+    editorState: CubeEditorState;
+    result: CubeExecutionResult;
+    darkMode: boolean;
+  }) => {
+    const { editorState, result, darkMode } = props;
+    const getContextMenuItems = useCallback(
+      (params: DataGridGetContextMenuItemsParams<CubeRow>) =>
+        getCubeGridContextMenuItems(editorState, params),
+      [editorState],
+    );
+    const columnDefs = useMemo(
+      (): DataGridColumnDefinition<CubeRow, CubeResultValue>[] =>
+        result.schema.columns.map((column, position) => {
+          const numeric = isNumericFamily(column.type.family);
+          return {
+            colId: `${COLUMN_ID_PREFIX}${position}`,
+            headerName: column.name,
+            headerTooltip: `${column.type.displayName}${column.nullable ? '?' : ''} (${column.type.fullName})`,
+            valueGetter: (params) => params.data?.[position] ?? null,
+            cellRenderer: CubeCell,
+            ...(numeric
+              ? { type: 'rightAligned', comparator: compareCellValues }
+              : {}),
+          };
+        }),
+      [result],
+    );
+    return (
+      <div
+        className={clsx('h-full w-full', {
+          'ag-theme-balham': !darkMode,
+          'ag-theme-balham-dark': darkMode,
+        })}
+        data-testid={LEGEND_CUBE_TEST_ID.RESULT_GRID}
+      >
+        <DataGrid<CubeRow>
+          rowData={result.rows as CubeRow[]}
+          columnDefs={columnDefs}
+          suppressFieldDotNotation={true}
+          tooltipShowDelay={500}
+          getContextMenuItems={getContextMenuItems}
+        />
+      </div>
+    );
+  },
+);
+CubeResultGrid.displayName = 'CubeResultGrid';