@lightdash/query-sdk 1.248.1 → 1.249.0

package/dist/apiTransport.js

@@ -7,7 +7,7 @@
  * 2. Poll GET /api/v2/projects/{projectUuid}/query/{queryUuid}
  *    → returns results when status is 'ready'
  */
-import { VIZ_UNDERLYING_DATA_PATH } from './types';
+import { VIZ_DRILL_DOWN_PATH, 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.
@@ -685,5 +685,8 @@ export function createApiTransport(config, adapter) {
                 options,
             });
         },
+        async openVizDrillDown(intent) {
+            await fetchFn('POST', VIZ_DRILL_DOWN_PATH, intent);
+        },
     };
 }

package/dist/features.js

@@ -95,6 +95,12 @@ export const SDK_FEATURES = [
         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.',
     },
+    {
+        key: 'viz-drill-down',
+        label: 'Drill into data points',
+        description: 'Drill into a clicked data point in a reusable visualization — pick a dimension in Lightdash and open the drilled view in explore.',
+        wiring: 'Show a "Drill into …" item in the data-point action menu only when useVizContext().drillDown.enabled and the mark maps to exactly one source row, and call drillDown.open({ row: datum.sourceRow, metric: "<field name>" }) on selection. The host opens its drill dialog — render no dialog in the viz and never render a disabled item.',
+    },
 ];
 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.248.1";
+export declare const SDK_VERSION = "1.249.0";

package/dist/generated/sdkVersion.js

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

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, VizContextPivotDetails, VizContextRow, VizUnderlyingData, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
+export type { VizContext, VizContextCell, VizContextOptionValue, VizContextPivotDetails, VizContextRow, VizUnderlyingData, VizDrillDown, 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

@@ -185,6 +185,29 @@ export type VizUnderlyingDataIntent = {
     metric: string;
     limit?: number | null;
 };
+/**
+ * Bridge-only virtual route for viz drill-down click intents. Duplicated from
+ * `@lightdash/common` (`APP_SDK_VIZ_DRILL_DOWN_PATH`) — this package must not
+ * depend on common. The host answers it directly (opens its drill dialog);
+ * nothing is forwarded to the API. On a direct-API transport it fails with a
+ * plain HTTP error.
+ */
+export declare const VIZ_DRILL_DOWN_PATH = "/__sdk/viz/drill-down";
+/**
+ * Drill 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 and owns all
+ * subsequent UI.
+ */
+export type VizDrillDownIntent = {
+    row: Record<string, {
+        value?: {
+            raw?: unknown;
+            formatted?: string;
+        };
+    } | undefined>;
+    metric: string;
+};
 export type LightdashClientConfig = {
     /** Lightdash instance URL */
     baseUrl: string;
@@ -254,4 +277,11 @@ export type Transport = {
     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>;
+    /**
+     * Fire the drill-down intent for a viz data point via the host bridge.
+     * One-way: the host opens its drill dialog; the resolved promise is only
+     * an ack. Optional so custom transports predating the capability stay
+     * valid — `useVizContext().drillDown.enabled` is false when absent.
+     */
+    openVizDrillDown?: (intent: VizDrillDownIntent) => Promise<void>;
 };

package/dist/types.js

@@ -10,3 +10,11 @@
  * on a direct-API transport it fails with a plain HTTP error.
  */
 export const VIZ_UNDERLYING_DATA_PATH = '/__sdk/viz/underlying-data';
+/**
+ * Bridge-only virtual route for viz drill-down click intents. Duplicated from
+ * `@lightdash/common` (`APP_SDK_VIZ_DRILL_DOWN_PATH`) — this package must not
+ * depend on common. The host answers it directly (opens its drill dialog);
+ * nothing is forwarded to the API. On a direct-API transport it fails with a
+ * plain HTTP error.
+ */
+export const VIZ_DRILL_DOWN_PATH = '/__sdk/viz/drill-down';

package/dist/vizContext.d.ts

@@ -97,6 +97,10 @@ export type DataAppVizContextMessage = {
     underlyingData?: {
         enabled?: boolean;
     };
+    /** Absent when the installed host predates drill-down delivery. */
+    drillDown?: {
+        enabled?: boolean;
+    };
 };
 /** Posted by the iframe on mount so the host pushes the current context. */
 export type VizContextRequestMessage = {
@@ -145,6 +149,8 @@ export type VizContext = {
     ready: boolean;
     /** Fetch/export the raw rows behind a clicked data point via the host. */
     underlyingData: VizUnderlyingData;
+    /** Fire a drill-down on a clicked data point; the host opens its drill dialog. */
+    drillDown: VizDrillDown;
 };
 type VizContextValue = {
     fieldMapping: Record<string, string>;
@@ -153,6 +159,7 @@ type VizContextValue = {
     colorPalette: string[];
     pivotDetails: VizContextPivotDetails | null;
     underlyingDataEnabled: boolean;
+    drillDownEnabled: boolean;
 };
 type VizContextState = VizContextValue | null;
 /**
@@ -166,6 +173,22 @@ export declare function toVizContextState(message: DataAppVizContextMessage): Vi
  * standalone `useVizContext` usage). Exported for tests.
  */
 export declare function buildVizUnderlyingData(hostEnabled: boolean, transport: Transport | null): VizUnderlyingData;
+/**
+ * Host-mediated drill-down for a clicked data point. `enabled` is false when
+ * the host predates the capability, the viewer lacks permission, results are
+ * pivoted, or no transport is mounted — render no menu item in that case
+ * (never a disabled one). `open` fires the intent; the HOST shows the drill
+ * dialog, nothing renders in the viz.
+ */
+export type VizDrillDown = {
+    enabled: boolean;
+    open: (opts: {
+        row: VizContextRow;
+        metric: string;
+    }) => Promise<void>;
+};
+/** Builds the `drillDown` surface. Exported for tests. */
+export declare function buildVizDrillDown(hostEnabled: boolean, transport: Transport | null): VizDrillDown;
 declare const NO_PROVIDER: unique symbol;
 /**
  * Owns the single listener + handshake for a data app viz. Mount it in the

package/dist/vizContext.js

@@ -55,6 +55,7 @@ export function toVizContextState(message) {
         pivotDetails: message.pivotDetails ?? null,
         // Strict boolean check — non-boolean payloads read as disabled.
         underlyingDataEnabled: message.underlyingData?.enabled === true,
+        drillDownEnabled: message.drillDown?.enabled === true,
     };
 }
 /**
@@ -89,6 +90,22 @@ export function buildVizUnderlyingData(hostEnabled, transport) {
         },
     };
 }
+/** Builds the `drillDown` surface. Exported for tests. */
+export function buildVizDrillDown(hostEnabled, transport) {
+    const supported = typeof transport?.openVizDrillDown === 'function';
+    return {
+        enabled: hostEnabled && supported,
+        open: async ({ row, metric }) => {
+            if (!hostEnabled) {
+                throw new Error('Drill-down is not enabled for this visualization.');
+            }
+            if (!transport?.openVizDrillDown) {
+                throw new Error('This SDK build predates drill-down. Rebuild the app on the current template.');
+            }
+            return transport.openVizDrillDown({ row, metric });
+        },
+    };
+}
 // Distinguishes "no provider mounted" from "provider present, no context yet".
 const NO_PROVIDER = Symbol('viz-context/no-provider');
 const VizContextContext = createContext(NO_PROVIDER);
@@ -152,6 +169,8 @@ export function useVizContext() {
     const transport = useOptionalTransport();
     const hostEnabled = context?.underlyingDataEnabled === true;
     const underlyingData = useMemo(() => buildVizUnderlyingData(hostEnabled, transport), [hostEnabled, transport]);
+    const drillHostEnabled = context?.drillDownEnabled === true;
+    const drillDown = useMemo(() => buildVizDrillDown(drillHostEnabled, transport), [drillHostEnabled, transport]);
     return {
         fieldMapping: context?.fieldMapping ?? {},
         rows: context?.rows ?? [],
@@ -160,5 +179,6 @@ export function useVizContext() {
         pivotDetails: context?.pivotDetails ?? null,
         ready: context !== null,
         underlyingData,
+        drillDown,
     };
 }

package/package.json

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