@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/stores/CubeGridQuickActions.ts

@@ -15,11 +15,16 @@
  */
 
 import {
-  buildQuickFilterRule,
+  AggregationFunction,
+  buildDrilldownKeyRule,
   FilterOperator,
   Filter,
+  foldColumnName,
+  getAggregationAutoName,
+  Group,
   isOperatorAvailable,
   isSortableType,
+  type Schema,
   Sort,
   TypeFamily,
 } from '@finos/legend-cube';
@@ -31,6 +36,24 @@ import {
 import type { CubeResultValue } from '../graph-manager/CubeEngine.js';
 import type { CubeEditorState } from './CubeEditorState.js';
 
+/**
+ * The name of a Group by's Count rows: `Count Rows`, or with a number after it
+ * when an input column already has that name in any case, e.g. on a Group of
+ * a Group (PLAN §11.5)
+ */
+export const getGroupByCountName = (schema: Schema): string => {
+  const base = getAggregationAutoName(
+    AggregationFunction.COUNT_ROWS,
+    undefined,
+  ) as string;
+  const taken = new Set(schema.names().map(foldColumnName));
+  let name = base;
+  for (let suffix = 2; taken.has(foldColumnName(name)); suffix += 1) {
+    name = `${base} ${suffix}`;
+  }
+  return name;
+};
+
 /** One of the grid's quick actions on a cell (spec §12.4) */
 export interface CubeGridQuickAction {
   /** e.g. `Sort by "SHIP_COUNTRY"` */
@@ -43,13 +66,27 @@ export interface CubeGridQuickAction {
   readonly apply: () => void;
 }
 
+/** What a cell of the grid holds */
+export enum CubeGridCellKind {
+  /** A run row's value, or a group row's key */
+  VALUE = 'value',
+  /** A group row's aggregation of its rows' values (PLAN §11.10) */
+  AGGREGATE = 'aggregate',
+  /** A group row's column with no aggregation: nothing */
+  EMPTY = 'empty',
+}
+
 /**
- * The quick actions on a cell of the shown rows (spec §12.4, PLAN §11.4):
- * "Sort by" adds an ascending Sort on the cell's column, and "Filter by" an
- * Equal on its value (Is Empty on a null), after the node that runs, which
- * they replace as the node that runs. Both need the rows to be from the
- * current query, no run in flight, and a cube that can change; "Sort by" a
- * type that sorts, and "Filter by" a value its column's type can compare.
+ * The quick actions on a cell of the shown rows (spec §12.4, PLAN §11.4,
+ * §11.5 and §11.10): "Sort by" adds an ascending Sort on the cell's column,
+ * "Group by" a Group by it with Count rows, and "Filter by" an Equal on its
+ * value (Is Empty on a null; on a float, In the value and its 32-bit value
+ * when they differ, so a `REAL` value is found, as a drill-down's key is,
+ * PLAN §11.14), after the node that runs, which they replace as
+ * the node that runs; a group row's cell other than its key has no value of a
+ * row, so "Filter by" is disabled there. All need the rows to be from the current query, no run in
+ * flight, and a cube that can change; "Sort by" and "Group by" a type that
+ * compares, and "Filter by" a value its column's type can compare.
  * Read when the menu opens; `[]` when the position is not a column of the
  * shown rows.
  */
@@ -57,6 +94,7 @@ export const getCubeGridQuickActions = (
   editorState: CubeEditorState,
   position: number,
   cell: CubeResultValue,
+  cellKind = CubeGridCellKind.VALUE,
 ): CubeGridQuickAction[] => {
   const { execution, document } = editorState;
   const { result } = execution;
@@ -67,28 +105,43 @@ export const getCubeGridQuickActions = (
   const { query } = document;
   const afterId = query.selected;
   const typeName = column.type.displayName;
-  const rule = buildQuickFilterRule(column.name, column.type, cell);
+  const rule =
+    cellKind === CubeGridCellKind.VALUE
+      ? buildDrilldownKeyRule(column.name, column.type, cell)
+      : undefined;
   // what keeps both from being used, in order
   const blocked =
-    result.query !== query
+    result.query !== query || execution.isStale
       ? CUBE_QUICK_ACTION_DISABLED_REASON.STALE_ROWS
-      : execution.isRunning
-        ? CUBE_QUICK_ACTION_DISABLED_REASON.RUNNING
-        : editorState.readOnly
-          ? READ_ONLY_CUBE_TITLE
-          : undefined;
+      : // choosing would apply the edits first, leaving these rows stale
+        editorState.hasEditsToApply || editorState.nodeEditor.hasPendingInput()
+        ? CUBE_QUICK_ACTION_DISABLED_REASON.EDITING
+        : execution.isRunning
+          ? CUBE_QUICK_ACTION_DISABLED_REASON.RUNNING
+          : editorState.readOnly
+            ? READ_ONLY_CUBE_TITLE
+            : undefined;
   const sortReason =
     blocked ??
     (isSortableType(column.type)
       ? undefined
       : CUBE_QUICK_ACTION_DISABLED_REASON.notSortable(typeName));
+  const groupReason =
+    blocked ??
+    (isSortableType(column.type)
+      ? undefined
+      : CUBE_QUICK_ACTION_DISABLED_REASON.notGroupable(typeName));
   const filterReason =
     blocked ??
     (rule
       ? undefined
-      : isOperatorAvailable(FilterOperator.EQUAL, column.type)
-        ? CUBE_QUICK_ACTION_DISABLED_REASON.UNREADABLE_VALUE
-        : CUBE_QUICK_ACTION_DISABLED_REASON.notComparable(typeName));
+      : cellKind === CubeGridCellKind.AGGREGATE
+        ? CUBE_QUICK_ACTION_DISABLED_REASON.AGGREGATE_VALUE
+        : cellKind === CubeGridCellKind.EMPTY
+          ? CUBE_QUICK_ACTION_DISABLED_REASON.NO_VALUE
+          : isOperatorAvailable(FilterOperator.EQUAL, column.type)
+            ? CUBE_QUICK_ACTION_DISABLED_REASON.UNREADABLE_VALUE
+            : CUBE_QUICK_ACTION_DISABLED_REASON.notComparable(typeName));
   return [
     {
       label: `Sort by "${column.name}"`,
@@ -96,7 +149,7 @@ export const getCubeGridQuickActions = (
       hint: undefined,
       apply: () => {
         // as the menu found it: nothing changed since it opened
-        if (sortReason === undefined && editorState.document.query === query) {
+        if (sortReason === undefined && editorState.document === document) {
           editorState.addConfiguredNode(
             Sort.byColumn(query.generateId(Sort.TYPE), column.name),
             afterId,
@@ -104,11 +157,35 @@ export const getCubeGridQuickActions = (
         }
       },
     },
+    {
+      label: `Group by "${column.name}"`,
+      disabledReason: groupReason,
+      hint: undefined,
+      apply: () => {
+        if (groupReason === undefined && editorState.document === document) {
+          editorState.addConfiguredNode(
+            new Group(
+              query.generateId(Group.TYPE),
+              [column.name],
+              [
+                {
+                  column: undefined,
+                  function: AggregationFunction.COUNT_ROWS,
+                  name: getGroupByCountName(result.schema),
+                },
+              ],
+            ),
+            afterId,
+          );
+        }
+      },
+    },
     {
       label: `Filter by "${column.name}"`,
       disabledReason: filterReason,
       hint:
-        rule?.operator === FilterOperator.EQUAL &&
+        (rule?.operator === FilterOperator.EQUAL ||
+          rule?.operator === FilterOperator.IN) &&
         column.type.family === TypeFamily.FLOAT
           ? FILTER_FLOAT_COMPARISON_HINT
           : undefined,
@@ -116,7 +193,7 @@ export const getCubeGridQuickActions = (
         if (
           filterReason === undefined &&
           rule &&
-          editorState.document.query === query
+          editorState.document === document
         ) {
           editorState.addConfiguredNode(
             new Filter(query.generateId(Filter.TYPE), rule),

package/src/stores/CubeGridState.ts

@@ -0,0 +1,450 @@
+/**
+ * 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 {
+  addDrilldownLevel,
+  type AggregationFunction,
+  type CheckedDrilldown,
+  checkDrilldown,
+  type ColumnFormat,
+  type ColumnDirection,
+  type Drilldown,
+  type DrilldownCell,
+  foldColumnName,
+  isDrilldownLevelType,
+  isEmptyDrilldown,
+  removeDrilldownLevel,
+  setColumnFormat,
+  setDrilldownAggregation,
+  SortDirection,
+} from '@finos/legend-cube';
+import {
+  action,
+  computed,
+  makeObservable,
+  observable,
+  runInAction,
+} from 'mobx';
+import {
+  CUBE_DRILLDOWN_BLOCKER,
+  LEGEND_CUBE_USER_DATA_KEY,
+  READ_ONLY_CUBE_TITLE,
+} from '../__lib__/LegendCubeLabels.js';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeResultValue,
+} from '../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import type { CubeExecutionResult } from './CubeExecutionState.js';
+import { CubeGridFetchDropped } from './CubeGridFetcher.js';
+
+/** How the grid shows a run (spec §12.1, PLAN §11.10) */
+export enum CubeGridMode {
+  /** Each sort and drill-down level runs on the engine (the default) */
+  SERVER_SIDE = 'serverSide',
+  /** The run's rows, grouped, pivoted and filtered in the browser */
+  LOCAL = 'local',
+}
+
+/** The id ag-grid gives the column of the drill-down's groups */
+export const CUBE_GRID_GROUP_COLUMN_ID = 'ag-Grid-AutoColumn';
+
+/** A column's id in the grid: its position, as `c<position>` */
+export const CUBE_GRID_COLUMN_ID_PREFIX = 'c';
+
+/** A row of the server-side grid: a group of the drill-down, or a row of the run */
+export interface CubeGridRowData {
+  /** Unique among the grid's rows: its group's keys, typed, or its group's and its position */
+  readonly id: string;
+  /** The keys of its group and the groups around it, outermost first, as the engine returned them */
+  readonly keys: readonly DrilldownCell[];
+  readonly isGroup: boolean;
+  /** Each run column's value, `undefined` where a group row shows none */
+  readonly cells: readonly (CubeResultValue | undefined)[];
+  /** On a group row, how many of the run's rows it holds */
+  readonly count?: number | undefined;
+}
+
+/** A sort ag-grid asks for: a column's id and its direction */
+export interface CubeGridSortRequest {
+  readonly colId: string;
+  readonly sort: 'asc' | 'desc';
+}
+
+const NO_DRILLDOWN = Object.freeze({ columns: [], aggregations: [] });
+
+/**
+ * The grid's state beyond the run (PLAN §11.10): its mode, remembered for the
+ * user, and in server-side mode the rows of each level ag-grid asks for, from
+ * the run on screen (`CubeGridFetcher`), with what the levels say: an error,
+ * and whether a level was cut at the row limit.
+ */
+export class CubeGridState {
+  readonly editorState: CubeEditorState;
+  mode: CubeGridMode;
+  /** The last fetch's error, until the next fetch or a new run */
+  fetchError: CubeEngineError | undefined;
+  /** Some level shown was cut at the run's row limit */
+  hasLimitedLevel = false;
+  /** Fetches in flight */
+  fetching = 0;
+  /** The grid on screen: answers for an earlier one are left alone */
+  private gridToken = 0;
+  /** The drill-down's settings dialog is open */
+  isSettingsOpen = false;
+  /** The column whose format the Format Column dialog edits, while it is open */
+  formatColumn: string | undefined;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable(this, {
+      mode: observable,
+      fetchError: observable.ref,
+      hasLimitedLevel: observable,
+      fetching: observable,
+      drilldown: computed,
+      setMode: action,
+      addLevel: action,
+      removeLevel: action,
+      setAggregation: action,
+      clearDrilldown: action,
+      openSettings: action,
+      closeSettings: action,
+      isSettingsOpen: observable,
+      isSettingsShown: computed,
+      formatColumn: observable,
+      openFormat: action,
+      closeFormat: action,
+      setColumnFormat: action,
+      clearFetchError: action,
+      resetLevels: action,
+    });
+    this.editorState = editorState;
+    const stored =
+      editorState.host.applicationStore.userDataService.getStringValue(
+        LEGEND_CUBE_USER_DATA_KEY.GRID_MODE,
+      );
+    this.mode =
+      stored === CubeGridMode.LOCAL
+        ? CubeGridMode.LOCAL
+        : CubeGridMode.SERVER_SIDE;
+  }
+
+  get isServerSide(): boolean {
+    return this.mode === CubeGridMode.SERVER_SIDE;
+  }
+
+  /** The cube's drill-down, checked against the run on screen; none without a run */
+  get drilldown(): CheckedDrilldown | undefined {
+    const { result } = this.editorState.execution;
+    return result
+      ? checkDrilldown(
+          this.editorState.document.meta.drilldown ?? NO_DRILLDOWN,
+          result.schema,
+        )
+      : undefined;
+  }
+
+  /**
+   * Shows the run another way. Both modes show the same run, so nothing runs
+   * again: local mode shows its rows, server-side mode fetches what it needs
+   */
+  setMode(mode: CubeGridMode): void {
+    this.mode = mode;
+    this.editorState.host.applicationStore.userDataService.persistValue(
+      LEGEND_CUBE_USER_DATA_KEY.GRID_MODE,
+      mode,
+    );
+  }
+
+  /**
+   * Why 'Drilldown by' can't be used on the run's column, if it can't: a
+   * type that can't be grouped, a column that is a level already, a cube
+   * saved by a newer version
+   */
+  getAddLevelBlocker(column: string): string | undefined {
+    const { editorState } = this;
+    const type = editorState.execution.result?.schema.type(column);
+    if (editorState.readOnly) {
+      return READ_ONLY_CUBE_TITLE;
+    }
+    if (!type || !isDrilldownLevelType(type)) {
+      return CUBE_DRILLDOWN_BLOCKER.notGroupable(type?.displayName ?? '');
+    }
+    return (editorState.document.meta.drilldown?.columns ?? []).some(
+      (level) => foldColumnName(level) === foldColumnName(column),
+    )
+      ? CUBE_DRILLDOWN_BLOCKER.ALREADY_A_LEVEL
+      : undefined;
+  }
+
+  private setDrilldown(drilldown: Drilldown | undefined): void {
+    const { editorState } = this;
+    const { meta } = editorState.document;
+    const { drilldown: _, ...others } = meta;
+    editorState.applyDocument(
+      editorState.document.withMeta(
+        isEmptyDrilldown(drilldown) ? others : { ...meta, drilldown },
+      ),
+    );
+  }
+
+  /**
+   * Adds the column as the drill-down's innermost level, an undo step that
+   * leaves the rows current (spec §12.4); the grid shows it server-side,
+   * the only mode with levels (spec §12.1)
+   */
+  addLevel(column: string): void {
+    if (this.getAddLevelBlocker(column) !== undefined) {
+      return;
+    }
+    this.setDrilldown(
+      addDrilldownLevel(this.editorState.document.meta.drilldown, column),
+    );
+    if (!this.isServerSide) {
+      this.setMode(CubeGridMode.SERVER_SIDE);
+    }
+  }
+
+  /** Removes the level at the position: the ones inside it move out */
+  removeLevel(index: number): void {
+    const { drilldown } = this.editorState.document.meta;
+    if (drilldown && !this.editorState.readOnly) {
+      this.setDrilldown(removeDrilldownLevel(drilldown, index));
+    }
+  }
+
+  /** Sets how a group row shows the run's column: a function, or nothing */
+  setAggregation(column: string, fn: AggregationFunction | null): void {
+    const type = this.editorState.execution.result?.schema.type(column);
+    if (type && !this.editorState.readOnly) {
+      this.setDrilldown(
+        setDrilldownAggregation(
+          this.editorState.document.meta.drilldown,
+          column,
+          type,
+          fn,
+        ),
+      );
+    }
+  }
+
+  /** Removes the drill-down: its levels and its aggregations */
+  clearDrilldown(): void {
+    if (!this.editorState.readOnly) {
+      this.closeSettings();
+      this.setDrilldown(undefined);
+    }
+  }
+
+  openSettings(): void {
+    this.isSettingsOpen = true;
+  }
+
+  closeSettings(): void {
+    this.isSettingsOpen = false;
+  }
+
+  openFormat(column: string): void {
+    this.formatColumn = column;
+  }
+
+  closeFormat(): void {
+    this.formatColumn = undefined;
+  }
+
+  /**
+   * Sets a number column's format, or removes it with `undefined`; with no
+   * column, the format of every number column (spec §13.1). An undo step
+   * that leaves the rows current.
+   */
+  setColumnFormat(
+    column: string | undefined,
+    format: ColumnFormat | undefined,
+  ): void {
+    const { editorState } = this;
+    if (editorState.readOnly) {
+      return;
+    }
+    const { meta } = editorState.document;
+    editorState.applyDocument(
+      editorState.document.withMeta({
+        ...meta,
+        presentation: {
+          ...meta.presentation,
+          columnHints: setColumnFormat(
+            meta.presentation.columnHints ?? [],
+            column,
+            format,
+          ),
+        },
+      }),
+    );
+  }
+
+  clearFetchError(): void {
+    this.fetchError = undefined;
+  }
+
+  /** A new grid on screen: what earlier levels said is forgotten */
+  resetLevels(): void {
+    this.fetchError = undefined;
+    this.hasLimitedLevel = false;
+  }
+
+  /**
+   * A new grid, for a new run or drill-down, taking its token for
+   * `loadRows`: the earlier grid's answers, still on their way, are then left
+   * alone, saying nothing (PLAN §11.10). Not observable, so a grid takes it
+   * as it renders, before its first request.
+   */
+  beginGrid(): number {
+    this.gridToken += 1;
+    return this.gridToken;
+  }
+
+  /** The drill-down's settings dialog shows: asked for, on a run with a drill-down */
+  get isSettingsShown(): boolean {
+    return (
+      this.isSettingsOpen &&
+      this.drilldown !== undefined &&
+      !isEmptyDrilldown(this.editorState.document.meta.drilldown)
+    );
+  }
+
+  /**
+   * The sort ag-grid asks for, by the run's column names: a column by its
+   * position; the groups' column by the level's own column at a group level,
+   * and not at all at the leaf
+   */
+  toSorts(
+    result: CubeExecutionResult,
+    sortModel: readonly CubeGridSortRequest[],
+    depth: number,
+  ): ColumnDirection[] {
+    const levels = this.drilldown?.columns ?? [];
+    return sortModel.flatMap(({ colId, sort }): ColumnDirection[] => {
+      const direction =
+        sort === 'desc' ? SortDirection.DESC : SortDirection.ASC;
+      if (colId === CUBE_GRID_GROUP_COLUMN_ID) {
+        const column = levels[depth];
+        return column === undefined ? [] : [{ column, direction }];
+      }
+      const column = colId.startsWith(CUBE_GRID_COLUMN_ID_PREFIX)
+        ? result.schema.columns[
+            Number(colId.slice(CUBE_GRID_COLUMN_ID_PREFIX.length))
+          ]
+        : undefined;
+      return column ? [{ column: column.name, direction }] : [];
+    });
+  }
+
+  /**
+   * The rows under a group, by its keys (none for the top level), sorted as
+   * ag-grid asks. The run's own rows when nothing is derived (no drill-down
+   * level, no sort), else a fetched level. Resolves to `undefined` for rows
+   * the grid no longer shows, which are then left alone.
+   */
+  async loadRows(
+    result: CubeExecutionResult,
+    keys: readonly DrilldownCell[],
+    sortModel: readonly CubeGridSortRequest[],
+    token = this.gridToken,
+  ): Promise<CubeGridRowData[] | undefined> {
+    const parentId = JSON.stringify(keys);
+    const sorts = this.toSorts(result, sortModel, keys.length);
+    if (!keys.length && !this.drilldown?.columns.length && !sorts.length) {
+      return result.rows.map((row, index) => ({
+        id: `${parentId}#${index}`,
+        keys,
+        isGroup: false,
+        cells: row,
+      }));
+    }
+    this.track(1);
+    try {
+      const level = await this.editorState.gridFetcher.fetchLevel(
+        result,
+        keys,
+        sorts,
+      );
+      if (token !== this.gridToken) {
+        return undefined;
+      }
+      this.noteLevel(level.limited);
+      const levels = this.drilldown?.columns ?? [];
+      const keyAt = level.level.isLeaf
+        ? -1
+        : result.schema.names().indexOf(levels[keys.length] as string);
+      return level.rows.map((row, index) => {
+        if (level.level.isLeaf) {
+          return {
+            id: `${parentId}#${index}`,
+            keys,
+            isGroup: false,
+            cells: row.cells,
+          };
+        }
+        const groupKeys = [...keys, row.cells[keyAt] ?? null];
+        return {
+          id: JSON.stringify(groupKeys),
+          keys: groupKeys,
+          isGroup: true,
+          cells: row.cells,
+          count: row.count,
+        };
+      });
+    } catch (error) {
+      if (error instanceof CubeGridFetchDropped || token !== this.gridToken) {
+        return undefined;
+      }
+      this.noteError(
+        error instanceof CubeEngineError
+          ? error
+          : new CubeEngineError(
+              CubeEngineErrorKind.EXECUTION,
+              error instanceof Error ? error.message : String(error),
+            ),
+      );
+      throw error;
+    } finally {
+      this.track(-1);
+    }
+  }
+
+  private track(change: number): void {
+    runInAction(() => {
+      this.fetching += change;
+      if (change > 0) {
+        this.fetchError = undefined;
+      }
+    });
+  }
+
+  private noteLevel(limited: boolean): void {
+    if (limited) {
+      runInAction(() => {
+        this.hasLimitedLevel = true;
+      });
+    }
+  }
+
+  private noteError(error: CubeEngineError): void {
+    runInAction(() => {
+      this.fetchError = error;
+    });
+  }
+}