@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/components/canvas/CubeCanvasElements.ts

@@ -15,10 +15,18 @@
  */
 
 import {
+  DataProductAccessPointSource,
+  FunctionSource,
+  getLiteralText,
+  getRelationalDisplayName,
+  IngestDatasetSource,
   isIncompleteError,
   isSchemasError,
+  isTypingError,
   type Query,
   type QueryNode,
+  RelationalTableSource,
+  ServiceSource,
 } from '@finos/legend-cube';
 import { type Edge, MarkerType, type Node, Position } from '@xyflow/react';
 import type { CubeEditorState } from '../../stores/CubeEditorState.js';
@@ -119,7 +127,10 @@ export interface CubeCanvasNodeStatus {
   readonly hasEngineError: boolean;
   /** It has a warning, stored (a table that changed) or derived (a lost sort order) */
   readonly hasWarnings: boolean;
-  /** Its errors, then its warnings, its description and its id, one a line */
+  /**
+   * Its errors, then its warnings and its description, one a line; not its
+   * id, which is internal (UX audit A5, 2026-10-11)
+   */
   readonly tooltip: string;
 }
 
@@ -134,20 +145,88 @@ export const getCubeCanvasNodeStatus = (
   return {
     isCapture: editorState.document.query.selected === node.id,
     isInvalid: (ownErrors ?? []).some(
-      (error) => !isIncompleteError(error) && !isSchemasError(error),
+      (error) =>
+        !isIncompleteError(error) &&
+        !isSchemasError(error) &&
+        !isTypingError(error),
     ),
     isIncomplete: (ownErrors ?? []).some(
       (error) => isIncompleteError(error) || isSchemasError(error),
     ),
-    isResolving: editorState.isPendingSource(node),
+    // a source typed again, or an Extend waiting for its columns' types
+    isResolving:
+      editorState.isPendingSource(node) || editorState.isTypingNode(node),
     hasEngineError: editorState.hostIssues.has(node.id),
     hasWarnings: warnings.length > 0,
     tooltip: [
       ...(ownErrors ? [] : [MISSING_VALIDITY_TOOLTIP]),
       ...errors,
       ...warnings,
-      node.describe(),
-      node.id,
+      // a node not set yet has no description to add (the review of the demo)
+      ...(node.isUnset() ? [] : [node.describe()]),
     ].join('\n'),
   };
 };
+
+/** What a node not set yet shows under its type's name */
+export const CUBE_NODE_NOT_SET_LABEL = 'Not set';
+
+/**
+ * What a node shows on the canvas: a source shows its name, with where it
+ * comes from as a muted second line (`TRADES`, from `TRADES_SAMPLE`); every
+ * other node, and a source not resolved yet, its description. The tooltip
+ * keeps the full description (UX audit B9, 2026-10-11).
+ */
+export const getCubeCanvasNodeLabel = (
+  node: QueryNode,
+  /** The node type's name, e.g. "Join Another Input", shown on a node not set yet */
+  typeLabel?: string | undefined,
+): { title: string; detail?: string | undefined } => {
+  if (node.isUnset() && typeLabel !== undefined) {
+    // "Join Another Input", then a muted "Not set", in place of "Join additional input"
+    return { title: typeLabel, detail: CUBE_NODE_NOT_SET_LABEL };
+  }
+  if (
+    (node instanceof RelationalTableSource ||
+      node instanceof DataProductAccessPointSource ||
+      node instanceof IngestDatasetSource ||
+      node instanceof ServiceSource ||
+      node instanceof FunctionSource) &&
+    node.resolution.kind === 'unresolved'
+  ) {
+    return { title: node.describe() };
+  }
+  if (node instanceof RelationalTableSource) {
+    return {
+      title: getRelationalDisplayName(node.table),
+      detail: getRelationalDisplayName(node.schema),
+    };
+  }
+  if (node instanceof DataProductAccessPointSource) {
+    return { title: node.accessPoint, detail: node.dataProductName };
+  }
+  if (node instanceof IngestDatasetSource) {
+    return { title: node.dataSet, detail: node.ingestDefinitionName };
+  }
+  if (node instanceof FunctionSource) {
+    // its values, as the call takes them: `100000, (none)`
+    return {
+      title: node.functionName,
+      detail: node.values.length
+        ? node.values
+            .map((value) =>
+              value === undefined
+                ? '(none)'
+                : value.kind === 'invalid'
+                  ? value.text
+                  : getLiteralText(value),
+            )
+            .join(', ')
+        : undefined,
+    };
+  }
+  if (node instanceof ServiceSource) {
+    return { title: node.serviceName, detail: node.pattern };
+  }
+  return { title: node.describe() };
+};

package/src/components/canvas/CubeCanvasLayout.ts

@@ -21,7 +21,7 @@ import type { Connection, Query } from '@finos/legend-cube';
 export const CUBE_CANVAS_NODE_WIDTH = 200;
 export const CUBE_CANVAS_NODE_HEIGHT = 72;
 
-const RANK_SEPARATION = 80;
+const RANK_SEPARATION = 56;
 const NODE_SEPARATION = 32;
 
 /** A node's top-left corner on the canvas */

package/src/components/canvas/CubeCanvasNode.tsx

@@ -14,16 +14,18 @@
  * limitations under the License.
  */
 
-import { clsx, ContextMenu, WarningIcon } from '@finos/legend-art';
+import { clsx, ContextMenu, Tooltip, WarningIcon } from '@finos/legend-art';
 import { Handle, type NodeProps, Position } from '@xyflow/react';
 import { observer } from 'mobx-react-lite';
 import { useRef } from 'react';
+import { RUNNING_NODE_LABEL } from '../../__lib__/LegendCubeHelpText.js';
 import { useDrag, useDrop } from 'react-dnd';
 import { LEGEND_CUBE_TEST_ID } from '../../__lib__/LegendCubeTesting.js';
 import { CubeNodeIcon } from '../CubeNodeIcon.js';
 import {
   CUBE_OUTPUT_HANDLE_ID,
   type CubeCanvasFlowNode,
+  getCubeCanvasNodeLabel,
   getCubeCanvasNodeStatus,
   getInputHandleOffset,
 } from './CubeCanvasElements.js';
@@ -50,12 +52,20 @@ export const CubeCanvasNode = observer(
     const { node } = props.data;
     const editorState = useCubeCanvasEditorState();
     const status = getCubeCanvasNodeStatus(editorState, node);
+    const label = getCubeCanvasNodeLabel(
+      node,
+      editorState.registry.get(node.type)?.label,
+    );
     const connectable = !editorState.readOnly && node.acceptsNewInputs;
     const ref = useRef<HTMLDivElement>(null);
     const [, dragConnector] = useDrag<CubeNodeDragItem>(
       () => ({
         type: CUBE_DND_TYPE.NODE,
-        item: { nodeId: node.id },
+        // the drop changes the query, so the open editor applies first
+        item: () => {
+          editorState.nodeEditor.finish();
+          return { nodeId: node.id };
+        },
         canDrag: () => !editorState.readOnly,
       }),
       [editorState, node.id],
@@ -94,49 +104,84 @@ export const CubeCanvasNode = observer(
             style={{ top: getInputHandleOffset(index, node.ports.length) }}
           />
         ))}
-        <div
-          ref={ref}
-          className={clsx(
-            // React Flow must leave the mouse to the HTML drag: 'nodrag' keeps
-            // it from moving the node, 'nopan' from panning the canvas
-            'legend-cube__node nodrag nopan flex h-full w-full items-center gap-2 rounded border bg-[var(--color-bg-panel)] px-2 text-base text-[var(--color-text-primary)]',
-            status.isInvalid
-              ? 'border-[var(--color-status-error)]'
-              : status.isIncomplete
-                ? 'border-dashed border-[var(--color-status-warn)]'
-                : 'border-[var(--color-border-default)]',
-            {
-              'legend-cube__node--selected ring-2 ring-[var(--color-accent)]':
-                status.isCapture,
-              'legend-cube__node--invalid': status.isInvalid,
-              'legend-cube__node--incomplete': status.isIncomplete,
-              'legend-cube__node--resolving animate-pulse': status.isResolving,
-              'legend-cube__node--engine-error bg-[var(--color-status-error-bg)]':
-                status.hasEngineError,
-              'legend-cube__node--warning': status.hasWarnings,
-              'legend-cube__node--drop-target outline-dashed outline-2 outline-[var(--color-accent)]':
-                isDropTarget,
-            },
-          )}
-          title={status.tooltip}
-          aria-current={status.isCapture}
-          data-testid={LEGEND_CUBE_TEST_ID.CANVAS_NODE}
+        <Tooltip
+          // after a moment, above the node, one message a line (U1(c))
+          title={<div className="whitespace-pre-line">{status.tooltip}</div>}
+          placement="top"
+          enterDelay={500}
+          enterNextDelay={500}
+          disableInteractive={true}
+          // it describes the node, whose name stays its description
+          describeChild={true}
+          slotProps={{ tooltip: { className: 'max-w-[40rem]' } }}
         >
-          <CubeNodeIcon
-            icon={editorState.registry.get(node.type)?.icon}
-            className="shrink-0 text-lg text-[var(--color-text-secondary)]"
-          />
-          <span className="line-clamp-2 min-w-0 break-words leading-tight">
-            {node.describe()}
-          </span>
-          {status.hasWarnings && (
-            // the warning's text is in the node's tooltip
-            <WarningIcon
-              className="ml-auto shrink-0 text-[var(--color-status-warn)]"
-              aria-hidden={true}
+          <div
+            ref={ref}
+            className={clsx(
+              // React Flow must leave the mouse to the HTML drag: 'nodrag' keeps
+              // it from moving the node, 'nopan' from panning the canvas
+              'legend-cube__node nodrag nopan relative flex h-full w-full items-center gap-2 rounded border bg-[var(--color-bg-panel)] px-2 text-base text-[var(--color-text-primary)]',
+              status.isInvalid
+                ? 'border-[var(--color-status-error)]'
+                : status.isIncomplete
+                  ? 'border-dashed border-[var(--color-status-warn)]'
+                  : 'border-[var(--color-border-default)]',
+              {
+                'legend-cube__node--selected ring-2 ring-[var(--color-accent)]':
+                  status.isCapture,
+                'legend-cube__node--invalid': status.isInvalid,
+                'legend-cube__node--incomplete': status.isIncomplete,
+                'legend-cube__node--resolving animate-pulse':
+                  status.isResolving,
+                'legend-cube__node--engine-error bg-[var(--color-status-error-bg)]':
+                  status.hasEngineError,
+                'legend-cube__node--warning': status.hasWarnings,
+                'legend-cube__node--drop-target outline-dashed outline-2 outline-[var(--color-accent)]':
+                  isDropTarget,
+              },
+            )}
+            // the tooltip's text, for assistive technology and tests
+            aria-description={status.tooltip}
+            aria-current={status.isCapture}
+            data-testid={LEGEND_CUBE_TEST_ID.CANVAS_NODE}
+          >
+            <CubeNodeIcon
+              icon={editorState.registry.get(node.type)?.icon}
+              className="shrink-0 text-lg text-[var(--color-text-secondary)]"
             />
-          )}
-        </div>
+            <span className="flex min-w-0 flex-col leading-tight">
+              <span
+                className={clsx(
+                  'break-words',
+                  label.detail === undefined ? 'line-clamp-2' : 'line-clamp-1',
+                )}
+              >
+                {label.title}
+              </span>
+              {label.detail !== undefined && (
+                <span className="truncate text-sm text-[var(--color-text-muted)]">
+                  {label.detail}
+                </span>
+              )}
+            </span>
+            {status.hasWarnings && (
+              // the warning's text is in the node's tooltip
+              <WarningIcon
+                className="ml-auto shrink-0 text-[var(--color-status-warn)]"
+                aria-hidden={true}
+              />
+            )}
+            {status.isCapture && (
+              // the step Execute runs, marked on its corner
+              <span
+                className="absolute -top-2 right-2 rounded-sm bg-[var(--color-accent)] px-1 text-xs font-medium leading-4 text-[var(--color-text-on-accent)]"
+                data-testid={LEGEND_CUBE_TEST_ID.RUNNING_NODE_BADGE}
+              >
+                {`▶ ${RUNNING_NODE_LABEL}`}
+              </span>
+            )}
+          </div>
+        </Tooltip>
         <Handle
           id={CUBE_OUTPUT_HANDLE_ID}
           type="source"

package/src/components/canvas/CubeCanvasNodeFocus.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+
+/**
+ * Gives the keyboard focus back to a node on the canvas, as its editor
+ * closes from the keyboard (PLAN §11.8), when the focus was in the editor or
+ * nowhere: focus the user put elsewhere stays there
+ */
+export const returnFocusToCubeCanvasNode = (
+  nodeId: string,
+  editor: Element | null,
+  focused: Element | null,
+): void => {
+  if (
+    focused !== null &&
+    focused !== document.body &&
+    !editor?.contains(focused)
+  ) {
+    return;
+  }
+  Array.from(document.querySelectorAll<HTMLElement>('.react-flow__node'))
+    .find((element) => element.dataset.id === nodeId)
+    ?.focus();
+};

package/src/components/canvas/CubeNodeEditorAnchor.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 {
+  CUBE_CANVAS_NODE_HEIGHT,
+  CUBE_CANVAS_NODE_WIDTH,
+  type CubeCanvasPosition,
+} from './CubeCanvasLayout.js';
+
+/** A rectangle on the screen, in pixels from the window's top-left corner */
+export interface CubeScreenRect {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** React Flow's viewport: the pan, then the zoom */
+export type CubeCanvasTransform = readonly [
+  translateX: number,
+  translateY: number,
+  zoom: number,
+];
+
+/**
+ * Where a node is on the screen: its place in the layout, moved by the
+ * canvas's pan and zoom, inside the canvas's own place on the screen. Every
+ * node is the same size (PLAN §7.2), so nothing is measured.
+ */
+export const getCubeNodeScreenRect = (
+  position: CubeCanvasPosition,
+  transform: CubeCanvasTransform,
+  canvas: Pick<CubeScreenRect, 'left' | 'top'>,
+): CubeScreenRect => {
+  const [translateX, translateY, zoom] = transform;
+  return {
+    left: canvas.left + translateX + position.x * zoom,
+    top: canvas.top + translateY + position.y * zoom,
+    width: CUBE_CANVAS_NODE_WIDTH * zoom,
+    height: CUBE_CANVAS_NODE_HEIGHT * zoom,
+  };
+};
+
+/**
+ * Whether any of the node shows inside the canvas: a node panned out of
+ * view hides its editor, which stays open with its edits. A canvas not laid
+ * out yet (no size) hides nothing.
+ */
+export const isCubeNodeInView = (
+  node: CubeScreenRect,
+  canvas: CubeScreenRect,
+): boolean =>
+  canvas.width <= 0 ||
+  canvas.height <= 0 ||
+  (node.left < canvas.left + canvas.width &&
+    node.left + node.width > canvas.left &&
+    node.top < canvas.top + canvas.height &&
+    node.top + node.height > canvas.top);
+
+/** The rectangle as the DOM gives one, for a positioning library to read */
+export const toDOMRect = (rect: CubeScreenRect): DOMRect =>
+  ({
+    ...rect,
+    x: rect.left,
+    y: rect.top,
+    right: rect.left + rect.width,
+    bottom: rect.top + rect.height,
+    toJSON: () => rect,
+  }) as DOMRect;

package/src/components/dev-settings/CubeDevSettings.tsx

@@ -0,0 +1,154 @@
+/**
+ * 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 {
+  Dialog,
+  DropdownMenu,
+  DropdownMenuItem,
+  MenuIcon,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalFooterButton,
+  ModalHeader,
+  PanelForm,
+  PanelFormBooleanField,
+  PanelFormTextField,
+  useDropdownMenu,
+} from '@finos/legend-art';
+import { observer } from 'mobx-react-lite';
+import type { CubeEditorState } from '../../stores/CubeEditorState.js';
+
+/** Why Dev Settings can't change anything */
+const DEV_SETTINGS_UNAVAILABLE =
+  "This Legend deployment doesn't let Legend Cube's engine clients be changed.";
+
+/**
+ * The page's menu, at the top left, as Legend Query's editor has one: Dev
+ * Settings (PLAN §11.16)
+ */
+export const CubePageMenu = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const [openMenu, closeMenu, menuProps, isOpen] = useDropdownMenu();
+    return (
+      <>
+        <button
+          type="button"
+          className="flex h-6 w-6 shrink-0 items-center justify-center text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)]"
+          title="Menu"
+          aria-haspopup="menu"
+          aria-expanded={isOpen}
+          onClick={openMenu}
+        >
+          <MenuIcon />
+        </button>
+        <DropdownMenu
+          {...menuProps}
+          menuProps={{
+            elevation: 7,
+            slotProps: {
+              root: { slotProps: { backdrop: { invisible: true } } },
+            },
+          }}
+        >
+          <DropdownMenuItem
+            className="px-2 text-base"
+            onClick={() => {
+              closeMenu();
+              editorState.devSettings.open();
+            }}
+          >
+            Dev Settings
+          </DropdownMenuItem>
+        </DropdownMenu>
+      </>
+    );
+  },
+);
+
+/**
+ * Dev Settings, as Legend Query's editor offers them: the engine client's
+ * URL and its request compression, for Cube's engine clients
+ */
+export const CubeDevSettingsDialog = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const { devSettings } = editorState;
+    const { applicationStore } = editorState.host;
+    const darkMode =
+      !applicationStore.layoutService.TEMPORARY__isLightColorThemeEnabled;
+    return (
+      <Dialog open={devSettings.isOpen} onClose={() => devSettings.close()}>
+        <Modal darkMode={darkMode} className="w-[600px] max-w-full">
+          <ModalHeader>
+            <div className="modal__title">Dev Settings</div>
+          </ModalHeader>
+          <ModalBody>
+            {!devSettings.isAvailable && (
+              <div className="mb-2 text-base text-[var(--color-text-secondary)]">
+                {DEV_SETTINGS_UNAVAILABLE}
+              </div>
+            )}
+            <PanelForm>
+              <PanelFormTextField
+                name="Engine client base URL"
+                prompt={`The engine Legend Cube's requests go to, from the next one. The deployment's: ${devSettings.defaultBaseUrl ?? 'none'}`}
+                value={devSettings.baseUrlText}
+                isReadOnly={!devSettings.isAvailable}
+                update={(value) => devSettings.setBaseUrlText(value ?? '')}
+                errorMessage={devSettings.baseUrlError}
+                darkMode={darkMode}
+                fullWidth={true}
+              />
+              <PanelFormBooleanField
+                name="Engine client request payload compression"
+                prompt="Specifies if request payload should be compressed. Off, the browser's Network tab shows each request's JSON."
+                value={devSettings.requestCompression}
+                isReadOnly={!devSettings.isAvailable}
+                update={() =>
+                  devSettings.setRequestCompression(
+                    !devSettings.requestCompression,
+                  )
+                }
+              />
+            </PanelForm>
+          </ModalBody>
+          <ModalFooter>
+            <ModalFooterButton
+              darkMode={darkMode}
+              formatText={false}
+              type="secondary"
+              text="Reset engine URL"
+              disabled={
+                !devSettings.isAvailable ||
+                devSettings.baseUrlText === (devSettings.defaultBaseUrl ?? '')
+              }
+              onClick={() => devSettings.resetBaseUrl()}
+            />
+            <ModalFooterButton
+              darkMode={darkMode}
+              formatText={false}
+              type="secondary"
+              text="Close"
+              onClick={() => devSettings.close()}
+            />
+          </ModalFooter>
+        </Modal>
+      </Dialog>
+    );
+  },
+);