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

package/src/__test-utils__/CubeNorthwindTestQueries.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 {
+  ColumnComparisonFilter,
+  CompositeFilter,
+  CompositeFilterOperator,
+  Connection,
+  Filter,
+  FilterOperator,
+  type FilterRule,
+  Join,
+  JoinType,
+  PrimitiveType,
+  Query,
+  RelationalTableSource,
+  Schema,
+  SchemaColumn,
+} from '@finos/legend-cube';
+
+// Cube queries over Northwind, typed as the engine types the Cube fixture
+// (PLAN §8.5), for the serializer's and the engine's tests
+
+export const NORTHWIND_DATABASE =
+  'showcase::northwind::store::NorthwindDatabase';
+export const NORTHWIND_RUNTIME = 'showcase::northwind::mapping::StoreRuntime';
+
+const P = 'meta::pure::precisePrimitives::';
+
+const column = (
+  name: string,
+  path: string,
+  nullable = true,
+  params: number[] = [],
+): SchemaColumn =>
+  new SchemaColumn(name, PrimitiveType.get(path, params), nullable);
+const varchar = (name: string, length: number, nullable = true): SchemaColumn =>
+  column(name, `${P}Varchar`, nullable, [length]);
+const smallInt = (name: string, nullable = true): SchemaColumn =>
+  column(name, `${P}SmallInt`, nullable);
+const date = (name: string): SchemaColumn => column(name, 'StrictDate');
+
+export const ORDERS_COLUMNS = [
+  smallInt('ORDER_ID', false),
+  varchar('CUSTOMER_ID', 5),
+  smallInt('EMPLOYEE_ID'),
+  date('ORDER_DATE'),
+  date('REQUIRED_DATE'),
+  date('SHIPPED_DATE'),
+  smallInt('SHIP_VIA'),
+  column('FREIGHT', `${P}Double`),
+  varchar('SHIP_NAME', 40),
+  varchar('SHIP_ADDRESS', 60),
+  varchar('SHIP_CITY', 15),
+  varchar('SHIP_REGION', 15),
+  varchar('SHIP_POSTAL_CODE', 10),
+  varchar('SHIP_COUNTRY', 15),
+];
+
+export const CUSTOMERS_COLUMNS = [
+  varchar('CUSTOMER_ID', 5, false),
+  varchar('COMPANY_NAME', 40, false),
+  varchar('CONTACT_NAME', 30),
+  varchar('CONTACT_TITLE', 30),
+  varchar('ADDRESS', 60),
+  varchar('CITY', 15),
+  varchar('REGION', 15),
+  varchar('POSTAL_CODE', 10),
+  varchar('COUNTRY', 15),
+  varchar('PHONE', 24),
+  varchar('FAX', 24),
+];
+
+export const northwindTable = (
+  id: string,
+  name: string,
+  columns: SchemaColumn[],
+): RelationalTableSource =>
+  new RelationalTableSource(
+    id,
+    { database: NORTHWIND_DATABASE, schema: 'NORTHWIND', table: name },
+    { kind: 'resolved', schema: new Schema(columns) },
+  );
+
+/** France since 1997, by employees 1 and 4 (PLAN §8.5) */
+export const SLICE_FILTER: FilterRule = new CompositeFilter(
+  CompositeFilterOperator.AND,
+  [
+    new ColumnComparisonFilter('SHIP_COUNTRY', FilterOperator.EQUAL, {
+      kind: 'string',
+      value: 'France',
+    }),
+    new ColumnComparisonFilter(
+      'ORDER_DATE',
+      FilterOperator.GREATER_THAN_OR_EQUAL,
+      { kind: 'strictDate', value: '1997-01-01' },
+    ),
+    new ColumnComparisonFilter('EMPLOYEE_ID', FilterOperator.IN, [
+      { kind: 'integer', value: '1' },
+      { kind: 'integer', value: '4' },
+    ]),
+  ],
+);
+
+/** The slice (PLAN §8.5): ORDERS ⋈ CUSTOMERS on CUSTOMER_ID, then the filter, captured at the filter */
+export const sliceQuery = (
+  filter: FilterRule = SLICE_FILTER,
+  joinType = JoinType.INNER,
+): Query =>
+  new Query(
+    [
+      northwindTable('relational101', 'ORDERS', ORDERS_COLUMNS),
+      northwindTable('relational102', 'CUSTOMERS', CUSTOMERS_COLUMNS),
+      new Join('join101', {
+        leftColumns: ['CUSTOMER_ID'],
+        rightColumns: ['CUSTOMER_ID'],
+        joinType,
+      }),
+      new Filter('filter101', filter),
+    ],
+    [
+      new Connection('relational101', 'join101', 'leftTds'),
+      new Connection('relational102', 'join101', 'rightTds'),
+      new Connection('join101', 'filter101', 'tds'),
+    ],
+    'filter101',
+  );
+
+/**
+ * ORDERS ⟗ a CUSTOMERS-like table on CUSTOMER_ID, nullable on both sides with
+ * different lengths (so `toOne()`, a merge and a cast), captured at the join
+ */
+export const fullJoinQuery = (): Query =>
+  new Query(
+    [
+      northwindTable('relational101', 'ORDERS', ORDERS_COLUMNS),
+      northwindTable('relational102', 'CUSTOMERS', [
+        varchar('CUSTOMER_ID', 40),
+        varchar('COMPANY_NAME', 40),
+      ]),
+      new Join('join101', {
+        leftColumns: ['CUSTOMER_ID'],
+        rightColumns: ['CUSTOMER_ID'],
+        joinType: JoinType.FULL_OUTER,
+      }),
+    ],
+    [
+      new Connection('relational101', 'join101', 'leftTds'),
+      new Connection('relational102', 'join101', 'rightTds'),
+    ],
+    'join101',
+  );

package/src/__test-utils__/CubeOperationsTestUtils.ts

@@ -0,0 +1,177 @@
+/**
+ * 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 {
+  buildSchemasAndValidity,
+  Connection,
+  createNodeRegistry,
+  Query,
+  type QueryNode,
+  QueryEmitter,
+  RelationalTableSource,
+  Schema,
+} from '@finos/legend-cube';
+import type {
+  CubeEngine,
+  CubeResult,
+  CubeResultValue,
+} from '../graph-manager/CubeEngine.js';
+import {
+  CUBE_NORTHWIND_DATABASE,
+  CUBE_NORTHWIND_MODEL,
+  CUBE_NORTHWIND_RUNTIME,
+} from '../stores/fixtures/CubeNorthwindModel.js';
+
+// Helpers for engine tests of operations on the Cube Northwind fixture,
+// through the engine port only (no V1 classes), so any CubeEngine works
+
+/** A table of the Cube Northwind model, not resolved yet */
+export const TEST__northwindTable = (
+  id: string,
+  table: string,
+  schema = 'NORTHWIND',
+): RelationalTableSource =>
+  new RelationalTableSource(id, {
+    database: CUBE_NORTHWIND_DATABASE,
+    schema,
+    table,
+  });
+
+/** The sources, resolved through the engine as the editor resolves them */
+export const TEST__resolveSources = async (
+  engine: CubeEngine,
+  sources: readonly RelationalTableSource[],
+): Promise<RelationalTableSource[]> => {
+  const typed = await engine.resolveSchemas(
+    CUBE_NORTHWIND_MODEL,
+    new Map(
+      sources.map((source) => [
+        source.id,
+        [source.database, source.schema, source.table] as const,
+      ]),
+    ),
+  );
+  return sources.map((source) => {
+    const schema = typed.get(source.id);
+    if (!(schema instanceof Schema)) {
+      throw schema ?? new Error(`No schema for ${source.id}`);
+    }
+    return source.withResolution({ kind: 'resolved', schema });
+  });
+};
+
+/** A chain of nodes, each feeding the next on its first port, captured at the last */
+export const TEST__chainOf = (nodes: readonly QueryNode[]): Query =>
+  new Query(
+    nodes,
+    nodes
+      .slice(1)
+      .map(
+        (node, index) =>
+          new Connection(
+            (nodes[index] as QueryNode).id,
+            node.id,
+            node.ports[0] as string,
+          ),
+      ),
+    nodes.at(-1)?.id,
+  );
+
+/** Every node of the query is valid */
+export const TEST__expectValidQuery = (query: Query): void => {
+  const { validity } = buildSchemasAndValidity(
+    query,
+    createNodeRegistry().queryRules,
+  );
+  expect([...validity].filter(([, errors]) => errors.length)).toEqual([]);
+};
+
+/**
+ * Runs the query up to its capture node, with this row limit; with a database
+ * type, written as for that database (on the fixture's H2 all the same, so a
+ * workaround's rows can be checked)
+ */
+export const TEST__runQuery = async (
+  engine: CubeEngine,
+  query: Query,
+  rowLimit: number,
+  databaseType?: string,
+): Promise<CubeResult> => {
+  TEST__expectValidQuery(query);
+  return engine.execute(
+    CUBE_NORTHWIND_MODEL,
+    new QueryEmitter(query).emitExecutionLambda({
+      rowLimit,
+      runtime: CUBE_NORTHWIND_RUNTIME,
+      databaseType,
+    }),
+  );
+};
+
+/** The values of one column of a result */
+export const TEST__columnValues = (
+  result: CubeResult,
+  column: string,
+): CubeResultValue[] => {
+  const index = result.columns.indexOf(column);
+  expect(index).toBeGreaterThanOrEqual(0);
+  return result.rows.map((row) => row[index] ?? null);
+};
+
+/** The schema Cube infers for a node of the query, its capture node by default */
+export const TEST__inferredSchema = (
+  query: Query,
+  nodeId = query.selected ?? '',
+): Schema => {
+  const schema = buildSchemasAndValidity(
+    query,
+    createNodeRegistry().queryRules,
+  ).schemas.get(nodeId);
+  expect(schema).toBeDefined();
+  return schema as Schema;
+};
+
+/**
+ * The engine types the node as Cube infers it: the same names, in the same
+ * order, of the same types and parameters. Cube's nullability may only be
+ * wider, since the engine misreports it after outer joins (PLAN §4.7).
+ */
+export const TEST__expectEngineTyping = async (
+  engine: CubeEngine,
+  query: Query,
+  nodeId = query.selected ?? '',
+): Promise<void> => {
+  const cube = TEST__inferredSchema(query, nodeId);
+  const typed = (
+    await engine.typeLambdas(
+      CUBE_NORTHWIND_MODEL,
+      new Map([[nodeId, new QueryEmitter(query).emitTypingLambda(nodeId)]]),
+    )
+  ).get(nodeId);
+  expect(typed).toBeInstanceOf(Schema);
+  const engineSchema = typed as Schema;
+  expect(
+    cube.columns.map((column) => [column.name, column.type.fullName]),
+  ).toEqual(
+    engineSchema.columns.map((column) => [column.name, column.type.fullName]),
+  );
+  cube.columns.forEach((column, index) => {
+    if (engineSchema.columns[index]?.nullable) {
+      expect([column.name, column.nullable]).toEqual([column.name, true]);
+    }
+  });
+};

package/src/__test-utils__/CubePageTestUtils.tsx

@@ -0,0 +1,96 @@
+/**
+ * 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 {
+  ApplicationFrameworkProvider,
+  ApplicationStoreProvider,
+  type GenericLegendApplicationStore,
+} from '@finos/legend-application';
+import { TEST__BrowserEnvironmentProvider } from '@finos/legend-application/test';
+import type { CubeDocument } from '@finos/legend-cube';
+import {
+  act,
+  type RenderResult,
+  render,
+  waitFor,
+} from '@testing-library/react';
+import type { CubeEditorState } from '../stores/CubeEditorState.js';
+
+/** React Flow watches the canvas with an IntersectionObserver, which jsdom lacks */
+class TEST__IntersectionObserver {
+  observe(): void {
+    // nothing is ever in view under jsdom
+  }
+  unobserve(): void {
+    // nothing to stop watching
+  }
+  disconnect(): void {
+    // nothing to stop watching
+  }
+  takeRecords(): IntersectionObserverEntry[] {
+    return [];
+  }
+}
+
+/** Lets the canvas mount under jsdom; call before rendering it */
+export const TEST__installCanvasDomStubs = (): void => {
+  if (!('IntersectionObserver' in window)) {
+    Object.defineProperty(window, 'IntersectionObserver', {
+      configurable: true,
+      writable: true,
+      value: TEST__IntersectionObserver,
+    });
+  }
+};
+
+/**
+ * Renders an element inside a Legend application, as a host would, and waits
+ * for the element with the given test id: the framework renders nothing until
+ * the application store has initialized
+ */
+export const TEST__renderInCubeApplication = async (
+  element: React.ReactNode,
+  applicationStore: GenericLegendApplicationStore,
+  readyTestId: string,
+): Promise<RenderResult> => {
+  TEST__installCanvasDomStubs();
+  const renderResult = render(
+    <ApplicationStoreProvider store={applicationStore}>
+      <TEST__BrowserEnvironmentProvider initialEntries={['/']}>
+        <ApplicationFrameworkProvider>{element}</ApplicationFrameworkProvider>
+      </TEST__BrowserEnvironmentProvider>
+    </ApplicationStoreProvider>,
+  );
+  await waitFor(() => renderResult.getByTestId(readyTestId));
+  return renderResult;
+};
+
+/**
+ * Imports a cube into a rendered page, as Import does, and waits for its
+ * tables to be typed again, so nothing changes after the test has ended
+ */
+export const TEST__importDocument = async (
+  editorState: CubeEditorState,
+  document: CubeDocument,
+  readOnly = false,
+): Promise<void> => {
+  act(() => editorState.importDocument(document, readOnly));
+  await waitFor(() => {
+    if (editorState.isResolvingSources) {
+      throw new Error('The imported tables are still being typed');
+    }
+  });
+};

package/src/__test-utils__/CubeTestApplication.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 {
+  ApplicationStore,
+  type GenericLegendApplicationStore,
+  LegendApplicationConfig,
+  type LegendApplicationPlugin,
+  LegendApplicationPluginManager,
+} from '@finos/legend-application';
+import { TEST__getApplicationVersionData } from '@finos/legend-application/test';
+import type { CubeHost } from '../stores/CubeHost.js';
+import { LocalModelCatalog } from '../stores/LocalModelCatalog.js';
+import {
+  createFakeCubeEngine,
+  type FakeCubeEngine,
+  type FakeCubeEngineAnswers,
+} from './FakeCubeEngine.js';
+
+// A bare Legend application for Cube's jsdom tests, as the data-space viewer's
+// tests build theirs: the builder may not use the query builder's test helpers
+
+export class TEST__LegendCubePluginManager extends LegendApplicationPluginManager<LegendApplicationPlugin> {
+  private constructor() {
+    super();
+  }
+
+  static create(): TEST__LegendCubePluginManager {
+    return new TEST__LegendCubePluginManager();
+  }
+}
+
+class TEST__LegendCubeApplicationConfig extends LegendApplicationConfig {
+  override getDefaultApplicationStorageKey(): string {
+    return 'test';
+  }
+}
+
+/** A fresh application store: build one per test, since it initializes once */
+export const TEST__createCubeApplicationStore = (
+  plugins: LegendApplicationPlugin[] = [],
+): GenericLegendApplicationStore => {
+  const pluginManager = TEST__LegendCubePluginManager.create();
+  pluginManager.usePlugins(plugins).install();
+  return new ApplicationStore(
+    new TEST__LegendCubeApplicationConfig({
+      configData: { env: 'TEST', appName: 'TEST' },
+      versionData: TEST__getApplicationVersionData(),
+      baseAddress: '/',
+    }),
+    pluginManager,
+  );
+};
+
+/** A host over a fake engine, with the bundled models */
+export const TEST__createCubeHost = (
+  answers?: FakeCubeEngineAnswers,
+  applicationStore = TEST__createCubeApplicationStore(),
+): { host: CubeHost; fake: FakeCubeEngine } => {
+  const fake = createFakeCubeEngine(answers);
+  return {
+    host: {
+      applicationStore,
+      engine: fake.engine,
+      modelCatalog: new LocalModelCatalog(fake.engine),
+    },
+    fake,
+  };
+};

package/src/__test-utils__/FakeCubeEngine.ts

@@ -0,0 +1,145 @@
+/**
+ * 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 { jest } from '@jest/globals';
+import { Schema } from '@finos/legend-cube';
+import {
+  type CubeEngine,
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeModelOutline,
+  type CubeResult,
+} from '../graph-manager/CubeEngine.js';
+import {
+  CUSTOMERS_COLUMNS,
+  NORTHWIND_DATABASE,
+  NORTHWIND_RUNTIME,
+  ORDERS_COLUMNS,
+} from './CubeNorthwindTestQueries.js';
+
+// A CubeEngine for jsdom tests (PLAN §11.1 M1.8a): canned answers, no network.
+// Each method is a jest.fn, kept in its own variable so tests can read its
+// calls or change its answer.
+
+/** Northwind as the fake knows it: two tables, one runtime keyed by the database */
+export const FAKE_NORTHWIND_OUTLINE: CubeModelOutline = {
+  databases: [
+    {
+      path: NORTHWIND_DATABASE,
+      schemas: [
+        {
+          name: 'NORTHWIND',
+          tables: [
+            {
+              name: 'ORDERS',
+              isView: false,
+              columnCount: ORDERS_COLUMNS.length,
+              flags: [],
+              untypedColumns: [],
+            },
+            {
+              name: 'CUSTOMERS',
+              isView: false,
+              columnCount: CUSTOMERS_COLUMNS.length,
+              flags: [],
+              untypedColumns: [],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  runtimes: [
+    {
+      path: NORTHWIND_RUNTIME,
+      storePaths: [NORTHWIND_DATABASE],
+      connections: [{ storePath: NORTHWIND_DATABASE, databaseType: 'H2' }],
+    },
+  ],
+};
+
+/** The schemas the fake gives, keyed by `<schema>.<table>` as the outline names them */
+export const FAKE_NORTHWIND_SCHEMAS: ReadonlyMap<string, Schema> = new Map([
+  ['NORTHWIND.ORDERS', new Schema(ORDERS_COLUMNS)],
+  ['NORTHWIND.CUSTOMERS', new Schema(CUSTOMERS_COLUMNS)],
+]);
+
+export const EMPTY_CUBE_RESULT: CubeResult = {
+  columns: [],
+  rows: [],
+  sql: [],
+  durationMs: 0,
+};
+
+export interface FakeCubeEngineAnswers {
+  readonly outline?: CubeModelOutline;
+  /** keyed by `<schema>.<table>`; a table not in it gets a compile error */
+  readonly schemas?: ReadonlyMap<string, Schema>;
+  readonly result?: CubeResult;
+  readonly pure?: string;
+}
+
+export interface FakeCubeEngine {
+  readonly engine: CubeEngine;
+  readonly loadModel: jest.Mock<CubeEngine['loadModel']>;
+  readonly resolveSchemas: jest.Mock<CubeEngine['resolveSchemas']>;
+  readonly typeLambdas: jest.Mock<CubeEngine['typeLambdas']>;
+  readonly execute: jest.Mock<CubeEngine['execute']>;
+  readonly renderPure: jest.Mock<CubeEngine['renderPure']>;
+}
+
+/** A fresh fake: build one per test, since jest.fn keeps its calls across tests */
+export const createFakeCubeEngine = (
+  answers: FakeCubeEngineAnswers = {},
+): FakeCubeEngine => {
+  const schemas = answers.schemas ?? FAKE_NORTHWIND_SCHEMAS;
+  const loadModel = jest.fn<CubeEngine['loadModel']>(async () =>
+    Promise.resolve(answers.outline ?? FAKE_NORTHWIND_OUTLINE),
+  );
+  const resolveSchemas = jest.fn<CubeEngine['resolveSchemas']>(
+    async (_model, accessors) =>
+      Promise.resolve(
+        new Map(
+          [...accessors].map(([nodeId, [, schema, table]]) => [
+            nodeId,
+            schemas.get(`${schema}.${table}`) ??
+              new CubeEngineError(
+                CubeEngineErrorKind.COMPILE,
+                `The table "${schema}.${table}" can't be found`,
+                nodeId,
+              ),
+          ]),
+        ),
+      ),
+  );
+  const typeLambdas = jest.fn<CubeEngine['typeLambdas']>(async () =>
+    Promise.resolve(new Map()),
+  );
+  const execute = jest.fn<CubeEngine['execute']>(async () =>
+    Promise.resolve(answers.result ?? EMPTY_CUBE_RESULT),
+  );
+  const renderPure = jest.fn<CubeEngine['renderPure']>(async () =>
+    Promise.resolve(answers.pure ?? ''),
+  );
+  return {
+    engine: { loadModel, resolveSchemas, typeLambdas, execute, renderPure },
+    loadModel,
+    resolveSchemas,
+    typeLambdas,
+    execute,
+    renderPure,
+  };
+};

package/src/components/CubeButton.tsx

@@ -0,0 +1,35 @@
+/**
+ * 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 { clsx } from '@finos/legend-art';
+
+/** A small text button in the page's toolbars and lists, coloured by the theme's tokens */
+export const CubeButton: React.FC<
+  React.ButtonHTMLAttributes<HTMLButtonElement> & { primary?: boolean }
+> = ({ className, primary, ...props }) => (
+  <button
+    {...props}
+    // these buttons never submit a form
+    type="button"
+    className={clsx(
+      'h-6 shrink-0 rounded-sm border px-2 text-base enabled:cursor-pointer disabled:cursor-not-allowed disabled:text-[var(--color-text-disabled)]',
+      primary
+        ? 'border-[var(--color-accent)] bg-[var(--color-accent)] text-[var(--color-text-on-accent)] enabled:hover:bg-[var(--color-accent-hover)] disabled:border-[var(--color-border-default)] disabled:bg-[var(--color-bg-panel-header)]'
+        : 'border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] text-[var(--color-text-primary)] enabled:hover:bg-[var(--color-bg-hover)]',
+      className,
+    )}
+  />
+);