@finos/legend-cube-builder 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finos/legend-cube-builder",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Legend Cube builder: the canvas UI and the Legend engine adapter of the Legend Cube query builder",
   "keywords": [
     "legend",
@@ -47,7 +47,7 @@
     "@dagrejs/dagre": "1.1.4",
     "@finos/legend-application": "16.0.129",
     "@finos/legend-art": "7.1.169",
-    "@finos/legend-cube": "0.0.5",
+    "@finos/legend-cube": "0.0.6",
     "@finos/legend-graph": "32.8.0",
     "@finos/legend-lego": "2.0.231",
     "@finos/legend-server-depot": "6.1.24",

package/src/__lib__/LegendCubeHelpText.ts

@@ -22,6 +22,7 @@ import {
   Distinct,
   Drop,
   ExpressionFilter,
+  Explode,
   Extend,
   Filter,
   FunctionSource,
@@ -67,6 +68,9 @@ export const CUBE_NODE_HELP_TEXT: Readonly<Record<string, string>> = {
     'Reduces the number of rows in the previous data set, removing the specified number of rows from the beginning of the data set.',
   [Extend.TYPE]:
     'Extends outgoing data set with new columns produced by expressions.',
+  /** Added by Cube: the original has no JSON operations (PLAN §11.20) */
+  [Explode.TYPE]:
+    'Makes a row for each element of an array in a JSON (Variant) column of the previous data set, keeping its columns and adding the element as a new column. A row whose array is empty, or missing, is kept once, with an empty element.',
   [Filter.TYPE]:
     'Reduces the number of rows in the previous data set, keeping only rows matching the specified criteria.',
   /** Added by Cube: the original has no filter by expression (PLAN §11.11) */

package/src/__lib__/LegendCubeLabels.ts

@@ -141,13 +141,13 @@ const TYPE_FAMILY_LABELS: Partial<Record<TypeFamily, string>> = {
 
 /**
  * A column's type as the editors show it: the kind of value, and whether it
- * can be empty, e.g. `Text, can be empty`; an enumeration, or a type Cube
- * doesn't know, by its name. The exact type (`getExactColumnTypeLabel`) is
- * on hover.
+ * is optional (can be empty), e.g. `Text, optional`; an enumeration, or a
+ * type Cube doesn't know, by its name. The exact type
+ * (`getExactColumnTypeLabel`) is on hover.
  */
 export const getColumnTypeLabel = (column: SchemaColumn): string =>
   `${TYPE_FAMILY_LABELS[column.type.family] ?? column.type.displayName}${
-    column.nullable ? ', can be empty' : ''
+    column.nullable ? ', optional' : ''
   }`;
 
 const listColumns = (columns: readonly SchemaColumn[]): string =>
@@ -188,6 +188,12 @@ export const CUBE_SORT_COLUMN_DISABLED_REASON = {
 };
 
 /** Why the grid's quick actions (spec §12.4) can't be used */
+/** Why a Variant cell's Open JSON can't be used (PLAN §11.20) */
+export const CUBE_JSON_DISABLED_REASON = {
+  NOT_A_ROW: "A group row's cell holds no row's document.",
+  EMPTY: 'This cell is empty.',
+};
+
 export const CUBE_QUICK_ACTION_DISABLED_REASON = {
   STALE_ROWS:
     'Execute again: these rows are from an earlier version of the query.',
@@ -343,6 +349,50 @@ export const PIVOT_EDITOR_NOTES = [
   "Pivot runs on Snowflake, Databricks, SingleStore and DuckDB; other databases, such as H2 and Postgres, can't run it.",
 ] as const;
 
+/** Why the Explode Array editor won't pick a column (PLAN §11.20) */
+export const EXPLODE_COLUMN_DISABLED_REASON = {
+  /** a column of another type than Variant */
+  NOT_JSON: 'not JSON',
+} as const;
+
+/** Under the Explode Array editor (PLAN §11.20) */
+export const EXPLODE_EDITOR_NOTES = [
+  'One row per element of the array, the other columns repeated on each. A row whose array is empty, or that has none, is kept once, with an empty element.',
+  "Find arrays reads the column's first values, as Explore JSON does, and lists the arrays they hold. Keys can be typed too: none when the column is the array.",
+  'The element is JSON: Explore JSON, in its column menu, makes columns of its fields. Explode Array runs on Snowflake, Databricks, Postgres and DuckDB.',
+] as const;
+
+/** Explore JSON's one row per element offer, as its tooltip explains it (PLAN §11.20) */
+export const CUBE_JSON_EXPLODE_OFFER_TITLE =
+  'Adds an Explode Array node: a row for each element, the element as a new JSON column. One array at a time.';
+
+/** The tooltips of a Variant column's fields in an expression editor (PLAN §11.20, V.9) */
+export const CUBE_JSON_FIELDS_TITLE = {
+  OPEN: 'Show its fields, read from its first values just before this step: listed in Runs; a field clicked is written into the expression',
+  FORMS:
+    'Other forms of the field: counts, lists, the first element, totals, as JSON',
+  EXPLODE:
+    'One row per element is a step of its own: add Explode Array from the palette, or from Explore JSON in the grid',
+  READ_AGAIN: 'Read the column again',
+  EVERY_ROW:
+    'Read every value of the column, for the shape of the whole column: listed in Runs, and it can be stopped',
+} as const;
+
+/** What a Variant column's fields were read from, in an expression editor (PLAN §11.20, V.9) */
+export const getCubeJsonFieldsStatus = (sample: {
+  readonly rows: number;
+  readonly complete: boolean;
+}): string => {
+  const count = sample.rows.toLocaleString('en-US');
+  return sample.complete
+    ? `All ${count} values read, just before this step`
+    : `The first ${count} values read, just before this step`;
+};
+
+/** Says that Find arrays found none in the values read (PLAN §11.20) */
+export const EXPLODE_NO_ARRAYS_NOTICE =
+  'No array in the values read: type the keys to one.';
+
 /** Says that Load values found no value to list (PLAN §11.12) */
 export const PIVOT_NO_VALUES_NOTICE =
   'The pivot column has no value to list: its rows are all empty, or there are none.';
@@ -364,7 +414,7 @@ export const PARTITION_EDITOR_NOTES = [
   "Rank, Dense Rank and Row Number need a sort column. Tied rows share a rank: Rank then skips numbers and Dense Rank doesn't. Row Number numbers every row, and rows tied on this node's sort columns get their numbers in no set order: add a sort column that tells them apart, such as an id, for a stable top N.",
   'NTile, Percent Rank and Cumulative Distribution need a sort column too. NTile splits each partition into buckets of near-equal size, numbered from 1 in the sort order; Percent Rank and Cumulative Distribution give each row its place in its partition, from 0 to 1.',
   "Lag and Lead read a column from the row so many rows before or after in the sort order, and are empty at the partition's edges. First and Last read it from the partition's first and last rows, the same on every row. They need a sort column, and rows tied on it may give any of them.",
-  "On ClickHouse, First and Last skip empty values, and Lag and Lead show a column's default, such as 0, at the partition's edges instead of empty, unless the column can be empty there.",
+  "On ClickHouse, First and Last skip empty values, and Lag and Lead show a column's default, such as 0, at the partition's edges instead of empty, unless the column is optional there.",
   "Their sort columns also make this node's other functions run. For totals over the whole partition, add another Apply Window Functions without sort columns.",
   'Empty sort values come last when ascending and first when descending on H2; other databases may differ.',
   "A Sort before this node doesn't order the window: its sort columns do. The rows keep the order they came in.",
@@ -391,8 +441,9 @@ export const DIFFERENCE_EDITOR_NOTES = [
 /** What the Extend editor says about its expressions (PLAN §11.7) */
 export const EXTEND_EDITOR_NOTES = [
   'Write each expression as a lambda of one row, such as x | $x.PRICE * $x.QTY: $x.PRICE reads the column PRICE. A column can use the new columns above it.',
-  'A column that can be empty needs ->toOne() before arithmetic, such as $x.QTY->toOne() * 2; an empty value still gives an empty result. Every new column can be empty.',
+  'An optional column needs ->toOne() before arithmetic, such as $x.QTY->toOne() * 2; an empty value still gives an empty result. Every new column is optional.',
   "Validate (F10) checks the expressions with the engine, types them, and plans them for this cube's database: some functions type, but not every database runs them.",
+  'A JSON (Variant) column’s {} opens its fields, read from its first values just before this step: a field clicked is written into the expression last used, and + column adds it as a new column.',
 ];
 
 /** Why the Extend editor's Apply waits (PLAN §11.7) */
@@ -434,14 +485,15 @@ export const EXPRESSION_FILTER_PARENTHESES_HINT =
 export const EXPRESSION_FILTER_EDITOR_NOTES = [
   "A condition of one row, written as in Query's text mode: x | $x.SHIPPED_DATE > $x.REQUIRED_DATE. The rows for which it is true are kept, in their order.",
   'Put each comparison in parentheses when you combine them: ($x.A > 1) && ($x.B > 3). In Pure, &&, || and ! bind as tightly as >, <, >= and <=; == binds tighter.',
-  'A column that can be empty, compared directly ($x.A > 6), fails the condition when it is empty and passes its negation. After ->toOne(), an empty value fails both.',
+  'An optional column, compared directly ($x.A > 6), fails the condition when it is empty and passes its negation. After ->toOne(), an empty value fails both.',
   "Validate (F10) checks the condition with the engine and plans it for the cube's database.",
   "startsWith, endsWith and contains can't take a value with a backslash (\\) yet, nor, on DuckDB, one with % or _.",
+  'A JSON (Variant) column’s {} opens its fields, read from its first values just before this step: a field clicked is written into the condition.',
 ] as const;
 
 /** The hint after an engine error on a column that can be empty, in arithmetic (PLAN §11.7) */
 export const EXTEND_TO_ONE_HINT =
-  'A column that can be empty needs ->toOne() first, such as $x.QTY->toOne() + 1.';
+  'An optional column needs ->toOne() first, such as $x.QTY->toOne() + 1.';
 
 /** The problem a database refusing an Extend's or a Filter by Expression's plan gives (PLAN §11.7, §11.11) */
 export const getExtendPlanProblem = (

package/src/__lib__/LegendCubeNavigation.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+
+/**
+ * The anchor Legend Marketplace's data product viewer gives an access point
+ * group, which it reads from the URL hash on load: as Legend Query writes it
+ * (`EXTERNAL_APPLICATION_NAVIGATION__generateMarketplaceDataProductUrl`)
+ *
+ * @external_application_navigation This depends on Legend Marketplace routing and is hardcoded so it's potentially brittle
+ */
+const EXTERNAL_APPLICATION_NAVIGATION__generateCubeAccessPointGroupAnchor = (
+  accessPointGroupId: string,
+): string =>
+  encodeURIComponent(
+    `apg-${accessPointGroupId}`.trim().toLowerCase().replace(/\s+/gu, '-'),
+  );
+
+/**
+ * A deployed data product's page in Legend Marketplace, at its access point
+ * group when one is given, as Legend Query links to it (PLAN §11.18)
+ *
+ * @external_application_navigation This depends on Legend Marketplace routing and is hardcoded so it's potentially brittle
+ */
+export const EXTERNAL_APPLICATION_NAVIGATION__generateCubeMarketplaceDataProductUrl =
+  (
+    marketplaceApplicationUrl: string,
+    dataProductId: string,
+    deploymentId: string,
+    accessPointGroupId?: string | undefined,
+  ): string =>
+    `${marketplaceApplicationUrl}/dataProduct/deployed/${dataProductId}/${deploymentId}${
+      accessPointGroupId
+        ? `#${EXTERNAL_APPLICATION_NAVIGATION__generateCubeAccessPointGroupAnchor(accessPointGroupId)}`
+        : ''
+    }`;

package/src/__lib__/LegendCubeTesting.ts

@@ -38,4 +38,6 @@ export enum LEGEND_CUBE_TEST_ID {
   GRID_TOOLBAR = 'legend-cube__grid-toolbar',
   EXECUTION_ERROR = 'legend-cube__execution-error',
   SQL_PANEL = 'legend-cube__sql-panel',
+  JSON_VIEWER = 'legend-cube__json-viewer',
+  JSON_EXPLORER = 'legend-cube__json-explorer',
 }

package/src/__lib__/LegendCubeTour.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 {
+  EXECUTE_SHORTCUT_LABEL,
+  REDO_SHORTCUT_LABEL,
+  UNDO_SHORTCUT_LABEL,
+} from './LegendCubeCommand.js';
+
+// The editor's guided tour (PLAN §11.21): its steps, in order, each pointing
+// at the controls marked with its anchor. A control joins a step by carrying
+// `cubeTourAnchor(...)`; a step whose controls aren't on the page (the graph
+// hidden, no run yet, a host without examples) is skipped. A new step adds
+// its anchor here, its text below, and the anchor on its controls.
+
+/** The attribute that marks a control as a tour step's */
+export const CUBE_TOUR_ANCHOR_ATTRIBUTE = 'data-cube-tour';
+
+export enum CUBE_TOUR_ANCHOR {
+  SOURCES = 'sources',
+  STEPS = 'steps',
+  CANVAS = 'canvas',
+  RUNNING_STEP = 'running-step',
+  EXECUTE = 'execute',
+  GRID_MODE = 'grid-mode',
+  RESULTS = 'results',
+  SHOW_SQL = 'show-sql',
+  RUNS = 'runs',
+  CUBE_MENU = 'cube-menu',
+  ADD_ITEMS = 'add-items',
+  EXAMPLES = 'examples',
+  VIEW = 'view',
+  PAGE_MENU = 'page-menu',
+}
+
+/** The props that mark a control as a tour step's */
+export const cubeTourAnchor = (
+  anchor: CUBE_TOUR_ANCHOR,
+): { [CUBE_TOUR_ANCHOR_ATTRIBUTE]: string } => ({
+  [CUBE_TOUR_ANCHOR_ATTRIBUTE]: anchor,
+});
+
+/** Where a step's card sits beside its controls */
+export type CubeTourPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+export interface CubeTourStep {
+  readonly title: string;
+  readonly text: string;
+  /** The controls it points at; none for a card in the middle of the page */
+  readonly anchor?: CUBE_TOUR_ANCHOR | undefined;
+  readonly placement?: CubeTourPlacement | undefined;
+}
+
+/** The example the tour opens on an empty cube, where examples are offered */
+export const CUBE_TOUR_EXAMPLE_ID = 'northwind-top-customers';
+
+export const CUBE_EDITOR_TOUR: readonly CubeTourStep[] = Object.freeze([
+  {
+    title: 'Welcome to Legend Cube',
+    text: 'A cube is a query built as a chain of steps: a source of rows, then steps that sort, group, filter or join them. This tour shows where everything is: Next (or the → key) moves on, and Esc ends it.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.SOURCES,
+    placement: 'right',
+    title: 'Sources',
+    text: 'Where the rows come from: a database table, a function, a data product or a service. Click one, or drop it on the canvas.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.STEPS,
+    placement: 'right',
+    title: 'Steps',
+    text: 'Each step works on the rows of the step before it. Click one to add it after the selected step, or drop it on the canvas. A greyed-out step says why when you hover over it.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.CANVAS,
+    placement: 'bottom',
+    title: 'The graph',
+    text: 'Your query, from left to right. Click a step to edit it: its editor opens beside it, with a ? that says what the step does.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.RUNNING_STEP,
+    placement: 'bottom',
+    title: 'The step that runs',
+    text: 'Execute runs the query up to the step marked Runs. To run up to another step, open its editor and click Run this step.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.EXECUTE,
+    placement: 'top',
+    title: 'Execute',
+    text: `Runs the query and shows its rows below (${EXECUTE_SHORTCUT_LABEL}). Rows caps how many rows come back.`,
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.GRID_MODE,
+    placement: 'top',
+    title: 'Server-side or Local',
+    text: 'Server-side: each sort and drill-down in the grid runs on the engine, over every row of the query. Local: the grid groups, pivots and filters the rows already fetched, in your browser.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.RESULTS,
+    placement: 'top',
+    title: 'The results',
+    text: 'The rows of the last run. Right-click a cell to sort, group or filter by its column as a new step, drill down, format a number column, or export the rows.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.SHOW_SQL,
+    placement: 'top',
+    title: 'Show SQL',
+    text: 'The SQL the last run sent to the database.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.RUNS,
+    placement: 'top',
+    title: 'Runs',
+    text: 'The latest runs, fetches and exports, each with its SQL and how long it took.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.CUBE_MENU,
+    placement: 'bottom',
+    title: 'The Cube menu',
+    text: 'Start a new cube, import or export one, or read a Pure query in as steps with Import Pure.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.ADD_ITEMS,
+    placement: 'bottom',
+    title: 'Add Items',
+    text: "The palette's sources and steps, as a menu.",
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.EXAMPLES,
+    placement: 'bottom',
+    title: 'Examples',
+    text: 'Ready-made cubes on sample data, to try things out.',
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.VIEW,
+    placement: 'bottom',
+    title: 'Undo, Show Pure, Hide graph',
+    text: `Undo (${UNDO_SHORTCUT_LABEL}) and Redo (${REDO_SHORTCUT_LABEL}) every change. Show Pure shows the Pure query Execute runs. Hide graph leaves more room for the results.`,
+  },
+  {
+    anchor: CUBE_TOUR_ANCHOR.PAGE_MENU,
+    placement: 'right',
+    title: "That's the tour",
+    text: 'Take it again from this menu whenever you like.',
+  },
+]);
+
+export const CUBE_TOUR_LABEL = {
+  START: 'Take the tour',
+  /** The empty canvas's offer */
+  OFFER: 'New to Legend Cube?',
+  NEXT: 'Next',
+  BACK: 'Back',
+  DONE: 'Done',
+  END: 'End the tour',
+  progress: (step: number, steps: number): string => `${step} of ${steps}`,
+  /** Added to the first step when the tour opened its example */
+  EXAMPLE_OPENED:
+    'The tour opened the example "Top customers by orders" to show you around; Undo puts the empty cube back.',
+};

package/src/__test-utils__/CubeExampleTestUtils.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 {
+  buildSchemasAndValidity,
+  createNodeRegistry,
+  Extend,
+  type ModelContext,
+  Query,
+  RelationalTableSource,
+  Schema,
+} from '@finos/legend-cube';
+import type { CubeEngine } from '../graph-manager/CubeEngine.js';
+import {
+  buildCubeExtendTypingLambdas,
+  readCubeExtendTyping,
+} from '../stores/CubeExtendTyping.js';
+import type { CubeExample } from '../stores/CubeExamples.js';
+
+/**
+ * The query with each Extend typed by the engine, in node order, as the
+ * editor types them in the background
+ */
+export const TEST__typeExtendsOnEngine = async (
+  engine: CubeEngine,
+  model: ModelContext,
+  input: Query,
+): Promise<Query> => {
+  const registry = createNodeRegistry();
+  let query = input;
+  for (const node of query.nodes) {
+    if (node instanceof Extend) {
+      const columns = node.columns.map(({ name, lambda }) => ({
+        name,
+        lambda: lambda as NonNullable<typeof lambda>,
+      }));
+      const [inputId] = query.getInputIds(node.id);
+      const answers = await engine.typeLambdas(
+        model,
+        buildCubeExtendTypingLambdas(query, node, columns, registry, false),
+      );
+      const { typing } = readCubeExtendTyping(
+        answers,
+        node,
+        buildSchemasAndValidity(query, registry.queryRules).schemas.get(
+          inputId ?? '',
+        ) as Schema,
+        columns,
+        undefined,
+      );
+      query = query.replace(
+        new Extend(node.id, node.columns, typing, node.rest),
+      );
+    }
+  }
+  return query;
+};
+
+/**
+ * An example's cube as opening it types it, on the engine: its tables, then
+ * each Extend, in node order, as the editor types it in the background (an
+ * Extend parsing JSON, PLAN §11.20)
+ */
+export const TEST__openExampleOnEngine = async (
+  engine: CubeEngine,
+  example: CubeExample,
+): Promise<{ model: ModelContext; runtime: string; query: Query }> => {
+  const document = example.createDocument();
+  const model = document.context?.model;
+  const runtime = document.context?.runtime;
+  if (!model || !runtime) {
+    throw new Error(`Example ${example.id} has no model or runtime`);
+  }
+  const sources = document.query.nodes.filter(
+    (node): node is RelationalTableSource =>
+      node instanceof RelationalTableSource,
+  );
+  const typed = await engine.resolveSchemas(
+    model,
+    new Map(
+      sources.map((source) => [
+        source.id,
+        [source.database, source.schema, source.table] as const,
+      ]),
+    ),
+  );
+  const query = new Query(
+    document.query.nodes.map((node) => {
+      if (!(node instanceof RelationalTableSource)) {
+        return node;
+      }
+      const schema = typed.get(node.id);
+      if (!(schema instanceof Schema)) {
+        throw schema ?? new Error(`No schema for ${node.id}`);
+      }
+      return node.withResolution({ kind: 'resolved', schema });
+    }),
+    document.query.connections,
+    document.query.selected,
+  );
+  return {
+    model,
+    runtime,
+    query: await TEST__typeExtendsOnEngine(engine, model, query),
+  };
+};

package/src/__test-utils__/CubeVariantTestUtils.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 { expect } from '@jest/globals';
+import {
+  CubeDocument,
+  PrimitiveType,
+  Query,
+  SchemaColumn,
+} from '@finos/legend-cube';
+import { flowResult } from 'mobx';
+import type { CubeResult } from '../graph-manager/CubeEngine.js';
+import { CubeEditorState } from '../stores/CubeEditorState.js';
+import { CUBE_NORTHWIND_MODEL } from '../stores/fixtures/CubeNorthwindModel.js';
+import { TEST__createCubeHost } from './CubeTestApplication.js';
+import {
+  NORTHWIND_RUNTIME,
+  northwindTable,
+} from './CubeNorthwindTestQueries.js';
+import {
+  createFakeNorthwindOutline,
+  type FakeCubeEngine,
+} from './FakeCubeEngine.js';
+
+// A cube whose rows hold a Variant column, PAYLOAD, for Explore JSON's tests
+// (PLAN §11.20): Northwind's ORDERS as a table of a model whose runtime runs on
+// the database type given
+
+export const TEST__PAYLOAD = new SchemaColumn(
+  'PAYLOAD',
+  PrimitiveType.get('Variant'),
+  true,
+);
+
+/** ORDERS' columns in these tests: an id, PAYLOAD, and a number */
+export const TEST__PAYLOAD_COLUMNS = [
+  new SchemaColumn(
+    'ORDER_ID',
+    PrimitiveType.get('meta::pure::precisePrimitives::Int'),
+    false,
+  ),
+  TEST__PAYLOAD,
+  // a name an offer would take, in another case
+  new SchemaColumn('PAYLOAD_TAGS_COUNT', PrimitiveType.get('Integer'), true),
+];
+
+export const TEST__PAYLOAD_DOCUMENTS = [
+  '{"user":{"name":"ann","tier":"gold"},"tags":["a","b"]}',
+  '{"user":{"name":"bob"},"tags":[]}',
+];
+
+/** The engine's answer to a read of PAYLOAD: these documents, one per row */
+export const TEST__payloadSample = (
+  documents: readonly string[] = TEST__PAYLOAD_DOCUMENTS,
+): CubeResult => ({
+  columns: ['PAYLOAD'],
+  rows: documents.map((document) => [document]),
+  sql: [],
+  durationMs: 1,
+});
+
+/** The table alone, run once on a database of this type; later runs read the sample */
+export const TEST__setUpPayloadRun = async (
+  databaseType = 'DuckDB',
+  sample: CubeResult = TEST__payloadSample(),
+): Promise<{ state: CubeEditorState; fake: FakeCubeEngine }> => {
+  const { host, fake } = TEST__createCubeHost({
+    result: {
+      columns: TEST__PAYLOAD_COLUMNS.map((column) => column.name),
+      rows: [['1', TEST__PAYLOAD_DOCUMENTS[0] ?? null, '2']],
+      sql: [],
+      durationMs: 1,
+    },
+    outline: createFakeNorthwindOutline(databaseType),
+  });
+  const state = new CubeEditorState(
+    host,
+    new CubeDocument({
+      context: { model: CUBE_NORTHWIND_MODEL, runtime: NORTHWIND_RUNTIME },
+      query: new Query(
+        [northwindTable('relational101', 'ORDERS', TEST__PAYLOAD_COLUMNS)],
+        [],
+        'relational101',
+      ),
+    }),
+  );
+  await flowResult(state.execution.execute());
+  expect(state.execution.result).toBeDefined();
+  fake.execute.mockResolvedValue(sample);
+  return { state, fake };
+};

package/src/components/CubeAddItems.tsx

@@ -32,6 +32,7 @@ import {
   OTHER_SOURCE_KIND_TITLE,
   READ_ONLY_CUBE_TITLE,
 } from '../__lib__/LegendCubeLabels.js';
+import { CUBE_TOUR_ANCHOR, cubeTourAnchor } from '../__lib__/LegendCubeTour.js';
 import {
   addCubeNode,
   canAddCubeNode,
@@ -158,6 +159,7 @@ export const CubeAddItemsMenu = observer(
               ? READ_ONLY_CUBE_TITLE
               : 'Add a source, or a step after the selected node'
           }
+          {...cubeTourAnchor(CUBE_TOUR_ANCHOR.ADD_ITEMS)}
           aria-haspopup="menu"
           aria-expanded={isOpen}
           onClick={openMenu}