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

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@finos/legend-cube-builder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Legend Cube builder: the canvas UI and the Legend engine adapter of the Legend Cube query builder",
+  "keywords": [
+    "legend",
+    "legend-cube",
+    "legend-cube-builder",
+    "cube",
+    "query"
+  ],
+  "homepage": "https://github.com/finos/legend-studio/tree/master/packages/legend-cube-builder",
+  "bugs": {
+    "url": "https://github.com/finos/legend-studio/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finos/legend-studio.git",
+    "directory": "packages/legend-cube-builder"
+  },
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js",
+    "./lib/index.css": "./lib/index.css"
+  },
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "yarn clean && yarn build:sass && yarn build:ts",
+    "build:sass": "cross-env INIT_CWD=$INIT_CWD node ../../scripts/workflow/buildSass.js",
+    "build:ts": "tsc --project ./tsconfig.build.json",
+    "clean": "npm-run-all clean:cache clean:lib",
+    "clean:cache": "rimraf \"build\"",
+    "clean:lib": "rimraf \"lib\"",
+    "dev": "npm-run-all --parallel dev:sass dev:ts",
+    "dev:sass": "sass style:lib --watch --load-path=../../node_modules/@finos/legend-art/scss",
+    "dev:ts": "tsc --watch --preserveWatchOutput",
+    "lint:js": "cross-env NODE_ENV=production eslint --cache --cache-location ./build/.eslintcache --report-unused-disable-directives --parser-options=project:\"./tsconfig.json\" \"./src/**/*.{js,ts,tsx}\"",
+    "publish:prepare": "node ../../scripts/release/preparePublishContent.js",
+    "publish:snapshot": "node ../../scripts/release/publishDevSnapshot.js",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@dagrejs/dagre": "1.1.4",
+    "@finos/legend-application": "16.0.126",
+    "@finos/legend-art": "7.1.166",
+    "@finos/legend-cube": "0.0.2",
+    "@finos/legend-graph": "32.7.4",
+    "@finos/legend-lego": "2.0.228",
+    "@finos/legend-shared": "11.0.31",
+    "@types/react": "19.0.10",
+    "@types/react-dom": "19.0.4",
+    "@xyflow/react": "12.4.4",
+    "mobx": "6.13.6",
+    "mobx-react-lite": "4.1.0",
+    "react": "19.0.1",
+    "react-dnd": "16.0.1",
+    "react-dom": "19.0.1",
+    "serializr": "3.0.3"
+  },
+  "devDependencies": {
+    "@finos/legend-dev-utils": "2.2.8",
+    "@jest/globals": "29.7.0",
+    "@testing-library/dom": "10.4.0",
+    "@testing-library/react": "16.2.0",
+    "axios": "1.16.0",
+    "cross-env": "7.0.3",
+    "eslint": "9.22.0",
+    "jest": "29.7.0",
+    "npm-run-all": "4.1.5",
+    "rimraf": "6.0.1",
+    "sass": "1.85.1",
+    "typescript": "5.8.2"
+  },
+  "peerDependencies": {
+    "react": "^19.0.1"
+  },
+  "publishConfig": {
+    "directory": "build/publishContent"
+  }
 }

package/src/__lib__/LegendCubeCommand.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { CommandConfigData } from '@finos/legend-application';
+
+// The Cube page's keyboard shortcuts (spec §17.12, PLAN §3.5). A Legend
+// application binds keys only through its plugins, so the host contributes
+// this config from one of its plugins (`getExtraKeyedCommandConfigEntries`);
+// the page registers the commands while it is open.
+
+export enum LEGEND_CUBE_COMMAND_KEY {
+  EXECUTE = 'legend-cube.execute',
+  UNDO = 'legend-cube.undo',
+}
+
+/** Keys as `KeyboardEvent.code` names */
+export const LEGEND_CUBE_COMMAND_CONFIG: CommandConfigData = {
+  [LEGEND_CUBE_COMMAND_KEY.EXECUTE]: {
+    title: 'Execute the query',
+    defaultKeyboardShortcut: 'F9',
+  },
+  [LEGEND_CUBE_COMMAND_KEY.UNDO]: {
+    title: 'Undo the last change',
+    defaultKeyboardShortcut: 'Control+KeyZ',
+    additionalKeyboardShortcuts: ['Meta+KeyZ'],
+  },
+};
+
+/** How the buttons' tooltips name the shortcuts */
+export const EXECUTE_SHORTCUT_LABEL = 'F9';
+export const UNDO_SHORTCUT_LABEL = 'Ctrl+Z / Cmd+Z';

package/src/__lib__/LegendCubeHelpText.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 {
+  Filter,
+  Join,
+  RelationalTableSource,
+  UnknownNode,
+} from '@finos/legend-cube';
+
+// The node editor's help text, verbatim from the original (spec §17.9). A
+// new node type adds its entry here.
+
+export const CUBE_NODE_HELP_TEXT: Readonly<Record<string, string>> = {
+  [RelationalTableSource.TYPE]: 'Sources data from relational database table.',
+  [Filter.TYPE]:
+    'Reduces the number of rows in the previous data set, keeping only rows matching the specified criteria.',
+  [Join.TYPE]:
+    'Joins two previous data sets using specified columns as join keys.',
+  [UnknownNode.TYPE]: 'Source or transformation unknown to the application.',
+};
+
+/** The tooltip of the editor's Select link (spec §17.9) */
+export const SELECT_NODE_TOOLTIP =
+  'Selects this node as active and its output will be shown in the grid once query is executed.';

package/src/__lib__/LegendCubeLabels.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 { SchemaColumn, SchemaDiff } from '@finos/legend-cube';
+import { CubeTableFlag } from '../graph-manager/CubeEngine.js';
+
+// The page's own text and settings; validation messages live in the core's
+// CubeMessages (PLAN §4.11)
+
+/** The rows a run returns by default (PLAN §9, Settled before M1.8) */
+export const DEFAULT_ROW_LIMIT = 1000;
+/** Above this, the row limit input warns that the tab may slow down; there is no hard cap */
+export const ROW_LIMIT_WARNING_THRESHOLD = 100_000;
+/** At most this many undo steps are kept */
+export const MAX_UNDO_STEPS = 100;
+
+export enum LEGEND_CUBE_USER_DATA_KEY {
+  ROW_LIMIT = 'legend-cube.row-limit',
+  PALETTE_COLLAPSED = 'legend-cube.palette-collapsed',
+}
+
+export const UNSAVED_CUBE_NAME = 'Unsaved Query';
+/** Why a cube's edits are disabled: it was saved by a newer version (Settled before M1.8) */
+export const READ_ONLY_CUBE_TITLE =
+  "This cube was saved by a newer version of Legend Cube, so it can't be changed or exported";
+/** How a SQL NULL shows in the grid, distinct from an empty string */
+export const NULL_CELL_TEXT = '(null)';
+
+/** Pending labels: lower-case gerunds, shown as they are (spec §17.13) */
+export enum CUBE_PENDING_LABEL {
+  LOADING_MODEL = 'loading model',
+  RESOLVING_SOURCE = 'resolving source',
+  EXECUTING_QUERY = 'executing query',
+  RENDERING_QUERY = 'rendering query',
+  REFRESHING_SOURCE = 'refreshing source',
+}
+
+export const getRowLimitError = (text: string): string | undefined => {
+  const value = Number(text.trim());
+  return text.trim() === '' || !Number.isSafeInteger(value) || value < 1
+    ? 'The row limit must be a whole number of at least 1.'
+    : undefined;
+};
+
+export const getTruncationMessage = (rowLimit: number): string =>
+  `Showing the first ${rowLimit.toLocaleString('en-US')} rows; the query returned more.`;
+
+/** How the picker shows a table's problem, and why (PLAN §6.2.6) */
+export const CUBE_TABLE_FLAG_LABELS: Readonly<
+  Record<CubeTableFlag, { label: string; description: string }>
+> = {
+  [CubeTableFlag.UNAVAILABLE]: {
+    label: 'unavailable',
+    description: "A column's type (BINARY or VARBINARY) can't be read by Cube.",
+  },
+  [CubeTableFlag.LENGTH_UNKNOWN]: {
+    label: 'length unknown',
+    description: 'A CHAR column: its length is not known to Cube.',
+  },
+  [CubeTableFlag.TYPE_UNKNOWN]: {
+    label: 'type unknown',
+    description: "A column's type (OTHER or ARRAY) is not known to Cube.",
+  },
+};
+
+/** A column's type as the editors show it: its display name, `?` when it takes NULL, e.g. `Varchar(5)?` */
+export const getColumnTypeLabel = (column: SchemaColumn): string =>
+  `${column.type.displayName}${column.nullable ? '?' : ''}`;
+
+const listColumns = (columns: readonly SchemaColumn[]): string =>
+  columns.map((column) => column.name).join(', ');
+
+/** Why Execute (and Show Pure) can't run, one reason a line, for a tooltip */
+export const formatDisabledReasons = (reasons: readonly string[]): string =>
+  reasons.map((reason) => `• ${reason}`).join('\n');
+
+/** The warning on a source whose table changed since the cube was saved; the table's new columns are used */
+export const getSchemaDriftWarning = (diff: SchemaDiff): string => {
+  const changes = [
+    ...(diff.added.length ? [`added ${listColumns(diff.added)}`] : []),
+    ...(diff.removed.length ? [`removed ${listColumns(diff.removed)}`] : []),
+    ...(diff.changed.length
+      ? [
+          `changed ${diff.changed
+            .map(
+              (change) =>
+                `${change.after.name} (${getColumnTypeLabel(change.before)} to ${getColumnTypeLabel(change.after)})`,
+            )
+            .join(', ')}`,
+        ]
+      : []),
+    ...(diff.reordered ? ['reordered its columns'] : []),
+  ];
+  return `This table changed since the cube was saved: ${changes.join('; ')}`;
+};
+
+/** Beside a condition comparing a floating-point column for equality (R133) */
+export const FILTER_FLOAT_COMPARISON_HINT =
+  'exact comparison on floating-point columns may not match';
+
+/** The Filter editor's note on NULLs (D4): negated conditions keep them */
+export const FILTER_NULL_NOTE =
+  'A negated condition (is not, does not contain, is not in list of, Not) also keeps the rows where its column is empty (NULL).';
+
+/** Why the node editor closed without applying its edits */
+export enum CUBE_EDITOR_CLOSED_REASON {
+  NODE_CHANGED = 'nodeChanged',
+  NODE_REMOVED = 'nodeRemoved',
+  CUBE_REPLACED = 'cubeReplaced',
+}
+
+/** The notice of a node editor that closed by itself, dropping its edits (M1.8b) */
+export const getEditorClosedNotice = (
+  nodeId: string,
+  reason: CUBE_EDITOR_CLOSED_REASON,
+): string => {
+  const cause =
+    reason === CUBE_EDITOR_CLOSED_REASON.NODE_CHANGED
+      ? `${nodeId} changed`
+      : reason === CUBE_EDITOR_CLOSED_REASON.NODE_REMOVED
+        ? `${nodeId} was removed`
+        : 'Another cube was opened';
+  return `${cause}, so the editor of ${nodeId} closed without applying its changes.`;
+};
+
+/** The warning on a source with saved columns that the engine couldn't type again */
+export const getSourceRecheckWarning = (firstLine: string): string =>
+  `Could not re-check this table, so it keeps its saved columns: ${firstLine}`;

package/src/__lib__/LegendCubeTesting.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+
+export enum LEGEND_CUBE_TEST_ID {
+  EDITOR = 'legend-cube__editor',
+  GRAPH_REGION = 'legend-cube__graph-region',
+  GRID_REGION = 'legend-cube__grid-region',
+  CANVAS = 'legend-cube__canvas',
+  CANVAS_NODE = 'legend-cube__canvas-node',
+  CANVAS_EDGE_LABEL = 'legend-cube__canvas-edge-label',
+  PALETTE = 'legend-cube__palette',
+  PALETTE_ITEM = 'legend-cube__palette-item',
+  NODE_EDITOR = 'legend-cube__node-editor',
+  EDITOR_NOTICE = 'legend-cube__editor-notice',
+  FILTER_CONDITION = 'legend-cube__filter-condition',
+  RESULT_GRID = 'legend-cube__result-grid',
+  GRID_TOOLBAR = 'legend-cube__grid-toolbar',
+  EXECUTION_ERROR = 'legend-cube__execution-error',
+  SQL_PANEL = 'legend-cube__sql-panel',
+}

package/src/__test-utils__/CubeCanvasTestUtils.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { screen, waitFor } from '@testing-library/react';
+import { LEGEND_CUBE_TEST_ID } from '../__lib__/LegendCubeTesting.js';
+
+// The canvas's nodes, as the tests find them: React Flow keys its own wrapper
+// of each node by the node's id
+
+/** The canvas node of a query node, or `null` when it isn't drawn */
+export const TEST__queryCanvasNode = (
+  nodeId: string,
+  container: ParentNode = document,
+): HTMLElement | null =>
+  container.querySelector<HTMLElement>(
+    `.react-flow__node[data-id="${nodeId}"] [data-testid="${LEGEND_CUBE_TEST_ID.CANVAS_NODE}"]`,
+  );
+
+/** The canvas node of a query node, once React Flow has drawn it */
+export const TEST__findCanvasNode = async (
+  nodeId: string,
+  container: ParentNode = document,
+): Promise<HTMLElement> => {
+  let node: HTMLElement | null = null;
+  await waitFor(() => {
+    node = TEST__queryCanvasNode(nodeId, container);
+    if (!node) {
+      throw new Error(`Node "${nodeId}" is not on the canvas`);
+    }
+  });
+  return node as unknown as HTMLElement;
+};
+
+/** Every node drawn on the canvas */
+export const TEST__getCanvasNodes = (): HTMLElement[] =>
+  screen.queryAllByTestId(LEGEND_CUBE_TEST_ID.CANVAS_NODE);
+
+/** The node's tooltip, one line an item: errors, warnings, description, id */
+export const TEST__getCanvasNodeTooltip = (node: HTMLElement): string[] =>
+  (node.getAttribute('title') ?? '').split('\n');

package/src/__test-utils__/CubeEngineTestSupport.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 axios, { type AxiosResponse } from 'axios';
+import {
+  ContentType,
+  HttpHeader,
+  parseLosslessJSON,
+  type PlainObject,
+} from '@finos/legend-shared';
+import { ENGINE_TEST_SUPPORT_API_URL } from '@finos/legend-graph/test';
+
+// Engine calls for Cube's engine tests (PLAN §3.4), as plain JSON. legend-graph's
+// engine test support has no batch relation-type helper, and its `execute`
+// parses the response, which would bypass Cube's lossless result reader
+
+const PURE_API = `${ENGINE_TEST_SUPPORT_API_URL}/pure/v1`;
+
+const JSON_HEADERS = {
+  [HttpHeader.CONTENT_TYPE]: ContentType.APPLICATION_JSON,
+};
+
+/** The commit of the engine the tests run against */
+export const CUBE_ENGINE_TEST__getCommit = async (): Promise<string> => {
+  const { data } = await axios.get<unknown, AxiosResponse<PlainObject>>(
+    `${ENGINE_TEST_SUPPORT_API_URL}/server/v1/info`,
+  );
+  const info = data.info as { legendSDLC?: Record<string, string> } | undefined;
+  return info?.legendSDLC?.['git.commit.id'] ?? 'unknown';
+};
+
+/**
+ * The protocol JSON the engine parses Pure lambda text into, read losslessly
+ * (a JSON parse would round large numbers) and without source information
+ */
+export const CUBE_ENGINE_TEST__grammarToJson_lambda = async (
+  code: string,
+): Promise<unknown> =>
+  parseLosslessJSON(
+    (
+      await axios.post<unknown, AxiosResponse<string>>(
+        `${PURE_API}/grammar/grammarToJson/lambda`,
+        code,
+        {
+          headers: { [HttpHeader.CONTENT_TYPE]: ContentType.TEXT_PLAIN },
+          params: { returnSourceInformation: false },
+          responseType: 'text',
+          transformResponse: (data: string) => data,
+        },
+      )
+    ).data,
+  );
+
+/** The relation types of a batch of lambdas: `{result, errors}`, keyed as the input */
+export const CUBE_ENGINE_TEST__lambdaRelationTypeBatch = async (
+  input: object,
+): Promise<PlainObject> =>
+  (
+    await axios.post<unknown, AxiosResponse<PlainObject>>(
+      `${PURE_API}/compilation/lambdaRelationType/batch`,
+      input,
+      { headers: JSON_HEADERS },
+    )
+  ).data;
+
+/** Compiles a model context; a model that doesn't compile is an HTTP 400 */
+export const CUBE_ENGINE_TEST__compile = async (
+  model: object,
+): Promise<PlainObject> =>
+  (
+    await axios.post<unknown, AxiosResponse<PlainObject>>(
+      `${PURE_API}/compilation/compile`,
+      model,
+      { headers: JSON_HEADERS },
+    )
+  ).data;
+
+/** The Pure text of a lambda, as the engine renders it */
+export const CUBE_ENGINE_TEST__jsonToGrammar_lambda = async (
+  lambda: PlainObject,
+  renderStyle?: string | undefined,
+): Promise<string> =>
+  (
+    await axios.post<unknown, AxiosResponse<string>>(
+      `${PURE_API}/grammar/jsonToGrammar/lambda`,
+      lambda,
+      {
+        headers: {
+          ...JSON_HEADERS,
+          [HttpHeader.ACCEPT]: ContentType.TEXT_PLAIN,
+        },
+        params: { renderStyle },
+        responseType: 'text',
+        transformResponse: (data: string) => data,
+      },
+    )
+  ).data;
+
+/**
+ * Executes a query and gives the response as the client's `returnAsResponse`
+ * does, its body unread, so the lossless reader parses the raw text as it
+ * does in the browser. A body given as text (with lossless numbers) is sent
+ * as it is.
+ */
+export const CUBE_ENGINE_TEST__execute = async (
+  input: object | string,
+): Promise<{ ok: boolean; status: number; text: () => Promise<string> }> => {
+  const response = await axios.post<unknown, AxiosResponse<string>>(
+    `${PURE_API}/execution/execute`,
+    input,
+    {
+      headers: JSON_HEADERS,
+      params: { serializationFormat: 'DEFAULT' },
+      responseType: 'text',
+      transformResponse: (data: string) => data,
+      validateStatus: () => true,
+    },
+  );
+  return {
+    ok: response.status >= 200 && response.status < 300,
+    status: response.status,
+    text: async () => response.data,
+  };
+};