@lightdash/query-sdk 1.11.0 → 1.13.0

package/dist/features.js

@@ -59,6 +59,12 @@ export const SDK_FEATURES = [
         label: 'Dashboard visualization context',
         description: 'Receive query context when app visualizations are embedded in dashboards.',
     },
+    {
+        key: 'viz-config-options',
+        label: 'Visualization config options',
+        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().',
+    },
 ];
 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.11.0";
+export declare const SDK_VERSION = "1.13.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.13.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,28 @@ 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.
+ * Series colours are not an option — they arrive on `colorPalette`.
+ */
+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; `colorPalette` is the
+ * Lightdash palette resolved for this chart, pushed whether or not the
+ * renderer declared one.
  */
 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>;
+    /** Absent when the installed host predates palette delivery. */
+    colorPalette?: string[];
 };
 /** Posted by the iframe on mount so the host pushes the current context. */
 export type VizContextRequestMessage = {
@@ -46,13 +59,32 @@ 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>;
+    /**
+     * Ordered series colours resolved from the Lightdash palette the viewer
+     * picked. Colour multi-series charts with
+     * `colorPalette[i % colorPalette.length]`. Empty only when the host
+     * resolved no palette; keep a fallback array in your own code for that.
+     */
+    colorPalette: string[];
     /** 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>;
+    colorPalette: string[];
+};
+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
+ * `{}` / `[]`.
+ */
+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 +99,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]`, and colour series from `colorPalette`.
  */
 export declare function useVizContext(): VizContext;
 export {};

package/dist/vizContext.js

@@ -28,6 +28,33 @@ 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` and
+ * `colorPalette` are also absent from hosts predating them, and fall back to
+ * `{}` / `[]`.
+ */
+export function toVizContextState(message) {
+    return {
+        fieldMapping: message.fieldMapping ?? {},
+        rows: Array.isArray(message.rows) ? message.rows : [],
+        options: normalizeOptions(message.options),
+        colorPalette: Array.isArray(message.colorPalette)
+            ? message.colorPalette.filter((color) => typeof color === 'string')
+            : [],
+    };
+}
 // 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 +72,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 +101,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]`, and colour series from `colorPalette`.
  */
 export function useVizContext() {
     const fromProvider = useContext(VizContextContext);
@@ -91,6 +116,8 @@ export function useVizContext() {
     return {
         fieldMapping: context?.fieldMapping ?? {},
         rows: context?.rows ?? [],
+        options: context?.options ?? {},
+        colorPalette: context?.colorPalette ?? [],
         ready: context !== null,
     };
 }

package/package.json

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