@lightdash/query-sdk 1.143.0 → 1.144.1

package/dist/LightdashProvider.d.ts

@@ -10,6 +10,9 @@ import { type LightdashClient } from './client';
 import type { Transport } from './types';
 export declare function useTransport(): Transport;
 export declare function useLightdashClient(): LightdashClient | null;
+/** Non-throwing transport lookup for hooks that must keep working without a
+ *  provider (`useVizContext` supports standalone self-subscription). */
+export declare function useOptionalTransport(): Transport | null;
 type LightdashProviderProps = {
     children: ReactNode;
 } & ({

package/dist/LightdashProvider.js

@@ -20,6 +20,12 @@ export function useLightdashClient() {
     const ctx = useContext(LightdashContext);
     return ctx?.client ?? null;
 }
+/** Non-throwing transport lookup for hooks that must keep working without a
+ *  provider (`useVizContext` supports standalone self-subscription). */
+export function useOptionalTransport() {
+    const ctx = useContext(LightdashContext);
+    return ctx?.transport ?? null;
+}
 export function LightdashProvider({ children, ...props }) {
     const client = ('client' in props ? props.client : null) ?? null;
     const transport = client?.transport ??

package/dist/apiTransport.js

@@ -7,6 +7,7 @@
  * 2. Poll GET /api/v2/projects/{projectUuid}/query/{queryUuid}
  *    → returns results when status is 'ready'
  */
+import { VIZ_UNDERLYING_DATA_PATH } from './types';
 // Mirrors the explorer's `useInfiniteQueryResults` polling rhythm so the
 // SDK behaves like a normal Lightdash chart: 500-row pages, exponential
 // backoff starting at 250ms, capped at 1000ms.
@@ -653,5 +654,36 @@ export function createApiTransport(config, adapter) {
             // to resolve. Only the in-iframe postMessage transport supports it.
             throw new Error('externalFetch is only available inside a data app preview');
         },
+        async getVizUnderlyingData(intent) {
+            const execResult = await fetchFn('POST', VIZ_UNDERLYING_DATA_PATH, intent);
+            const { firstReadyPage, apiRows } = await pollQueryRows(fetchFn, config.projectUuid, execResult.queryUuid);
+            const fieldIds = [
+                ...Object.keys(execResult.fields),
+                ...Object.keys(firstReadyPage.columns).filter((fieldId) => !(fieldId in execResult.fields)),
+            ];
+            return {
+                ...mapApiRowsToQueryResult({
+                    apiRows,
+                    columns: firstReadyPage.columns,
+                    fields: execResult.fields,
+                    fieldIds,
+                    fieldNameForId: (fieldId) => fieldId,
+                }),
+                queryUuid: execResult.queryUuid,
+            };
+        },
+        async downloadVizUnderlyingData(intent, options = {}) {
+            const execResult = await fetchFn('POST', VIZ_UNDERLYING_DATA_PATH, {
+                ...intent,
+                limit: getUnderlyingDownloadLimit(options.limit),
+            });
+            await pollQueryReady(fetchFn, config.projectUuid, execResult.queryUuid, 1);
+            return scheduleDownloadForQuery({
+                fetchFn,
+                projectUuid: config.projectUuid,
+                queryUuid: execResult.queryUuid,
+                options,
+            });
+        },
     };
 }

package/dist/features.js

@@ -83,6 +83,12 @@ export const SDK_FEATURES = [
         description: "Scheduled deliveries and their preview render every tab or slide's data, not just the one currently visible.",
         wiring: "Gate tab/slide content so DATA components for all tabs mount when useDeliveryRender() is true — tabs switch what's shown, not what's fetched. Never mount all tabs unconditionally.",
     },
+    {
+        key: 'viz-underlying-data',
+        label: 'View underlying data',
+        description: 'Open the raw result rows behind a clicked data point in a reusable visualization, with CSV/XLSX download.',
+        wiring: 'In the viz, keep the untransformed source row on each interactive datum, show a data-point action menu only when useVizContext().underlyingData.enabled and the mark maps to exactly one source row, render underlyingData.get({ row, metric }) in a themed dialog, and wire its Download button to underlyingData.download.',
+    },
 ];
 export const SDK_FEATURE_KEYS = SDK_FEATURES.map((f) => f.key);
 export const SDK_MANIFEST_MESSAGE_TYPE = 'lightdash:sdk:manifest';

package/dist/generated/sdkVersion.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.143.0";
+export declare const SDK_VERSION = "1.144.1";

package/dist/generated/sdkVersion.js

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

package/dist/index.d.ts

@@ -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, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
+export type { VizContext, VizContextCell, VizContextOptionValue, VizContextRow, VizUnderlyingData, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
 export { useColorScheme } from './colorScheme';
 export type { HostColorScheme, HostColorSchemeMessage, HostColorSchemeRequestMessage, } from './colorScheme';
 export { isDeliveryRender, useDeliveryRender } from './deliveryRender';

package/dist/types.d.ts

@@ -162,6 +162,29 @@ export type UnderlyingDataResult = {
     format: FormatFunction;
     queryUuid: string;
 };
+/**
+ * Bridge-only virtual route for viz underlying-data click intents. Duplicated
+ * from `@lightdash/common` (`APP_SDK_VIZ_UNDERLYING_DATA_PATH`) — this package
+ * must not depend on common. The path only resolves behind the host's
+ * postMessage bridge, which rewrites it into the real underlying-data request;
+ * on a direct-API transport it fails with a plain HTTP error.
+ */
+export declare const VIZ_UNDERLYING_DATA_PATH = "/__sdk/viz/underlying-data";
+/**
+ * Semantic click intent a viz sends to the host: the untransformed source row
+ * (as received from `useVizContext().rows`) and the declared field NAME bound
+ * to the clicked metric slot. The host resolves everything else.
+ */
+export type VizUnderlyingDataIntent = {
+    row: Record<string, {
+        value?: {
+            raw?: unknown;
+            formatted?: string;
+        };
+    } | undefined>;
+    metric: string;
+    limit?: number | null;
+};
 export type LightdashClientConfig = {
     /** Lightdash instance URL */
     baseUrl: string;
@@ -223,4 +246,12 @@ export type Transport = {
     }) => Promise<QueryResult>;
     getUser: () => Promise<LightdashUser>;
     externalFetch: (alias: string, opts: ExternalFetchOptions) => Promise<ExternalFetchResult>;
+    /**
+     * Fetch the raw rows behind a viz data point via the host bridge.
+     * Optional so custom transports predating the capability stay valid —
+     * `useVizContext().underlyingData.enabled` is false when absent.
+     */
+    getVizUnderlyingData?: (intent: VizUnderlyingDataIntent) => Promise<UnderlyingDataResult>;
+    /** Schedule a CSV/XLSX export of the rows behind a viz data point. */
+    downloadVizUnderlyingData?: (intent: Omit<VizUnderlyingDataIntent, 'limit'>, options?: DownloadResultsOptions) => Promise<DownloadResultsResult>;
 };

package/dist/types.js

@@ -1,4 +1,12 @@
 /**
  * Core types for the Lightdash SDK.
  */
-export {};
+// --- Viz underlying data ---
+/**
+ * Bridge-only virtual route for viz underlying-data click intents. Duplicated
+ * from `@lightdash/common` (`APP_SDK_VIZ_UNDERLYING_DATA_PATH`) — this package
+ * must not depend on common. The path only resolves behind the host's
+ * postMessage bridge, which rewrites it into the real underlying-data request;
+ * on a direct-API transport it fails with a plain HTTP error.
+ */
+export const VIZ_UNDERLYING_DATA_PATH = '/__sdk/viz/underlying-data';

package/dist/vizContext.d.ts

@@ -14,6 +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';
 /** A single cell of a Lightdash result row: `{ value: { raw, formatted } }`. */
 export type VizContextCell = {
     value?: {
@@ -45,6 +46,10 @@ export type DataAppVizContextMessage = {
     options?: Record<string, VizContextOptionValue>;
     /** Absent when the installed host predates palette delivery. */
     colorPalette?: string[];
+    /** Absent when the installed host predates underlying-data delivery. */
+    underlyingData?: {
+        enabled?: boolean;
+    };
 };
 /** Posted by the iframe on mount so the host pushes the current context. */
 export type VizContextRequestMessage = {
@@ -54,6 +59,25 @@ export type VizContextRequestMessage = {
 export declare const getFormatted: (row: VizContextRow | undefined, fieldId: string | undefined) => string;
 /** Raw value for a field's cell in a row (number/string/etc.), or null when unset. */
 export declare const getRaw: (row: VizContextRow | undefined, fieldId: string | undefined) => unknown;
+/**
+ * Host-mediated access to the raw rows behind a clicked data point. `enabled`
+ * is false when the host predates the capability, the viewer lacks permission,
+ * or no transport is mounted — render no menu item in that case (never a
+ * disabled one). `row` is the untransformed source row from `rows`; `metric`
+ * is the declared field NAME bound to the clicked metric slot.
+ */
+export type VizUnderlyingData = {
+    enabled: boolean;
+    get: (opts: {
+        row: VizContextRow;
+        metric: string;
+        limit?: number;
+    }) => Promise<UnderlyingDataResult>;
+    download: (opts: {
+        row: VizContextRow;
+        metric: string;
+    } & DownloadResultsOptions) => Promise<DownloadResultsResult>;
+};
 export type VizContext = {
     /** field name → query field id, as bound in the host field mapping UI. */
     fieldMapping: Record<string, string>;
@@ -70,12 +94,15 @@ export type VizContext = {
     colorPalette: string[];
     /** 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. */
+    underlyingData: VizUnderlyingData;
 };
 type VizContextValue = {
     fieldMapping: Record<string, string>;
     rows: VizContextRow[];
     options: Record<string, VizContextOptionValue>;
     colorPalette: string[];
+    underlyingDataEnabled: boolean;
 };
 type VizContextState = VizContextValue | null;
 /**
@@ -85,6 +112,12 @@ type VizContextState = VizContextValue | null;
  * `{}` / `[]`.
  */
 export declare function toVizContextState(message: DataAppVizContextMessage): VizContextValue;
+/**
+ * Builds the `underlyingData` surface from the host's availability flag and
+ * the mounted transport (null when no `LightdashProvider` is present, e.g.
+ * standalone `useVizContext` usage). Exported for tests.
+ */
+export declare function buildVizUnderlyingData(hostEnabled: boolean, transport: Transport | null): VizUnderlyingData;
 declare const NO_PROVIDER: unique symbol;
 /**
  * Owns the single listener + handshake for a data app viz. Mount it in the

package/dist/vizContext.js

@@ -13,7 +13,8 @@
  * request is guaranteed to be sent after any listener the app registered. The
  * host's reply therefore can't be missed. No timers, no races.
  */
-import { createContext, createElement, useContext, useEffect, useState, } from 'react';
+import { createContext, createElement, useContext, useEffect, useMemo, useState, } from 'react';
+import { useOptionalTransport } from './LightdashProvider';
 const DATA_APP_VIZ_CONTEXT_MESSAGE = 'lightdash:sdk:data-app-viz-context';
 const VIZ_CONTEXT_REQUEST_MESSAGE = 'lightdash:sdk:viz-context-request';
 /** Display string for a field's cell in a row, e.g. `"$1,234"`. Empty when unset. */
@@ -53,6 +54,40 @@ export function toVizContextState(message) {
         colorPalette: Array.isArray(message.colorPalette)
             ? message.colorPalette.filter((color) => typeof color === 'string')
             : [],
+        // Strict boolean check — non-boolean payloads read as disabled.
+        underlyingDataEnabled: message.underlyingData?.enabled === true,
+    };
+}
+/**
+ * Builds the `underlyingData` surface from the host's availability flag and
+ * the mounted transport (null when no `LightdashProvider` is present, e.g.
+ * standalone `useVizContext` usage). Exported for tests.
+ */
+export function buildVizUnderlyingData(hostEnabled, transport) {
+    // Atomic capability: the generated menu promises Download whenever
+    // `enabled` is true, so a transport must implement both methods.
+    const supported = typeof transport?.getVizUnderlyingData === 'function' &&
+        typeof transport?.downloadVizUnderlyingData === 'function';
+    return {
+        enabled: hostEnabled && supported,
+        get: async ({ row, metric, limit }) => {
+            if (!hostEnabled) {
+                throw new Error('Underlying data is not enabled for this visualization.');
+            }
+            if (!transport?.getVizUnderlyingData) {
+                throw new Error('This SDK build predates underlying data. Rebuild the app on the current template.');
+            }
+            return transport.getVizUnderlyingData({ row, metric, limit });
+        },
+        download: async ({ row, metric, ...options }) => {
+            if (!hostEnabled) {
+                throw new Error('Underlying data is not enabled for this visualization.');
+            }
+            if (!transport?.downloadVizUnderlyingData) {
+                throw new Error('This SDK build predates underlying data. Rebuild the app on the current template.');
+            }
+            return transport.downloadVizUnderlyingData({ row, metric }, options);
+        },
     };
 }
 // Distinguishes "no provider mounted" from "provider present, no context yet".
@@ -113,11 +148,17 @@ export function useVizContext() {
     const context = hasProvider
         ? fromProvider
         : selfSubscribed;
+    // Null-returning lookup — standalone usage without LightdashProvider keeps
+    // working, with underlying data reported as unavailable.
+    const transport = useOptionalTransport();
+    const hostEnabled = context?.underlyingDataEnabled === true;
+    const underlyingData = useMemo(() => buildVizUnderlyingData(hostEnabled, transport), [hostEnabled, transport]);
     return {
         fieldMapping: context?.fieldMapping ?? {},
         rows: context?.rows ?? [],
         options: context?.options ?? {},
         colorPalette: context?.colorPalette ?? [],
         ready: context !== null,
+        underlyingData,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "1.143.0",
+  "version": "1.144.1",
   "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.143.0"
+    "@lightdash/common": "1.144.1"
   },
   "scripts": {
     "prebuild": "node ./scripts/generateSdkVersion.mjs",