@sigmacomputing/plugin 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -9,17 +9,3 @@ request. Read our `CONTRIBUTING.md` guide to get started.
 - `@sigmacomputing/plugin-types` has been merged with `@sigmacomputing/plugin`
   and will no longer received updates in the future. Please use only
   `@sigmacomputing/plugin` going forward.
-
-- All `react` exports (`SigmaClientProvider` and all hooks) have been moved to
-  a separate explicit export. This will allow better bundle splitting by not
-  including `react` specific code for plugins that do not use `react`.
-
-  ```ts
-  // before
-  import { SigmaClientProvider, usePlugin } from '@sigmacomputing/plugin';
-
-  // after
-  import { SigmaClientProvider, usePlugin } from '@sigmacomputing/plugin/react';
-  ```
-
-  All types can be imported from either `@sigmacomputing/plugin` or `@sigmacomputing/plugin/react`

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Sigma Computing
+Copyright (c) 2026 Sigma Computing
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -32,7 +32,6 @@ To test your plugin in Sigma Plugin Dev Playground, you must:
 To test a development version of a registered plugin, you must:
 
 - Have either:
-
   - An Admin account type
   - A custom account type that supports plugin developer feature permissions
 
@@ -106,7 +105,6 @@ and a React Hooks API.
    ```
 
 7. Start developing:
-
    - Get started with Sigma’s Plugin APIs.
    - Test your plugin directly in a Sigma workbook using the Sigma Plugin Dev
      Playground.
@@ -137,7 +135,7 @@ Before you start:
   > following command in your terminal:
   >
   > ```sh
-  > yarn && yarn start
+  > yarn && yarn dev
   > ```
 
 1. Create/open a workbook.
@@ -264,14 +262,14 @@ type CustomPluginConfigOptions =
       label?: string;
     }
   | {
-    type: 'action-effect';
-    name: string;
-    label?: string;
-  }
+      type: 'action-effect';
+      name: string;
+      label?: string;
+    }
   | {
-    type: 'url-parameter';
-    name: string;
-  };
+      type: 'url-parameter';
+      name: string;
+    };
 ```
 
 </details>
@@ -488,9 +486,9 @@ interface PluginInstance<T> {
     registerEffect(configId: string, effect: Function): void;
 
     /**
-     * Overrider function for Config Ready state
+     * Overrider function for Config loading state
      */
-    setLoadingState(ready: boolean): void;
+    setLoadingState(isLoading: boolean): void;
 
     /**
      * Allows users to subscribe to changes in the passed in variable
@@ -655,8 +653,8 @@ Arguments
 
 #### useLoadingState()
 
-Gets the current plugin's loading stat. Returns a value and a setter allowing
-you to update the plugin's loading state
+Gets the current plugin's loading state and a setter. Call the setter with
+`false` when your plugin has finished loading
 
 ```ts
 function useLoadingState(
@@ -666,7 +664,7 @@ function useLoadingState(
 
 Arguments
 
-- `initialState : boolean` - Initial value to set loading state to
+- `initialState : boolean` - Initial loading state (typically `true`; then set to `false` when ready)
 
 #### useElementColumns()
 
@@ -814,9 +812,12 @@ console.log(urlParam?.value);
 client.config.setUrlParameter('myParamId', 'new-value');
 
 // Subscribe to changes
-const unsubscribe = client.config.subscribeToUrlParameter('myParamId', (urlParam) => {
-  console.log('URL parameter updated:', urlParam.value);
-});
+const unsubscribe = client.config.subscribeToUrlParameter(
+  'myParamId',
+  urlParam => {
+    console.log('URL parameter updated:', urlParam.value);
+  },
+);
 ```
 
 #### useInteraction()
@@ -904,33 +905,27 @@ Github.
 ### Available Plugins
 
 - **Recharts Bar Chart** - A basic bar chart built with the Recharts library.
-
   - [Source Code](https://github.com/sigmacomputing/sigma-sample-plugins/tree/main/sample-plugin-bar-chart)
   - Production URL: https://sigma-sample-bar-chart-54049.netlify.app/
 
 - **D3 Candlestick** - A candlestick visualization built with D3.
-
   - [Source Code](https://github.com/sigmacomputing/sigma-sample-plugins/tree/main/sample-plugin-bar-chart)
   - Production URL: https://sigma-sample-candlestick-chart-1664e5.netlify.app/
 
 - **Narrative Science Quill** - Demonstrates secure text entry.
-
   - [Source Code]()
   - Production URL: https://narrativescience-quill-3ee312.netlify.app/
 
 - **D3 Graph** - Demonstrates usage of multiple data sources and in-memory
   joins.
-
   - [Source Code](https://github.com/sigmacomputing/sigma-sample-plugins/tree/main/d3-graph)
   - Production URL: https://d3-graph-3a0d0f.netlify.app/
 
 - **D3 Sunburst** - A sunburst visualization built with D3.
-
   - [Source Code](https://github.com/sigmacomputing/sigma-sample-plugins/tree/main/d3-sunburst)
   - Production URL: https://d3-sunburst-b97c7c.netlify.app/
 
 - **Frappe Heatmap** - A basic Frappe visualization example.
-
   - [Source Code](https://github.com/sigmacomputing/sigma-sample-plugins/tree/main/frappe-heatmap)
   - Production URL: https://frappe-heatmap-9a4163.netlify.app/
 

package/dist/cjs/index.cjs

@@ -0,0 +1,506 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let react = require("react");
+let react$1 = __toESM(react, 1);
+react = __toESM(react);
+//#region src/utils/deepEqual.ts
+function isObject(obj) {
+	if (typeof obj === "object" && obj != null) return true;
+	else return false;
+}
+function deepEqual(obj1, obj2) {
+	if (obj1 === obj2) return true;
+	else if (isObject(obj1) && isObject(obj2)) {
+		if (Object.keys(obj1).length !== Object.keys(obj2).length) return false;
+		for (const prop in obj1) if (!deepEqual(obj1[prop], obj2[prop])) return false;
+		return true;
+	}
+}
+//#endregion
+//#region src/utils/error.ts
+function validateConfigId(configId, expectedConfigType) {
+	if (configId === void 0) console.warn(`Invalid config ${expectedConfigType}: ${configId}`);
+}
+//#endregion
+//#region src/client/initialize.ts
+function initialize() {
+	const pluginConfig = { config: {} };
+	let subscribedInteractions = {};
+	let subscribedWorkbookVars = {};
+	let subscribedUrlParameters = {};
+	const registeredEffects = {};
+	const listeners = {};
+	const location = new URL(document.location.href);
+	for (const [key, value] of location.searchParams.entries()) try {
+		pluginConfig[key] = JSON.parse(value);
+	} catch (_err) {
+		console.error(`Failed to parse URL param ${key} with value ${value} as JSON.`);
+	}
+	const listener = (e) => {
+		emit(e.data.type, e.data.result, e.data.error);
+	};
+	window.addEventListener("message", listener, false);
+	window.addEventListener("click", () => execPromise("wb:plugin:focus"));
+	on("wb:plugin:config:update", (config) => {
+		Object.assign(pluginConfig, config);
+		emit("config", pluginConfig.config ?? {});
+	});
+	execPromise("wb:plugin:init", "1.2.0").then((config) => {
+		Object.assign(pluginConfig, config);
+		emit("init", pluginConfig);
+		emit("config", pluginConfig.config);
+	});
+	on("wb:plugin:variable:update", (updatedVariables) => {
+		subscribedWorkbookVars = {};
+		Object.assign(subscribedWorkbookVars, updatedVariables);
+	});
+	on("wb:plugin:selection:update", (updatedInteractions) => {
+		subscribedInteractions = {};
+		Object.assign(subscribedInteractions, updatedInteractions);
+	});
+	on("wb:plugin:url-parameter:update", (updatedUrlParameters) => {
+		subscribedUrlParameters = {};
+		Object.assign(subscribedUrlParameters, updatedUrlParameters);
+	});
+	on("wb:plugin:action-effect:invoke", (configId) => {
+		const effect = registeredEffects[configId];
+		if (!effect) throw new Error(`Unknown action effect with name: ${configId}`);
+		effect();
+	});
+	function on(event, listener) {
+		listeners[event] = listeners[event] || [];
+		listeners[event].push(listener);
+	}
+	function off(event, listener) {
+		if (listeners[event] == null) return;
+		listeners[event] = listeners[event].filter((a) => a !== listener);
+	}
+	function emit(event, ...args) {
+		Object.values(listeners[event] || []).forEach((fn) => fn(...args));
+	}
+	function execPromise(event, ...args) {
+		return new Promise((resolve, reject) => {
+			const callback = (data, error) => {
+				if (error) reject(error);
+				else resolve(data);
+				off(event, callback);
+			};
+			on(event, callback);
+			window.parent.postMessage({
+				type: event,
+				args,
+				elementId: pluginConfig.id
+			}, pluginConfig?.wbOrigin ?? "*");
+		});
+	}
+	return {
+		get sigmaEnv() {
+			return pluginConfig.sigmaEnv;
+		},
+		get isScreenshot() {
+			return pluginConfig.screenshot;
+		},
+		config: {
+			getKey(key) {
+				return pluginConfig?.config?.[key];
+			},
+			get() {
+				return pluginConfig.config;
+			},
+			set(partialConfig) {
+				execPromise("wb:plugin:config:update", partialConfig);
+			},
+			setKey(key, value) {
+				execPromise("wb:plugin:config:update", { [key]: value });
+			},
+			subscribe(listener) {
+				on("config", listener);
+				return () => off("config", listener);
+			},
+			getVariable(configId) {
+				validateConfigId(configId, "variable");
+				return subscribedWorkbookVars[configId];
+			},
+			setVariable(configId, ...values) {
+				validateConfigId(configId, "variable");
+				execPromise("wb:plugin:variable:set", configId, ...values);
+			},
+			getInteraction(configId) {
+				validateConfigId(configId, "interaction");
+				return subscribedInteractions[configId];
+			},
+			setInteraction(configId, elementId, selection) {
+				validateConfigId(configId, "interaction");
+				execPromise("wb:plugin:selection:set", configId, elementId, selection);
+			},
+			triggerAction(configId) {
+				validateConfigId(configId, "action-trigger");
+				execPromise("wb:plugin:action-trigger:invoke", configId);
+			},
+			registerEffect(configId, effect) {
+				validateConfigId(configId, "action-effect");
+				registeredEffects[configId] = effect;
+				return () => {
+					delete registeredEffects[configId];
+				};
+			},
+			configureEditorPanel(options) {
+				execPromise("wb:plugin:config:inspector", options);
+			},
+			setLoadingState(loadingState) {
+				execPromise("wb:plugin:config:loading-state", loadingState);
+			},
+			subscribeToWorkbookVariable(configId, callback) {
+				validateConfigId(configId, "variable");
+				const setValues = (values) => {
+					callback(values[configId]);
+				};
+				on("wb:plugin:variable:update", setValues);
+				return () => {
+					off("wb:plugin:variable:update", setValues);
+				};
+			},
+			subscribeToWorkbookInteraction(configId, callback) {
+				validateConfigId(configId, "interaction");
+				const setValues = (values) => {
+					callback(values[configId]);
+				};
+				on("wb:plugin:selection:update", setValues);
+				return () => {
+					off("wb:plugin:selection:update", setValues);
+				};
+			},
+			subscribeToUrlParameter(configId, callback) {
+				validateConfigId(configId, "url-parameter");
+				const setValues = (values) => {
+					callback(values[configId]);
+				};
+				setValues(subscribedUrlParameters);
+				on("wb:plugin:url-parameter:update", setValues);
+				return () => {
+					off("wb:plugin:url-parameter:update", setValues);
+				};
+			},
+			getUrlParameter(configId) {
+				validateConfigId(configId, "url-parameter");
+				return subscribedUrlParameters[configId];
+			},
+			setUrlParameter(configId, value) {
+				validateConfigId(configId, "url-parameter");
+				execPromise("wb:plugin:url-parameter:set", configId, value);
+			}
+		},
+		elements: {
+			getElementColumns(configId) {
+				validateConfigId(configId, "element");
+				return execPromise("wb:plugin:element:columns:get", configId);
+			},
+			subscribeToElementColumns(configId, callback) {
+				validateConfigId(configId, "element");
+				const eventName = `wb:plugin:element:${configId}:columns`;
+				on(eventName, callback);
+				execPromise("wb:plugin:element:subscribe:columns", configId);
+				return () => {
+					off(eventName, callback);
+					execPromise("wb:plugin:element:unsubscribe:columns", configId);
+				};
+			},
+			subscribeToElementData(configId, callback) {
+				validateConfigId(configId, "element");
+				const eventName = `wb:plugin:element:${configId}:data`;
+				on(eventName, callback);
+				execPromise("wb:plugin:element:subscribe:data", configId);
+				return () => {
+					off(eventName, callback);
+					execPromise("wb:plugin:element:unsubscribe:data", configId);
+				};
+			},
+			fetchMoreElementData(configId) {
+				validateConfigId(configId, "element");
+				execPromise("wb:plugin:element:fetch-more", configId);
+			}
+		},
+		style: {
+			subscribe(callback) {
+				on("wb:plugin:style:update", callback);
+				return () => off("wb:plugin:style:update", callback);
+			},
+			get() {
+				return execPromise("wb:plugin:style:get");
+			}
+		},
+		destroy() {
+			Object.keys(listeners).forEach((event) => delete listeners[event]);
+			window.removeEventListener("message", listener, false);
+		}
+	};
+}
+//#endregion
+//#region src/client.ts
+const client = initialize();
+//#endregion
+//#region src/react/Context.ts
+const PluginContext = react$1.createContext(client);
+//#endregion
+//#region src/react/hooks.ts
+/**
+* Gets the entire plugin instance
+* @returns {PluginInstance} Context for the current plugin instance
+*/
+function usePlugin() {
+	return react$1.useContext(PluginContext);
+}
+/**
+* Provides a setter for the Plugin's Config Options
+* @param {CustomPluginConfigOptions[]} nextOptions Updated possible Config Options
+*/
+function useEditorPanelConfig(nextOptions) {
+	const client = usePlugin();
+	const optionsRef = react$1.useRef({});
+	react$1.useEffect(() => {
+		if (nextOptions == null) return;
+		if (!deepEqual(nextOptions, optionsRef.current)) {
+			client.config.configureEditorPanel(nextOptions);
+			optionsRef.current = nextOptions;
+		}
+	}, [client, nextOptions]);
+}
+/**
+* React hook for Plugin Config loading state
+* @param {boolean} initialState Initial value to set loading state to
+* @returns {[boolean, Function]} Boolean value corresponding to loading state for plugin config and setter for loading state
+*/
+function useLoadingState(initialState) {
+	const client = usePlugin();
+	const [loading, setLoading] = react$1.useState(() => {
+		client.config.setLoadingState(initialState);
+		return initialState;
+	});
+	return [loading, (nextState) => {
+		if (nextState === loading) return;
+		setLoading(nextState);
+		client.config.setLoadingState(nextState);
+	}];
+}
+/**
+* Provides the latest column values from corresponding config element
+* @param {string} configId ID from the config for fetching element columns, with type: 'element'
+* @returns {WorkbookElementColumns} Values of corresponding columns contained
+* within the config element
+*/
+function useElementColumns(configId) {
+	const client = usePlugin();
+	const [columns, setColumns] = react$1.useState({});
+	react$1.useEffect(() => {
+		if (configId) return client.elements.subscribeToElementColumns(configId, setColumns);
+	}, [client, configId]);
+	return columns;
+}
+/**
+* Provides the latest data values from config element (max 25_000)
+* @param {string} configId ID from the config for fetching element data, with type: 'element'
+* @returns {WorkbookElementData} Element Data for config element, if any
+*/
+function useElementData(configId) {
+	const client = usePlugin();
+	const [data, setData] = react$1.useState({});
+	react$1.useEffect(() => {
+		if (configId) return client.elements.subscribeToElementData(configId, setData);
+	}, [client, configId]);
+	return data;
+}
+/**
+* Provides the latest data values from corresponding config element with a callback to
+* fetch more in chunks of 25_000 data points
+* @param {string} configId ID from the config for fetching paginated
+* element data, with type: 'element'
+* @returns {WorkbookElementData} Element Data for configured config element, if any
+*/
+function usePaginatedElementData(configId) {
+	const client = usePlugin();
+	const [data, setData] = react$1.useState({});
+	const loadMore = react$1.useCallback(() => {
+		if (configId) client.elements.fetchMoreElementData(configId);
+	}, [configId, client.elements]);
+	react$1.useEffect(() => {
+		if (configId) return client.elements.subscribeToElementData(configId, setData);
+	}, [client, configId]);
+	return [data, loadMore];
+}
+/**
+* Provides the latest value for entire config or certain key within the config
+* @param {string} key Key within Plugin Config, optional
+* @returns Entire config if no key passed in or value for key within plugin config
+*/
+function useConfig(key) {
+	const client = usePlugin();
+	const [config, setConfig] = react$1.useState(key != null ? client.config.getKey(key) : client.config.get());
+	react$1.useEffect(() => client.config.subscribe((newConfig) => {
+		if (key != null && newConfig[key] !== config[key]) setConfig(newConfig[key]);
+		else setConfig(newConfig);
+	}), [
+		client,
+		key,
+		config
+	]);
+	return config;
+}
+/**
+* React hook for accessing a workbook control variable
+* @param {string} id ID from the config of type: 'variable'
+* @returns {[(WorkbookVariable | undefined), Function]} Constantly updating
+* value of the control variable and setter for the variable
+*/
+function useVariable(id) {
+	const client = usePlugin();
+	const [workbookVariable, setWorkbookVariable] = react$1.useState();
+	const isFirstRender = react$1.useRef(true);
+	react$1.useEffect(() => {
+		if (isFirstRender.current) {
+			setWorkbookVariable(client.config.getVariable(id));
+			isFirstRender.current = false;
+		}
+		return client.config.subscribeToWorkbookVariable(id, setWorkbookVariable);
+	}, [client, id]);
+	return [workbookVariable, react$1.useCallback((...values) => client.config.setVariable(id, ...values), [id, client.config])];
+}
+/**
+* React hook for accessing a url parameter
+* @param {string} id ID from the config of type: 'url-parameter'
+* @returns {[(UrlParameter | undefined), Function]} Constantly updating value of the url parameter and setter for the url parameter
+*/
+function useUrlParameter(id) {
+	const client = usePlugin();
+	const [urlParameter, setUrlParameter] = react$1.useState();
+	const isFirstRender = react$1.useRef(true);
+	react$1.useEffect(() => {
+		if (isFirstRender.current) {
+			setUrlParameter(client.config.getUrlParameter(id));
+			isFirstRender.current = false;
+		}
+		return client.config.subscribeToUrlParameter(id, setUrlParameter);
+	}, [client, id]);
+	return [urlParameter, react$1.useCallback((value) => client.config.setUrlParameter(id, value), [client, id])];
+}
+/**
+* @deprecated Use Action API instead
+* React hook for accessing a workbook interaction selections state
+* @param {string} id ID from the config of type: 'interaction'
+* @returns {[(WorkbookSelection | undefined), Function]} Constantly updating selection state and setter thereof
+*/
+function useInteraction(id, elementId) {
+	const client = usePlugin();
+	const [workbookInteraction, setWorkbookInteraction] = react$1.useState();
+	react$1.useEffect(() => {
+		return client.config.subscribeToWorkbookInteraction(id, setWorkbookInteraction);
+	}, [client, id]);
+	return [workbookInteraction, react$1.useCallback((value) => {
+		client.config.setInteraction(id, elementId, value);
+	}, [
+		id,
+		elementId,
+		client.config
+	])];
+}
+/**
+* React hook for returning a triggering callback function for the registered
+* action trigger
+* @param {string} configId ID from the config of type: 'action-trigger'
+* @returns {Function} A callback function to trigger the action
+*/
+function useActionTrigger(configId) {
+	const client = usePlugin();
+	return react$1.useCallback(() => {
+		client.config.triggerAction(configId);
+	}, [client, configId]);
+}
+/**
+* React hook for registering and unregistering an action effect
+* @param {string} configId ID from the config of type: 'action-effect'
+* @param {Function} effect The function to be called when the action is triggered
+*/
+function useActionEffect(configId, effect) {
+	const client = usePlugin();
+	const effectRef = react$1.useRef(effect);
+	react$1.useEffect(() => {
+		effectRef.current = effect;
+	});
+	react$1.useEffect(() => {
+		return client.config.registerEffect(configId, effectRef.current);
+	}, [
+		client,
+		configId,
+		effect
+	]);
+}
+/**
+* React hook for accessing plugin style with live updates
+* @returns {PluginStyle | undefined} Style properties from the workbook if available
+*/
+function usePluginStyle() {
+	const client = usePlugin();
+	const [style, setStyle] = react$1.useState();
+	react$1.useEffect(() => {
+		client.style.get().then((response) => setStyle(response));
+		return client.style.subscribe(setStyle);
+	}, [client]);
+	return style;
+}
+//#endregion
+//#region src/react/Provider.tsx
+function SigmaClientProvider(props) {
+	return /* @__PURE__ */ react.createElement(PluginContext.Provider, { value: props.client }, props.children);
+}
+//#endregion
+//#region src/utils/polyfillRequestAnimationFrame.ts
+const FPS = 1e3 / 60;
+/**
+* requestAnimationFrame() calls are paused in most browsers when running in background tabs or hidden <iframe>s in order to improve performance and battery life
+* @see https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
+*/
+function polyfillRequestAnimationFrame(window) {
+	if ("requestAnimationFrame" in window) {
+		window.requestAnimationFrame = (callback) => window.setTimeout(callback, FPS);
+		window.cancelAnimationFrame = (id) => window.clearTimeout(id);
+	}
+}
+//#endregion
+exports.SigmaClientProvider = SigmaClientProvider;
+exports.client = client;
+exports.polyfillRequestAnimationFrame = polyfillRequestAnimationFrame;
+exports.useActionEffect = useActionEffect;
+exports.useActionTrigger = useActionTrigger;
+exports.useConfig = useConfig;
+exports.useEditorPanelConfig = useEditorPanelConfig;
+exports.useElementColumns = useElementColumns;
+exports.useElementData = useElementData;
+exports.useInteraction = useInteraction;
+exports.useLoadingState = useLoadingState;
+exports.usePaginatedElementData = usePaginatedElementData;
+exports.usePlugin = usePlugin;
+exports.usePluginStyle = usePluginStyle;
+exports.useUrlParameter = useUrlParameter;
+exports.useVariable = useVariable;
+
+//# sourceMappingURL=index.cjs.map