@lightdash/query-sdk 1.95.1 → 1.97.0

package/dist/deliveryRender.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Delivery-render flag: the host rides `deliveryRender: true` on its
+ * `lightdash:sdk:ready` message during delivery/preview capture renders
+ * (absent on interactive loads). Apps gate all-tab data mounting on it.
+ */
+export type DeliveryRenderStore = {
+    getValue: () => boolean;
+    setValue: (next: boolean) => void;
+    subscribe: (listener: () => void) => () => void;
+};
+/**
+ * Minimal external store: synchronous reads for useSyncExternalStore.
+ * Exported for tests — app code uses `useDeliveryRender`.
+ */
+export declare function createDeliveryRenderStore(): DeliveryRenderStore;
+/**
+ * Listen for the flag riding on the host's `lightdash:sdk:ready`. Called by
+ * `createPostMessageTransport()`; a no-op outside the browser (SSR/tests that
+ * never create a postMessage transport keep the default `false`). One
+ * listener per bundle — re-mounting replaces the previous listener rather
+ * than stacking.
+ */
+export declare function mountDeliveryRender(targetWindow: Window): () => void;
+/**
+ * True inside delivery/preview capture renders. Gate DATA fetching on this —
+ * mount every tab's/slide's data hooks and show only the active one — never
+ * mount all tabs unconditionally on interactive loads.
+ *
+ *   const deliveryRender = useDeliveryRender();
+ *   return (deliveryRender || activeTab === 'summary') && <SummaryTabData />;
+ */
+export declare function useDeliveryRender(): boolean;
+/**
+ * Non-hook accessor for event handlers and other post-boot code. Do NOT call
+ * at module init: the flag arrives from the host after the iframe loads, so
+ * a read before then always returns false. Components should use the hook,
+ * which re-renders when the flag arrives.
+ */
+export declare function isDeliveryRender(): boolean;
+/**
+ * Test-only seam: drops the listener and the shared store so the next mount
+ * re-reads the default `false`.
+ */
+export declare function resetDeliveryRenderState(): void;

package/dist/deliveryRender.js

@@ -0,0 +1,97 @@
+/**
+ * Delivery-render flag: the host rides `deliveryRender: true` on its
+ * `lightdash:sdk:ready` message during delivery/preview capture renders
+ * (absent on interactive loads). Apps gate all-tab data mounting on it.
+ */
+import { useSyncExternalStore } from 'react';
+const SDK_READY_MESSAGE = 'lightdash:sdk:ready';
+/**
+ * Minimal external store: synchronous reads for useSyncExternalStore.
+ * Exported for tests — app code uses `useDeliveryRender`.
+ */
+export function createDeliveryRenderStore() {
+    let value = false;
+    const listeners = new Set();
+    return {
+        getValue: () => value,
+        setValue: (next) => {
+            if (next === value)
+                return;
+            value = next;
+            listeners.forEach((listener) => listener());
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+// Lazily created so tests (and SSR) never touch window at import time.
+let sharedStore = null;
+function getSharedStore() {
+    if (sharedStore === null) {
+        sharedStore = createDeliveryRenderStore();
+    }
+    return sharedStore;
+}
+let activeCleanup = null;
+/**
+ * Listen for the flag riding on the host's `lightdash:sdk:ready`. Called by
+ * `createPostMessageTransport()`; a no-op outside the browser (SSR/tests that
+ * never create a postMessage transport keep the default `false`). One
+ * listener per bundle — re-mounting replaces the previous listener rather
+ * than stacking.
+ */
+export function mountDeliveryRender(targetWindow) {
+    if (typeof window === 'undefined')
+        return () => { };
+    const store = getSharedStore();
+    const handler = (event) => {
+        if (event.source !== targetWindow)
+            return;
+        const data = event.data;
+        if (data?.type !== SDK_READY_MESSAGE)
+            return;
+        store.setValue(data.deliveryRender === true);
+    };
+    activeCleanup?.();
+    window.addEventListener('message', handler);
+    const cleanup = () => {
+        window.removeEventListener('message', handler);
+        if (activeCleanup === cleanup)
+            activeCleanup = null;
+    };
+    activeCleanup = cleanup;
+    return cleanup;
+}
+/**
+ * True inside delivery/preview capture renders. Gate DATA fetching on this —
+ * mount every tab's/slide's data hooks and show only the active one — never
+ * mount all tabs unconditionally on interactive loads.
+ *
+ *   const deliveryRender = useDeliveryRender();
+ *   return (deliveryRender || activeTab === 'summary') && <SummaryTabData />;
+ */
+export function useDeliveryRender() {
+    const store = getSharedStore();
+    return useSyncExternalStore(store.subscribe, store.getValue, () => false);
+}
+/**
+ * Non-hook accessor for event handlers and other post-boot code. Do NOT call
+ * at module init: the flag arrives from the host after the iframe loads, so
+ * a read before then always returns false. Components should use the hook,
+ * which re-renders when the flag arrives.
+ */
+export function isDeliveryRender() {
+    return getSharedStore().getValue();
+}
+/**
+ * Test-only seam: drops the listener and the shared store so the next mount
+ * re-reads the default `false`.
+ */
+export function resetDeliveryRenderState() {
+    activeCleanup?.();
+    sharedStore = null;
+}

package/dist/features.js

@@ -77,6 +77,12 @@ export const SDK_FEATURES = [
         description: "Match the light or dark mode of the viewer's Lightdash (or embed) instead of a fixed theme, and restyle live when they switch.",
         wiring: 'Keep complete light tokens in :root and dark tokens in .dark, remove any fixed dark class from the app shell, and use useColorScheme() only for colours that cannot be expressed in CSS.',
     },
+    {
+        key: 'delivery-render',
+        label: 'Full data in scheduled deliveries',
+        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.",
+    },
 ];
 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.95.1";
+export declare const SDK_VERSION = "1.97.0";

package/dist/generated/sdkVersion.js

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

package/dist/index.d.ts

@@ -18,5 +18,6 @@ export { VizContextProvider, useVizContext, getFormatted, getRaw, } from './vizC
 export type { VizContext, VizContextCell, VizContextOptionValue, VizContextRow, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
 export { useColorScheme } from './colorScheme';
 export type { HostColorScheme, HostColorSchemeMessage, HostColorSchemeRequestMessage, } from './colorScheme';
+export { isDeliveryRender, useDeliveryRender } from './deliveryRender';
 export { useUrlState } from './urlState';
 export type { SdkUrlStateChangeMessage, UrlStateMap } from './urlState';

package/dist/index.js

@@ -22,5 +22,8 @@ export { exportToSheets } from './exportToSheets';
 export { VizContextProvider, useVizContext, getFormatted, getRaw, } from './vizContext';
 // Host light/dark mode (seeded from the iframe URL, updated by the host)
 export { useColorScheme } from './colorScheme';
+// Delivery/preview capture flag (true when the host is capturing this render
+// for a scheduled delivery or its preview, not an interactive load)
+export { isDeliveryRender, useDeliveryRender } from './deliveryRender';
 // Shareable URL state (seeded from and written back to the host page URL)
 export { useUrlState } from './urlState';

package/dist/postMessageTransport.d.ts

@@ -26,6 +26,10 @@ export type SdkFetchResponse = {
 };
 export type SdkReadyMessage = {
     type: 'lightdash:sdk:ready';
+    /** True when the host is capturing this render for a scheduled delivery
+     *  or its preview. Absent (never `false`) on ordinary interactive loads —
+     *  see `deliveryRender.ts`'s `useDeliveryRender()`. */
+    deliveryRender?: boolean;
 };
 export type SdkScreenshotRequest = {
     type: 'lightdash:sdk:screenshot-request';

package/dist/postMessageTransport.js

@@ -9,6 +9,7 @@
  * mapping) stays in the SDK's apiTransport.
  */
 import { createApiTransport } from './apiTransport';
+import { mountDeliveryRender } from './deliveryRender';
 import { announceSdkManifest } from './manifest';
 const DEFAULT_TIMEOUT_MS = 120000;
 const READY_TIMEOUT_MS = 10000;
@@ -172,6 +173,9 @@ function createPostMessageExternalFetch(config) {
 export function createPostMessageTransport(config) {
     // Report this bundle's SDK capabilities so the host can offer upgrades.
     announceSdkManifest(config.targetWindow);
+    // Listen for the delivery/preview capture flag riding on the same
+    // `lightdash:sdk:ready` handshake — see `useDeliveryRender()`.
+    mountDeliveryRender(config.targetWindow);
     const adapter = createPostMessageFetchAdapter({
         targetWindow: config.targetWindow,
         timeoutMs: config.timeoutMs,

package/package.json

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