@lightdash/query-sdk 1.11.0 → 1.12.0

package/dist/generated/sdkVersion.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.11.0";
+export declare const SDK_VERSION = "1.12.0";

package/dist/generated/sdkVersion.js

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

package/dist/index.d.ts

@@ -13,6 +13,6 @@ export type { InspectAvailableMessage, InspectSelectedMessage, } from './inspect
 export { exportToSheets } from './exportToSheets';
 export type { ExportToSheetsOptions, ExportToSheetsResult, } from './exportToSheets';
 export { VizContextProvider, useVizContext, getFormatted, getRaw, } from './vizContext';
-export type { VizContext, VizContextCell, VizContextRow, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
+export type { VizContext, VizContextCell, VizContextOptionValue, VizContextRow, DataAppVizContextMessage, VizContextRequestMessage, } from './vizContext';
 export { useUrlState } from './urlState';
 export type { SdkUrlStateChangeMessage, UrlStateMap } from './urlState';

package/dist/index.js

@@ -16,7 +16,7 @@ export { createPostMessageTransport } from './postMessageTransport';
 export { SDK_FEATURES, SDK_FEATURE_KEYS, SDK_MANIFEST_MESSAGE_TYPE, } from './features';
 // Google Sheets export (data apps)
 export { exportToSheets } from './exportToSheets';
-// Data app viz render context (host-pushed rows + field mapping)
+// Data app viz render context (host-pushed rows + field mapping + config options)
 export { VizContextProvider, useVizContext, getFormatted, getRaw, } from './vizContext';
 // Shareable URL state (seeded from and written back to the host page URL)
 export { useUrlState } from './urlState';

package/dist/vizContext.d.ts

@@ -23,15 +23,23 @@ export type VizContextCell = {
 };
 /** A result row keyed by query field id. */
 export type VizContextRow = Record<string, VizContextCell | undefined>;
+/**
+ * A config option value. Its shape follows the option's declared type:
+ * `boolean` → boolean, `number` → number, `select`/`text`/`color` → string.
+ */
+export type VizContextOptionValue = boolean | number | 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
- * host-fetched result rows keyed by field id.
+ * host-fetched result rows keyed by field id; `options` holds the current
+ * value of each config option the renderer declared.
  */
 export type DataAppVizContextMessage = {
     type: 'lightdash:sdk:data-app-viz-context';
     fieldMapping: Record<string, string>;
     rows: VizContextRow[];
+    /** Absent when the installed host predates config-option delivery. */
+    options?: Record<string, VizContextOptionValue>;
 };
 /** Posted by the iframe on mount so the host pushes the current context. */
 export type VizContextRequestMessage = {
@@ -46,13 +54,23 @@ export type VizContext = {
     fieldMapping: Record<string, string>;
     /** Host-fetched result rows, keyed by query field id. */
     rows: VizContextRow[];
+    /** Config option name → current value (the user's choice, else the declared default). */
+    options: Record<string, VizContextOptionValue>;
     /** False until the first context arrives — render a placeholder while false. */
     ready: boolean;
 };
-type VizContextState = {
+type VizContextValue = {
     fieldMapping: Record<string, string>;
     rows: VizContextRow[];
-} | null;
+    options: Record<string, VizContextOptionValue>;
+};
+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` is also
+ * absent from hosts predating it, and falls back to `{}`.
+ */
+export declare function toVizContextState(message: DataAppVizContextMessage): VizContextValue;
 declare const NO_PROVIDER: unique symbol;
 /**
  * Owns the single listener + handshake for a data app viz. Mount it in the
@@ -67,7 +85,8 @@ export declare function VizContextProvider({ children }: {
  * one is mounted (the scaffold default); otherwise self-subscribes so the hook
  * still works standalone. Re-renders whenever the host pushes (on load, on
  * mapping change, on query change). Resolve a declared field to its bound cell
- * with `fieldMapping[name]` then `getFormatted`/`getRaw`.
+ * with `fieldMapping[name]` then `getFormatted`/`getRaw`; read a declared
+ * config option with `options[name]`.
  */
 export declare function useVizContext(): VizContext;
 export {};

package/dist/vizContext.js

@@ -28,6 +28,29 @@ export const getRaw = (row, fieldId) => {
         return null;
     return row[fieldId]?.value?.raw ?? null;
 };
+const isVizContextOptionValue = (value) => typeof value === 'string' ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value));
+const normalizeOptions = (options) => {
+    if (typeof options !== 'object' ||
+        options === null ||
+        Array.isArray(options)) {
+        return {};
+    }
+    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` is also
+ * absent from hosts predating it, and falls back to `{}`.
+ */
+export function toVizContextState(message) {
+    return {
+        fieldMapping: message.fieldMapping ?? {},
+        rows: Array.isArray(message.rows) ? message.rows : [],
+        options: normalizeOptions(message.options),
+    };
+}
 // Distinguishes "no provider mounted" from "provider present, no context yet".
 const NO_PROVIDER = Symbol('viz-context/no-provider');
 const VizContextContext = createContext(NO_PROVIDER);
@@ -45,10 +68,7 @@ function useVizContextSubscription(enabled) {
             const data = event.data;
             if (!data || data.type !== DATA_APP_VIZ_CONTEXT_MESSAGE)
                 return;
-            setContext({
-                fieldMapping: data.fieldMapping ?? {},
-                rows: Array.isArray(data.rows) ? data.rows : [],
-            });
+            setContext(toVizContextState(data));
         };
         window.addEventListener('message', handleMessage);
         // Ask the host to push the current context. Sent from a mount effect —
@@ -77,7 +97,8 @@ export function VizContextProvider({ children }) {
  * one is mounted (the scaffold default); otherwise self-subscribes so the hook
  * still works standalone. Re-renders whenever the host pushes (on load, on
  * mapping change, on query change). Resolve a declared field to its bound cell
- * with `fieldMapping[name]` then `getFormatted`/`getRaw`.
+ * with `fieldMapping[name]` then `getFormatted`/`getRaw`; read a declared
+ * config option with `options[name]`.
  */
 export function useVizContext() {
     const fromProvider = useContext(VizContextContext);
@@ -91,6 +112,7 @@ export function useVizContext() {
     return {
         fieldMapping: context?.fieldMapping ?? {},
         rows: context?.rows ?? [],
+        options: context?.options ?? {},
         ready: context !== null,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "private": false,
   "type": "module",
   "description": "SDK for building custom data apps against the Lightdash semantic layer",
@@ -35,7 +35,7 @@
     "typescript": "npm:@typescript/typescript6@6.0.1",
     "typescript-7": "npm:typescript@7.0.1-rc",
     "vitest": "4.1.6",
-    "@lightdash/common": "1.11.0"
+    "@lightdash/common": "1.12.0"
   },
   "scripts": {
     "prebuild": "node ./scripts/generateSdkVersion.mjs",