@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/components/editors/CubeSortEditor.tsx

@@ -14,126 +14,18 @@
  * limitations under the License.
  */
 
-import { ArrowDownIcon, ArrowUpIcon, TimesIcon } from '@finos/legend-art';
-import {
-  isSortableType,
-  isSortDirection,
-  MESSAGE_CANNOT_HAVE_DUPLICATES,
-  type Schema,
-  type SchemaColumn,
-  SORT_DIRECTION_DESCRIPTIONS,
-  SORT_DIRECTIONS,
-  validateSortKey,
-} from '@finos/legend-cube';
+import { isSortableType, type Schema } from '@finos/legend-cube';
 import { guaranteeType } from '@finos/legend-shared';
 import { observer } from 'mobx-react-lite';
-import { CUBE_SORT_COLUMN_DISABLED_REASON } from '../../__lib__/LegendCubeLabels.js';
-import {
-  type CubeSortRow,
-  CubeSortDraft,
-} from '../../stores/editors/CubeSortDraft.js';
+import { READ_ONLY_CUBE_TITLE } from '../../__lib__/LegendCubeLabels.js';
+import { CubeSortDraft } from '../../stores/editors/CubeSortDraft.js';
 import { CubeButton } from '../CubeButton.js';
-import { CubeColumnPicker } from './CubeColumnPicker.js';
 import type { CubeNodeEditorProps } from './CubeNodeEditorRegistry.js';
-
-const ROW_BUTTON_CLASS =
-  'flex h-6 w-6 items-center justify-center text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] disabled:text-[var(--color-text-disabled)]';
-
-const CubeSortRowEditor = observer(
-  (props: {
-    draft: CubeSortDraft;
-    row: CubeSortRow;
-    position: number;
-    count: number;
-    schema: Schema;
-    /** The columns of the other rows, which this row can't take */
-    takenColumns: ReadonlySet<string>;
-    problem: string | undefined;
-    readOnly: boolean;
-  }) => {
-    const {
-      draft,
-      row,
-      position,
-      count,
-      schema,
-      takenColumns,
-      problem,
-      readOnly,
-    } = props;
-    const isColumnDisabled = (column: SchemaColumn): string | undefined =>
-      !isSortableType(column.type)
-        ? CUBE_SORT_COLUMN_DISABLED_REASON.NOT_SORTABLE
-        : takenColumns.has(column.name)
-          ? CUBE_SORT_COLUMN_DISABLED_REASON.TAKEN
-          : undefined;
-    return (
-      <li className="flex flex-col gap-1 border-b border-[var(--color-border-subtle)] py-1">
-        <div className="grid grid-cols-[1fr_auto_auto_auto_auto] items-center gap-1">
-          <CubeColumnPicker
-            label={`Sort column ${position}`}
-            schema={schema}
-            value={row.column}
-            disabled={readOnly}
-            invalid={problem !== undefined}
-            isColumnDisabled={isColumnDisabled}
-            onChange={(name) => draft.setColumn(row.key, name)}
-          />
-          <select
-            aria-label={`Sort direction ${position}`}
-            className="h-6 rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] px-1 text-base"
-            value={row.direction}
-            disabled={readOnly}
-            onChange={(event) => {
-              const direction = event.target.value;
-              if (isSortDirection(direction)) {
-                draft.setDirection(row.key, direction);
-              }
-            }}
-          >
-            {SORT_DIRECTIONS.map((direction) => (
-              <option key={direction} value={direction}>
-                {SORT_DIRECTION_DESCRIPTIONS[direction]}
-              </option>
-            ))}
-          </select>
-          <button
-            className={ROW_BUTTON_CLASS}
-            aria-label={`Move sort column ${position} up`}
-            title="Sort by this column before the one above"
-            disabled={readOnly || position === 1}
-            onClick={() => draft.moveRow(row.key, -1)}
-          >
-            <ArrowUpIcon />
-          </button>
-          <button
-            className={ROW_BUTTON_CLASS}
-            aria-label={`Move sort column ${position} down`}
-            title="Sort by this column after the one below"
-            disabled={readOnly || position === count}
-            onClick={() => draft.moveRow(row.key, 1)}
-          >
-            <ArrowDownIcon />
-          </button>
-          <button
-            className={ROW_BUTTON_CLASS}
-            aria-label={`Remove sort column ${position}`}
-            title="Remove this sort column"
-            disabled={readOnly}
-            onClick={() => draft.removeRow(row.key)}
-          >
-            <TimesIcon />
-          </button>
-        </div>
-        {problem && (
-          <div className="text-sm text-[var(--color-status-error)]">
-            {problem}
-          </div>
-        )}
-      </li>
-    );
-  },
-);
+import {
+  CubeSortRowEditor,
+  getSortRowProblems,
+  getTakenSortColumns,
+} from './CubeSortRowEditor.js';
 
 /**
  * The Sort editor (spec §17.6: an ordered list of column and direction rows,
@@ -147,53 +39,39 @@ export const CubeSortEditor = observer((props: CubeNodeEditorProps) => {
   const draft = guaranteeType(props.draft, CubeSortDraft);
   const [schema] = props.inputSchemas as [Schema];
   const { rows } = draft;
-  // a row's problem, as the node will judge it; a blank row has none
-  const problems = rows.map((row, index) => {
-    if (!row.column) {
-      return undefined;
-    }
-    const errors: string[] = [];
-    validateSortKey(row, schema, errors);
-    return (
-      errors[0] ??
-      (rows.slice(0, index).some(({ column }) => column === row.column)
-        ? MESSAGE_CANNOT_HAVE_DUPLICATES('Sort columns')
-        : undefined)
-    );
-  });
+  const problems = getSortRowProblems(rows, schema);
   const sortable = schema.columns.filter((column) =>
     isSortableType(column.type),
   );
   const canAddRow = !readOnly && rows.length < sortable.length;
   return (
     <div className="flex flex-col gap-2 text-base">
-      <ul aria-label="Sort columns" className="max-h-80 overflow-auto">
+      <ul aria-label="Sort columns">
         {rows.map((row, index) => (
           <CubeSortRowEditor
             key={row.key}
-            draft={draft}
             row={row}
             position={index + 1}
             count={rows.length}
             schema={schema}
-            takenColumns={
-              new Set(
-                rows
-                  .filter((other) => other.key !== row.key && other.column)
-                  .map(({ column }) => column),
-              )
-            }
+            takenColumns={getTakenSortColumns(rows, row)}
             problem={problems[index]}
             readOnly={readOnly}
+            onColumn={(column) => draft.setColumn(row.key, column)}
+            onDirection={(direction) => draft.setDirection(row.key, direction)}
+            onMove={(offset) => draft.moveRow(row.key, offset)}
+            onRemove={() => draft.removeRow(row.key)}
           />
         ))}
       </ul>
       <div>
         <CubeButton
           title={
-            canAddRow
-              ? 'Add a column to sort by'
-              : 'Every column that can be sorted already has a row'
+            readOnly
+              ? READ_ONLY_CUBE_TITLE
+              : canAddRow
+                ? 'Add a column to sort by'
+                : 'Every column that can be sorted already has a row'
           }
           disabled={!canAddRow}
           onClick={() => draft.addRow()}

package/src/components/editors/CubeSortRowEditor.tsx

@@ -0,0 +1,176 @@
+/**
+ * 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 { ArrowDownIcon, ArrowUpIcon, TimesIcon } from '@finos/legend-art';
+import {
+  isSortableType,
+  isSortDirection,
+  MESSAGE_CANNOT_HAVE_DUPLICATES,
+  type Schema,
+  type SchemaColumn,
+  SORT_DIRECTION_DESCRIPTIONS,
+  SORT_DIRECTIONS,
+  type SortDirection,
+  validateSortKey,
+} from '@finos/legend-cube';
+import { observer } from 'mobx-react-lite';
+import { CUBE_SORT_COLUMN_DISABLED_REASON } from '../../__lib__/LegendCubeLabels.js';
+import type { CubeSortRow } from '../../stores/editors/CubeSortRows.js';
+import { CubeColumnPicker } from './CubeColumnPicker.js';
+
+const ROW_BUTTON_CLASS =
+  'flex h-6 w-6 items-center justify-center text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] disabled:text-[var(--color-text-disabled)]';
+
+/**
+ * Each sort row's first problem, as the node will judge it: its key
+ * (`validateSortKey`), then a column an earlier row has; a blank row has none
+ */
+export const getSortRowProblems = (
+  rows: readonly CubeSortRow[],
+  schema: Schema,
+): (string | undefined)[] =>
+  rows.map((row, index) => {
+    if (!row.column) {
+      return undefined;
+    }
+    const errors: string[] = [];
+    validateSortKey(row, schema, errors);
+    return (
+      errors[0] ??
+      (rows.slice(0, index).some(({ column }) => column === row.column)
+        ? MESSAGE_CANNOT_HAVE_DUPLICATES('Sort columns')
+        : undefined)
+    );
+  });
+
+/** The columns of the other rows, which a row can't take */
+export const getTakenSortColumns = (
+  rows: readonly CubeSortRow[],
+  row: CubeSortRow,
+): ReadonlySet<string> =>
+  new Set(
+    rows
+      .filter((other) => other.key !== row.key && other.column)
+      .map(({ column }) => column),
+  );
+
+/**
+ * One sort row (a Sort's, PLAN §11.4; a Partition's window, §11.6): its
+ * column, its direction, buttons that move it up or down and remove it, then
+ * its first problem. A column that can't be sorted, or that another row has,
+ * can't be picked.
+ */
+export const CubeSortRowEditor = observer(
+  (props: {
+    row: CubeSortRow;
+    position: number;
+    count: number;
+    schema: Schema;
+    /** The columns of the other rows, which this row can't take */
+    takenColumns: ReadonlySet<string>;
+    problem: string | undefined;
+    readOnly: boolean;
+    onColumn: (column: string) => void;
+    onDirection: (direction: SortDirection) => void;
+    onMove: (offset: -1 | 1) => void;
+    onRemove: () => void;
+  }) => {
+    const {
+      row,
+      position,
+      count,
+      schema,
+      takenColumns,
+      problem,
+      readOnly,
+      onColumn,
+      onDirection,
+      onMove,
+      onRemove,
+    } = props;
+    const isColumnDisabled = (column: SchemaColumn): string | undefined =>
+      !isSortableType(column.type)
+        ? CUBE_SORT_COLUMN_DISABLED_REASON.NOT_SORTABLE
+        : takenColumns.has(column.name)
+          ? CUBE_SORT_COLUMN_DISABLED_REASON.TAKEN
+          : undefined;
+    return (
+      <li className="flex flex-col gap-1 border-b border-[var(--color-border-subtle)] py-1">
+        <div className="grid grid-cols-[1fr_auto_auto_auto_auto] items-center gap-1">
+          <CubeColumnPicker
+            label={`Sort column ${position}`}
+            schema={schema}
+            value={row.column}
+            disabled={readOnly}
+            invalid={problem !== undefined}
+            isColumnDisabled={isColumnDisabled}
+            onChange={onColumn}
+          />
+          <select
+            aria-label={`Sort direction ${position}`}
+            className="h-6 rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] px-1 text-base"
+            value={row.direction}
+            disabled={readOnly}
+            onChange={(event) => {
+              const direction = event.target.value;
+              if (isSortDirection(direction)) {
+                onDirection(direction);
+              }
+            }}
+          >
+            {SORT_DIRECTIONS.map((direction) => (
+              <option key={direction} value={direction}>
+                {SORT_DIRECTION_DESCRIPTIONS[direction]}
+              </option>
+            ))}
+          </select>
+          <button
+            className={ROW_BUTTON_CLASS}
+            aria-label={`Move sort column ${position} up`}
+            title="Sort by this column before the one above"
+            disabled={readOnly || position === 1}
+            onClick={() => onMove(-1)}
+          >
+            <ArrowUpIcon />
+          </button>
+          <button
+            className={ROW_BUTTON_CLASS}
+            aria-label={`Move sort column ${position} down`}
+            title="Sort by this column after the one below"
+            disabled={readOnly || position === count}
+            onClick={() => onMove(1)}
+          >
+            <ArrowDownIcon />
+          </button>
+          <button
+            className={ROW_BUTTON_CLASS}
+            aria-label={`Remove sort column ${position}`}
+            title="Remove this sort column"
+            disabled={readOnly}
+            onClick={onRemove}
+          >
+            <TimesIcon />
+          </button>
+        </div>
+        {problem && (
+          <div className="text-sm text-[var(--color-status-error)]">
+            {problem}
+          </div>
+        )}
+      </li>
+    );
+  },
+);

package/src/components/editors/CubeSourceEditor.tsx

@@ -23,11 +23,14 @@ import { guaranteeType } from '@finos/legend-shared';
 import { flowResult } from 'mobx';
 import { observer } from 'mobx-react-lite';
 import {
-  CUBE_PENDING_LABEL,
-  getColumnTypeLabel,
-} from '../../__lib__/LegendCubeLabels.js';
+  CUBE_DIRECT_CONNECTION_FALLBACK_LABEL,
+  getCubeConnectionSummaryLabel,
+} from '../../__lib__/LegendCubeDirectConnectionLabels.js';
+import { CUBE_PENDING_LABEL } from '../../__lib__/LegendCubeLabels.js';
+import { getCubeDirectConnection } from '../../graph-manager/CubeDirectConnection.js';
+import { getCubeProjectCoordinates } from '../../graph-manager/CubeProject.js';
 import { CubeButton } from '../CubeButton.js';
-import { CubeColumnTypeIcon } from './CubeColumnPicker.js';
+import { CubeSchemaColumnsTable } from '../CubeSchemaColumnsTable.js';
 import type { CubeNodeEditorProps } from './CubeNodeEditorRegistry.js';
 
 /**
@@ -40,11 +43,43 @@ export const CubeSourceEditor = observer((props: CubeNodeEditorProps) => {
   const source = guaranteeType(props.draft.original, RelationalTableSource);
   const refreshing = editorState.isPendingSource(source);
   const { resolution } = source;
+  // a direct cube's tables all belong to a Database Cube builds: its
+  // connection says where they come from (PLAN §6.8)
+  const model = editorState.document.context?.model;
+  const connection = model ? getCubeDirectConnection(model) : undefined;
+  const description =
+    connection &&
+    editorState.host.connectionExplorer?.describeConnection(connection);
+  // a project cube's tables come from its project at the saved version (PLAN §6.3)
+  const project = model ? getCubeProjectCoordinates(model) : undefined;
   return (
     <div className="relative flex flex-col gap-2">
       <dl className="grid grid-cols-[max-content_1fr] gap-x-3 gap-y-1 text-base">
-        <dt className="text-[var(--color-text-secondary)]">Database</dt>
-        <dd className="min-w-0 break-all">{source.database}</dd>
+        {connection ? (
+          <>
+            <dt className="text-[var(--color-text-secondary)]">Connection</dt>
+            <dd className="min-w-0 break-words">
+              {description?.supported
+                ? getCubeConnectionSummaryLabel(description.summary)
+                : CUBE_DIRECT_CONNECTION_FALLBACK_LABEL}
+            </dd>
+          </>
+        ) : (
+          <>
+            {project && (
+              <>
+                <dt className="text-[var(--color-text-secondary)]">Project</dt>
+                <dd className="min-w-0 break-all">
+                  {project.groupId}:{project.artifactId}
+                </dd>
+                <dt className="text-[var(--color-text-secondary)]">Version</dt>
+                <dd>{project.versionId}</dd>
+              </>
+            )}
+            <dt className="text-[var(--color-text-secondary)]">Database</dt>
+            <dd className="min-w-0 break-all">{source.database}</dd>
+          </>
+        )}
         <dt className="text-[var(--color-text-secondary)]">Schema</dt>
         <dd>{getRelationalDisplayName(source.schema)}</dd>
         <dt className="text-[var(--color-text-secondary)]">Table</dt>
@@ -70,30 +105,7 @@ export const CubeSourceEditor = observer((props: CubeNodeEditorProps) => {
       </div>
       <PanelLoadingIndicator isLoading={refreshing} />
       {resolution.kind === 'resolved' ? (
-        <table className="w-full text-base" aria-label="Columns">
-          <thead>
-            <tr className="text-left text-[var(--color-text-secondary)]">
-              <th className="font-normal">Column</th>
-              <th className="font-normal">Type</th>
-            </tr>
-          </thead>
-          <tbody>
-            {resolution.schema.columns.map((column) => (
-              <tr key={column.name}>
-                <td className="break-all pr-2">{column.name}</td>
-                <td title={column.type.fullName}>
-                  <span className="flex items-center gap-1">
-                    <CubeColumnTypeIcon
-                      type={column.type}
-                      className="text-[var(--color-text-secondary)]"
-                    />
-                    {getColumnTypeLabel(column)}
-                  </span>
-                </td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
+        <CubeSchemaColumnsTable schema={resolution.schema} />
       ) : (
         <div className="text-base text-[var(--color-text-secondary)]">
           {resolution.kind === 'failed'

package/src/components/editors/CubeWarehouseControl.tsx

@@ -0,0 +1,113 @@
+/**
+ * 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 { CubeContext } from '@finos/legend-cube';
+import { observer } from 'mobx-react-lite';
+import { useEffect, useRef, useState } from 'react';
+import {
+  CUBE_WAREHOUSE_APPLY_TITLE,
+  getCubeWarehouseErrorHint,
+} from '../../__lib__/LegendCubeDataProductLabels.js';
+import { READ_ONLY_CUBE_TITLE } from '../../__lib__/LegendCubeLabels.js';
+import {
+  CubeDataProductRunErrorKind,
+  type CubeDataProductRuntimeState,
+} from '../../stores/CubeDataProductRuntimeState.js';
+import { CubeButton } from '../CubeButton.js';
+
+/**
+ * The warehouse a lakehouse cube runs on, edited in place: Apply, Enter, or
+ * closing the node editor, runs the cube on another one, as one undo step. Text typed but not
+ * applied belongs to the cube's context it was typed on; once the context
+ * changes, e.g. on Undo, the control shows the cube's warehouse again.
+ * Below it, after a run the warehouse failed, what to do about it
+ */
+export const CubeWarehouseControl = observer(
+  (props: { runtime: CubeDataProductRuntimeState; readOnly: boolean }) => {
+    const { runtime, readOnly } = props;
+    const { context } = runtime.editorState.document;
+    const current = runtime.effectiveWarehouse ?? '';
+    const [draft, setDraft] = useState<
+      { context: CubeContext | undefined; text: string } | undefined
+    >();
+    const text =
+      draft !== undefined && draft.context === context ? draft.text : current;
+    const disabled = readOnly || !runtime.canEditWarehouse;
+    const canApply =
+      !disabled && text.trim().length > 0 && text.trim() !== current;
+    const apply = (): void => {
+      if (canApply && runtime.setWarehouse(text)) {
+        setDraft(undefined);
+      }
+    };
+    // closing the node editor applies, as for every edit (PLAN §11.8),
+    // without remembering it for the viewer's next cubes: Undo takes it back
+    const latest = useRef({ text, canApply });
+    latest.current = { text, canApply };
+    useEffect(
+      () =>
+        runtime.editorState.nodeEditor.addFlusher(
+          () => {
+            if (
+              latest.current.canApply &&
+              runtime.setWarehouse(latest.current.text, { remember: false })
+            ) {
+              setDraft(undefined);
+            }
+          },
+          { isPending: () => latest.current.canApply },
+        ),
+      [runtime],
+    );
+    return (
+      <>
+        <span className="flex min-w-0 items-center gap-1">
+          <input
+            className="h-6 min-w-0 flex-1 rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] px-1 text-base text-[var(--color-text-primary)] disabled:text-[var(--color-text-secondary)]"
+            aria-label="Warehouse"
+            spellCheck={false}
+            disabled={disabled}
+            title={readOnly ? READ_ONLY_CUBE_TITLE : undefined}
+            value={text}
+            onChange={(event) =>
+              setDraft({ context, text: event.target.value })
+            }
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                apply();
+              }
+            }}
+          />
+          <CubeButton
+            title={readOnly ? READ_ONLY_CUBE_TITLE : CUBE_WAREHOUSE_APPLY_TITLE}
+            disabled={!canApply}
+            onClick={apply}
+          >
+            Apply
+          </CubeButton>
+        </span>
+        {runtime.runErrorKind === CubeDataProductRunErrorKind.WAREHOUSE && (
+          <span
+            className="mt-1 block text-sm text-[var(--color-status-error)]"
+            role="alert"
+          >
+            {getCubeWarehouseErrorHint(current, runtime.canEditWarehouse)}
+          </span>
+        )}
+      </>
+    );
+  },
+);

package/src/components/editors/useCubeNodeEditorDismiss.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 { useEffect } from 'react';
+import type { CubeEditorState } from '../../stores/CubeEditorState.js';
+import { returnFocusToCubeCanvasNode } from '../canvas/CubeCanvasNodeFocus.js';
+
+/**
+ * What a press outside the floating editor leaves alone (PLAN §11.8):
+ * a node, whose click applies and opens it or selects it; the canvas's
+ * background, controls and minimap, so panning or zooming keeps the editor
+ * (a plain click on the background closes it, through the canvas); the
+ * splitter above the results, as the editor follows its node when the
+ * canvas is resized; and MUI's layers, where a dropdown, menu or dialog
+ * opened from the editor lives.
+ */
+const LEFT_ALONE =
+  '.react-flow__node, .react-flow__pane, .react-flow__controls, .react-flow__minimap, .reflex-splitter, .MuiModal-root, .MuiPopover-root, .MuiPopper-root';
+
+/** An Escape there is the results grid's, e.g. closing its menu */
+const GRID_LAYERS = '.ag-popup, .ag-menu';
+
+/** Whether a press on the target, outside the editor, closes it */
+export const isCubeNodeEditorDismissedBy = (
+  target: EventTarget | null,
+  editor: Element | null,
+): boolean =>
+  target instanceof Element &&
+  !editor?.contains(target) &&
+  target.closest(LEFT_ALONE) === null;
+
+/**
+ * Closes the floating node editor, applying its edits, on a press of the
+ * main button outside it, or on Escape (PLAN §11.8, spec §17.5). A press
+ * closes it as it goes down, before the click, so a button pressed outside
+ * (Execute, Undo) acts on the applied edits. Nothing closes it while a Cube
+ * dialog is open or something opened from it holds it; an Escape a field or
+ * a dialog already used is theirs, and so is one in the results grid's menu.
+ * A surface opened from the editor and shown elsewhere (a portal) must be
+ * one of MUI's layers, or hold the editor open (`nodeEditor.holdOpen()`),
+ * or a press in it closes the editor.
+ */
+export const useCubeNodeEditorDismiss = (
+  editorState: CubeEditorState,
+  editorRef: React.RefObject<Element | null>,
+): void => {
+  const isOpen = editorState.nodeEditor.nodeId !== undefined;
+  useEffect(() => {
+    if (!isOpen) {
+      return undefined;
+    }
+    const canDismiss = (): boolean =>
+      !editorState.isDialogOpen && !editorState.nodeEditor.isHeld;
+    const onPointerDown = (event: PointerEvent): void => {
+      if (
+        event.button === 0 &&
+        // on macOS, Ctrl with the main button is a right-click
+        !event.ctrlKey &&
+        canDismiss() &&
+        isCubeNodeEditorDismissedBy(event.target, editorRef.current)
+      ) {
+        editorState.nodeEditor.finish();
+      }
+    };
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (
+        event.key === 'Escape' &&
+        !event.defaultPrevented &&
+        !(
+          event.target instanceof Element &&
+          event.target.closest(GRID_LAYERS) !== null
+        ) &&
+        canDismiss()
+      ) {
+        const { nodeId } = editorState.nodeEditor;
+        const focused = document.activeElement;
+        if (editorState.nodeEditor.finish() && nodeId !== undefined) {
+          returnFocusToCubeCanvasNode(nodeId, editorRef.current, focused);
+        }
+      }
+    };
+    // capturing, so a press that something else stops still closes it
+    document.addEventListener('pointerdown', onPointerDown, true);
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown, true);
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, [editorState, editorRef, isOpen]);
+};