@lightdash/query-sdk 1.202.0 → 1.202.2

package/dist/features.js

@@ -71,6 +71,12 @@ export const SDK_FEATURES = [
         description: "Let viewers adjust the visualization from the Lightdash config panel — toggles, dropdowns, numbers, text and colours — and take series colours from the chart's palette, without regenerating the app.",
         wiring: 'Declare configOptions (and colorPalette, if the viz colours series) in the viz schema, then read options[name] and colorPalette from useVizContext().',
     },
+    {
+        key: 'viz-pivoted-results',
+        label: 'Pivoted results',
+        description: 'Render reusable charts and tables from backend-pivoted rows and their complete layout metadata.',
+        wiring: 'When useVizContext().pivotDetails is non-null, use valuesColumns to resolve generated row keys and use indexColumn, groupByColumns, originalColumns, sortBy, totalColumnCount, and passthroughDimensions when the visualization needs their layout semantics. Keep the existing fieldMapping path when pivotDetails is null.',
+    },
     {
         key: 'follow-host-theme',
         label: 'Follow the host light/dark mode',

package/dist/generated/sdkVersion.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.202.0";
+export declare const SDK_VERSION = "1.202.2";

package/dist/generated/sdkVersion.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generateSdkVersion.mjs (prebuild) — do not edit.
-export const SDK_VERSION = '1.202.0';
+export const SDK_VERSION = '1.202.2';

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { LightdashProvider, useLightdashClient } from './LightdashProvider';
 export { createApiTransport, type FetchAdapter } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
 export { SDK_FEATURES, SDK_FEATURE_KEYS, SDK_MANIFEST_MESSAGE_TYPE, type SdkFeature, type SdkManifestMessage, } from './features';
-export type { AdditionalMetric, Column, CustomDimension, DownloadResultsFileType, DownloadResultsLimit, DownloadResultsOptions, DownloadResultsResult, DownloadResultsValues, DownloadUnderlyingDataOptions, ExternalFetchMethod, ExternalFetchOptions, ExternalFetchResult, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, MetricType, QueryDefinition, QueryResult, Row, Sort, TableCalculation, Transport, UnitOfTime, UnderlyingDataOptions, UnderlyingDataResult, } from './types';
+export type { AdditionalMetric, Column, ColumnType, CustomDimension, DownloadResultsFileType, DownloadResultsLimit, DownloadResultsOptions, DownloadResultsResult, DownloadResultsValues, DownloadUnderlyingDataOptions, ExternalFetchMethod, ExternalFetchOptions, ExternalFetchResult, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, MetricType, QueryDefinition, QueryResult, Row, Sort, TableCalculation, Transport, UnitOfTime, UnderlyingDataOptions, UnderlyingDataResult, } from './types';
 export type { SdkExternalFetchRequest, SdkExternalFetchResponse, SdkFetchRequest, SdkFetchResponse, SdkReadyMessage, SdkScreenshotAvailableMessage, SdkScreenshotRequest, SdkScreenshotResponse, SdkGsheetExportRequest, SdkGsheetExportResponse, SdkGsheetExportColumn, SdkGsheetExportColumnType, SdkGsheetExportRow, } from './postMessageTransport';
 export type { InspectAvailableMessage, InspectSelectedMessage, } from './inspector';
 export { useDelivery } from './delivery';
@@ -15,7 +15,7 @@ export type { DeliveryQuery } from './delivery';
 export { exportToSheets } from './exportToSheets';
 export type { ExportToSheetsOptions, ExportToSheetsResult, } from './exportToSheets';
 export { VizContextProvider, useVizContext, getFormatted, getRaw, } from './vizContext';
-export type { VizContext, VizContextCell, VizContextOptionValue, VizContextRow, VizUnderlyingData, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
+export type { VizContext, VizContextCell, VizContextOptionValue, VizContextPivotDetails, VizContextRow, VizUnderlyingData, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
 export { useColorScheme } from './colorScheme';
 export type { HostColorScheme, HostColorSchemeMessage, HostColorSchemeRequestMessage, } from './colorScheme';
 export { isDeliveryRender, useDeliveryRender } from './deliveryRender';

package/dist/vizContext.d.ts

@@ -14,7 +14,7 @@
  * host's reply therefore can't be missed. No timers, no races.
  */
 import { type ReactNode } from 'react';
-import type { DownloadResultsOptions, DownloadResultsResult, Transport, UnderlyingDataResult } from './types';
+import type { ColumnType, DownloadResultsOptions, DownloadResultsResult, Transport, UnderlyingDataResult } from './types';
 /** A single cell of a Lightdash result row: `{ value: { raw, formatted } }`. */
 export type VizContextCell = {
     value?: {
@@ -30,6 +30,51 @@ export type VizContextRow = Record<string, VizContextCell | undefined>;
  * Series colours are not an option — they arrive on `colorPalette`.
  */
 export type VizContextOptionValue = boolean | number | string;
+/**
+ * The host's complete backend-pivot layout metadata. This is a structural
+ * mirror because query-sdk is published without a dependency on
+ * `@lightdash/common`.
+ */
+export type VizContextPivotDetails = {
+    totalColumnCount: number | null;
+    indexColumn: {
+        reference: string;
+        type: 'time' | 'category';
+    } | {
+        reference: string;
+        type: 'time' | 'category';
+    }[] | undefined;
+    valuesColumns: {
+        referenceField: string;
+        pivotColumnName: string;
+        aggregation: string;
+        pivotValues: {
+            referenceField: string;
+            value: unknown;
+            formatted?: string;
+        }[];
+        columnIndex?: number;
+    }[];
+    groupByColumns: {
+        reference: string;
+    }[] | undefined;
+    sortBy: {
+        reference: string;
+        direction: 'ASC' | 'DESC';
+        nullsFirst?: boolean;
+        pivotValues?: {
+            reference: string;
+            value: string | number | boolean | null;
+        }[];
+    }[] | undefined;
+    originalColumns: Record<string, {
+        reference: string;
+        type: ColumnType;
+    }>;
+    passthroughDimensions?: {
+        reference: string;
+    }[];
+};
 /**
  * Pushed by the host into the iframe. `fieldMapping` maps each field name the
  * renderer declared to the query field id it resolves to; `rows` are the
@@ -46,6 +91,8 @@ export type DataAppVizContextMessage = {
     options?: Record<string, VizContextOptionValue>;
     /** Absent when the installed host predates palette delivery. */
     colorPalette?: string[];
+    /** Null for unpivoted rows; absent when the installed host predates pivot metadata delivery. */
+    pivotDetails?: VizContextPivotDetails | null;
     /** Absent when the installed host predates underlying-data delivery. */
     underlyingData?: {
         enabled?: boolean;
@@ -92,6 +139,8 @@ export type VizContext = {
      * resolved no palette; keep a fallback array in your own code for that.
      */
     colorPalette: string[];
+    /** Metadata that maps generated pivot column names back to their metric and series values. */
+    pivotDetails: VizContextPivotDetails | null;
     /** False until the first context arrives — render a placeholder while false. */
     ready: boolean;
     /** Fetch/export the raw rows behind a clicked data point via the host. */
@@ -102,14 +151,13 @@ type VizContextValue = {
     rows: VizContextRow[];
     options: Record<string, VizContextOptionValue>;
     colorPalette: string[];
+    pivotDetails: VizContextPivotDetails | null;
     underlyingDataEnabled: boolean;
 };
 type VizContextState = VizContextValue | null;
 /**
- * Normalises an inbound host message into provider state. The payload crosses a
- * postMessage boundary so every key is treated as untrusted; `options` and
- * `colorPalette` are also absent from hosts predating them, and fall back to
- * `{}` / `[]`.
+ * Normalises an inbound host message into provider state. Optional capabilities
+ * are absent from hosts predating them and receive stable fallback values.
  */
 export declare function toVizContextState(message: DataAppVizContextMessage): VizContextValue;
 /**

package/dist/vizContext.js

@@ -41,10 +41,8 @@ const normalizeOptions = (options) => {
     return Object.fromEntries(Object.entries(options).filter((entry) => isVizContextOptionValue(entry[1])));
 };
 /**
- * Normalises an inbound host message into provider state. The payload crosses a
- * postMessage boundary so every key is treated as untrusted; `options` and
- * `colorPalette` are also absent from hosts predating them, and fall back to
- * `{}` / `[]`.
+ * Normalises an inbound host message into provider state. Optional capabilities
+ * are absent from hosts predating them and receive stable fallback values.
  */
 export function toVizContextState(message) {
     return {
@@ -54,6 +52,7 @@ export function toVizContextState(message) {
         colorPalette: Array.isArray(message.colorPalette)
             ? message.colorPalette.filter((color) => typeof color === 'string')
             : [],
+        pivotDetails: message.pivotDetails ?? null,
         // Strict boolean check — non-boolean payloads read as disabled.
         underlyingDataEnabled: message.underlyingData?.enabled === true,
     };
@@ -158,6 +157,7 @@ export function useVizContext() {
         rows: context?.rows ?? [],
         options: context?.options ?? {},
         colorPalette: context?.colorPalette ?? [],
+        pivotDetails: context?.pivotDetails ?? null,
         ready: context !== null,
         underlyingData,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "1.202.0",
+  "version": "1.202.2",
   "private": false,
   "type": "module",
   "description": "SDK for building custom data apps against the Lightdash semantic layer",
@@ -34,7 +34,7 @@
     "jsdom": "26.1.0",
     "typescript": "7.0.2",
     "vitest": "4.1.6",
-    "@lightdash/common": "1.202.0"
+    "@lightdash/common": "1.202.2"
   },
   "scripts": {
     "prebuild": "node ./scripts/generateSdkVersion.mjs",